deploy: build Hugging Face Space from source

.dockerignore

@@ -0,0 +1,11 @@
+node_modules
+dist
+docs
+.git
+.cursor
+.agent
+.shared
+.env
+screenshots
+packages/server/data
+*.md

.env.example

@@ -0,0 +1,44 @@
+# =============================================================================
+# Music Together 服务端配置
+# 复制此文件为 .env 并填写需要的值
+# =============================================================================
+#
+# 所有变量都有合理默认值。
+# Docker 同域部署时无需配置任何环境变量（前端由 Express 托管，自动同源）。
+# 本地开发时也无需配置（CORS 自动放行所有来源）。
+#
+
+# 服务端端口（默认 3001）
+# PORT=3001
+
+# 客户端 URL（可选，用于 CORS 严格白名单模式）
+# - 不设置：自动模式，允许所有来源访问（适用于单镜像部署、局域网、公网反代）
+# - 设置为具体域名：严格白名单模式（适用于前后端分离跨域部署）
+# CLIENT_URL=https://music.example.com
+
+# 额外的 CORS origins（逗号分隔，可选）
+# CORS_ORIGINS=https://other-domain.com,https://another.com
+
+# Identity cookie policy. Defaults are suitable for normal same-origin deployments.
+# For embedded Hugging Face Spaces, use the following values:
+# IDENTITY_COOKIE_SAME_SITE=none
+# IDENTITY_COOKIE_PARTITIONED=true
+
+# Log level: debug | info | warn | error (default: info)
+# LOG_LEVEL=info
+
+# Log output: pretty (default, readable single-line output) | json
+# Use json only when logs are collected by a structured logging platform.
+# LOG_FORMAT=pretty
+
+# QQ 音乐单曲搜索 API（仅用于 QQ 音乐的歌曲搜索；未配置时回退到 QQ 原生搜索）
+# URL 可填写 Master 根地址或完整的 /api 地址
+# QQ_MUSIC_API_URL=http://localhost:9000
+# QQ_MUSIC_API_KEY=ag_xxxxxxxxxxxxxxxxxxxxxxxx
+
+# SQLite database path. Keep this under /app/data in Docker and mount that directory.
+# DATABASE_URL=file:./data/music-together.db
+
+# 服务器管理员账号 ID，多个 ID 使用英文逗号分隔。
+# 先在网页中为账号设置密码，再复制账号 ID 填到这里并重启服务器。
+# SERVER_ADMIN_IDS=account-id-1,account-id-2

.gitattributes

@@ -0,0 +1,13 @@
+# Auto detect text files and perform LF normalization
+* text=auto
+
+# 源码文件强制使用 LF
+*.ts text eol=lf
+*.tsx text eol=lf
+*.js text eol=lf
+*.json text eol=lf
+*.md text eol=lf
+*.css text eol=lf
+*.html text eol=lf
+*.yaml text eol=lf
+*.yml text eol=lf

.github/workflows/build.yml

