@orbit-work/ui 0.1.0

package/src/examples/ResourceManagementExample.tsx

@@ -0,0 +1,119 @@
+import { useState } from "react"
+import {
+  ResourceListView,
+  type ResourceTab,
+  ResourceWorkbenchView,
+  type ShareAccessScope,
+  ShareSettingsDialogView,
+  type ShareSettingsMember,
+} from "../components/domain/desktop"
+
+const initialMembers: ShareSettingsMember[] = [
+  { id: "member-1", name: "林晓", account: "lin.xiao", avatarUrl: "https://i.pravatar.cc/48?img=5" },
+]
+
+export function ResourceManagementExample({
+  initialDetail = false,
+  initialTenant = false,
+  unavailable = false,
+  onBack,
+  initialTab = "shared-sites",
+  scenario: initialScenario = "ready",
+}: {
+  initialDetail?: boolean
+  initialTenant?: boolean
+  unavailable?: boolean
+  onBack?: () => void
+  initialTab?: ResourceTab
+  scenario?: "ready" | "loading" | "empty" | "error"
+}) {
+  const [tab, setTab] = useState<ResourceTab>(initialTab)
+  const [scope, setScope] = useState<ShareAccessScope>(initialTenant ? "all" : "selected")
+  const [members, setMembers] = useState(initialMembers)
+  const [manage, setManage] = useState(initialDetail)
+  const [keyword, setKeyword] = useState("")
+  const [query, setQuery] = useState("")
+  const [status, setStatus] = useState("")
+  const [scenario, setScenario] = useState(initialScenario)
+  const [notice, setNotice] = useState("")
+  const name = tab === "conversations" ? "项目评审记录" : "项目演示"
+  const candidate: ShareSettingsMember = {
+    id: "member-2",
+    name: "陈然",
+    account: "chen.ran",
+    avatarUrl: "https://i.pravatar.cc/48?img=12",
+  }
+  return (
+    <ResourceWorkbenchView
+      tab={tab}
+      filters={{ query, status, onQuery: setQuery, onStatus: setStatus }}
+      onTab={(value) => {
+        if (value === "sites" && onBack) onBack()
+        else setTab(value)
+      }}
+    >
+      <ResourceListView
+        title={tab === "conversations" ? "会话分享" : "站点分享"}
+        rows={
+          scenario !== "ready" ||
+          (query && !name.includes(query)) ||
+          (status && status !== (unavailable ? "disabled" : "active"))
+            ? []
+            : [
+                {
+                  id: "resource-1",
+                  name,
+                  address: "https://sites.example.com/project-demo/",
+                  status: unavailable ? "已停用" : "可访问",
+                  access: scope === "all" ? "全员访问" : `指定 ${members.length} 位成员`,
+                  detail: "更新于 2026/09/07 10:00",
+                  available: !unavailable,
+                  disabled: unavailable,
+                },
+              ]
+        }
+        loading={scenario === "loading"}
+        error={scenario === "error" ? { title: "暂时无法加载分享", message: "请稍后重试。" } : undefined}
+        more={false}
+        query={query}
+        status={status}
+        onClear={() => {
+          setQuery("")
+          setStatus("")
+        }}
+        onBack={() => onBack?.()}
+        onMore={() => {}}
+        onRetry={() => setScenario("ready")}
+        onOpen={() => {}}
+        onDetail={() => setManage(true)}
+        onManage={() => setManage(true)}
+      />
+      {manage && (
+        <ShareSettingsDialogView
+          title="分享设置"
+          subtitle={`设置谁可以访问「${name}」`}
+          scope={scope}
+          members={members}
+          search={{
+            keyword,
+            onKeyword: setKeyword,
+            results: keyword ? [candidate] : [],
+            searching: false,
+          }}
+          notice={notice}
+          onScope={setScope}
+          onAddMember={(member) => {
+            setMembers((current) => (current.some((item) => item.id === member.id) ? current : [...current, member]))
+            setKeyword("")
+          }}
+          onRemoveMember={(id) => setMembers((current) => current.filter((member) => member.id !== id))}
+          onClose={() => setManage(false)}
+          onSave={() => {
+            setNotice("分享设置已保存")
+            setManage(false)
+          }}
+        />
+      )}
+    </ResourceWorkbenchView>
+  )
+}

package/src/examples/SiteWorkbenchExample.tsx

