@agentprojectcontext/apx 1.81.0 → 1.89.1

package/src/interfaces/web/src/components/ui.tsx

@@ -2,8 +2,11 @@
 // components in ./ui/* — they keep a small, stable API (variant/tone/size,
 // Dialog open/onClose, Field label/hint) so call sites don't churn, while the
 // actual rendering comes from base-ui (proper focus, portaling, a11y).
-import type { ReactNode, ButtonHTMLAttributes, InputHTMLAttributes, TextareaHTMLAttributes, SelectHTMLAttributes } from "react";
+import type { ReactNode, ButtonHTMLAttributes, InputHTMLAttributes, TextareaHTMLAttributes } from "react";
+import type { LucideIcon } from "lucide-react";
 import { cn } from "../lib/cn";
+import { t } from "../i18n";
+import { Logo } from "./layout/Logo";
 import { Button as SButton } from "./ui/button";
 import { Input as SInput } from "./ui/input";
 import { Textarea as STextarea } from "./ui/textarea";
@@ -59,19 +62,6 @@ export function Textarea(props: TextareaHTMLAttributes<HTMLTextAreaElement>) {
   return <STextarea {...props} />;
 }
 
-// Native select kept for legacy call sites; new code uses UiSelect (base-ui).
-export function Select(props: SelectHTMLAttributes<HTMLSelectElement>) {
-  return (
-    <select
-      {...props}
-      className={cn(
-        "h-8 w-full rounded-lg border border-input bg-transparent px-2.5 text-sm outline-none transition-colors focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50",
-        props.className,
-      )}
-    />
-  );
-}
-
 // ── Field wrapper ───────────────────────────────────────────────────────────
 
 export function Field({
@@ -96,7 +86,7 @@ export function Field({
         )}
       </span>
       {children}
-      {hint && <span className="block text-[11px] text-muted-foreground/70">{hint}</span>}
+      {hint && <span className="block text-[11px] text-muted-foreground">{hint}</span>}
     </div>
   );
 }