@@ -0,0 +1,34 @@
+name: Build & Push
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set image name to lowercase
+        run: echo "IMAGE=ghcr.io/${GITHUB_REPOSITORY,,}" >> $GITHUB_ENV
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: docker/setup-buildx-action@v3
+
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ env.IMAGE }}:latest,${{ env.IMAGE }}:${{ github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.gitignore

@@ -0,0 +1,15 @@
+node_modules
+dist
+*.tsbuildinfo
+.env
+.env.local
+*.log
+.DS_Store
+Thumbs.db
+.claude
+.spec-workflow
+.pnpm-store/
+.omc
+.trae
+/.sanshu-memory
+/packages/server/data/

.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 120,
+  "tabWidth": 2
+}

Dockerfile

@@ -1 +1,41 @@
-FROM ghcr.io/liuyunlingnai/music-together:latest
+# Install workspace dependencies.
+FROM node:22-alpine AS deps
+RUN corepack enable
+RUN apk add --no-cache python3 make g++
+WORKDIR /app
+COPY pnpm-lock.yaml pnpm-workspace.yaml package.json ./
+COPY packages/shared/package.json packages/shared/
+COPY packages/server/package.json packages/server/
+COPY packages/client/package.json packages/client/
+RUN pnpm install --frozen-lockfile
+
+# Build all workspace packages.
+FROM deps AS build
+COPY packages/shared/ packages/shared/
+COPY packages/server/ packages/server/
+COPY packages/client/ packages/client/
+RUN pnpm --filter @music-together/shared run build
+RUN pnpm --filter @music-together/server run build
+RUN pnpm --filter @music-together/client run build
+
+# Run the production server, which also serves the client bundle.
+FROM node:22-alpine AS production
+RUN corepack enable
+RUN apk add --no-cache python3 make g++ vips
+WORKDIR /app
+COPY pnpm-lock.yaml pnpm-workspace.yaml package.json ./
+COPY packages/shared/package.json packages/shared/
+COPY packages/server/package.json packages/server/
+COPY packages/client/package.json packages/client/
+RUN pnpm install --frozen-lockfile --prod --filter @music-together/server...
+COPY --from=build /app/packages/server/dist packages/server/dist
+COPY --from=build /app/packages/client/dist packages/client/dist
+COPY --from=build /app/packages/shared/dist packages/shared/dist
+RUN sed -i 's|./src/index.ts|./dist/index.js|g' packages/shared/package.json
+RUN mkdir -p /data
+
+EXPOSE 3001
+ENV NODE_ENV=production
+ENV DATABASE_URL=file:/data/music-together.db
+VOLUME ["/data"]
+CMD ["node", "packages/server/dist/index.js"]

LICENSE

@@ -0,0 +1,661 @@
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU Affero General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.

README.en.md

@@ -0,0 +1,188 @@
+<p align="center">
+  <img alt="Music Together" src="public/logo.svg" width="80">
+</p>
+
+<h1 align="center">Music Together</h1>
+
+<p align="center">
+  A real-time collaborative listening platform. Run one server, then join the same rooms, queue, and synchronized playback from the web, Android, or Windows desktop client.
+</p>
+
+<p align="center">
+  <a href="README.md">Simplified Chinese</a>
+</p>
+
+## Overview
+
+Music Together consists of a Node.js server and several clients. The server coordinates rooms, identities, queues, voting, chat, and playback timing. Clients render the experience, play audio, and integrate with their host platform. All clients use the same HTTP and WebSocket protocol, so they can join the same room across devices.
+
+| Platform | Implementation | Current location | Best for |
+| --- | --- | --- | --- |
+| Web | React + Vite | `main` branch | Browsers, mobile browsers, and quick deployment |
+| Android | Kotlin + Jetpack Compose + Media3 | `codex/android-native-client`, v2.2.5 | Native background playback, system media controls, and multi-server lobby |
+| Windows desktop | Electron + React + TypeScript | `codex/windows-native-client` | Installed desktop experience and standalone windows |
+
+> The Android and desktop clients are currently maintained in their own branches and do not include the server. Deploy or run the `main` branch server first, then configure its address in the client.
+
+## Screenshots
+
+### Web Desktop
+
+| 1 | 2 | 3 | 4 | 5 |
+| --- | --- | --- | --- | --- |
+| ![Web desktop screenshot 1](screenshots/1.png) | ![Web desktop screenshot 2](screenshots/2.png) | ![Web desktop screenshot 3](screenshots/3.png) | ![Web desktop screenshot 4](screenshots/4.png) | ![Web desktop screenshot 5](screenshots/5.png) |
+
+### Web Mobile
+
+| 1 | 2 | 3 | 4 | 5 |
+| --- | --- | --- | --- | --- |
+| ![Web mobile screenshot 1](screenshots/1_m.png) | ![Web mobile screenshot 2](screenshots/2_m.png) | ![Web mobile screenshot 3](screenshots/3_m.png) | ![Web mobile screenshot 4](screenshots/4_m.png) | ![Web mobile screenshot 5](screenshots/5_m.png) |
+
+### Native Android Client
+
+| Launch | 1 | 2 | 3 | 4 |
+| --- | --- | --- | --- | --- |
+| ![Android launch screen](screenshots/0_a.jpg) | ![Android screenshot 1](screenshots/1_a.jpg) | ![Android screenshot 2](screenshots/2_a.jpg) | ![Android screenshot 3](screenshots/3_a.jpg) | ![Android screenshot 4](screenshots/4_a.jpg) |
+
+### Windows Desktop Client
+
+| 1 | 2 | 3 | 4 | 5 |
+| --- | --- | --- | --- | --- |
+| ![Windows desktop screenshot 1](screenshots/1_w.png) | ![Windows desktop screenshot 2](screenshots/2_w.png) | ![Windows desktop screenshot 3](screenshots/3_w.png) | ![Windows desktop screenshot 4](screenshots/4_w.png) | ![Windows desktop screenshot 5](screenshots/5_w.png) |
+
+## Capabilities
+
+- Real-time room synchronization with clock correction, scheduled actions, progress reporting, and drift correction
+- NetEase Cloud Music, QQ Music, Kugou, Kugou Concept, and Bilibili sources
+- Platform sign-in and playlists through QR/Cookie login, with quality selection based on account capability
+- Rooms, password rooms, invite links, queue management, chat, roles, votes, and hidden rooms
+- Sequential, single-loop, list-loop, and shuffle playback with word-by-word, translated, romanized, and Ruby lyrics
+- One shared room protocol across the web, Android native player, and Windows desktop client
+
+## Architecture
+
+```text
+Web client / Android client / Windows desktop client
+                    │ HTTP + WebSocket
+                    ▼
+          Music Together Node.js server
+                    │
+     Rooms, clock sync, authentication, music and lyric proxy
+```
+
+The server persists room data and server-side account configuration. Music-platform cookies are sent only to the connected Music Together server. Bilibili and proxy-required audio are routed through the server so platform credentials are not exposed to other room members.
+
+## Web and Server Development
+
+### Prerequisites
+
+- Node.js 22+
+- pnpm 10+
+
+### Start locally
+
+```powershell
+git clone https://github.com/LiuYunLingNai/music-together.git
+cd music-together
+pnpm install --frozen-lockfile
+pnpm dev
+```
+
+- Web client: `http://localhost:5173`
+- Server: `http://localhost:3001`
+
+In default auto mode, the web client connects to the server at its current origin. Set `CLIENT_URL` when deploying frontend and backend separately or when an explicit origin allowlist is required.
+
+## Android Client
+
+The Android app is native, not a WebView wrapper. It uses Kotlin, Jetpack Compose, OkHttp WebSocket, and Media3 ExoPlayer. It supports a multi-server lobby, background playback, system media controls, chat, queue management, search, platform accounts/playlists, votes, and word-by-word lyrics.
+
+### Build a debug APK
+
+Requires JDK 17-21 (the Android Studio bundled JBR is recommended) and Android SDK 36:
+
+```powershell
+git clone --branch codex/android-native-client --single-branch https://github.com/LiuYunLingNai/music-together.git
+cd music-together/packages/android-client
+.\gradlew.bat testStandardDebugUnitTest assembleStandardDebug
+```
+
+The APK is written to `app/build/outputs/apk/standard/debug/app-standard-debug.apk`.
+
+- Android emulator to a server on the development machine: `http://10.0.2.2:3001`
+- Physical device on a LAN: use the computer's LAN address, for example `http://192.168.1.8:3001`
+- Use HTTPS for public servers. The app can store multiple server addresses and aggregate their rooms in one lobby.
+
+The Android branch ships `standard` and `vivo` variants. Its GitHub Actions workflow builds Debug/Release APKs and a standard AAB.
+
+## Windows Desktop Client
+
+The desktop client is an Electron, React, and TypeScript application with its own interface rather than loading the web app URL. The current branch builds Windows installers and portable executables, while retaining AppImage and deb Linux targets.
+
+It includes server connection settings, room discovery and reconnecting, NTP clock sync, rooms/password rooms, search, queue, chat, transport controls, and Apple Music-style lyrics.
+
+### Develop and package
+
+Requires Node.js 22+:
+
+```powershell
+git clone --branch codex/windows-native-client --single-branch https://github.com/LiuYunLingNai/music-together.git
+cd music-together
+npm ci
+npm run dev
+```
+
+Useful verification and packaging commands:
+
+```powershell
+npm run typecheck
+npm test
+npm run build
+npm run dist:win
+```
+
+Artifacts are written to `release/`. Windows targets are NSIS and Portable. Run `npm run dist:linux` for AppImage and deb packages.
+
+## Deploy the Server with Docker
+
+```bash
+docker run -d --name music-together --restart unless-stopped \
+  -p 3001:3001 \
+  -v /path/to/music-together-data:/app/data \
+  ghcr.io/LiuYunLingNai/music-together:latest
+```
+
+Replace `/path/to/music-together-data` with a persistent host directory. It holds the server database and account-related data; recreating a container without the mount loses that data.
+
+When serving HTTPS through Nginx, Caddy, 1Panel, or another reverse proxy, forward `X-Forwarded-Proto` so the server can set secure cookies correctly. Configure public clients with the proxied HTTPS address.
+
+## Repository Layout
+
+The `main` branch:
+
+```text
+packages/
+  client/   Web React app
+  server/   Node.js server
+  shared/   Shared types, constants, and permissions
+```
+
+Native-client branches:
+
+```text
+codex/android-native-client
+  packages/android-client/   Kotlin/Compose Android app
+
+codex/windows-native-client
+  electron/ + src/           Electron desktop app
+```
+
+## Documentation
+
+- [Web and server architecture](docs/PROJECT_ARCHITECTURE.md)
+- [Android client README](https://github.com/LiuYunLingNai/music-together/tree/codex/android-native-client/packages/android-client)
+- [Windows desktop client README](https://github.com/LiuYunLingNai/music-together/tree/codex/windows-native-client)
+
+## License
+
+[AGPL-3.0](LICENSE)

docs/PROJECT_ARCHITECTURE.md

@@ -0,0 +1,44 @@
+# Music Together — 项目速查手册
+
+> 供 AI 助手快速理解项目全貌的参考文档。
+
+## 1. 项目概览
+
+**Music Together** 是一个在线同步听歌平台，允许多人在同一房间内实时同步播放音乐、聊天互动。
+
+### 核心功能
+
+| 功能       | 说明                                                                                                                                 |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| 房间系统   | 创建/加入房间，房间号邀请，可选密码保护；永久房间在用户加入时按 30 分钟间隔按需刷新当前播放链接                                      |
+| 多音源搜索 | 网易云、QQ音乐、酷狗                                                                                                                 |
+| 同步播放   | 房间内播放进度实时同步                                                                                                               |
+| 实时聊天   | 房间内文字聊天                                                                                                                       |
+| 权限控制   | RBAC 三级权限（owner > admin > member）基于 @casl/ability，hostId 为自动选举的播放主持（conductor）                                  |
+| 播放模式   | 顺序播放、列表循环、单曲循环、随机播放（Owner/Admin 直接切换，Member 投票切换）                                                      |
+| 投票系统   | 普通成员通过投票控制播放（暂停/恢复/切歌/切换播放模式/指定播放/移除歌曲）                                                            |
+| VIP 认证   | 平台账号登录（网易云/QQ/酷狗），房间级 Cookie 池（VIP 播放共享）+ 用户级歌单（私有）                                                 |
+| 歌词展示   | Apple Music 风格歌词动画 (AMLL)，四级优先级：TTML 在线逐词（网易云/QQ，可配置）> 平台原生逐词（网易云 YRC / 酷狗 KRC）> LRC 行级歌词 |
+
+### 技术栈
+
+- **前端**: React 19 + Vite 7 + TypeScript 5.9 + Tailwind CSS v4 + shadcn/ui + Zustand
+- **后端**: Node.js + Express 4 + Socket.IO 4 + @meting/core
+- **Monorepo**: pnpm workspaces（3 个包：`client`、`server`、`shared`）
+
+---
+
+## 子文档索引
+
+本文档已拆分为多个子文件，位于 `docs/architecture/` 目录：
+
+| 章节            | 文件                                                          | 内容                                                                              |
+| --------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| 2. 目录结构     | [directory-structure.md](architecture/directory-structure.md) | client / server / shared 三包目录树                                               |
+| 3. 架构与数据流 | [data-flow.md](architecture/data-flow.md)                     | 分层架构、Socket 事件清单、核心类型定义、NTP 同步、播放同步、播放模式、音频质量等 |
+| 4. 第三方库依赖 | [dependencies.md](architecture/dependencies.md)               | 前端/后端/共享/开发依赖清单                                                       |
+| 5. 设计模式     | [design-patterns.md](architecture/design-patterns.md)         | Zustand Store、Hook 组合、Dialog、Provider、分层架构、Repository 等               |
+| 6. 代码规范     | [coding-standards.md](architecture/coding-standards.md)       | 语言模块、路径别名、状态更新、错误处理                                            |
+| 7. UI 设计规范  | [ui-design.md](architecture/ui-design.md)                     | 组件库、颜色系统、动画、歌词、响应式                                              |
+| 8. 开发指南     | [dev-guide.md](architecture/dev-guide.md)                     | 快速启动、构建、添加组件、注意事项                                                |
+| 9. 部署方案     | [deployment.md](architecture/deployment.md)                   | Docker、CORS、Watchtower、1Panel                                                  |

docs/UPDATE_NOTES.md

@@ -0,0 +1,137 @@
+# 本轮功能更新说明
+
+本文记录从 `Music-Together-Pro-UNM-Support` 分支移植并在当前项目中完成适配的功能，涵盖用户数据持久化、多音源、账号系统、服务器管理员、权限安全和审计日志。
+
+## 1. 用户数据持久化
+
+- 新增 SQLite 数据库，默认地址为 `file:./data/music-together.db`，可通过 `DATABASE_URL` 修改。
+- 用户账号资料、密码 Hash、角色和平台登录 Cookie 均可在服务器重启后恢复。
+- 用户再次访问时可通过身份 Cookie 恢复账号及对应的房间身份。
+- 平台 Cookie 加密后再持久化，避免以明文形式保存第三方平台凭据。
+- 用户 ID 使用不区分大小写的唯一性约束，不能注册或修改为已存在的 ID。
+
+> 当前房间和播放状态仍保存在内存中。服务器重启后，账号数据会保留，但正在运行的房间会消失。
+
+## 2. 更广的音源与音质支持
+
+- 扩展网易云音乐相关能力，并接入 QQ 音乐、酷狗音乐等音源。
+- 增加多平台搜索、歌曲信息解析、播放地址获取和歌单解析能力。
+- 支持按平台选择更多音质，包括标准、高品质、无损及平台提供的更高规格音质。
+- 客户端会根据音源展示可用音质，服务端负责对应音源和音质的解析与回退。
+
+第三方平台接口和高音质播放能力仍受账号权限、Cookie 有效期、地区限制及平台接口可用性影响。
+
+## 3. 账号功能
+
+- 账号现在包含：账号 ID、昵称、密码、头像和角色。
+- 用户可修改自己的昵称、头像、密码和账号 ID。
+- 修改密码时需要验证当前密码，验证失败返回 `401`。
+- 修改账号 ID 时会检查格式、重复 ID、系统保留 ID和管理员配置 ID；冲突返回 `409`，非法或不可占用的 ID 返回 `400`。
+- 普通用户只能修改自己的账号资料，不能指定其他用户作为修改目标，也不能自行提升为服务器管理员。
+- 未登录或身份失效时，会按接口要求返回 `401`、`403` 或 `409`，不会绕过账号归属检查。
+
+## 4. 延迟创建正式账号
+
+账号生成逻辑已调整为“设置昵称后才创建正式账号”：
+
+1. 用户首次访问时只签发临时身份 Cookie。
+2. 此时不会向 `users` 表写入账号，也不会在客户端保存或展示正式用户 ID。
+3. 用户保存昵称，或使用需要正式身份的创建/加入房间流程后，服务器才生成唯一账号 ID并创建账号。
+4. 正式账号创建后，账号 ID、头像和密码设置等控件才会开放。
+
+未设置昵称时：
+
+- `GET /api/auth/me` 返回 `204 No Content`。
+- 密码和头像设置接口返回 `409 Conflict`。
+- 设置页显示“保存昵称后生成账号 ID”，不会暴露临时身份值。
+
+## 5. 修改账号 ID时的数据迁移
+
+账号 ID 修改不是简单地改一个字段。服务端会同步迁移与旧 ID 关联的数据和运行时身份，包括：
+
+- 用户资料、密码 Hash 和账号角色。
+- 已保存的平台 Cookie。
+- 房主、主持人和房间管理员身份。
+- WebSocket 用户映射与重连票据。
+
+迁移完成后，原账号 ID 不再代表该用户；新的身份 Cookie 和运行时映射会继续指向同一账号。
+
+## 6. 服务器管理员
+
+- 新增服务器管理员角色和管理界面。
+- 可通过 `SERVER_ADMIN_IDS` 配置初始服务器管理员账号 ID，多个 ID使用英文逗号分隔。
+- 服务器管理员可查看用户和房间列表、重置用户密码、删除用户以及解散房间。
+- 配置中的管理员 ID和系统保留 ID不能被普通用户抢占。
+
+### 权限分层
+
+服务器管理员和房间管理员是两套独立身份：
+
+- **服务器管理员**负责服务器级用户与房间治理。
+- **房主、主持人、房间管理员**负责当前房间内的管理操作。
+- 服务器管理员身份不会覆盖或清除房间角色，房间角色也不会自动获得服务器管理权限。
+- 所有敏感操作都在服务端重新校验身份和目标对象，不能仅靠修改客户端请求获得权限。
+
+## 7. 管理员审计日志
+
+管理员操作已按项目原有日志格式增加结构化审计记录，包含操作者、目标对象、操作结果及必要上下文。
+
+新增的主要审计事件包括：
+
+- `admin.access_denied`
+- `admin.users_viewed`
+- `admin.rooms_viewed`
+- `admin.user_deleted`
+- `admin.user_delete_failed`
+- `admin.user_delete_rejected`
+- `admin.user_password_reset`
+- `admin.user_password_reset_failed`
+- `admin.user_password_reset_rejected`
+- `admin.room_dissolved`
+- `admin.room_dissolve_failed`
+
+房间管理日志同时增加 `operatorIsServerAdmin` 字段，用于区分操作来自房间权限还是服务器管理员权限。
+
+## 8. 安全加固
+
+- 账号资料修改以服务端认证身份为准，不接受客户端伪造的目标用户 ID。
+- 普通用户不能读取或修改其他用户的敏感账号信息。
+- 普通用户不能调用服务器管理员接口，越权访问返回 `403 Forbidden`。
+- 账号 ID修改采用唯一性校验和事务迁移，防止重复 ID及只迁移部分数据。
+- 密码只保存 Hash，不保存明文。
+- 平台 Cookie 加密持久化，并绑定到账号身份。
+- 删除用户、重置密码、解散房间等高风险管理员操作均记录成功、拒绝或失败结果。
+
+## 9. 配置项
+
+本轮涉及的主要环境变量如下：
+
+```dotenv
+# SQLite 数据库地址
+DATABASE_URL=file:./data/music-together.db
+
+# 服务器管理员账号 ID，多个值使用英文逗号分隔
+SERVER_ADMIN_IDS=account-id-1,account-id-2
+
+# 是否只通过 HTTPS发送身份 Cookie
+IDENTITY_COOKIE_SECURE=false
+```
+
+部署时应使用持久化磁盘保存数据库文件，并在 HTTPS生产环境中启用安全 Cookie 配置。
+
+## 10. 验证结果
+
+本轮修改已完成以下验证：
+
+- 项目完整构建通过。
+- Prettier 格式检查通过。
+- Git 差异空白检查通过。
+- 普通用户跨账号修改注入测试通过。
+- 普通用户访问管理员接口返回 `403`。
+- 重复账号 ID返回 `409`。
+- 管理员配置 ID抢占返回 `400`。
+- 错误当前密码返回 `401`。
+- 修改账号 ID后，房主身份和平台 Cookie 能正确迁移。
+- 管理员操作会实际输出结构化审计日志。
+- 首次访问不会创建数据库用户；保存昵称后才生成正式账号。
+- 保存昵称前后账号设置界面状态正确，移动端页面无水平溢出，浏览器控制台无错误。

docs/architecture/coding-standards.md

@@ -0,0 +1,79 @@
+# 代码规范
+
+## 语言与模块
+
+- **TypeScript strict 模式**：所有包均启用 `"strict": true`
+- **ESM**：所有包 `"type": "module"`，使用 `import/export` 语法
+- **目标**：ES2022（server/shared），ES2022 + DOM（client）
+- **模块解析**：`"moduleResolution": "bundler"`
+
+## 命名规范
+
+| 类型             | 规范                     | 示例                                   |
+| ---------------- | ------------------------ | -------------------------------------- |
+| 组件文件/组件名  | PascalCase               | `ChatPanel.tsx`, `AudioPlayer`         |
+| Hook 文件/函数名 | camelCase + `use` 前缀   | `usePlayer.ts`, `useHowl`              |
+| Store 文件       | camelCase + `Store` 后缀 | `playerStore.ts`                       |
+| 工具函数/文件    | camelCase                | `format.ts`, `formatDuration()`        |
+| 类型/接口        | PascalCase               | `Track`, `RoomState`, `HandlerContext` |
+| 常量             | UPPER_SNAKE_CASE         | `EVENTS`, `LIMITS`, `TIMING`           |
+| 事件名           | 命名空间:动作            | `room:create`, `player:sync_response`  |
+
+## 路径别名
+
+客户端使用 `@/*` 映射到 `src/*`：
+
+```typescript
+import { usePlayerStore } from '@/stores/playerStore'
+import { cn } from '@/lib/utils'
+```
+
+## 状态更新
+
+Zustand Store 通过 `set()` 进行不可变更新：
+
+```typescript
+// 展开运算符更新嵌套状态
+updateRoom: (partial) =>
+  set((state) => ({
+    room: state.room ? { ...state.room, ...partial } : null,
+  }))
+```
+
+## 错误处理
+
+- **REST 路由**：统一使用 `validated(schema, label, handler)` 包装器自动完成 Zod 验证 + try/catch + 日志记录，返回适当的 HTTP 状态码
+- **Socket.IO**：中间件统一捕获异步错误，通过 `ROOM_ERROR` 事件回传 `ERROR_CODE` 枚举和消息
+- **客户端 Hook**：hook 中处理 Socket 错误事件，使用 `sonner` toast 提示用户（含限流反馈）
+- **客户端 ErrorBoundary**：`react-error-boundary` 全局 + 路由级双层包裹（`RouteErrorBoundary` 包裹 `HomePage` 和 `RoomPage`），页面崩溃只影响当前路由并导航回首页
+- **客户端连接状态**：`SocketProvider` 监听 disconnect/reconnect，显示持久化 warning toast
+- **搜索竞态防护**：`SearchDialog` 使用 `AbortController` 取消上一次请求 + `searchIdRef` 忽略过时响应 + `loadMoreAbortRef` 在卸载时中止加载更多请求。搜索结果和歌单详情均通过 `VirtualTrackList` 共享组件实现虚拟滚动 + 无限自动加载
+- **Socket 事件速率限制**：`socketRateLimiter` 中间件（`rate-limiter-flexible`）对 `QUEUE_ADD`、`PLAYER_PLAY`、`VOTE_START` 等关键事件做 per-socket 限流（10 次/5 秒）
+- **投票阈值动态更新**：`voteService.updateVoteThreshold` 在用户离开房间时重新计算 `requiredVotes`，防止人数减少后投票永远无法通过
+- **外部 API 超时保护**：`musicProvider` 所有 `@meting/core` 调用使用 `Promise.race` 包裹 15s 超时
+- **3 层引用式 LRU 缓存**：`musicProvider` 采用三层缓存架构——Layer 1: `trackRegistry`（max 10000, TTL 2h）以 `source:sourceId` 为 key 存储去重的 TrackMeta，所有经过系统的歌曲注册于此，支持跨上下文数据富化（搜索的 duration/cover 自动回填到歌单）；Layer 2: `searchIndex`（max 200, TTL 10min）和 `playlistIndex`（max 50, TTL 30min）仅存 sourceId 数组引用（不存 Track 对象），2000 首歌单仅占 ~40KB 引用而非 ~1MB 对象；Layer 3: `streamUrlCache`（1h）、`coverCache`（24h）、`lyricCache`（24h）存标量值。内存预算 worst case ~8.3MB（vs 旧架构 ~104MB）。歌单分页通过 `getPlaylistPage(source, id, limit, offset)` 实现，仅对当前页解析封面后回写 registry；VIP cookie 请求不走缓存。**所有平台歌单均使用原始 API 模式**（Netease 用 ncmApi 分块请求，Tencent/Kugou 用 Meting 无 format 模式），统一通过 `rawToTrack()` 解析（exhaustive switch + `never` 检查），保留 VIP/付费标记和歌曲时长
+- **广播防抖**：`broadcastRoomList` 使用 100ms trailing debounce，多次快速操作（create+join、多人 leave）合并为一次广播
+- **反向索引优化**：`roomRepository` 维护 `roomToSockets` 反向索引（`Map<string, Set<string>>`），使 `getP90RTT` 从 O(全局 socket 数) 降为 O(房间内 socket 数)
+- **Timer 泄漏防护**：`usePlayer`/`useHowl`/`usePlayerSync`/`PlayerControls` 中所有 `setTimeout` 均存入 ref 并在组件卸载时清理
+- **Stalled 检测**：`useHowl` 的 rAF 时间更新循环中检测播放卡住（`playing()` 为 true 但 `seek()` 8 秒内无变化），自动跳到下一首并 toast 提示。兜底播放中途网络断开等 Howler 不触发任何事件的场景
+
+## ESLint 配置
+
+- **Flat config** 格式（`eslint.config.js`）
+- 仅客户端包配置了 ESLint
+- 插件：`@eslint/js` recommended + `typescript-eslint` recommended + `react-hooks` + `react-refresh`
+- 无 Prettier（依赖编辑器格式化）
+
+## 导入顺序（约定）
+
+```typescript
+// 1. 第三方库
+import { create } from 'zustand'
+import type { Track } from '@music-together/shared'
+
+// 2. 内部模块（@/ 别名）
+import { storage } from '@/lib/storage'
+import { usePlayerStore } from '@/stores/playerStore'
+```
+
+---

docs/architecture/data-flow.md

@@ -0,0 +1,307 @@
+# 架构与数据流
+
+## 整体架构
+
+```mermaid
+graph TB
+  subgraph client [Client - React SPA]
+    Pages[Pages]
+    Hooks[Custom Hooks]
+    Stores[Zustand Stores]
+    SocketClient[Socket.IO Client]
+  end
+
+  subgraph server [Server - Node.js]
+    Express[Express REST API]
+    SocketServer[Socket.IO Server]
+    Controllers[Controllers]
+    Services[Services]
+    Repos[In-Memory Repositories]
+  end
+
+  subgraph external [External]
+    Meting["@meting/core 音乐源"]
+  end
+
+  Pages --> Hooks
+  Hooks --> Stores
+  Hooks --> SocketClient
+
+  SocketClient <-->|"WebSocket 双向通信"| SocketServer
+  Pages -->|"HTTP GET /api/music/*"| Express
+
+  SocketServer --> Controllers
+  Controllers --> Services
+  Services --> Repos
+  Express --> Meting
+  Services --> Meting
+```
+
+## Socket 事件清单
+
+| 分类         | 客户端 → 服务端                                                                                                                     | 服务端 → 客户端                                                                                                                            |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Room**     | `room:create`, `room:join`, `room:leave`, `room:list`, `room:settings`, `room:set_role`                                             | `room:created`, `room:state`, `room:user_joined`, `room:user_left`, `room:settings`, `room:error`, `room:list_update`, `room:role_changed` |
+| **Player**   | `player:play`, `player:pause`, `player:seek`, `player:next`, `player:prev`, `player:sync`, `player:sync_request`, `player:set_mode` | `player:play`, `player:pause`, `player:resume`, `player:seek`, `player:sync_response`                                                      |
+| **Queue**    | `queue:add`, `queue:add_batch`, `queue:remove`, `queue:reorder`, `queue:clear`                                                      | `queue:updated`                                                                                                                            |
+| **Chat**     | `chat:message`                                                                                                                      | `chat:message`, `chat:history`                                                                                                             |
+| **Vote**     | `vote:start`, `vote:cast`                                                                                                           | `vote:started`, `vote:result`                                                                                                              |
+| **Auth**     | `auth:request_qr`, `auth:check_qr`, `auth:set_cookie`, `auth:logout`, `auth:get_status`                                             | `auth:qr_generated`, `auth:qr_status`, `auth:set_cookie_result`, `auth:status_update`, `auth:my_status`                                    |
+| **Playlist** | `playlist:get_my`                                                                                                                   | `playlist:my_list`                                                                                                                         |
+| **NTP**      | `ntp:ping`                                                                                                                          | `ntp:pong`                                                                                                                                 |
+| **Server**   | —                                                                                                                                   | `server:audio_proxy_policy`                                                                                                                |
+
+## 关键数据模型
+
+```typescript
+// 音乐曲目
+interface Track {
+  id: string
+  title: string
+  artist: string[]
+  album: string
+  duration: number
+  cover: string
+  source: 'netease' | 'tencent' | 'kugou'
+  sourceId: string
+  urlId: string
+  lyricId?: string
+  picId?: string
+  streamUrl?: string
+  requiresServerProxy?: boolean // 上游字节需要服务器解密等处理
+  requestedBy?: string // 点歌人昵称
+  vip?: boolean // 是否为 VIP / 付费歌曲（可能无法播放或仅试听）
+}
+
+// 播放模式
+type PlayMode = 'sequential' | 'loop-all' | 'loop-one' | 'shuffle'
+
+// 音频质量档位 (kbps)
+type AudioQuality = 128 | 192 | 320 | 999 | 'highest' | ProviderSpecificQuality
+
+interface AudioProxyPolicy {
+  kugouForceProxy: boolean
+}
+
+// 客户端可见的房间状态
+interface RoomState {
+  id: string
+  name: string
+  creatorId: string
+  hostId: string
+  hasPassword: boolean
+  password?: string | null // 仅 owner 专用状态携带；公开状���不含该字段
+  audioQuality: AudioQuality
+  users: User[]
+  queue: Track[]
+  currentTrack: Track | null
+  playState: PlayState
+  playMode: PlayMode
+}
+
+// 播放状态（含服务端时间戳用于同步校准）
+interface PlayState {
+  isPlaying: boolean
+  currentTime: number
+  serverTimestamp: number
+}
+
+// 预定执行播放状态（play/pause/seek/resume 广播时使用）
+interface ScheduledPlayState extends PlayState {
+  serverTimeToExecute: number // 客户端应在此服务器时间点执行动作
+}
+
+// 歌单元数据
+interface Playlist {
+  id: string
+  name: string
+  cover: string
+  trackCount: number
+  source: MusicSource
+  creator?: string
+  description?: string
+}
+
+// 用户（RBAC: owner > admin > member）
+// hostId 是自动选举的播放主持(conductor)，不是可见角色
+interface User {
+  id: string
+  nickname: string
+  role: UserRole
+}
+type UserRole = 'owner' | 'admin' | 'member'
+
+// 聊天消息
+interface ChatMessage {
+  id: string
+  userId: string
+  nickname: string
+  content: string
+  timestamp: number
+  type: 'user' | 'system'
+}
+```
+
+## 播放同步机制
+
+采用**事件驱动同步 + 周期性比例漂移校正**架构：NTP 时钟同步 + Scheduled Execution + 比例控制漂移校正（EMA 平滑 + proportional rate + hard seek）。
+
+**三层防护**：
+
+1. **NTP 时钟同步**：保证各客户端时钟与服务器对齐（时间衰减加权中位数）
+2. **Scheduled Execution**：离散事件（play/pause/seek/resume）通过预定执行消除网络延迟差异（P90 RTT 自适应调度）
+3. **周期性比例漂移校正**：客户端每 2 秒发起 `PLAYER_SYNC_REQUEST`，服务端返回当前预期位置；漂移经 EMA 低通滤波后进入比例控制器，rate 调整幅度与漂移成正比（自然收敛无振荡），>200ms 用 hard seek 跳转
+
+## Layer 1：NTP 时钟同步 + RTT 回报
+
+客户端与服务器通过 `ntp:ping` / `ntp:pong` 事件交换时间戳，计算 `clockOffset`（客户端与服务端时钟差值），使 `getServerTime()` 返回与服务端对齐的时间。
+
+- 初始阶段：快速采样（每 50ms）收集 20 个样本，使用 `switchedRef` 保证仅在首次校准完成时切换到稳定阶段
+- 稳定阶段：每 5 秒一次 NTP 心跳
+- NTP 仅在用户进入房间后启动（`ClockSyncRunner` 渲染在 `RoomPage` 中），大厅用户不运行时钟同步
+- 使用**时间衰减加权中位数**计算 offset：每个样本按 `exp(-age / halfLife)` 衰减（halfLife=30s），兼具中位数的异常值鲁棒性和对网络环境突变的快速收敛能力
+- **`performance.now()` 锚点**：`getServerTime()` 基于 `performance.now()`（单调递增）计算时间流逝，不受系统时钟突变影响（NTP 调整、手动改时间、休眠唤醒）。每次 `processPong` 刷新锚点：`anchorServerTime = Date.now() + medianOffset`、`anchorPerfNow = performance.now()`
+- **RTT 回报**：每次 `ntp:ping` 附带 `lastRttMs`（客户端中位 RTT），服务端在 `NTP_PING` handler 中调用 `roomRepo.setSocketRTT()` 存储，用于自适应调度延迟计算
+- 核心模块：`clockSync.ts`（采样引擎 + `getServerTime()` + `getMedianRTT()` + `computeWeightedMedian()`）、`useClockSync.ts`（React Hook，在 SocketProvider 中运行）
+
+## Layer 2：Scheduled Execution（预定执行）
+
+所有多客户端同步动作（play、pause、seek、resume）由服务端广播 `ScheduledPlayState`，包含 `serverTimeToExecute` 字段。客户端收到后通过 `setTimeout(execute, serverTimeToExecute - getServerTime())` 在同一时刻执行，消除网络延迟差异。
+
+- 服务端根据房间 **P90 RTT** 动态计算调度延迟：`max(P90RTT * 1.5 + 100, 300ms)`，上限 3000ms。P90 避免单个慢连接拖累整个房间，房间人数 ≤3 时退化为取 max
+- RTT 由客户端 NTP 测量后通过 `ntp:ping` 事件回报，服务端以指数移动平均（alpha=0.2）平滑存储在 `roomRepository` 的 per-socket RTT map
+- 全部客户端（含操作发起者）统一收到广播并在预定时刻执行
+- **serverTimestamp 对齐**：播放中的动作（play/resume/seek）将 `room.playState.serverTimestamp` 设为 `serverTimeToExecute` 而非 `Date.now()`，确保 `estimateCurrentTime()` 在下一次 conductor 上报前也能准确估算位置
+- Scheduled action（seek/pause/resume）执行时自动重置 `rate(1)`，避免残留非正常速率；执行后同步更新 `roomStore.playState`（仅 `PlayState` 三字段，不含 `serverTimeToExecute`），确保 recovery effect 读到最新状态
+- **NTP 未校准保护**：`scheduleDelay()` 和 `usePlayer` 的 PLAYER_PLAY 调度在 NTP 未校准完成前退化为 0（立即执行），避免本地时钟偏差导致离谱的调度延迟
+- **Action ID 竞态保护**：每个 scheduled action 分配单调递增 ID，`setTimeout(fn, 0)` 回调执行前检查 ID 是否匹配，防止快速连续事件导致 stale 回调执行
+
+## Layer 3：周期性比例漂移校正（EMA + Proportional Rate + Hard Seek）
+
+**非 conductor 客户端**每 `SYNC_REQUEST_INTERVAL_MS`（2s）向服务端发送 `PLAYER_SYNC_REQUEST`（conductor 跳过，因为 conductor 是权威播放源，不应被 server 估算值反向校正），服务端通过 `estimateCurrentTime()` 计算当前预期位置后回复 `PLAYER_SYNC_RESPONSE`。客户端利用 NTP 校准时钟补偿网络延迟，计算原始漂移量后经 **EMA 低通滤波**（alpha=0.3）得到 `smoothedDrift`，再进入比例控制器：
+
+- **新曲 Grace Period**：新曲加载后 `DRIFT_GRACE_PERIOD_MS`（3s）内**仅跳过 rate 微调**（EMA 产生的比例速率校正），但**保留 hard seek**（大偏差 >200ms 仍会跳转修正）。此窗口内 `estimateCurrentTime()` 基于 `scheduleTime` 锚点，尚未被 conductor 上报修正，rate 微调可能基于不准确的估算。等待至少一次 conductor 上报后再启用全面校正
+- **EMA 平滑**：`smoothed = alpha * rawDrift + (1 - alpha) * prevSmoothed`，消除测量噪声导致的正负跳动
+- **EMA 冷启动种子**：pause/resume/新曲/hard seek 后 EMA 重置，首次 sync response 直接用 rawDrift 种子初始化（而非从 0 开始混合），避免恢复播放后 6-8 秒的 EMA 收敛滞后
+- `|smoothedDrift|` > `DRIFT_SEEK_THRESHOLD_MS`（200ms）→ hard seek 到预期位置 + rate(1) + 重置 smoothedDrift
+- `|smoothedDrift|` 5~200ms（死区之上） → **比例控制**：`rate = 1 - clamp(smoothedDrift * Kp, ±MAX_RATE_ADJUSTMENT)`（Kp=0.5，最大 ±2%）。漂移越大修正越强，接近目标时自然减速——数学上保证不振荡
+- `|smoothedDrift|` < `DRIFT_DEAD_ZONE_MS`（5ms）→ 恢复正常速率 rate(1)（消除稳态微小抖动）
+- UI 展示 smoothedDrift 而非 rawDrift，界面数值更稳定
+- **插件干扰自动降级**：设置 rate 后通过 `setTimeout(50ms)` 验证是否生效（timer 存于 ref，每次新 sync response 前清理上一个，组件卸载时也清理），若连续 3 次检测到被浏览器倍速插件覆盖才标记 `rateDisabled`；禁用后 hard seek 阈值降至 `DRIFT_PLUGIN_SEEK_THRESHOLD_MS`（30ms）；新曲加载时重置标记和计数器
+
+典型场景：手机息屏暂停后解锁、浏览器后台标签页节流、网络波动导致的累积偏移。
+
+## Conductor 上报与服务端状态维护
+
+Conductor（当前 `hostId` 对应用户）**自适应频率**上报当前播放位置到服务端：新曲开始后前 10 秒高频上报（每 2 秒，`CONDUCTOR_REPORT_FAST_INTERVAL_MS`），之后回到正常频率（每 5 秒，`CONDUCTOR_REPORT_INTERVAL_MS`），使用动态 `setTimeout` 链实现。仅用于维护 `room.playState` 的准确性（供 mid-song join、reconnect recovery 和漂移校正使用），**不会转发给其他客户端**。Conductor 标签页从后台恢复时（`visibilitychange` → visible），立即补偿上报一次当前位置，避免 `setTimeout` 被浏览器节流后 `playState` 过时。
+
+- **NTP 校准时间戳**：conductor 上报时附带 `hostServerTime`（历史字段名，通过 `getServerTime()` 获取的 NTP 校准后服务器时间），服务端优先使用此值作为 `playState.serverTimestamp`，替代 `Date.now()`。这消除了 conductor→Server 单向网络延迟（≈RTT/2）导致的 `estimateCurrentTime()` 系统性落后偏差。服务端对 `hostServerTime` 做 10 秒容差校验（`Math.abs(hostServerTime - Date.now()) < 10_000`），超出范围回退到 `Date.now()`
+- 服务端通过 `playerService.validateConductorReport()` 校验 conductor 上报位置与 `estimateCurrentTime()` 预估值的偏差，超过 `CONDUCTOR_REJECT_DRIFT_THRESHOLD_S`（3 秒）的报告视为过时数据（如手机息屏后恢复）被拒绝；但连续拒绝 `CONDUCTOR_REJECT_FORCE_ACCEPT_COUNT`（2）次后强制接受以打破僵局。`conductorRejectCount`、`lastNextTimestamp`、`playMutexes` 统一在 `playerService.cleanupRoom()` 中清理，避免内存泄漏。Conductor 切换时自动刷新 `playState.serverTimestamp` 和 `currentTime`，确保新 conductor 的首个报告不会被误拒
+- `syncService.estimateCurrentTime()` 基于 conductor 上报的位置 + 经过时间估算当前位置，对 `elapsed` 做 `Math.max(0, ...)` 防护（`serverTimestamp` 可能是未来的 `scheduleTime`），且 clamp 到曲目时长上界（`room.currentTrack.duration`），防止 conductor 断线后估算值无限增长
+- 新用户加入时，通过 `ROOM_STATE` 获取 `playState` 并计算应跳转到的位置
+- 断线重连时，`usePlayer` 的 recovery 机制自动检测 desync 并重新加载音轨。Recovery 通过检查 `loadingRef` 避免与 `onPlayerPlay` 双重 `loadTrack`，且在加载前清理 `playTimerRef` 防止定时器重复触发
+- **加载补偿上限**：`useHowl` 加载音频后会根据 `loadStartTime` 计算 elapsed 补偿 seek，但 elapsed 被 `MAX_LOAD_COMPENSATION_S`（2s）上限 clamp，防止网络慢时跳过歌曲开头过多
+- 漂移校正时，`PLAYER_SYNC_RESPONSE` 基于此数据返回准确位置
+
+## 播放模式
+
+房间支持 4 种播放模式（`PlayMode`），由 `room.playMode` 字段控制，默认 `loop-all`：
+
+| 模式         | 说明                                   |
+| ------------ | -------------------------------------- |
+| `sequential` | 顺序播放，末尾停止                     |
+| `loop-all`   | 列表循环，末尾回到第一首               |
+| `loop-one`   | 单曲循环，重播当前曲目                 |
+| `shuffle`    | 随机播放，从队列随机选一首（排除当前） |
+
+- **Owner/Admin** 直接 emit `player:set_mode`，服务端更新 `room.playMode` 并广播 `ROOM_STATE`
+- **Member** 通过 `vote:start { action: 'set-mode', payload: { mode } }` 投票切换
+- **指定播放**：播放列表工具栏提供 Play 按钮，Owner/Admin 直接 emit `player:play`；Member 通过 `vote:start { action: 'play-track', payload: { trackId, trackTitle } }` 投票播放
+- **投票移除**：播放列表工具栏的删除按钮对所有用户可见，Owner/Admin 直接 emit `queue:remove`；Member 通过 `vote:start { action: 'remove-track', payload: { trackId, trackTitle } }` 投票移除
+- 服务端 `queueService.getNextTrack(roomId, playMode)` 根据模式返回下一首；`getPreviousTrack` 在 `loop-all` 模式下支持尾→首回绕
+- 客户端 `PlayerControls` 提供循环切换按钮，带 `AnimatePresence` 图标过渡动画
+
+## 音频质量
+
+房间音质由 `room.audioQuality` 字段控制，默认 `320`（HQ）。除固定和平台特色档位外，`highest` 表示“尽量高”：
+
+| 档位    | bitrate  | 说明                                 |
+| ------- | -------- | ------------------------------------ |
+| 标准    | 128 kbps | 流量节省                             |
+| 较高    | 192 kbps | 平衡音质与流量                       |
+| HQ      | 320 kbps | 高品质（默认）                       |
+| 无损 SQ | 999 kbps | 无损音质，通常需要 VIP 账号          |
+| 尽量高  | highest  | 根据歌曲平台及房间内最高会员等级选择 |
+
+- **房主和房间管理员**可在房间设置中切换音质；其他房间设置仍仅限房主
+- 登录平台会员账号不会改变房间音质；新房间仍保持默认 `320`，需要房主手动切换其他档位
+- 音质切换仅对**下一首歌**生效，当前播放不中断
+- 服务端将各平台会员统一为 `0/1/2`（普通/VIP/SVIP），并从房间凭据池选择该歌曲平台等级最高的账号
+- `audioQualityPolicy.getEffectiveQuality()` 一次确定不超过账号权益和房间设置的目标档位，不通过连续请求猜测会员等级
+- 网易云：普通账号最高 320、VIP 最高高清臻音、SVIP 最高超清母带；QQ 与酷狗使用各自对应的 VIP/SVIP 档位
+- B站：普通账号最高 192K，普通/年度大会员最高 Hi-Res；服务端用带 Cookie 的单次 WBI `playurl` 请求合并普通和 FLAC DASH 音轨，并在同一响应内选择不超过目标的最高可用档位。B站杜比为 E-AC-3，桌面浏览器支持不完整，当前明确不参与选流
+- B站沿用现有五档，不增加平台专属 UI 选项：
+
+| 房间音质       | 无会员   | 普通大会员 | 年度大会员 |
+| -------------- | -------- | ---------- | ---------- |
+| 标准 128kbps   | B站 132K | B站 132K   | B站 132K   |
+| 较高 192kbps   | B站 192K | B站 192K   | B站 192K   |
+| 高品质 320kbps | B站 192K | B站 192K   | B站 192K   |
+| 无损 SQ        | B站 192K | Hi-Res     | Hi-Res     |
+| 尽量高         | B站 192K | Hi-Res     | Hi-Res     |
+
+B站没有与房间 128K、320K 完全对应的普通 DASH 音轨，因此分别映射为最接近的 132K、192K。Hi-Res 还要求视频本身提供 FLAC 音轨，否则直接从同一次响应选 192K，不再次请求其他音质。
+
+- 上游若返回歌曲实际可用的较低规格，服务端记录 `actualQuality` 和实际平均码率，不再逐档重新请求
+- `musicProvider.streamUrlCache` 的 key 包含 bitrate，不同音质自动隔离缓存
+
+## 音频代理策略
+
+- B站音频始终通过服务器代理，播放所需 Cookie 只保留在服务端，不提供关闭入口。
+- 全局 `AudioProxyPolicy` 只包含酷狗策略并持久化在 SQLite `server_settings` 表，旧数据库或无效配置默认酷狗强制代理。
+- 只有服务器管理员可以通过 `GET/PATCH /api/admin/audio-proxy-policy` 读取或修改酷狗策略；PATCH 接受 `kugouForceProxy` 并返回完整策略。
+- 新 WebSocket 连接会收到 `server:audio_proxy_policy`，管理员修改后服务端向 `lobby` 中的全部连接广播完整策略。
+- `kugouForceProxy=false` 时，Web 端的酷狗标准版明文资源由兼容代理入口返回 `307` 到 CDN，音频字节不经过服务器；酷狗概念版和需要服务端处理的资源仍使用代理。Android 继续按自身能力先请求 CDN，失败时仅回退一次现有服务器代理。
+- 重新启用酷狗强制代理时，Android 将正在直连的对应曲目保留位置切回代理；关闭强制代理不打断当前播放，从下一次加载开始生效。
+- 酷狗策略同时覆盖 `kugou` 与 `kugou_concept`。服务端登记概念版 URL，并为已注册 QMC2 解密器的流设置 `Track.requiresServerProxy=true`；`.mflac`/`.mgg` 地址也按加密资源保守处理。Android 即使在关闭强制代理时也直接使用服务器代理解密，仅对明文资源尝试 CDN 直连。
+
+## 队列清空
+
+- Owner/Admin 可通过播放列表抽屉的「清空」按钮（`ListX` 图标）一次性清空队列
+- 采用二次确认防误操作：首次点击变为 destructive 提示，3 秒内再次点击才执行
+- 服务端 `queue:clear` handler 复用 `remove` on `Queue` 权限，清空后停止播放并广播 `QUEUE_UPDATED` + `PLAYER_PAUSE` + `ROOM_STATE`
+
+## 其他同步机制
+
+1. **暂停快照**：服务端 `pauseTrack()` 在暂停前调用 `estimateCurrentTime()` 快照准确位置
+2. **恢复播放**：暂停后点击播放，服务端检测同一首歌时发 `player:resume`（所有客户端预定时刻恢复）
+3. **自动续播**：房主独自重新加入时，若有歌曲暂停/排队中，自动恢复播放
+4. **加入房间补偿**：中途加入的客户端使用 `getServerTime()` 计算当前应处的播放位置，采用 fade-in 淡入策略（400ms 等待 + 200ms fade）减少加入延迟
+5. **房间宽限期**：普通房间空置 60 秒 (`ROOM_GRACE_PERIOD_MS`) 后自动清理（重复调用 `scheduleDeletion` 不会创建重复 timer）；永久房间不会因空置被清理，最近 200 条聊天消息会持久化到 SQLite 并在服务重启后恢复
+6. **角色与 Conductor 机制**：房间记录 `creatorId`（创建者 ID，永久不变）、`adminUserIds: Set<string>`（持久化 admin 集合）和 `temporaryAdminUserId`（临时管理员，仅在线态）。非空房间通过 `reconcileRoomRoles()` 保证至少有一个具备管理能力的在线用户：创建者在线时为 `owner`；持久 admin 在线时保持 `admin`；若 owner / 持久 admin 都不在线，则选择一个在线成员作为临时 `admin`，且不写入 `adminUserIds`。owner / 持久 admin 返回时会清除临时管理员并恢复其普通成员身份。`room.hostId` 是自动选举的播放主持（conductor），在用户加入/离开时基于已协调后的角色重选（优先级：owner > admin > member），无需宽限期。`setUserRole` 只能设置持久 `admin` / `member`（不能改 `owner`），同步维护 `adminUserIds`。返回的创建者/持久化 admin 免密码验证
+7. **持久化用户身份**：客户端通过 `storage.getUserId()` 生成并持久化 `nanoid`，每次 `ROOM_CREATE` / `ROOM_JOIN` 携带 `userId`，使服务端可跨 socket 重连识别同一用户。服务端通过 `roomRepo.getSocketMapping(socket.id)` 获取 `{ roomId, userId }` 映射——`socket.id` 仅用于 Socket 映射查找，所有涉及用户身份的操作（host 判断、auth cookie 归属、权限检查等）统一使用 `mapping.userId`
+8. **`currentUser` 自动推导**：`roomStore` 中 `currentUser` 始终从 `room.users` 自动推导（`deriveCurrentUser`），`setRoom` / `addUser` / `removeUser` / `updateRoom` 等 action 内部自动同步，不暴露 `setCurrentUser` 以避免脱节风险
+9. **断线时钟重置**：`resetAllRoomState()` 除重置 Zustand stores 外，还调用 `resetClockSync()` 清空 NTP 采样，确保重连后使用全新的时钟校准数据
+10. **Socket 断开竞态防护**：页面刷新时新旧 socket 的 join/disconnect 到达顺序不确定，`leaveRoom` 通过 `roomRepo.hasOtherSocketForUser()` 检测同一用户是否有更新的 socket 连接，避免旧 socket disconnect 误删活跃用户
+11. **投票安全网**：`voteController` 接收 `VOTE_START` 时，若检测到用户已有直接操作权限（owner/admin），不再返回错误，而是直接执行该操作（`executeAction`），防止客户端-服务端角色不同步时操作失效。部分 VoteAction 通过 `PERM_MAP` 映射到不同的 CASL action+subject（如 `'play-track'` → `('play', 'Player')`，`'remove-track'` → `('remove', 'Queue')`）
+12. **切歌防抖**：500ms (`PLAYER_NEXT_DEBOUNCE_MS`) 内不重复触发下一首。`playNextTrackInRoom` / `playPrevTrackInRoom` 将 debounce 检查和队列导航封装在 per-room mutex 内部，确保同 tick 的多个 NEXT/PREV 事件不会都通过 debounce。支持 `{ skipDebounce: true }` 选项，投票执行、删除当前曲目等场景绕过 debounce 以确保操作不被静默吞掉
+13. **停止播放统一处理**：`playerService.stopPlayback()` 统一处理"队列为空/清空"场景——清除 currentTrack、emit PLAYER_PAUSE、广播 ROOM_STATE、刷新大厅列表，避免 controller 中重复逻辑。`stopPlaybackSafe()` 提供 mutex 保护版本，`QUEUE_CLEAR` 使用此版本防止与并发 `autoPlayIfEmpty` 竞态
+14. **大厅重连刷新**：`useLobby` 监听 socket `connect` 事件，断线重连后自动重新拉取房间列表
+15. **投票执行**：`VOTE_CAST` / `VOTE_START` 中 `executeAction` 使用 `await` 确保动作完成后才广播 `VOTE_RESULT`。投票的 `next`/`prev` 通过 `playerService.playNextTrackInRoom` / `playPrevTrackInRoom`（`skipDebounce: true`）执行，与直接操作路径完全一致（含 stopPlayback 兜底和播放失败重试），且不受 debounce 影响
+16. **密码安全隔离**：`toPublicRoomState()` 默认不含密码明文；`toPublicRoomStateForOwner()` 仅在发送给 owner 的 socket 时使用（创建房间、加入房间、设置变更、conductor/角色变更）。非 owner 成员仅能看到 `hasPassword` 布尔标记，无法获取密码明文。设置广播通过 `socket.emit`（owner） + `socket.to(roomId).emit`（其他成员）分别发送。owner 在线且 conductor/角色变更时，通过 `roomRepo.getSocketIdForUser()` 反查 owner 的 socketId 定向发送含密码版本；没有 owner 在线（仅临时管理员）时广播不含密码版本
+
+## REST API
+
+| 路径                            | 方法  | 用途                                                                                                    |
+| ------------------------------- | ----- | ------------------------------------------------------------------------------------------------------- |
+| `/api/music/search`             | GET   | 搜索曲目（`source` + `keyword` + `page`）                                                               |
+| `/api/music/url`                | GET   | 解析流媒体 URL（`source` + `id`）                                                                       |
+| `/api/music/lyric`              | GET   | 获取歌词                                                                                                |
+| `/api/music/cover`              | GET   | 获取封面图                                                                                              |
+| `/api/music/playlist`           | GET   | 获取歌单曲目列表（`source` + `id` + `limit` + `offset`），分页返回 `{ tracks, total, offset, hasMore }` |
+| `/api/rooms/:roomId/check`      | GET   | 房间预检（存在性 + 是否需要密码），用于分享链接直接访问时的前置校验                                     |
+| `/api/admin/audio-proxy-policy` | GET   | 服务器管理员读取酷狗全局强制代理策略                                                                    |
+| `/api/admin/audio-proxy-policy` | PATCH | 服务器管理员部分更新代理策略并广播完整结果                                                              |
+| `/api/health`                   | GET   | 健康检查                                                                                                |
+
+---

docs/architecture/dependencies.md

@@ -0,0 +1,77 @@
+# 第三方库依赖
+
+## Client 核心依赖
+
+| 分类         | 库                                                         | 版本     | 用途                                    |
+| ------------ | ---------------------------------------------------------- | -------- | --------------------------------------- |
+| **UI 框架**  | react, react-dom                                           | ^19.2.0  | UI 基础                                 |
+|              | shadcn/ui (new-york)                                       | —        | 组件库（基于 Radix UI）                 |
+|              | radix-ui                                                   | ^1.4.3   | 无障碍 UI 原语                          |
+|              | tailwindcss                                                | ^4.1.18  | 原子化 CSS                              |
+|              | class-variance-authority                                   | ^0.7.1   | 组件变体样式                            |
+|              | tailwind-merge                                             | ^3.4.0   | class 合并去重                          |
+|              | clsx                                                       | ^2.1.1   | 条件 class 拼接                         |
+| **权限**     | @casl/react                                                | ^5.0.1   | RBAC 权限（配合 @casl/ability）         |
+| **错误边界** | react-error-boundary                                       | ^6.1.0   | React Error Boundary                    |
+| **状态管理** | zustand                                                    | ^5.0.11  | 轻量全局状态                            |
+| **路由**     | react-router-dom                                           | ^7.13.0  | 客户端路由                              |
+| **实时通信** | socket.io-client                                           | ^4.8.3   | WebSocket 客户端                        |
+| **音频**     | howler                                                     | ^2.2.4   | 音频播放引擎                            |
+|              | @applemusic-like-lyrics/core                               | ^0.2.0   | 歌词解析核心                            |
+|              | @applemusic-like-lyrics/react                              | ^0.2.0   | 歌词 React 组件                         |
+| **动画**     | motion                                                     | ^12.34.0 | Framer Motion 动画                      |
+|              | tw-animate-css                                             | ^1.4.0   | Tailwind 动画预设                       |
+| **图形渲染** | @pixi/app, core, display, sprite                           | ^7.4.3   | PixiJS（歌词背景渲染）                  |
+|              | @pixi/filter-blur, filter-bulge-pinch, filter-color-matrix | —        | PixiJS 滤镜                             |
+| **弹窗**     | vaul                                                       | ^1.x     | 移动端 Drawer（底部抽屉，支持拖拽关闭） |
+| **虚拟列表** | @tanstack/react-virtual                                    | ^3.13.18 | 虚拟滚动（歌单详情大列表）              |
+| **工具**     | dayjs                                                      | ^1.11.19 | 日期格式化                              |
+|              | nanoid                                                     | ^5.1.6   | ID 生成                                 |
+|              | sonner                                                     | ^2.0.7   | Toast 通知                              |
+|              | lucide-react                                               | ^0.563.0 | 图标库                                  |
+|              | jss, jss-preset-default                                    | ^10.10.0 | CSS-in-JS（AMLL 依赖）                  |
+
+## Server 核心依赖
+
+| 库                                | 版本    | 用途                                                                |
+| --------------------------------- | ------- | ------------------------------------------------------------------- |
+| express                           | ^4.21.0 | HTTP 框架                                                           |
+| socket.io                         | ^4.8.3  | WebSocket 服务端                                                    |
+| @meting/core                      | ^1.6.0  | 多音源音乐数据聚合                                                  |
+| @s4p/kugou-lrc                    | ^0.2.0  | 酷狗 KRC 逐字歌词获取与解析                                         |
+| nanoid                            | ^5.0.9  | 房间 ID 生成                                                        |
+| cors                              | ^2.8.5  | 跨域                                                                |
+| dotenv                            | ^16.4.5 | 环境变量                                                            |
+| zod                               | ^4.3.6  | 请求数据验证（配合 shared schemas）                                 |
+| pino                              | ^10.3.1 | 结构化日志                                                          |
+| rate-limiter-flexible             | ^9.1.1  | 聊天限流                                                            |
+| @neteasecloudmusicapienhanced/api | ^4.30.1 | 网易云 QR 登录 / Cookie 验证 / 用户信息                             |
+| qrcode                            | ^1.5.4  | QR 码生成（酷狗扫码登录，API 仅返回 URL 需服务端转 base64 DataURL） |
+| escape-html                       | ^1.0.3  | HTML 转义（防注入）                                                 |
+| p-limit                           | ^7.3.0  | 并发控制（封面批量解析）                                            |
+| lru-cache                         | ^11.2.6 | LRU 缓存（musicProvider 外部 API 结果缓存）                         |
+
+## Shared 核心依赖
+
+| 库            | 版本   | 用途                        |
+| ------------- | ------ | --------------------------- |
+| @casl/ability | ^6.8.0 | RBAC 权限定义（前后端共用） |
+| zod           | ^4.3.6 | 数据验证 Schema             |
+
+## 开发工具
+
+| 库                          | 版本    | 包     | 用途                    |
+| --------------------------- | ------- | ------ | ----------------------- |
+| vite                        | ^7.3.1  | client | 前端构建                |
+| @vitejs/plugin-react        | ^5.1.1  | client | Vite React 插件         |
+| @tailwindcss/vite           | ^4.1.18 | client | Vite Tailwind 插件      |
+| typescript                  | ~5.9.3  | all    | 类型系统                |
+| tsx                         | ^4.19.0 | server | 服务端 TS 运行/热重载   |
+| pino-pretty                 | ^13.1.3 | server | 开发环境日志美化        |
+| eslint                      | ^9.39.1 | client | 代码检查                |
+| eslint-plugin-react-hooks   | ^7.0.1  | client | React Hooks 规则        |
+| eslint-plugin-react-refresh | ^0.4.24 | client | React Fast Refresh 规则 |
+| concurrently                | ^9.2.1  | root   | 并行运行前后端          |
+| kill-port                   | ^2.0.1  | root   | 端口清理                |
+
+---

docs/architecture/deployment.md

@@ -0,0 +1,64 @@
+# 部署方案
+
+## 架构
+
+采用**纯 Node.js 单镜像**方案：Express 同时托管前端 SPA 静态文件和后端 API/WebSocket，无需 Nginx。
+
+```
+Docker 容器 (:3001)
+├── / 静态文件        → client/dist（Vite 产物）
+├── /api/*           → REST API
+└── /socket.io/*     → WebSocket
+```
+
+## CI/CD 流程
+
+1. **push 到 main** → GitHub Actions 构建 Docker 镜像 → 推送到 GHCR（`ghcr.io`）
+2. **服务器上** Watchtower 每 5 分钟检查镜像更新 → 自动拉取并重启容器
+
+零人工干预，GitHub 零额外 Secrets（使用自带的 `GITHUB_TOKEN`）。
+
+## Docker 多阶段构建
+
+- **阶段 1（deps）**：`pnpm install --frozen-lockfile` 安装全部依赖
+- **阶段 2（build）**：分别构建 shared、server（tsc）、client（vite build）
+- **阶段 3（production）**：仅安装 server 生产依赖（`--filter @music-together/server...`），复制构建产物
+
+## CORS 策略
+
+- `CLIENT_URL` 未设置 → 自动模式，允许所有来源访问（适用于单镜像同域部署、局域网、公网反代）
+- `CLIENT_URL` 显式设置 → 严格白名单模式（适用于前后端分离跨域部署）
+
+## Identity Cookie 策略
+
+- 未显式设置 `IDENTITY_COOKIE_SECURE` 时，服务端会根据当前请求协议自动决定是否添加 `Secure`
+- 局域网 HTTP 访问会下发非 Secure cookie
+- 公网 HTTPS / 反代 HTTPS 访问会下发 Secure cookie
+- 自动判断 HTTPS 依赖代理正确透传 `X-Forwarded-Proto`
+- 仅在需要强制行为时才手动设置 `IDENTITY_COOKIE_SECURE`
+
+## 前端同域适配
+
+`SERVER_URL` 默认使用 `window.location.origin`，同域部署时自动指向当前页面的 origin，无需配置。
+
+## 静态文件托管
+
+`packages/server/src/index.ts` 在启动时检测 `client/dist/index.html` 是否存在：
+
+- **存在**（生产环境）：挂载 `express.static` + SPA fallback
+- **不存在**（本地开发）：跳过，零影响
+
+## 服务器部署命令
+
+```bash
+# 启动应用容器
+docker run -d --name music-together --restart unless-stopped -p 3001:3001 ghcr.io/<owner>/music-together:latest
+
+# 启动 Watchtower 自动更新
+docker run -d --name watchtower --restart unless-stopped \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  -e WATCHTOWER_CLEANUP=true \
+  containrrr/watchtower --interval 300 music-together
+```
+
+如使用 1Panel，创建反向代理网站指向 `127.0.0.1:3001`，启用 WebSocket 和 HTTPS。

docs/architecture/design-patterns.md

@@ -0,0 +1,204 @@
+# 设计模式
+
+## 前端模式
+
+## Zustand Store 模式
+
+5 个独立 store，各自管理一个领域的状态：
+
+| Store           | 职责                                                | 持久化                    |
+| --------------- | --------------------------------------------------- | ------------------------- |
+| `playerStore`   | 播放状态（曲目、进度、音量、歌词）                  | 音量持久化到 localStorage |
+| `roomStore`     | 房间状态（room、currentUser 自动推导自 room.users） | 无                        |
+| `chatStore`     | 聊天（消息列表、未读数、开关状态）                  | 无                        |
+| `lobbyStore`    | 大厅（房间列表、加载状态）                          | 无                        |
+| `settingsStore` | 设置（歌词对齐/动画/字体/翻译字体大小、背景参数）   | 全部持久化到 localStorage |
+
+使用方式：通过选择器订阅特定字段，避免不必要的渲染：
+
+```typescript
+const volume = usePlayerStore((s) => s.volume)
+```
+
+在 Socket 回调中使用 `getState()` 避免闭包问题：
+
+```typescript
+const room = useRoomStore.getState().room
+```
+
+## 自定义 Hooks 组合模式
+
+两个核心组合 hook 各自编排多个子 hook：
+
+```
+usePlayer                             useRoom
+├── useHowl (Howler.js 实例)          ├── useRoomState (核心房间事件)
+├── useLyric (歌词解析)                ├── useChatSync (聊天事件)
+└── usePlayerSync                     ├── useQueueSync (队列事件)
+    ├── Scheduled Execution           ├── useAuthSync (Cookie 持久化 + toast 反馈，永不删除 cookie)
+    └── Host Progress Reporting       └── useConnectionGuard (断线重置)
+
+SocketProvider (连接管理，无 NTP)
+
+RoomPage
+└── ClockSyncRunner → useClockSync (NTP 时钟同步，仅房间内运行)
+```
+
+通用工具 Hook：`useSocketEvent(event, handler)` 封装 `socket.on/off` 样板代码，已在 `useLobby` 和 `useVote` 中使用。
+
+其他独立 hook：`useChat`、`useLobby`、`useQueue`、`useVote`、`useAuth`、`usePlaylist`，每个 hook 负责将 Socket 事件绑定到对应 Store。
+
+`usePlaylist` 管理歌单功能：通过 Socket 获取用户歌单列表（`playlist:get_my` → `playlist:my_list`），通过 REST 分页获取歌单曲目（`GET /api/music/playlist?limit=100&offset=0`，返回 `{ tracks, total, offset, hasMore }`），提供 `loadMoreTracks()` 无限加载下一页、URL/ID 解析工具函数（`parsePlaylistInput`），以及单曲/批量添加到队列。切换歌单时立即重置状态防止闪旧数据，内部 `loadingMoreRef`（ref）做同步防重，避免 React 批量更新前的闭包竞态。URL 拼接通过 `buildPlaylistUrl()` 辅助函数集中管理。
+
+## 受控 Dialog 模式
+
+所有弹窗组件遵循统一的 prop 接口：
+
+```typescript
+interface DialogProps {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  // 业务回调...
+}
+```
+
+父组件（页面）管理 `open` 状态，弹窗组件只负责渲染和用户交互。
+
+## ResponsiveDialog 模式
+
+`responsive-dialog.tsx` 通用组件根据视口宽度自动切换呈现方式：
+
+- **桌面端**（≥640px）：居中 Dialog（基于 Radix UI）
+- **移动端**（<640px）：底部 Drawer（基于 vaul，支持拖拽关闭）
+
+通过 React Context 向子组件传递 `isMobile` 状态，提供一一映射的子组件：`ResponsiveDialog`、`ResponsiveDialogContent`、`ResponsiveDialogHeader`、`ResponsiveDialogTitle`、`ResponsiveDialogDescription`、`ResponsiveDialogFooter`、`ResponsiveDialogClose`、`ResponsiveDialogBody`。使用方只需替换 import 路径即可获得响应式行为。项目中所有业务弹窗（CreateRoomDialog、PasswordDialog、NicknameDialog、SearchDialog、SettingsDialog）均已迁移至此组件。
+
+## Context Provider 模式
+
+`SocketProvider` 通过 React Context 提供 Socket.IO 实例和连接状态，并内置断线/重连 Toast 提示：
+
+```typescript
+const { socket, isConnected } = useSocketContext()
+```
+
+`AbilityProvider` 通过 React Context 提供 CASL ability 实例，组件可通过 `useContext(AbilityContext)` 查询权限。
+
+## 组件组合模式
+
+`AudioPlayer` 组合 `NowPlaying` + `SongInfoBar` + `PlayerControls` + `LyricDisplay`，各组件独立负责自己的渲染逻辑。`RoomPage` 组合所有功能区域和覆盖层弹窗。
+
+## 移动端双模式播放页面
+
+移动端（竖屏）播放页面通过 `lyricExpanded` 状态实现两种模式切换，模仿 Apple Music 移动端交互：
+
+- **默认模式**（`lyricExpanded=false`）：大封面 + 歌曲信息 + 控制器，封面自适应剩余空间（`flex-1 min-h-0` + `aspect-square max-h-full max-w-full`），控制器固定底部，不显示歌词
+- **歌词模式**（`lyricExpanded=true`）：点击封面后，封面缩小到顶部变为 compact 横排（48px 小封面 `rounded-md` + ��题 `text-base` / 艺术家 `text-sm`），歌词区域 fade+slide-up 入场占满中间空间，控制器固定底部
+
+布局策略：
+
+- 移动端外层 padding `px-5 py-7`（水平 20px，垂直 28px），所有子元素 `w-full`，不使用 `max-w` 约束，边距由外层 padding 统一控制
+- `NowPlaying` wrapper 使用 `flex-1 min-h-0`，默认模式下封面在剩余空间内居中缩放（`aspect-square max-h-full max-w-full`），避免封面过大挤压控件
+
+关键技术：
+
+- `NowPlaying` 组件支持 `compact` prop 切换大图/小图布局，`onCoverClick` 触发模式切换
+- `framer-motion` 的 `layoutId`（"cover-art" / "song-info"）实现封面和文字在两种布局间的共享布局动画（0.45s Apple 风格贝塞尔缓动）
+- `LayoutGroup` 包裹移动端内容区，确保跨组件 `layoutId` 动画生效
+- `AnimatePresence` + `motion.div` 实现歌词区域的 fade+slide-up 入场/退场
+- 歌词模式状态在切歌时保持不变，用户手动点击封面切换
+- 桌面端保持左右分栏布局不受影响
+
+## 后端模式
+
+## 分层架构
+
+```
+Controller → Service → Repository / Utils
+```
+
+- **Controller**：注册 Socket 事件监听器，薄编排层（校验输入 → 调用 Service → 编排通知）。不包含业务逻辑。
+- **Service**：业务逻辑、跨领域编排、Socket 广播。关键服务职责拆分：
+  - `roomService`：房间 CRUD + 角色管理 + 临时管理员协调（`reconcileRoomRoles`）+ conductor 选举（`electConductor`）+ 加入校验（`validateJoinRequest`）。Re-export `toPublicRoomState` 和 `broadcastRoomList` 以保持控制器调用方式不变。
+  - `roomLifecycleService`：房间空置删除定时器 + 防抖广播。不依赖 `roomService`，消除循环依赖。API：`scheduleDeletion`、`cancelDeletionTimer`、`broadcastRoomList`、`clearAllTimers`。角色宽限期已移除（conductor 自动选举，无需 grace period）。
+  - `playerService`：播放状态管理 + 流 URL 解析 + 切歌防抖 + 加入播放同步（`syncPlaybackToSocket`）+ 房间清理（`cleanupRoom`）。`playTrackInRoom` 通过 per-room Promise 链互斥锁防止并发竞态。`playNextTrackInRoom` / `playPrevTrackInRoom` 将 debounce + 队列导航 + 播放统一封装在 mutex 内部。`autoPlayIfEmpty` 在 mutex 内重新检查 `room.currentTrack`，防止并发 QUEUE_ADD 双重自动播放。
+- **Repository**：数据存取（当前为内存 Map，接口抽象，可替换为数据库）
+- **Utils**：纯函数工具（`toPublicRoomState` 等），无状态，可被任意层引用
+
+## Repository 模式
+
+使用 TypeScript 接口抽象数据访问：
+
+```typescript
+interface RoomRepository {
+  get(roomId: string): RoomData | undefined
+  set(roomId: string, room: RoomData): void
+  delete(roomId: string): void
+  getAll(): Map<string, RoomData>
+  // ...
+}
+```
+
+当前实现为 `InMemoryRoomRepository`（`Map<string, RoomData>`），未来可替换为 Redis/数据库实现。
+
+## Socket.IO 中间件链
+
+```
+withPermission(action, subject)  →  withRoom(io)  →  Handler
+withOwnerOnly(io)                →  withRoom(io)  →  Handler
+```
+
+- `withRoom`：校验 Socket 是否在房间中，构建 `HandlerContext`（io, socket, roomId, room, user）
+- `withPermission`：在 `withRoom` 基础上用 CASL `defineAbilityFor(role)` 检查 `(action, subject)` 权限
+- `withOwnerOnly`：在 `withRoom` 基础上仅允许房主（`user.role === 'owner'`），用于设置和角色管理
+
+错误统一通过 `ROOM_ERROR` 事件回传给客户端，错误码使用 `ERROR_CODE` 枚举（`shared/types.ts`），包括：`NOT_IN_ROOM`、`ROOM_NOT_FOUND`、`NO_PERMISSION`、`INVALID_DATA`、`QUEUE_FULL`、`RATE_LIMITED`、`INTERNAL` 等。
+
+## 结构化日志（pino）
+
+基于 [pino](https://github.com/pinojs/pino) 的薄封装，开发环境使用 `pino-pretty` 美化输出：
+
+```typescript
+logger.info('Room created', { roomId, socketId: socket.id })
+logger.error('Failed to resolve stream URL', err, { roomId, trackId })
+```
+
+输出格式：`[ISO_TIMESTAMP] LEVEL message {JSON_CONTEXT}`
+
+## 共享模式
+
+## 类型驱动的事件系统
+
+`EVENTS` 常量对象定义所有事件名，`ClientToServerEvents` / `ServerToClientEvents` 接口为每个事件定义精确的负载类型，确保前后端通信的类型安全。
+
+## 构建优化
+
+- **路由级懒加载**：`RoomPage` 和 `NotFoundPage` 使用 `React.lazy` + `Suspense`（`HomePage` 保持同步加载以保证首屏速度）
+- **Vite manualChunks 分包**：react、socket.io、motion、radix-ui、pixi.js 分别打包为独立 chunk，利用浏览器长期缓存
+- **React.memo**：列表项组件（`RoomCard`、`ChatMessage`、`TrackListItem`）和高频更新组件（`PlayerControls`）均使用 `React.memo` 避免不必要的 re-render
+- **Zustand 细粒度 selector**：避免 `useRoomStore((s) => s.room)` 的粗粒度订阅，改用 `s.room?.name` 等精确字段
+
+## 常量集中管理
+
+`LIMITS` 和 `TIMING` 在 shared 包中统一定义，���后端共用：
+
+```typescript
+LIMITS.QUEUE_MAX_SIZE // 100
+LIMITS.QUEUE_BATCH_MAX_SIZE // 100
+LIMITS.CHAT_HISTORY_MAX // 200
+TIMING.ROOM_GRACE_PERIOD_MS // 60_000
+TIMING.PLAYER_NEXT_DEBOUNCE_MS // 500
+TIMING.VOTE_TIMEOUT_MS // 30_000
+NTP.INITIAL_INTERVAL_MS // 50
+NTP.STEADY_STATE_INTERVAL_MS // 5_000
+NTP.MAX_INITIAL_SAMPLES // 20
+NTP.MIN_SCHEDULE_DELAY_MS // 300
+NTP.MAX_SCHEDULE_DELAY_MS // 3_000
+QR_STATUS.EXPIRED // 800
+QR_STATUS.WAITING_SCAN // 801
+QR_STATUS.SCANNED // 802
+QR_STATUS.SUCCESS // 803
+QR_TIMING.POLL_INTERVAL_MS // 2_000
+QR_TIMING.SUCCESS_CLOSE_DELAY_MS // 1_000
+```
+
+---

docs/architecture/dev-guide.md

@@ -0,0 +1,74 @@
+# 开发指南
+
+## 快速启动
+
+```bash
+# 安装依赖
+pnpm install
+
+# 启动前后端开发服务器（默认同时开放到局域网）
+pnpm dev
+
+# 其他设备通过 http://你的局域网IP:5173 访问前端
+# 前端会自动连接到 http://你的局域网IP:3001 后端
+
+# 仅启动前端
+pnpm dev:client
+
+# 仅启动后端
+pnpm dev:server
+```
+
+## 端口
+
+| 服务                       | 默认端口 |
+| -------------------------- | -------- |
+| 前端 (Vite)                | 5173     |
+| 后端 (Express + Socket.IO) | 3001     |
+
+## 环境变量
+
+## 服务端 (`packages/server/.env`)
+
+| 变量           | 说明                     | 默认值                  |
+| -------------- | ------------------------ | ----------------------- |
+| `PORT`         | 服务端口                 | `3001`                  |
+| `CLIENT_URL`   | 客户端地址（CORS）       | `http://localhost:5173` |
+| `CORS_ORIGINS` | 额外 CORS 源（逗号分隔） | 空                      |
+
+## 客户端 (Vite 环境变量)
+
+| 变量              | 说明     | 默认值                  |
+| ----------------- | -------- | ----------------------- |
+| `VITE_SERVER_URL` | 后端地址 | `http://localhost:3001` |
+
+## 构建
+
+```bash
+# 构建所有包
+pnpm build
+
+# 前端产物 → packages/client/dist/
+# 后端产物 → packages/server/dist/
+# shared 包无构建步骤，直接作为 TS 源码引用
+```
+
+## 添加 shadcn/ui 组件
+
+```bash
+cd packages/client
+npx shadcn@latest add <component-name>
+```
+
+组件会安装到 `src/components/ui/`。
+
+## 注意事项
+
+- 服务端数据全部存储在内存中，重启后丢失
+- 无数据库、无服务端持久化（客户端 Cookie 通过 localStorage 持久化）
+- 用户身份基于持久化 nanoid（localStorage）+ 昵称（无注册/登录账号系统）；`socket.id` 仅用于 Socket 传输层映射
+- 平台认证（网易云/酷狗 QR 扫码登录、QQ 手动 Cookie）用于 VIP 歌曲访问，Cookie 作用域为房间级。QR 登录状态码在 `shared/constants.ts` 中定义为 `QR_STATUS`（800-803），前后端共用，`QrLoginDialog` 无需区分平台
+- Auth Cookie 持久化策略：**只有用户主动登出（`useAuth.logout()`）才删除 localStorage 中的 cookie**。`useAuthSync` 在收到 `AUTH_SET_COOKIE_RESULT` 失败时（无论 `reason` 是 `expired` 还是 `error`）仅通过 toast 反馈，永远不删除 cookie，确保下次进房间时自动重试。`LoginSection` 在 localStorage 有 cookie 但服务端未确认时显示 "验证登录中…" 乐观状态
+- Auth Cookie 自动重发：`useRoomState` 在收到 `ROOM_STATE` 时自动重发 localStorage 中的 cookie。另外，当从 HomePage 导航到 RoomPage 时（`ROOM_STATE` 已被 HomePage 提前消费），`useRoomState` 挂载时检测到 room 已存在会立即补发 cookie，确保任何入口都能恢复认证
+- Auth Cookie 服务端验证双路径：`authController` 收到 `AUTH_SET_COOKIE` 时先检查 `hasCookie()`——如果 cookie 已在内存池中（刷新页面场景），走 **fast path** 跳过 API 调用直接返回成功；否则走 **slow path** 调用 `getUserInfo()` → `ncmApi.login_status()`。slow path 对**任何失败原因**（`expired` 或 `error`）都自动重试 1 次（间隔 1.5 秒），因为网易云 `login_status` API 可能对有效 cookie 临时返回空 profile
+- `shared` 包修改后前后端会自动热重载（pnpm workspace 链接）

docs/architecture/directory-structure.md

@@ -0,0 +1,219 @@
+# 目录结构
+
+## 根目录
+
+```
+music-together/
+├── packages/
+│   ├── client/          # React 前端
+│   ├── server/          # Node.js 后端
+│   └── shared/          # 共享类型与常量
+├── docs/                # 项目文档（含本文件 PROJECT_ARCHITECTURE.md）
+├── package.json         # 根 package（工作区编排）
+├── pnpm-workspace.yaml  # pnpm 工作区定义
+├── pnpm-lock.yaml
+├── README.md
+└── .gitignore
+```
+
+## packages/client/src/ — 前端源码
+
+```
+src/
+├── main.tsx                    # 入口：ReactDOM.createRoot
+├── App.tsx                     # 根组件：Router + Provider + ErrorBoundary + Suspense 懒加载
+├── index.css                   # 全局样式：Tailwind + 配色变量 + 自定义动画
+│
+├── pages/                      # 页面级组件
+│   ├── HomePage.tsx            #   大厅：创建/加入房间、房间列表
+│   ├── RoomPage.tsx            #   房间：播放器 + 聊天（桌面侧栏/移动端 Drawer） + 覆盖层弹窗
+│   └── NotFoundPage.tsx        #   404 页面
+│
+├── components/                 # UI 组件
+│   ├── Chat/
+│   │   ├── ChatMessage.tsx     #     单条消息（用户/系统）
+│   │   └── ChatPanel.tsx       #     聊天面板（消息列表 + 输入框）
+│   ├── Lobby/
+│   │   ├── CreateRoomDialog.tsx #    创建房间弹窗
+│   │   ├── NicknameDialog.tsx  #     设置昵称弹窗
+│   │   ├── PasswordDialog.tsx  #     输入房间密码弹窗
+│   │   ├── RoomCard.tsx        #     房间列表卡片
+│   │   ├── UserPopover.tsx     #     用户信息气泡
+│   │   ├── HeroSection.tsx     #     首页 Hero 标题区域
+│   │   ├── ActionCards.tsx     #     创建/加入房间卡片
+│   │   └── RoomListSection.tsx #     活跃房间列表区域
+│   ├── TrackListItem.tsx        #   共享曲目行渲染（序号+封面+标题VIP+歌手可点击+时长+isAdded 添加按钮，memo 优化）
+│   ├── VirtualTrackList.tsx     #   共享虚拟滚动曲目列表（@tanstack/react-virtual + 无限加载 + skeleton + 空态，forwardRef 暴露 scrollToTop）
+│   ├── Overlays/
+│   │   ├── QueueDrawer.tsx     #     播放队列抽屉（vaul Drawer，移动端底部/桌面端右侧）
+│   │   ├── SearchDialog.tsx    #     音乐搜索弹窗（VirtualTrackList 虚拟滚动 + 自动无限加载 + AbortController 竞态防护）
+│   │   ├── SettingsDialog.tsx  #     设置弹窗（壳，Tab 导航：房间/成员/账号/个人/外观，移动端 nav scrollbar-hide）
+│   │   └── Settings/
+│   │       ├── SettingRow.tsx              # 设置行共享组件
+│   │       ├── RoomSettingsSection.tsx     # 房间设置（名称、密码）
+│   │       ├── MembersSection.tsx          # 成员列表（角色管理）
+│   │       ├── PlatformAuthSection.tsx     # 平台账号认证（VIP Cookie，旧版，已被 PlatformHub 替代）
+│   │       ├── PlatformHub.tsx            # 平台中心（登录 + 歌单浏览 + 导入，替代 PlatformAuthSection）
+│   │       ├── LoginSection.tsx           # 精简版平台登录区域（PlatformHub 子组件）
+│   │       ├── PlaylistSection.tsx        # 歌单列表 + 手动输入（PlatformHub 子组件）
+│   │       ├── PlaylistDetail.tsx         # 歌单详情（header + VirtualTrackList + queueKeys/addedIds 去重 + 动态全部添加过滤重复）
+│   │       ├── ProfileSettingsSection.tsx  # 个人设置（昵称）
+│   │       ├── AppearanceSection.tsx       # 外观设置（歌词 + 背景 + 布局）
+│   │       ├── OtherSettingsSection.tsx    # 其他设置
+│   │       ├── ManualCookieDialog.tsx      # 手动输入 Cookie 弹窗
+│   │       └── QrLoginDialog.tsx           # 通用 QR 扫码登录弹窗（网易云 + 酷狗 + QQ 音乐）
+│   ├── Player/
+│   │   ├── constants.ts        #     共享动画常量（SPRING / LAYOUT_TRANSITION），NowPlaying 和 SongInfoBar 统一导入
+│   │   ├── AudioPlayer.tsx     #     主播放器布局（桌面：左右分栏；移动：双模式封面/歌词切换）
+│   │   ├── LyricDisplay.tsx    #     AMLL 歌词渲染（LRC 正则支持 [mm:ss] / [mm:ss.x] / [mm:ss.xx] / [mm:ss.xxx]）
+│   │   ├── NowPlaying.tsx      #     当前曲目展示（支持 compact 小封面横排模式 + layoutId 共享动画）
+│   │   ├── SongInfoBar.tsx     #     歌曲信息栏（标题/艺术家 + 音量/聊天按钮，竖屏模式自适应缩放）
+│   │   └── PlayerControls.tsx  #     进度条+播放控制+播放模式切换
+│   ├── Room/
+│   │   └── RoomHeader.tsx      #     房间头部（房间名/人数/连接状态；移动端 DropdownMenu 收纳设置/离开等操作）
+│   ├── Vote/
+│   │   └── VoteBanner.tsx      #     投票横幅（进行中的投票显示 + 投票按钮）
+│   ├── InteractionGate.tsx     #   浏览器交互解锁（点击后才能播放音频）
+│   └── ui/                     #   shadcn/ui 基础组件
+│       ├── avatar.tsx
+│       ├── badge.tsx
+│       ├── button.tsx
+│       ├── card.tsx
+│       ├── dialog.tsx
+│       ├── drawer.tsx
+│       ├── dropdown-menu.tsx
+│       ├── input.tsx
+│       ├── label.tsx
+│       ├── popover.tsx
+│       ├── resize-handle.tsx
+│       ├── scroll-area.tsx
+│       ├── select.tsx
+│       ├── separator.tsx
+│       ├── marquee-text.tsx
+│       ├── responsive-dialog.tsx
+│       ├── sheet.tsx
+│       ├── skeleton.tsx
+│       ├── slider.tsx
+│       ├── switch.tsx
+│       ├── tabs.tsx
+│       └── tooltip.tsx
+│
+├── hooks/                      # 自定义 Hooks
+│   ├── useSocketEvent.ts       #   通用 Socket 事件订阅工具 Hook（自动 on/off，ref 稳定）
+│   ├── usePlayer.ts            #   播放器主 hook（组合 useHowl + useLyric + usePlayerSync）
+│   ├── useHowl.ts              #   Howler.js 音频实例管理
+│   ├── useLyric.ts             #   歌词加载（TTML → 平台逐词 YRC/KRC → LRC）
+│   ├── usePlayerSync.ts        #   播放同步（Scheduled Execution + conductor 上报 + 周期性漂移校正）
+│   ├── useClockSync.ts         #   NTP 时钟同步 hook（校准客户端时钟与服务器对齐）
+│   ├── useRoom.ts              #   房间组合 hook（编排 5 个子 hook，对外 API 不变）
+│   ├── room/                   #   useRoom 子 hook（按职责拆分）
+│   │   ├── useRoomState.ts     #     ROOM_STATE / JOIN / LEFT / SETTINGS / ROLE_CHANGED / ERROR + 挂载时补发 cookie（覆盖 HomePage 提前消费 ROOM_STATE 的场景）
+│   │   ├── useChatSync.ts      #     CHAT_HISTORY / CHAT_MESSAGE
+│   │   ├── useQueueSync.ts     #     QUEUE_UPDATED
+│   │   ├── useAuthSync.ts      #     AUTH_SET_COOKIE_RESULT + localStorage 持久化（验证失败只做 toast 反馈，永不删除 cookie；删除权仅在 useAuth.logout）
+│   │   └── useConnectionGuard.ts #   disconnect → resetAllRoomState
+│   ├── useAuth.ts              #   平台认证 UI & Socket 事件
+│   ├── useVote.ts              #   投票（使用 useSocketEvent）
+│   ├── useChat.ts              #   聊天消息收发
+│   ├── useLobby.ts             #   大厅房间列表与操作（使用 useSocketEvent）
+│   ├── useQueue.ts             #   播放队列操作（含 addBatchTracks 批量添加）
+│   ├── usePlaylist.ts          #   歌单管理（用户歌单列表、分页曲目获取 + 无限加载、URL 解析、批量导入）
+│   ├── useIsMobile.ts          #   布局维度：orientation 检测（portrait=竖屏布局，landscape=横屏布局）
+│   ├── useHasHover.ts          #   交互维度：hover 能力检测（(hover: hover) 媒体查询，触控设备=false）
+│   ├── useContainerPortrait.ts #   容器宽高比检测（ResizeObserver，用于播放器横竖屏切换）
+│   └── useCoverWidth.ts        #   封面容器最小尺寸测量（约束信息栏/控件宽度与封面对齐）
+│
+├── stores/                     # Zustand 状态仓库
+│   ├── playerStore.ts          #   播放状态（currentTrack, isPlaying, volume 等）
+│   ├── roomStore.ts            #   房间状态（room, currentUser, users）
+│   ├── chatStore.ts            #   聊天（messages, unreadCount, isChatOpen）
+│   ├── lobbyStore.ts           #   大厅（rooms 列表, isLoading）
+│   └── settingsStore.ts        #   设置（歌词参数、背景参数，持久化到 localStorage）
+│
+├── providers/                  # React Context Provider
+│   ├── SocketProvider.tsx      #   Socket.IO 连接管理，提供 socket + isConnected + 断线/重连 Toast
+│   └── AbilityProvider.tsx     #   CASL 权限上下文（基于 currentUser.role）
+│
+└── lib/                        # 工具库
+    ├── config.ts               #   配置常量（SERVER_URL）
+    ├── constants.ts            #   命名常量（定时器、阈值、布局尺寸）
+    ├── clockSync.ts            #   NTP 时钟同步引擎（采样、offset 计算、getServerTime）
+    ├── resetStores.ts          #   全局 store 重置工具
+    ├── socket.ts               #   Socket.IO 客户端实例
+    ├── storage.ts              #   localStorage 封装（带类型校验）
+    ├── platform.ts             #   平台常量��PLATFORM_LABELS / PLATFORM_SHORT_LABELS / PLATFORM_COLORS / VIP_LABELS / 状态查找函数）
+    ├── format.ts               #   格式化工具（时间、文本等）
+    ├── audioUnlock.ts          #   浏览器音频自动播放解锁
+    └── utils.ts                #   cn() + trackKey() 等通用工具
+```
+
+## packages/server/src/ — 后端源码
+
+```
+src/
+├── index.ts                    # 入口：Express + HTTP + Socket.IO 服务启动与优雅关闭
+├── config.ts                   # 环境变量配置（PORT, CLIENT_URL, CORS）
+│
+├── controllers/                # 控制器：注册 Socket 事件处理器（薄编排层，不含业务逻辑）
+│   ├── index.ts                #   统一注册入口
+│   ├── roomController.ts       #   房间生命周期（创建/加入/离开/发现/设置/角色）
+│   ├── playerController.ts     #   播放控制（play/pause/seek/next/prev/sync/set_mode）+ NTP ping/pong
+│   ├── queueController.ts      #   队列管理（add/remove/reorder/clear）
+│   ├── chatController.ts       #   聊天消息（含限流反馈）
+│   ├── voteController.ts       #   投票系统（发起/投票/超时/执行，支持 set-mode / play-track / remove-track 投票）
+│   ├── authController.ts       #   平台认证（QR 登录/Cookie 管理/状态查询；支持网易云/酷狗/QQ 音乐三平台；策略模式——通过 AUTH_PROVIDERS 映射表统一处理；fast path: 内存池命中跳过 API；slow path: getUserInfo + 任意失败重试 1 次）
+│   └── playlistController.ts   #   歌单管理（获取用户歌单列表 via Socket，使用 getUserCookie 取请求者自己的 cookie，歌单私有）
+│
+├── services/                   # 服务层：业务逻辑
+│   ├── roomService.ts          #   房间 CRUD + 角色管理 + 加入校验（validateJoinRequest）
+│   ├── roomLifecycleService.ts #   房间生命周期定时器（空置删除）+ 防抖广播
+│   ├── playerService.ts        #   播放状态管理 + 流 URL 解析 + 切歌防抖 + 加入播放同步
+│   ├── queueService.ts         #   队列操作（reorder 保留未包含曲目防丢歌，getNextTrack 支持 4 种播放模式，clearQueue 清空，addBatchTracks 批量添加）
+│   ├── chatService.ts          #   聊天消息处理 + HTML 转义（含系统消息）
+│   ├── syncService.ts          #   播放位置估算工具（estimateCurrentTime）
+│   ├── musicProvider.ts        #   音乐数据聚合（3 层引用式 LRU 缓存 + 外部 API 超时保护 + 歌单分页获取；Netease 歌单使用 ncmApi.playlist_track_all 分块请求突破 1000 首限制，Kugou 用户歌单使用原生 API (get_other_list_file_nofilt) + Meting fallback，Tencent 使用 Meting 原始模式保留 VIP/时长字段）
+│   ├── authService.ts          #   Cookie 池管理（房间级作用域；getAnyCookie 用于 VIP 播放共享，getUserCookie 用于歌单等用户私有操作）
+│   ├── authProvider.ts         #   统一认证接口（AuthProvider 接口定义 + GetUserInfoResult/UserInfoData 共享类型 + AUTH_PROVIDERS 策略映射表）
+│   ├── neteaseAuthService.ts   #   网易云 API 认证（QR / Cookie 验证 / 用户信息 / 用户歌单列表；getUserInfo 返回 { ok, data? } | { ok: false, reason: 'expired' | 'error' } 区分过期与临时故障）
+│   ├── kugouAuthService.ts    #   酷狗 API 认证（QR 扫码登录 + VIP 检查 + 用户昵称(RSA) + 用户歌单列表 + 歌单歌曲获取；kugouRequest 含 HTTP 状态检查与 JSON 安全解析；自包含签名实现，状态码归一化为 800-803 与网易云统一）
+│   ├── tencentAuthService.ts  #   QQ 音乐认证（5 步 OAuth QR 扫码登录：ptqrshow/ptqrlogin/check_sig/authorize/QQLogin 换取 musickey；zzc 签名防风控；getUserInfo 获取昵称 + VIP 状态；getUserPlaylists 获取自建 + 收藏歌单；getPlaylistTracks 分页获取歌单歌曲）
+│   └── voteService.ts          #   投票状态管理
+│
+├── repositories/               # 数据仓库：内存状态与 SQLite 持久化
+│   ├── types.ts                #   接口定义（RoomRepository, ChatRepository）
+│   ├── roomRepository.ts       #   房间数据 + Socket 映射 + per-socket RTT + roomToSockets 反向索引（Map<string, RoomData>）
+│   ├── chatRepository.ts       #   聊天记录（内存最多 200 条；永久房间同步持久化到 SQLite）
+│   └── audioProxyPolicyRepository.ts # 全局酷狗音频代理策略（SQLite server_settings）
+│
+├── middleware/                  # Socket.IO 中间件
+│   ├── types.ts                #   TypedServer, TypedSocket, HandlerContext
+│   ├── withRoom.ts             #   房间成员身份校验
+│   ├── withControl.ts          #   操作权限校验（包装 withRoom）
+│   └── socketRateLimiter.ts    #   Socket 事件速率限制（per-socket，10次/5秒）+ 断连清理（cleanupSocketRateLimit）
+│
+├── routes/                     # Express REST 路由
+│   ├── music.ts                #   GET /api/music/search|url|lyric|cover|playlist|ttml（统一 validated() 路由包装器消除重复 try/catch + Zod 模式）
+│   └── rooms.ts                #   GET /api/rooms/:roomId/check（房间预检）
+│
+├── types/
+│   └── meting.d.ts             #   @meting/core 类型声明
+│
+└── utils/
+    ├── logger.ts               #   结构化日志（基于 pino，info/warn/error + JSON context）
+    └── roomUtils.ts            #   房间数据转换纯函数（toPublicRoomState / toPublicRoomStateForOwner，密码仅 owner 可见）
+```
+
+## packages/shared/src/ — 共享代码
+
+```
+src/
+├── index.ts           # 统一导出（re-export 所有模块）
+├── types.ts           # 核心类型：ERROR_CODE, Track, RoomState, PlayState, ScheduledPlayState, PlayMode, AudioQuality, User, ChatMessage, VoteAction (incl. play-track, remove-track), VoteState, RoomListItem, Playlist
+├── events.ts          # 事件常量：EVENTS 对象（room:*, player:*, queue:*, chat:*, auth:*, ntp:*, playlist:*）
+├── socket-types.ts    # Socket.IO 类型：ServerToClientEvents, ClientToServerEvents
+├── constants.ts       # 业务常量：LIMITS（长度/数量限制）, TIMING（同步间隔/宽限期）, NTP（时钟同步参数）, QR_STATUS（扫码状态码）, QR_TIMING（轮询间隔）
+├── schemas.ts         # Zod 验证 schema
+└── abilities.ts       # CASL 权限定义（Actions incl. set-mode, Subjects, defineAbilityFor）
+```
+
+---

docs/architecture/ui-design.md

@@ -0,0 +1,150 @@
+# UI 设计规范
+
+## 组件库
+
+- **shadcn/ui**：`new-york` 风格变体，`neutral` 基色
+- **配置**：非 RSC（`"rsc": false`），使用 CSS 变量，Lucide 图标
+- **安装路径**：`@/components/ui/`，工具函数 `@/lib/utils`
+
+## 颜色系统
+
+使用 **oklch 色彩空间**，单一深色主题，CSS 变量直接定义在 `:root`（无亮/暗切换）：
+
+```css
+:root {
+  --background: oklch(0.178 0.005 265); /* 深蓝灰 */
+  --foreground: oklch(0.985 0 0); /* 近白 */
+  --primary: oklch(0.922 0 0); /* 亮色主色 */
+  --card: oklch(0.235 0.008 265); /* 微蓝灰卡片 */
+  --accent: oklch(0.35 0.008 265); /* 强调色 */
+  /* ... */
+}
+```
+
+## 字体
+
+- **主字体**：Plus Jakarta Sans（通过 `@fontsource/plus-jakarta-sans` 本地打包）
+- **回退**：system-ui, -apple-system, sans-serif
+
+## 圆角
+
+基准值 `--radius: 0.625rem`，其他圆角通过计算派生：
+
+```css
+--radius-sm: calc(var(--radius) - 4px); /* 小 */
+--radius-md: calc(var(--radius) - 2px); /* 中 */
+--radius-lg: var(--radius); /* 标准 */
+--radius-xl: calc(var(--radius) + 4px); /* 大 */
+```
+
+## 图标
+
+使用 **lucide-react**，按需导入：
+
+```typescript
+import { Play, Pause, SkipForward, Volume2 } from 'lucide-react'
+```
+
+## 动画
+
+- **motion (Framer Motion)**：组件进入/退出动画、列表动画
+- **tw-animate-css**：Tailwind 动画预设类
+- **自定义动画**：`float` 关键帧（6s 缓动上下浮动）、`marquee` 关键帧（文本溢出自动滚动）
+
+```css
+@keyframes float {
+  0%,
+  100% {
+    transform: translateY(0);
+  }
+  50% {
+    transform: translateY(-6px);
+  }
+}
+
+@keyframes marquee {
+  0%,
+  15% {
+    transform: translateX(0);
+  }
+  45%,
+  55% {
+    transform: translateX(var(--marquee-distance));
+  }
+  85%,
+  100% {
+    transform: translateX(0);
+  }
+}
+```
+
+## MarqueeText 组件
+
+`marquee-text.tsx` 通用文本溢出自动滚动组件，用于播放列表项、SongInfoBar、NowPlaying compact 模式等场景：
+
+- 使用 `ResizeObserver` 检测文本是否溢出容器（`scrollWidth > clientWidth`）
+- 溢出时通过 CSS `translateX` 动画实现 pause-scroll-pause 循环（GPU 加速）
+- 动画时长根据溢出距离动态计算（`Math.max(5, 4 + overflow / 30)`），长文本滚动更慢
+- 未溢出时无动画，等同普通文本
+- 遵循 `prefers-reduced-motion` 系统偏好（已有全局 `animation-duration: 0.01ms` 降级）
+
+## 滚动条
+
+自定义 WebKit 滚动条：6px 宽/高，透明轨道，半透明滑块。Firefox 使用 `scrollbar-width: thin`。`.scrollbar-hide` 工具类隐藏滚动条但保持滚动功能（用于移动端设置导航栏等）。
+
+## 歌词渲染
+
+- **AMLL** (`@applemusic-like-lyrics/react`)：Apple Music 风格逐行歌词动画
+- **逐词来源**：TTML 在线库（网易云/QQ）、平台原生 YRC（网易云）、平台原生 KRC（酷狗，服务端解析后以 `wordByWord` 返回）
+- **PixiJS 背景**：`BackgroundRender` 组件使用 PixiJS 渲染动态专辑封面背景
+- 歌词设置可调：对齐锚点、弹簧动画、模糊效果、缩放效果、字重、字体大小、翻译字体大小
+
+## 样式工具函数
+
+```typescript
+// cn() — 条件 class 合并（clsx + tailwind-merge）
+import { cn } from '@/lib/utils'
+
+<div className={cn('base-class', isActive && 'active-class')} />
+```
+
+## Toast 通知
+
+使用 **sonner**，定位在顶部居中：
+
+```typescript
+<Toaster position="top-center" richColors />
+```
+
+## 触控与 Hover 双模式
+
+项目将**布局**和**交互**解耦为两个正交维度：
+
+| Hook            | 维度 | 媒体查询                  | 控制内容                                      |
+| --------------- | ---- | ------------------------- | --------------------------------------------- |
+| `useIsMobile()` | 布局 | `(orientation: portrait)` | Drawer 方向、面板高度、Dialog vs Drawer       |
+| `useHasHover()` | 交互 | `(hover: hover)`          | hover 工具栏 vs tap 展开、Slider thumb 可见性 |
+
+横屏手机 = `isMobile: false`（使用桌面布局）+ `hasHover: false`（使用触控交互）。
+
+- **Slider Thumb**：进度条 Thumb 默认透明，桌面端 `group-hover` 显示，触控设备通过 `focus:opacity-100` 在触摸拖拽时显示
+- **触控目标尺寸**：所有可点击按钮在移动端通过 `min-h-11 min-w-11`（44px）扩大触控热区，桌面端 `sm:min-h-0 sm:min-w-0` 还原视觉尺寸。涉及 QueueDrawer 工具栏、VoteBanner、RoomHeader
+- **QueueDrawer tap-to-expand**：触控设备（`isTouch = !hasHover`）点击列表项展开操作工具栏；桌面端通过 `group-hover` 显示工具栏。两种模式在横屏手机上都能正确工作
+
+## 封面图片 onError 回退
+
+- **NowPlaying**：使用 `coverError` state 追踪加载失败，切歌时重置；失败后回退到 `Disc3` 占位图标
+- **QueueDrawer**：`<img>` 的 `onError` 隐藏图片并显示 `Music` 占位图标（始终渲染占位 div，通过 `hidden` class 切换）
+
+## 音频加载失败重试
+
+`useHowl` 的 `onloaderror` 处理：
+
+- 首次失败自动重试一次（`retryRef` flag + `howl.load()`）
+- 重试仍失败则 toast 显示歌曲名（`trackTitleRef`）并跳到下一首
+- `onloaderror` 开头有 stale guard（`howlRef.current !== howl`），防止旧 Howl 实例的重试回调影响新曲
+- `loadTrack` 时重置 retry flag 和歌曲名 ref，并清理 `playErrorTimerRef`（防止上一首的 play-error 超时跳过新曲）
+- `onload` 和 `onplay` 中对 `howl.duration()` 做 `Number.isFinite` + `> 0` 校验，防止流式加载时无效 duration 写入 store
+- `queueAddSchema` 对 `duration` 做 `z.number().finite().nonnegative()` 校验，从数据入口杜绝无效时长
+
+---

package.json

@@ -0,0 +1,30 @@
+{
+  "name": "music-together",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Online music listening together platform",
+  "scripts": {
+    "predev": "kill-port 3001 --silent || true",
+    "dev": "concurrently --kill-others --names server,client --prefix-colors blue,green \"pnpm run dev:server\" \"pnpm run dev:client\"",
+    "dev:client": "pnpm --filter @music-together/client dev",
+    "dev:server": "pnpm --filter @music-together/server dev",
+    "build": "pnpm -r run build && node scripts/prepare-production.mjs",
+    "start": "node packages/server/dist/index.js",
+    "format": "prettier --write \"packages/*/src/**/*.{ts,tsx}\" \"packages/shared/src/**/*.ts\""
+  },
+  "keywords": [],
+  "author": "",
+  "license": "AGPL-3.0",
+  "packageManager": "pnpm@10.29.2",
+  "devDependencies": {
+    "concurrently": "^9.2.1",
+    "kill-port": "^2.0.1",
+    "prettier": "^3.8.1"
+  },
+  "workspaces": [
+    "packages/*"
+  ],
+  "dependencies": {
+    "semver": "^7.8.5"
+  }
+}

packages/client/.env.development

@@ -0,0 +1,2 @@
+# 开发环境：前端 5173、后端 3001，需要显式指定后端地址
+VITE_SERVER_URL=http://localhost:3001

packages/client/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

packages/client/README.md

@@ -0,0 +1,73 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+
+## React Compiler
+
+The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+
+```js
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+
+      // Remove tseslint.configs.recommended and replace with this
+      tseslint.configs.recommendedTypeChecked,
+      // Alternatively, use this for stricter rules
+      tseslint.configs.strictTypeChecked,
+      // Optionally, add this for stylistic rules
+      tseslint.configs.stylisticTypeChecked,
+
+      // Other configs...
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x'
+import reactDom from 'eslint-plugin-react-dom'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+      // Enable lint rules for React
+      reactX.configs['recommended-typescript'],
+      // Enable lint rules for React DOM
+      reactDom.configs.recommended,
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```

packages/client/components.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/index.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "rtl": false,
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "registries": {}
+}

packages/client/eslint.config.js

@@ -0,0 +1,23 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      globals: globals.browser,
+    },
+  },
+])

