From 09c556093e2da2b571a5a48208d0d3c725f95d64 Mon Sep 17 00:00:00 2001
From: xyh202131 <246811510+xyh202131@users.noreply.github.com>
Date: Fri, 21 Aug 2026 17:50:39 +0800
Subject: [PATCH 1/2] =?UTF-8?q?feat(playtest):=20=E6=94=AF=E6=8C=81?=
 =?UTF-8?q?=E8=B4=A6=E5=8F=B7=E7=BA=A7=E6=9C=AC=E5=9C=B0=E9=94=AE=E4=BD=8D?=
 =?UTF-8?q?=E9=85=8D=E7=BD=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 frontend/src/pages/playtest/index.tsx         |   1 +
 .../pages/playtest/workbench/bindings.test.ts |  21 +-
 .../src/pages/playtest/workbench/bindings.ts  |  26 ++
 .../src/pages/playtest/workbench/index.tsx    | 295 +++++++++++++-----
 .../workbench/minimal-workbench.test.tsx      | 103 +++++-
 .../playtest/workbench/preferences.test.ts    | 126 ++++++++
 .../pages/playtest/workbench/preferences.ts   | 189 +++++++++++
 .../workbench/runtime/runtime.test.ts         |   6 +-
 .../playtest/workbench/runtime/runtime.ts     |   8 +-
 .../runtime/use-playtest-runtime.test.ts      |  35 +++
 .../workbench/runtime/use-playtest-runtime.ts |  61 +++-
 .../pages/playtest/workbench/stage.test.tsx   |  42 +++
 .../src/pages/playtest/workbench/stage.tsx    |  33 +-
 13 files changed, 842 insertions(+), 104 deletions(-)
 create mode 100644 frontend/src/pages/playtest/workbench/preferences.test.ts
 create mode 100644 frontend/src/pages/playtest/workbench/preferences.ts

diff --git a/frontend/src/pages/playtest/index.tsx b/frontend/src/pages/playtest/index.tsx
index 6a6a25c9..148a78c1 100644
--- a/frontend/src/pages/playtest/index.tsx
+++ b/frontend/src/pages/playtest/index.tsx
@@ -168,6 +168,7 @@ export function PlaytestPage({ renderToolbar }: PlaytestPageProps = {}) {
       outfitId={outfitId}
       movementMode={data.project.directionalMovement}
       initialActionId={initialActionId}
+      userId={recentOwnerId}
       toolbar={toolbar}
     />
   )
diff --git a/frontend/src/pages/playtest/workbench/bindings.test.ts b/frontend/src/pages/playtest/workbench/bindings.test.ts
index 6384a0cb..3e0f9fb9 100644
--- a/frontend/src/pages/playtest/workbench/bindings.test.ts
+++ b/frontend/src/pages/playtest/workbench/bindings.test.ts
@@ -1,7 +1,8 @@
 import { describe, expect, it } from 'vitest'
 
 import type { PlaytestAction } from './model'
-import { createDefaultActionBindings } from './bindings'
+import { createDefaultActionBindings, resolvePlaytestActionBindings } from './bindings'
+import { DEFAULT_PLAYTEST_PREFERENCES, setPlaytestActionType } from './preferences'
 
 function action(id: string, type: string): PlaytestAction {
   return {
@@ -67,4 +68,22 @@ describe('playtest action bindings', () => {
       shift: 'directional-crouch',
     })
   })
+
+  it('resolves persisted action types against each character instead of reusing action ids', () => {
+    const preferences = setPlaytestActionType(
+      DEFAULT_PLAYTEST_PREFERENCES,
+      'primary_action',
+      'attack',
+    )
+
+    expect(
+      resolvePlaytestActionBindings(
+        [action('character-2-attack', 'attack'), action('character-2-duck', 'duck')],
+        preferences,
+      ),
+    ).toEqual({
+      space: 'character-2-attack',
+      shift: 'character-2-duck',
+    })
+  })
 })
diff --git a/frontend/src/pages/playtest/workbench/bindings.ts b/frontend/src/pages/playtest/workbench/bindings.ts
index e6473779..30ca0488 100644
--- a/frontend/src/pages/playtest/workbench/bindings.ts
+++ b/frontend/src/pages/playtest/workbench/bindings.ts
@@ -1,4 +1,5 @@
 import { hasPlayableFrames, type PlaytestAction } from './model'
+import type { PlaytestPreferences } from './preferences'
 
 export const PLAYTEST_CONTROL_KEYS = ['space', 'shift'] as const
 
@@ -7,6 +8,10 @@ export type PlaytestActionBindings = Readonly<Record<PlaytestControlKey, string
 
 const CROUCH_TYPES = new Set(['crouch', 'duck', 'squat'])
 
+export function playtestPreferenceActionType(actionType: string): string {
+  return CROUCH_TYPES.has(actionType) ? 'crouch' : actionType
+}
+
 export function createDefaultActionBindings(
   actions: readonly PlaytestAction[],
 ): PlaytestActionBindings {
@@ -16,6 +21,27 @@ export function createDefaultActionBindings(
   }
 }
 
