#302

frontend/AGENTS.md

@@ -4,7 +4,8 @@
 
 These rules apply to work under `frontend/`.
 
-This is a Vite + React + TypeScript app using TanStack Query, Tailwind CSS, Framer Motion, Radix UI-style components, MDX, and Zustand.
+This is a Vite + React + TypeScript app using TanStack Query, Tailwind CSS,
+Framer Motion, Radix UI-style components, MDX, and Zustand.
 
 ## Commands
 
@@ -17,9 +18,11 @@ npm run lint
 npm run preview
 ```
 
-`npm run build` runs `tsc -b && vite build`, and `postbuild` runs `node scripts/generate-sitemap.js`.
+`npm run build` runs `tsc -b && vite build`, and `postbuild` runs
+`node scripts/generate-sitemap.js`.
 
-There is currently no `test` script in `package.json`. Do not run or report `npm test` unless a test script is added.
+There is currently no `test` script in `package.json`. Do not run or report
+`npm test` unless a test script is added.
 
 After frontend changes, run:
 
@@ -32,18 +35,33 @@ If either command cannot be run or fails, report the exact command and failure.
 
 ## TypeScript
 
-- TypeScript is strict. `tsconfig.app.json` enables `strict`, `noUnusedLocals`, `noUnusedParameters`, `erasableSyntaxOnly`, `noFallthroughCasesInSwitch`, and `noUncheckedSideEffectImports`.
+- TypeScript is strict. `tsconfig.app.json` enables `strict`,
+  `noUnusedLocals`, `noUnusedParameters`, `erasableSyntaxOnly`,
+  `noFallthroughCasesInSwitch`, and `noUncheckedSideEffectImports`.
 - Keep types explicit at module boundaries, API helpers, and exported utilities.
 - Use `import type` for type-only imports.
 - Prefer existing shared types from `src/types.ts` before adding local duplicate types.
-- Preserve the repository's existing spacing style in TypeScript, including GNU-style spacing before call parentheses where it is already used.
+- Preserve the repository's existing spacing style in TypeScript, including
+  GNU-style spacing before call parentheses where it is already used.
 - Prefer single quotes for strings unless interpolation or escaping makes double quotes better.
+- Never write a TypeScript or TSX line longer than 99 characters.
+- Aim to keep TypeScript and TSX lines within 79 characters where practical.
+- Use 4-space logical indentation in TypeScript and TSX.
+- In TypeScript and TSX only, replace every leading run of 8 spaces with a tab
+  to reduce bytes.
+- Treat one leading tab as exactly equivalent to 8 leading spaces.
+- Use tabs only for leading indentation. Never replace spaces that occur after
+  a non-space character on the same line.
 
 ## React
 
 - Use function components.
-- Existing page components commonly export an anonymous function satisfying `FC`; match nearby file style when editing.
+- Existing page components commonly export an anonymous function satisfying
+  `FC`; match nearby file style when editing.
 - React hooks must be called unconditionally and at the top level of components or custom hooks.
+- Gate editing and other privileged controls with shared permission helpers
+  such as `canEditContent`, instead of showing controls and relying only on a
+  later API failure.
 - Keep page-level components under `src/pages`.
 - Keep shared and feature components under `src/components`.
 - Use `react-router-dom` route params and navigation patterns already present in `src/App.tsx`.
@@ -52,17 +70,23 @@ If either command cannot be run or fails, report the exact command and failure.
 ## TanStack Query
 
 - Use `@tanstack/react-query` for server state.
-- Query keys should come from `src/lib/queryKeys.ts`; add key builders there instead of using ad hoc arrays in components.
-- Fetch functions should live in domain helpers under `src/lib`, such as `posts.ts`, `tags.ts`, or `wiki.ts`.
-- Use `useQueryClient().invalidateQueries` with the shared root keys when mutations affect cached lists or detail views.
-- The app-wide `QueryClient` is configured in `src/main.tsx`; do not create additional clients in feature code.
+- Query keys should come from `src/lib/queryKeys.ts`; add key builders there
+  instead of using ad hoc arrays in components.
+- Fetch functions should live in domain helpers under `src/lib`, such as
+  `posts.ts`, `tags.ts`, or `wiki.ts`.
+- Use `useQueryClient().invalidateQueries` with the shared root keys when
+  mutations affect cached lists or detail views.
+- The app-wide `QueryClient` is configured in `src/main.tsx`; do not create
+  additional clients in feature code.
 
 ## API calls
 
 - Use `src/lib/api.ts` for HTTP calls.
-- The API wrapper attaches `X-Transfer-Code` from `localStorage` and converts non-blob responses to camelCase.
+- The API wrapper attaches `X-Transfer-Code` from `localStorage` and converts
+  non-blob responses to camelCase.
 - Send Rails snake_case params and request body keys where the backend expects them.
-- Do not bypass the API wrapper unless there is a specific reason, such as a third-party request outside the Rails API.
+- Do not bypass the API wrapper unless there is a specific reason, such as a
+  third-party request outside the Rails API.
 - For blob responses, pass `responseType: 'blob'` so the wrapper does not camelCase the body.
 
 ## Imports and aliases
@@ -76,17 +100,41 @@ If either command cannot be run or fails, report the exact command and failure.
 
 - Tailwind scans `src/**/*.{html,js,ts,jsx,tsx,mdx}`.
 - Use `cn` from `src/lib/utils.ts` for conditional class names and class merging.
-- Reuse components from `src/components/common`, `src/components/layout`, and `src/components/ui` before adding new primitives.
+- Reuse components from `src/components/common`, `src/components/layout`, and
+  `src/components/ui` before adding new primitives.
 - Keep Tailwind classes consistent with nearby components.
-- When adding dynamic tag color classes, update `tailwind.config.js` safelist if the class cannot be statically detected.
+- Prefer restrained, content-first UI chrome: avoid adding card backgrounds,
+  heavy borders, or nested panel decoration unless the surrounding screen
+  already uses them.
+- Keep operational screens dense and direct; trim explanatory copy and use
+  short Japanese labels that fit the control.
+- Preserve existing Japanese tone and orthography in nearby UI text, including
+  old-kana wording where the file already uses it.
+- When adding dynamic tag color classes, update `tailwind.config.js` safelist
+  if the class cannot be statically detected.
 - Do not introduce new UI libraries or production dependencies without approval.
 
+## TSX formatting
+
+- Preserve compact TSX expression shapes such as inline ternary branches and
+  closing `</div>)` forms when nearby code uses them.
+- For long Tailwind `className` strings, wrap across lines only when needed.
+- Keep continuation indentation aligned with the 4-space logical indentation
+  rule, using tabs only as leading 8-space compression.
+- Do not add braces around `if`, `else`, or `for` bodies when the body is a
+  single physical line.
+- Always add braces around `if`, `else`, or `for` bodies when the body spans
+  two or more physical lines, even if it is one statement.
+- Avoid reformatting unrelated JSX.
+
 ## Lint and build constraints
 
-- ESLint uses `@eslint/js`, `typescript-eslint`, `eslint-plugin-react-hooks`, and `eslint-plugin-react-refresh`.
+- ESLint uses `@eslint/js`, `typescript-eslint`, `eslint-plugin-react-hooks`,
+  and `eslint-plugin-react-refresh`.
 - The hooks rules are enforced; fix hook ordering instead of disabling the rule.
 - `react-refresh/only-export-components` is enabled as a warning with `allowConstantExport`.
-- Build failures from unused locals or unused parameters are TypeScript errors, not lint-only issues.
+- Build failures from unused locals or unused parameters are TypeScript
+  errors, not lint-only issues.
 
 ## Files to avoid in routine work