packages/client/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/logo.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="color-scheme" content="dark" />
+    <title>Music Together - 一起听歌</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

packages/client/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@music-together/client",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "typecheck": "tsc -b --noEmit",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@applemusic-like-lyrics/core": "^0.2.0",
+    "@applemusic-like-lyrics/lyric": "^0.3.0",
+    "@applemusic-like-lyrics/react": "^0.2.0",
+    "@casl/react": "^5.0.1",
+    "@fontsource/plus-jakarta-sans": "^5.3.0",
+    "@music-together/shared": "workspace:*",
+    "@pixi/app": "^7.4.3",
+    "@pixi/core": "^7.4.3",
+    "@pixi/display": "^7.4.3",
+    "@pixi/filter-blur": "^7.4.3",
+    "@pixi/filter-bulge-pinch": "^5.1.1",
+    "@pixi/filter-color-matrix": "^7.4.3",
+    "@pixi/sprite": "^7.4.3",
+    "@soundtouchjs/audio-worklet": "2.1.0",
+    "@tanstack/react-virtual": "^3.13.18",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "dayjs": "^1.11.19",
+    "howler": "^2.2.4",
+    "jss": "^10.10.0",
+    "jss-preset-default": "^10.10.0",
+    "lucide-react": "^0.563.0",
+    "motion": "^12.34.0",
+    "nanoid": "^5.1.6",
+    "radix-ui": "^1.4.3",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-error-boundary": "^6.1.0",
+    "react-router-dom": "^7.13.0",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.4.0",
+    "vaul": "^1.1.2",
+    "zustand": "^5.0.11"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@tailwindcss/vite": "^4.1.18",
+    "@types/howler": "^2.2.12",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.1",
+    "eslint": "^9.39.1",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.24",
+    "globals": "^16.5.0",
+    "shadcn": "^3.8.4",
+    "tailwindcss": "^4.1.18",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.48.0",
+    "vite": "^7.3.1",
+    "vite-plugin-wasm": "^3.5.0"
+  }
+}

