리펙토링: 코드 최적화, AGENTS.md, README.md 내용 반영

AGENTS.md

@@ -91,9 +91,13 @@ prisma/
 ### 접근성 / 키보드 조작
 
 - 문제 풀이 화면은 키보드만으로 진행할 수 있어야 한다.
-- 새 문제가 표시되면 첫째 항 입력 칸에 focus를 둔다.
+- 문제 풀이 화면은 모든 항을 하나의 공유 input group으로 입력한다.
-- 첫째 항에서 Enter를 누르면 둘째 항 입력 칸으로 focus를 이동한다.
+- input group 아래에는 각 항의 입력값 버튼을 버튼 그룹으로 표시한다. 현재 입력 중인 항은 `aria-pressed`로 표시하고, 비어 있는 항은 `?`로 표시한다.
-- 둘째 항에서 Enter를 누르면 제출 동작을 실행한다.
+- 첫째 항에서 Enter를 누르면 같은 input group이 둘째 항 입력으로 전환된다.
+- 둘째 항에서 Enter를 누르면 제출 동작을 실행한다. 별도 제출 버튼이 없어도 form submit 흐름이 유지되어야 한다.
+- 모바일 화면에서는 input group에 `-/+` 버튼과 `↵` 버튼을 표시한다. `sm` 이상 화면에서는 물리 키보드 사용을 전제로 이 보조 버튼들을 숨긴다.
+- 문제 풀이 화면 최초 진입 시 모바일 키보드를 강제로 열지 않는다. 사용자가 input을 직접 focus하거나 피드백 후 다음 문제로 넘어갈 때 input에 focus를 둔다.
+- 모바일 input focus 시 가상 키보드가 올라온 뒤 `span.katex` 상단이 브라우저 화면 상단에 오도록 조정한다.
 - 정답·오답 피드백이 표시되면 다음 진행 버튼에 focus를 둔다.
 - 최종 결과 화면이 표시되면 다시 시작 버튼에 focus를 둔다.
 - 아이콘이나 기호만으로 상태를 표시할 때는 `aria-label`, `sr-only` 텍스트 등으로 의미를 함께 제공한다.
@@ -157,12 +161,16 @@ NEXTAUTH_SECRET=your-secret
 시작 화면 → 문제 유형 선택 → 게임 모드 선택 → 문제 풀이 → 결과 및 기록
 ```
 
+- 시작 화면은 문제 수 `[5] [10]` 선택 버튼 그룹을 제공하고 기본값은 `10`이다.
+- 문제 풀이 화면은 URL의 `count` 쿼리와 Zustand의 선택 문제 수를 동기화한다. 허용 문제 수는 `5`, `10`이며 유효하지 않은 값은 `10`으로 처리한다.
+
 ---
 
 ## CI/CD
 
 - `.gitea/workflows/deploy.yml`이 CI/CD 진입점이다. main 브랜치 push 시 자동으로 빌드·배포된다.
 - 패키지 설치는 반드시 `pnpm`을 사용한다. `npm` / `yarn` 명령을 사용하지 않는다.
+- 빌드 확인은 `pnpm build`로 실행한다. standalone 배포 산출물에 필요한 정적 파일 복사까지 `postbuild` 스크립트가 처리한다.
 - 배포 환경: Synology NAS + Docker Compose + Nginx Proxy Manager.
 
 ---

README.md

@@ -48,16 +48,19 @@
 
 ## 현재 구현 상태
 
-- 시작 화면에서 `/play` 풀이 화면으로 이동할 수 있습니다.
+- 시작 화면에서 문제 수를 5개 또는 10개로 선택한 뒤 `/play` 풀이 화면으로 이동할 수 있습니다.
-- `/play`에서 괄호 앞 음수 분배 문제 10개를 풉니다.
+- 문제 수 기본값은 10개이며, `/play?count=5` 또는 `/play?count=10`으로 선택값을 전달합니다.
 - 문제와 정답 수식은 KaTeX로 렌더링합니다.
 - 진행 단계는 현재 문제, 완료된 정답, 완료된 오답, 남은 문제를 구분해서 표시합니다.
 - 키보드 흐름을 지원합니다.
-  - 새 문제 시작 시 첫째 항 입력 칸에 focus
+  - 모든 항은 하나의 input group에서 순서대로 입력
-  - 첫째 항 Enter → 둘째 항 입력 칸으로 이동
+  - 첫째 항 Enter → 같은 input group이 둘째 항 입력으로 전환
   - 둘째 항 Enter → 제출
   - 피드백 화면 → 다음 문제/결과 보기 버튼에 focus
+  - 다음 문제 이동 후 → input에 focus
   - 결과 화면 → 다시 시작 버튼에 focus
+- input group 아래에는 각 항의 입력값 버튼이 표시됩니다. 비어 있는 항은 `?`로 표시하고, 버튼을 누르면 해당 항을 초기화한 뒤 다시 입력합니다.
+- 모바일 화면에서는 `-/+`와 `↵` 보조 버튼을 표시하고, input focus 후 가상 키보드가 올라오면 문제 수식이 화면 상단에 오도록 스크롤 위치를 조정합니다.
 
 ---
 
@@ -104,6 +107,8 @@ pnpm build
 pnpm start
 ```
 
