개발세발

Flutter `Scrollable.ensureVisible` — 포커스·에러 필드를 키보드 뒤에 두지 않기

3onK — Tue, 29 Sep 2026 11:56:54 +0900

한 줄 요약: 긴 약관·배송·설정 폼에서 다음 필드 requestFocus()만 하면 소프트키보드에 가려 사용자가 어디를 치는지 모른다. Flutter Scrollable.ensureVisible(context, …) 로 포커스/에러 위젯을 스크롤 뷰포트 안으로 가져오는 것이 계약이다. FocusNode·TextInputAction(#57)·TextFormField validator sync(#98)·Form autovalidate(#35)·MediaQuery.viewInsetsOf(#102)·ScrollController(#44)·ListView itemExtent(#173)과 겹치지 않게, 이번엔 ensureVisible 스크롤 정렬만 판다.

버전 가정: Flutter 안정 채널의 Scrollable.ensureVisible (BuildContext · duration · curve · alignment · alignmentPolicy 등). ScrollController.animateTo로 offset을 직접 계산하는 패턴·패키지 scroll_to_index 심화는 범위 밖. 코드는 최소 골격.

교차 링크(재탕 금지):

FocusNode · autofocus · TextInputAction → draft 57
TextFormField validator · focus sync → draft 98 (포커스 계약; 스크롤은 위임)
Form · autovalidateMode · GlobalKey → draft 35
MediaQuery.viewInsetsOf · sizeOf → draft 102
ScrollController · NotificationListener → draft 44
ListView itemExtent · prototypeItem → draft 173

1차 소스: Flutter API Scrollable.ensureVisible.

이 글에서 다루는 것

증상 → 언제 ensureVisible
포커스 후 / 검증 실패 후 최소 패턴
alignment · duration 감각
AI 안티패턴 · FAQ · 체크리스트

1. 증상과 원인 — 답부터

흔한 증상

“다음”을 눌렀더니 커서는 아래 필드로 갔는데 화면은 그대로 · 키보드는 필드를 덮음
제출 실패 후 첫 에러에 requestFocus()만 함 → 에러 보더가 뷰 밖
AI가 ScrollController.jumpTo(9999) 또는 primaryFocus만 생성
NestedScrollView·탭 안 폼에서 잘못된 Scrollable을 스크롤

원인 한 줄

포커스는 포커스 트리 문제이고, 보이는지는 스크롤 가능 조상 문제다. Scrollable.ensureVisible 는 해당 context가 속한 Scrollable들을 올라가며 그 위젯이 보이게 맞춘다.

상황	처방
필드 이동 후 가림	focus 후 `ensureVisible(fieldContext)`
검증 실패 첫 에러	`requestFocus` + `ensureVisible`
키보드 inset만 알고 싶음	`viewInsetsOf`(#102) — 스크롤 명령과 별개
offset을 내가 계산	최후 · ensureVisible으로 부족한 티켓만

2. 최소 패턴 — 포커스 다음

Future<void> focusAndReveal(FocusNode node, BuildContext fieldContext) async {
  node.requestFocus();
  await Future<void>.delayed(Duration.zero); // 포커스·키보드 레이아웃 한 프레임
  if (!fieldContext.mounted) return;
  await Scrollable.ensureVisible(
    fieldContext,
    duration: const Duration(milliseconds: 250),
    curve: Curves.easeOut,
    alignment: 0.1, // 상단에 살짝 여유 (0.0=맨 위, 1.0=맨 아래 쪽)
  );
}

TextFormField에 연결:

TextFormField(
  focusNode: phoneFocus,
  textInputAction: TextInputAction.next,
  onFieldSubmitted: (_) {
    focusAndReveal(addressFocus, addressKey.currentContext!);
  },
  // ...
)

GlobalKey 또는 필드 루트 Builder의 context를 넘긴다. requestFocus만 하고 context가 다른 위젯이면 엉뚱한 곳이 스크롤된다.
mounted / context.mounted 체크는 async gap 글(#8)과 같은 습관.
alignment: 0.1 정도는 키보드·앱바에 가리지 않게 위쪽 여유를 주는 감각값 — 제품 UI에 맞춰 조정.

3. 검증 실패 첫 에러

Future<void> revealFirstError(GlobalKey<FormState> formKey, List<FocusNode> order) async {
  if (formKey.currentState?.validate() ?? false) return;
  for (final node in order) {
    final ctx = node.context;
    if (ctx == null) continue;
    // 에러 있는 필드만 — validator/autovalidate와 팀 계약에 맞게 조건 보강
    node.requestFocus();
    await Scrollable.ensureVisible(
      ctx,
      duration: const Duration(milliseconds: 250),
      curve: Curves.easeOut,
      alignment: 0.15,
    );
    break;
  }
}

#35·#98이 검증·포커스 순서를 담당한다. 이 글은 그 다음 한 줄 — 보이게 스크롤.

4. alignment · alignmentPolicy 감각

인자	실무 감각
`alignment`	0.0에 가까울수록 타깃이 뷰포트 상단 쪽. 키보드에 가리면 0.0~0.2에서 시작
`duration` / `curve`	0ms jump는 어지러움 · 200–300ms easeOut이 무난
`alignmentPolicy`	이미 충분히 보이면 스크롤 생략 등 정책 — 과도한 점프 티켓에 검토

Nested·커스텀 스크롤에서는 필드 context가 진짜로 그 스크롤 트리 안인지를 먼저 확인한다(#54·#113 감각). ensureVisible은 마법이 아니라 조상 Scrollable 탐색이다.

5. AI 안티패턴

안티패턴	대신
`jumpTo(double.infinity)` / 매직 offset	`ensureVisible(fieldContext)`
focus만 하고 QA에 “가림” 재오픈	focus + ensureVisible 한 함수로 묶기
매 keypress마다 ensureVisible	submitted·next·validate 실패 시에만
viewInsets 패딩 없이 ensureVisible만 무한 조정	폼 패딩/`viewInsetsOf`(#102)와 역할 분리
#98 포커스 글에 스크롤 장문 합치기	티켓 분리 — 포커스 vs 가시성

FAQ

Q. ScrollController.animateTo가 더 정확한 거 아닌가?
A. offset을 당신이 아는 목록(고정 extent 등)이면 가능. 폼·가변 높이·중첩에서는 ensureVisible이 기본값.

Q. ListView.builder 재활용에 context가 죽지 않나?
A. 화면에 없는 항목은 context가 없을 수 있다. 에러/포커스 대상이 빌드돼 있는지가 전제. 필요 시 해당 인덱스로 먼저 스크롤(#173 extent 힌트와 별 티켓).

Q. MediaQuery.viewInsetsOf(#102)랑 동시에?
A. inset은 하단 패딩·리사이즈, ensureVisible은 스크롤 위치. 둘 다 필요할 수 있고 한 API로 합치지 말 것.

Q. TextFormField 글(#98)에 이미 있지 않나?
A. #98은 포커스·validator sync. ensureVisible은 범위 밖으로 위임해 둔 항목을 이번에만 판다.

체크리스트

next/에러 경로에 requestFocus + Scrollable.ensureVisible 묶음
필드 전용 BuildContext/GlobalKey를 넘기는가
async 후 mounted 가드
alignment·duration을 키보드+앱바 QA로 확인
NestedScroll 폼이면 조상 Scrollable 소유 확인
#57·#98·#102와 역할이 문서/PR에 분리돼 있는가

자체 검수

기술: ensureVisible 인자·포커스 후 스크롤만. offset 매직·패키지 강제 없음. #98·#57·#102와 분리.
용어/맞춤법: Scrollable.ensureVisible / FocusNode / viewInsets 통일. 본문 H1 없음 · 한 줄 요약:부터 시작.

Ember-1(Fireworks) on AI Gateway(2026-09-27) — 짧은 reasoning 트레이스 FE 데스크 노트

3onK — Tue, 29 Sep 2026 11:51:41 +0900

한 줄 요약: 2026-09-29 기준, late-Sep FE·에이전트 데스크가 열어볼 공식 공지는 Vercel Changelog Ember-1 from Fireworks now available on AI Gateway(Published September 27, 2026 · Zachary Chen, Jerilyn Zheng)다. 요지(원문 고정): (1) 모델 id fireworks/ember-1 (2) Kimi K3 기반 research preview reasoning 모델 · 코딩·에이전트 워크플로 (3) Fireworks 평가에서 Kimi K3 대비 약 40% 적은 generated tokens(comparable quality) — 반복 호출 시 출력 비용·후속 컨텍스트 감소 서술 (4) 1M-token 컨텍스트 · text/image 입력 · tool calling · implicit prompt caching (5) Fireworks 엔드포인트 Zero Data Retention · No Prompt Training (6) research preview · 초기 2주 윈도우 (7) AI SDK streamText · Claude Code/Codex/fx · Chat Completions + npx vercel ai-gateway setup / /model. Sonnet 5.5(#167)·Pixel Canary(#158)·Opus 5.5(#130)·FlashX(#111)와 제품 면이 다름 — 이번엔 Ember-1 Gateway 롤아웃 FE 함의만. 원문에 없는 단가표·벤치 재현·“Kimi를 대체한다” 단정은 적지 않는다.

교차 링크(재탕 금지):

Claude Sonnet 5.5 Gateway → draft 167
Pixel Canary stealth → draft 158
Claude Opus 5.5 Gateway → draft 130
GPT-6 Sol/Luna → draft 134
GLM 5.3 FlashX → draft 111
Managed Agents auto → draft 122

1차 확인(2026-09-29): Vercel Changelog 2026-09-27만. 배포 전 URL·preview 윈도우 잔여 일수 재확인.

이 글에서 다루는 것

공지가 말한 것 / 안 말한 것
왜 FE 데스크 뉴스인가 (짧은 트레이스·반복 루프)
지금 / 스테이징 / 안 함
FAQ · 체크리스트

1. 답 먼저 — 왜 FE 뉴스인가

에이전트 루프는 같은 모델 호출을 N번 한다. 원문이 강조하는 포인트는 “더 똑똑한 새 플래그십”이 아니라, Fireworks 평가 기준 생성 토큰이 약 40% 적다는 것과 그것이 출력 비용·이후 스텝에 들고 가는 컨텍스트에 미치는 영향이다. FE 데스크에서는 툴 루프·리뷰 봇·짧은 패치 에이전트 슬롯 후보로 읽으면 된다.

역할	Changelog 요지
모델 ID	`fireworks/ember-1`
성격(원문)	research preview · Kimi K3 기반 reasoning · coding/agentic
효율(원문)	~40% fewer generated tokens vs Kimi K3 (Fireworks evals, comparable quality)
창·입력	1M context · text + image · tool calling · implicit prompt caching
컴플라이언스(원문)	Fireworks endpoint: ZDR · No Prompt Training
기간	research preview · initial two-week window
연결면	AI SDK · Chat Completions · Claude Code / Codex / fx + `vercel ai-gateway setup`

슬랙 한 줄:

Ember-1 Gateway(fireworks/ember-1) 올림. 짧은 reasoning 트레이스 후보. research preview 2주. Sonnet/Opus/Pixel 슬롯과 섞지 말 것.

2. Changelog가 말한 것 / 안 말한 것

말한 것

AI Gateway에 Ember-1 가용, id fireworks/ember-1
Kimi K3 기반 research preview reasoning · coding/agentic
Fireworks: ~40% fewer generated tokens at comparable quality (their evaluations)
반복 모델 호출에서 짧은 reasoning trace → 출력 비용·후속 컨텍스트 감소 서술
1M context · text/image · tool calling · implicit prompt caching
Fireworks endpoint ZDR · No Prompt Training
research preview · initial two-week window
streamText({ model: 'fireworks/ember-1', ... }) 예시
Claude Code / Codex / fx: setup 후 /model(Codex는 codex --model fireworks/ember-1도)
Chat Completions 예시(Gateway base URL)
Gateway 단일 API · usage/cost · budgets · routing

안 말한 것 (추측 금지)

토큰 단가표·우리 계정 쿼터 배수
“Sonnet/Opus/Pixel을 대체한다” / Cursor 기본값 변경
40% 수치의 독립 재현·벤치 리더보드 순위
preview 종료 후 GA 일정·가격 확정
Gateway 전체 ZDR이 Fireworks 엔드포인트와 동일 설정 UI라는 단정(원문은 Fireworks endpoint 기준으로 ZDR/No Prompt Training)

3. FE 데스크 관점 — 슬롯을 나누는 법

슬롯	후보(기존 글)	이번 공지
일상 PR·문서	Sonnet 5.5 (#167)	비대상(비교 단정 금지)
긴 에이전트·고난도	Opus 5.5 (#130)	비대상
스텔스/실험 FE 디자인	Pixel Canary (#158)	비대상
고속 서빙	FlashX (#111)	비대상
짧은 reasoning · 반복 툴 루프 실험	(팀 표)	Ember-1 후보

실무 규칙 초안:

스테이징 에이전트 1대에만 fireworks/ember-1을 올려 flake·과잉/과소 추론을 1주 관찰(또는 preview 잔여 기간).
preview 2주 윈도우를 캘린더에 적고, 종료 후 슬롯을 되돌릴 rollback id를 표에 고정.
ZDR/No Prompt Training이 필요한 레포는 원문대로 Fireworks endpoint 옵션·팀 Gateway 콘솔을 진실로 확인 후 적용.
Sonnet(#167)·Opus(#130)·Pixel(#158) 경로의 프롬프트/thinking 가드를 그대로 복사·삭제하지 말 것 — 모델 계약이 다름.
npx vercel ai-gateway setup 후 /model에 id가 보이는지 확인.

4. 원문 코드 골격 (그대로 읽기)

import { streamText } from 'ai';

const result = streamText({
  model: 'fireworks/ember-1',
  prompt: 'Write a retry helper with exponential backoff.',
});

에이전트:

npx vercel ai-gateway setup
# Claude Code / Codex / fx 에서 /model → Ember-1
# Codex: codex --model fireworks/ember-1

5. 지금 / 스테이징 / 안 함

상태	조건
지금	Gateway 카탈로그에 id 노출 확인 · 내부 툴 루프 PoC 1경로
스테이징	반복 호출 많은 리뷰/패치 봇 1대 · 토큰·품질·preview 만료일 관찰
안 함	프로덕션 기본 모델을 preview 기간에 전면 교체 · Sonnet/Opus 설정과 뭉뚱그려 교체 · 원문 없는 단가로 ROI 확정

FAQ

Q. “40% fewer tokens”를 우리 대시보드 숫자로 써도 되나?
A. 원문은 Fireworks evaluations 기준. 내부 측정 전에는 슬랙/위키에 “벤더 주장”으로만 인용.

Q. Sonnet 5.5 글(#167)이랑 같이 읽나?
A. 일상 슬롯이면 #167. 짧은 reasoning·반복 루프 실험이면 이 글. 한 PR에 모델을 섞어 쓰지 말 것.

Q. preview 2주가 지나면?
A. 원문에 GA 일정 없음. 만료 전 rollback id를 표에 적어 둔다.

Q. ZDR이 Gateway 기본인가?
A. 원문은 Fireworks endpoint의 ZDR · No Prompt Training. 설정 방식·기본 on 여부는 팀 콘솔·문서가 진실.

체크리스트

Changelog URL·날짜(2026-09-27)·모델 id fireworks/ember-1 재확인
research preview · two-week window 만료일을 팀 캘린더에 기록
반복 툴 루프 슬롯 vs Sonnet/Opus/Pixel 분리표 업데이트
ZDR/No Prompt Training 필요 레포 · Fireworks endpoint 옵션 확인
vercel ai-gateway setup + /model 피커 확인
스테이징 1대 관찰 후 전면 여부 결정(preview 만료 전)

자체 검수

사실/날짜/출처: Vercel Changelog 2026-09-27만 인용. 단가·독립 벤치·타 모델 대체 단정 없음. 40%는 Fireworks evals 인용으로만.
용어/맞춤법: Ember-1 / fireworks/ember-1 / Fireworks / Kimi K3 / Gateway 표기 통일. #167·#158·#130·#111과 각도 분리. 본문 H1 없음.

CSS `light-dark()` — 라이트/다크 색을 미디어쿼리 복붙으로 끝내지 않기

3onK — Tue, 29 Sep 2026 11:47:33 +0900

한 줄 요약: 라이트/다크마다 :root 변수를 @media (prefers-color-scheme: dark)에 통째로 복붙하면 토큰 표가 두 벌이 되고 AI가 한쪽만 고친다. CSS light-dark(light, dark) 는 한 속성에서 두 값을 넘기고, 문서/color-scheme이 고른 쪽에 맞춰 고른다. color-mix·relative color(#163)·:has(#148)·Container Queries(#143)·prefers-reduced-motion(#108)·field-sizing(#169)과 겹치지 않게, 이번엔 라이트/다크 한 줄 선택만 판다.

버전 가정: CSS Color Module의 light-dark(). 사용 전제: 루트(또는 해당 요소)에 color-scheme: light dark(또는 강제 light/dark)가 잡혀 있어야 엔진이 어느 쪽을 고를지 안다. 지원 표·폴백은 배포 주 기준으로 팀 caniuse/MDN 재확인. 디자인 시스템 전체 마이그레이션 가이드 아님.

교차 링크(재탕 금지):

color-mix · relative color 파생 → draft 163 (파생 ≠ 라이트/다크 선택)
prefers-reduced-motion → draft 108
:has → draft 148
Container Queries → draft 143
field-sizing → draft 169

1차 감각 소스: MDN light-dark() · CSS Color. 지원율 숫자는 글에 박제하지 않는다.

이 글에서 다루는 것

답 먼저 — 미디어쿼리 이중 토큰 vs light-dark
최소 CSS · color-scheme 계약
토큰 표에 넣는 법 · 폴백
AI 안티패턴 · FAQ · 체크리스트

1. 증상과 원인 — 답부터

흔한 증상

--bg / --fg를 라이트 블록·다크 블록에 같은 이름 두 번 선언 → PR마다 한쪽만 수정
컴포넌트 SCSS에 @media (prefers-color-scheme: dark)가 산발 복붙
사용자 토글(클래스 .dark)과 OS prefers가 서로 다른 진실
AI가 다크 hex만 바꾸고 라이트 대비를 깨먹음

원인 한 줄

라이트/다크를 선택하는 문제와 파생(호버·disabled)하는 문제를 한 미디어쿼리 덩어리에 섞으면 표가 폭발한다. light-dark() 는 선택만 담당한다.

도구	역할
`light-dark(a, b)`	라이트값 / 다크값 한 줄 선택
`color-mix` / `oklch(from …)`(#163)	베이스에서 파생
`@media (prefers-color-scheme)`	레거시·미지원 폴백 · 토글과 충돌 시 신중
`.dark` 클래스 토글	제품이 OS와 무관하게 강제할 때 — `color-scheme`과 같이 설계

2. 최소 CSS

:root {
  color-scheme: light dark;
  --bg: light-dark(#f7f7f8, #121214);
  --fg: light-dark(#111113, #ececf1);
  --border: light-dark(#e4e4e7, #2a2a2e);
}

body {
  background: var(--bg);
  color: var(--fg);
}

핵심:

color-scheme: light dark — 없으면 light-dark()가 기대대로 안 고른다(엔진·문서 계약).
토큰 값은 light-dark로, 소비는 var(--bg) 한 경로.
강제 다크 페이지(마케팅 히어로만 다크 등)는 그 서브트리에 color-scheme: dark를 좁게.

사용자 토글 예시(패턴만):

:root[data-theme="light"] { color-scheme: light; }
:root[data-theme="dark"]  { color-scheme: dark; }
:root[data-theme="system"] { color-scheme: light dark; }

토글은 color-scheme만 바꾸고, --bg 선언은 light-dark 한 곳을 유지한다. 다크용 hex를 클래스마다 다시 쓰지 말 것.

3. 파생(#163)과 같이 쓸 때

:root {
  color-scheme: light dark;
  --brand: light-dark(#4f46e5, #818cf8);
  --brand-hover: color-mix(in oklab, var(--brand) 85%, black);
}

선택 = light-dark로 브랜드 베이스 두 값.
파생 = color-mix / relative color로 hover·muted.
다크에서 hover를 color-mix(..., white)로 올리다 네온이 되면 #163 FAQ처럼 베이스를 먼저 재조정.

4. 점진적 향상

:root {
  --bg: #f7f7f8;
  --fg: #111113;
}

@media (prefers-color-scheme: dark) {
  :root {
    --bg: #121214;
    --fg: #ececf1;
  }
}

@supports (color: light-dark(black, white)) {
  :root {
    color-scheme: light dark;
    --bg: light-dark(#f7f7f8, #121214);
    --fg: light-dark(#111113, #ececf1);
  }
}

@supports 안에서는 미디어쿼리 이중 선언을 제거하는 방향이 이상적이다. 지원 브라우저에 두 체계를 남기면 또 한쪽만 고치는 사고가 난다.

5. AI 안티패턴

안티패턴	대신
컴포넌트마다 dark 미디어쿼리 복붙	루트 토큰 + `light-dark`
`light-dark`만 넣고 `color-scheme` 생략	루트에 `light dark` 명시
#163 파생 글과 섞어 “light-dark가 호버를 계산”	선택은 light-dark, 파생은 color-mix
지원율 %를 README에 박제	배포 주 재확인 칸
시스템 토글 없이 OS만 / OS 무시 클래스만	`data-theme` + `color-scheme` 계약표

FAQ

Q. prefers-color-scheme만으로 충분하지 않나?
A. 동작은 한다. 문제는 토큰 이중 관리. light-dark는 선언을 한 줄로 접는다.

Q. Tailwind dark:와?
A. 유틸 클래스 전략과 병행 가능. 원시 토큰은 CSS 변수+light-dark로 두고 유틸은 그 변수를 소비하는 편이 AI 패치에 안전.

Q. color-mix 글(#163)이랑 뭐가 다르나?
A. #163은 한 테마 안에서 파생. 이 글은 라이트 vs 다크 선택.

체크리스트

:root에 color-scheme: light dark(또는 토글 계약)
핵심 토큰을 light-dark(light, dark)로 접었는가
컴포넌트 산발 @media dark 중복 제거
호버·disabled 파생은 #163 도구로 분리
@supports 폴백 전략·팀 지원 표 날짜 기록

자체 검수

기술: light-dark + color-scheme 계약만. 지원율 숫자 발명 없음. #163과 역할 분리 명시.
용어/맞춤법: light-dark / color-scheme / prefers-color-scheme 통일. 본문 H1 없음 · 한 줄 요약:부터 시작.

Flutter `ListView.builder` — `itemExtent` · `prototypeItem` 으로 스크롤 점프 줄이기

3onK — Tue, 29 Sep 2026 11:42:52 +0900

한 줄 요약: 카드 높이가 거의 고정인 피드인데 ListView.builder 만 쓰면, 스크롤 중 미측정 자식 때문에 점프·바운스가 난다. 높이를 아는 목록은 itemExtent(고정) 또는 prototypeItem(동일 레이아웃 샘플)으로 extent를 미리 알려 레이아웃 추정 비용을 줄이는 것이 계약이다. AnimatedList(#152)·ReorderableListView(#124)·RepaintBoundary(#170)·AutomaticKeepAlive(#47)·nested scroll(#113)과 겹치지 않게, 이번엔 builder 목록의 extent 힌트만 판다.

버전 가정: Flutter 3.x · ListView.builder / ListView.separated · itemExtent · prototypeItem (둘 다 쓰면 안 되는 조합 — API 계약상 상호 배타에 가깝게 쓴다). 완전 가변 높이(채팅 버블·접이식)는 itemExtent 금지. Sliver 심화·CustomScrollView 튜토리얼 아님.

교차 링크(재탕 금지):

AnimatedList insert/remove → draft 152
ReorderableListView → draft 124
RepaintBoundary 페인트 → draft 170 (페인트 ≠ layout extent)
AutomaticKeepAlive / IndexedStack → draft 47
nested ScrollNotification → draft 113
PageView onboarding → draft 140

1차 소스: ListView (itemExtent, prototypeItem)

이 글에서 다루는 것

증상 → extent를 언제 넘기는가
itemExtent vs prototypeItem
separated · 가변 높이 경계
AI 안티패턴 · FAQ · 체크리스트

1. 증상과 원인 — 답부터

흔한 증상

빠른 플링 후 스크롤바가 떨리거나 위치가 살짝 점프
이미지·한 줄 텍스트 카드인데도 스크롤이 “무거운” 느낌
하단으로 점프(jumpTo / 초기 initialScrollOffset) 시 오차
AI가 모든 리스트를 기본 builder 로만 생성 · extent 없음

원인 한 줄

빌더는 보이는 근처만 만드므로, 엔진은 아직 안 만든 자식의 높이를 추정한다. 추정이 빗나가면 스크롤 offset 보정이 점프로 보인다. extent를 알려 주면 추측이 줄어든다.

목록 특성	힌트
높이 완전 고정(예: 72)	`itemExtent: 72`
위젯 구조는 동일, 숫자만 쓰기 싫음	`prototypeItem: …`
행마다 높이 천차만별	extent 넣지 말 것 · 설계 재고

2. `itemExtent` — 숫자가 있을 때

ListView.builder(
  itemCount: items.length,
  itemExtent: 72, // 고정 행 높이(논리 픽셀)
  itemBuilder: (context, index) {
    final item = items[index];
    return OrderRow(item: item); // 내부도 72에 맞게
  },
)

행 위젯 실제 높이와 itemExtent 가 어긋나면 overflow/클리핑이 난다. 패딩·타이틀 줄 수까지 포함해 맞출 것.
ListView.separated 는 separator 높이까지 고려해야 해서 단순 고정 행보다 설계가 지저분해진다 — 고정 피드를 우선 builder + extent로.

3. `prototypeItem` — 샘플 한 칸

ListView.builder(
  itemCount: items.length,
  prototypeItem: const OrderRow.skeleton(), // 실제와 같은 레이아웃 골격
  itemBuilder: (context, index) => OrderRow(item: items[index]),
)

프로토타입은 레이아웃 측정용. 화면에 그 인스턴스가 리스트 아이템으로 반복 삽입되는 그림이 아니다(문맥: extent 계산).
const 가능한 골격이면 좋다. 데이터 의존 높이(여러 줄 말줄임 해제)면 prototype과 실행이 어긋난다 → 그때는 extent 계열을 포기하거나 행 디자인을 고정 높이로.

itemExtent 와 prototypeItem 을 동시에 넣지 않는다. 팀 컨벤션: 숫자 확실하면 extent, 위젯으로 맞춰야 하면 prototype.

4. 가변 높이·다른 최적화와 경계

하고 싶은 것	이 글	다른 글
고정/유사 높이 추정	✅ extent / prototype	—
insert 애니메이션	—	#152 AnimatedList
드래그 재정렬	—	#124 Reorderable
부모 setState 페인트 격리	—	#170 RepaintBoundary
탭 상태 유지	—	#47 KeepAlive

이미지가 늦게 들어와 행 높이가 커지는 피드는 itemExtent 가 독이 될 수 있다. 플레이스홀더 높이를 고정하거나, 가변을 인정하고 extent를 뺀다.

5. AI 안티패턴

안티패턴	대신
모든 builder에 `itemExtent: 50` 매직	디자인 토큰·실제 행 높이 측정
채팅 버블에 itemExtent	가변 높이 — 제거
extent + prototype 동시	하나만
“성능 = 무조건 RepaintBoundary”	layout extent와 paint 경계 분리(#170)
Separated에 extent 대충	separator 높이 포함해 재계산 또는 builder로

FAQ

Q. itemExtentBuilder(가능 버전)는?
A. 인덱스별 다른 고정 높이일 때. 팀 Flutter 버전·API 안정성을 확인하고, 완전 가변 대체재로 오해하지 말 것. 이 글은 공통인 itemExtent / prototypeItem 중심.

Q. GridView도?
A. gridDelegate 가 extent 역할을 상당 부분 한다. 리스트 행 계약과 별개.

Q. cacheExtent 만 키우면?
A. 미리 만들 범위일 뿐 점프의 근본(미지 높이) 을 안 없앤다. 직교 옵션.

체크리스트

행 높이가 고정/유사인지 제품과 합의
고정이면 itemExtent 수치 = 실제 행(패딩 포함)
위젯 샘플이면 prototypeItem 만 (extent와 배타)
가변 콘텐츠면 extent 제거 · 점프 QA
플링·jumpTo·초기 오프셋 수동 확인

자체 검수

기술: itemExtent/prototypeItem 배타 사용·가변 높이 금지 명시. AnimatedList/RepaintBoundary와 축 분리. itemExtentBuilder는 버전 확인 톤.
용어/맞춤법: ListView.builder / itemExtent / prototypeItem 통일. #152·#170 재탕 없음.

Next.js `Link` `scroll={false}` — 필터·탭 URL 교체 후 스크롤 점프 막기

3onK — Tue, 29 Sep 2026 11:39:47 +0900

한 줄 요약: 목록 위에서 필터·정렬·탭만 바꿨는데 스크롤이 맨 위로 튀면 사용자는 “페이지가 리로드된 것”으로 느낀다. App Router <Link> 기본값은 내비게이션 후 스크롤을 상단으로 옮긴다. 같은 목록 UX면 scroll={false} 가 계약이다. searchParams Promise(#34)·Router Cache/prefetch(#114)·useLinkStatus(#86)·router.refresh(#151)·loading.tsx(#38)와 겹치지 않게, 이번엔 Link 스크롤 동작만 판다.

버전 가정: Next.js App Router · next/link 의 scroll boolean(기본 true). useRouter().push(href, { scroll: false }) 동일 감각. hash 앵커·브라우저 기본 스크롤 복원 심화·Pages Router 전용 API는 범위 밖.

교차 링크(재탕 금지):

searchParams await → draft 34
Router Cache · staleTimes · prefetch → draft 114 (캐시 ≠ 스크롤 계약)
useLinkStatus pending → draft 86
router.refresh / revalidate → draft 151
loading.tsx → draft 38
draftMode disable + prefetch 주의 → draft 58 (교차만)

1차 소스: Link (scroll prop)

이 글에서 다루는 것

증상 → 언제 scroll={false}
Link · router.push 최소 패턴
prefetch와 같이 쓸 때
AI 안티패턴 · FAQ · 체크리스트

1. 증상과 원인 — 답부터

흔한 증상

?status=open 만 바꿨는데 긴 테이블 스크롤이 0으로
탭 UI가 URL과 동기화될 때마다 헤더 아래로 튕김
router.push로 쿼리 갱신 후 동일
AI가 필터 칩을 전부 기본 <Link> 로 생성 → QA에서 “리로드 같다” 티켓

원인 한 줄

App Router는 라우트 전환 후 기본적으로 스크롤을 최상단으로 맞춘다. 문서(페이지)가 바뀌는 이동에는 맞고, 같은 목록의 쿼리·탭 교체에는 거슬린다.

전환	scroll
목록 → 상세 · 다른 섹션	기본 `true` (상단)
같은 page에서 `?q`·탭만 변경	`false`
hash로 섹션 점프	제품에 맞게 별도(기본 상단 리셋과 혼동 금지)

2. 최소 패턴

Link

import Link from 'next/link'

export function StatusChip({ status, label }: { status: string; label: string }) {
  return (
    <Link
      href={`/orders?status=${status}`}
      scroll={false}
      // 목록이 자주 바뀌면 draft 114 감각으로 prefetch={false}도 검토
      className="chip"
    >
      {label}
    </Link>
  )
}

router.push

'use client'

import { useRouter } from 'next/navigation'

export function useOrderFilter() {
  const router = useRouter()
  return (status: string) => {
    router.push(`/orders?status=${status}`, { scroll: false })
  }
}

서버 컴포넌트 칩은 <Link scroll={false}> 로 충분.
클라이언트 핸들러(셀렉트·디바운스 검색)는 push/replace 옵션.
replace 로 히스토리를 얇게 가져갈 때도 scroll: false 를 같이 준다.

3. prefetch · soft navigation과 역할 분리

관심사	담당	이 글
스크롤 점프	`scroll={false}`	✅
오래된 RSC 페이로드	staleTimes · refresh(#114·#151)	교차
클릭 pending UI	useLinkStatus(#86)	교차
쿼리 타입·dynamic	searchParams(#34)	교차

필터 칩에 scroll={false} 를 깜빡여도, Router Cache가 옛 목록을 보여 주는 문제는 별개다. 스크롤만 잠그고 데이터는 #114·#151로 간다.

관리 화면 긴 링크 리스트면 draft 114처럼 prefetch={false} 를 스크롤 옵션과 직교로 검토한다.

4. AI 안티패턴

안티패턴	대신
모든 Link에 `scroll={false}`	목록 내 쿼리·탭만
`window.scrollTo` 로 복구	원인인 Link/push 옵션부터
필터를 `window.location` 하드 리로드	soft nav + scroll false
scroll false인데 상세 진입 Link에도 동일	상세는 기본 true
“CSS scroll-behavior만 있으면 됨”	라우터 스크롤 리셋과 별개

FAQ

Q. replace 만 쓰면 스크롤이 안 튀나?
A. 아니다. 히스토리 치환과 스크롤 리셋은 다른 축. replace + scroll: false 조합이 흔하다.

Q. loading.tsx 가 뜨면?
A. 세그먼트가 갈리면 로딩 UI·스크롤 경험이 달라질 수 있다. 같은 page·searchParams만 바꾸는 구조인지도 #38과 함께 본다.

Q. hash #section 은?
A. 제품이 앵커 이동을 원하면 기본 상단 리셋과 싸운다. 이 글 범위는 필터·탭 쿼리. hash는 팀 패턴으로 따로.

Q. Pages Router Router.push(url, as, { scroll })?
A. App Router 옵션 객체 형태와 다르다. 이 글은 App next/link · next/navigation 기준.

체크리스트

필터·정렬·탭 Link에 scroll={false}
클라이언트 push/replace에도 { scroll: false }
목록→상세 Link는 기본 스크롤(true) 유지
관리 목록 prefetch 정책은 #114와 별도 점검
QA: 스크롤 중간에서 칩 클릭 → 위치 유지

자체 검수

기술: Link scroll 기본 true · router.push 두 번째 인자 옵션. prefetch/refresh와 역할 분리. Pages API 혼동 없음.
용어/맞춤법: scroll={false} / soft navigation 통일. #34·#86·#114·#151 재탕 없음.

AI 코딩 — 허용 파일 화이트리스트로 패치 범위를 잠그는 FE 루틴

3onK — Tue, 29 Sep 2026 11:36:17 +0900

한 줄 요약: “이 티켓 고쳐줘”만 던지면 에이전트가 인접 유틸·배럴·테스트 스냅샷까지 손을 댄다. FE 데스크에서는 허용 경로 화이트리스트 + 금지 글롭 + 새 파일 정책을 프롬프트 맨 위에 고정한다. 테스트 fix 루프(#31)·Plan 스코프(#81)·스펙 프롬프트(#150)·eval 글롭(#162)·모노레포 Rules(#166)와 겹치지 않게, 이번엔 매 패치 세션의 파일 자물쇠만 판다.

버전 가정: Cursor Agent/Composer · Claude Code 등 멀티파일 패치 도구 일반. 제품 UI 단축키는 바뀔 수 있으니 프롬프트 계약이 진실. git worktree·모노레포 apps/* 가정. CI 게이트 전체 설계 아님.

교차 링크(재탕 금지):

테스트 깨짐 fix 루프 → draft 31 (실패 1건 루프 ≠ 파일 자물쇠)
Plan mode 스코프 → draft 81
스펙 드리븐 프롬프트 → draft 150
eval allowed/forbidden globs → draft 162 (프롬프트 회귀 측정 ≠ 티켓 패치)
모노레포 Rules 레이어링 → draft 166
Composer PR 루틴 → draft 7
cursorignore 예산 → draft 101

이 글에서 다루는 것

증상 → 화이트리스트 계약
붙여넣기 템플릿 · 새 파일 정책
검증(git status) · AI 안티패턴 · FAQ · 체크리스트

1. 증상과 원인 — 답부터

흔한 증상

버튼 카피 수정인데 packages/ui 배럴·토큰 파일까지 diff
“타입만 맞춰줘”에 포매터·import 정렬·무관 리네임 동반
모노레포에서 apps/web 티켓인데 apps/api 스키마 제안(#166 감각)
리뷰어가 “왜 이 파일이?”를 반복

한 줄 원인

모델은 관련성 휴리스틱으로 이웃 파일을 연다. 범위는 채팅 톤이 아니라 경로 계약으로만 잠긴다.

계약	역할
Allow	이번 세션에 편집 가능한 경로(파일 또는 글롭)
Deny	열람만 / 편집 금지(스냅샷·생성 코드·타 앱)
New files	`forbidden` / `ask-first` / `only-under: path/`

슬랙 한 줄:

허용 목록 밖 diff는 머지 대상이 아니다. 되돌려라.

2. 붙여넣기 템플릿

## 패치 자물쇠 (필수)
- Allow (edit):
  - apps/web/app/(dashboard)/orders/page.tsx
  - apps/web/components/orders/OrderFilter.tsx
- Deny (no edit):
  - **/*.snap
  - **/generated/**
  - apps/api/**
  - packages/ui/src/index.ts
- New files: forbidden
- 목표: 주문 필터 쿼리키 `status` 반영. 리팩터·포맷만의 변경 금지.
- 끝낼 때: `git status` / `git diff --stat`가 Allow 안인지 보고.

짧게 쓸 때:

EDIT ONLY: src/components/SearchBox.tsx, src/lib/queryKeys.ts
NO NEW FILES. NO SNAPSHOTS. 최소 diff.

파일 단위가 글롭보다 안전하다. 급하면 apps/web/components/orders/** 정도.
Deny에 스냅샷·codegen·타 앱을 기본으로 넣는다.
#150 스펙이 있으면 자물쇠 블록을 스펙 다음·코드 요청 전에 둔다.

3. 새 파일 정책 세 가지

정책	언제
`forbidden`	카피·버그·한 컴포넌트 props — 기본값
`ask-first`	훅 추출이 필요할 수 있지만 확정 전
`only-under: …/__tests__/`	테스트 추가가 티켓에 명시된 경우

“나중에 정리하자”로 유틸 신설을 허용하면 화이트리스트가 빈 말록이 된다. 추출이 필요하면 사람이 경로를 Allow에 추가한 뒤 재요청.

4. 검증 — 패치 후 30초

사람이 돌린다(에이전트 말만 믿지 않음):

git status -sb
git diff --stat
git diff --name-only

Allow 밖 경로가 있으면 revert 또는 세션 롤백 후 자물쇠를 강화해 재실행.
“포맷터만”도 범위 위반이면 되돌린다 — #31의 “초록이 목표”와 같이 최소 diff가 계약.
모노레포면 git diff --name-only에 apps/api가 보이는 순간 중단(#166).

5. AI 안티패턴

안티패턴	대신
“관련 파일 알아서”	Allow 목록 명시
Deny 없이 “스냅샷 맞추지 마”만 문장	`*/.snap` Deny
자물쇠를 채팅 맨 아래	맨 위 고정
Plan(#81)만 길고 패치 세션에 자물쇠 없음	Plan 승인 후 패치마다 재부착
eval 글롭(#162)을 티켓 프롬프트에 복붙	측정용 ≠ 세션용. 티켓은 파일 목록이 더 낫다
새 파일 5개 + “구조 개선”	New files: forbidden

FAQ

Q. #31이랑 뭐가 다르나?
A. #31은 실패 테스트 1건 루프. 이 글은 어떤 티켓이든 편집 경로 자물쇠. 같이 쓴다.

Q. #81 Plan이면 충분하지 않나?
A. Plan은 범위 합의. 실행 세션에서 모델이 다시 넓어진다. 패치 프롬프트마다 Allow를 붙인다.

Q. Rules(#15·#166)에 “최소 diff”를 넣으면?
A. 전역 톤에는 도움. 티켓별 경로는 세션 자물쇠가 이긴다.

Q. 읽기(참조)는?
A. 읽기는 넓혀도 된다. 문제는 쓰기. “Read OK / Edit only Allow”로 구분해도 좋다.

체크리스트

프롬프트 상단에 Allow / Deny / New files가 있는가
스냅샷·codegen·타 앱이 Deny에 있는가
패치 후 git diff --name-only가 Allow 안인가
범위 밖이면 revert 후 자물쇠 강화 재실행인가
#150 스펙과 자물쇠를 한 덩어리로 붙였는가

자체 검수

기술: 화이트리스트는 프롬프트 계약이지 IDE 강제 샌드박스가 아님을 전제. git으로 사람 검증. #31·#81·#162와 역할 분리.
용어/맞춤법: Allow/Deny/화이트리스트 통일. 모노레포 예시는 apps/web·apps/api.

Flutter RepaintBoundary — 깜빡이는 조상 setState에 전체가 다시 그려지지 않게

3onK — Tue, 29 Sep 2026 11:33:08 +0900

한 줄 요약: 타이머·오디오 미터·커서 깜빡임처럼 자주 변하는 위젯이 큰 트리 위에 있으면, 조상 setState·부모 paint가 카드 리스트 전체를 다시 그린다. RepaintBoundary 로 리페인트 경계를 끊어 레이어를 분리하는 것이 계약이다. AnimatedSwitcher(#156)·PageRouteBuilder(#160)·resume refresh(#165)·ValueListenableBuilder(#84)·AnimationController dispose(#76)와 겹치지 않게, 이번엔 페인트 경계·레이어만 판다.

버전 가정: Flutter 3.x · RepaintBoundary · DevTools Performance / debugProfilePaintsEnabled 감각. 무분별한 Boundary는 레이어·메모리 비용이 있다 — 핫스팟에만. Skia/Impeller 차이 심화·엔진 내부 튜토리얼 아님.

교차 링크(재탕 금지):

AnimatedSwitcher → draft 156
PageRouteBuilder → draft 160
resume data refresh → draft 165
ValueListenableBuilder → draft 84
AnimationController dispose → draft 76
AutomaticKeepAlive → draft 47 (스크롤 keepAlive ≠ 페인트 경계)

1차 소스: RepaintBoundary

이 글에서 다루는 것

증상 → 언제 Boundary인가
최소 패턴 · 자식/부모 위치
과용 비용
AI 안티패턴 · FAQ · 체크리스트

1. 증상과 원인 — 답부터

흔한 증상

한 줄 스피너만 도는데 리스트 스크롤이 같이 버벅
PerformanceOverlay에 넓은 영역이 매 프레임 반짝
“상태만 국소인데 왜 전체가?”

원인 한 줄

Flutter는 더티한 render object의 페인트가 조상/형제로 번질 수 있다. RepaintBoundary 는 자손을 별 레이어로 합성해, 안쪽 리페인트가 바깥을 덜 건드리게 한다.

상황	처방
1Hz 미만 UI 갱신	Boundary 없어도 됨
애니메이션·미터·타이머가 큰 리스트 옆	그 위젯을 Boundary로 감싸기
상태 소유가 조상에 있음	상태를 내리거나 Listenable로 국소화(#84) 후 Boundary

2. 최소 패턴

class HeaderWithClock extends StatelessWidget {
  const HeaderWithClock({super.key, required this.child});
  final Widget child;

  @override
  Widget build(BuildContext context) {
    return Row(
      children: [
        Expanded(child: child),
        const RepaintBoundary(child: _BlinkClock()),
      ],
    );
  }
}

자주 그리는 잎을 Boundary 안에.
리스트 아이템 전체를 무조건 Boundary로 감싸지 말 것 — 프로파일 후 핫스팟만.
RepaintBoundary.wrap / 자동 경계가 생기는 스크롤 슬롯과 역할을 헷갈리지 말 것(스크롤 최적화 ≠ 이 글의 의도적 경계).

3. 상태 국소화가 먼저

Boundary는 밴드에이드가 되기 쉽다. 우선순위:

애니메이션 상태를 잎 위젯으로 이동
AnimatedBuilder / ValueListenableBuilder로 빌드 범위 축소(#84)
그래도 이웃 페인트가 보이면 RepaintBoundary

4. 과용 비용

레이어 수 ↑ → 메모리·합성 비용
“전부 Boundary”는 AI가 좋아하는 거짓 최적화
DevTools에서 전/후 프레임·레이어 수를 보고 남길지 결정

AI 안티패턴

안티패턴	대신
루트 Scaffold를 Boundary	핫스팟 잎만
setState 조상 유지 + Boundary만 추가	상태 국소화 먼저
KeepAlive와 혼동	47은 스크롤 dispose 방지
Hero/전환 이슈를 Boundary로 해결	160·50 계약 확인

FAQ

Q. Opacity·클립과 같이 쓰나?
A. 일부 위젯은 자체로 레이어를 만든다. 중복 Boundary는 프로파일로 판단.

Q. 웹(Flutter web)에서도?
A. 개념은 같으나 합성 경로가 다름 — 모바일 프로파일 기준으로 먼저 검증.

Q. resume refresh(#165)와?
A. 데이터 무효화 이슈와 페인트 이슈는 별층.

체크리스트

PerformanceOverlay / DevTools로 핫스팟 확인
상태 국소화 가능 여부 먼저 검토
잎에만 RepaintBoundary
레이어 수·메모리 회귀 확인
불필요 Boundary 제거 PR 기준 문서화

자체 검수

기술: RepaintBoundary 역할·과용 비용만. 엔진 내부 단정·만능 최적화 주장 없음.
용어/맞춤법: RepaintBoundary / layer / jank 통일. #156·#84·#47과 분리.

CSS `field-sizing: content` — textarea 높이 JS 측정 그만하기

3onK — Tue, 29 Sep 2026 11:29:49 +0900

한 줄 요약: 댓글·프롬프트 박스마다 scrollHeight를 읽어 style.height를 때리는 autosize 훅은 접근성·IME·SSR에서 새는 지점이 많다. 모던 엔진의 field-sizing: content 로 필드가 콘텐츠만큼 커지게 두는 것이 계약이다. text-wrap(#155)·color-mix(#163)·scroll-snap(#159)·:has(#148)·Anchor(#139)와 겹치지 않게, 이번엔 폼 컨트롤 자동 크기만 판다.

버전 가정: CSS UI field-sizing (content | fixed). Chromium 계열 중심으로 실무 도입 — 지원 표는 배포 주 mid-2026+ 기준으로 팀 caniuse/MDN을 재확인. 미지원 브라우저는 fixed(기본 감각)로 두고 JS 폴백은 점진적 향상. 디자인 시스템 전체 마이그레이션 가이드 아님.

교차 링크(재탕 금지):

text-wrap balance/pretty → draft 155
color-mix · relative color → draft 163
scroll-snap → draft 159
:has → draft 148
Anchor positioning → draft 139

1차 감각 소스: MDN field-sizing · CSS UI 스펙. 버전·지원율 숫자는 글에서 고정하지 않고 팀 확인 칸으로 둔다.

이 글에서 다루는 것

답 먼저 — JS autosize vs field-sizing
최소 CSS · max-height와 조합
폴백 전략
AI 안티패턴 · FAQ · 체크리스트

1. 증상과 원인 — 답부터

흔한 증상

한글 IME 조합 중 높이가 깜빡이거나 한 줄 늦게 따라옴
SSR 마크업과 클라이언트 측정이 어긋나 CLS
onInput마다 layout thrash → INP 악화(#97 감각)

원인 한 줄

높이를 스크립트 관측으로 맞추면 입력 파이프라인과 레이아웃이 경쟁한다. field-sizing: content 는 엔진이 콘텐츠 기반으로 컨트롤 크기를 잡게 한다.

접근	언제
`field-sizing: content`	지원 브라우저 · 댓글/프롬프트/짧은 메모
`field-sizing: fixed` + rows	고정 줄 수가 제품 계약일 때
JS autosize	미지원 폴백만 · `@supports` 밖

2. 최소 CSS

.prompt {
  field-sizing: content;
  min-height: 2.75rem;
  max-height: 12rem; /* 무한 성장 방지 — 스크롤로 넘김 */
  width: 100%;
  resize: none; /* content 모드에서 수동 리사이즈와 역할 정리 */
}

<textarea class="prompt" name="prompt" rows="1" placeholder="메시지를 입력"></textarea>

min-height / max-height: 빈 상태·장문 폭주 가드.
rows: 폴백·접근성 힌트로 남겨도 됨(지원 엔진에서는 content가 우선하는 그림 — 팀으로 한번 확인).
input에도 동일 속성이 열리는 엔진이 있다. 가로 성장이 레이아웃을 깨면 width/max-width를 먼저 고정.

3. 점진적 향상

.prompt {
  /* 기본: 고정 감각 */
  field-sizing: fixed;
}

@supports (field-sizing: content) {
  .prompt {
    field-sizing: content;
  }
}

JS autosize는 @supports 실패 구간에서만 로드. 지원 브라우저에 JS를 이중 적용하지 말 것 — 높이 전쟁이 난다.

4. AI 안티패턴

안티패턴	대신
모든 textarea에 `useAutosizeTextArea` 강제	`field-sizing` 먼저
`scrollHeight + 2px` 매직	max-height + 스크롤
resize: both + content 동시	제품이 수동 리사이즈를 원할 때만 예외
지원율 숫자를 글에 박제	배포 주 재확인 칸

FAQ

Q. contenteditable div에도 되나?
A. 이 글 범위는 form-associated 컨트롤 중심. contenteditable은 별 계약.

Q. React controlled value와 충돌?
A. value는 그대로. 높이 측정을 제거하는 것이 목표. controlled 패턴 자체는 유지.

Q. 디자인 토큰 색(#163)이랑?
A. 직교. 크기는 field-sizing, 색은 color-mix.

체크리스트

대상 textarea/input에 field-sizing: content + min/max-height
@supports 폴백 분기
기존 autosize 훅 이중 적용 제거
IME·장문·빈 값 수동 QA
팀 caniuse/MDN 지원 표 날짜 기록

자체 검수

기술: field-sizing 값·점진적 향상만. 미지원율 숫자 발명 없음. JS autosize 완전 금지 단정 없음(폴백 허용).
용어/맞춤법: field-sizing / content / fixed 통일. #155·#163과 분리.

Next.js `viewport` · `generateViewport` — themeColor를 metadata에 묶지 않기

3onK — Tue, 29 Sep 2026 11:25:29 +0900

한 줄 요약: metadata 안에 themeColor·viewport를 계속 넣으면 분리된 viewport 계약을 놓치고, AI가 구버전 예시를 복붙한다. App Router는 export const viewport / generateViewport 가 theme-color·초기 스케일을 담당한다. generateMetadata(#56)·sitemap.ts/robots.ts(#164)·template vs layout(#157)·searchParams Promise(#34)·loading.tsx(#38)와 겹치지 않게, 이번엔 viewport 수출만 판다.

버전 가정: Next.js App Router · Server Components에서만 viewport / generateViewport. 같은 세그먼트에 둘 다 export 금지. metadata-to-viewport-export codemod 언급. 코드는 최소 골격. PWA 매니페스트 전체·브라우저별 theme-color 버그는 범위 밖.

교차 링크(재탕 금지):

generateMetadata / OG → draft 56
sitemap · robots → draft 164
template vs layout → draft 157
searchParams await → draft 34
loading.tsx → draft 38
error / not-found → draft 21

1차 소스: generateViewport

이 글에서 다루는 것

증상 → 원인 표
static viewport vs generateViewport
metadata에서 옮기는 법 · codemod
런타임 의존 시 주의
AI 안티패턴 · FAQ · 체크리스트

1. 증상과 원인 — 답부터

흔한 증상

다크 모드인데 모바일 브라우저 크롬(주소창) 색이 안 바뀜
metadata.themeColor를 고쳤는데 빌드 경고·타입 불만
AI가 export const metadata = { viewport: { ... }, themeColor } 구형을 계속 생성

원인 한 줄

viewport 관련 필드는 metadata가 아니라 viewport / generateViewport 계약이다.

잘못된 습관	계약
`metadata.themeColor`에만 의존	`viewport.themeColor` (또는 generateViewport 반환)
같은 파일에 `viewport` + `generateViewport`	둘 중 하나
정적 색인데 `generateViewport`에서 `cookies()`	불필요 동적 → 프리렌더/내비 비용

2. static `viewport` — 기본값

import type { Viewport } from 'next'

export const viewport: Viewport = {
  themeColor: [
    { media: '(prefers-color-scheme: light)', color: '#ffffff' },
    { media: '(prefers-color-scheme: dark)', color: '#0a0a0a' },
  ],
  width: 'device-width',
  initialScale: 1,
}

런타임 값이 필요 없으면 이 형태가 기본. 문서도 “runtime에 안 기대면 static”을 권한다.

3. `generateViewport` — 세그먼트에 따라 달라질 때

import type { Viewport } from 'next'

type Props = {
  params: Promise<{ brand: string }>
}

export async function generateViewport({ params }: Props): Promise<Viewport> {
  const { brand } = await params
  return {
    themeColor: brand === 'night' ? '#0a0a0a' : '#ffffff',
  }
}

Server Component 세그먼트에서만.
params / searchParams는 프레임워크 버전에 맞게 Promise await(#34와 동일 감각).
요청 쿠키·헤더에 실제로 묶여야 할 때만 동적으로. 아니면 static으로 되돌린다.

Cache Components·프리렌더 경로에서는 generateViewport가 런타임 API를 읽으면 초기 로드 viewport를 미룰 수 없어 내비/프리렌더가 막힐 수 있다. 공식 메시지 blocking-prerender-viewport-runtime 계열을 팀 위키에 링크해 둔다. 해결 우선순위: (1) static으로 재작성 (2) 런타임 의존 제거 (3) 문서가 안내하는 세그먼트 opt-out — 루트에 함부로 켜지 말 것.

4. metadata에서 옮기기

구형:

export const metadata = {
  title: 'My App',
  themeColor: 'dark',
  viewport: { width: 'device-width' },
}

신형:

export const metadata = { title: 'My App' }

export const viewport = {
  width: 'device-width',
  themeColor: 'dark',
}

일괄: npx @next/codemod@latest metadata-to-viewport-export .

5. AI 안티패턴

안티패턴	대신
본문 `<meta name="viewport">` 수동 삽입	`viewport` export
themeColor만 metadata에 남김	viewport로 이동
모든 페이지 generateViewport + cookies	정말 테마가 유저별로 다를 때만
layout과 page 둘 다 충돌 export	세그먼트 소유권 하나로

FAQ

Q. generateMetadata와 같이 쓰나?
A. 예. 역할이 다름 — 문서/OG는 metadata, 뷰포트/theme-color는 viewport.

Q. 클라이언트 컴포넌트에서 export?
A. 문서: Server Components만. 'use client' 파일에 두지 말 것.

Q. sitemap(#164)이랑 헷갈린다?
A. 메타데이터 파일 라우트 vs 세그먼트 export. 층이 다르다.

체크리스트

metadata에 남은 themeColor / viewport 키 검색·이전
세그먼트당 viewport XOR generateViewport
정적 색은 static export
다크/라이트 media 쿼리 themeColor 필요한지 제품과 합의
codemod 후 타입 Viewport import
런타임 의존 시 프리렌더 경고 문서 링크

자체 검수

기술: Next 공식 generateViewport 문서·codemod·blocking-prerender 메시지 각도만. 없는 API 발명 없음.
용어/맞춤법: viewport / generateViewport / themeColor 통일. #56·#164와 분리.

Claude Sonnet 5.5 on AI Gateway(2026-09-28) — FE 일상 코딩·문서 루프 데스크 노트

3onK — Tue, 29 Sep 2026 11:20:35 +0900

한 줄 요약: 2026-09-29 기준, late-Sep FE·에이전트 데스크가 열어볼 공식 공지는 Vercel Changelog Claude Sonnet 5.5 now available on AI Gateway(Published September 28, 2026 · Rohan Taneja, Zachary Chen, Jerilyn Zheng)다. 요지(원문 고정): (1) 모델 id anthropic/claude-sonnet-5.5 (2) Sonnet 5 대비 잘 범위가 잡힌 일상 작업(피처·버그픽스·문서/슬라이드/스프레드시트) 개선 (3) 코딩에서 여러 스텝을 이어가고 완료 전 자체 점검 경향 (4) 문서·차트·데스크톱 앱 사용·기술 도면 읽기 개선 언급 (5) AI Gateway에서 Zero Data Retention 지원 (6) AI SDK · Chat Completions · Responses · Anthropic Messages · coding agents + npx vercel ai-gateway setup / /model. Opus 5.5 Gateway(#130)·Pixel Canary 스텔스(#158)·GPT-6 Sol/Luna(#134)·Managed Agents(#122)와 제품 면이 다름 — 이번엔 Sonnet 5.5 Gateway 롤아웃 FE 함의만. 원문에 없는 단가표·벤치 승패·자동 기본모델 교체 단정은 적지 않는다.

교차 링크(재탕 금지):

Claude Opus 5.5 Gateway → draft 130 (상위 에이전트 모델 ≠ 일상 Sonnet 슬롯)
Pixel Canary stealth → draft 158
GPT-6 Sol/Luna API → draft 134
Managed Agents auto → draft 122
Claude Code Projects → draft 96
one Claude Docs/Slides → draft 87
AI SDK harness → draft 75

1차 확인(2026-09-29): Vercel Changelog 2026-09-28만. 배포 전 URL 재확인.

이 글에서 다루는 것

공지가 말한 것 / 안 말한 것
왜 FE 데스크 뉴스인가 (Opus 슬롯과 분리)
지금 / 스테이징 / 안 함
FAQ · 체크리스트

1. 답 먼저 — 왜 FE 뉴스인가

Opus 5.5(#130)가 “긴 에이전트·깨지는 요청 계약” 뉴스였다면, Sonnet 5.5는 매일 돌리는 PR·리뷰·문서 루프의 기본 슬롯 후보다. 원문이 강조하는 면도 그쪽이다 — well-scoped everyday work, multi-step coding with self-check, polished docs/slides.

역할	Changelog 요지
모델 ID	`anthropic/claude-sonnet-5.5`
강점(원문)	피처·버그픽스 · 문서/슬라이드/시트 · multi-step coding + self-check · 차트·기술도면·데스크톱 앱
컴플라이언스	ZDR 지원(Gateway)
연결면	AI SDK · Chat Completions · Responses · Anthropic Messages · Claude Code/fx + `vercel ai-gateway setup`

슬랙 한 줄:

Sonnet 5.5 Gateway 올림. 일상 코딩 슬롯 후보. ZDR 켜는지 팀 표 확인. Opus 5.5 breaking(thinking/forced tool)과 혼동 금지.

2. Changelog가 말한 것 / 안 말한 것

말한 것

AI Gateway에 Sonnet 5.5 가용, id anthropic/claude-sonnet-5.5
Sonnet 5 대비 일상 작업·문서 산출물·코딩 multi-step/self-check 개선 서술
ZDR on AI Gateway
streamText({ model: 'anthropic/claude-sonnet-5.5', ... }) 예시
Claude Code·fx: setup 후 /model로 선택
Chat Completions / Anthropic Messages 예시 코드
Gateway 단일 API·usage/cost·routing/retries/failover · Gateway key 또는 BYOK

안 말한 것 (추측 금지)

토큰 단가 표·우리 계정 쿼터 배수
“Opus를 대체한다 / Cursor 기본값을 바꾼다”
Opus 5.5의 adaptive thinking·forced tool 폐기 계약이 Sonnet에도 동일하다는 단정(이 항목 원문에 없음 — Opus 글 #130과 분리)
벤치 리더보드 숫자

3. FE 데스크 관점 — 슬롯을 나누는 법

슬롯	후보(기존 글)	이번 공지
긴 에이전트·고난도	Opus 5.5 Gateway (#130)	비대상
일상 PR·리뷰·짧은 피처	(팀 표)	Sonnet 5.5 후보
스텔스/실험 모델	Pixel Canary (#158)	비대상
저비용 대량	Luna 등 (#134)	비대상

실무 규칙 초안:

기본 일상 슬롯에 Sonnet 5.5를 올릴지 A/B(스테이징 에이전트 1대).
ZDR 필요 레포는 Gateway ZDR 옵션·키 정책을 표로 고정 후 모델 변경.
Opus 하니스의 thinking/tool_choice 가드는 Opus 경로에만 유지(#130). Sonnet 경로에 복사·삭제하기 전 원문·SDK 릴리즈 노트 재확인.
npx vercel ai-gateway setup 후 /model 피커에 id가 보이는지 확인.

4. 원문 코드 골격 (그대로 읽기)

import { streamText } from 'ai';

const result = streamText({
  model: 'anthropic/claude-sonnet-5.5',
  prompt: 'Fix the failing test and verify the change.',
});

에이전트:

npx vercel ai-gateway setup
# Claude Code / fx 에서 /model → Claude Sonnet 5.5

5. 지금 / 스테이징 / 안 함

상태	조건
지금	Gateway 카탈로그에 id 노출 확인 · 문서/슬라이드 보조 봇에 한정 적용
스테이징	일상 PR 에이전트 1대에 올려 flake·과잉편집 관찰 1주
안 함	Opus 경로와 설정을 뭉뚱그려 교체 · ZDR 미확인 프로덕션 키에 즉시 전면 적용

FAQ

Q. Opus 5.5 글을 다시 읽어야 하나?
A. 긴 에이전트·HTTP 400 계약이면 #130. 일상 슬롯이면 이 글.

Q. ZDR이 기본인가?
A. 원문은 “supports Zero Data Retention” — opt-in/설정 방식은 팀 Gateway 문서·콘솔을 진실로. 이 글에서 기본 on을 단정하지 않음.

Q. Cursor 기본 모델이 바뀌나?
A. 원문에 없음. Gateway/에이전트 /model 선택 이슈로 취급.

체크리스트

Changelog URL·날짜(2026-09-28)·모델 id 재확인
일상 슬롯 vs Opus 슬롯 분리표 업데이트
ZDR 필요 레포 키·옵션 확인
vercel ai-gateway setup + /model 피커 확인
스테이징 에이전트 1대 A/B 후 전면

자체 검수

사실/날짜/출처: Vercel Changelog 2026-09-28만 인용. 단가·벤치·Opus breaking 동일 적용 단정 없음.
용어/맞춤법: Sonnet 5.5 / anthropic/claude-sonnet-5.5 / ZDR / Gateway 표기 통일. #130·#158·#134과 각도 분리.

개발세발

Flutter `Scrollable.ensureVisible` — 포커스·에러 필드를 키보드 뒤에 두지 않기

이 글에서 다루는 것

1. 증상과 원인 — 답부터

흔한 증상

원인 한 줄

2. 최소 패턴 — 포커스 다음

3. 검증 실패 첫 에러

4. alignment · alignmentPolicy 감각

5. AI 안티패턴

FAQ

체크리스트

자체 검수

Ember-1(Fireworks) on AI Gateway(2026-09-27) — 짧은 reasoning 트레이스 FE 데스크 노트

이 글에서 다루는 것

1. 답 먼저 — 왜 FE 뉴스인가

2. Changelog가 말한 것 / 안 말한 것

말한 것

안 말한 것 (추측 금지)

3. FE 데스크 관점 — 슬롯을 나누는 법

4. 원문 코드 골격 (그대로 읽기)

5. 지금 / 스테이징 / 안 함

FAQ

체크리스트

자체 검수

CSS `light-dark()` — 라이트/다크 색을 미디어쿼리 복붙으로 끝내지 않기

이 글에서 다루는 것

1. 증상과 원인 — 답부터

흔한 증상

원인 한 줄

2. 최소 CSS

3. 파생(#163)과 같이 쓸 때

4. 점진적 향상

5. AI 안티패턴

FAQ

체크리스트

자체 검수

Flutter `ListView.builder` — `itemExtent` · `prototypeItem` 으로 스크롤 점프 줄이기

이 글에서 다루는 것

1. 증상과 원인 — 답부터

흔한 증상

원인 한 줄

2. itemExtent — 숫자가 있을 때

3. prototypeItem — 샘플 한 칸

4. 가변 높이·다른 최적화와 경계

5. AI 안티패턴

FAQ

체크리스트

자체 검수

Next.js `Link` `scroll={false}` — 필터·탭 URL 교체 후 스크롤 점프 막기

이 글에서 다루는 것

1. 증상과 원인 — 답부터

흔한 증상

원인 한 줄

2. 최소 패턴

Link

router.push

3. prefetch · soft navigation과 역할 분리

4. AI 안티패턴

FAQ

체크리스트

자체 검수

AI 코딩 — 허용 파일 화이트리스트로 패치 범위를 잠그는 FE 루틴

이 글에서 다루는 것

1. 증상과 원인 — 답부터

흔한 증상

한 줄 원인

2. 붙여넣기 템플릿

3. 새 파일 정책 세 가지

4. 검증 — 패치 후 30초

5. AI 안티패턴

FAQ

체크리스트

자체 검수

Flutter RepaintBoundary — 깜빡이는 조상 setState에 전체가 다시 그려지지 않게

이 글에서 다루는 것

1. 증상과 원인 — 답부터

흔한 증상

원인 한 줄

2. 최소 패턴

2. `itemExtent` — 숫자가 있을 때

3. `prototypeItem` — 샘플 한 칸

2. static `viewport` — 기본값

3. `generateViewport` — 세그먼트에 따라 달라질 때