packages/client/src/App.tsx

@@ -0,0 +1,92 @@
+import { lazy, Suspense } from 'react'
+import { ErrorBoundary } from 'react-error-boundary'
+import { TooltipProvider } from '@/components/ui/tooltip'
+import { Button } from '@/components/ui/button'
+import { SocketProvider } from '@/providers/SocketProvider'
+import HomePage from '@/pages/HomePage'
+import { BrowserRouter, Route, Routes, useLocation, useNavigate } from 'react-router-dom'
+import { Toaster } from 'sonner'
+import { AnimatePresence } from 'motion/react'
+import { AlertTriangle } from 'lucide-react'
+
+// Lazy-loaded routes (keep HomePage sync for fast first paint)
+const RoomPage = lazy(() => import('@/pages/RoomPage'))
+const NotFoundPage = lazy(() => import('@/pages/NotFoundPage'))
+
+function ErrorFallback({ error, resetErrorBoundary }: { error: unknown; resetErrorBoundary: () => void }) {
+  const message = error instanceof Error ? error.message : '应用遇到了意外错误'
+  return (
+    <div className="flex min-h-screen items-center justify-center p-6">
+      <div className="flex max-w-md flex-col items-center gap-4 rounded-xl border bg-card p-8 text-center shadow-lg">
+        <AlertTriangle className="h-12 w-12 text-destructive" />
+        <h2 className="text-xl font-semibold">出了点问题</h2>
+        <p className="text-sm text-muted-foreground">{message}</p>
+        <Button onClick={resetErrorBoundary} variant="default">
+          重试
+        </Button>
+      </div>
+    </div>
+  )
+}
+
+function RouteFallback() {
+  return (
+    <div className="flex min-h-screen items-center justify-center">
+      <div className="h-8 w-8 animate-spin rounded-full border-4 border-primary border-t-transparent" />
+    </div>
+  )
+}
+
+/** Route-level ErrorBoundary: navigates home on reset instead of full reload */
+function RouteErrorBoundary({ children }: { children: React.ReactNode }) {
+  const navigate = useNavigate()
+  return (
+    <ErrorBoundary FallbackComponent={ErrorFallback} onReset={() => navigate('/', { replace: true })}>
+      {children}
+    </ErrorBoundary>
+  )
+}
+
+function AnimatedRoutes() {
+  const location = useLocation()
+  return (
+    <AnimatePresence mode="wait">
+      <Suspense fallback={<RouteFallback />}>
+        <Routes location={location} key={location.pathname}>
+          <Route
+            path="/"
+            element={
+              <RouteErrorBoundary>
+                <HomePage />
+              </RouteErrorBoundary>
+            }
+          />
+          <Route
+            path="/room/:roomId"
+            element={
+              <RouteErrorBoundary>
+                <RoomPage />
+              </RouteErrorBoundary>
+            }
+          />
+          <Route path="*" element={<NotFoundPage />} />
+        </Routes>
+      </Suspense>
+    </AnimatePresence>
+  )
+}
+
+export default function App() {
+  return (
+    <BrowserRouter>
+      <SocketProvider>
+        <TooltipProvider>
+          <ErrorBoundary FallbackComponent={ErrorFallback} onReset={() => window.location.reload()}>
+            <AnimatedRoutes />
+          </ErrorBoundary>
+          <Toaster position="top-center" richColors />
+        </TooltipProvider>
+      </SocketProvider>
+    </BrowserRouter>
+  )
+}

packages/client/src/components/Chat/ChatMessage.tsx

@@ -0,0 +1,46 @@
+import { memo } from 'react'
+import dayjs from 'dayjs'
+import { motion } from 'motion/react'
+import type { ChatMessage as ChatMessageType } from '@music-together/shared'
+import { cn } from '@/lib/utils'
+
+interface ChatMessageProps {
+  message: ChatMessageType
+  isOwnMessage: boolean
+}
+
+export const ChatMessage = memo(function ChatMessage({ message, isOwnMessage }: ChatMessageProps) {
+  if (message.type === 'system') {
+    return (
+      <motion.div
+        initial={{ opacity: 0 }}
+        animate={{ opacity: 1 }}
+        className="py-1.5 text-center text-xs text-muted-foreground/50"
+      >
+        {message.content}
+      </motion.div>
+    )
+  }
+
+  return (
+    <motion.div
+      initial={{ opacity: 0, y: 10, scale: 0.96 }}
+      animate={{ opacity: 1, y: 0, scale: 1 }}
+      transition={{ type: 'spring', stiffness: 400, damping: 30 }}
+      className={cn('flex flex-col gap-0.5 py-1.5', isOwnMessage ? 'items-end' : 'items-start')}
+    >
+      <div className="flex items-center gap-2">
+        <span className="text-xs font-medium text-muted-foreground">{message.nickname}</span>
+        <span className="text-xs text-muted-foreground/40">{dayjs(message.timestamp).format('HH:mm')}</span>
+      </div>
+      <div
+        className={cn(
+          'max-w-[80%] rounded-xl px-3 py-2 text-sm break-words',
+          isOwnMessage ? 'bg-primary text-primary-foreground' : 'bg-secondary text-secondary-foreground',
+        )}
+      >
+        {message.content}
+      </div>
+    </motion.div>
+  )
+})

packages/client/src/components/Chat/ChatPanel.tsx

@@ -0,0 +1,141 @@
+import { useState, useRef, useEffect, useCallback } from 'react'
+import { ArrowDown, MessageSquare, PanelRightClose, Send } from 'lucide-react'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+import { ChatMessage } from './ChatMessage'
+import { useChatStore } from '@/stores/chatStore'
+import { useRoomStore } from '@/stores/roomStore'
+import { useChat } from '@/hooks/useChat'
+
+/** Threshold (px) to consider the user "at the bottom" of the scroll container */
+const SCROLL_BOTTOM_THRESHOLD = 80
+
+interface ChatPanelProps {
+  onCollapse?: () => void
+}
+
+export function ChatPanel({ onCollapse }: ChatPanelProps) {
+  const [input, setInput] = useState('')
+  const [showNewMsgHint, setShowNewMsgHint] = useState(false)
+  const messagesEndRef = useRef<HTMLDivElement>(null)
+  const scrollContainerRef = useRef<HTMLDivElement>(null)
+  const isAtBottomRef = useRef(true)
+  const messages = useChatStore((s) => s.messages)
+  const currentUser = useRoomStore((s) => s.currentUser)
+  const { sendMessage } = useChat()
+
+  // Track whether the user has scrolled to the bottom
+  const handleScroll = useCallback(() => {
+    const el = scrollContainerRef.current
+    if (!el) return
+    const atBottom = el.scrollHeight - el.scrollTop - el.clientHeight < SCROLL_BOTTOM_THRESHOLD
+    isAtBottomRef.current = atBottom
+    if (atBottom) setShowNewMsgHint(false)
+  }, [])
+
+  // Smart auto-scroll: only scroll to bottom if user was already at the bottom
+  useEffect(() => {
+    const frame = requestAnimationFrame(() => {
+      if (isAtBottomRef.current) {
+        messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' })
+      } else {
+        setShowNewMsgHint(true)
+      }
+    })
+    return () => cancelAnimationFrame(frame)
+  }, [messages])
+
+  const scrollToBottom = useCallback(() => {
+    messagesEndRef.current?.scrollIntoView({ behavior: 'smooth' })
+    setShowNewMsgHint(false)
+  }, [])
+
+  const handleSend = () => {
+    if (!input.trim()) return
+    sendMessage(input)
+    setInput('')
+  }
+
+  return (
+    <div className="flex min-h-0 w-full flex-1 flex-col border-l border-border/50 bg-background/60 backdrop-blur-sm">
+      {/* Header */}
+      <div className="relative flex shrink-0 items-center gap-2 border-b border-border/50 px-4 py-3">
+        <MessageSquare className="h-4 w-4 text-muted-foreground" />
+        {onCollapse && (
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button
+                type="button"
+                variant="ghost"
+                size="icon-xs"
+                className="absolute right-3"
+                onClick={onCollapse}
+                aria-label="收起聊天"
+              >
+                <PanelRightClose className="h-4 w-4" />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent>收起聊天</TooltipContent>
+          </Tooltip>
+        )}
+        <span className="text-sm font-medium">聊天</span>
+      </div>
+
+      {/* Messages */}
+      <div className="relative min-h-0 flex-1">
+        <div
+          ref={scrollContainerRef}
+          onScroll={handleScroll}
+          className="absolute inset-0 overflow-y-auto px-3"
+          aria-live="polite"
+          aria-label="聊天消息"
+        >
+          <div className="py-3">
+            {messages.length === 0 ? (
+              <p className="text-center text-sm text-muted-foreground/30 py-8">还没有消息，开始聊天吧~</p>
+            ) : (
+              messages.map((msg) => (
+                <ChatMessage key={msg.id} message={msg} isOwnMessage={msg.userId === currentUser?.id} />
+              ))
+            )}
+            <div ref={messagesEndRef} />
+          </div>
+        </div>
+
+        {/* New message hint */}
+        {showNewMsgHint && (
+          <Button
+            variant="secondary"
+            size="sm"
+            className="absolute bottom-2 left-1/2 z-10 -translate-x-1/2 gap-1 rounded-full shadow-md"
+            onClick={scrollToBottom}
+          >
+            <ArrowDown className="h-3.5 w-3.5" />
+            新消息
+          </Button>
+        )}
+      </div>
+
+      {/* Input */}
+      <div className="flex shrink-0 gap-2 border-t border-border/50 px-3 py-3">
+        <Input
+          placeholder="输入消息..."
+          value={input}
+          onChange={(e) => setInput(e.target.value)}
+          onKeyDown={(e) => e.key === 'Enter' && handleSend()}
+          className="flex-1"
+          aria-label="输入聊天消息"
+        />
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <Button size="icon" variant="secondary" onClick={handleSend} disabled={!input.trim()} aria-label="发送消息">
+              <Send className="h-4 w-4" />
+            </Button>
+          </TooltipTrigger>
+          <TooltipContent>发送</TooltipContent>
+        </Tooltip>
+      </div>
+    </div>
+  )
+}

packages/client/src/components/GlobalBackground.tsx

@@ -0,0 +1,121 @@
+import { useEffect, useState, type CSSProperties } from 'react'
+import { EVENTS, type GlobalBackgroundSettings } from '@music-together/shared'
+import { SERVER_URL } from '@/lib/config'
+import { useSocketEvent } from '@/hooks/useSocketEvent'
+import { useGlobalBackgroundStore } from '@/stores/globalBackgroundStore'
+
+function resolveBackgroundUrl(backgroundUrl: string | null): string | undefined {
+  if (!backgroundUrl) return undefined
+  return backgroundUrl.startsWith('/uploads/') ? `${SERVER_URL}${backgroundUrl}` : backgroundUrl
+}
+
+export function GlobalBackground() {
+  const backgroundUrl = useGlobalBackgroundStore((state) => state.backgroundUrl)
+  const glassOverlay = useGlobalBackgroundStore((state) => state.glassOverlay)
+  const colorPreset = useGlobalBackgroundStore((state) => state.colorPreset)
+  const backgroundBrightness = useGlobalBackgroundStore((state) => state.backgroundBrightness)
+  const autoTint = useGlobalBackgroundStore((state) => state.autoTint)
+  const setBackgroundUrl = useGlobalBackgroundStore((state) => state.setBackgroundUrl)
+  const setGlassOverlay = useGlobalBackgroundStore((state) => state.setGlassOverlay)
+  const setColorPreset = useGlobalBackgroundStore((state) => state.setColorPreset)
+  const setBackgroundBrightness = useGlobalBackgroundStore((state) => state.setBackgroundBrightness)
+  const setAutoTint = useGlobalBackgroundStore((state) => state.setAutoTint)
+  const [tint, setTint] = useState<string | null>(null)
+
+  useEffect(() => {
+    let cancelled = false
+    void fetch(`${SERVER_URL}/api/settings/background`, { credentials: 'include' })
+      .then(async (response) => {
+        if (!response.ok) throw new Error(`Request failed: ${response.status}`)
+        return (await response.json()) as GlobalBackgroundSettings
+      })
+      .then((settings) => {
+        if (!cancelled) {
+          setBackgroundUrl(settings.backgroundUrl)
+          setGlassOverlay(settings.glassOverlay)
+          setColorPreset(settings.colorPreset)
+          setBackgroundBrightness(settings.backgroundBrightness)
+          setAutoTint(settings.autoTint)
+        }
+      })
+      .catch(() => {
+        // The default theme remains usable if a server is temporarily unavailable.
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [setBackgroundUrl, setGlassOverlay, setColorPreset, setBackgroundBrightness, setAutoTint])
+
+  useSocketEvent(EVENTS.SERVER_GLOBAL_BACKGROUND, (settings) => {
+    setBackgroundUrl(settings.backgroundUrl)
+    setGlassOverlay(settings.glassOverlay)
+    setColorPreset(settings.colorPreset)
+    setBackgroundBrightness(settings.backgroundBrightness)
+    setAutoTint(settings.autoTint)
+  })
+
+  useEffect(() => {
+    document.documentElement.dataset.colorPreset = colorPreset
+  }, [colorPreset])
+
+  const resolvedUrl = resolveBackgroundUrl(backgroundUrl)
+
+  useEffect(() => {
+    if (!autoTint || !resolvedUrl) {
+      setTint(null)
+      return
+    }
+
+    let cancelled = false
+    const image = new Image()
+    image.crossOrigin = 'anonymous'
+    image.onload = () => {
+      try {
+        const canvas = document.createElement('canvas')
+        canvas.width = 32
+        canvas.height = 32
+        const context = canvas.getContext('2d', { willReadFrequently: true })
+        if (!context) return
+        context.drawImage(image, 0, 0, 32, 32)
+        const pixels = context.getImageData(0, 0, 32, 32).data
+        let red = 0
+        let green = 0
+        let blue = 0
+        let count = 0
+        for (let index = 0; index < pixels.length; index += 4) {
+          if (pixels[index + 3] < 32) continue
+          red += pixels[index]!
+          green += pixels[index + 1]!
+          blue += pixels[index + 2]!
+          count += 1
+        }
+        if (!cancelled && count > 0) {
+          setTint(`rgb(${Math.round(red / count)} ${Math.round(green / count)} ${Math.round(blue / count)})`)
+        }
+      } catch {
+        if (!cancelled) setTint(null)
+      }
+    }
+    image.onerror = () => {
+      if (!cancelled) setTint(null)
+    }
+    image.src = resolvedUrl
+    return () => {
+      cancelled = true
+    }
+  }, [autoTint, resolvedUrl])
+
+  if (!resolvedUrl) return null
+
+  return (
+    <div
+      className={glassOverlay ? 'mt-global-background mt-global-background-glass' : 'mt-global-background'}
+      aria-hidden="true"
+      style={{
+        backgroundImage: `url("${resolvedUrl}")`,
+        '--mt-background-brightness': backgroundBrightness / 100,
+        '--mt-auto-tint': tint ?? 'transparent',
+      } as CSSProperties}
+    />
+  )
+}

packages/client/src/components/InteractionGate.tsx

@@ -0,0 +1,113 @@
+import { motion, useReducedMotion } from 'motion/react'
+import { Headphones, Lock, UserRound } from 'lucide-react'
+import { LIMITS } from '@music-together/shared'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import { Label } from '@/components/ui/label'
+import { useState } from 'react'
+import { storage } from '@/lib/storage'
+
+interface InteractionGateProps {
+  onStart: (password?: string) => void
+  roomName?: string
+  hasPassword?: boolean
+  passwordError?: string | null
+}
+
+export function InteractionGate({ onStart, roomName, hasPassword, passwordError }: InteractionGateProps) {
+  const prefersReducedMotion = useReducedMotion()
+  const [password, setPassword] = useState('')
+
+  const savedNickname = storage.getNickname()
+  const needsNickname = !savedNickname
+  const [nickname, setNickname] = useState(savedNickname)
+
+  const canStart = (!needsNickname || nickname.trim().length > 0) && (!hasPassword || password.trim().length > 0)
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault()
+    if (!canStart) return
+    if (needsNickname) {
+      storage.setNickname(nickname.trim())
+    }
+    onStart(hasPassword ? password.trim() : undefined)
+  }
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center bg-background px-4">
+      <motion.div
+        initial={{ opacity: 0, scale: 0.9 }}
+        animate={{ opacity: 1, scale: 1 }}
+        transition={{ type: 'spring', stiffness: 300, damping: 25 }}
+        className="flex w-full max-w-sm flex-col items-center gap-6 rounded-2xl border border-border bg-card p-10 shadow-lg"
+      >
+        <motion.div
+          animate={prefersReducedMotion ? {} : { rotate: [0, 5, -5, 0] }}
+          transition={prefersReducedMotion ? {} : { duration: 4, repeat: Infinity, ease: 'easeInOut' }}
+        >
+          <Headphones className="h-16 w-16 text-primary" />
+        </motion.div>
+
+        <div className="flex flex-col items-center gap-1.5">
+          <h2 className="text-xl font-semibold">准备就绪</h2>
+          {roomName ? (
+            <p className="text-sm text-muted-foreground">即将加入「{roomName}」</p>
+          ) : (
+            <p className="text-sm text-muted-foreground">点击开始，与房间好友一起听歌</p>
+          )}
+        </div>
+
+        <form onSubmit={handleSubmit} className="flex w-full flex-col gap-4">
+          {needsNickname && (
+            <div className="flex flex-col gap-2">
+              <Label htmlFor="gate-nickname" className="flex items-center gap-1.5 text-xs text-muted-foreground">
+                <UserRound className="h-3.5 w-3.5" />
+                <span>设置你的昵称</span>
+              </Label>
+              <Input
+                id="gate-nickname"
+                placeholder="你的昵称..."
+                value={nickname}
+                onChange={(e) => setNickname(e.target.value)}
+                maxLength={LIMITS.NICKNAME_MAX_LENGTH}
+                autoFocus
+              />
+            </div>
+          )}
+
+          {hasPassword && (
+            <div className="flex flex-col gap-2">
+              <div className="flex items-center gap-1.5 text-xs text-muted-foreground">
+                <Lock className="h-3.5 w-3.5" />
+                <span>该房间需要密码</span>
+              </div>
+              <motion.div animate={passwordError ? { x: [-8, 8, -6, 6, -3, 3, 0] } : {}} transition={{ duration: 0.5 }}>
+                <Input
+                  type="password"
+                  placeholder="输入房间密码..."
+                  value={password}
+                  onChange={(e) => setPassword(e.target.value)}
+                  autoFocus={!needsNickname}
+                  className={passwordError ? 'border-destructive' : ''}
+                />
+                {passwordError && (
+                  <motion.p
+                    initial={{ opacity: 0, y: -4 }}
+                    animate={{ opacity: 1, y: 0 }}
+                    className="mt-1.5 text-xs text-destructive"
+                  >
+                    {passwordError}
+                  </motion.p>
+                )}
+              </motion.div>
+            </div>
+          )}
+
+          <Button type="submit" size="lg" className="w-full" disabled={!canStart} aria-label="开始收听">
+            开始收听
+          </Button>
+        </form>
+      </motion.div>
+    </div>
+  )
+}

packages/client/src/components/Lobby/ActionCards.tsx

@@ -0,0 +1,71 @@
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import { Home, LogIn } from 'lucide-react'
+import { motion } from 'motion/react'
+
+interface ActionCardsProps {
+  directRoomId: string
+  onDirectRoomIdChange: (value: string) => void
+  onCreateClick: () => void
+  onDirectJoin: () => void
+  actionLoading: boolean
+}
+
+export function ActionCards({
+  directRoomId,
+  onDirectRoomIdChange,
+  onCreateClick,
+  onDirectJoin,
+  actionLoading,
+}: ActionCardsProps) {
+  return (
+    <motion.div
+      initial={{ opacity: 0, y: 10 }}
+      animate={{ opacity: 1, y: 0 }}
+      transition={{ duration: 0.4, delay: 0.15 }}
+      className="mb-10 grid gap-4 sm:grid-cols-2"
+    >
+      {/* Create room card */}
+      <div className="mt-card flex flex-col justify-between rounded-2xl p-5">
+        <div className="mb-4">
+          <div className="mb-2 flex items-center gap-2">
+            <div className="mt-icon-box h-9 w-9">
+              <Home className="h-4 w-4 text-primary" />
+            </div>
+            <h2 className="text-base font-semibold text-foreground">创建房间</h2>
+          </div>
+          <p className="text-xs text-muted-foreground">新建一个房间，分享房间号邀请朋友加入</p>
+        </div>
+        <Button onClick={onCreateClick} className="w-full">
+          <Home className="mr-2 h-4 w-4" />
+          创建房间
+        </Button>
+      </div>
+
+      {/* Join room card */}
+      <div className="mt-card flex flex-col justify-between rounded-2xl p-5">
+        <div className="mb-4">
+          <div className="mb-2 flex items-center gap-2">
+            <div className="mt-icon-box h-9 w-9">
+              <LogIn className="h-4 w-4 text-primary" />
+            </div>
+            <h2 className="text-base font-semibold text-foreground">加入房间</h2>
+          </div>
+          <p className="text-xs text-muted-foreground">输入房间号直接加入已有房间</p>
+        </div>
+        <div className="flex gap-2">
+          <Input
+            placeholder="输入房间号..."
+            value={directRoomId}
+            onChange={(e) => onDirectRoomIdChange(e.target.value)}
+            onKeyDown={(e) => e.key === 'Enter' && onDirectJoin()}
+            className="flex-1"
+          />
+          <Button variant="secondary" onClick={onDirectJoin} disabled={actionLoading}>
+            加入
+          </Button>
+        </div>
+      </div>
+    </motion.div>
+  )
+}

packages/client/src/components/Lobby/CreateRoomDialog.tsx

@@ -0,0 +1,120 @@
+import { useEffect, useState } from 'react'
+import { Lock, Music, Loader2 } from 'lucide-react'
+import { LIMITS } from '@music-together/shared'
+import {
+  ResponsiveDialog,
+  ResponsiveDialogBody,
+  ResponsiveDialogContent,
+  ResponsiveDialogHeader,
+  ResponsiveDialogTitle,
+} from '@/components/ui/responsive-dialog'
+import { Input } from '@/components/ui/input'
+import { Button } from '@/components/ui/button'
+import { Switch } from '@/components/ui/switch'
+import { Label } from '@/components/ui/label'
+
+interface CreateRoomDialogProps {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  onCreateRoom: (nickname: string, roomName?: string, password?: string) => void
+  defaultNickname: string
+  isLoading: boolean
+}
+
+export function CreateRoomDialog({
+  open,
+  onOpenChange,
+  onCreateRoom,
+  defaultNickname,
+  isLoading,
+}: CreateRoomDialogProps) {
+  const [nickname, setNickname] = useState(defaultNickname)
+  const [roomName, setRoomName] = useState('')
+  const [passwordEnabled, setPasswordEnabled] = useState(false)
+  const [password, setPassword] = useState('')
+
+  useEffect(() => {
+    if (!open) return
+    const frame = requestAnimationFrame(() => setNickname(defaultNickname))
+    return () => cancelAnimationFrame(frame)
+  }, [open, defaultNickname])
+
+  const canSubmit = nickname.trim() && !(passwordEnabled && !password.trim())
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault()
+    if (!canSubmit) return
+    onCreateRoom(
+      nickname.trim(),
+      roomName.trim() || undefined,
+      passwordEnabled && password.trim() ? password.trim() : undefined,
+    )
+  }
+
+  return (
+    <ResponsiveDialog open={open} onOpenChange={onOpenChange}>
+      <ResponsiveDialogContent className="sm:max-w-md">
+        <ResponsiveDialogHeader>
+          <ResponsiveDialogTitle className="flex items-center gap-2 text-lg">
+            <Music className="h-5 w-5 text-primary" />
+            创建房间
+          </ResponsiveDialogTitle>
+        </ResponsiveDialogHeader>
+
+        <ResponsiveDialogBody>
+          <form onSubmit={handleSubmit} className="space-y-4">
+            <div className="space-y-2">
+              <Label className="text-sm font-medium text-foreground/80">昵称</Label>
+              <Input
+                placeholder="你的昵称..."
+                value={nickname}
+                onChange={(e) => setNickname(e.target.value)}
+                maxLength={LIMITS.NICKNAME_MAX_LENGTH}
+                autoFocus
+              />
+            </div>
+
+            <div className="space-y-2">
+              <Label className="text-sm font-medium text-foreground/80">房间名 (可选)</Label>
+              <Input
+                placeholder="给房间起个名字..."
+                value={roomName}
+                onChange={(e) => setRoomName(e.target.value)}
+                maxLength={LIMITS.ROOM_NAME_MAX_LENGTH}
+              />
+            </div>
+
+            <div className="space-y-3">
+              <div className="flex items-center gap-2">
+                <Switch id="password-toggle" checked={passwordEnabled} onCheckedChange={setPasswordEnabled} />
+                <Label
+                  htmlFor="password-toggle"
+                  className="flex cursor-pointer items-center gap-1.5 text-sm text-muted-foreground"
+                >
+                  <Lock className="h-3.5 w-3.5" />
+                  设置密码
+                </Label>
+              </div>
+
+              {passwordEnabled && (
+                <Input
+                  type="password"
+                  placeholder="设置房间密码..."
+                  value={password}
+                  onChange={(e) => setPassword(e.target.value)}
+                  maxLength={LIMITS.ROOM_PASSWORD_MAX_LENGTH}
+                  autoFocus
+                />
+              )}
+            </div>
+
+            <Button type="submit" className="w-full" size="lg" disabled={isLoading || !canSubmit}>
+              {isLoading ? <Loader2 className="mr-2 h-4 w-4 animate-spin" /> : null}
+              创建房间
+            </Button>
+          </form>
+        </ResponsiveDialogBody>
+      </ResponsiveDialogContent>
+    </ResponsiveDialog>
+  )
+}