+`pnpm build`는 Next.js standalone 산출물에 필요한 정적 파일 복사까지 함께 처리합니다.
+
 ---
 
 ## 프로젝트 구조

app/(game)/play/PlayClient.tsx

@@ -1,9 +1,14 @@
 "use client";
 
-import { useEffect, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import type { FormEvent } from "react";
+import { flushSync } from "react-dom";
 
 import AnswerForm from "@/components/game/AnswerForm";
+import type {
+  ActiveAnswerInput,
+  AnswerFormHandle,
+} from "@/components/game/AnswerForm";
 import FeedbackPanel from "@/components/game/FeedbackPanel";
 import ScoreSummary from "@/components/game/ScoreSummary";
 import StageIndicator from "@/components/game/StageIndicator";
@@ -11,6 +16,9 @@ import KatexRenderer from "@/components/math/KatexRenderer";
 import { useGameStore } from "@/store/gameStore";
 import type { ProblemCount } from "@/store/gameStore";
 
+const MOBILE_BREAKPOINT_QUERY = "(min-width: 640px)";
+const MOBILE_KEYBOARD_SPACER_OFFSET = 480;
+
 function parseAnswer(value: string) {
   const trimmed = value.trim();
 
@@ -34,8 +42,15 @@ export default function PlayClient({ problemCount }: PlayClientProps) {
   const nextProblem = useGameStore((state) => state.nextProblem);
   const resetSession = useGameStore((state) => state.resetSession);
 
+  const problemCardRef = useRef<HTMLDivElement>(null);
+  const scrollTimeoutsRef = useRef<number[]>([]);
+  const viewportResizeCleanupRef = useRef<(() => void) | null>(null);
+  const answerFormRef = useRef<AnswerFormHandle>(null);
+
   const [answerA, setAnswerA] = useState("");
   const [answerB, setAnswerB] = useState("");
+  const [activeInput, setActiveInput] = useState<ActiveAnswerInput>(0);
+  const [mobileFocusSpacerHeight, setMobileFocusSpacerHeight] = useState(0);
   const [inputError, setInputError] = useState("");
 
   const sessionProblemCount = session?.problems.length ?? null;
@@ -69,9 +84,21 @@ export default function PlayClient({ problemCount }: PlayClientProps) {
   useEffect(() => {
     setAnswerA("");
     setAnswerB("");
+    setActiveInput(0);
     setInputError("");
   }, [currentProblem?.key]);
 
+  const clearViewportFocusCleanup = useCallback(() => {
+    scrollTimeoutsRef.current.forEach((timeoutId) => {
+      window.clearTimeout(timeoutId);
+    });
+    scrollTimeoutsRef.current = [];
+    viewportResizeCleanupRef.current?.();
+    viewportResizeCleanupRef.current = null;
+  }, []);
+
+  useEffect(() => clearViewportFocusCleanup, [clearViewportFocusCleanup]);
+
   function handleSubmit(event: FormEvent<HTMLFormElement>) {
     event.preventDefault();
 
@@ -89,6 +116,94 @@ export default function PlayClient({ problemCount }: PlayClientProps) {
     submitAnswer({ a: parsedA, b: parsedB });
   }
 
+  function handleNextProblem() {
+    flushSync(() => {
+      nextProblem();
+    });
+    answerFormRef.current?.focusInput();
+  }
+
+  const handleInputBlur = useCallback(() => {
+    setMobileFocusSpacerHeight(0);
+  }, []);
+
+  const scrollKatexToViewportTop = useCallback(() => {
+    if (window.matchMedia(MOBILE_BREAKPOINT_QUERY).matches) return;
+
+    function alignKatex() {
+      const katexElement =
+        problemCardRef.current?.querySelector<HTMLElement>("span.katex");
+
+      if (!katexElement) return;
+
+      const rect = katexElement.getBoundingClientRect();
+      const scrollElement =
+        document.scrollingElement ?? document.documentElement;
+      const elementDocumentTop = window.pageYOffset + rect.top;
+      const maxScrollTop = Math.max(
+        0,
+        scrollElement.scrollHeight - window.innerHeight,
+      );
+      const scrollTop = Math.min(
+        maxScrollTop,
+        Math.max(0, elementDocumentTop),
+      );
+
+      if (Math.abs(window.pageYOffset - scrollTop) < 4) return;
+
+      scrollElement.scrollTop = scrollTop;
+      document.body.scrollTop = scrollTop;
+      window.scrollTo(0, scrollTop);
+    }
+
+    const visualViewport = window.visualViewport;
+    const keyboardHeight = Math.max(
+      0,
+      window.innerHeight -
+        (visualViewport?.height ?? window.innerHeight) -
+        (visualViewport?.offsetTop ?? 0),
+    );
+
+    setMobileFocusSpacerHeight(
+      Math.max(
+        window.innerHeight,
+        keyboardHeight + MOBILE_KEYBOARD_SPACER_OFFSET,
+      ),
+    );
+
+    clearViewportFocusCleanup();
+
+    if (visualViewport) {
+      let settleTimeoutId: number | null = null;
+
+      const handleViewportResize = () => {
+        if (settleTimeoutId !== null) {
+          window.clearTimeout(settleTimeoutId);
+        }
+
+        settleTimeoutId = window.setTimeout(() => {
+          alignKatex();
+        }, 180);
+      };
+
+      visualViewport.addEventListener("resize", handleViewportResize);
+      viewportResizeCleanupRef.current = () => {
+        visualViewport.removeEventListener("resize", handleViewportResize);
+        if (settleTimeoutId !== null) {
+          window.clearTimeout(settleTimeoutId);
+        }
+      };
+    }
+
+    window.requestAnimationFrame(() => {
+      window.requestAnimationFrame(alignKatex);
+    });
+    [900, 1300].forEach((delay) => {
+      const timeoutId = window.setTimeout(alignKatex, delay);
+      scrollTimeoutsRef.current.push(timeoutId);
+    });
+  }, [clearViewportFocusCleanup]);
+
   if (!session || sessionNeedsInit) {
     return (
       <main className="flex min-h-screen items-center bg-slate-50 px-6 py-12 text-slate-950">
@@ -144,7 +259,10 @@ export default function PlayClient({ problemCount }: PlayClientProps) {
           />
         </div>
 
-        <div className="rounded-md bg-white p-6 shadow-sm ring-1 ring-slate-200 sm:p-8">
+        <div
+          ref={problemCardRef}
+          className="rounded-md bg-white px-6 pt-6 pb-2 shadow-sm ring-1 ring-slate-200 sm:p-8"
+        >
           <p className="mb-4 text-sm font-semibold text-slate-500">
             괄호를 풀어 두 항을 순서대로 입력하세요.
           </p>
@@ -153,22 +271,36 @@ export default function PlayClient({ problemCount }: PlayClientProps) {
           </div>
         </div>
 
-        <AnswerForm
+        {!submitted ? (
-          answerA={answerA}
+          <AnswerForm
-          answerB={answerB}
+            ref={answerFormRef}
-          disabled={submitted}
+            answerA={answerA}
-          error={inputError}
+            answerB={answerB}
-          onAnswerAChange={setAnswerA}
+            activeInput={activeInput}
-          onAnswerBChange={setAnswerB}
+            error={inputError}
-          onSubmit={handleSubmit}
+            onActiveInputChange={setActiveInput}
-        />
+            onAnswerAChange={setAnswerA}
+            onAnswerBChange={setAnswerB}
+            onInputBlur={handleInputBlur}
+            onInputFocus={scrollKatexToViewportTop}
+            onSubmit={handleSubmit}
+          />
+        ) : null}
 
         {currentResult ? (
           <FeedbackPanel
             result={currentResult}
             answerLatex={currentProblem.latexAfter}
             isLastProblem={isLastProblem}
-            onNext={nextProblem}
+            onNext={handleNextProblem}
+          />
+        ) : null}
+
+        {!submitted && mobileFocusSpacerHeight > 0 ? (
+          <div
+            aria-hidden="true"
+            className="sm:hidden"
+            style={{ height: mobileFocusSpacerHeight }}
           />
         ) : null}
       </section>

components/game/AnswerForm.tsx

@@ -1,93 +1,213 @@
 "use client";
 
-import { useEffect, useRef } from "react";
+import {
+  forwardRef,
+  useCallback,
+  useId,
+  useImperativeHandle,
+  useRef,
+} from "react";
 import type { FormEvent } from "react";
 
+export type ActiveAnswerInput = 0 | 1;
+
+export interface AnswerFormHandle {
+  focusInput: () => void;
+}
+
 interface AnswerFormProps {
   answerA: string;
   answerB: string;
-  disabled: boolean;
+  activeInput: ActiveAnswerInput;
   error: string;
   onAnswerAChange: (value: string) => void;
   onAnswerBChange: (value: string) => void;
+  onActiveInputChange: (input: ActiveAnswerInput) => void;
+  onInputBlur?: () => void;
+  onInputFocus?: () => void;
   onSubmit: (event: FormEvent<HTMLFormElement>) => void;
 }
 
-export default function AnswerForm({
+const AnswerForm = forwardRef<AnswerFormHandle, AnswerFormProps>(function AnswerForm(
-  answerA,
+  {
-  answerB,
+    answerA,
-  disabled,
+    answerB,
-  error,
+    activeInput,
-  onAnswerAChange,
+    error,
-  onAnswerBChange,
+    onAnswerAChange,
-  onSubmit,
+    onAnswerBChange,
-}: AnswerFormProps) {
+    onActiveInputChange,
-  const firstInputRef = useRef<HTMLInputElement>(null);
+    onInputBlur,
-  const secondInputRef = useRef<HTMLInputElement>(null);
+    onInputFocus,
-  const submitButtonRef = useRef<HTMLButtonElement>(null);
+    onSubmit,
+  },
+  ref,
+) {
+  const inputId = useId();
+  const formRef = useRef<HTMLFormElement>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
 
-  useEffect(() => {
+  const activeAnswer = activeInput === 0 ? answerA : answerB;
-    if (!disabled) {
+  const activeLabel = activeInput === 0 ? "첫째 항" : "둘째 항";
-      firstInputRef.current?.focus();
+  const activeEnterKeyHint = activeInput === 0 ? "next" : "done";
+  const activeAnswerChange =
+    activeInput === 0 ? onAnswerAChange : onAnswerBChange;
+
+  const focusInput = useCallback(() => {
+    const input = inputRef.current;
+
+    if (!input) return;
+
+    const wasFocused = document.activeElement === input;
+
+    input.focus({ preventScroll: true });
+
+    if (wasFocused) {
+      onInputFocus?.();
     }
-  }, [disabled]);
+  }, [onInputFocus]);
+
+  useImperativeHandle(ref, () => ({ focusInput }), [focusInput]);
+
+  function setAnswer(input: ActiveAnswerInput, value: string) {
+    if (input === 0) {
+      onAnswerAChange(value);
+    } else {
+      onAnswerBChange(value);
+    }
+  }
+
+  function toggleMinus() {
+    activeAnswerChange(
+      activeAnswer.startsWith("-") ? activeAnswer.slice(1) : `-${activeAnswer}`,
+    );
+    focusInput();
+  }
+
+  function moveToInput(input: ActiveAnswerInput, reset = false) {
+    onActiveInputChange(input);
+    if (reset) {
+      setAnswer(input, "");
+    }
+    focusInput();
+  }
+
+  function handleEnter() {
+    if (activeInput === 0) {
+      moveToInput(1);
+      return;
+    }
+
+    formRef.current?.requestSubmit();
+  }
+
+  const answerButtons = [
+    {
+      index: 0 as const,
+      label: "첫째 항",
+      value: answerA,
+    },
+    {
+      index: 1 as const,
+      label: "둘째 항",
+      value: answerB,
+    },
+  ];
 
   return (
     <form
+      ref={formRef}
       onSubmit={onSubmit}
       className="rounded-md bg-white p-6 shadow-sm ring-1 ring-slate-200 sm:p-8"
     >
-      <div className="grid gap-4 sm:grid-cols-2">
+      <div className="flex flex-col gap-4">
-        <label className="flex flex-col gap-2 text-sm font-semibold text-slate-700">
+        <div>
-          첫째 항
+          <label
-          <input
+            htmlFor={inputId}
-            ref={firstInputRef}
+            className="mb-2 block text-sm font-semibold text-slate-700"
-            value={answerA}
+          >
-            onChange={(event) => onAnswerAChange(event.target.value)}
+            {activeLabel}
-            onKeyDown={(event) => {
+          </label>
-              if (event.key === "Enter") {
+          <div className="flex h-12 w-full min-w-0 overflow-hidden rounded-md border border-slate-300 bg-white focus-within:border-emerald-600 focus-within:ring-2 focus-within:ring-emerald-200 sm:border-0 sm:focus-within:ring-0">
-                event.preventDefault();
+            <button
-                secondInputRef.current?.focus();
+              type="button"
+              onPointerDown={(event) => event.preventDefault()}
+              onClick={toggleMinus}
+              aria-label={`${activeLabel} 음수 기호 입력`}
+              className="inline-flex h-full w-12 shrink-0 items-center justify-center border-r border-slate-300 px-2 text-sm font-semibold text-slate-800 transition hover:bg-slate-100 focus:outline-none sm:hidden"
+            >
+              -/+
+            </button>
+            <input
+              id={inputId}
+              ref={inputRef}
+              type="text"
+              value={activeAnswer}
+              onFocus={onInputFocus}
+              onBlur={onInputBlur}
+              onChange={(event) => activeAnswerChange(event.target.value)}
+              onKeyDown={(event) => {
+                if (event.key === "Enter") {
+                  event.preventDefault();
+                  handleEnter();
+                }
+              }}
+              autoComplete="off"
+              enterKeyHint={activeEnterKeyHint}
+              inputMode="numeric"
+              pattern="-?[0-9]*"
+              className="h-full min-w-0 flex-1 px-3 text-lg font-semibold text-slate-950 outline-none sm:rounded-md sm:border sm:border-slate-300 sm:px-4 sm:transition sm:focus:border-emerald-600 sm:focus:ring-2 sm:focus:ring-emerald-200"
+            />
+            <button
+              type="button"
+              onPointerDown={(event) => event.preventDefault()}
+              onClick={handleEnter}
+              aria-label={
+                activeInput === 0
+                  ? "첫째 항 입력 완료 후 둘째 항으로 이동"
+                  : "둘째 항 입력 완료 후 제출"
               }
-            }}
+              className="inline-flex h-full w-12 shrink-0 items-center justify-center border-l border-slate-300 px-2 text-xl font-semibold text-slate-800 transition hover:bg-slate-100 focus:outline-none sm:hidden"
-            disabled={disabled}
+            >
-            inputMode="numeric"
+              ↵
-            className="h-12 rounded-md border border-slate-300 px-4 text-lg font-semibold text-slate-950 outline-none transition focus:border-emerald-600 focus:ring-2 focus:ring-emerald-200 disabled:bg-slate-100"
+            </button>
-          />
+          </div>
-        </label>
+        </div>
-        <label className="flex flex-col gap-2 text-sm font-semibold text-slate-700">
+
-          둘째 항
+        <div
-          <input
+          className="inline-flex w-fit max-w-full gap-1 rounded-md border border-slate-300 bg-white p-1 shadow-sm"
-            ref={secondInputRef}
+          role="group"
-            value={answerB}
+          aria-label="입력 항 선택"
-            onChange={(event) => onAnswerBChange(event.target.value)}
+        >
-            onKeyDown={(event) => {
+          {answerButtons.map((button) => {
-              if (event.key === "Enter") {
+            const selected = activeInput === button.index;
-                event.preventDefault();
+
-                submitButtonRef.current?.click();
+            return (
-              }
+              <button
-            }}
+                key={button.index}
-            disabled={disabled}
+                type="button"
-            inputMode="numeric"
+                onPointerDown={(event) => event.preventDefault()}
-            className="h-12 rounded-md border border-slate-300 px-4 text-lg font-semibold text-slate-950 outline-none transition focus:border-emerald-600 focus:ring-2 focus:ring-emerald-200 disabled:bg-slate-100"
+                onClick={() => moveToInput(button.index, true)}
-          />
+                aria-pressed={selected}
-        </label>
+                aria-label={`${button.label} 다시 입력`}
+                className={`inline-flex h-10 min-w-20 items-center justify-center rounded px-3 text-base font-semibold transition focus:outline-none focus:ring-2 focus:ring-emerald-500 focus:ring-offset-2 ${
+                  selected
+                    ? "bg-emerald-700 text-white"
+                    : "text-slate-700 hover:bg-slate-100"
+                }`}
+              >
+                {button.value || "?"}
+              </button>
+            );
+          })}
+        </div>
       </div>
 
       {error ? (
         <p className="mt-3 text-sm font-semibold text-red-700">{error}</p>
       ) : null}
-
-      <div className="mt-6 flex flex-wrap gap-3">
-        <button
-          ref={submitButtonRef}
-          type="submit"
-          disabled={disabled}
-          className="inline-flex h-12 items-center justify-center rounded-md bg-emerald-700 px-6 text-base font-semibold text-white transition hover:bg-emerald-800 focus:outline-none focus:ring-2 focus:ring-emerald-500 focus:ring-offset-2 disabled:cursor-not-allowed disabled:bg-slate-300"
-        >
-          제출
-        </button>
-      </div>
     </form>
   );
-}
+});
+
+export default AnswerForm;

package.json

@@ -6,6 +6,7 @@
   "scripts": {
     "dev": "next dev",
     "build": "next build",
+    "postbuild": "mkdir -p .next/standalone/.next && cp -R .next/static .next/standalone/.next/static",
     "start": "next start",
     "test": "vitest run",
     "lint": "next lint"