@@ -0,0 +1,96 @@
+import { useState } from "react"
+import { PreviewDialog } from "../components/domain/browser/WebPreviewDialog"
+import { DesktopSiteReleasesView } from "../components/domain/desktop/DesktopSiteReleasesView"
+import { type DesktopSiteItem, DesktopSitesListView } from "../components/domain/desktop/DesktopSitesListView"
+import { ShareSettingsDialogView } from "../components/domain/desktop/ShareSettingsDialogView"
+import { ResourceManagementExample } from "./ResourceManagementExample"
+
+const site: DesktopSiteItem = {
+  id: "demo",
+  name: "产品演示",
+  status: "SITE_STATUS_ACTIVE",
+  baseUrl: "https://demo.example/",
+  version: 2,
+  sessionId: "conversation-1",
+  description: "仅自己",
+  publishedAt: "2026-09-06T08:00:00Z",
+}
+
+/** Interactive mirror of the desktop's card → detail → management flow. */
+export function SiteWorkbenchExample() {
+  const [detail, setDetail] = useState(false)
+  const [manage, setManage] = useState(false)
+  const [preview, setPreview] = useState(false)
+  const [shares, setShares] = useState(false)
+  const [dense, setDense] = useState(false)
+  const [query, setQuery] = useState("")
+  const [tenant, setTenant] = useState(false)
+  const [notice, setNotice] = useState("")
+  const summary = tenant ? "全员访问" : "仅自己"
+  const current = { ...site, description: summary }
+  if (shares) return <ResourceManagementExample onBack={() => setShares(false)} />
+  return (
+    <>
+      {detail ? (
+        <DesktopSiteReleasesView
+          site={current}
+          releases={[
+            {
+              id: "release-2",
+              version: 2,
+              status: "SITE_RELEASE_STATUS_PUBLISHED",
+              fileCount: 12,
+              totalSizeBytes: 1887437,
+              publishedAt: site.publishedAt,
+            },
+          ]}
+          loading={false}
+          onBack={() => setDetail(false)}
+          onEdit={() => setNotice("已打开来源会话")}
+          onManage={() => setManage(true)}
+          onPreviewSite={() => setPreview(true)}
+          onRetry={() => {}}
+        />
+      ) : (
+        <DesktopSitesListView
+          sites={!query || site.name.includes(query) ? [current] : []}
+          loading={false}
+          onCreateSite={() => setNotice("已创建站点任务")}
+          onViewDetails={() => setDetail(true)}
+          onPreviewSite={() => setPreview(true)}
+          onRetry={() => {}}
+          dense={dense}
+          onDenseChange={setDense}
+          query={query}
+          onQueryChange={setQuery}
+          onOpenShares={() => setShares(true)}
+        />
+      )}
+      {manage && (
+        <ShareSettingsDialogView
+          title="分享设置"
+          subtitle="设置谁可以访问「产品演示」"
+          scope={tenant ? "all" : "selected"}
+          members={[]}
+          search={{ keyword: "", onKeyword: () => {}, results: [], searching: false }}
+          notice={notice}
+          onScope={(scope) => setTenant(scope === "all")}
+          onAddMember={() => {}}
+          onRemoveMember={() => {}}
+          onClose={() => setManage(false)}
+          onSave={() => {
+            setNotice("分享设置已保存")
+            setManage(false)
+          }}
+        />
+      )}
+      <PreviewDialog open={preview} title={site.name} onClose={() => setPreview(false)}>
+        <iframe
+          title="产品演示预览"
+          sandbox=""
+          srcDoc="<!doctype html><html lang='zh'><title>产品演示</title><h1>产品演示</h1><p>与团队分享最新的产品进展。</p></html>"
+        />
+      </PreviewDialog>
+    </>
+  )
+}

package/src/hooks/index.ts

@@ -0,0 +1,7 @@
+export * from "./useClickOutside"
+export * from "./useDragReorder"
+export * from "./useImeAwareEnter"
+export * from "./useKeyboard"
+export * from "./usePopover"
+export * from "./useSelectedOptionLocator"
+export * from "./useSidebarResize"

package/src/hooks/useClickOutside.ts