packages/client/src/components/Lobby/HeroSection.tsx

@@ -0,0 +1,23 @@
+import { motion } from 'motion/react'
+
+export function HeroSection() {
+  return (
+    <motion.div
+      initial={{ opacity: 0, y: -12 }}
+      animate={{ opacity: 1, y: 0 }}
+      transition={{ duration: 0.5 }}
+      className="mt-hero mb-8 px-6 text-center"
+    >
+      <div className="mb-4 inline-flex items-center gap-2 rounded-full border border-primary/20 bg-primary/10 px-3 py-1 text-xs font-medium text-primary">
+        <span className="flex items-end gap-0.5" aria-hidden="true">
+          <i className="h-1 w-0.5 rounded-full bg-current" />
+          <i className="h-2.5 w-0.5 rounded-full bg-current" />
+          <i className="h-1.5 w-0.5 rounded-full bg-current" />
+        </span>
+        实时同步音乐播放
+      </div>
+      <h1 className="text-2xl font-bold tracking-tight text-foreground sm:text-3xl">和朋友一起听歌</h1>
+      <p className="mt-2 text-sm text-muted-foreground">创建或加入一个房间，实时同步音乐播放</p>
+    </motion.div>
+  )
+}

packages/client/src/components/Lobby/NicknameDialog.tsx

@@ -0,0 +1,75 @@
+import { useState } from 'react'
+import { UserRound } from 'lucide-react'
+import { LIMITS } from '@music-together/shared'
+import {
+  ResponsiveDialog,
+  ResponsiveDialogBody,
+  ResponsiveDialogContent,
+  ResponsiveDialogDescription,
+  ResponsiveDialogHeader,
+  ResponsiveDialogTitle,
+} from '@/components/ui/responsive-dialog'
+import { Input } from '@/components/ui/input'
+import { Label } from '@/components/ui/label'
+import { Button } from '@/components/ui/button'
+import { storage } from '@/lib/storage'
+
+interface NicknameDialogProps {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  onConfirm: (nickname: string) => void
+}
+
+export function NicknameDialog({ open, onOpenChange, onConfirm }: NicknameDialogProps) {
+  const [nickname, setNickname] = useState(storage.getNickname())
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault()
+    const trimmed = nickname.trim()
+    if (!trimmed) return
+    storage.setNickname(trimmed)
+    onConfirm(trimmed)
+  }
+
+  // Sync from storage every time the dialog opens
+  const handleOpenChange = (nextOpen: boolean) => {
+    if (nextOpen) {
+      setNickname(storage.getNickname())
+    }
+    onOpenChange(nextOpen)
+  }
+
+  return (
+    <ResponsiveDialog open={open} onOpenChange={handleOpenChange}>
+      <ResponsiveDialogContent className="sm:max-w-sm">
+        <ResponsiveDialogHeader>
+          <ResponsiveDialogTitle className="flex items-center gap-2 text-lg">
+            <UserRound className="h-5 w-5 text-primary" />
+            设置昵称
+          </ResponsiveDialogTitle>
+          <ResponsiveDialogDescription>加入房间前，请先设置你的昵称</ResponsiveDialogDescription>
+        </ResponsiveDialogHeader>
+
+        <ResponsiveDialogBody>
+          <form onSubmit={handleSubmit} className="space-y-4">
+            <div className="space-y-2">
+              <Label htmlFor="nickname-input">昵称</Label>
+              <Input
+                id="nickname-input"
+                placeholder="你的昵称..."
+                value={nickname}
+                onChange={(e) => setNickname(e.target.value)}
+                maxLength={LIMITS.NICKNAME_MAX_LENGTH}
+                autoFocus
+              />
+            </div>
+
+            <Button type="submit" className="w-full" disabled={!nickname.trim()}>
+              确认并加入
+            </Button>
+          </form>
+        </ResponsiveDialogBody>
+      </ResponsiveDialogContent>
+    </ResponsiveDialog>
+  )
+}

packages/client/src/components/Lobby/PasswordDialog.tsx

@@ -0,0 +1,81 @@
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import {
+  ResponsiveDialog,
+  ResponsiveDialogBody,
+  ResponsiveDialogContent,
+  ResponsiveDialogHeader,
+  ResponsiveDialogTitle,
+} from '@/components/ui/responsive-dialog'
+import { Loader2, Lock } from 'lucide-react'
+import { motion } from 'motion/react'
+import { useState } from 'react'
+
+interface PasswordDialogProps {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  roomName: string
+  onSubmit: (password: string) => void
+  error: string | null
+  isLoading: boolean
+}
+
+export function PasswordDialog({ open, onOpenChange, roomName, onSubmit, error, isLoading }: PasswordDialogProps) {
+  const [password, setPassword] = useState('')
+
+  // Reset password when dialog opens
+  const handleOpenChange = (nextOpen: boolean) => {
+    if (nextOpen) setPassword('')
+    onOpenChange(nextOpen)
+  }
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault()
+    if (!password.trim()) return
+    onSubmit(password.trim())
+  }
+
+  return (
+    <ResponsiveDialog open={open} onOpenChange={handleOpenChange}>
+      <ResponsiveDialogContent className="sm:max-w-sm">
+        <ResponsiveDialogHeader>
+          <ResponsiveDialogTitle className="flex items-center gap-2 text-lg">
+            <Lock className="h-5 w-5 text-muted-foreground" />
+            需要密码
+          </ResponsiveDialogTitle>
+        </ResponsiveDialogHeader>
+
+        <ResponsiveDialogBody className="space-y-4">
+          <p className="text-sm text-muted-foreground">房间「{roomName}」已设置密码保护</p>
+
+          <form onSubmit={handleSubmit} className="space-y-4">
+            <motion.div animate={error ? { x: [-8, 8, -6, 6, -3, 3, 0] } : {}} transition={{ duration: 0.5 }}>
+              <Input
+                type="password"
+                placeholder="输入房间密码..."
+                value={password}
+                onChange={(e) => setPassword(e.target.value)}
+                autoFocus
+                className={error ? 'border-destructive' : ''}
+              />
+              {error && (
+                <motion.p
+                  initial={{ opacity: 0, y: -4 }}
+                  animate={{ opacity: 1, y: 0 }}
+                  className="mt-1.5 text-xs text-destructive"
+                >
+                  {error}
+                </motion.p>
+              )}
+            </motion.div>
+
+            <Button type="submit" className="w-full" disabled={isLoading || !password.trim()}>
+              {isLoading ? <Loader2 className="mr-2 h-4 w-4 animate-spin" /> : null}
+              加入房间
+            </Button>
+          </form>
+        </ResponsiveDialogBody>
+      </ResponsiveDialogContent>
+    </ResponsiveDialog>
+  )
+}

packages/client/src/components/Lobby/RoomCard.tsx

@@ -0,0 +1,87 @@
+import { memo } from 'react'
+import { Lock, LockOpen, Music, Pin, Users } from 'lucide-react'
+import { motion, useReducedMotion } from 'motion/react'
+import type { RoomListItem } from '@music-together/shared'
+import { cn } from '@/lib/utils'
+
+interface RoomCardProps {
+  room: RoomListItem
+  index: number
+  onClick: () => void
+}
+
+export const RoomCard = memo(function RoomCard({ room, index, onClick }: RoomCardProps) {
+  const prefersReducedMotion = useReducedMotion()
+  return (
+    <motion.button
+      initial={{ opacity: 0, y: 20 }}
+      animate={{ opacity: 1, y: 0 }}
+      transition={{ duration: 0.4, delay: index * 0.06, ease: [0.25, 0.46, 0.45, 0.94] }}
+      whileHover={{ y: -4, scale: 1.01 }}
+      whileTap={{ scale: 0.98 }}
+      onClick={onClick}
+      className={cn(
+        'group relative flex w-full flex-col gap-3 overflow-hidden rounded-xl p-5 text-left',
+        'mt-card rounded-2xl transition-all duration-300',
+        'hover:-translate-y-1 hover:border-primary/30 hover:shadow-lg hover:shadow-primary/5',
+      )}
+    >
+      {/* Room name row */}
+      <div className="flex items-start justify-between">
+        <div className="min-w-0 flex-1">
+          <h3 className="truncate text-base font-semibold text-foreground">{room.name}</h3>
+          {room.currentTrackTitle && (
+            <p className="mt-1 flex items-center gap-1.5 truncate text-xs text-muted-foreground">
+              <Music className="h-3 w-3 shrink-0 text-primary" />
+              <span className="truncate">
+                {room.currentTrackTitle}
+                {room.currentTrackArtist && ` - ${room.currentTrackArtist}`}
+              </span>
+            </p>
+          )}
+        </div>
+
+        {/* Right side: playing animation + lock icon */}
+        <div className="ml-3 flex shrink-0 items-center gap-2">
+          {room.permanent && <Pin className="h-4 w-4 text-primary/70" aria-label="永久房间" />}
+          {/* Subtle playing animation for rooms with active tracks */}
+          {room.currentTrackTitle && (
+            <div className="flex items-end gap-0.5">
+              {[0, 1, 2].map((i) => (
+                <motion.div
+                  key={i}
+                  className="w-0.5 rounded-full bg-primary/40"
+                  animate={prefersReducedMotion ? { height: 8 } : { height: [4, 12, 6, 10, 4] }}
+                  transition={
+                    prefersReducedMotion
+                      ? {}
+                      : {
+                          duration: 1.2,
+                          repeat: Infinity,
+                          delay: i * 0.15,
+                          ease: 'easeInOut',
+                        }
+                  }
+                />
+              ))}
+            </div>
+          )}
+          {room.hasPassword ? (
+            <Lock className="h-4 w-4 text-muted-foreground/60" />
+          ) : (
+            <LockOpen className="h-4 w-4 text-muted-foreground/40" />
+          )}
+        </div>
+      </div>
+
+      {/* Bottom info */}
+      <div className="flex items-center gap-3">
+        <span className="flex items-center gap-1 text-xs text-muted-foreground">
+          <Users className="h-3 w-3" />
+          {room.userCount}
+        </span>
+        <span className="text-xs text-muted-foreground/50">{room.id}</span>
+      </div>
+    </motion.button>
+  )
+})

packages/client/src/components/Lobby/RoomListSection.tsx

@@ -0,0 +1,62 @@
+import { Music } from 'lucide-react'
+import { motion } from 'motion/react'
+import type { RoomListItem } from '@music-together/shared'
+import { RoomCard } from './RoomCard'
+import { Skeleton } from '@/components/ui/skeleton'
+
+interface RoomListSectionProps {
+  rooms: RoomListItem[]
+  isLoading: boolean
+  onRoomClick: (room: RoomListItem) => void
+}
+
+export function RoomListSection({ rooms, isLoading, onRoomClick }: RoomListSectionProps) {
+  return (
+    <>
+      <div className="mb-4">
+        <h2 className="text-lg font-semibold text-foreground/80">
+          活跃房间
+          {!isLoading && rooms.length > 0 && (
+            <span className="ml-2 text-sm font-normal text-muted-foreground">({rooms.length})</span>
+          )}
+        </h2>
+      </div>
+
+      {isLoading ? (
+        <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
+          {Array.from({ length: 3 }).map((_, i) => (
+            <div key={i} className="mt-card flex flex-col gap-3 rounded-2xl p-5">
+              <div className="space-y-2">
+                <Skeleton className="h-5 w-2/3" />
+                <Skeleton className="h-3 w-1/2" />
+              </div>
+              <div className="flex items-center gap-3">
+                <Skeleton className="h-3 w-12" />
+                <Skeleton className="h-3 w-16" />
+              </div>
+            </div>
+          ))}
+        </div>
+      ) : rooms.length === 0 ? (
+        <motion.div
+          initial={{ opacity: 0 }}
+          animate={{ opacity: 1 }}
+          transition={{ delay: 0.25 }}
+          className="mt-card flex flex-col items-center gap-4 rounded-2xl border-dashed bg-card/50 px-8 py-16 text-center"
+        >
+          <Music className="h-10 w-10 text-muted-foreground/25" />
+          <div>
+            <p className="text-base font-medium text-foreground/60">还没有活跃的房间</p>
+            <p className="mt-1 text-sm text-muted-foreground">创建一个房间，邀请朋友一起听歌</p>
+          </div>
+        </motion.div>
+      ) : (
+        <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
+          {rooms.map((room, i) => (
+            <RoomCard key={room.id} room={room} index={i} onClick={() => onRoomClick(room)} />
+          ))}
+        </div>
+      )}
+    </>
+  )
+}

packages/client/src/components/Lobby/UserPopover.tsx

@@ -0,0 +1,166 @@
+import { useEffect, useState } from 'react'
+import { Camera, CircleUser, Loader2 } from 'lucide-react'
+import { LIMITS } from '@music-together/shared'
+import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar'
+import { Badge } from '@/components/ui/badge'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import { Separator } from '@/components/ui/separator'
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'
+import { resolveAvatarUrl, updateCurrentNickname, uploadCurrentAvatar } from '@/lib/profileApi'
+import { storage } from '@/lib/storage'
+import { useAccountStore } from '@/stores/accountStore'
+import { toast } from 'sonner'
+import { AccountAccessControls, AccountIdEditor } from '@/components/Overlays/Settings/AccountSection'
+
+export function UserPopover() {
+  const profile = useAccountStore((state) => state.profile)
+  const [nickname, setNickname] = useState(profile?.nickname || storage.getNickname())
+  const [open, setOpen] = useState(false)
+  const [saving, setSaving] = useState(false)
+  const [uploading, setUploading] = useState(false)
+
+  useEffect(() => {
+    setNickname(profile?.nickname || storage.getNickname())
+  }, [profile?.nickname])
+
+  const handleSave = async () => {
+    const trimmed = nickname.trim()
+    if (!trimmed || trimmed === profile?.nickname) return
+    setSaving(true)
+    try {
+      await updateCurrentNickname(trimmed)
+      toast.success('昵称已保存到服务器')
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : '昵称保存失败')
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  const handleAvatar = async (file?: File) => {
+    if (!file) return
+    if (!['image/png', 'image/jpeg', 'image/webp'].includes(file.type)) {
+      toast.error('仅支持 PNG、JPEG 和 WebP 图片')
+      return
+    }
+    if (file.size > 5 * 1024 * 1024) {
+      toast.error('头像不能超过 5MB')
+      return
+    }
+
+    setUploading(true)
+    try {
+      const image = await new Promise<string>((resolve, reject) => {
+        const reader = new FileReader()
+        reader.onload = () => resolve(String(reader.result))
+        reader.onerror = () => reject(new Error('读取图片失败'))
+        reader.readAsDataURL(file)
+      })
+      await uploadCurrentAvatar(image)
+      toast.success('头像已保存到服务器')
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : '头像上传失败')
+    } finally {
+      setUploading(false)
+    }
+  }
+
+  const displayName = profile?.nickname || storage.getNickname()
+  const initial = displayName?.charAt(0).toUpperCase()
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <Button
+          variant="ghost"
+          size="icon"
+          className="h-9 w-9 rounded-full border border-border/60"
+          aria-label="个人资料"
+        >
+          {profile?.avatarUrl ? (
+            <Avatar className="h-8 w-8">
+              <AvatarImage src={resolveAvatarUrl(profile.avatarUrl)} alt="" />
+              <AvatarFallback>{initial}</AvatarFallback>
+            </Avatar>
+          ) : initial ? (
+            <span className="text-sm font-semibold">{initial}</span>
+          ) : (
+            <CircleUser className="h-5 w-5" />
+          )}
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent align="end" className="w-80">
+        <div className="space-y-4">
+          <div className="flex items-center gap-3">
+            <Avatar size="lg">
+              <AvatarImage src={resolveAvatarUrl(profile?.avatarUrl)} alt="" />
+              <AvatarFallback>{initial || '?'}</AvatarFallback>
+            </Avatar>
+            <div className="min-w-0 flex-1">
+              <p className="truncate text-sm font-medium">{displayName || '尚未设置昵称'}</p>
+              <div className="flex items-center gap-2">
+                <p className="truncate font-mono text-[11px] text-muted-foreground">
+                  {profile?.id || '保存昵称后生成账号 ID'}
+                </p>
+                {profile?.role === 'admin' && (
+                  <Badge variant="secondary" className="px-1.5 py-0 text-[10px]">
+                    管理员
+                  </Badge>
+                )}
+              </div>
+            </div>
+            {profile && (
+              <label>
+                <input
+                  type="file"
+                  accept="image/png,image/jpeg,image/webp"
+                  className="sr-only"
+                  onChange={(event) => void handleAvatar(event.currentTarget.files?.[0])}
+                />
+                <Button asChild variant="ghost" size="icon" className="h-8 w-8" aria-label="上传头像">
+                  <span>
+                    {uploading ? <Loader2 className="h-4 w-4 animate-spin" /> : <Camera className="h-4 w-4" />}
+                  </span>
+                </Button>
+              </label>
+            )}
+          </div>
+
+          <Separator />
+
+          <div className="space-y-1.5">
+            <label htmlFor="profile-nickname" className="text-xs font-medium text-muted-foreground">
+              昵称
+            </label>
+            <div className="flex gap-2">
+              <Input
+                id="profile-nickname"
+                value={nickname}
+                onChange={(event) => setNickname(event.target.value)}
+                onKeyDown={(event) => event.key === 'Enter' && void handleSave()}
+                maxLength={LIMITS.NICKNAME_MAX_LENGTH}
+                className="h-8 text-sm"
+              />
+              <Button size="sm" className="h-8" onClick={() => void handleSave()} disabled={saving || !nickname.trim()}>
+                {saving ? <Loader2 className="h-4 w-4 animate-spin" /> : '保存'}
+              </Button>
+            </div>
+          </div>
+
+          {profile ? (
+            <>
+              <Separator />
+              <AccountIdEditor compact onComplete={() => setOpen(false)} />
+
+              <Separator />
+              <AccountAccessControls compact onComplete={() => setOpen(false)} />
+            </>
+          ) : (
+            <p className="text-xs text-muted-foreground">保存昵称后将生成账号 ID，并可设置密码保护账号。</p>
+          )}
+        </div>
+      </PopoverContent>
+    </Popover>
+  )
+}

packages/client/src/components/Overlays/BilibiliCollectionDialog.tsx

@@ -0,0 +1,127 @@
+import { ResponsiveDialog, ResponsiveDialogBody, ResponsiveDialogContent, ResponsiveDialogHeader, ResponsiveDialogTitle } from '@/components/ui/responsive-dialog'
+import { Input } from '@/components/ui/input'
+import { VirtualTrackList } from '@/components/VirtualTrackList'
+import { SERVER_URL } from '@/lib/config'
+import type { Track } from '@music-together/shared'
+import { ListMusic, Search } from 'lucide-react'
+import { useEffect, useMemo, useState } from 'react'
+import { toast } from 'sonner'
+
+interface BilibiliCollectionDialogProps {
+  track: Track | null
+  onOpenChange: (open: boolean) => void
+  onSelectTrack: (track: Track) => void
+  onNotCollection: () => void
+  isTrackAdded: (track: Track) => boolean
+}
+
+function normalizeSearchText(value: string) {
+  return value.normalize('NFKC').toLocaleLowerCase().replace(/[\s\p{P}\p{S}]+/gu, '')
+}
+
+/**
+ * Resolves a Bilibili video on demand. If it belongs to a UGC collection,
+ * show its individual videos so users choose what to add instead of queuing
+ * the whole collection or blindly playing the first video.
+ */
+export function BilibiliCollectionDialog({
+  track,
+  onOpenChange,
+  onSelectTrack,
+  onNotCollection,
+  isTrackAdded,
+}: BilibiliCollectionDialogProps) {
+  const [tracks, setTracks] = useState<Track[]>([])
+  const [title, setTitle] = useState('')
+  const [loading, setLoading] = useState(false)
+  const [query, setQuery] = useState('')
+
+  const filteredTracks = useMemo(() => {
+    const keyword = normalizeSearchText(query)
+    if (!keyword) return tracks
+
+    return tracks.filter((collectionTrack) =>
+      [collectionTrack.title, collectionTrack.album, ...collectionTrack.artist]
+        .filter(Boolean)
+        .some((value) => normalizeSearchText(value).includes(keyword)),
+    )
+  }, [query, tracks])
+
+  useEffect(() => {
+    if (!track) {
+      setTracks([])
+      setTitle('')
+      setLoading(false)
+      setQuery('')
+      return
+    }
+
+    const controller = new AbortController()
+    setTracks([])
+    setTitle('')
+    setLoading(true)
+    setQuery('')
+
+    void fetch(`${SERVER_URL}/api/music/bilibili-collection?bvid=${encodeURIComponent(track.urlId)}`, {
+      signal: controller.signal,
+      credentials: 'include',
+    })
+      .then(async (response) => {
+        if (!response.ok) throw new Error('Failed to resolve Bilibili collection')
+        return (await response.json()) as { title?: string; tracks?: Track[] }
+      })
+      .then((data) => {
+        if (controller.signal.aborted) return
+        const collectionTracks = data.tracks ?? []
+        if (collectionTracks.length <= 1) {
+          onNotCollection()
+          return
+        }
+        setTitle(data.title || 'B站合集')
+        setTracks(collectionTracks)
+      })
+      .catch(() => {
+        if (controller.signal.aborted) return
+        toast.error('读取 B 站合集失败，已按单视频处理')
+        onNotCollection()
+      })
+      .finally(() => {
+        if (!controller.signal.aborted) setLoading(false)
+      })
+
+    return () => controller.abort()
+  }, [track, onNotCollection])
+
+  return (
+    <ResponsiveDialog open={Boolean(track)} onOpenChange={onOpenChange}>
+      <ResponsiveDialogContent className="flex h-dvh max-h-dvh flex-col overflow-hidden sm:h-auto sm:max-h-[80vh] sm:max-w-2xl">
+        <ResponsiveDialogHeader>
+          <ResponsiveDialogTitle>{title ? `合集：${title}` : '正在读取合集…'}</ResponsiveDialogTitle>
+        </ResponsiveDialogHeader>
+        <ResponsiveDialogBody className="flex min-h-0 flex-1 flex-col gap-3 overflow-hidden">
+          <div className="relative shrink-0">
+            <Search className="pointer-events-none absolute top-1/2 left-3 h-4 w-4 -translate-y-1/2 text-muted-foreground" />
+            <Input
+              value={query}
+              onChange={(event) => setQuery(event.target.value)}
+              placeholder="搜索视频、作者或专辑..."
+              aria-label="搜索合集内容"
+              className="pl-9"
+            />
+          </div>
+          <VirtualTrackList
+            tracks={filteredTracks}
+            loading={loading}
+            hasMore={false}
+            loadingMore={false}
+            onLoadMore={() => undefined}
+            isTrackAdded={isTrackAdded}
+            onAddTrack={onSelectTrack}
+            emptyIcon={<ListMusic className="h-8 w-8" />}
+            emptyMessage={query.trim() ? '没有匹配的视频' : '合集内没有可播放的视频'}
+          />
+        </ResponsiveDialogBody>
+      </ResponsiveDialogContent>
+    </ResponsiveDialog>
+  )
+}

packages/client/src/components/Overlays/BilibiliMetadataDialog.tsx