@@ -137,12 +127,15 @@ export function Badge({
 }) {
   // muted/danger use built-in variants; the colored tones use outline + color.
   const variant = tone === "danger" ? "destructive" : tone === "muted" ? "secondary" : "outline";
+  // Light ink matches lib/tone's chip scale (800, not 700): these badges land
+  // on muted rows as often as on a card, and 700 only clears 4.5:1 against
+  // white. See lib/tone.ts for the shared pairs.
   const toneClass: Record<Tone, string> = {
     muted: "",
     danger: "",
-    success: "text-emerald-400 border-emerald-500/30",
-    warning: "text-amber-400 border-amber-500/30",
-    info: "text-sky-400 border-sky-500/30",
+    success: "text-emerald-800 dark:text-emerald-400 border-emerald-500/30",
+    warning: "text-amber-800 dark:text-amber-400 border-amber-500/30",
+    info: "text-sky-800 dark:text-sky-400 border-sky-500/30",
   };
   return (
     <SBadge variant={variant} className={cn("rounded-md", toneClass[tone], className)}>
@@ -201,18 +194,64 @@ export function Spinner({ size = 14 }: { size?: number }) {
 
 // ── Empty / Loading helpers ─────────────────────────────────────────────────
 
-export function Empty({ children }: { children: ReactNode }) {
+/**
+ * The house empty state: one centred illustration, the line that says what is
+ * missing, and optionally the button that fixes it. Every empty pane in the
+ * app goes through here, so they all read the same way.
+ *
+ * `icon` is the screen's own lucide glyph; without one the APX mark stands in.
+ * `fill` is for the empty half of a master-detail (or any pane with a height):
+ * it takes the whole pane and centres in it, instead of leaving a short dashed
+ * card pinned to the top edge with dead space under it. Inline (no `fill`) it
+ * is a card sized for the gap where the list would have been.
+ */
+export function Empty({
+  children,
+  icon: Icon,
+  action,
+  fill,
+  className,
+}: {
+  children: ReactNode;
+  icon?: LucideIcon;
+  /** The one button that resolves the state — create the first item, retry. */
+  action?: ReactNode;
+  fill?: boolean;
+  className?: string;
+}) {
   return (
-    <div className="rounded-lg border border-dashed border-border bg-muted/20 px-4 py-6 text-center text-sm text-muted-foreground">
-      {children}
+    <div
+      className={cn(
+        "flex flex-col items-center justify-center gap-4 text-center",
+        fill
+          ? "h-full min-h-[200px] p-8"
+          : "rounded-lg border border-dashed border-border bg-muted/20 px-6 py-8",
+        className
+      )}
+    >
+      <div
+        className={cn(
+          "grid shrink-0 place-items-center rounded-full bg-muted/70 ring-1 ring-border/60",
+          fill ? "size-24" : "size-14"
+        )}
+      >
+        {Icon
+          ? <Icon size={fill ? 42 : 24} strokeWidth={1.5} className="text-muted-fg" />
+          : <Logo size={fill ? 44 : 26} />}
+      </div>
+      <div className="max-w-[46ch] text-balance text-sm leading-relaxed text-muted-foreground">{children}</div>
+      {action}
     </div>
   );
 }
 
-export function Loading({ label = "Cargando…" }: { label?: string }) {
+// The label is i18n by default: most call sites just want "loading", and a
+// hardcoded default here rendered Spanish inside the English UI.
+export function Loading({ label }: { label?: string }) {
+  const text = label ?? t("common.loading");
   return (
     <div className="flex items-center gap-2 text-sm text-muted-foreground">
-      <Spinner /> {label}
+      <Spinner /> {text}
     </div>
   );
 }

package/src/interfaces/web/src/components/voice/VoiceProviderList.tsx

@@ -4,6 +4,7 @@ import { StatusDot } from "../Section";
 import { cn } from "../../lib/cn";
 import { TTS_PROVIDER_META, type TtsEngineInfo } from "../../lib/api/voice";
 import { t } from "../../i18n";
+import { toneOutline } from "../../lib/tone";
 
 // TTS engine list — an ordered fallback chain (router). The arrows reorder the
 // chain, the switch enables/disables an engine, and the first available engine
@@ -120,7 +121,7 @@ export function VoiceProviderList({
                   className={cn(
                     "rounded-md border px-2 py-1 text-xs font-medium transition-colors disabled:opacity-50",
                     e.emotionsOn
-                      ? "border-emerald-500/50 bg-emerald-500/10 text-emerald-300"
+                      ? toneOutline.emerald
                       : "border-border text-muted-fg hover:text-fg",
                   )}
                 >

package/src/interfaces/web/src/components/voice/VoiceProviderModal.tsx

@@ -1,4 +1,5 @@
 import { useEffect, useState } from "react";
+import useSWR from "swr";
 import { Button, Dialog, Field, Input, Switch, Textarea } from "../ui";
 import { UiSelect } from "../UiSelect";
 import { isSecretMarker, secretSuffix } from "../../lib/secrets";
@@ -8,7 +9,10 @@ import {
   GEMINI_TTS_VOICES,
   OPENAI_TTS_MODELS,
   OPENAI_TTS_VOICES,
+  QVOX_LANGUAGES,
   TTS_PROVIDER_META,
+  Voice,
+  voiceLabel,
   type CustomTtsConfig,
   type ElevenLabsConfig,
   type EmotionsConfig,
@@ -72,6 +76,15 @@ function EmotionsField({ on, setOn, tags, setTags }: {
 }
 
 export function VoiceProviderModal({ open, providerId, config, onClose, onSave }: Props) {
+  // The speakers this endpoint actually has. Resolved daemon-side from the
+  // SAVED base_url, so a provider still being created has no list — the field
+  // degrades to free text rather than to a wrong list.
+  const saved = open && providerId?.startsWith("custom:") ? providerId : null;
+  const { data: voiceList } = useSWR(saved ? ["tts-voices", saved] : null, () =>
+    Voice.voices(saved as string)
+  );
+  const serverVoices = voiceList?.voices ?? [];
+
   const [busy, setBusy] = useState(false);
   const [error, setError] = useState<string | null>(null);
 
@@ -100,7 +113,10 @@ export function VoiceProviderModal({ open, providerId, config, onClose, onSave }
         label: str(p.label),
         base_url: str(p.base_url),
         model: str(p.model),
+        language: str(p.language),
         voice: str(p.voice),
+        clone: str(p.clone),
+        ref_text: str(p.ref_text),
         format: str(p.format),
         style: str(p.style),
         temperature: str(p.temperature),
@@ -155,21 +171,29 @@ export function VoiceProviderModal({ open, providerId, config, onClose, onSave }
 
       const set: Record<string, unknown> = {};
       const unset: string[] = [];
-      const opt = (key: string, val: string) => {
-        if (val.trim()) set[`${base}.${key}`] = val.trim();
+      // Tolerates a field this provider's form never rendered: absent and
+      // blank both mean "clear it", never a crash on the way to saving.
+      const opt = (key: string, val: string | undefined) => {
+        if (val?.trim()) set[`${base}.${key}`] = val.trim();
         else unset.push(`${base}.${key}`);
       };
 
       if (isCustom) {
         set[`${base}.label`] = f.label.trim();
         set[`${base}.base_url`] = f.base_url.trim();
+        opt("language", f.language);
+        // The three ways to pick a timbre. They are not additive — the server
+        // reads clone, then voice, then style — so all three are stored and the
+        // form says which one is winning rather than hiding the other two.
+        opt("voice", f.voice);
+        opt("clone", f.clone);
+        opt("ref_text", f.ref_text);
         opt("style", f.style);
         if (f.temperature.trim() && !Number.isNaN(Number(f.temperature)))
           set[`${base}.temperature`] = Number(f.temperature);
         else unset.push(`${base}.temperature`);
-        // Advanced (optional): model/voice for non-QVox OpenAI-compatible servers.
+        // Advanced (optional): the model id, for servers that host several.
         opt("model", f.model);
-        opt("voice", f.voice);
       } else if (providerId === "piper") {
         opt("bin", f.bin);
         opt("model", f.model);
@@ -285,9 +309,46 @@ export function VoiceProviderModal({ open, providerId, config, onClose, onSave }
             <Field label={t("voice_ui.api_key_label")} hint={existingKey ? t("voice_ui.api_key_keep_hint") : t("voice_ui.api_key_optional_hint")}>
               <Input type="password" autoComplete="new-password" value={apiKey} onChange={(e) => setApiKey(e.target.value)} placeholder={keyPlaceholder} />
             </Field>
-            <Field label={t("voice_ui.style_label")} hint={t("voice_ui.openai_style_hint")}>
+            <Field label={t("voice_ui.language_label")} hint={t("voice_ui.language_hint")}>
+              <UiSelect
+                value={f.language || ""}
+                onChange={(v) => up({ language: v })}
+                options={[
+                  { value: "", label: t("voice_ui.language_server_default") },
+                  ...QVOX_LANGUAGES.map((l) => ({ value: l, label: l })),
+                ]}
+              />
+            </Field>
+
+            {/* The timbre. Three mutually exclusive ways to set it, in the
+                order the server resolves them, with the winner named out loud:
+                a preset speaker keeps its own accent, so choosing one is also
+                choosing to ignore the accent described in the style. */}
+            <Field label={t("voice_ui.voice_label")} hint={t("voice_ui.qvox_voice_hint")}>
+              {serverVoices.length > 0 ? (
+                <UiSelect
+                  value={f.voice || ""}
+                  onChange={(v) => up({ voice: v })}
+                  options={[
+                    { value: "", label: t("voice_ui.voice_none") },
+                    ...serverVoices.map((v) => ({ value: v, label: voiceLabel(v, voiceList) })),
+                  ]}
+                />
+              ) : (
+                <Input value={f.voice || ""} onChange={(e) => up({ voice: e.target.value })} placeholder={t("voice_ui.custom_optional_ph")} />
+              )}
+            </Field>
+            <Field label={t("voice_ui.style_label")} hint={(f.voice || "").trim() ? t("voice_ui.style_overridden_hint") : t("voice_ui.qvox_style_hint")}>
               <Textarea rows={2} value={f.style || ""} onChange={(e) => up({ style: e.target.value })} placeholder={t("voice_ui.style_ph")} />
             </Field>
+            <Field label={t("voice_ui.clone_label")} hint={t("voice_ui.clone_hint")}>
+              <Input value={f.clone || ""} onChange={(e) => up({ clone: e.target.value })} placeholder="/Users/me/.qvox/voices/mi-voz.wav" />
+            </Field>
+            {(f.clone || "").trim() && (
+              <Field label={t("voice_ui.ref_text_label")} hint={t("voice_ui.ref_text_hint")}>
+                <Textarea rows={2} value={f.ref_text || ""} onChange={(e) => up({ ref_text: e.target.value })} />
+              </Field>
+            )}
             <Field label={t("voice_ui.temperature_label")} hint={t("voice_ui.temperature_hint")}>
               <Input value={f.temperature} onChange={(e) => up({ temperature: e.target.value })} inputMode="decimal" placeholder="0.7" />
             </Field>
@@ -305,9 +366,6 @@ export function VoiceProviderModal({ open, providerId, config, onClose, onSave }
                   <Field label={t("voice_ui.model_label")} hint={t("voice_ui.custom_model_hint")}>
                     <Input value={f.model} onChange={(e) => up({ model: e.target.value })} placeholder={t("voice_ui.custom_optional_ph")} />
                   </Field>
-                  <Field label={t("voice_ui.voice_label")} hint={t("voice_ui.custom_voice_hint")}>
-                    <Input value={f.voice} onChange={(e) => up({ voice: e.target.value })} placeholder={t("voice_ui.custom_optional_ph")} />
-                  </Field>
                 </div>
               )}
             </div>

package/src/interfaces/web/src/components/voice/VoiceQvoxInstallCard.tsx

@@ -0,0 +1,63 @@
+// The offer to set up a local voice, shown under the provider list because
+// that is where the absence is felt: every other engine there bills per minute
+// and sends the audio off the machine.
+//
+// Only rendered while QVox is missing. Telling a machine that already runs it
+// to go and install it is the one thing this card must not do — the status
+// card next to the tests covers that case instead.
+import { Button } from "../ui";
+import { t } from "../../i18n";
+import { usePersonaName } from "../../hooks/usePersonaName";
+import { QVOX_REPO } from "../../lib/qvox";
+
+// English on purpose, like the Sessions tab's "ask the persona": this is a
+// prompt for the super-agent, not UI copy, and the user appends their own
+// instructions after the colon.
+const ASK_PROMPT =
+  "Install QVox (local Qwen3-TTS on Apple Silicon) and wire it into APX as a voice provider. " +
+  "Steps: check that Node 18+ and `uv` are installed (`brew install uv` if missing — the npm package " +
+  "installs only the Node CLI, and the engine runs through `uv run`, so it will not start without it); " +
+  "`npm install -g qwen3-tts-api`; `qvox setup`, which creates the config and folders and checks the " +
+  "dependencies; `qvox models download` for the first model, a multi-gigabyte download; " +
+  "`qvox serve` and leave it running on 127.0.0.1:5111; " +
+  "then add it in APX as a custom OpenAI-compatible TTS provider with base_url http://127.0.0.1:5111/v1. " +
+  `Repo: ${QVOX_REPO}. ` +
+  "Tell me what you did and what is still missing. With these instructions: ";
+
+export function VoiceQvoxInstallCard() {
+  const persona = usePersonaName();
+
+  // Opens the side sheet with the prompt loaded but UNSENT, so it can be read
+  // and added to first.
+  const ask = () =>
+    window.dispatchEvent(
+      new CustomEvent("apx:roby-prompt", { detail: { prompt: ASK_PROMPT } })
+    );
+
+  return (
+    <div
+      className="rounded-xl border border-dashed border-border p-5"
+      data-testid="qvox-install"
+    >
+      <h3 className="text-sm font-semibold text-foreground">{t("voice_ui.qvox_install_title")}</h3>
+      <p className="mt-1.5 text-sm text-muted-fg">{t("voice_ui.qvox_body")}</p>
+
+      <pre className="mt-3 overflow-x-auto rounded-lg bg-muted/40 p-3 text-[11px] leading-relaxed text-muted-fg">
+        <code>{"brew install uv\nnpm install -g qwen3-tts-api\nqvox setup\nqvox serve"}</code>
+      </pre>
+      <p className="mt-2 text-xs text-muted-fg">{t("voice_ui.qvox_note")}</p>
+
+      <div className="mt-4 flex flex-wrap items-center gap-2">
+        <Button size="sm" onClick={ask}>{t("voice_ui.qvox_ask", { persona })}</Button>
+        <a
+          href={QVOX_REPO}
+          target="_blank"
+          rel="noreferrer"
+          className="text-xs text-muted-fg underline underline-offset-2 hover:text-foreground"
+        >
+          {t("voice_ui.qvox_repo")}
+        </a>
+      </div>
+    </div>
+  );
+}

package/src/interfaces/web/src/components/voice/VoiceQvoxStatusCard.tsx

@@ -0,0 +1,51 @@
+// "Local voice on this Mac" — the standing report on the self-hosted engine.
+//
+// Lives next to the test/STT cards rather than in the provider list because it
+// answers a different question. The list says what is configured; this says
+// whether the thing is actually up.
+//
+// Its badge comes from a live probe, not from the provider list's `available`
+// flag: that flag is a config probe by design (a custom endpoint counts as
+// available for having a base_url), so it reads green with the server stopped.
+// A status card that cannot go red is worse than no status card.
+import useSWR from "swr";
+import { Badge } from "../ui";
+import { t } from "../../i18n";
+import { Voice } from "../../lib/api/voice";
+import { QVOX_REPO } from "../../lib/qvox";
+
+export function VoiceQvoxStatusCard() {
+  // Polled, because the interesting transition (the server dying) produces no
+  // event anywhere. 15s is often enough to notice and rare enough to ignore.
+  const { data } = useSWR("/api/tts/reachable", () => Voice.reachable(), {
+    refreshInterval: 15_000,
+  });
+  const running = !!data?.reachable;
+  // Until the first probe answers, say nothing rather than flash "Stopped" at
+  // a server that is perfectly fine.
+  const known = data !== undefined;
+
+  return (
+    <div className="rounded-xl border border-dashed border-border p-5" data-testid="qvox-status">
+      <div className="flex items-center gap-2">
+        <h3 className="text-sm font-semibold text-foreground">{t("voice_ui.qvox_title")}</h3>
+        {known && (
+          <Badge tone={running ? "success" : "warning"}>
+            {running ? t("voice_ui.qvox_running") : t("voice_ui.qvox_stopped")}
+          </Badge>
+        )}
+      </div>
+      <p className="mt-1.5 text-sm text-muted-fg">
+        {known && !running ? t("voice_ui.qvox_stopped_hint") : t("voice_ui.qvox_body")}
+      </p>
+      <a
+        href={QVOX_REPO}
+        target="_blank"
+        rel="noreferrer"
+        className="mt-3 inline-block text-xs text-muted-fg underline underline-offset-2 hover:text-foreground"
+      >
+        {t("voice_ui.qvox_repo")}
+      </a>
+    </div>
+  );
+}

package/src/interfaces/web/src/components/voice/VoiceSttCard.tsx

@@ -4,14 +4,15 @@ import { UiSelect } from "../UiSelect";
 import { Voice, WHISPER_MODELS, type TranscriptionConfig, type SttHardwareResponse, type SttModelEntry } from "../../lib/api/voice";
 import { isSecretMarker, secretSuffix } from "../../lib/secrets";
 import { t } from "../../i18n";
+import { toneChip } from "../../lib/tone";
 
 // Acceleration badge — each compute backend gets its own colour so the user can
 // tell at a glance what the local engine runs on (Metal on Apple Silicon, CUDA
 // on NVIDIA, Vulkan/ROCm on AMD, plain CPU otherwise).
 const ACCEL: Record<string, { label: string; cls: string }> = {
-  metal: { label: "Metal",         cls: "text-emerald-400 border-emerald-500/40 bg-emerald-500/10" },
-  cuda:  { label: "CUDA",          cls: "text-lime-400 border-lime-500/40 bg-lime-500/10" },
-  rocm:  { label: "Vulkan / ROCm", cls: "text-orange-400 border-orange-500/40 bg-orange-500/10" },
+  metal: { label: "Metal",         cls: toneChip.emerald },
+  cuda:  { label: "CUDA",          cls: toneChip.lime },
+  rocm:  { label: "Vulkan / ROCm", cls: toneChip.orange },
   none:  { label: "CPU",           cls: "text-muted-fg border-border bg-muted" },
 };
 

package/src/interfaces/web/src/components/voice/VoiceTestCard.tsx

@@ -1,16 +1,20 @@
-import { useState } from "react";
+import { useEffect, useState } from "react";
+import useSWR from "swr";
 import { Play, Square, Volume2 } from "lucide-react";
 import { Button, Field, Textarea } from "../ui";
 import { UiSelect } from "../UiSelect";
 import { useToast } from "../Toast";
 import { useTtsPlayer } from "./useTtsPlayer";
-import { Voice, TTS_PROVIDER_META, type TtsEngineInfo, type TtsMode, type TtsSayResult } from "../../lib/api/voice";
+import { Voice, TTS_PROVIDER_META, voiceLabel, type TtsEngineInfo, type TtsMode, type TtsSayResult } from "../../lib/api/voice";
 import { t } from "../../i18n";
 
 // "Say this" tester. Lets you pick which engine to synthesize with (overriding
 // the saved default), then plays the resulting audio in-browser via /tts/say.
-// The base voice / emotions are configured per-engine now, so there's no
-// free-text style field here — pick the engine and hear it.
+//
+// The voice is overridable here too, and only here: picking one in the engine's
+// settings saves it for every channel, which is the wrong move while you are
+// still deciding which voice you want. This one rides along with the single
+// request and changes nothing.
 
 interface Props {
   engines: TtsEngineInfo[];
@@ -25,9 +29,25 @@ export function VoiceTestCard({ engines, defaultProvider, mode }: Props) {
   const [text, setText] = useState(t("voice_ui.test_default_text"));
   // "" = use the saved default; otherwise force a specific engine.
   const [engine, setEngine] = useState("");
+  // "" = whatever the engine has saved. Anything else overrides for this request.
+  const [voice, setVoice] = useState("");
   const [busy, setBusy] = useState(false);
   const [last, setLast] = useState<TtsSayResult | null>(null);
 
+  // Which engine will actually speak, so the voice list belongs to it. In chain
+  // mode with no override there is no answer — the router decides at send time —
+  // and an empty id means no list rather than a list from the wrong engine.
+  const speaking =
+    engine || (mode === "single" && defaultProvider && defaultProvider !== "auto" ? defaultProvider : "");
+  const { data: voiceList } = useSWR(
+    speaking ? ["tts-voices", speaking] : null,
+    () => Voice.voices(speaking)
+  );
+  const serverVoices = voiceList?.voices ?? [];
+
+  // A voice from the previous engine would be meaningless to the next one.
+  useEffect(() => setVoice(""), [speaking]);
+
   const defaultLabel =
     mode === "single" && defaultProvider && defaultProvider !== "auto"
       ? t("voice_ui.test_default_engine", { name: TTS_PROVIDER_META[defaultProvider]?.name || defaultProvider })
@@ -57,6 +77,7 @@ export function VoiceTestCard({ engines, defaultProvider, mode }: Props) {
       const res = await Voice.say({
         text: txt,
         provider: engine || undefined,
+        voice: voice || undefined,
       });
       setLast(res);
       await play(res.audio_path);
@@ -72,6 +93,18 @@ export function VoiceTestCard({ engines, defaultProvider, mode }: Props) {
       <Field label={t("voice_ui.test_engine_label")} hint={t("voice_ui.test_engine_hint")}>
         <UiSelect value={engine} onChange={setEngine} options={options} />
       </Field>
+      {serverVoices.length > 0 && (
+        <Field label={t("voice_ui.test_voice_label")} hint={t("voice_ui.test_voice_hint")}>
+          <UiSelect
+            value={voice}
+            onChange={setVoice}
+            options={[
+              { value: "", label: t("voice_ui.test_voice_default") },
+              ...serverVoices.map((v) => ({ value: v, label: voiceLabel(v, voiceList) })),
+            ]}
+          />
+        </Field>
+      )}
       <Field label={t("voice_ui.test_text_label")}>
         <Textarea
           rows={2}
@@ -97,6 +130,7 @@ export function VoiceTestCard({ engines, defaultProvider, mode }: Props) {
         {last && (
           <span className="text-xs text-muted-fg">
             {t("voice_ui.engine_result")}: <strong>{last.provider}</strong>
+            {voice ? ` · ${voice}` : ""}
             {last.duration_s ? ` · ${last.duration_s.toFixed(1)}s` : ""}
           </span>
         )}

package/src/interfaces/web/src/constants/index.ts

@@ -21,6 +21,7 @@ export const STORAGE = {
   theme: "apx.theme",
   token: "apx.token",
   sidebarCollapsed: "apx.sidebar.collapsed",
+  railOrder: "apx.rail.order",
   language: "apx.lang",
   robyChat: "apx.roby.chat",
 } as const;

package/src/interfaces/web/src/hooks/useChannelPrefs.ts

@@ -0,0 +1,39 @@
+import { useEffect, useState } from "react";
+import {
+  channelEnabledIn,
+  channelPrefs,
+  setChannelEnabled,
+  setChannelsEnabled,
+  onChannelPrefsChange,
+  type ChannelAxis,
+} from "../lib/channels";
+
+/**
+ * React binding for this device's per-channel choices (lib/channels.ts).
+ *
+ * The stored map holds only EXPLICIT choices, so `enabled()` falls through to
+ * the surface default for anything untouched — which is what lets the phone
+ * start with Telegram off without writing that opinion into storage as if the
+ * owner had chosen it.
+ *
+ * Kept in state rather than read from localStorage per render so a change in
+ * this tab (the chips) and one in another tab (the settings dialog) both
+ * repaint, and so React has something to re-render on.
+ */
+export function useChannelPrefs(axis: ChannelAxis) {
+  const [prefs, setPrefs] = useState<Record<string, boolean>>(() => channelPrefs(axis));
+
+  useEffect(() => onChannelPrefsChange(() => setPrefs(channelPrefs(axis))), [axis]);
+
+  const enabled = (channel: string | null | undefined): boolean =>
+    channelEnabledIn(prefs, axis, channel);
+
+  return {
+    /** The stored map itself, so a caller can memoise against it. */
+    prefs,
+    enabled,
+    set: (channel: string, on: boolean) => setChannelEnabled(axis, channel, on),
+    toggle: (channel: string) => setChannelEnabled(axis, channel, !enabled(channel)),
+    setAll: (channels: string[], on: boolean) => setChannelsEnabled(axis, channels, on),
+  };
+}