+export function resolvePlaytestActionBindings(
+  actions: readonly PlaytestAction[],
+  preferences: PlaytestPreferences,
+): PlaytestActionBindings {
+  return {
+    space:
+      findActionByPreferenceType(actions, preferences.bindings.primary_action.actionType ?? null)
+        ?.id ?? null,
+    shift:
+      findActionByPreferenceType(actions, preferences.bindings.secondary_action.actionType ?? null)
+        ?.id ?? null,
+  }
+}
+
+function findActionByPreferenceType(actions: readonly PlaytestAction[], actionType: string | null) {
+  if (actionType === null) return undefined
+  return findAction(actions, (action) => {
+    return playtestPreferenceActionType(action.type) === actionType
+  })
+}
+
 function findAction(
   actions: readonly PlaytestAction[],
   predicate: (action: PlaytestAction) => boolean,
diff --git a/frontend/src/pages/playtest/workbench/index.tsx b/frontend/src/pages/playtest/workbench/index.tsx
index f9d227ff..981285bf 100644
--- a/frontend/src/pages/playtest/workbench/index.tsx
+++ b/frontend/src/pages/playtest/workbench/index.tsx
@@ -1,13 +1,25 @@
-import { useEffect, useMemo, useState, type PointerEvent, type ReactNode } from 'react'
+import { useCallback, useEffect, useMemo, useState, type PointerEvent, type ReactNode } from 'react'
 
 import type { Character, DirectionalMovement } from '@/entities'
 
 import {
-  createDefaultActionBindings,
+  playtestPreferenceActionType,
   PLAYTEST_CONTROL_KEYS,
+  resolvePlaytestActionBindings,
   type PlaytestControlKey,
 } from './bindings'
 import { createPlaytestModel, type PlaytestModel } from './model'
+import {
+  PLAYTEST_COMMANDS,
+  readPlaytestPreferences,
+  rebindPlaytestCommand,
+  removePlaytestPreferences,
+  setPlaytestActionType,
+  writePlaytestPreferences,
+  type PlaytestActionCommand,
+  type PlaytestCommand,
+  type PlaytestPreferences,
+} from './preferences'
 import { usePlaytestRuntime } from './runtime/use-playtest-runtime'
 import { playbackForFacing, type MovementDirection } from './runtime/runtime'
 import { PlaytestStage } from './stage'
@@ -16,51 +28,75 @@ export interface PlaytestWorkbenchProps {
   readonly character: Character
   readonly outfitId: string
   readonly movementMode: DirectionalMovement
+  readonly userId?: string | null
   readonly initialActionId?: string | null
   readonly toolbar?: ReactNode
 }
 
-const controlLabels: Readonly<Record<PlaytestControlKey, string>> = {
-  space: '空格键',
-  shift: 'Shift 键',
-}
-
-const controlKeyLabels: Readonly<Record<PlaytestControlKey, string>> = {
-  space: 'Space',
-  shift: 'Shift',
-}
-
-const assignmentLabels: Readonly<Record<PlaytestControlKey, string>> = {
-  space: '空格键分配动作',
-  shift: 'Shift 分配动作',
-}
-
-const assignmentKeyWidths: Readonly<Record<PlaytestControlKey, string>> = {
-  space: 'w-14',
-  shift: 'w-12',
-}
-
-const controlButtonWidths: Readonly<Record<PlaytestControlKey, string>> = {
-  space: 'w-16',
-  shift: 'w-14',
+const actionControls: Readonly<
+  Record<PlaytestControlKey, { readonly command: PlaytestActionCommand; readonly label: string }>
+> = {
+  space: { command: 'primary_action', label: '主动作' },
+  shift: { command: 'secondary_action', label: '次动作' },
 }
 
 const movementControls: readonly {
-  key: 'w' | 'a' | 's' | 'd'
+  command: Extract<PlaytestCommand, `move_${string}`>
   direction: MovementDirection
   label: string
   gridClass: string
 }[] = [
-  { key: 'w', direction: 'up', label: '向上移动', gridClass: 'col-start-2 row-start-1' },
-  { key: 'a', direction: 'left', label: '向左移动', gridClass: 'col-start-1 row-start-2' },
-  { key: 's', direction: 'down', label: '向下移动', gridClass: 'col-start-2 row-start-2' },
-  { key: 'd', direction: 'right', label: '向右移动', gridClass: 'col-start-3 row-start-2' },
+  {
+    command: 'move_up',
+    direction: 'up',
+    label: '向上移动',
+    gridClass: 'col-start-2 row-start-1',
+  },
+  {
+    command: 'move_left',
+    direction: 'left',
+    label: '向左移动',
+    gridClass: 'col-start-1 row-start-2',
+  },
+  {
+    command: 'move_down',
+    direction: 'down',
+    label: '向下移动',
+    gridClass: 'col-start-2 row-start-2',
+  },
+  {
+    command: 'move_right',
+    direction: 'right',
+    label: '向右移动',
+    gridClass: 'col-start-3 row-start-2',
+  },
 ]
 
+const commandLabels: Readonly<Record<PlaytestCommand, string>> = {
+  move_up: '向上移动',
+  move_down: '向下移动',
+  move_left: '向左移动',
+  move_right: '向右移动',
+  primary_action: '主动作',
+  secondary_action: '次动作',
+}
+
+function keyLabel(code: string | null): string {
+  if (code === null) return '未绑定'
+  if (code.startsWith('Key')) return code.slice(3)
+  if (code.startsWith('Digit')) return code.slice(5)
+  if (code === 'Space') return 'Space'
+  if (code === 'ShiftLeft') return 'L Shift'
+  if (code === 'ShiftRight') return 'R Shift'
+  if (code.startsWith('Arrow')) return code.slice(5)
+  return code
+}
+
 export function PlaytestWorkbench({
   character,
   outfitId,
   movementMode,
+  userId = null,
   initialActionId = null,
   toolbar = null,
 }: PlaytestWorkbenchProps) {
@@ -83,6 +119,7 @@ export function PlaytestWorkbench({
     <PlaytestExperience
       model={result.model}
       movementMode={movementMode}
+      userId={userId}
       toolbar={toolbar}
       initialActionId={initialActionId}
     />
@@ -92,21 +129,87 @@ export function PlaytestWorkbench({
 function PlaytestExperience({
   model,
   movementMode,
+  userId,
   toolbar,
   initialActionId,
 }: {
   readonly model: PlaytestModel
   readonly movementMode: DirectionalMovement
+  readonly userId: string | null
   readonly toolbar: ReactNode
   readonly initialActionId: string | null
 }) {
-  const [bindings, setBindings] = useState(() => createDefaultActionBindings(model.actions))
-  const runtime = usePlaytestRuntime(model.actions, initialActionId, movementMode, bindings)
+  const [preferences, setPreferences] = useState<PlaytestPreferences>(() =>
+    readPlaytestPreferences(userId ?? ''),
+  )
+  const [capturing, setCapturing] = useState<PlaytestCommand | null>(null)
+  const [persistenceMessage, setPersistenceMessage] = useState(
+    userId === null ? '仅本次有效，未找到登录账号' : '键位仅保存在此浏览器',
+  )
+  const bindings = useMemo(
+    () => resolvePlaytestActionBindings(model.actions, preferences),
+    [model.actions, preferences],
+  )
+  const runtime = usePlaytestRuntime(model.actions, initialActionId, movementMode, bindings, {
+    preferences,
+    keyboardEnabled: capturing === null,
+  })
   const locomotion = model.actions.find((action) => action.type === 'walk' || action.type === 'run')
+  const actionChoices = useMemo(() => {
+    const choices = new Map<string, string>()
+    for (const action of model.actions) {
+      const type = playtestPreferenceActionType(action.type)
+      if (!choices.has(type)) choices.set(type, action.name)
+    }
+    return [...choices].map(([type, name]) => ({ type, name }))
+  }, [model.actions])
 
   useEffect(() => {
-    setBindings(createDefaultActionBindings(model.actions))
-  }, [model.actions])
+    setPreferences(readPlaytestPreferences(userId ?? ''))
+    setPersistenceMessage(userId === null ? '仅本次有效，未找到登录账号' : '键位仅保存在此浏览器')
+    setCapturing(null)
+  }, [userId])
+
+  const applyPreferences = useCallback(
+    (next: PlaytestPreferences) => {
+      setPreferences(next)
+      const saved = userId !== null && writePlaytestPreferences(userId, next)
+      setPersistenceMessage(saved ? '已保存到此浏览器' : '仅本次有效，浏览器未保存')
+    },
+    [userId],
+  )
+
+  useEffect(() => {
+    if (capturing === null) return
+    const captureKey = (event: globalThis.KeyboardEvent) => {
+      event.preventDefault()
+      event.stopPropagation()
+      if (event.code === 'Escape') {
+        setCapturing(null)
+        return
+      }
+      if (event.code === 'Delete' || event.code === 'Backspace') {
+        if (capturing === 'primary_action' || capturing === 'secondary_action') {
+          applyPreferences(rebindPlaytestCommand(preferences, capturing, null))
+          setCapturing(null)
+        }
+        return
+      }
+      if (!event.code) return
+      applyPreferences(rebindPlaytestCommand(preferences, capturing, event.code))
+      setCapturing(null)
+    }
+    window.addEventListener('keydown', captureKey, true)
+    return () => window.removeEventListener('keydown', captureKey, true)
+  }, [applyPreferences, capturing, preferences])
+
+  const resetPreferences = () => {
+    const next = readPlaytestPreferences('', null)
+    setPreferences(next)
+    const removed = userId !== null && removePlaytestPreferences(userId)
+    setPersistenceMessage(removed ? '已恢复此浏览器默认键位' : '仅本次有效，浏览器未保存')
+    setCapturing(null)
+  }
 
   const holdControl = (key: PlaytestControlKey, pressed: boolean, source: string) => {
     runtime.setControl(key, pressed, source)
@@ -147,7 +250,12 @@ function PlaytestExperience({
             </h1>
           </div>
           <div className="flex items-center gap-3">
-            <p className="text-xs text-app-muted">W / A / S / D 移动 · Space 跳跃 · Shift 下蹲</p>
+            <p className="text-xs text-app-muted">
+              {keyLabel(preferences.bindings.move_up.code)} /{' '}
+              {keyLabel(preferences.bindings.move_left.code)} /{' '}
+              {keyLabel(preferences.bindings.move_down.code)} /{' '}
+              {keyLabel(preferences.bindings.move_right.code)} 移动
+            </p>
             {toolbar}
           </div>
         </header>
@@ -168,7 +276,7 @@ function PlaytestExperience({
 
           <aside
             aria-label="动作绑定"
-            className="absolute left-4 top-4 w-[190px] rounded-2xl border border-app-surface-raised/55 bg-app-surface/95 p-2.5 shadow-app-stage-panel backdrop-blur-xl sm:left-5 sm:top-5 sm:w-[210px]"
+            className="absolute left-4 top-4 w-[250px] rounded-3xl border border-app-surface-raised/55 bg-app-surface/95 p-3 shadow-app-stage-panel backdrop-blur-xl sm:left-5 sm:top-5 sm:w-[270px]"
           >
             <p className="px-2 pb-2 font-mono text-[9px] font-semibold tracking-[0.16em] text-app-faint">
               BOUND ACTIONS
@@ -176,18 +284,20 @@ function PlaytestExperience({
             <div className="space-y-1">
               {model.actions.map((action) => {
                 const selected = action.id === runtime.runtime.actionId
+                const disabled = playbackForFacing(action, runtime.runtime.facing) === undefined
                 return (
                   <button
                     key={action.id}
                     type="button"
                     aria-label={`绑定动作：${action.name}`}
                     aria-pressed={selected}
+                    disabled={disabled}
                     onClick={() => runtime.selectAction(action.id)}
                     className={`flex w-full items-center justify-between rounded-xl px-3 py-2.5 text-left text-xs font-medium transition-colors ${
                       selected
                         ? 'bg-app-accent text-app-on-accent'
                         : 'text-app-ink-soft hover:bg-app-surface-muted'
-                    }`}
+                    } disabled:cursor-not-allowed disabled:opacity-35`}
                   >
                     <span>{action.name}</span>
                     <span
@@ -202,32 +312,70 @@ function PlaytestExperience({
             </div>
             <div className="mt-2 border-t border-app-line pt-2">
               <p className="px-2 pb-1.5 text-[10px] font-medium text-app-faint">按键分配</p>
-              <div className="space-y-1.5">
-                {PLAYTEST_CONTROL_KEYS.map((key) => (
-                  <label key={key} className="flex items-center gap-2 px-1">
-                    <span
-                      className={`grid h-7 shrink-0 place-items-center rounded-md border border-app-line bg-app-surface-raised font-mono text-[11px] font-semibold text-app-ink-soft ${assignmentKeyWidths[key]}`}
-                    >
-                      {controlKeyLabels[key]}
-                    </span>
-                    <select
-                      aria-label={assignmentLabels[key]}
-                      value={bindings[key] ?? ''}
-                      onChange={(event) => {
-                        const actionId = event.target.value || null
-                        setBindings((current) => ({ ...current, [key]: actionId }))
-                      }}
-                      className="h-7 min-w-0 flex-1 rounded-md border border-app-line bg-app-surface-raised px-2 text-[11px] text-app-ink outline-none focus:border-app-accent"
-                    >
-                      <option value="">未分配</option>
-                      {model.actions.map((action) => (
-                        <option key={action.id} value={action.id}>
-                          {action.name}
-                        </option>
-                      ))}
-                    </select>
-                  </label>
-                ))}
+              <div className="space-y-2">
+                {PLAYTEST_COMMANDS.map((command) => {
+                  const actionCommand =
+                    command === 'primary_action' || command === 'secondary_action'
+                  return (
+                    <div key={command} className="flex items-center gap-2 px-1">
+                      <button
+                        type="button"
+                        aria-label={`修改${commandLabels[command]}键位`}
+                        aria-pressed={capturing === command}
+                        onClick={() => setCapturing(command)}
+                        className={`min-w-14 shrink-0 rounded-full border px-2.5 py-1.5 font-mono text-[10px] font-semibold shadow-sm transition duration-150 active:translate-y-px active:scale-[0.98] motion-reduce:transform-none motion-reduce:transition-none ${
+                          capturing === command
+                            ? 'border-app-accent bg-app-accent/12 text-app-accent ring-4 ring-app-accent-soft'
+                            : 'border-app-line bg-app-surface-raised/85 text-app-ink-soft hover:border-app-line-strong hover:bg-app-surface-muted'
+                        }`}
+                      >
+                        {capturing === command
+                          ? '请按新键'
+                          : keyLabel(preferences.bindings[command].code)}
+                      </button>
+                      {actionCommand ? (
+                        <select
+                          aria-label={`${commandLabels[command]}分配动作`}
+                          value={preferences.bindings[command].actionType ?? ''}
+                          onChange={(event) =>
+                            applyPreferences(
+                              setPlaytestActionType(
+                                preferences,
+                                command,
+                                event.target.value || null,
+                              ),
+                            )
+                          }
+                          className="h-7 min-w-0 flex-1 rounded-full border border-app-line bg-app-surface-raised px-2 text-[11px] text-app-ink outline-none transition-colors focus:border-app-accent"
+                        >
+                          <option value="">未分配</option>
+                          {actionChoices.map((choice) => (
+                            <option key={choice.type} value={choice.type}>
+                              {choice.name}
+                            </option>
+                          ))}
+                        </select>
+                      ) : (
+                        <span className="truncate text-[10px] text-app-muted">
+                          {commandLabels[command]}
+                        </span>
+                      )}
+                    </div>
+                  )
+                })}
+              </div>
+              <div className="mt-2 flex items-center justify-between gap-2 border-t border-app-line px-1 pt-2">
+                <p aria-live="polite" className="text-[9px] leading-4 text-app-faint">
+                  {persistenceMessage}
+                </p>
+                <button
+                  type="button"
+                  aria-label="恢复默认键位"
+                  onClick={resetPreferences}
+                  className="shrink-0 rounded-full px-2 py-1 text-[9px] font-medium text-app-muted transition-colors hover:bg-app-surface-muted hover:text-app-ink"
+                >
+                  恢复默认
+                </button>
               </div>
             </div>
           </aside>
@@ -238,7 +386,7 @@ function PlaytestExperience({
             className="absolute bottom-4 left-1/2 flex -translate-x-1/2 items-center gap-3 rounded-2xl border border-app-surface-raised/60 bg-app-surface/95 p-2 shadow-app-float backdrop-blur-2xl sm:bottom-5"
           >
             <div className="grid grid-cols-3 grid-rows-2 gap-1.5">
-              {movementControls.map(({ key, direction, label, gridClass }) => {
+              {movementControls.map(({ command, direction, label, gridClass }) => {
                 const pressed = runtime.runtime.held[direction]
                 const facing =
                   direction === 'left'
@@ -257,7 +405,7 @@ function PlaytestExperience({
 
                 return (
                   <button
-                    key={key}
+                    key={command}
                     type="button"
                     aria-label={label}
                     aria-pressed={pressed}
@@ -280,13 +428,13 @@ function PlaytestExperience({
                         `pointer:${event.pointerId}:${direction}`,
                       )
                     }
-                    className={`${gridClass} grid h-9 w-11 touch-none place-items-center rounded-md border font-mono text-xs font-semibold uppercase transition-colors ${
+                    className={`${gridClass} grid h-9 min-w-11 touch-none place-items-center rounded-xl border px-2 font-mono text-[11px] font-semibold transition duration-150 active:translate-y-px active:scale-[0.98] motion-reduce:transform-none motion-reduce:transition-none ${
                       pressed
                         ? 'border-app-accent bg-app-accent text-app-on-accent'
                         : 'border-app-line bg-app-surface-raised/80 text-app-ink-soft hover:border-app-line-strong'
                     } disabled:cursor-not-allowed disabled:opacity-35 disabled:hover:border-app-line`}
                   >
-                    {key}
+                    {keyLabel(preferences.bindings[command].code)}
                   </button>
                 )
               })}
@@ -294,15 +442,18 @@ function PlaytestExperience({
             <div className="h-12 w-px bg-app-line" aria-hidden="true" />
             <div className="flex items-center gap-1.5">
               {PLAYTEST_CONTROL_KEYS.map((key) => {
+                const { command, label } = actionControls[key]
+                const boundAction = model.actions.find((action) => action.id === bindings[key])
                 const pressed = bindings[key] !== null && runtime.runtime.actionId === bindings[key]
-                const disabled = bindings[key] === null
-                const width = controlButtonWidths[key]
+                const disabled =
+                  boundAction === undefined ||
+                  playbackForFacing(boundAction, runtime.runtime.facing) === undefined
 
                 return (
                   <button
                     key={key}
                     type="button"
-                    aria-label={controlLabels[key]}
+                    aria-label={`${label}键`}
                     aria-pressed={pressed}
                     disabled={disabled}
                     onPointerDown={(event) => {
@@ -315,13 +466,13 @@ function PlaytestExperience({
                     onLostPointerCapture={(event) =>
                       holdControl(key, false, `pointer:${event.pointerId}:${key}`)
                     }
-                    className={`grid h-9 touch-none place-items-center rounded-md border font-mono text-xs font-semibold transition-colors ${width} ${
+                    className={`grid h-9 min-w-14 touch-none place-items-center rounded-xl border px-3 font-mono text-[11px] font-semibold transition duration-150 active:translate-y-px active:scale-[0.98] motion-reduce:transform-none motion-reduce:transition-none ${
                       pressed
                         ? 'border-app-accent bg-app-accent text-app-on-accent'
                         : 'border-app-line bg-app-surface-raised/80 text-app-ink-soft hover:border-app-line-strong'
                     } disabled:cursor-not-allowed disabled:opacity-35 disabled:hover:border-app-line`}
                   >
-                    {controlKeyLabels[key]}
+                    {keyLabel(preferences.bindings[command].code)}
                   </button>
                 )
               })}
diff --git a/frontend/src/pages/playtest/workbench/minimal-workbench.test.tsx b/frontend/src/pages/playtest/workbench/minimal-workbench.test.tsx
index 1aeb5866..0d5b3661 100644
--- a/frontend/src/pages/playtest/workbench/minimal-workbench.test.tsx
+++ b/frontend/src/pages/playtest/workbench/minimal-workbench.test.tsx
@@ -84,13 +84,14 @@ const characterWithoutLocomotion: Character = {
   })),
 }
 
-function renderWorkbench() {
+function renderWorkbench(userId: string | null = '7') {
   render(
     <PlaytestWorkbench
       character={character}
       outfitId={OUTFIT_ID}
       movementMode="single"
       initialActionId={IDLE_ACTION_ID}
+      userId={userId}
     />,
   )
 }
@@ -101,7 +102,11 @@ function pressedState(actionName: string) {
     .getAttribute('aria-pressed')
 }
 
-afterEach(cleanup)
+afterEach(() => {
+  cleanup()
+  window.localStorage.clear()
+  vi.restoreAllMocks()
+})
 
 describe('PlaytestWorkbench minimal control path', () => {
   it('shows a clear error when the requested outfit does not exist', () => {
@@ -138,27 +143,33 @@ describe('PlaytestWorkbench minimal control path', () => {
     expect(pressedState('待机')).toBe('true')
   })
 
-  it('keeps moving until every key bound to the same direction is released', () => {
+  it('keeps moving until the keyboard and visible control are both released', () => {
     renderWorkbench()
+    const right = screen.getByRole('button', { name: '向右移动' })
+    Object.assign(right, {
+      setPointerCapture: vi.fn(),
+      hasPointerCapture: () => true,
+      releasePointerCapture: vi.fn(),
+    })
 
+    fireEvent.pointerDown(right, { pointerId: 41 })
     fireEvent.keyDown(window, { key: 'd', code: 'KeyD' })
-    fireEvent.keyDown(window, { key: 'ArrowRight', code: 'ArrowRight' })
     fireEvent.keyUp(window, { key: 'd', code: 'KeyD' })
 
     expect(pressedState('行走')).toBe('true')
 
-    fireEvent.keyUp(window, { key: 'ArrowRight', code: 'ArrowRight' })
+    fireEvent.pointerUp(right, { pointerId: 41 })
     expect(pressedState('待机')).toBe('true')
   })
 
   it('shows action assignments separately and disables directions without assets', () => {
     renderWorkbench()
 
-    expect((screen.getByLabelText('空格键分配动作') as HTMLSelectElement).value).toBe('jump')
-    expect((screen.getByLabelText('Shift 分配动作') as HTMLSelectElement).value).toBe('')
+    expect((screen.getByLabelText('主动作分配动作') as HTMLSelectElement).value).toBe('jump')
+    expect((screen.getByLabelText('次动作分配动作') as HTMLSelectElement).value).toBe('')
     expect(screen.queryByLabelText('A 分配动作')).toBeNull()
     expect(screen.queryByLabelText('D 分配动作')).toBeNull()
-    expect((screen.getByRole('button', { name: 'Shift 键' }) as HTMLButtonElement).disabled).toBe(
+    expect((screen.getByRole('button', { name: '次动作键' }) as HTMLButtonElement).disabled).toBe(
       true,
     )
     expect((screen.getByRole('button', { name: '向左移动' }) as HTMLButtonElement).disabled).toBe(
@@ -203,7 +214,7 @@ describe('PlaytestWorkbench minimal control path', () => {
   it('uses an adjusted assignment immediately without reloading the action frames', () => {
     renderWorkbench()
 
-    fireEvent.change(screen.getByLabelText('空格键分配动作'), {
+    fireEvent.change(screen.getByLabelText('主动作分配动作'), {
       target: { value: 'attack' },
     })
     fireEvent.keyDown(window, { key: ' ', code: 'Space' })
@@ -214,7 +225,7 @@ describe('PlaytestWorkbench minimal control path', () => {
   it('allows an assignment to be cleared and releases pointers without capture', () => {
     renderWorkbench()
 
-    const space = screen.getByRole('button', { name: '空格键' })
+    const space = screen.getByRole('button', { name: '主动作键' })
     const releaseControlPointerCapture = vi.fn()
     Object.assign(space, {
       hasPointerCapture: () => false,
@@ -223,10 +234,10 @@ describe('PlaytestWorkbench minimal control path', () => {
     fireEvent.pointerUp(space, { pointerId: 20 })
     expect(releaseControlPointerCapture).not.toHaveBeenCalled()
 
-    fireEvent.change(screen.getByLabelText('空格键分配动作'), {
+    fireEvent.change(screen.getByLabelText('主动作分配动作'), {
       target: { value: '' },
     })
-    expect((screen.getByRole('button', { name: '空格键' }) as HTMLButtonElement).disabled).toBe(
+    expect((screen.getByRole('button', { name: '主动作键' }) as HTMLButtonElement).disabled).toBe(
       true,
     )
 
@@ -275,7 +286,7 @@ describe('PlaytestWorkbench minimal control path', () => {
   it('uses the assigned action for pointer press, release, cancel, and lost capture', () => {
     renderWorkbench()
 
-    const space = screen.getByRole('button', { name: '空格键' })
+    const space = screen.getByRole('button', { name: '主动作键' })
     const setPointerCapture = vi.fn()
     const releasePointerCapture = vi.fn()
     Object.assign(space, {
@@ -299,4 +310,70 @@ describe('PlaytestWorkbench minimal control path', () => {
     fireEvent.lostPointerCapture(space, { pointerId: 13 })
     expect(space.getAttribute('aria-pressed')).toBe('true')
   })
+
+  it('captures a physical key and restores it for the same local account', () => {
+    renderWorkbench('7')
+
+    fireEvent.click(screen.getByRole('button', { name: '修改向右移动键位' }))
+    fireEvent.keyDown(window, { key: 'l', code: 'KeyL' })
+
+    expect(screen.getByText('已保存到此浏览器')).toBeTruthy()
+    expect(screen.getByRole('button', { name: '修改向右移动键位' }).textContent).toContain('L')
+    expect(pressedState('待机')).toBe('true')
+
+    cleanup()
+    renderWorkbench('7')
+    expect(screen.getByRole('button', { name: '修改向右移动键位' }).textContent).toContain('L')
+  })
+
+  it('keeps persisted keybindings isolated between local accounts', () => {
+    renderWorkbench('7')
+    fireEvent.click(screen.getByRole('button', { name: '修改向右移动键位' }))
+    fireEvent.keyDown(window, { key: 'l', code: 'KeyL' })
+
+    cleanup()
+    renderWorkbench('8')
+
+    expect(screen.getByRole('button', { name: '修改向右移动键位' }).textContent).toContain('D')
+  })
+
+  it('swaps occupied controls and lets Escape cancel capture', () => {
+    renderWorkbench()
+
+    fireEvent.click(screen.getByRole('button', { name: '修改向右移动键位' }))
+    fireEvent.keyDown(window, { key: 'w', code: 'KeyW' })
+    expect(screen.getByRole('button', { name: '修改向右移动键位' }).textContent).toContain('W')
+    expect(screen.getByRole('button', { name: '修改向上移动键位' }).textContent).toContain('D')
+
+    fireEvent.click(screen.getByRole('button', { name: '修改向左移动键位' }))
+    expect(screen.getByText('请按新键')).toBeTruthy()
+    fireEvent.keyDown(window, { key: 'Escape', code: 'Escape' })
+    expect(screen.queryByText('请按新键')).toBeNull()
+    expect(screen.getByRole('button', { name: '修改向左移动键位' }).textContent).toContain('A')
+  })
+
+  it('reports when browser persistence is unavailable instead of claiming success', () => {
+    vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {
+      throw new Error('blocked')
+    })
+    renderWorkbench()
+
+    fireEvent.click(screen.getByRole('button', { name: '修改向右移动键位' }))
+    fireEvent.keyDown(window, { key: 'l', code: 'KeyL' })
+
+    expect(screen.getByText('仅本次有效，浏览器未保存')).toBeTruthy()
+    expect(screen.queryByText('已保存到此浏览器')).toBeNull()
+  })
+
+  it('clears an action key and restores all defaults without touching the backend', () => {
+    renderWorkbench()
+
+    fireEvent.click(screen.getByRole('button', { name: '修改主动作键位' }))
+    fireEvent.keyDown(window, { key: 'Delete', code: 'Delete' })
+    expect(screen.getByRole('button', { name: '修改主动作键位' }).textContent).toContain('未绑定')
+
+    fireEvent.click(screen.getByRole('button', { name: '恢复默认键位' }))
+    expect(screen.getByRole('button', { name: '修改主动作键位' }).textContent).toContain('Space')
+    expect(screen.getByText('已恢复此浏览器默认键位')).toBeTruthy()
+  })
 })
diff --git a/frontend/src/pages/playtest/workbench/preferences.test.ts b/frontend/src/pages/playtest/workbench/preferences.test.ts
new file mode 100644
index 00000000..19d8095b
--- /dev/null
+++ b/frontend/src/pages/playtest/workbench/preferences.test.ts
@@ -0,0 +1,126 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  DEFAULT_PLAYTEST_PREFERENCES,
+  readPlaytestPreferences,
+  rebindPlaytestCommand,
+  removePlaytestPreferences,
+  setPlaytestActionType,
+  writePlaytestPreferences,
+  type PlaytestPreferences,
+} from './preferences'
+
+class MemoryStorage implements Storage {
+  readonly values = new Map<string, string>()
+
+  get length() {
+    return this.values.size
+  }
+
+  clear() {
+    this.values.clear()
+  }
+
+  getItem(key: string) {
+    return this.values.get(key) ?? null
+  }
+
+  key(index: number) {
+    return [...this.values.keys()][index] ?? null
+  }
+
+  removeItem(key: string) {
+    this.values.delete(key)
+  }
+
+  setItem(key: string, value: string) {
+    this.values.set(key, value)
+  }
+}
+
+const customPreferences: PlaytestPreferences = {
+  version: 1,
+  bindings: {
+    move_up: { code: 'ArrowUp' },
+    move_down: { code: 'ArrowDown' },
+    move_left: { code: 'ArrowLeft' },
+    move_right: { code: 'ArrowRight' },
+    primary_action: { code: 'KeyJ', actionType: 'attack' },
+    secondary_action: { code: 'KeyK', actionType: 'jump' },
+  },
+}
+
+describe('Playtest local account preferences', () => {
+  it('isolates persisted preferences by authenticated user', () => {
+    const storage = new MemoryStorage()
+
+    expect(writePlaytestPreferences('7', customPreferences, storage)).toBe(true)
+    expect(readPlaytestPreferences('7', storage)).toEqual(customPreferences)
+    expect(readPlaytestPreferences('8', storage)).toEqual(DEFAULT_PLAYTEST_PREFERENCES)
+  })
+
+  it('returns fresh defaults for missing, corrupt, unknown-version, and duplicate-key data', () => {
+    const storage = new MemoryStorage()
+
+    expect(readPlaytestPreferences('7', storage)).toEqual(DEFAULT_PLAYTEST_PREFERENCES)
+
+    storage.setItem('windup.playtest.keybindings.v1:7', '{')
+    expect(readPlaytestPreferences('7', storage)).toEqual(DEFAULT_PLAYTEST_PREFERENCES)
+
+    storage.setItem(
+      'windup.playtest.keybindings.v1:7',
+      JSON.stringify({ ...customPreferences, version: 2 }),
+    )
+    expect(readPlaytestPreferences('7', storage)).toEqual(DEFAULT_PLAYTEST_PREFERENCES)
+
+    storage.setItem(
+      'windup.playtest.keybindings.v1:7',
+      JSON.stringify({
+        ...customPreferences,
+        bindings: {
+          ...customPreferences.bindings,
+          move_right: { code: 'ArrowLeft' },
+        },
+      }),
+    )
+    const recovered = readPlaytestPreferences('7', storage)
+    expect(recovered).toEqual(DEFAULT_PLAYTEST_PREFERENCES)
+    expect(recovered).not.toBe(DEFAULT_PLAYTEST_PREFERENCES)
+  })
+
+  it('reports unavailable persistence without throwing or pretending success', () => {
+    const blocked = new MemoryStorage()
+    blocked.setItem = () => {
+      throw new Error('storage blocked')
+    }
+
+    expect(writePlaytestPreferences('7', customPreferences, blocked)).toBe(false)
+    expect(writePlaytestPreferences('', customPreferences, blocked)).toBe(false)
+    expect(removePlaytestPreferences('7', null)).toBe(false)
+  })
+
+  it('swaps commands when a captured physical code is already used', () => {
+    const next = rebindPlaytestCommand(DEFAULT_PLAYTEST_PREFERENCES, 'move_up', 'KeyD')
+
+    expect(next.bindings.move_up.code).toBe('KeyD')
+    expect(next.bindings.move_right.code).toBe('KeyW')
+    expect(next.bindings.move_down.code).toBe('KeyS')
+  })
+
+  it('clears action controls but refuses to clear movement controls', () => {
+    expect(
+      rebindPlaytestCommand(DEFAULT_PLAYTEST_PREFERENCES, 'primary_action', null).bindings
+        .primary_action,
+    ).toEqual({ code: null, actionType: 'jump' })
+    expect(rebindPlaytestCommand(DEFAULT_PLAYTEST_PREFERENCES, 'move_up', null)).toEqual(
+      DEFAULT_PLAYTEST_PREFERENCES,
+    )
+  })
+
+  it('stores semantic action types without character-specific action ids', () => {
+    const next = setPlaytestActionType(DEFAULT_PLAYTEST_PREFERENCES, 'primary_action', 'attack')
+
+    expect(next.bindings.primary_action).toEqual({ code: 'Space', actionType: 'attack' })
+    expect(next.bindings.secondary_action).toEqual({ code: 'ShiftLeft', actionType: 'crouch' })
+  })
+})
diff --git a/frontend/src/pages/playtest/workbench/preferences.ts b/frontend/src/pages/playtest/workbench/preferences.ts
new file mode 100644
index 00000000..3b84c0ed
--- /dev/null
+++ b/frontend/src/pages/playtest/workbench/preferences.ts
@@ -0,0 +1,189 @@
+export const PLAYTEST_COMMANDS = [
+  'move_up',
+  'move_down',
+  'move_left',
+  'move_right',
+  'primary_action',
+  'secondary_action',
+] as const
+
+export type PlaytestCommand = (typeof PLAYTEST_COMMANDS)[number]
+export type PlaytestActionCommand = 'primary_action' | 'secondary_action'
+
+export interface PlaytestPreferenceBinding {
+  readonly code: string | null
+  readonly actionType?: string | null
+}
+
+export interface PlaytestPreferences {
+  readonly version: 1
+  readonly bindings: Readonly<Record<PlaytestCommand, PlaytestPreferenceBinding>>
+}
+
+const STORAGE_PREFIX = 'windup.playtest.keybindings.v1:'
+const MAX_CODE_LENGTH = 64
+const MAX_ACTION_TYPE_LENGTH = 64
+
+export const DEFAULT_PLAYTEST_PREFERENCES: PlaytestPreferences = {
+  version: 1,
+  bindings: {
+    move_up: { code: 'KeyW' },
+    move_down: { code: 'KeyS' },
+    move_left: { code: 'KeyA' },
+    move_right: { code: 'KeyD' },
+    primary_action: { code: 'Space', actionType: 'jump' },
+    secondary_action: { code: 'ShiftLeft', actionType: 'crouch' },
+  },
+}
+
+function clonePreferences(value: PlaytestPreferences): PlaytestPreferences {
+  return {
+    version: 1,
+    bindings: Object.fromEntries(
+      PLAYTEST_COMMANDS.map((command) => [command, { ...value.bindings[command] }]),
+    ) as unknown as PlaytestPreferences['bindings'],
+  }
+}
+
+function defaults(): PlaytestPreferences {
+  return clonePreferences(DEFAULT_PLAYTEST_PREFERENCES)
+}
+
+function browserStorage(): Storage | null {
+  try {
+    return typeof globalThis.localStorage === 'undefined' ? null : globalThis.localStorage
+  } catch {
+    return null
+  }
+}
+
+function storageKey(userId: string) {
+  return `${STORAGE_PREFIX}${userId}`
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isBoundedText(value: unknown, maxLength: number): value is string {
+  return typeof value === 'string' && value.length > 0 && value.length <= maxLength
+}
+
+function isActionCommand(command: PlaytestCommand): command is PlaytestActionCommand {
+  return command === 'primary_action' || command === 'secondary_action'
+}
+
+function parsePreferences(value: unknown): PlaytestPreferences | null {
+  if (!isRecord(value) || value.version !== 1 || !isRecord(value.bindings)) return null
+  if (
+    Object.keys(value.bindings).length !== PLAYTEST_COMMANDS.length ||
+    !Object.keys(value.bindings).every((command) =>
+      PLAYTEST_COMMANDS.includes(command as PlaytestCommand),
+    )
+  )
+    return null
+
+  const bindings = {} as Record<PlaytestCommand, PlaytestPreferenceBinding>
+  const usedCodes = new Set<string>()
+  for (const command of PLAYTEST_COMMANDS) {
+    const candidate = value.bindings[command]
+    if (!isRecord(candidate)) return null
+    const allowedKeys = isActionCommand(command) ? ['code', 'actionType'] : ['code']
+    if (!Object.keys(candidate).every((key) => allowedKeys.includes(key))) return null
+
+    const code = candidate.code
+    if (isActionCommand(command)) {
+      if (code !== null && !isBoundedText(code, MAX_CODE_LENGTH)) return null
+      const actionType = candidate.actionType
+      if (actionType !== null && !isBoundedText(actionType, MAX_ACTION_TYPE_LENGTH)) return null
+      bindings[command] = { code, actionType }
+    } else {
+      if (!isBoundedText(code, MAX_CODE_LENGTH)) return null
+      bindings[command] = { code }
+    }
+
+    if (code !== null) {
+      if (usedCodes.has(code)) return null
+      usedCodes.add(code)
+    }
+  }
+  return { version: 1, bindings }
+}
+
+export function readPlaytestPreferences(
+  userId: string,
+  storage: Storage | null = browserStorage(),
+): PlaytestPreferences {
+  if (!userId || storage === null) return defaults()
+  try {
+    const raw = storage.getItem(storageKey(userId))
+    if (raw === null) return defaults()
+    return parsePreferences(JSON.parse(raw)) ?? defaults()
+  } catch {
+    return defaults()
+  }
+}
+
+export function writePlaytestPreferences(
+  userId: string,
+  value: PlaytestPreferences,
+  storage: Storage | null = browserStorage(),
+): boolean {
+  if (!userId || storage === null || parsePreferences(value) === null) return false
+  try {
+    storage.setItem(storageKey(userId), JSON.stringify(value))
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function removePlaytestPreferences(
+  userId: string,
+  storage: Storage | null = browserStorage(),
+): boolean {
+  if (!userId || storage === null) return false
+  try {
+    storage.removeItem(storageKey(userId))
+    return true
+  } catch {
+    return false
+  }
+}
+
+export function rebindPlaytestCommand(
+  value: PlaytestPreferences,
+  command: PlaytestCommand,
+  code: string | null,
+): PlaytestPreferences {
+  if (code === null && !isActionCommand(command)) return clonePreferences(value)
+  if (code !== null && !isBoundedText(code, MAX_CODE_LENGTH)) return clonePreferences(value)
+
+  const next = clonePreferences(value)
+  const oldCode = next.bindings[command].code
+  const occupied = PLAYTEST_COMMANDS.find(
+    (candidate) => candidate !== command && next.bindings[candidate].code === code,
+  )
+  const bindings = { ...next.bindings }
+  bindings[command] = { ...bindings[command], code }
+  if (occupied !== undefined) bindings[occupied] = { ...bindings[occupied], code: oldCode }
+  return { version: 1, bindings }
+}
+
+export function setPlaytestActionType(
+  value: PlaytestPreferences,
+  command: PlaytestActionCommand,
+  actionType: string | null,
+): PlaytestPreferences {
+  if (actionType !== null && !isBoundedText(actionType, MAX_ACTION_TYPE_LENGTH)) {
+    return clonePreferences(value)
+  }
+  const next = clonePreferences(value)
+  return {
+    version: 1,
+    bindings: {
+      ...next.bindings,
+      [command]: { ...next.bindings[command], actionType },
+    },
+  }
+}
diff --git a/frontend/src/pages/playtest/workbench/runtime/runtime.test.ts b/frontend/src/pages/playtest/workbench/runtime/runtime.test.ts
index e9b54ff7..3aa5afca 100644
--- a/frontend/src/pages/playtest/workbench/runtime/runtime.test.ts
+++ b/frontend/src/pages/playtest/workbench/runtime/runtime.test.ts
@@ -201,7 +201,7 @@ describe('playtest runtime', () => {
     ])
   })
 
-  it('switches to a real direction when the selected action lacks the current facing', () => {
+  it('keeps the current action and facing when the selected action lacks that direction', () => {
     const sideOnlyAction: PlaytestAction = {
       id: 'side-attack',
       name: '侧向攻击',
@@ -226,8 +226,8 @@ describe('playtest runtime', () => {
 
     const selected = selectRuntimeAction(current, actionSet, 'side-attack')
 
-    expect(selected).toMatchObject({ actionId: 'side-attack', facing: 'east', frameIndex: 0 })
-    expect(framesForFacing(sideOnlyAction, selected.facing)).toBeDefined()
+    expect(selected).toBe(current)
+    expect(selected).toMatchObject({ actionId: 'idle', facing: 'north' })
   })
 
   it('does not treat a directional-only action as a side action', () => {
diff --git a/frontend/src/pages/playtest/workbench/runtime/runtime.ts b/frontend/src/pages/playtest/workbench/runtime/runtime.ts
index 8d39f548..134b71a0 100644
--- a/frontend/src/pages/playtest/workbench/runtime/runtime.ts
+++ b/frontend/src/pages/playtest/workbench/runtime/runtime.ts
@@ -134,12 +134,16 @@ export function selectRuntimeAction(
   actionId: string,
 ): PlaytestRuntime {
   const action = actionById(actions, actionId)
-  if (action === undefined || action.id === runtime.actionId) return runtime
+  if (
+    action === undefined ||
+    action.id === runtime.actionId ||
+    playbackForFacing(action, runtime.facing) === undefined
+  )
+    return runtime
 
   return {
     ...runtime,
     actionId: action.id,
-    facing: facingForAction(action, runtime.facing),
     frameIndex: 0,
     frameElapsedMs: 0,
   }
diff --git a/frontend/src/pages/playtest/workbench/runtime/use-playtest-runtime.test.ts b/frontend/src/pages/playtest/workbench/runtime/use-playtest-runtime.test.ts
index 521fd771..09560447 100644
--- a/frontend/src/pages/playtest/workbench/runtime/use-playtest-runtime.test.ts
+++ b/frontend/src/pages/playtest/workbench/runtime/use-playtest-runtime.test.ts
@@ -4,6 +4,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 
 import type { PlaytestActionBindings } from '../bindings'
 import type { PlaytestAction } from '../model'
+import { DEFAULT_PLAYTEST_PREFERENCES, rebindPlaytestCommand } from '../preferences'
 import { preloadActionFrames, usePlaytestRuntime } from './use-playtest-runtime'
 
 afterEach(() => {
@@ -209,6 +210,40 @@ describe('preloadActionFrames', () => {
     expect(result.current.runtime).toMatchObject({ actionId: 'walk', facing: 'south' })
   })
 
+  it('uses persisted physical key codes instead of the fixed default key', () => {
+    vi.stubGlobal(
+      'requestAnimationFrame',
+      vi.fn(() => 1),
+    )
+    vi.stubGlobal('cancelAnimationFrame', vi.fn())
+    const preferences = rebindPlaytestCommand(DEFAULT_PLAYTEST_PREFERENCES, 'move_right', 'KeyL')
+    const { result } = renderHook(() =>
+      usePlaytestRuntime(actions, 'idle', 'single', bindings, { preferences }),
+    )
+
+    act(() => window.dispatchEvent(new KeyboardEvent('keydown', { key: 'd', code: 'KeyD' })))
+    expect(result.current.runtime.actionId).toBe('idle')
+
+    act(() => window.dispatchEvent(new KeyboardEvent('keydown', { key: 'l', code: 'KeyL' })))
+    expect(result.current.runtime).toMatchObject({ actionId: 'walk', facing: 'east' })
+  })
+
+  it('pauses runtime keyboard handling while the workbench captures a new key', () => {
+    vi.stubGlobal(
+      'requestAnimationFrame',
+      vi.fn(() => 1),
+    )
+    vi.stubGlobal('cancelAnimationFrame', vi.fn())
+    const { result } = renderHook(() =>
+      usePlaytestRuntime(actions, 'idle', 'single', bindings, { keyboardEnabled: false }),
+    )
+
+    act(() => window.dispatchEvent(new KeyboardEvent('keydown', { key: 'd', code: 'KeyD' })))
+
+    expect(result.current.runtime.actionId).toBe('idle')
+    expect(result.current.runtime.held.right).toBe(false)
+  })
+
   it('ignores typing and unknown keys while keeping the direction compatibility entry', () => {
     vi.stubGlobal(
       'requestAnimationFrame',
diff --git a/frontend/src/pages/playtest/workbench/runtime/use-playtest-runtime.ts b/frontend/src/pages/playtest/workbench/runtime/use-playtest-runtime.ts
index aa538efd..c1ce732d 100644
--- a/frontend/src/pages/playtest/workbench/runtime/use-playtest-runtime.ts
+++ b/frontend/src/pages/playtest/workbench/runtime/use-playtest-runtime.ts
@@ -8,6 +8,11 @@ import {
   type PlaytestControlKey,
 } from '../bindings'
 import type { PlaytestAction } from '../model'
+import {
+  DEFAULT_PLAYTEST_PREFERENCES,
+  type PlaytestCommand,
+  type PlaytestPreferences,
+} from '../preferences'
 import {
   advanceRuntime,
   createRuntime,
@@ -35,15 +40,32 @@ function isTypingTarget(target: EventTarget | null): boolean {
   )
 }
 
-function keyboardInput(key: string, code: string): MovementDirection | PlaytestControlKey | null {
-  const normalized = key.toLowerCase()
-  if (normalized === 'arrowleft' || normalized === 'a') return 'left'
-  if (normalized === 'arrowright' || normalized === 'd') return 'right'
-  if (normalized === 'arrowup' || normalized === 'w') return 'up'
-  if (normalized === 'arrowdown' || normalized === 's') return 'down'
-  if (code === 'Space' || key === ' ' || normalized === 'spacebar') return 'space'
-  if (code === 'ShiftLeft' || code === 'ShiftRight' || normalized === 'shift') return 'shift'
-  return null
+const COMMAND_INPUTS: Readonly<Record<PlaytestCommand, MovementDirection | PlaytestControlKey>> = {
+  move_up: 'up',
+  move_down: 'down',
+  move_left: 'left',
+  move_right: 'right',
+  primary_action: 'space',
+  secondary_action: 'shift',
+}
+
+function fallbackCode(key: string): string {
+  if (/^[a-z]$/i.test(key)) return `Key${key.toUpperCase()}`
+  if (key === ' ') return 'Space'
+  if (key.toLowerCase() === 'shift') return 'ShiftLeft'
+  return key
+}
+
+function keyboardInput(
+  key: string,
+  code: string,
+  preferences: PlaytestPreferences,
+): MovementDirection | PlaytestControlKey | null {
+  const physicalCode = code || fallbackCode(key)
+  const command = Object.entries(preferences.bindings).find(
+    ([, binding]) => binding.code === physicalCode,
+  )?.[0] as PlaytestCommand | undefined
+  return command === undefined ? null : COMMAND_INPUTS[command]
 }
 
 function isMovementDirection(
@@ -93,6 +115,10 @@ export function usePlaytestRuntime(
   initialActionId: string | null,
   movementMode: DirectionalMovement = 'single',
   bindings?: PlaytestActionBindings,
+  options: {
+    readonly preferences?: PlaytestPreferences
+    readonly keyboardEnabled?: boolean
+  } = {},
 ) {
   const effectiveBindings = useMemo(
     () => bindings ?? createDefaultActionBindings(actions),
@@ -103,6 +129,7 @@ export function usePlaytestRuntime(
   )
   const actionsRef = useRef(actions)
   const bindingsRef = useRef(effectiveBindings)
+  const preferencesRef = useRef(options.preferences ?? DEFAULT_PLAYTEST_PREFERENCES)
   const boundsRef = useRef<StageBounds>(INITIAL_BOUNDS)
   const activeInputsRef = useRef(new Map<string, MovementDirection>())
   const preloadedImagesRef = useRef<readonly HTMLImageElement[]>([])
@@ -121,6 +148,10 @@ export function usePlaytestRuntime(
     bindingsRef.current = effectiveBindings
   }, [effectiveBindings])
 
+  useEffect(() => {
+    preferencesRef.current = options.preferences ?? DEFAULT_PLAYTEST_PREFERENCES
+  }, [options.preferences])
+
   useEffect(() => {
     preloadedImagesRef.current = preloadActionFrames(actions, initialRuntimeActionId)
     return () => {
@@ -184,10 +215,15 @@ export function usePlaytestRuntime(
     )
   }, [])
 
+  useEffect(() => {
+    if (options.keyboardEnabled === false) clearDirections()
+  }, [clearDirections, options.keyboardEnabled])
+
   useEffect(() => {
     const handleKeyDown = (event: globalThis.KeyboardEvent) => {
+      if (options.keyboardEnabled === false) return
       if (isTypingTarget(event.target)) return
-      const input = keyboardInput(event.key, event.code)
+      const input = keyboardInput(event.key, event.code, preferencesRef.current)
       if (input === null) return
       event.preventDefault()
       if (event.repeat) return
@@ -196,7 +232,8 @@ export function usePlaytestRuntime(
       else setControl(input, true, source)
     }
     const handleKeyUp = (event: globalThis.KeyboardEvent) => {
-      const input = keyboardInput(event.key, event.code)
+      if (options.keyboardEnabled === false) return
+      const input = keyboardInput(event.key, event.code, preferencesRef.current)
       if (input === null) return
       event.preventDefault()
       const source = `keyboard:${event.code || event.key}`
@@ -212,7 +249,7 @@ export function usePlaytestRuntime(
       window.removeEventListener('keyup', handleKeyUp)
       window.removeEventListener('blur', clearDirections)
     }
-  }, [clearDirections, setControl, setMovement])
+  }, [clearDirections, options.keyboardEnabled, setControl, setMovement])
 
   const selectAction = useCallback((actionId: string) => {
     setRuntime((current) => selectRuntimeAction(current, actionsRef.current, actionId))
diff --git a/frontend/src/pages/playtest/workbench/stage.test.tsx b/frontend/src/pages/playtest/workbench/stage.test.tsx
index 3db158ae..15d4f783 100644
--- a/frontend/src/pages/playtest/workbench/stage.test.tsx
+++ b/frontend/src/pages/playtest/workbench/stage.test.tsx
@@ -49,6 +49,48 @@ describe('PlaytestStage', () => {
     expect(screen.getByText('暂无可播放帧')).toBeTruthy()
   })
 
+  it('reports a failed frame and retries the same image on demand', () => {
+    const firstSprite = renderStage(0)!
+
+    fireEvent.error(firstSprite)
+
+    expect(screen.getByText('当前帧加载失败')).toBeTruthy()
+    const retry = screen.getByRole('button', { name: '重试当前帧' })
+    fireEvent.click(retry)
+
+    expect(screen.queryByText('当前帧加载失败')).toBeNull()
+    const retriedSprite = screen.getByRole('region', { name: '预览舞台' }).querySelector('img')
+    expect(retriedSprite).not.toBe(firstSprite)
+    expect(retriedSprite?.getAttribute('src')).toBe('/idle-01.png')
+  })
+
+  it('clears a frame failure when playback advances to another image', () => {
+    const { rerender } = render(
+      <PlaytestStage
+        frame={{ imageUrl: '/idle-01.png', durationMs: 100 }}
+        x={0}
+        y={0}
+        mirrorX={false}
+        onBoundsChange={() => undefined}
+      />,
+    )
+    const stage = screen.getByRole('region', { name: '预览舞台' })
+    fireEvent.error(stage.querySelector('img')!)
+
+    rerender(
+      <PlaytestStage
+        frame={{ imageUrl: '/walk-02.png', durationMs: 100 }}
+        x={0}
+        y={0}
+        mirrorX={false}
+        onBoundsChange={() => undefined}
+      />,
+    )
+
+    expect(screen.queryByText('当前帧加载失败')).toBeNull()
+    expect(stage.querySelector('img')?.getAttribute('src')).toBe('/walk-02.png')
+  })
+
   it('measures horizontal and depth bounds from the stage and sprite sizes', () => {
     const onBoundsChange = vi.fn()
     render(
diff --git a/frontend/src/pages/playtest/workbench/stage.tsx b/frontend/src/pages/playtest/workbench/stage.tsx
index 13d98ccd..b6f2c1e0 100644
--- a/frontend/src/pages/playtest/workbench/stage.tsx
+++ b/frontend/src/pages/playtest/workbench/stage.tsx
@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useRef } from 'react'
+import { useCallback, useEffect, useRef, useState } from 'react'
 
 import type { PlaytestFrame } from './model'
 import type { StageBounds } from './runtime/runtime'
@@ -14,6 +14,8 @@ export interface PlaytestStageProps {
 export function PlaytestStage({ frame, x, y, mirrorX, onBoundsChange }: PlaytestStageProps) {
   const stageRef = useRef<HTMLDivElement>(null)
   const characterRef = useRef<HTMLImageElement>(null)
+  const [failedImageUrl, setFailedImageUrl] = useState<string | null>(null)
+  const [retryToken, setRetryToken] = useState(0)
 
   const measureBounds = useCallback(() => {
     const stageWidth = stageRef.current?.getBoundingClientRect().width ?? 0
@@ -45,6 +47,17 @@ export function PlaytestStage({ frame, x, y, mirrorX, onBoundsChange }: Playtest
     return () => observer.disconnect()
   }, [measureBounds])
 
+  useEffect(() => {
+    setFailedImageUrl(null)
+  }, [frame?.imageUrl])
+
+  const retryFrame = () => {
+    setFailedImageUrl(null)
+    setRetryToken((token) => token + 1)
+  }
+
+  const frameFailed = frame !== null && failedImageUrl === frame.imageUrl
+
   return (
     <div
       ref={stageRef}
@@ -72,8 +85,25 @@ export function PlaytestStage({ frame, x, y, mirrorX, onBoundsChange }: Playtest
         <p className="absolute inset-0 grid place-items-center text-xs tracking-[0.16em] text-[#6f746f]">
           暂无可播放帧
         </p>
+      ) : frameFailed ? (
+        <div
+          role="alert"
+          className="absolute inset-0 grid place-items-center px-6 text-center text-app-ink-soft"
+        >
+          <div className="rounded-3xl border border-app-surface-raised/70 bg-app-surface/80 px-6 py-5 shadow-app-float backdrop-blur-sm">
+            <p className="text-sm font-medium">当前帧加载失败</p>
+            <button
+              type="button"
+              onClick={retryFrame}
+              className="mt-3 rounded-full border border-app-line bg-app-surface-raised px-4 py-2 text-xs font-medium transition hover:-translate-y-0.5 hover:border-app-line-strong hover:shadow-sm focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-app-accent motion-reduce:transform-none"
+            >
+              重试当前帧
+            </button>
+          </div>
+        </div>
       ) : (
         <img
+          key={`${frame.imageUrl}:${retryToken}`}
           ref={characterRef}
           src={frame.imageUrl}
           alt=""
@@ -83,6 +113,7 @@ export function PlaytestStage({ frame, x, y, mirrorX, onBoundsChange }: Playtest
           decoding="async"
           fetchPriority="high"
           onLoad={measureBounds}
+          onError={() => setFailedImageUrl(frame.imageUrl)}
           className="pointer-events-none absolute left-1/2 w-[clamp(150px,22vw,256px)] select-none object-contain [image-rendering:pixelated] drop-shadow-[0_14px_9px_rgba(27,25,20,0.18)] will-change-transform"
           style={{
             bottom: 'calc(50% - 18px)',

From e30e843fc82daf450e870235892128e7e2c00603 Mon Sep 17 00:00:00 2001
From: xyh202131 <246811510+xyh202131@users.noreply.github.com>
Date: Fri, 21 Aug 2026 17:50:51 +0800
Subject: [PATCH 2/2] =?UTF-8?q?docs(playtest):=20=E8=AF=B4=E6=98=8E?=
 =?UTF-8?q?=E6=9C=AC=E5=9C=B0=E9=94=AE=E4=BD=8D=E8=83=BD=E5=8A=9B=E8=BE=B9?=
 =?UTF-8?q?=E7=95=8C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...-21-playtest-account-keybindings-design.md | 145 ++++++++++++++++++
 frontend/src/pages/playtest/README.md         |  24 ++-
 2 files changed, 164 insertions(+), 5 deletions(-)
 create mode 100644 docs/superpowers/specs/2026-08-21-playtest-account-keybindings-design.md

diff --git a/docs/superpowers/specs/2026-08-21-playtest-account-keybindings-design.md b/docs/superpowers/specs/2026-08-21-playtest-account-keybindings-design.md
new file mode 100644
index 00000000..322b7354
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-21-playtest-account-keybindings-design.md
@@ -0,0 +1,145 @@
+# Playtest 本地账号键位设计
+
+## 目标与真实能力边界
+
+在后端不提供偏好接口的现状下，让登录用户在同一浏览器中修改一次 Playtest 键位后，切换角色、造型或重新登录仍使用同一套配置。
+
+配置通过 JWT 用户 ID 分区保存在浏览器 `localStorage`。它不是服务端账号同步：清理浏览器数据、使用无痕窗口、换浏览器或换设备都会丢失或无法读取。页面只描述“已保存到此浏览器”，不得显示“已同步到账号”或“跨设备可用”。
+
+本次同时修复三类现有体验问题：当前方向缺少动作素材时自动改朝向、键帽交互过于方格化、当前帧图片加载失败时没有可见反馈。
+
+## 范围
+
+### 包含
+
+- 本地保存上、下、左、右、主动作、次动作六个控制位。
+- 使用当前登录用户的 JWT `sub` 作为本地存储命名空间。
+- 点击键帽后捕获下一次物理键盘输入。
+- 使用 `KeyboardEvent.code` 保存物理位置，显示时使用可读标签。
+- 主、次动作保存 Action `type`，运行时在当前角色中解析为首个可播放的同类型动作。
+- 键位冲突自动交换，`Escape` 取消捕获，`Delete` 或 `Backspace` 清除非移动控制位。
+- 当前角色没有对应动作，或对应动作没有当前朝向的可播放帧时，控制位禁用且不改变朝向。
+- 当前播放帧加载失败时展示错误和重试入口。
+- 键帽和动作选择改为柔和胶囊、轻微缩放及低强度光晕，并支持减少动态效果设置。
+
+### 不包含
+
+- 任何后端模型、接口、OpenAPI 或数据库改动。
+- 跨浏览器、跨设备同步。
+- 组合键、宏、连招、手柄和触屏手势编辑。
+- 每个项目、角色或造型单独覆盖本地账号配置。
+- 修改 Character、WorkflowRun、Generation 或导出数据。
+- mock 服务端保存、伪造同步成功或隐藏本地存储限制。
+
+## 存储设计
+
+### 接口边界
+
+新增前端内部 `PlaytestPreferenceRepository`：
+
+- `read(userId)`：读取并校验当前用户配置；无配置或配置损坏时返回默认配置。
+- `write(userId, preferences)`：同步写入浏览器存储；写入失败时返回明确失败结果。
+- `remove(userId)`：删除当前用户的本地自定义配置并恢复默认值。
+
+默认实现只使用浏览器 `localStorage`。Playtest 页面只依赖这个窄接口；未来如果有真实后端接口，可以增加服务端实现，但本次不创建空 API、假请求或未配置成功分支。
+
+### 命名空间与数据结构
+
+存储键：
+
+```text
+windup.playtest.keybindings.v1:<userId>
+```
+
+版本 1 数据：
+
+```json
+{
+  "version": 1,
+  "bindings": {
+    "move_up": { "code": "KeyW" },
+    "move_down": { "code": "KeyS" },
+    "move_left": { "code": "KeyA" },
+    "move_right": { "code": "KeyD" },
+    "primary_action": { "code": "Space", "actionType": "jump" },
+    "secondary_action": { "code": "ShiftLeft", "actionType": "crouch" }
+  }
+}
+```
+
+移动控制位必须有键；动作控制位允许 `code` 或 `actionType` 为 `null`。读取时拒绝未知版本、重复键位、空字符串和非法结构，直接恢复内置默认配置，不尝试猜测或迁移损坏数据。
+
+用户身份使用现有 JWT `sub` 解析方法。未取得合法用户 ID 时不读写持久化配置，只在当前页面使用默认值。
+
+## 前端运行设计
+
+### 页面状态
+
+页面初始化时读取当前用户的本地配置；角色模型变化时重新按 Action type 解析动作，但不重置键位。
+
+修改后同步写入本地存储：
+
+- 成功显示“已保存到此浏览器”。
+- 浏览器拒绝存储或容量异常时，当前会话仍使用新配置，但显示“仅本次有效，浏览器未保存”。
+- 提供“恢复默认键位”，删除当前用户的本地配置。
+
+不存在网络保存、加载骨架、乐观请求或伪造的服务端同步状态。
+
+### 键盘捕获
+
+用户点击键帽后进入捕获模式：
+
+- 普通按键以 `event.code` 绑定到选中的控制位。
+- 新键已被其他控制位占用时，两个控制位交换，保证移动键不会意外丢失。
+- `Escape` 取消，不修改配置。
+- `Delete` 或 `Backspace` 只允许清除主、次动作；移动控制位保持可操作。
+- 捕获期间阻止该次按键触发角色动作。
+- 输入框、文本域、下拉框和可编辑元素仍不触发 Playtest 控制。
+
+默认按键为 W、A、S、D、Space、左 Shift。运行时不再硬编码这些键，而是从当前偏好反向建立 `code -> command` 映射。
+
+### 动作解析和方向约束
+
+主、次动作保存 `actionType`。每次载入角色时，从当前造型中选择首个具有可播放帧的同类型动作；不存在时控制位禁用。
+
+触发动作时只接受当前 facing 对应的 playback。缺少该方向时不执行、不切换 facing，并在控制位上显示“当前方向无素材”。动作列表中的直接选择同样遵循该规则。
+
+移动方向缺少 locomotion playback 时，现有方向按钮和键盘输入都保持无效，不猜测其他方向。
+
+### 图片失败
+
+舞台按 `frame.imageUrl` 记录当前失败状态。`img` 的 `onError` 显示“当前帧加载失败”，停止展示破图；重试会清除失败状态并重新加载同一 URL。切换到不同帧时自动清除旧帧错误。
+
+预加载失败不阻塞页面，但当前帧真正渲染失败必须可见。此错误不写入 Character 或 WorkflowRun。
+
+### 视觉与无障碍
+
+- 键帽使用圆角胶囊而非方格，按下时仅做 1–2px 位移、轻微缩放和柔和阴影。
+- 捕获态使用脉冲描边和“请按新键”文本，不依赖颜色表达状态。
+- 所有控制位有可读名称、`aria-pressed`、`aria-disabled` 和本地保存状态播报。
+- `prefers-reduced-motion` 下关闭脉冲与缩放动画。
+
+## 测试策略
+
+- 不同用户本地配置隔离。
+- 无配置、损坏 JSON、未知版本和浏览器拒绝写入。
+- 点击键帽后捕获 `event.code`。
+- 冲突交换、取消和清除规则。
+- 切换角色后按 Action type 重新解析，不复用旧 Action ID。
+- 缺少动作或当前方向素材时禁用且 facing 不变。
+- 自定义键位驱动四/八向移动，斜向速度继续归一化。
+- 当前帧图片失败提示与重试。
+- 键盘监听测试放在运行时 Hook；页面集成测试使用可见按钮，避免 `useEffect` 监听挂载竞态。
+- 全量前端测试、类型检查、格式、lint 与构建。
+
+## 验收标准
+
+1. 同一浏览器内，用户修改键位后刷新、退出再登录或切换角色仍保留配置。
+2. 同一浏览器中的不同账号互不读取对方配置。
+3. 页面明确显示配置只保存在此浏览器，不宣称跨设备同步。
+4. 切换不同角色后，键位仍对应同一动作类型；角色没有该动作时控制位不可用。
+5. 当前方向缺少动作素材时，按键不会改变朝向或播放其他方向素材。
+6. 任一物理键只对应一个控制位，冲突交换可预测。
+7. 本地写入失败不会展示虚假的“已保存”。
+8. 图片失败有明确提示和重试，不出现无解释的空白舞台。
+9. Playtest 仍只读 Character，不修改 WorkflowRun、Generation、Character 或导出数据。
diff --git a/frontend/src/pages/playtest/README.md b/frontend/src/pages/playtest/README.md
index 1adc6d7c..d89451a9 100644
--- a/frontend/src/pages/playtest/README.md
+++ b/frontend/src/pages/playtest/README.md
@@ -24,15 +24,29 @@ Character、Outfit、Action、Frame 或后端数据。这几条由 `playtest-bou
 ## 操控
 
 - 页面绑定当前造型下全部有帧的动作，点击动作名可以直接切换。
-- 默认将 jump 分配给 Space、crouch/duck/squat 分配给 Shift，并将首个 walk（没有时取
-  run）同时分配给 A / D；当前预览会话可以在舞台左上角重新分配四个按键。
-- A / D 或 ← / → 始终可以切换角色朝向。只有当前动作类型是 walk 或 run 时，角色才会按
-  150 px/s 连续移动；待机、跳跃、攻击和自定义动作只播放帧，不产生水平位移。
-- 没有可分配动作的 Space / Shift 控件禁用；A / D 即使未分配动作也保留转向能力。
+- 上、下、左、右、主动作和次动作共六个控制位都可修改。点击圆角键帽后按下目标物理键即可
+  重新绑定；键位冲突时交换原键位，`Escape` 取消，`Delete` 或 `Backspace` 可清除动作键。
+- 默认键位是 W、S、A、D、Space 和左 Shift。四个方向键驱动四向或八向移动；只有当前动作
+  类型是 walk 或 run 时，角色才会按 150 px/s 连续移动，斜向速度保持归一化。
+- 主、次动作按 Action `type` 保存：默认把 jump 分配给主动作，把 crouch/duck/squat 归一为
+  crouch 分配给次动作。切换角色或造型时会在新资产中重新查找同类型动作，不复用旧 Action ID。
+- 当前角色没有对应动作，或动作没有当前朝向的帧时，相关控制禁用；不会自动切换到有素材的
+  其他朝向。
 - 松开所有横向按键后，存在 idle 动作时切回首个 idle 动作，找不到时保持当前动作。
 - 所有动作帧进入页面时统一预加载；切换动作只重置帧游标，不重复请求素材。动作帧按各自
   时长播放，角色位移使用 `requestAnimationFrame` 的真实时间差计算，两者互不耦合。
 - 舞台按实际宽度限制移动范围；窗口尺寸变化时重新计算。
+- 当前帧图片真实加载失败时显示错误；点击“重试当前帧”会重新请求同一资源，不用占位图伪装
+  成功。
+
+## 键位保存边界
+
+登录后，键位按 JWT 用户 ID 隔离保存在当前浏览器 `localStorage`，页面明确显示“已保存到此
+浏览器”。刷新、重新登录或切换角色仍会读取本地配置；同一浏览器中的不同账号互不读取。
+
+这不是服务端账号同步：换浏览器、换设备、使用无痕窗口或清理浏览器数据后不会保留。未取得
+有效用户 ID 或浏览器拒绝存储时，设置只在本次页面会话有效，界面会明确提示“浏览器未保存”。
+本模块没有新增后端接口、mock 保存请求或伪造同步成功。
 
 视觉复用 livedemo 的白色透明棋盘画布、悬浮控制胶囊和动作状态层级，代码使用项目现有的
 React、TypeScript 与 Tailwind。顶栏悬浮不占布局高度，页面自己让出 `pt-24` 的避让空间。