@@ -0,0 +1,137 @@
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import {
+  ResponsiveDialog,
+  ResponsiveDialogBody,
+  ResponsiveDialogContent,
+  ResponsiveDialogHeader,
+  ResponsiveDialogTitle,
+} from '@/components/ui/responsive-dialog'
+import { Tabs, TabsList, TabsTrigger } from '@/components/ui/tabs'
+import { useSearch } from '@/hooks/useSearch'
+import { trackKey } from '@/lib/utils'
+import type { BilibiliMetadataSource, Track } from '@music-together/shared'
+import { Loader2, Music2, Search } from 'lucide-react'
+import { useEffect, useState } from 'react'
+
+interface BilibiliMetadataDialogProps {
+  track: Track | null
+  roomId?: string
+  onOpenChange: (open: boolean) => void
+  onSelect: (metadataTrack: Track, source: BilibiliMetadataSource) => void
+  onSkip: () => void
+}
+
+export function BilibiliMetadataDialog({ track, roomId, onOpenChange, onSelect, onSkip }: BilibiliMetadataDialogProps) {
+  const [source, setSource] = useState<BilibiliMetadataSource>('netease')
+  const trackId = track?.id
+  const trackTitle = track?.title
+  const [query, setQuery] = useState({ trackId, value: trackTitle ?? '' })
+  const keyword = query.trackId === trackId ? query.value : (trackTitle ?? '')
+  const { results, loading, loadingMore, hasMore, hasSearched, search, loadMore, resetState } = useSearch(
+    source,
+    'song',
+    roomId,
+  )
+
+  useEffect(() => {
+    if (!trackTitle) return
+    resetState()
+    search(trackTitle)
+  }, [trackId, trackTitle, source, resetState, search])
+
+  return (
+    <ResponsiveDialog open={Boolean(track)} onOpenChange={onOpenChange}>
+      <ResponsiveDialogContent className="flex max-h-[80vh] flex-col sm:max-w-xl">
+        <ResponsiveDialogHeader>
+          <ResponsiveDialogTitle>选择歌词和封面</ResponsiveDialogTitle>
+        </ResponsiveDialogHeader>
+        <ResponsiveDialogBody className="flex min-h-0 flex-1 flex-col gap-4 overflow-hidden">
+          <Tabs value={source} onValueChange={(value) => setSource(value as BilibiliMetadataSource)}>
+            <TabsList className="grid h-9 w-full grid-cols-4">
+              <TabsTrigger value="netease" className="w-full text-xs sm:text-sm">
+                网易云音乐
+              </TabsTrigger>
+              <TabsTrigger value="tencent" className="w-full text-xs sm:text-sm">
+                QQ 音乐
+              </TabsTrigger>
+              <TabsTrigger value="kugou" className="w-full text-xs sm:text-sm">
+                酷狗音乐
+              </TabsTrigger>
+              <TabsTrigger value="kugou_concept" className="w-full text-xs sm:text-sm">
+                酷狗概念版
+              </TabsTrigger>
+            </TabsList>
+          </Tabs>
+
+          <div className="flex gap-2">
+            <Input
+              value={keyword}
+              onChange={(event) => setQuery({ trackId, value: event.target.value })}
+              onKeyDown={(event) => event.key === 'Enter' && search(keyword)}
+              placeholder="搜索歌曲或歌手..."
+              autoFocus
+              aria-label="搜索歌词和封面"
+            />
+            <Button onClick={() => search(keyword)} disabled={loading} aria-label="搜索">
+              {loading ? <Loader2 className="h-4 w-4 animate-spin" /> : <Search className="h-4 w-4" />}
+            </Button>
+          </div>
+
+          <Button variant="outline" onClick={onSkip}>
+            直接播放 B 站视频
+          </Button>
+
+          <div className="min-h-0 flex-1 overflow-y-auto rounded-md border">
+            {loading ? (
+              <div className="flex h-48 items-center justify-center">
+                <Loader2 className="h-6 w-6 animate-spin text-muted-foreground" />
+              </div>
+            ) : !hasSearched || results.length === 0 ? (
+              <div className="flex h-48 flex-col items-center justify-center gap-2 text-muted-foreground">
+                <Music2 className="h-8 w-8" />
+                <span className="text-sm">{hasSearched ? '暂无匹配结果' : '搜索后选择一首歌曲'}</span>
+              </div>
+            ) : (
+              <div className="divide-y">
+                {(results as Track[]).map((metadataTrack) => (
+                  <button
+                    key={trackKey(metadataTrack)}
+                    className="hover:bg-accent flex w-full min-w-0 items-center gap-3 p-3 text-left transition-colors"
+                    onClick={() => onSelect(metadataTrack, source)}
+                  >
+                    {metadataTrack.cover ? (
+                      <img
+                        src={metadataTrack.cover}
+                        alt=""
+                        referrerPolicy="no-referrer"
+                        className="h-10 w-10 shrink-0 rounded object-cover"
+                        loading="lazy"
+                      />
+                    ) : (
+                      <div className="bg-muted flex h-10 w-10 shrink-0 items-center justify-center rounded">
+                        <Music2 className="text-muted-foreground h-4 w-4" />
+                      </div>
+                    )}
+                    <div className="min-w-0 flex-1">
+                      <p className="truncate text-sm font-medium">{metadataTrack.title}</p>
+                      <p className="text-muted-foreground truncate text-xs">
+                        {metadataTrack.artist.join(' / ')}
+                        {metadataTrack.album ? ` · ${metadataTrack.album}` : ''}
+                      </p>
+                    </div>
+                  </button>
+                ))}
+                {hasMore && (
+                  <Button className="m-2 w-[calc(100%-1rem)]" variant="ghost" onClick={loadMore} disabled={loadingMore}>
+                    {loadingMore ? '加载中...' : '加载更多'}
+                  </Button>
+                )}
+              </div>
+            )}
+          </div>
+        </ResponsiveDialogBody>
+      </ResponsiveDialogContent>
+    </ResponsiveDialog>
+  )
+}

packages/client/src/components/Overlays/QueueDrawer.tsx

@@ -0,0 +1,482 @@
+import { Badge } from '@/components/ui/badge'
+import { Button } from '@/components/ui/button'
+import { Drawer, DrawerContent, DrawerHeader, DrawerTitle } from '@/components/ui/drawer'
+import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip'
+import { cn } from '@/lib/utils'
+import { getProxiedCoverUrl } from '@/lib/cover'
+import { usePlayerStore } from '@/stores/playerStore'
+import { useRoomStore } from '@/stores/roomStore'
+import { useSocketContext } from '@/providers/socket-context'
+import type { BilibiliMetadataSource, Track } from '@music-together/shared'
+import { EVENTS } from '@music-together/shared'
+import { useHasHover } from '@/hooks/useHasHover'
+import { useIsMobile } from '@/hooks/useIsMobile'
+import { useCallback, useContext, useEffect, useRef, useState, type MouseEvent } from 'react'
+import { useVirtualizer } from '@tanstack/react-virtual'
+import { AbilityContext } from '@/providers/ability-context'
+import { ArrowUpToLine, ChevronDown, ChevronUp, ListX, Music, Play, RefreshCw, Trash2, User, X } from 'lucide-react'
+import { toast } from 'sonner'
+import { MarqueeText } from '@/components/ui/marquee-text'
+import { BilibiliMetadataDialog } from './BilibiliMetadataDialog'
+import type { MusicSource } from '@music-together/shared'
+
+const EMPTY_QUEUE: Track[] = []
+
+const SOURCE_STYLE: Record<MusicSource, { label: string; className: string }> = {
+  netease: { label: '网易', className: 'text-white bg-red-500 ring-red-600/50' },
+  tencent: { label: 'QQ', className: 'text-white bg-green-500 ring-green-600/50' },
+  kugou: { label: '酷狗', className: 'text-white bg-blue-500 ring-blue-600/50' },
+  kugou_concept: { label: '概念版', className: 'text-white bg-sky-500 ring-sky-600/50' },
+  bilibili: { label: 'B站', className: 'text-white bg-pink-500 ring-pink-600/50' },
+}
+
+interface QueueDrawerProps {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  onRemoveFromQueue: (trackId: string) => void
+  onReorderQueue: (trackIds: string[]) => void
+  onUpdateBilibiliMetadata: (
+    trackId: string,
+    metadata:
+      | { metadataSource: BilibiliMetadataSource; lyricId?: string; picId?: string; cover: string }
+      | { clearMetadata: true },
+  ) => void
+  onClearQueue: () => void
+}
+
+export function QueueDrawer({
+  open,
+  onOpenChange,
+  onRemoveFromQueue,
+  onReorderQueue,
+  onUpdateBilibiliMetadata,
+  onClearQueue,
+}: QueueDrawerProps) {
+  const queue = useRoomStore((s) => s.room?.queue ?? EMPTY_QUEUE)
+  const roomId = useRoomStore((s) => s.room?.id)
+  const room = useRoomStore((s) => s.room)
+  const currentUser = useRoomStore((s) => s.currentUser)
+  const currentTrack = usePlayerStore((s) => s.currentTrack)
+  const { socket } = useSocketContext()
+  const isMobile = useIsMobile() // layout: Drawer direction, height
+  const hasHover = useHasHover() // interaction: hover vs touch
+  const isTouch = !hasHover
+  const ability = useContext(AbilityContext)
+  const canRemove = ability.can('remove', 'Queue')
+  const isTemporaryAdmin = room?.temporaryAdminUserId === currentUser?.id && !currentUser?.isServerAdmin
+  const allowTemporaryAdminTrackRemoval = room?.allowTemporaryAdminTrackRemoval ?? false
+  const allowTemporaryAdminQueueClear = room?.allowTemporaryAdminQueueClear ?? false
+  const canRemoveTrack = canRemove && (!isTemporaryAdmin || allowTemporaryAdminTrackRemoval)
+  const canClearQueue = canRemove && (!isTemporaryAdmin || allowTemporaryAdminQueueClear)
+  const canAdd = ability.can('add', 'Queue')
+  const canReorder = ability.can('reorder', 'Queue')
+  const canPlay = ability.can('play', 'Player')
+  const canVote = ability.can('vote', 'Player')
+  const [confirmClear, setConfirmClear] = useState(false)
+  const confirmTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  // Mobile: track which item has its action toolbar visible
+  const [activeTrackId, setActiveTrackId] = useState<string | null>(null)
+  // Desktop: after clicking an action, temporarily suppress the hover toolbar until the cursor leaves the item
+  const [dismissedHoverTrackId, setDismissedHoverTrackId] = useState<string | null>(null)
+  const [metadataTrack, setMetadataTrack] = useState<Track | null>(null)
+
+  const [scrollElement, setScrollElement] = useState<HTMLDivElement | null>(null)
+  // TanStack Virtual manages mutable measurements internally and cannot be compiler-memoized.
+  // eslint-disable-next-line react-hooks/incompatible-library
+  const virtualizer = useVirtualizer({
+    count: queue.length,
+    getScrollElement: () => scrollElement,
+    estimateSize: () => 56,
+    overscan: 5,
+  })
+
+  // Clear the confirm-dismiss timer on unmount
+  useEffect(
+    () => () => {
+      if (confirmTimerRef.current) clearTimeout(confirmTimerRef.current)
+    },
+    [],
+  )
+
+  const handleClear = useCallback(() => {
+    if (!confirmClear) {
+      setConfirmClear(true)
+      // Auto-dismiss after 3s
+      if (confirmTimerRef.current) clearTimeout(confirmTimerRef.current)
+      confirmTimerRef.current = setTimeout(() => {
+        confirmTimerRef.current = null
+        setConfirmClear(false)
+      }, 3000)
+      return
+    }
+    if (confirmTimerRef.current) {
+      clearTimeout(confirmTimerRef.current)
+      confirmTimerRef.current = null
+    }
+    onClearQueue()
+    setConfirmClear(false)
+    toast.success('播放列表已清空')
+  }, [confirmClear, onClearQueue])
+
+  const handleMoveUp = (index: number) => {
+    if (index <= 0) return
+    const ids = queue.map((t) => t.id)
+    ;[ids[index - 1], ids[index]] = [ids[index], ids[index - 1]]
+    onReorderQueue(ids)
+  }
+
+  const handleMoveDown = (index: number) => {
+    if (index >= queue.length - 1) return
+    const ids = queue.map((t) => t.id)
+    ;[ids[index], ids[index + 1]] = [ids[index + 1], ids[index]]
+    onReorderQueue(ids)
+  }
+
+  const handlePlayTrack = (track: Track) => {
+    if (canPlay) {
+      socket.emit(EVENTS.PLAYER_PLAY, { track })
+    } else if (canVote) {
+      socket.emit(EVENTS.VOTE_START, {
+        action: 'play-track' as const,
+        payload: { trackId: track.id, trackTitle: track.title },
+      })
+      toast.info(`已发起投票：播放「${track.title}」`)
+    }
+  }
+
+  const handleRemoveTrack = (track: Track) => {
+    if (canRemoveTrack) {
+      onRemoveFromQueue(track.id)
+      toast.success(`已移除「${track.title}」`)
+    } else if (canVote) {
+      socket.emit(EVENTS.VOTE_START, {
+        action: 'remove-track' as const,
+        payload: { trackId: track.id, trackTitle: track.title },
+      })
+      toast.info(`已发起投票：移除「${track.title}」`)
+    }
+  }
+
+  const handleInsertAfterCurrent = (track: Track, e?: MouseEvent) => {
+    // If this was triggered from inside the floating actions, hide it immediately.
+    // - Touch: activeTrackId controls visibility
+    // - Desktop: group-hover/group-focus-within can keep it visible after DOM reorders (transform keeps hover)
+    if (e) {
+      e.stopPropagation()
+      ;(e.currentTarget as HTMLButtonElement | null)?.blur()
+    }
+    if (isTouch && activeTrackId === track.id) setActiveTrackId(null)
+    if (!isTouch) setDismissedHoverTrackId(track.id)
+    const current = currentTrack
+    const currentIndex = current?.id ? queue.findIndex((t) => t.id === current.id) : -1
+
+    if (current && track.id === current.id) return
+
+    const ids = queue.map((t) => t.id)
+    const from = ids.indexOf(track.id)
+    if (from < 0) return
+
+    // 先移除再插入，避免重复
+    ids.splice(from, 1)
+
+    if (currentIndex >= 0) {
+      // 目标位置：当前播放歌曲的下方（已播放的在上方，不动）
+      // 如果被移动的歌曲在 current 之前，移除后 currentIndex 会左移一位
+      const adjustedCurrentIndex = from < currentIndex ? currentIndex - 1 : currentIndex
+      const to = adjustedCurrentIndex + 1
+      ids.splice(to, 0, track.id)
+    } else {
+      // 无 currentTrack（或 currentTrack 不在队列中）时，退化为置顶到队首
+      ids.unshift(track.id)
+    }
+
+    onReorderQueue(ids)
+    toast.success(`已置顶「${track.title}」`)
+  }
+
+  return (
+    <Drawer open={open} onOpenChange={onOpenChange} direction={isMobile ? 'bottom' : 'right'}>
+      <DrawerContent className={cn('flex flex-col p-0', isMobile && 'h-[70vh]')}>
+        <DrawerHeader className="shrink-0 border-b px-4 py-3">
+          <div className="flex items-center justify-between">
+            <DrawerTitle className="flex items-center gap-2 text-base">
+              <Music className="h-4 w-4" />
+              播放列表 ({queue.length})
+            </DrawerTitle>
+            <div className="flex items-center gap-1">
+              {canClearQueue && queue.length > 0 && (
+                <Tooltip delayDuration={300}>
+                  <TooltipTrigger asChild>
+                    <Button
+                      variant="ghost"
+                      size="icon"
+                      className={cn('h-7 w-7', confirmClear && 'text-destructive hover:text-destructive')}
+                      onClick={handleClear}
+                      aria-label="清空播放列表"
+                    >
+                      <ListX className="h-4 w-4" />
+                    </Button>
+                  </TooltipTrigger>
+                  <TooltipContent>{confirmClear ? '再次点击确认清空' : '清空播放列表'}</TooltipContent>
+                </Tooltip>
+              )}
+              {!isMobile && (
+                <Button
+                  variant="ghost"
+                  size="icon"
+                  className="h-7 w-7"
+                  onClick={() => onOpenChange(false)}
+                  aria-label="关闭播放列表"
+                >
+                  <X className="h-4 w-4" />
+                </Button>
+              )}
+            </div>
+          </div>
+        </DrawerHeader>
+
+        <div ref={setScrollElement} className="min-h-0 flex-1 overflow-x-hidden overflow-y-auto px-2">
+          {queue.length === 0 ? (
+            <div className="flex h-40 items-center justify-center text-muted-foreground">播放列表为空</div>
+          ) : (
+            <div className="w-full" style={{ height: `${virtualizer.getTotalSize()}px`, position: 'relative' }}>
+              {virtualizer.getVirtualItems().map((virtualRow) => {
+                const i = virtualRow.index
+                const track = queue[i]
+                if (!track) return null
+                return (
+                  <div
+                    key={track.id}
+                    style={{
+                      position: 'absolute',
+                      top: 0,
+                      left: 0,
+                      width: '100%',
+                      height: `${virtualRow.size}px`,
+                      transform: `translateY(${virtualRow.start}px)`,
+                      paddingTop: '8px', // To simulate the top padding/gap
+                    }}
+                  >
+                    <div
+                      className={cn(
+                        'group relative flex h-full items-center gap-2 rounded-lg px-2 transition-colors hover:bg-accent/50',
+                        currentTrack?.id === track.id && 'bg-primary/10',
+                      )}
+                      onClick={() => {
+                        if (isTouch) {
+                          setActiveTrackId((prev) => (prev === track.id ? null : track.id))
+                        }
+                      }}
+                      onMouseLeave={() => {
+                        if (!isTouch && dismissedHoverTrackId === track.id) setDismissedHoverTrackId(null)
+                      }}
+                    >
+                      {/* Index */}
+                      <span className="w-5 shrink-0 text-center text-xs tabular-nums text-muted-foreground">
+                        {i + 1}
+                      </span>
+
+                      {/* Cover + source badge */}
+                      <div className="relative shrink-0">
+                        {track.cover ? (
+                          <img
+                            src={getProxiedCoverUrl(track.cover)}
+                            alt={track.title}
+                            referrerPolicy="no-referrer"
+                            className="h-9 w-9 rounded object-cover"
+                            onError={(e) => {
+                              e.currentTarget.style.display = 'none'
+                              e.currentTarget.nextElementSibling?.classList.remove('hidden')
+                            }}
+                          />
+                        ) : null}
+                        <div
+                          className={cn(
+                            'flex h-9 w-9 items-center justify-center rounded bg-muted',
+                            track.cover && 'hidden',
+                          )}
+                        >
+                          <Music className="h-4 w-4 text-muted-foreground" />
+                        </div>
+                        {track.source && SOURCE_STYLE[track.source] && (
+                          <span
+                            className={cn(
+                              'absolute -bottom-1 -right-1 rounded px-0.5 text-[8px] font-bold leading-tight ring-1',
+                              SOURCE_STYLE[track.source].className,
+                            )}
+                          >
+                            {SOURCE_STYLE[track.source].label}
+                          </span>
+                        )}
+                      </div>
+
+                      {/* Track info */}
+                      <div className="min-w-0 flex-1">
+                        <MarqueeText
+                          className={cn('text-sm', currentTrack?.id === track.id && 'font-medium text-primary')}
+                        >
+                          {track.title}
+                        </MarqueeText>
+                        <div className="flex min-w-0 items-center gap-1">
+                          <MarqueeText className="min-w-0 flex-1 text-xs text-muted-foreground">
+                            {track.artist.join(' / ')}
+                          </MarqueeText>
+                          {track.requestedBy && (
+                            <Badge
+                              variant="outline"
+                              className="h-4 max-w-28 shrink-0 gap-0.5 truncate border-primary/30 bg-primary/10 px-1.5 py-0 text-[10px] font-normal text-primary"
+                            >
+                              <User className="h-2.5 w-2.5 shrink-0" />
+                              <span className="truncate">{track.requestedBy}</span>
+                            </Badge>
+                          )}
+                        </div>
+                      </div>
+
+                      {/* Actions — visible on hover (desktop) or tap (mobile) */}
+                      <div
+                        className={cn(
+                          'absolute right-1 top-1/2 z-20 flex -translate-y-1/2 items-center gap-0.5',
+                          'rounded-md border border-border/50 bg-popover px-1 py-0.5 shadow-md backdrop-blur-md',
+                          'opacity-0 pointer-events-none transition-opacity',
+                          'group-hover:opacity-100 group-hover:pointer-events-auto',
+                          'group-focus-within:opacity-100 group-focus-within:pointer-events-auto',
+                          isTouch && activeTrackId === track.id && 'opacity-100 pointer-events-auto',
+                          !isTouch && dismissedHoverTrackId === track.id && 'opacity-0 pointer-events-none',
+                        )}
+                        onClick={(e) => e.stopPropagation()}
+                      >
+                        {/* Play button — hidden for currently playing track */}
+                        {currentTrack?.id !== track.id && (canPlay || canVote) && (
+                          <Tooltip delayDuration={400}>
+                            <TooltipTrigger asChild>
+                              <Button
+                                variant="ghost"
+                                size="icon"
+                                className="h-6 w-6 min-h-9 min-w-9 sm:min-h-0 sm:min-w-0"
+                                onClick={() => handlePlayTrack(track)}
+                                aria-label={canPlay ? `播放 ${track.title}` : `投票播放 ${track.title}`}
+                              >
+                                <Play className="h-3 w-3" />
+                              </Button>
+                            </TooltipTrigger>
+                            <TooltipContent side="bottom">{canPlay ? '播放' : '投票播放'}</TooltipContent>
+                          </Tooltip>
+                        )}
+
+                        {track.source === 'bilibili' && canAdd && (
+                          <Tooltip delayDuration={400}>
+                            <TooltipTrigger asChild>
+                              <Button
+                                variant="ghost"
+                                size="icon"
+                                className="h-6 w-6 min-h-9 min-w-9 sm:min-h-0 sm:min-w-0"
+                                onClick={() => setMetadataTrack(track)}
+                                aria-label={`重选 ${track.title} 的歌词和封面`}
+                              >
+                                <RefreshCw className="h-3 w-3" />
+                              </Button>
+                            </TooltipTrigger>
+                            <TooltipContent side="bottom">重选歌词和封面</TooltipContent>
+                          </Tooltip>
+                        )}
+
+                        {canReorder && (
+                          <>
+                            <Tooltip delayDuration={400}>
+                              <TooltipTrigger asChild>
+                                <Button
+                                  variant="ghost"
+                                  size="icon"
+                                  className="h-6 w-6 min-h-9 min-w-9 sm:min-h-0 sm:min-w-0"
+                                  disabled={i === 0}
+                                  onClick={() => handleMoveUp(i)}
+                                  aria-label={`上移 ${track.title}`}
+                                >
+                                  <ChevronUp className="h-3 w-3" />
+                                </Button>
+                              </TooltipTrigger>
+                              <TooltipContent side="bottom">上移</TooltipContent>
+                            </Tooltip>
+
+                            <Tooltip delayDuration={400}>
+                              <TooltipTrigger asChild>
+                                <Button
+                                  variant="ghost"
+                                  size="icon"
+                                  className="h-6 w-6 min-h-9 min-w-9 sm:min-h-0 sm:min-w-0"
+                                  disabled={i === queue.length - 1}
+                                  onClick={() => handleMoveDown(i)}
+                                  aria-label={`下移 ${track.title}`}
+                                >
+                                  <ChevronDown className="h-3 w-3" />
+                                </Button>
+                              </TooltipTrigger>
+                              <TooltipContent side="bottom">下移</TooltipContent>
+                            </Tooltip>
+
+                            <Tooltip delayDuration={400}>
+                              <TooltipTrigger asChild>
+                                <Button
+                                  variant="ghost"
+                                  size="icon"
+                                  className="h-6 w-6 min-h-9 min-w-9 sm:min-h-0 sm:min-w-0"
+                                  onClick={(e) => handleInsertAfterCurrent(track, e)}
+                                  aria-label={`置顶 ${track.title}`}
+                                >
+                                  <ArrowUpToLine className="h-3 w-3" />
+                                </Button>
+                              </TooltipTrigger>
+                              <TooltipContent side="bottom">置顶到当前播放下方</TooltipContent>
+                            </Tooltip>
+                          </>
+                        )}
+
+                        {(canRemoveTrack || canVote) && (
+                          <Tooltip delayDuration={400}>
+                            <TooltipTrigger asChild>
+                              <Button
+                                variant="ghost"
+                                size="icon"
+                                className="h-6 w-6 min-h-9 min-w-9 sm:min-h-0 sm:min-w-0 text-destructive hover:text-destructive"
+                                onClick={() => handleRemoveTrack(track)}
+                                aria-label={canRemoveTrack ? `移除 ${track.title}` : `投票移除 ${track.title}`}
+                              >
+                                <Trash2 className="h-3 w-3" />
+                              </Button>
+                            </TooltipTrigger>
+                            <TooltipContent side="bottom">{canRemoveTrack ? '移除' : '投票移除'}</TooltipContent>
+                          </Tooltip>
+                        )}
+                      </div>
+                    </div>
+                  </div>
+                )
+              })}
+            </div>
+          )}
+        </div>
+      </DrawerContent>
+      <BilibiliMetadataDialog
+        track={metadataTrack}
+        roomId={roomId}
+        onOpenChange={(isOpen) => !isOpen && setMetadataTrack(null)}
+        onSelect={(metadata, metadataSource) => {
+          if (!metadataTrack) return
+          onUpdateBilibiliMetadata(metadataTrack.id, {
+            metadataSource,
+            lyricId: metadata.lyricId,
+            picId: metadata.picId,
+            cover: metadata.cover || metadataTrack.cover,
+          })
+          setMetadataTrack(null)
+        }}
+        onSkip={() => {
+          if (!metadataTrack) return
+          onUpdateBilibiliMetadata(metadataTrack.id, { clearMetadata: true })
+          setMetadataTrack(null)
+        }}
+      />
+    </Drawer>
+  )
+}

packages/client/src/components/Overlays/SearchDialog.tsx