@@ -0,0 +1,20 @@
+"use client"
+
+import { useEffect, useRef } from "react"
+
+export function useClickOutside<T extends HTMLElement>(handler: () => void, active = true) {
+  const ref = useRef<T>(null)
+
+  useEffect(() => {
+    if (!active) return
+    function onPointerDown(e: PointerEvent) {
+      if (ref.current && !ref.current.contains(e.target as Node)) {
+        handler()
+      }
+    }
+    document.addEventListener("pointerdown", onPointerDown)
+    return () => document.removeEventListener("pointerdown", onPointerDown)
+  }, [handler, active])
+
+  return ref
+}

package/src/hooks/useDragReorder.ts

@@ -0,0 +1,29 @@
+"use client"
+
+import { useCallback, useRef, useState } from "react"
+
+export function useDragReorder<T>(items: T[], onReorder: (items: T[]) => void) {
+  const [dragIdx, setDragIdx] = useState<number | null>(null)
+  const overIdx = useRef<number | null>(null)
+
+  const onDragStart = useCallback((idx: number) => {
+    setDragIdx(idx)
+  }, [])
+
+  const onDragOver = useCallback((idx: number) => {
+    overIdx.current = idx
+  }, [])
+
+  const onDragEnd = useCallback(() => {
+    if (dragIdx !== null && overIdx.current !== null && dragIdx !== overIdx.current) {
+      const next = [...items]
+      const [moved] = next.splice(dragIdx, 1)
+      next.splice(overIdx.current, 0, moved!)
+      onReorder(next)
+    }
+    setDragIdx(null)
+    overIdx.current = null
+  }, [dragIdx, items, onReorder])
+
+  return { dragIdx, onDragStart, onDragOver, onDragEnd }
+}

package/src/hooks/useImeAwareEnter.ts

@@ -0,0 +1,59 @@
+"use client"
+
+import { useCallback, useRef } from "react"
+
+export const IME_COMMIT_GUARD_MS = 50
+
+type ImeKeyboardEvent = {
+  key: string
+  keyCode: number
+  timeStamp: number
+  nativeEvent: { isComposing?: boolean }
+}
+
+type ImeCompositionEvent = {
+  timeStamp: number
+}
+
+/**
+ * Returns true when Enter belongs to an active IME composition or is the
+ * commit keydown immediately following compositionend. Callers should skip
+ * their Enter business logic without preventing the browser default.
+ */
+export function isImeCommitEnter(
+  event: ImeKeyboardEvent,
+  composing: boolean,
+  compositionEndedAt: number | null,
+): boolean {
+  if (event.key !== "Enter") return false
+  if (composing || event.nativeEvent.isComposing || event.keyCode === 229) return true
+  if (compositionEndedAt === null) return false
+
+  const elapsed = event.timeStamp - compositionEndedAt
+  return elapsed >= 0 && elapsed <= IME_COMMIT_GUARD_MS
+}
+
+/** Tracks IME composition across React's composition and keyboard events. */
+export function useImeAwareEnter() {
+  const composingRef = useRef(false)
+  const compositionEndedAtRef = useRef<number | null>(null)
+
+  const onCompositionStart = useCallback((_event?: ImeCompositionEvent) => {
+    composingRef.current = true
+    compositionEndedAtRef.current = null
+  }, [])
+
+  const onCompositionEnd = useCallback((event: ImeCompositionEvent) => {
+    composingRef.current = false
+    compositionEndedAtRef.current = event.timeStamp
+  }, [])
+
+  const isImeEnter = useCallback(
+    (event: ImeKeyboardEvent) => isImeCommitEnter(event, composingRef.current, compositionEndedAtRef.current),
+    [],
+  )
+
+  const isComposing = useCallback(() => composingRef.current, [])
+
+  return { isComposing, isImeEnter, onCompositionStart, onCompositionEnd }
+}

package/src/hooks/useImeAwareEnterSource.test.mjs