@@ -0,0 +1,720 @@
+import { Button } from '@/components/ui/button'
+import {
+  ResponsiveDialog,
+  ResponsiveDialogBody,
+  ResponsiveDialogContent,
+  ResponsiveDialogHeader,
+  ResponsiveDialogTitle,
+} from '@/components/ui/responsive-dialog'
+import { Input } from '@/components/ui/input'
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs'
+import { VirtualTrackList, type VirtualTrackListRef } from '@/components/VirtualTrackList'
+import { PLATFORM_ACTIVE, PLATFORM_TEXT } from '@/lib/platform'
+import { cn, trackKey } from '@/lib/utils'
+import { useRoomStore } from '@/stores/roomStore'
+import { useSearch } from '@/hooks/useSearch'
+import { useRecommendations } from '@/hooks/useRecommendations'
+import { usePlaylist } from '@/hooks/usePlaylist'
+import { useIsMobile } from '@/hooks/useIsMobile'
+import { useSocketContext } from '@/providers/socket-context'
+import { EVENTS, LIMITS } from '@music-together/shared'
+import type { MusicSource, Track, Playlist } from '@music-together/shared'
+import type { BilibiliMetadataSource } from '@music-together/shared'
+import { Loader2, Music2, Search, ListMusic, Radio, RefreshCw, Sparkles } from 'lucide-react'
+import { motion } from 'motion/react'
+import { useCallback, useLayoutEffect, useMemo, useRef, useState, useEffect } from 'react'
+import { toast } from 'sonner'
+import { PlaylistDetail } from './Settings/PlaylistDetail'
+import { BilibiliCollectionDialog } from './BilibiliCollectionDialog'
+import { BilibiliMetadataDialog } from './BilibiliMetadataDialog'
+
+const EMPTY_QUEUE: Track[] = []
+type BilibiliQueueAction = 'add' | 'insert'
+type SearchMode = 'song' | 'album' | 'playlist' | 'recommend'
+type TencentRecommendationView = 'radar' | 'playlists'
+
+const SOURCES: { id: MusicSource; label: string }[] = [
+  { id: 'netease', label: '网易云' },
+  { id: 'tencent', label: 'QQ' },
+  { id: 'kugou', label: '酷狗' },
+  { id: 'kugou_concept', label: '概念版' },
+  { id: 'bilibili', label: 'B站' },
+]
+
+interface SearchDialogProps {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  onAddToQueue: (track: Track) => void
+  onInsertAfterCurrent: (track: Track) => void
+}
+
+interface PlaylistListProps {
+  playlists: Playlist[]
+  onSelect: (playlist: Playlist) => void
+  hasMore?: boolean
+  loadingMore?: boolean
+  onLoadMore?: () => void
+}
+
+function PlaylistList({ playlists, onSelect, hasMore, loadingMore, onLoadMore }: PlaylistListProps) {
+  return (
+    <div className="min-h-0 flex-1 overflow-y-auto rounded-md border p-2">
+      <div className="flex flex-col gap-2">
+        {playlists.map((playlist, index) => (
+          <button
+            key={`${playlist.source}-${playlist.id}-${index}`}
+            className="hover:bg-accent flex w-full min-w-0 items-center gap-3 overflow-hidden rounded-lg p-2 text-left transition-colors"
+            onClick={() => onSelect(playlist)}
+          >
+            {playlist.cover ? (
+              <img
+                src={playlist.cover}
+                alt={playlist.name}
+                referrerPolicy="no-referrer"
+                className="h-12 w-12 shrink-0 rounded-md object-cover"
+                loading="lazy"
+              />
+            ) : (
+              <div className="bg-muted flex h-12 w-12 shrink-0 items-center justify-center rounded-md">
+                <ListMusic className="text-muted-foreground h-5 w-5" />
+              </div>
+            )}
+            <div className="min-w-0 flex-1">
+              <p className="truncate text-sm font-medium">{playlist.name}</p>
+              <p className="text-muted-foreground truncate text-xs">
+                {[
+                  playlist.trackCount > 0 || !['kugou', 'kugou_concept'].includes(playlist.source)
+                    ? `${playlist.trackCount} 首`
+                    : '',
+                  playlist.creator,
+                ]
+                  .filter(Boolean)
+                  .join(' · ')}
+              </p>
+            </div>
+          </button>
+        ))}
+        {hasMore && onLoadMore && (
+          <Button variant="ghost" size="sm" className="mt-2 w-full" onClick={onLoadMore} disabled={loadingMore}>
+            {loadingMore ? <Loader2 className="mr-2 h-4 w-4 animate-spin" /> : null}
+            {loadingMore ? '加载中...' : '加载更多'}
+          </Button>
+        )}
+      </div>
+    </div>
+  )
+}
+
+export function SearchDialog({ open, onOpenChange, onAddToQueue, onInsertAfterCurrent }: SearchDialogProps) {
+  const [source, setSource] = useState<MusicSource>('netease')
+  const [searchType, setSearchType] = useState<SearchMode>('song')
+  const [tencentRecommendationView, setTencentRecommendationView] = useState<TencentRecommendationView>('radar')
+  const [bilibiliMatch, setBilibiliMatch] = useState<{ track: Track; action: BilibiliQueueAction } | null>(null)
+  const [bilibiliCollectionMatch, setBilibiliCollectionMatch] = useState<{
+    track: Track
+    action: BilibiliQueueAction
+  } | null>(null)
+  const [keyword, setKeyword] = useState('')
+  const [addedIds, setAddedIds] = useState<Set<string>>(new Set())
+  const listRef = useRef<VirtualTrackListRef>(null)
+  const dialogContentRef = useRef<HTMLDivElement>(null)
+  const sourceContainerRef = useRef<HTMLDivElement>(null)
+  const [pillStyle, setPillStyle] = useState({ left: 0, width: 0 })
+  const queue = useRoomStore((s) => s.room?.queue ?? EMPTY_QUEUE)
+  const roomId = useRoomStore((s) => s.room?.id)
+  const queueKeys = useMemo(() => new Set(queue.map(trackKey)), [queue])
+  const { socket } = useSocketContext()
+  const isMobile = useIsMobile()
+
+  // Mobile browsers can pan the visual viewport when the keyboard focuses the
+  // search input, which moves even fixed drawers above the visible screen.
+  // Keep this search drawer pinned to the actual visible viewport instead.
+  useLayoutEffect(() => {
+    if (!open || !isMobile) return
+
+    const content = dialogContentRef.current
+    const viewport = window.visualViewport
+    if (!content || !viewport) return
+
+    let frame = 0
+    const syncToVisualViewport = () => {
+      cancelAnimationFrame(frame)
+      frame = requestAnimationFrame(() => {
+        content.style.setProperty('top', `${Math.max(0, viewport.offsetTop)}px`, 'important')
+        content.style.setProperty('bottom', 'auto', 'important')
+        content.style.setProperty('height', `${viewport.height}px`, 'important')
+        content.style.setProperty('max-height', `${viewport.height}px`, 'important')
+      })
+    }
+
+    syncToVisualViewport()
+    viewport.addEventListener('resize', syncToVisualViewport)
+    viewport.addEventListener('scroll', syncToVisualViewport)
+
+    return () => {
+      cancelAnimationFrame(frame)
+      viewport.removeEventListener('resize', syncToVisualViewport)
+      viewport.removeEventListener('scroll', syncToVisualViewport)
+      content.style.removeProperty('top')
+      content.style.removeProperty('bottom')
+      content.style.removeProperty('height')
+      content.style.removeProperty('max-height')
+    }
+  }, [open, isMobile])
+
+  // Album Detail view state
+  const [selectedAlbum, setSelectedAlbum] = useState<Playlist | null>(null)
+  const {
+    playlistTracks,
+    playlistTotal,
+    tracksLoading,
+    loadingMore: albumLoadingMore,
+    hasMoreTracks,
+    fetchPlaylistTracks,
+    loadMoreTracks,
+    fetchAllPlaylistTracks,
+  } = usePlaylist()
+
+  const { results, loading, loadingMore, hasMore, hasSearched, search, loadMore, resetState } = useSearch(
+    source,
+    searchType === 'recommend' ? 'song' : searchType,
+    roomId,
+  )
+  const {
+    recommendations,
+    loading: recommendationsLoading,
+    loadingMore: recommendationsLoadingMore,
+    loaded: recommendationsLoaded,
+    load: loadRecommendations,
+    loadMore: loadMoreRecommendations,
+    reset: resetRecommendations,
+  } = useRecommendations(roomId)
+  const activeRecommendation = useMemo(
+    () => recommendations.find((recommendation) => recommendation.platform === source),
+    [recommendations, source],
+  )
+  const visibleSources = useMemo(() => {
+    if (searchType !== 'recommend') return SOURCES
+    if (!recommendationsLoaded) return SOURCES
+    const available = new Set(recommendations.map((recommendation) => recommendation.platform))
+    return SOURCES.filter((item) => available.has(item.id))
+  }, [recommendations, recommendationsLoaded, searchType])
+
+  // Auto re-search when source or type changes
+  const prevSourceRef = useRef(source)
+  const prevTypeRef = useRef(searchType)
+  useEffect(() => {
+    const sourceChanged = prevSourceRef.current !== source
+    const typeChanged = prevTypeRef.current !== searchType
+    prevSourceRef.current = source
+    prevTypeRef.current = searchType
+    if ((sourceChanged || typeChanged) && searchType !== 'recommend' && keyword.trim()) {
+      search(keyword.trim())
+      if (searchType === 'song') listRef.current?.scrollToTop()
+    }
+  }, [source, searchType, keyword, search])
+
+  useEffect(() => {
+    if (open && searchType === 'recommend' && !recommendationsLoaded && !recommendationsLoading) {
+      loadRecommendations()
+    }
+  }, [loadRecommendations, open, recommendationsLoaded, recommendationsLoading, searchType])
+
+  useEffect(() => {
+    if (searchType !== 'recommend' || !recommendationsLoaded || recommendations.length === 0) return
+    if (!recommendations.some((recommendation) => recommendation.platform === source)) {
+      const frame = requestAnimationFrame(() => setSource(recommendations[0]!.platform))
+      return () => cancelAnimationFrame(frame)
+    }
+  }, [recommendations, recommendationsLoaded, searchType, source])
+
+  // Measure active source button position for sliding pill
+  const measurePill = useCallback(() => {
+    const container = sourceContainerRef.current
+    if (!container) return
+    const activeBtn = container.querySelector<HTMLButtonElement>(`[data-source="${source}"]`)
+    if (!activeBtn) return
+    setPillStyle({ left: activeBtn.offsetLeft, width: activeBtn.offsetWidth })
+  }, [source])
+
+  useLayoutEffect(() => {
+    measurePill()
+  }, [measurePill, visibleSources])
+
+  // Re-measure after dialog opens (DOM may not be ready on first render)
+  useEffect(() => {
+    if (open) requestAnimationFrame(measurePill)
+  }, [open, measurePill])
+
+  useEffect(() => {
+    if (open) return
+    const frame = requestAnimationFrame(() => {
+      setSelectedAlbum(null)
+      resetRecommendations()
+    })
+    return () => cancelAnimationFrame(frame)
+  }, [open, resetRecommendations])
+
+  const handleSearch = (overrideKeyword?: string) => {
+    const searchKeyword = (overrideKeyword ?? keyword).trim()
+    if (!searchKeyword) return
+    if (overrideKeyword !== undefined) setKeyword(overrideKeyword)
+    setAddedIds(new Set())
+    search(searchKeyword)
+    if (searchType === 'song') {
+      listRef.current?.scrollToTop()
+    }
+  }
+
+  const beginBilibiliMetadataMatch = useCallback((track: Track, action: BilibiliQueueAction) => {
+    setBilibiliMatch({ track, action })
+  }, [])
+
+  const beginBilibiliCollectionMatch = useCallback((track: Track, action: BilibiliQueueAction) => {
+    setBilibiliCollectionMatch({ track, action })
+  }, [])
+
+  const handleBilibiliNotCollection = useCallback(() => {
+    if (!bilibiliCollectionMatch) return
+    const { track, action } = bilibiliCollectionMatch
+    setBilibiliCollectionMatch(null)
+    beginBilibiliMetadataMatch(track, action)
+  }, [bilibiliCollectionMatch, beginBilibiliMetadataMatch])
+
+  const handleBilibiliCollectionTrack = useCallback(
+    (track: Track) => {
+      if (!bilibiliCollectionMatch) return
+      // Close the picker before opening the metadata dialog. Both dialogs use
+      // the same portal z-index, so leaving it open would cover the matcher.
+      const { action } = bilibiliCollectionMatch
+      setBilibiliCollectionMatch(null)
+      beginBilibiliMetadataMatch(track, action)
+    },
+    [bilibiliCollectionMatch, beginBilibiliMetadataMatch],
+  )
+
+  const applyBilibiliMetadataMatch = useCallback(
+    (metadataTrack: Track, metadataSource: BilibiliMetadataSource) => {
+      if (!bilibiliMatch) return
+      const track = {
+        ...bilibiliMatch.track,
+        metadataSource,
+        lyricId: metadataTrack.lyricId,
+        picId: metadataTrack.picId,
+        cover: metadataTrack.cover || bilibiliMatch.track.cover,
+      }
+      if (bilibiliMatch.action === 'insert') {
+        onInsertAfterCurrent(track)
+      } else {
+        onAddToQueue(track)
+      }
+      setAddedIds((prev) => new Set(prev).add(trackKey(track)))
+      setBilibiliMatch(null)
+    },
+    [bilibiliMatch, onAddToQueue, onInsertAfterCurrent],
+  )
+
+  const skipBilibiliMetadataMatch = useCallback(() => {
+    if (!bilibiliMatch) return
+    if (bilibiliMatch.action === 'insert') {
+      onInsertAfterCurrent(bilibiliMatch.track)
+    } else {
+      onAddToQueue(bilibiliMatch.track)
+    }
+    setAddedIds((prev) => new Set(prev).add(trackKey(bilibiliMatch.track)))
+    setBilibiliMatch(null)
+  }, [bilibiliMatch, onAddToQueue, onInsertAfterCurrent])
+
+  const handleAdd = useCallback(
+    (track: Track) => {
+      const key = trackKey(track)
+      if (queueKeys.has(key) || addedIds.has(key)) {
+        toast.info(`「${track.title}」已在队列中`)
+        return
+      }
+      if (track.source === 'bilibili') {
+        beginBilibiliCollectionMatch(track, 'add')
+        return
+      }
+      onAddToQueue(track)
+      setAddedIds((prev) => new Set(prev).add(key))
+      // Removed duplicate toast.success since onAddToQueue (from useQueue) usually already handles it
+      // or the UI handles feedback.
+    },
+    [onAddToQueue, queueKeys, addedIds, beginBilibiliCollectionMatch],
+  )
+
+  const handleInsertAfterCurrent = useCallback(
+    (track: Track) => {
+      const key = trackKey(track)
+      if (queueKeys.has(key) || addedIds.has(key)) {
+        toast.info(`「${track.title}」已在队列中`)
+        return
+      }
+      if (track.source === 'bilibili') {
+        beginBilibiliCollectionMatch(track, 'insert')
+        return
+      }
+      onInsertAfterCurrent(track)
+      setAddedIds((prev) => new Set(prev).add(key))
+      // Removed duplicate toast.success
+    },
+    [onInsertAfterCurrent, queueKeys, addedIds, beginBilibiliCollectionMatch],
+  )
+
+  const handleAddBatch = useCallback(
+    (tracks: Track[], playlistName?: string) => {
+      if (tracks.length === 0) return
+      for (let offset = 0; offset < tracks.length; offset += LIMITS.QUEUE_BATCH_MAX_SIZE) {
+        socket.emit(EVENTS.QUEUE_ADD_BATCH, {
+          tracks: tracks.slice(offset, offset + LIMITS.QUEUE_BATCH_MAX_SIZE),
+          playlistName,
+        })
+      }
+      setAddedIds((prev) => {
+        const next = new Set(prev)
+        for (const t of tracks) next.add(trackKey(t))
+        return next
+      })
+      toast.success(`已添加 ${tracks.length} 首歌曲`)
+    },
+    [socket],
+  )
+
+  const isTrackAdded = useCallback(
+    (track: Track) => {
+      const key = trackKey(track)
+      return addedIds.has(key) || queueKeys.has(key)
+    },
+    [addedIds, queueKeys],
+  )
+
+  const handleSelectAlbum = (playlist: Playlist, type?: 'album' | 'playlist') => {
+    setSelectedAlbum(playlist)
+    fetchPlaylistTracks(
+      playlist.source,
+      playlist.id,
+      playlist.trackCount,
+      type ?? (searchType === 'album' ? 'album' : 'playlist'),
+    )
+  }
+
+  return (
+    <ResponsiveDialog open={open} onOpenChange={onOpenChange} mobileRepositionInputs={false}>
+      <ResponsiveDialogContent
+        ref={dialogContentRef}
+        className="flex h-dvh max-h-dvh flex-col overflow-hidden sm:h-auto sm:max-h-[80vh] sm:max-w-2xl"
+      >
+        <ResponsiveDialogHeader>
+          <div className="flex items-center gap-3">
+            <ResponsiveDialogTitle className="shrink-0">
+              {selectedAlbum ? selectedAlbum.name : searchType === 'recommend' ? '推荐点歌' : '搜索点歌'}
+            </ResponsiveDialogTitle>
+            {!selectedAlbum && visibleSources.length > 0 && (
+              <div ref={sourceContainerRef} className="bg-muted/50 relative flex items-center rounded-lg p-0.5">
+                <motion.div
+                  className={cn('absolute inset-y-0.5 rounded-md', PLATFORM_ACTIVE[source])}
+                  animate={{ left: pillStyle.left, width: pillStyle.width }}
+                  transition={{ type: 'spring', bounce: 0.15, duration: 0.3 }}
+                />
+                {visibleSources.map((s) => (
+                  <button
+                    key={s.id}
+                    data-source={s.id}
+                    className={cn(
+                      'relative z-10 rounded-md px-2.5 py-0.5 text-xs font-medium transition-colors',
+                      source === s.id ? PLATFORM_TEXT[s.id] : 'text-muted-foreground hover:text-foreground',
+                    )}
+                    onClick={() => {
+                      setSource(s.id)
+                      if (
+                        (s.id === 'bilibili' || s.id === 'kugou_concept') &&
+                        (searchType === 'album' || searchType === 'playlist')
+                      ) {
+                        setSearchType('song')
+                      }
+                      resetState()
+                      setAddedIds(new Set())
+                    }}
+                  >
+                    {s.label}
+                  </button>
+                ))}
+              </div>
+            )}
+          </div>
+        </ResponsiveDialogHeader>
+
+        <ResponsiveDialogBody className="flex min-h-0 flex-1 flex-col gap-4 overflow-hidden">
+          {selectedAlbum ? (
+            <PlaylistDetail
+              playlist={selectedAlbum}
+              tracks={playlistTracks}
+              loading={tracksLoading}
+              loadingMore={albumLoadingMore}
+              hasMore={hasMoreTracks}
+              total={playlistTotal}
+              onBack={() => setSelectedAlbum(null)}
+              onAddTrack={handleAdd}
+              onInsertAfterCurrent={handleInsertAfterCurrent}
+              onAddAll={handleAddBatch}
+              onLoadAll={fetchAllPlaylistTracks}
+              onLoadMore={loadMoreTracks}
+            />
+          ) : (
+            <>
+              <Tabs
+                value={searchType}
+                onValueChange={(value) => {
+                  setSearchType(value as SearchMode)
+                  resetState()
+                  setAddedIds(new Set())
+                }}
+              >
+                <TabsList className="w-full">
+                  <TabsTrigger value="song" className="flex-1 text-xs sm:text-sm">
+                    单曲
+                  </TabsTrigger>
+                  <TabsTrigger value="recommend" className="flex-1 gap-1 text-xs sm:text-sm">
+                    <Sparkles className="h-3.5 w-3.5" />
+                    推荐
+                  </TabsTrigger>
+                  {source !== 'bilibili' && source !== 'kugou_concept' && (
+                    <>
+                      <TabsTrigger value="album" className="flex-1 text-xs sm:text-sm">
+                        专辑
+                      </TabsTrigger>
+                      <TabsTrigger value="playlist" className="flex-1 text-xs sm:text-sm">
+                        歌单
+                      </TabsTrigger>
+                    </>
+                  )}
+                </TabsList>
+              </Tabs>
+
+              {searchType === 'recommend' ? (
+                <div className="bg-muted/40 flex items-center justify-between gap-3 rounded-lg border px-3 py-2">
+                  <div className="flex min-w-0 items-center gap-2 text-sm">
+                    <Sparkles className={cn('h-4 w-4 shrink-0', PLATFORM_TEXT[source])} />
+                    <span className="truncate">展示当前账号在平台上的原生推荐内容</span>
+                  </div>
+                  <Button
+                    variant="ghost"
+                    size="sm"
+                    onClick={() => loadRecommendations()}
+                    disabled={recommendationsLoading || recommendationsLoadingMore}
+                    aria-label="刷新推荐"
+                  >
+                    <RefreshCw className={cn('h-4 w-4', recommendationsLoading && 'animate-spin')} />
+                  </Button>
+                </div>
+              ) : (
+                <div className="flex gap-2">
+                  <Input
+                    placeholder={
+                      source === 'bilibili'
+                        ? '搜索视频，或粘贴 B站链接 / BV号...'
+                        : searchType === 'song'
+                          ? '搜索歌曲、歌手...'
+                          : searchType === 'album'
+                            ? '搜索专辑...'
+                            : '搜索歌单...'
+                    }
+                    value={keyword}
+                    onChange={(e) => setKeyword(e.target.value)}
+                    onKeyDown={(e) => e.key === 'Enter' && handleSearch()}
+                    className="flex-1"
+                    autoFocus
+                    aria-label="搜索关键词"
+                  />
+                  <Button onClick={() => handleSearch()} disabled={loading} aria-label="搜索">
+                    {loading ? <Loader2 className="h-4 w-4 animate-spin" /> : <Search className="h-4 w-4" />}
+                  </Button>
+                </div>
+              )}
+
+              {/* Results area — virtual scrolling with auto-load */}
+              {searchType === 'recommend' ? (
+                !recommendationsLoaded || recommendationsLoading ? (
+                  <div className="flex min-h-0 flex-1 items-center justify-center rounded-md border">
+                    <Loader2 className="text-muted-foreground h-6 w-6 animate-spin" />
+                  </div>
+                ) : recommendations.length === 0 ? (
+                  <div className="flex min-h-0 flex-1 items-center justify-center rounded-md border">
+                    <div className="text-muted-foreground flex h-48 flex-col items-center justify-center gap-2 px-6 text-center">
+                      <Sparkles className="h-8 w-8" />
+                      <span className="text-sm">请先在设置中登录音乐平台，再查看平台推荐</span>
+                    </div>
+                  </div>
+                ) : source === 'bilibili' ? (
+                  <VirtualTrackList
+                    ref={listRef}
+                    tracks={activeRecommendation?.tracks ?? []}
+                    loading={false}
+                    hasMore={false}
+                    loadingMore={false}
+                    onLoadMore={() => undefined}
+                    isTrackAdded={isTrackAdded}
+                    onAddTrack={handleAdd}
+                    onInsertAfterCurrent={handleInsertAfterCurrent}
+                    onArtistClick={(artist) => {
+                      setSearchType('song')
+                      handleSearch(artist)
+                    }}
+                    emptyIcon={<Sparkles className="h-8 w-8" />}
+                    emptyMessage={
+                      activeRecommendation?.unavailableReason === 'upstream_unavailable'
+                        ? '平台推荐暂时不可用，请刷新重试'
+                        : '平台暂时没有返回推荐内容'
+                    }
+                  />
+                ) : source === 'tencent' ? (
+                  <Tabs
+                    value={tencentRecommendationView}
+                    onValueChange={(value) => setTencentRecommendationView(value as TencentRecommendationView)}
+                    className="min-h-0 flex-1 gap-2"
+                  >
+                    <TabsList className="grid w-full grid-cols-2">
+                      <TabsTrigger value="radar">
+                        <Radio />
+                        雷达歌曲
+                      </TabsTrigger>
+                      <TabsTrigger value="playlists">
+                        <ListMusic />
+                        推荐歌单
+                      </TabsTrigger>
+                    </TabsList>
+                    <TabsContent value="radar" className="flex min-h-0 flex-1 flex-col">
+                      <VirtualTrackList
+                        ref={listRef}
+                        tracks={activeRecommendation?.tracks ?? []}
+                        loading={false}
+                        hasMore={activeRecommendation?.pagination?.tracks?.hasMore ?? false}
+                        loadingMore={recommendationsLoadingMore}
+                        onLoadMore={loadMoreRecommendations}
+                        isTrackAdded={isTrackAdded}
+                        onAddTrack={handleAdd}
+                        onInsertAfterCurrent={handleInsertAfterCurrent}
+                        onArtistClick={(artist) => {
+                          setSearchType('song')
+                          handleSearch(artist)
+                        }}
+                        emptyIcon={<Radio className="h-8 w-8" />}
+                        emptyMessage={
+                          activeRecommendation?.unavailableReason === 'upstream_unavailable'
+                            ? 'QQ 雷达暂时不可用，请刷新重试'
+                            : 'QQ 雷达暂时没有返回歌曲'
+                        }
+                      />
+                    </TabsContent>
+                    <TabsContent value="playlists" className="flex min-h-0 flex-1 flex-col">
+                      {(activeRecommendation?.playlists?.length ?? 0) > 0 ? (
+                        <PlaylistList
+                          playlists={activeRecommendation?.playlists ?? []}
+                          onSelect={(playlist) => handleSelectAlbum(playlist, 'playlist')}
+                          hasMore={activeRecommendation?.pagination?.playlists?.hasMore ?? false}
+                          loadingMore={recommendationsLoadingMore}
+                          onLoadMore={loadMoreRecommendations}
+                        />
+                      ) : (
+                        <div className="flex min-h-0 flex-1 items-center justify-center rounded-md border">
+                          <div className="text-muted-foreground flex h-48 flex-col items-center justify-center gap-2 px-6 text-center">
+                            <ListMusic className="h-8 w-8" />
+                            <span className="text-sm">
+                              {activeRecommendation?.unavailableReason === 'upstream_unavailable'
+                                ? 'QQ 推荐歌单暂时不可用，请刷新重试'
+                                : 'QQ 暂时没有返回推荐歌单'}
+                            </span>
+                          </div>
+                        </div>
+                      )}
+                    </TabsContent>
+                  </Tabs>
+                ) : (activeRecommendation?.playlists?.length ?? 0) > 0 ? (
+                  <PlaylistList
+                    playlists={activeRecommendation?.playlists ?? []}
+                    onSelect={(playlist) => handleSelectAlbum(playlist, 'playlist')}
+                  />
+                ) : (
+                  <div className="flex min-h-0 flex-1 items-center justify-center rounded-md border">
+                    <div className="text-muted-foreground flex h-48 flex-col items-center justify-center gap-2 px-6 text-center">
+                      <Sparkles className="h-8 w-8" />
+                      <span className="text-sm">
+                        {activeRecommendation?.unavailableReason === 'upstream_unavailable'
+                          ? '平台推荐暂时不可用，请刷新重试'
+                          : '平台暂时没有返回推荐歌单'}
+                      </span>
+                    </div>
+                  </div>
+                )
+              ) : hasSearched ? (
+                searchType === 'song' ? (
+                  <VirtualTrackList
+                    ref={listRef}
+                    tracks={results as Track[]}
+                    loading={loading}
+                    hasMore={hasMore}
+                    loadingMore={loadingMore}
+                    onLoadMore={loadMore}
+                    isTrackAdded={isTrackAdded}
+                    onAddTrack={handleAdd}
+                    onInsertAfterCurrent={handleInsertAfterCurrent}
+                    onArtistClick={(artist) => {
+                      setSearchType('song')
+                      handleSearch(artist)
+                    }}
+                    emptyIcon={<Music2 className="h-8 w-8" />}
+                    emptyMessage={
+                      source === 'bilibili' ? '暂无结果，请检查链接、BV号或更换关键词' : '暂无结果，换个关键词试试'
+                    }
+                  />
+                ) : loading && results.length === 0 ? (
+                  <div className="flex min-h-0 flex-1 items-center justify-center rounded-md border">
+                    <Loader2 className="h-6 w-6 animate-spin text-muted-foreground" />
+                  </div>
+                ) : results.length === 0 ? (
+                  <div className="flex min-h-0 flex-1 items-center justify-center rounded-md border">
+                    <div className="flex h-48 flex-col items-center justify-center gap-2 text-muted-foreground">
+                      <Music2 className="h-8 w-8" />
+                      <span className="text-sm">暂无结果，换个关键词试试</span>
+                    </div>
+                  </div>
+                ) : (
+                  <PlaylistList
+                    playlists={results as Playlist[]}
+                    onSelect={handleSelectAlbum}
+                    hasMore={hasMore}
+                    loadingMore={loadingMore}
+                    onLoadMore={loadMore}
+                  />
+                )
+              ) : (
+                <div className="min-h-0 flex-1 overflow-y-auto rounded-md border">
+                  <div className="flex h-48 flex-col items-center justify-center gap-2 text-muted-foreground">
+                    <Music2 className="h-8 w-8" />
+                    <span className="text-sm">输入关键词开始搜索</span>
+                  </div>
+                </div>
+              )}
+            </>
+          )}
+        </ResponsiveDialogBody>
+      </ResponsiveDialogContent>
+
+      <BilibiliMetadataDialog
+        track={bilibiliMatch?.track ?? null}
+        roomId={roomId}
+        onOpenChange={(isOpen) => !isOpen && setBilibiliMatch(null)}
+        onSelect={applyBilibiliMetadataMatch}
+        onSkip={skipBilibiliMetadataMatch}
+      />
+      <BilibiliCollectionDialog
+        track={bilibiliCollectionMatch?.track ?? null}
+        onOpenChange={(isOpen) => !isOpen && setBilibiliCollectionMatch(null)}
+        onSelectTrack={handleBilibiliCollectionTrack}
+        onNotCollection={handleBilibiliNotCollection}
+        isTrackAdded={isTrackAdded}
+      />
+    </ResponsiveDialog>
+  )
+}

packages/client/src/components/Overlays/Settings/AccountSection.tsx

@@ -0,0 +1,273 @@
+import { Badge } from '@/components/ui/badge'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import { Separator } from '@/components/ui/separator'
+import { loginIdentity, logoutIdentity, setInitialPassword, updateAccountId } from '@/lib/identityAuth'
+import { useSocketContext } from '@/providers/socket-context'
+import { useAccountStore } from '@/stores/accountStore'
+import { Check, Copy, KeyRound, Loader2, LogIn, LogOut, Pencil, ShieldCheck, X } from 'lucide-react'
+import { useEffect, useState } from 'react'
+import { toast } from 'sonner'
+
+const ACCOUNT_ID_PATTERN = /^[a-z0-9_-]{3,32}$/
+
+export function AccountIdEditor({ compact = false, onComplete }: { compact?: boolean; onComplete?: () => void }) {
+  const { socket } = useSocketContext()
+  const profile = useAccountStore((state) => state.profile)
+  const [editing, setEditing] = useState(!compact)
+  const [accountId, setAccountId] = useState(profile?.id ?? '')
+  const [currentPassword, setCurrentPassword] = useState('')
+  const [saving, setSaving] = useState(false)
+
+  useEffect(() => {
+    setAccountId(profile?.id ?? '')
+  }, [profile?.id])
+
+  const copyAccountId = async () => {
+    if (!profile?.id) return
+    await navigator.clipboard.writeText(profile.id)
+    toast.success('账号 ID 已复制')
+  }
+
+  const cancel = () => {
+    setAccountId(profile?.id ?? '')
+    setCurrentPassword('')
+    setEditing(false)
+  }
+
+  const save = async () => {
+    const normalized = accountId.trim().toLowerCase()
+    if (!ACCOUNT_ID_PATTERN.test(normalized) || normalized === profile?.id) return
+    setSaving(true)
+    try {
+      await updateAccountId(socket, normalized, currentPassword || undefined)
+      setCurrentPassword('')
+      setEditing(!compact)
+      toast.success('账号 ID 已修改')
+      onComplete?.()
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : '账号 ID 修改失败')
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  if (compact && !editing) {
+    return (
+      <div className="flex items-center justify-between gap-3">
+        <div className="min-w-0">
+          <span className="text-xs font-medium text-muted-foreground">账号 ID</span>
+          <code className="block truncate text-[11px]">{profile?.id ?? '初始化中'}</code>
+        </div>
+        <Button type="button" variant="outline" size="icon" className="h-8 w-8" onClick={() => setEditing(true)}>
+          <Pencil className="h-4 w-4" />
+          <span className="sr-only">修改账号 ID</span>
+        </Button>
+      </div>
+    )
+  }
+
+  const normalized = accountId.trim().toLowerCase()
+  const canSave =
+    ACCOUNT_ID_PATTERN.test(normalized) &&
+    normalized !== profile?.id &&
+    (!profile?.hasPassword || currentPassword.length > 0)
+
+  return (
+    <div className="space-y-2">
+      <div className="flex items-center justify-between gap-2">
+        <label
+          htmlFor={compact ? 'compact-account-id' : 'account-id'}
+          className="text-xs font-medium text-muted-foreground"
+        >
+          账号 ID
+        </label>
+        {!compact && (
+          <Button type="button" variant="ghost" size="icon" className="h-7 w-7" onClick={() => void copyAccountId()}>
+            <Copy className="h-3.5 w-3.5" />
+            <span className="sr-only">复制账号 ID</span>
+          </Button>
+        )}
+      </div>
+      <Input
+        id={compact ? 'compact-account-id' : 'account-id'}
+        value={accountId}
+        onChange={(event) => setAccountId(event.target.value.toLowerCase())}
+        placeholder="3-32 位小写字母、数字、_ 或 -"
+        maxLength={32}
+        className="h-8 font-mono text-xs"
+      />
+      {profile?.hasPassword && (
+        <Input
+          type="password"
+          value={currentPassword}
+          onChange={(event) => setCurrentPassword(event.target.value)}
+          onKeyDown={(event) => event.key === 'Enter' && canSave && void save()}
+          placeholder="当前密码"
+          maxLength={128}
+          className="h-8"
+        />
+      )}
+      <div className="flex justify-end gap-2">
+        {compact && (
+          <Button type="button" variant="ghost" size="sm" className="h-8" onClick={cancel} disabled={saving}>
+            <X className="h-4 w-4" />
+            取消
+          </Button>
+        )}
+        <Button type="button" size="sm" className="h-8" onClick={() => void save()} disabled={saving || !canSave}>
+          {saving ? <Loader2 className="h-4 w-4 animate-spin" /> : <Check className="h-4 w-4" />}
+          保存 ID
+        </Button>
+      </div>
+    </div>
+  )
+}
+
+export function AccountAccessControls({ compact = false, onComplete }: { compact?: boolean; onComplete?: () => void }) {
+  const { socket } = useSocketContext()
+  const profile = useAccountStore((state) => state.profile)
+  const [newPassword, setNewPassword] = useState('')
+  const [accountId, setAccountId] = useState('')
+  const [loginPassword, setLoginPassword] = useState('')
+  const [busy, setBusy] = useState(false)
+
+  const run = async (action: () => Promise<unknown>, success: string) => {
+    setBusy(true)
+    try {
+      await action()
+      setNewPassword('')
+      setLoginPassword('')
+      toast.success(success)
+      onComplete?.()
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : '账号操作失败')
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  if (profile?.hasPassword) {
+    return (
+      <div className="flex items-center justify-between gap-3">
+        <div className="flex min-w-0 items-center gap-2 text-sm">
+          <ShieldCheck className="h-4 w-4 shrink-0 text-emerald-600" />
+          <span className="truncate">账号已启用密码</span>
+        </div>
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          disabled={busy}
+          onClick={() => void run(() => logoutIdentity(socket), '已退出账号并切换到访客身份')}
+        >
+          {busy ? <Loader2 className="h-4 w-4 animate-spin" /> : <LogOut className="h-4 w-4" />}
+          退出
+        </Button>
+      </div>
+    )
+  }
+
+  return (
+    <div className={compact ? 'space-y-3' : 'space-y-5'}>
+      <div className="space-y-2">
+        <div className="flex items-center gap-2 text-sm font-medium">
+          <KeyRound className="h-4 w-4" />
+          保护当前账号
+        </div>
+        <div className="flex gap-2">
+          <Input
+            type="password"
+            value={newPassword}
+            onChange={(event) => setNewPassword(event.target.value)}
+            placeholder="设置密码（至少 8 位）"
+            minLength={8}
+            maxLength={128}
+            className="h-8"
+          />
+          <Button
+            type="button"
+            size="sm"
+            className="h-8"
+            disabled={busy || newPassword.length < 8}
+            onClick={() => void run(() => setInitialPassword(newPassword), '账号密码已设置')}
+          >
+            设置
+          </Button>
+        </div>
+      </div>
+
+      <Separator />
+
+      <div className="space-y-2">
+        <div className="flex items-center gap-2 text-sm font-medium">
+          <LogIn className="h-4 w-4" />
+          登录已有账号
+        </div>
+        <Input
+          value={accountId}
+          onChange={(event) => setAccountId(event.target.value)}
+          placeholder="账号 ID"
+          className="h-8 font-mono text-xs"
+        />
+        <div className="flex gap-2">
+          <Input
+            type="password"
+            value={loginPassword}
+            onChange={(event) => setLoginPassword(event.target.value)}
+            onKeyDown={(event) => {
+              if (event.key === 'Enter' && accountId.trim() && loginPassword) {
+                void run(() => loginIdentity(socket, accountId, loginPassword), '账号登录成功')
+              }
+            }}
+            placeholder="密码"
+            className="h-8"
+          />
+          <Button
+            type="button"
+            size="sm"
+            className="h-8"
+            disabled={busy || !accountId.trim() || !loginPassword}
+            onClick={() => void run(() => loginIdentity(socket, accountId, loginPassword), '账号登录成功')}
+          >
+            {busy ? <Loader2 className="h-4 w-4 animate-spin" /> : '登录'}
+          </Button>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export function AccountSection() {
+  const profile = useAccountStore((state) => state.profile)
+
+  if (!profile) {
+    return (
+      <div className="mx-auto w-full max-w-xl space-y-2">
+        <h3 className="text-base font-semibold">账号</h3>
+        <p className="text-sm text-muted-foreground">请先在个人资料中保存昵称，系统随后会生成账号 ID。</p>
+      </div>
+    )
+  }
+
+  return (
+    <div className="mx-auto w-full max-w-xl space-y-6">
+      <div>
+        <div className="flex items-center justify-between gap-3">
+          <div>
+            <h3 className="text-base font-semibold">账号</h3>
+            <p className="mt-1 text-xs text-muted-foreground">
+              {profile?.hasPassword ? '已登录账号' : '当前为访客身份'}
+            </p>
+          </div>
+          {profile?.role === 'admin' && <Badge variant="secondary">服务器管理员</Badge>}
+        </div>
+        <Separator className="mt-3" />
+      </div>
+
+      <AccountIdEditor />
+
+      <AccountAccessControls />
+    </div>
+  )
+}

packages/client/src/components/Overlays/Settings/AdminSection.tsx

@@ -0,0 +1,602 @@
+import { Badge } from '@/components/ui/badge'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
+import { Slider } from '@/components/ui/slider'
+import { Switch } from '@/components/ui/switch'
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs'
+import { useSocketEvent } from '@/hooks/useSocketEvent'
+import { requestJson } from '@/lib/identityAuth'
+import { useAccountStore } from '@/stores/accountStore'
+import { SERVER_URL } from '@/lib/config'
+import { EVENTS, type AudioProxyPolicy, type ColorPreset, type GlobalBackgroundSettings } from '@music-together/shared'
+import { DoorClosed, ImagePlus, Link2, Loader2, Network, RefreshCw, Trash2, Upload, Users, X } from 'lucide-react'
+import { useCallback, useEffect, useState } from 'react'
+import { toast } from 'sonner'
+import { SettingRow } from './SettingRow'
+
+interface AdminUser {
+  id: string
+  nickname: string
+  avatarUrl: string | null
+  role: 'user' | 'admin'
+  hasPassword: boolean
+  createdAt: number
+  updatedAt: number
+  lastSeenAt: number
+}
+
+interface AdminRoom {
+  id: string
+  name: string
+  creatorId: string
+  userCount: number
+  hasPassword: boolean
+  hidden: boolean
+  permanent: boolean
+  currentTrackTitle: string | null
+}
+
+export function AdminSection() {
+  const currentUserId = useAccountStore((state) => state.profile?.id)
+  const [users, setUsers] = useState<AdminUser[]>([])
+  const [rooms, setRooms] = useState<AdminRoom[]>([])
+  const [audioProxyPolicy, setAudioProxyPolicy] = useState<AudioProxyPolicy>({
+    kugouForceProxy: true,
+  })
+  const [globalBackground, setGlobalBackground] = useState<GlobalBackgroundSettings>({
+    backgroundUrl: null,
+    glassOverlay: false,
+    colorPreset: 'gold',
+    backgroundBrightness: 60,
+    autoTint: false,
+  })
+  const [passwords, setPasswords] = useState<Record<string, string>>({})
+  const [loading, setLoading] = useState(true)
+  const [workingId, setWorkingId] = useState<string | null>(null)
+  const [updatingProxyPolicy, setUpdatingProxyPolicy] = useState(false)
+  const [updatingBackground, setUpdatingBackground] = useState(false)
+  const [backgroundUrlInput, setBackgroundUrlInput] = useState('')
+
+  const load = useCallback(async () => {
+    setLoading(true)
+    try {
+      const [userData, roomData, proxyPolicy, background] = await Promise.all([
+        requestJson<{ users: AdminUser[] }>('/api/admin/users'),
+        requestJson<{ rooms: AdminRoom[] }>('/api/admin/rooms'),
+        requestJson<AudioProxyPolicy>('/api/admin/audio-proxy-policy'),
+        requestJson<GlobalBackgroundSettings>('/api/admin/background'),
+      ])
+      setUsers(userData.users)
+      setRooms(roomData.rooms)
+      setAudioProxyPolicy(proxyPolicy)
+      setGlobalBackground(background)
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : '管理员数据加载失败')
+    } finally {
+      setLoading(false)
+    }
+  }, [])
+
+  useEffect(() => {
+    void load()
+  }, [load])
+
+  useSocketEvent(EVENTS.SERVER_AUDIO_PROXY_POLICY, setAudioProxyPolicy)
+
+  const updateAudioProxyPolicy = async (checked: boolean) => {
+    setUpdatingProxyPolicy(true)
+    try {
+      const policy = await requestJson<AudioProxyPolicy>('/api/admin/audio-proxy-policy', {
+        method: 'PATCH',
+        body: JSON.stringify({ kugouForceProxy: checked }),
+      })
+      setAudioProxyPolicy(policy)
+      toast.success('音频代理策略已更新')
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : '音频代理策略更新失败')
+    } finally {
+      setUpdatingProxyPolicy(false)
+    }
+  }
+
+  const uploadBackground = async (file?: File) => {
+    if (!file) return
+    if (!['image/png', 'image/jpeg', 'image/webp'].includes(file.type)) {
+      toast.error('仅支持 PNG、JPEG 和 WebP 图片')
+      return
+    }
+    if (file.size > 6 * 1024 * 1024) {
+      toast.error('背景图片不能超过 6MB')
+      return
+    }
+
+    setUpdatingBackground(true)
+    try {
+      const image = await new Promise<string>((resolve, reject) => {
+        const reader = new FileReader()
+        reader.onload = () => resolve(String(reader.result))
+        reader.onerror = () => reject(new Error('读取图片失败'))
+        reader.readAsDataURL(file)
+      })
+      const settings = await requestJson<GlobalBackgroundSettings>('/api/admin/background', {
+        method: 'POST',
+        body: JSON.stringify({ image }),
+      })
+      setGlobalBackground(settings)
+      toast.success('全局背景已更新')
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : '背景上传失败')
+    } finally {
+      setUpdatingBackground(false)
+    }
+  }
+
+  const removeBackground = async () => {
+    if (!window.confirm('确定移除全局背景吗？')) return
+    setUpdatingBackground(true)
+    try {
+      const settings = await requestJson<GlobalBackgroundSettings>('/api/admin/background', { method: 'DELETE' })
+      setGlobalBackground(settings)
+      toast.success('全局背景已移除')
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : '背景移除失败')
+    } finally {
+      setUpdatingBackground(false)
+    }
+  }
+
+  const updateGlassOverlay = async (glassOverlay: boolean) => {
+    setUpdatingBackground(true)
+    try {
+      const settings = await requestJson<GlobalBackgroundSettings>('/api/admin/background', {
+        method: 'PATCH',
+        body: JSON.stringify({ glassOverlay }),
+      })
+      setGlobalBackground(settings)
+      toast.success(glassOverlay ? '毛玻璃遮罩已开启' : '毛玻璃遮罩已关闭')
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : '毛玻璃设置更新失败')
+    } finally {
+      setUpdatingBackground(false)
+    }
+  }
+
+  const updateColorPreset = async (colorPreset: ColorPreset) => {
+    setUpdatingBackground(true)
+    try {
+      const settings = await requestJson<GlobalBackgroundSettings>('/api/admin/background', {
+        method: 'PATCH',
+        body: JSON.stringify({ colorPreset }),
+      })
+      setGlobalBackground(settings)
+      toast.success('全局配色已更新')
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : '全局配色更新失败')
+    } finally {
+      setUpdatingBackground(false)
+    }
+  }
+
+  const updateBackgroundBrightness = async (backgroundBrightness: number) => {
+    setUpdatingBackground(true)
+    try {
+      const settings = await requestJson<GlobalBackgroundSettings>('/api/admin/background', {
+        method: 'PATCH',
+        body: JSON.stringify({ backgroundBrightness }),
+      })
+      setGlobalBackground(settings)
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : '背景亮度更新失败')
+    } finally {
+      setUpdatingBackground(false)
+    }
+  }
+
+  const updateAutoTint = async (autoTint: boolean) => {
+    setUpdatingBackground(true)
+    try {
+      const settings = await requestJson<GlobalBackgroundSettings>('/api/admin/background', {
+        method: 'PATCH',
+        body: JSON.stringify({ autoTint }),
+      })
+      setGlobalBackground(settings)
+      toast.success(autoTint ? '自动适配背景色调已开启' : '自动适配背景色调已关闭')
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : '自动色调设置更新失败')
+    } finally {
+      setUpdatingBackground(false)
+    }
+  }
+
+  const applyBackgroundUrl = async () => {
+    const imageUrl = backgroundUrlInput.trim()
+    if (!imageUrl) return
+    try {
+      const parsedUrl = new URL(imageUrl)
+      if (!['http:', 'https:'].includes(parsedUrl.protocol)) throw new Error('图片 URL 必须使用 HTTP 或 HTTPS')
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : '图片 URL 格式无效')
+      return
+    }
+
+    setUpdatingBackground(true)
+    try {
+      const settings = await requestJson<GlobalBackgroundSettings>('/api/admin/background', {
+        method: 'POST',
+        body: JSON.stringify({ imageUrl }),
+      })
+      setGlobalBackground(settings)
+      setBackgroundUrlInput('')
+      toast.success('全局背景已从 URL 更新')
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : '图片 URL 获取失败')
+    } finally {
+      setUpdatingBackground(false)
+    }
+  }
+
+  const backgroundPreview = globalBackground.backgroundUrl
+    ? globalBackground.backgroundUrl.startsWith('/uploads/')
+      ? `${SERVER_URL}${globalBackground.backgroundUrl}`
+      : globalBackground.backgroundUrl
+    : null
+
+  const deleteUser = async (user: AdminUser) => {
+    if (!window.confirm(`确定删除账号 ${user.id}？`)) return
+    setWorkingId(user.id)
+    try {
+      await requestJson<void>(`/api/admin/users/${encodeURIComponent(user.id)}`, { method: 'DELETE' })
+      toast.success('账号已删除')
+      await load()
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : '删除失败')
+    } finally {
+      setWorkingId(null)
+    }
+  }
+
+  const resetPassword = async (user: AdminUser) => {
+    const password = passwords[user.id] ?? ''
+    if (password.length < 8) return
+    setWorkingId(user.id)
+    try {
+      await requestJson<void>(`/api/admin/users/${encodeURIComponent(user.id)}/reset-password`, {
+        method: 'POST',
+        body: JSON.stringify({ password }),
+      })
+      setPasswords((current) => ({ ...current, [user.id]: '' }))
+      toast.success('密码已重置')
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : '密码重置失败')
+    } finally {
+      setWorkingId(null)
+    }
+  }
+
+  const dissolveRoom = async (room: AdminRoom) => {
+    if (!window.confirm(`确定解散房间 ${room.name}（${room.id}）？`)) return
+    setWorkingId(room.id)
+    try {
+      await requestJson<void>(`/api/admin/rooms/${encodeURIComponent(room.id)}/dissolve`, { method: 'POST' })
+      toast.success('房间已解散')
+      await load()
+    } catch (error) {
+      toast.error(error instanceof Error ? error.message : '解散房间失败')
+    } finally {
+      setWorkingId(null)
+    }
+  }
+
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center justify-between gap-3">
+        <div>
+          <h3 className="text-base font-semibold">服务器管理</h3>
+          <p className="mt-1 text-xs text-muted-foreground">
+            账号 {users.length} · 活跃房间 {rooms.length}
+          </p>
+        </div>
+        <Button type="button" variant="outline" size="icon" className="h-8 w-8" onClick={() => void load()}>
+          <RefreshCw className={loading ? 'h-4 w-4 animate-spin' : 'h-4 w-4'} />
+          <span className="sr-only">刷新</span>
+        </Button>
+      </div>
+
+      <Tabs defaultValue="users">
+        <TabsList className="w-full">
+          <TabsTrigger value="users">
+            <Users />
+            账号
+          </TabsTrigger>
+          <TabsTrigger value="rooms">
+            <DoorClosed />
+            房间
+          </TabsTrigger>
+          <TabsTrigger value="background">
+            <ImagePlus />
+            背景
+          </TabsTrigger>
+          <TabsTrigger value="proxy">
+            <Network />
+            代理
+          </TabsTrigger>
+        </TabsList>
+
+        <TabsContent value="users" className="space-y-0 divide-y rounded-md border">
+          {loading ? (
+            <div className="flex h-24 items-center justify-center">
+              <Loader2 className="h-5 w-5 animate-spin" />
+            </div>
+          ) : users.length === 0 ? (
+            <p className="p-6 text-center text-sm text-muted-foreground">暂无账号</p>
+          ) : (
+            users.map((user) => (
+              <div key={user.id} className="space-y-3 p-3">
+                <div className="flex items-start justify-between gap-3">
+                  <div className="min-w-0">
+                    <div className="flex items-center gap-2">
+                      <span className="truncate text-sm font-medium">{user.nickname || '未设置昵称'}</span>
+                      {user.role === 'admin' && <Badge variant="secondary">管理员</Badge>}
+                      {user.hasPassword && <Badge variant="outline">有密码</Badge>}
+                    </div>
+                    <code className="block truncate text-[11px] text-muted-foreground">{user.id}</code>
+                  </div>
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="icon"
+                    className="h-8 w-8 text-destructive"
+                    disabled={workingId === user.id || currentUserId === user.id}
+                    onClick={() => void deleteUser(user)}
+                  >
+                    <Trash2 className="h-4 w-4" />
+                    <span className="sr-only">删除账号</span>
+                  </Button>
+                </div>
+                <div className="flex gap-2">
+                  <Input
+                    type="password"
+                    value={passwords[user.id] ?? ''}
+                    onChange={(event) => setPasswords((current) => ({ ...current, [user.id]: event.target.value }))}
+                    placeholder="新密码（至少 8 位）"
+                    className="h-8"
+                  />
+                  <Button
+                    type="button"
+                    variant="outline"
+                    size="sm"
+                    className="h-8"
+                    disabled={workingId === user.id || (passwords[user.id]?.length ?? 0) < 8}
+                    onClick={() => void resetPassword(user)}
+                  >
+                    重置密码
+                  </Button>
+                </div>
+              </div>
+            ))
+          )}
+        </TabsContent>
+
+        <TabsContent value="rooms" className="space-y-0 divide-y rounded-md border">
+          {loading ? (
+            <div className="flex h-24 items-center justify-center">
+              <Loader2 className="h-5 w-5 animate-spin" />
+            </div>
+          ) : rooms.length === 0 ? (
+            <p className="p-6 text-center text-sm text-muted-foreground">暂无活跃房间</p>
+          ) : (
+            rooms.map((room) => (
+              <div key={room.id} className="flex items-center justify-between gap-3 p-3">
+                <div className="min-w-0">
+                  <div className="flex items-center gap-2">
+                    <span className="truncate text-sm font-medium">{room.name}</span>
+                    <Badge variant="outline">{room.userCount} 人</Badge>
+                    {room.hasPassword && <Badge variant="secondary">密码</Badge>}
+                    <Badge variant={room.hidden ? 'secondary' : 'outline'}>{room.hidden ? '隐藏' : '公开'}</Badge>
+                    <Badge variant={room.permanent ? 'secondary' : 'outline'}>{room.permanent ? '永久' : '临时'}</Badge>
+                  </div>
+                  <p className="truncate text-xs text-muted-foreground">
+                    {room.id}
+                    {room.currentTrackTitle ? ` · ${room.currentTrackTitle}` : ''}
+                  </p>
+                </div>
+                <Button
+                  type="button"
+                  variant="destructive"
+                  size="sm"
+                  disabled={workingId === room.id}
+                  onClick={() => void dissolveRoom(room)}
+                >
+                  解散
+                </Button>
+              </div>
+            ))
+          )}
+        </TabsContent>
+
+        <TabsContent value="background" className="rounded-md border p-3">
+          {loading ? (
+            <div className="flex h-24 items-center justify-center">
+              <Loader2 className="h-5 w-5 animate-spin" />
+            </div>
+          ) : (
+            <div className="space-y-3">
+              <div className="overflow-hidden rounded-md border bg-muted/40">
+                {backgroundPreview ? (
+                  <img src={backgroundPreview} alt="当前全局背景" className="h-32 w-full object-cover" />
+                ) : (
+                  <div className="flex h-32 flex-col items-center justify-center gap-2 text-muted-foreground">
+                    <ImagePlus className="h-5 w-5" />
+                    <span className="text-xs">未设置全局背景</span>
+                  </div>
+                )}
+              </div>
+              <p className="text-xs leading-relaxed text-muted-foreground">
+                所有首页和房间页使用同一张背景图。上传后会压缩为 WebP 并保存到服务器数据目录。
+              </p>
+              <div className="flex gap-2">
+                <label>
+                  <input
+                    type="file"
+                    accept="image/png,image/jpeg,image/webp"
+                    className="sr-only"
+                    disabled={updatingBackground}
+                    onChange={(event) => {
+                      void uploadBackground(event.currentTarget.files?.[0])
+                      event.currentTarget.value = ''
+                    }}
+                  />
+                  <Button asChild type="button" size="sm" disabled={updatingBackground}>
+                    <span>
+                      {updatingBackground ? (
+                        <Loader2 className="h-4 w-4 animate-spin" />
+                      ) : (
+                        <Upload className="h-4 w-4" />
+                      )}
+                      上传背景
+                    </span>
+                  </Button>
+                </label>
+                {backgroundPreview && (
+                  <Button
+                    type="button"
+                    variant="outline"
+                    size="sm"
+                    disabled={updatingBackground}
+                    onClick={() => void removeBackground()}
+                  >
+                    <X className="h-4 w-4" />
+                    移除
+                  </Button>
+                )}
+              </div>
+              <div className="flex items-center justify-between gap-3 rounded-md border p-2">
+                <div>
+                  <p className="text-sm font-medium">颜色预设</p>
+                  <p className="text-xs text-muted-foreground">与背景搭配的全站强调色</p>
+                </div>
+                <Select
+                  value={globalBackground.colorPreset}
+                  disabled={updatingBackground}
+                  onValueChange={(value) => void updateColorPreset(value as ColorPreset)}
+                >
+                  <SelectTrigger className="w-32">
+                    <SelectValue />
+                  </SelectTrigger>
+                  <SelectContent>
+                    <SelectItem value="gold">金色暖调</SelectItem>
+                    <SelectItem value="ocean">海洋青绿</SelectItem>
+                    <SelectItem value="rose">玫瑰粉</SelectItem>
+                    <SelectItem value="violet">夜幕紫</SelectItem>
+                    <SelectItem value="sunset">落日橙红</SelectItem>
+                    <SelectItem value="mint">薄荷青柠</SelectItem>
+                    <SelectItem value="mono">黑白银灰</SelectItem>
+                  </SelectContent>
+                </Select>
+              </div>
+              <div className="flex items-center gap-2 rounded-md border p-2">
+                <Switch
+                  checked={globalBackground.glassOverlay}
+                  disabled={updatingBackground}
+                  onCheckedChange={(checked) => void updateGlassOverlay(checked)}
+                  aria-label="毛玻璃遮罩"
+                />
+                <div className="min-w-0">
+                  <p className="text-sm font-medium">毛玻璃遮罩</p>
+                  <p className="text-xs text-muted-foreground">让背景更柔和，减少对页面内容的干扰</p>
+                </div>
+              </div>
+              <div className="space-y-2 rounded-md border p-2">
+                <div className="flex items-center justify-between gap-3">
+                  <div>
+                    <p className="text-sm font-medium">背景亮度</p>
+                    <p className="text-xs text-muted-foreground">只调整背景图片，不影响文字和卡片</p>
+                  </div>
+                  <span className="text-xs tabular-nums text-muted-foreground">
+                    {globalBackground.backgroundBrightness}%
+                  </span>
+                </div>
+                <Slider
+                  value={[globalBackground.backgroundBrightness]}
+                  min={20}
+                  max={100}
+                  step={1}
+                  disabled={updatingBackground}
+                  onValueChange={([value]) => {
+                    if (typeof value === 'number') {
+                      setGlobalBackground((current) => ({ ...current, backgroundBrightness: value }))
+                    }
+                  }}
+                  onValueCommit={([value]) => {
+                    if (typeof value === 'number') void updateBackgroundBrightness(value)
+                  }}
+                  aria-label="背景亮度"
+                />
+              </div>
+              <div className="flex items-center gap-2 rounded-md border p-2">
+                <Switch
+                  checked={globalBackground.autoTint}
+                  disabled={updatingBackground || !backgroundPreview}
+                  onCheckedChange={(checked) => void updateAutoTint(checked)}
+                  aria-label="自动适配背景色调"
+                />
+                <div className="min-w-0">
+                  <p className="text-sm font-medium">自动适配背景色调</p>
+                  <p className="text-xs text-muted-foreground">从背景图片提取平均色，叠加到背景光效中</p>
+                </div>
+              </div>
+              <div className="flex flex-col gap-2 sm:flex-row">
+                <Input
+                  value={backgroundUrlInput}
+                  onChange={(event) => setBackgroundUrlInput(event.target.value)}
+                  placeholder="图片 API / 图片 URL（返回图片文件）"
+                  disabled={updatingBackground}
+                  onKeyDown={(event) => {
+                    if (event.key === 'Enter') void applyBackgroundUrl()
+                  }}
+                />
+                <Button
+                  type="button"
+                  variant="outline"
+                  disabled={updatingBackground || !backgroundUrlInput.trim()}
+                  onClick={() => void applyBackgroundUrl()}
+                >
+                  {updatingBackground ? <Loader2 className="h-4 w-4 animate-spin" /> : <Link2 className="h-4 w-4" />}
+                  使用 URL
+                </Button>
+              </div>
+            </div>
+          )}
+        </TabsContent>
+
+        <TabsContent value="proxy" className="rounded-md border">
+          {loading ? (
+            <div className="flex h-24 items-center justify-center">
+              <Loader2 className="h-5 w-5 animate-spin" />
+            </div>
+          ) : (
+            <>
+              <div className="border-b bg-muted/40 p-3 text-xs leading-relaxed text-muted-foreground">
+                B 站始终通过服务器代理播放，Cookie 仅保留在服务端。酷狗开关仅影响原生客户端；Web 端始终使用服务器代理。
+              </div>
+              <div className="divide-y px-3">
+                <SettingRow
+                  label="酷狗强制服务器代理"
+                  description="同时控制标准版和概念版；关闭后明文资源优先直连，加密资源仍由服务器代理解密"
+                >
+                  <Switch
+                    checked={audioProxyPolicy.kugouForceProxy}
+                    disabled={updatingProxyPolicy}
+                    onCheckedChange={(checked) => void updateAudioProxyPolicy(checked)}
+                    aria-label="酷狗强制服务器代理"
+                  />
+                </SettingRow>
+              </div>
+            </>
+          )}
+        </TabsContent>
+      </Tabs>
+    </div>
+  )
+}

packages/client/src/components/Overlays/Settings/AppearanceSection.tsx

@@ -0,0 +1,69 @@
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
+import { Separator } from '@/components/ui/separator'
+import { Slider } from '@/components/ui/slider'
+import { useSettingsStore } from '@/stores/settingsStore'
+import { SettingRow } from './SettingRow'
+
+export function AppearanceSection() {
+  const s = useSettingsStore()
+
+  return (
+    <div className="space-y-6">
+      {/* ---- 背景渲染 ---- */}
+      <div>
+        <h3 className="text-base font-semibold">背景渲染</h3>
+        <Separator className="mt-2 mb-4" />
+
+        <SettingRow
+          label="帧率"
+          description="更高帧率更流畅，但消耗更多性能"
+          onReset={s.bgFps !== s.bgFpsDefault ? s.resetBgFps : undefined}
+        >
+          <Select value={String(s.bgFps)} onValueChange={(v) => s.setBgFps(parseInt(v, 10))}>
+            <SelectTrigger className="w-24">
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="15">15 FPS</SelectItem>
+              <SelectItem value="30">30 FPS</SelectItem>
+              <SelectItem value="60">60 FPS</SelectItem>
+            </SelectContent>
+          </Select>
+        </SettingRow>
+
+        <SettingRow
+          label="流动速度"
+          description={`当前: ${s.bgFlowSpeed.toFixed(1)}`}
+          onReset={s.bgFlowSpeed !== s.bgFlowSpeedDefault ? s.resetBgFlowSpeed : undefined}
+        >
+          <Slider
+            value={[s.bgFlowSpeed * 10]}
+            min={5}
+            max={50}
+            step={5}
+            onValueChange={(v) => s.setBgFlowSpeed(v[0] / 10)}
+            className="w-32"
+          />
+        </SettingRow>
+
+        <SettingRow
+          label="渲染精度"
+          description="更低精度更省性能"
+          onReset={s.bgRenderScale !== s.bgRenderScaleDefault ? s.resetBgRenderScale : undefined}
+        >
+          <Select value={String(s.bgRenderScale)} onValueChange={(v) => s.setBgRenderScale(parseFloat(v))}>
+            <SelectTrigger className="w-24">
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="0.25">25%</SelectItem>
+              <SelectItem value="0.5">50%</SelectItem>
+              <SelectItem value="0.75">75%</SelectItem>
+              <SelectItem value="1">100%</SelectItem>
+            </SelectContent>
+          </Select>
+        </SettingRow>
+      </div>
+    </div>
+  )
+}

packages/client/src/components/Overlays/Settings/LoginSection.tsx

@@ -0,0 +1,113 @@
+import { Badge } from '@/components/ui/badge'
+import { Button } from '@/components/ui/button'
+import { getVipDisplayLabel } from '@/lib/platform'
+import type { MusicSource, MyPlatformAuth, PlatformAuthStatus } from '@music-together/shared'
+import { Crown, Gift, KeyRound, Loader2, LogOut, ScanLine } from 'lucide-react'
+
+interface LoginSectionProps {
+  platform: MusicSource
+  status?: PlatformAuthStatus
+  myStatus?: MyPlatformAuth
+  /** localStorage has a cookie for this platform but server hasn't confirmed yet */
+  isVerifying?: boolean
+  onQrLogin: () => void
+  onCookieLogin: () => void
+  onLogout: () => void
+  compactLabel?: string
+  onClaimConceptVip?: () => void
+  isClaimingConceptVip?: boolean
+}
+
+export function LoginSection({
+  platform,
+  status,
+  myStatus,
+  isVerifying,
+  onQrLogin,
+  onCookieLogin,
+  onLogout,
+  compactLabel,
+  onClaimConceptVip,
+  isClaimingConceptVip,
+}: LoginSectionProps) {
+  const loggedInCount = status?.loggedInCount ?? 0
+  const hasVip = status?.hasVip ?? false
+  const maxVipType = status?.maxVipType ?? 0
+  const isMyLoggedIn = myStatus?.loggedIn ?? false
+  const displayedVipType = isMyLoggedIn ? (myStatus?.vipType ?? 0) : maxVipType
+  const displayedVipLabel = getVipDisplayLabel(
+    displayedVipType,
+    isMyLoggedIn ? myStatus?.vipLabel : status?.maxVipLabel,
+  )
+
+  return (
+    <div className="flex items-center justify-between gap-2 overflow-hidden rounded-lg border p-3">
+      <div className="min-w-0 flex-1 space-y-0.5">
+        <div className="flex min-w-0 items-center gap-2">
+          {compactLabel && <span className="text-muted-foreground shrink-0 text-xs">{compactLabel}</span>}
+          {isMyLoggedIn && myStatus?.nickname ? (
+            <span className="truncate text-sm font-medium">{myStatus.nickname}</span>
+          ) : isVerifying ? (
+            <span className="text-muted-foreground flex shrink-0 items-center gap-1.5 text-sm">
+              <Loader2 className="h-3 w-3 animate-spin" />
+              验证登录中…
+            </span>
+          ) : (
+            <span className="text-muted-foreground shrink-0 text-sm">未登录</span>
+          )}
+          {displayedVipType > 0 && (
+            <Badge variant="secondary" className="shrink-0 gap-1 text-xs">
+              <Crown className="h-3 w-3" />
+              {displayedVipLabel}
+            </Badge>
+          )}
+        </div>
+        <p className="text-muted-foreground truncate text-xs">
+          {loggedInCount > 0 ? `房间内 ${loggedInCount} 人已登录${hasVip ? '，VIP 可用' : ''}` : '房间暂无人登录此平台'}
+        </p>
+      </div>
+
+      <div className="flex shrink-0 items-center gap-1.5">
+        {!isMyLoggedIn && !isVerifying ? (
+          <>
+            {(platform === 'netease' ||
+              platform === 'kugou' ||
+              platform === 'kugou_concept' ||
+              platform === 'tencent' ||
+              platform === 'bilibili') && (
+              <Button variant="outline" size="icon" className="h-8 w-8" onClick={onQrLogin} title="扫码登录">
+                <ScanLine className="h-3.5 w-3.5" />
+              </Button>
+            )}
+            <Button variant="outline" size="icon" className="h-8 w-8" onClick={onCookieLogin} title="Cookie 登录">
+              <KeyRound className="h-3.5 w-3.5" />
+            </Button>
+          </>
+        ) : isMyLoggedIn ? (
+          <>
+            {platform === 'kugou_concept' && onClaimConceptVip && (
+              <Button
+                variant="outline"
+                size="sm"
+                className="h-8 gap-1 px-2 text-xs"
+                onClick={onClaimConceptVip}
+                disabled={isClaimingConceptVip}
+                title="手动领取酷狗官方每日概念版权益"
+              >
+                {isClaimingConceptVip ? (
+                  <Loader2 className="h-3.5 w-3.5 animate-spin" />
+                ) : (
+                  <Gift className="h-3.5 w-3.5" />
+                )}
+                领权益
+              </Button>
+            )}
+            <Button variant="ghost" size="icon" className="text-destructive h-8 w-8" onClick={onLogout} title="登出">
+              <LogOut className="h-3.5 w-3.5" />
+            </Button>
+          </>
+        ) : null}
+      </div>
+    </div>
+  )
+}

packages/client/src/components/Overlays/Settings/LyricsSection.tsx

@@ -0,0 +1,159 @@
+import { Input } from '@/components/ui/input'
+import { NumericInput } from '@/components/ui/numeric-input'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select'
+import { Separator } from '@/components/ui/separator'
+import { Slider } from '@/components/ui/slider'
+import { Switch } from '@/components/ui/switch'
+import { useSettingsStore } from '@/stores/settingsStore'
+import { SettingRow } from './SettingRow'
+
+export function LyricsSection() {
+  const s = useSettingsStore()
+
+  return (
+    <div className="space-y-6">
+      {/* ---- 歌词源 ---- */}
+      <div>
+        <h3 className="text-base font-semibold">歌词源</h3>
+        <Separator className="mt-2 mb-4" />
+
+        <SettingRow
+          label="TTML 在线逐词歌词"
+          description="启用 AMLL 逐词歌词库（仅网易云/QQ音乐）"
+          onReset={s.ttmlEnabled !== s.ttmlEnabledDefault ? s.resetTtmlEnabled : undefined}
+        >
+          <Switch checked={s.ttmlEnabled} onCheckedChange={s.setTtmlEnabled} />
+        </SettingRow>
+
+        {s.ttmlEnabled && (
+          <SettingRow
+            label="TTML 歌词库地址"
+            description="URL 模板，%s 会被替换为歌曲 ID，QQ 音乐自动替换 ncm-lyrics 为 qq-lyrics"
+            onReset={s.ttmlDbUrl !== s.ttmlDbUrlDefault ? s.resetTtmlDbUrl : undefined}
+          >
+            <Input
+              value={s.ttmlDbUrl}
+              onChange={(e) => s.setTtmlDbUrl(e.target.value)}
+              placeholder="https://amlldb.bikonoo.com/ncm-lyrics/%s.ttml"
+              className="w-64 text-xs"
+            />
+          </SettingRow>
+        )}
+      </div>
+
+      {/* ---- 歌词布局 ---- */}
+      <div>
+        <h3 className="text-base font-semibold">歌词布局</h3>
+        <Separator className="mt-2 mb-4" />
+
+        <SettingRow
+          label="对齐锚点"
+          description="当前歌词行在视口中的锚定方式"
+          onReset={s.lyricAlignAnchor !== s.lyricAlignAnchorDefault ? s.resetLyricAlignAnchor : undefined}
+        >
+          <Select
+            value={s.lyricAlignAnchor}
+            onValueChange={(v) => s.setLyricAlignAnchor(v as 'top' | 'center' | 'bottom')}
+          >
+            <SelectTrigger className="w-28">
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="top">顶部</SelectItem>
+              <SelectItem value="center">居中</SelectItem>
+              <SelectItem value="bottom">底部</SelectItem>
+            </SelectContent>
+          </Select>
+        </SettingRow>
+
+        <SettingRow
+          label="对齐位置"
+          description={`当前: ${Math.round(s.lyricAlignPosition * 100)}%`}
+          onReset={s.lyricAlignPosition !== s.lyricAlignPositionDefault ? s.resetLyricAlignPosition : undefined}
+        >
+          <Slider
+            value={[s.lyricAlignPosition * 100]}
+            min={0}
+            max={100}
+            step={5}
+            onValueChange={(v) => s.setLyricAlignPosition(v[0] / 100)}
+            className="w-32"
+          />
+        </SettingRow>
+
+      </div>
+
+      {/* ---- 歌词动画 ---- */}
+      <div>
+        <h3 className="text-base font-semibold">歌词动画</h3>
+        <Separator className="mt-2 mb-4" />
+
+        <SettingRow
+          label="弹簧动画"
+          description="歌词行切换时的弹簧物理效果"
+          onReset={s.lyricEnableSpring !== s.lyricEnableSpringDefault ? s.resetLyricEnableSpring : undefined}
+        >
+          <Switch checked={s.lyricEnableSpring} onCheckedChange={s.setLyricEnableSpring} />
+        </SettingRow>
+
+        <SettingRow
+          label="模糊效果"
+          description="非当前行歌词模糊"
+          onReset={s.lyricEnableBlur !== s.lyricEnableBlurDefault ? s.resetLyricEnableBlur : undefined}
+        >
+          <Switch checked={s.lyricEnableBlur} onCheckedChange={s.setLyricEnableBlur} />
+        </SettingRow>
+
+        <SettingRow
+          label="缩放效果"
+          description="当前行歌词放大突出显示"
+          onReset={s.lyricEnableScale !== s.lyricEnableScaleDefault ? s.resetLyricEnableScale : undefined}
+        >
+          <Switch checked={s.lyricEnableScale} onCheckedChange={s.setLyricEnableScale} />
+        </SettingRow>
+      </div>
+
+      {/* ---- 歌词字体 ---- */}
+      <div>
+        <h3 className="text-base font-semibold">歌词字体</h3>
+        <Separator className="mt-2 mb-4" />
+
+        <SettingRow
+          label="字体粗细"
+          description="字体粗细值（100-900）"
+          onReset={s.lyricFontWeight !== s.lyricFontWeightDefault ? s.resetLyricFontWeight : undefined}
+        >
+          <NumericInput value={s.lyricFontWeight} onChange={s.setLyricFontWeight} min={100} max={900} />
+        </SettingRow>
+
+        <SettingRow
+          label="字体大小"
+          description="主歌词字号比例（10-200）"
+          onReset={s.lyricFontSize !== s.lyricFontSizeDefault ? s.resetLyricFontSize : undefined}
+        >
+          <NumericInput value={s.lyricFontSize} onChange={s.setLyricFontSize} />
+        </SettingRow>
+
+        <SettingRow
+          label="翻译字体大小"
+          description="翻译歌词相对主歌词的字号比例（10-200）"
+          onReset={
+            s.lyricTranslationFontSize !== s.lyricTranslationFontSizeDefault
+              ? s.resetLyricTranslationFontSize
+              : undefined
+          }
+        >
+          <NumericInput value={s.lyricTranslationFontSize} onChange={s.setLyricTranslationFontSize} />
+        </SettingRow>
+
+        <SettingRow
+          label="罗马音字体大小"
+          description="罗马音歌词相对主歌词的字号比例（10-200）"
+          onReset={s.lyricRomanFontSize !== s.lyricRomanFontSizeDefault ? s.resetLyricRomanFontSize : undefined}
+        >
+          <NumericInput value={s.lyricRomanFontSize} onChange={s.setLyricRomanFontSize} />
+        </SettingRow>
+      </div>
+    </div>
+  )
+}