@@ -0,0 +1,65 @@
+import assert from "node:assert/strict"
+import { readFile } from "node:fs/promises"
+import test from "node:test"
+
+const hookSource = await readFile(new URL("./useImeAwareEnter.ts", import.meta.url), "utf8")
+const composerSource = await readFile(new URL("../components/domain/chat/Composer/index.tsx", import.meta.url), "utf8")
+/* W2 废案删除：DesktopTaskDetailView 的追问 composer 随该件退役（现为 @deprecated 空态薄壳，
+   已无 textarea），本文件原来读它的源码断言 IME Enter 守卫，随宿主一并撤除。 */
+const sidebarSource = await readFile(
+  new URL("../components/domain/desktop/DesktopSidebarView/index.tsx", import.meta.url),
+  "utf8",
+)
+const createProjectSource = await readFile(
+  new URL("../components/composite/CreateProjectDialog/index.tsx", import.meta.url),
+  "utf8",
+)
+const searchSource = await readFile(new URL("../components/composite/SearchInput/index.tsx", import.meta.url), "utf8")
+const browserNavSource = await readFile(
+  new URL("../components/domain/browser/BrowserNavBarView/index.tsx", import.meta.url),
+  "utf8",
+)
+const browserFindSource = await readFile(
+  new URL("../components/domain/browser/BrowserFindBarView/index.tsx", import.meta.url),
+  "utf8",
+)
+/* W5 终扫：`WebPreviewUrl`（WebPreview 旧配方层的裸 <input> 地址栏）已随
+   Navigation / NavigationButton 一并删除，地址栏归口到 `WebPreviewShell` 的 Field 语法，
+   IME Enter 守卫也跟着搬过去——断言改读归口件。 */
+const webPreviewSource = await readFile(
+  new URL("../components/domain/browser/WebPreviewShell/index.tsx", import.meta.url),
+  "utf8",
+)
+
+test("IME-aware Enter hook declares its client component boundary", () => {
+  assert.ok(hookSource.startsWith('"use client"'))
+})
+
+test("IME Enter guard covers active, legacy, and just-ended composition states", () => {
+  assert.ok(hookSource.includes("composing || event.nativeEvent.isComposing || event.keyCode === 229"))
+  assert.ok(hookSource.includes("event.timeStamp - compositionEndedAt"))
+  assert.ok(hookSource.includes("elapsed >= 0 && elapsed <= IME_COMMIT_GUARD_MS"))
+})
+
+test("shared composers connect composition events before handling Enter", () => {
+  assert.match(
+    composerSource,
+    /if\s*\(\s*isImeEnter\s*\(\s*event\s*\)\s*\)\s*return[\s\S]*?if\s*\(\s*event\.key\s*!==\s*["']Enter["']\s*\)\s*return/,
+  )
+  assert.ok(composerSource.includes("onCompositionStart={onCompositionStart}"))
+  assert.ok(composerSource.includes("onCompositionEnd={onCompositionEnd}"))
+})
+
+test("sidebar rename inputs ignore the Enter used to commit IME composition", () => {
+  assert.equal((sidebarSource.match(/onCompositionStart=\{onCompositionStart\}/g) ?? []).length, 2)
+  assert.equal((sidebarSource.match(/onCompositionEnd=\{onCompositionEnd\}/g) ?? []).length, 2)
+  assert.equal((sidebarSource.match(/if\s*\(\s*isImeEnter\s*\(\s*event\s*\)\s*\)\s*return/g) ?? []).length, 2)
+})
+
+test("single-line action inputs ignore the Enter used to commit IME composition", () => {
+  for (const source of [createProjectSource, searchSource, browserNavSource, browserFindSource, webPreviewSource]) {
+    assert.ok(source.includes("onCompositionStart="))
+    assert.ok(source.includes("onCompositionEnd="))
+    assert.ok(/isImeEnter\s*\(\s*(?:event|e)\s*\)/.test(source))
+  }
+})

package/src/hooks/useKeyboard.ts

@@ -0,0 +1,16 @@
+"use client"
+
+import { useEffect } from "react"
+
+type KeyHandler = (e: KeyboardEvent) => void
+
+export function useKeyboard(key: string, handler: KeyHandler, active = true) {
+  useEffect(() => {
+    if (!active) return
+    function onKeyDown(e: KeyboardEvent) {
+      if (e.key === key) handler(e)
+    }
+    document.addEventListener("keydown", onKeyDown)
+    return () => document.removeEventListener("keydown", onKeyDown)
+  }, [key, handler, active])
+}

package/src/hooks/usePopover.ts

@@ -0,0 +1,67 @@
+"use client"
+
+import { useCallback, useEffect, useRef, useState } from "react"
+
+export interface PopoverCoords {
+  left: number
+  right: number
+  top: number
+  bottom: number
+}
+
+/** Shared anchored-popover behavior for menus that may need to flip upward. */
+export function usePopover(menuHeight = 300): {
+  open: boolean
+  up: boolean
+  coords: PopoverCoords | null
+  wrapRef: (node: HTMLDivElement | null) => void
+  btnRef: (node: HTMLButtonElement | null) => void
+  menuRef: (node: HTMLDivElement | null) => void
+  toggle: () => void
+  close: () => void
+} {
+  const [open, setOpen] = useState(false)
+  const [up, setUp] = useState(false)
+  const [coords, setCoords] = useState<PopoverCoords | null>(null)
+  const wrapElementRef = useRef<HTMLDivElement | null>(null) as { current: HTMLDivElement | null }
+  const buttonElementRef = useRef<HTMLButtonElement | null>(null) as { current: HTMLButtonElement | null }
+  const menuElementRef = useRef<HTMLDivElement | null>(null) as { current: HTMLDivElement | null }
+  // Callback refs keep this public hook compatible when consumers resolve a
+  // different React type package version than Orbitwork UI. DOM nodes stay private.
+  const wrapRef = useCallback((node: HTMLDivElement | null) => {
+    wrapElementRef.current = node
+  }, [])
+  const btnRef = useCallback((node: HTMLButtonElement | null) => {
+    buttonElementRef.current = node
+  }, [])
+  const menuRef = useCallback((node: HTMLDivElement | null) => {
+    menuElementRef.current = node
+  }, [])
+
+  useEffect(() => {
+    if (!open) return undefined
+    const onDocumentMouseDown = (event: MouseEvent) => {
+      const target = event.target as Node
+      if (wrapElementRef.current?.contains(target) || menuElementRef.current?.contains(target)) return
+      setOpen(false)
+    }
+    document.addEventListener("mousedown", onDocumentMouseDown, true)
+    return () => document.removeEventListener("mousedown", onDocumentMouseDown, true)
+  }, [open])
+
+  const toggle = () => {
+    if (!open && buttonElementRef.current) {
+      const rect = buttonElementRef.current.getBoundingClientRect()
+      setUp(window.innerHeight - rect.bottom < menuHeight)
+      setCoords({
+        left: rect.left,
+        right: window.innerWidth - rect.right,
+        top: rect.bottom,
+        bottom: window.innerHeight - rect.top,
+      })
+    }
+    setOpen((value) => !value)
+  }
+
+  return { open, up, coords, wrapRef, btnRef, menuRef, toggle, close: () => setOpen(false) }
+}

package/src/hooks/useSelectedOptionLocator.ts

@@ -0,0 +1,33 @@
+"use client"
+
+import { useCallback, useEffect, useRef } from "react"
+
+export type SelectedOptionLocatorOptions = {
+  open: boolean
+  selectedKey: string | null | undefined
+  query: string
+  itemCount: number
+}
+
+/** Keeps the selected option centered when an unfiltered picker opens. */
+export function useSelectedOptionLocator<T extends HTMLElement>({
+  open,
+  selectedKey,
+  query,
+  itemCount,
+}: SelectedOptionLocatorOptions): (node: T | null) => void {
+  const selectedOptionRef = useRef<T | null>(null)
+  const setSelectedOptionRef = useCallback((node: T | null) => {
+    selectedOptionRef.current = node
+  }, [])
+
+  useEffect(() => {
+    if (!open || !selectedKey || query.trim()) return
+    const frame = requestAnimationFrame(() => {
+      selectedOptionRef.current?.scrollIntoView({ block: "center", inline: "nearest" })
+    })
+    return () => cancelAnimationFrame(frame)
+  }, [itemCount, open, query, selectedKey])
+
+  return setSelectedOptionRef
+}

package/src/hooks/useSidebarResize.ts

@@ -0,0 +1,107 @@
+"use client"
+
+import { useCallback, useEffect, useRef, useState } from "react"
+
+export interface UseSidebarResizeOptions {
+  /** 当前宽度 */
+  width: number
+  /** 宽度变化回调 */
+  onWidthChange: (width: number) => void
+  /** 最小宽度（默认 160） */
+  minWidth?: number
+  /** 最大宽度（默认 480） */
+  maxWidth?: number
+  /** 是否启用（默认 true） */
+  enabled?: boolean
+}
+
+export interface UseSidebarResizeReturn {
+  /** 绑定到拖拽手柄元素的 props */
+  handleProps: {
+    onMouseDown: (e: React.MouseEvent) => void
+    onMouseEnter: () => void
+    onMouseLeave: () => void
+  }
+  /** 手柄是否处于激活状态（hover 或拖拽中） */
+  active: boolean
+  /** 是否正在拖拽 */
+  dragging: boolean
+}
+
+/**
+ * useSidebarResize — 为任意 sidebar 容器添加拖拽调整宽度的能力
+ *
+ * 用法:
+ * ```tsx
+ * const { handleProps, active } = useSidebarResize({
+ *   width: sidebarWidth,
+ *   onWidthChange: setSidebarWidth,
+ *   minWidth: 180,
+ *   maxWidth: 400,
+ * })
+ *
+ * return (
+ *   <aside style={{ width: sidebarWidth }}>
+ *     {children}
+ *     <div className="resize-handle" {...handleProps} />
+ *   </aside>
+ * )
+ * ```
+ */
+export function useSidebarResize({
+  width,
+  onWidthChange,
+  minWidth = 160,
+  maxWidth = 480,
+  enabled = true,
+}: UseSidebarResizeOptions): UseSidebarResizeReturn {
+  const [dragging, setDragging] = useState(false)
+  const [hover, setHover] = useState(false)
+  const startX = useRef(0)
+  const startWidth = useRef(width)
+
+  const onMouseDown = useCallback(
+    (e: React.MouseEvent) => {
+      if (!enabled) return
+      e.preventDefault()
+      setDragging(true)
+      startX.current = e.clientX
+      startWidth.current = width
+    },
+    [enabled, width],
+  )
+
+  useEffect(() => {
+    if (!dragging) return
+
+    const handleMouseMove = (e: MouseEvent) => {
+      const delta = e.clientX - startX.current
+      const newWidth = Math.min(maxWidth, Math.max(minWidth, startWidth.current + delta))
+      onWidthChange(newWidth)
+    }
+
+    const handleMouseUp = () => setDragging(false)
+
+    document.addEventListener("mousemove", handleMouseMove)
+    document.addEventListener("mouseup", handleMouseUp)
+    document.body.style.cursor = "col-resize"
+    document.body.style.userSelect = "none"
+
+    return () => {
+      document.removeEventListener("mousemove", handleMouseMove)
+      document.removeEventListener("mouseup", handleMouseUp)
+      document.body.style.cursor = ""
+      document.body.style.userSelect = ""
+    }
+  }, [dragging, maxWidth, minWidth, onWidthChange])
+
+  return {
+    handleProps: {
+      onMouseDown,
+      onMouseEnter: () => setHover(true),
+      onMouseLeave: () => !dragging && setHover(false),
+    },
+    active: hover || dragging,
+    dragging,
+  }
+}

package/src/hooks/useTenantTheme.ts

@@ -0,0 +1,53 @@
+import { useEffect, useState } from "react"
+import type { TenantTheme } from "../theme/core/types"
+import { parseTenantTheme } from "../theme/core/tenantTheme"
+import { applyTenantTheme, removeTenantTheme } from "../theme/utils/themeApplier"
+
+/**
+ * Hook to load and apply tenant theme
+ * Fetches theme from API: GET /api/v1/tenant/theme
+ *
+ * @param apiUrl - Optional API endpoint (defaults to '/api/v1/tenant/theme')
+ */
+export function useTenantTheme(apiUrl = "/api/v1/tenant/theme") {
+  const [theme, setTheme] = useState<TenantTheme | null>(null)
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    const loadTheme = async () => {
+      try {
+        setLoading(true)
+        const response = await fetch(apiUrl)
+
+        if (!response.ok) {
+          throw new Error(`Failed to load theme: ${response.status}`)
+        }
+
+        const data: unknown = await response.json()
+        const result = parseTenantTheme(data)
+        if (!result.ok) throw new Error(`租户主题契约非法：${result.error}`)
+        setTheme(result.theme)
+        applyTenantTheme(result.theme)
+      } catch (err) {
+        setError(err instanceof Error ? err.message : "Failed to load theme")
+        console.warn("[useTenantTheme]", err)
+      } finally {
+        setLoading(false)
+      }
+    }
+
+    void loadTheme()
+
+    return () => {
+      removeTenantTheme()
+    }
+  }, [apiUrl])
+
+  const switchTheme = (newTheme: TenantTheme) => {
+    setTheme(newTheme)
+    applyTenantTheme(newTheme)
+  }
+
+  return { theme, loading, error, switchTheme }
+}