@m1kapp/kit 0.0.33 → 0.0.37

package/README.md

@@ -22,6 +22,7 @@ import { Watermark, AppShell, AppShellHeader, AppShellContent, Section, TabBar,
 export default function App() {
   return (
     // Watermark가 뷰포트 전체 높이/중앙정렬/하단 크레딧을 같이 줍니다.
+    // (크레딧 스트립은 셸 바로 밑에 붙어서 셸과 한 덩어리로 중앙정렬됨 — 화면 진짜 바닥에 고정되는 게 아님)
     // AppShell만 단독으로 쓰면 콘텐츠 높이만큼 쪼그라들어요.
     <Watermark color="#e2603f" text="myapp">
       <AppShell>

package/bin/skills/m1kapp-clean.md

@@ -5,9 +5,24 @@
 - 최악 함수 cognitive 20 초과분 ×1 (최대 -15)
 - **중복 밀도 3% 초과분 ×2.5 (최대 -25)** — 토큰 단위 복붙 검출 (식별자 정규화, 테스트 제외)
 - 200줄 초과 파일 비율 ×2 (최대 -10) / 평균 파일 길이 80줄 초과분 ÷5 (최대 -10)
+- **루프 안 무캐시 파일읽기 ×4 (최대 -20)** — 호출 1번이 파일을 N번 읽는 구조 (`quality.io`)
+- **렌더 인질 ×3 (최대 -10)** — fetch 하나가 무관한 UI까지 막는 자리 (`quality.renderGates`)
 
 cognitive = 중첩 깊이 가중 복잡도 (SonarQube 방식): `a && b && c`는 1, 5중 중첩 if는 flat if 5개보다 훨씬 비쌈. `??`는 미카운트. 즉 **평평하게 펴는 것(조기 반환)이 진짜 점수가 됨** — 함수 쪼개기만으론 안 오름.
 
+`io` 축은 나머지와 성격이 다르다. cognitive·중복은 "코드가 얼마나 꼬였나"라 5줄짜리
+흠 없는 리더가 루프에서 120번 불리는 종류는 **원리상 못 잡는다** — 실제로 요청당 파일을
+492번 읽던 코드가 A+ 100점을 통과한 적이 있다. 그래서 파일을 읽는 함수(한 다리 건너
+읽는 얇은 래퍼 포함)를 찾아 루프·`map` 안에서 불리는 자리를 센다. 그 리더가 캐시를
+끼고 있으면(모듈 Map을 get/set) 반복 호출돼도 실제 읽기는 한 번이라 감점하지 않는다.
+**고치는 법은 리팩토링이 아니라 캐시를 끼우거나 한 번 읽어 재사용하도록 구조를 바꾸는 것** —
+`quality.io.worst`가 위치를 지목한다.
+
+`renderGates`도 같은 성격이다. `{data && <Nav a={local} b={data.x} onChange={fn} />}`처럼
+프롭 3개 중 1개만 그 데이터에 의존하는데 전체가 대기하면, 사용자에겐 이미 아는 UI까지
+매번 로딩으로 보인다. 데이터에 의존하는 부분만 늦게 채우고 나머지는 먼저 그리는 게 답이다
+(서버가 아는 값이면 아예 서버에서 내려주면 된다).
+
 즉 **효율 순서: ① 중복 블록 제거 (kit-stats.json `quality.duplication.worstBlocks`가 위치 지목) ② 최악 함수 중첩 평탄화 ③ cog15+ 함수들 ④ 긴 파일 분할**.
 
 `--llm` 플래그(선택): cognitive 최악 3개를 Claude(haiku)가 네이밍·응집도·본질적 복잡성 여부 자문 — 점수 미반영, `quality.llm`에 기록. "essential: true"로 나온 함수는 억지로 쪼개지 말 것.

package/bin/stats.mjs

@@ -340,6 +340,306 @@ function analyzeDuplication(ts, fileContents) {
   return { percent, dupTokens, totalTokens, blocks: blockKeys.size, worstFiles, worstBlocks };
 }
 
+// 파일 I/O 밀도 — "한 번 처리하는 데 파일을 몇 번이나 읽게 되는 구조인가".
+// cognitive·중복은 코드 모양만 보므로, 5줄짜리 흠 없는 리더가 루프에서 120번 불리는
+// 종류는 원리상 못 잡는다(그래서 요청당 492회 읽던 코드가 A+ 100점을 통과했다).
+// 여기선 리더 함수를 찾고, 그게 루프 안에서 불리는 자리를 센다. 리더가 캐시를 끼고
+// 있으면 반복 호출돼도 실제 읽기는 한 번이라 감점하지 않고 참고로만 남긴다.
+const FILE_READ_CALLS = new Set(["readFileSync", "readFile", "readdirSync"]);
+const ITERATING_METHODS = new Set(["map", "forEach", "flatMap", "filter", "reduce", "some", "every", "find"]);
+
+function analyzeIoDensity(ts, fileContents) {
+  const parsed = fileContents.map(({ file, content }) => ({
+    file,
+    sf: ts.createSourceFile(
+      file,
+      content,
+      ts.ScriptTarget.Latest,
+      true,
+      /\.(tsx|jsx)$/.test(file) ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+    ),
+  }));
+
+  const isFnLike = (n) =>
+    ts.isFunctionDeclaration(n) || ts.isFunctionExpression(n) || ts.isArrowFunction(n) ||
+    ts.isMethodDeclaration(n);
+
+  const nameOf = (sf, n) => {
+    if (n.name) return n.name.getText(sf);
+    const p = n.parent;
+    if (p && ts.isVariableDeclaration(p)) return p.name.getText(sf);
+    return null;
+  };
+
+  const lineOf = (sf, n) => sf.getLineAndCharacterOfPosition(n.getStart(sf)).line + 1;
+
+  // 1단계: 함수마다 "직접 파일을 읽는가 / 자기 캐시를 쓰는가 / 누구를 부르는가"를 모은다
+  const fns = new Map(); // 이름 -> { file, line, readsDirectly, hasOwnCache, calls:Set }
+  for (const { file, sf } of parsed) {
+    const moduleHasMap = /new (Map|WeakMap)\s*[<(]/.test(sf.text);
+    // 모듈 스코프 변수 이름 — "읽고 또 대입하는" 변수를 쓰면 그게 메모이제이션이다
+    // (globalThis에 물린 캐시나 `let memo = null` 패턴. Map만 캐시로 보면 이런 걸 다 놓친다)
+    const moduleVars = new Set();
+    for (const stmt of sf.statements) {
+      if (ts.isVariableStatement(stmt)) {
+        for (const decl of stmt.declarationList.declarations) {
+          if (ts.isIdentifier(decl.name)) moduleVars.add(decl.name.getText(sf));
+        }
+      }
+    }
+
+    const collect = (node) => {
+      if (isFnLike(node) && node.body) {
+        let readsDirectly = false;
+        let mapCacheOps = 0;
+        const calls = new Set();
+        const readVars = new Set();
+        const writtenVars = new Set();
+        const rootName = (expr) => {
+          let cur = expr;
+          while (ts.isPropertyAccessExpression(cur) || ts.isElementAccessExpression(cur)) cur = cur.expression;
+          return ts.isIdentifier(cur) ? cur.getText(sf) : null;
+        };
+        const scan = (n) => {
+          if (n !== node && isFnLike(n)) return; // 중첩 함수는 자기 항목에서 본다
+          if (ts.isCallExpression(n)) {
+            const callee = n.expression;
+            const called = ts.isPropertyAccessExpression(callee) ? callee.name.getText(sf) : callee.getText(sf);
+            if (FILE_READ_CALLS.has(called)) readsDirectly = true;
+            if (called === "get" || called === "set") mapCacheOps++;
+            calls.add(called);
+          }
+          if (ts.isBinaryExpression(n) && n.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
+            const target = rootName(n.left);
+            if (target && moduleVars.has(target)) writtenVars.add(target);
+          }
+          if (ts.isIdentifier(n) && moduleVars.has(n.getText(sf))) readVars.add(n.getText(sf));
+          ts.forEachChild(n, scan);
+        };
+        ts.forEachChild(node, scan);
+        const memoizesByVar = [...writtenVars].some((v) => readVars.has(v));
+        const name = nameOf(sf, node);
+        if (name && !fns.has(name)) {
+          fns.set(name, {
+            file,
+            line: lineOf(sf, node),
+            readsDirectly,
+            // 캐시로 보는 두 형태: 모듈 Map을 get/set 하거나, 모듈 변수를 읽고 다시 대입하거나
+            hasOwnCache: (moduleHasMap && mapCacheOps >= 2) || memoizesByVar,
+            calls,
+          });
+        }
+      }
+      ts.forEachChild(node, collect);
+    };
+    ts.forEachChild(sf, collect);
+  }
+
+  // 2단계: 호출 그래프로 "리더"를 전파한다 — getThemeComments → readJson → readFileSync 처럼
+  //        직접 읽지 않고 한 다리 건너 읽는 함수가 실제 N+1의 주인공이라 이게 핵심이다.
+  //        읽기 경로가 전부 캐시를 거치면 그 함수도 캐시된 리더로 본다(반복 호출돼도 읽기는 한 번).
+  const readers = new Map(); // 이름 -> { file, line, cached }
+  for (const [name, fn] of fns) {
+    if (fn.readsDirectly) readers.set(name, { file: fn.file, line: fn.line, cached: fn.hasOwnCache });
+  }
+  const MAX_HOPS = 2; // 얇은 래퍼(getThemeComments → readJson)까지만. 더 깊으면 전부 리더가 된다
+  for (let pass = 0; pass < MAX_HOPS; pass++) {
+    let changed = false;
+    for (const [name, fn] of fns) {
+      if (readers.has(name)) continue;
+      const calledReaders = [...fn.calls].map((c) => readers.get(c)).filter(Boolean);
+      if (calledReaders.length === 0) continue;
+      readers.set(name, {
+        file: fn.file,
+        line: fn.line,
+        cached: fn.hasOwnCache || calledReaders.every((r) => r.cached),
+      });
+      changed = true;
+    }
+    if (!changed) break;
+  }
+
+  // 3단계: 그 리더(또는 fs 읽기 자체)가 루프 안에서 불리는 자리를 찾는다.
+  //        for/while뿐 아니라 map·forEach 같은 순회 콜백 안도 루프로 본다.
+  const sites = [];
+  for (const { file, sf } of parsed) {
+    // 캐시를 직접 관리하는 함수 안에서의 읽기는 캐시 미스일 때만 나간다(2단 캐시의 디스크 티어 등)
+    const walk = (node, inLoop, inCachingFn) => {
+      let childInLoop = inLoop;
+      let childInCachingFn = inCachingFn;
+      if (isFnLike(node)) {
+        const self = fns.get(nameOf(sf, node));
+        if (self && self.hasOwnCache) childInCachingFn = true;
+      }
+      switch (node.kind) {
+        case ts.SyntaxKind.ForStatement:
+        case ts.SyntaxKind.ForInStatement:
+        case ts.SyntaxKind.ForOfStatement:
+        case ts.SyntaxKind.WhileStatement:
+        case ts.SyntaxKind.DoStatement:
+          childInLoop = true;
+          break;
+      }
+      if (ts.isCallExpression(node)) {
+        const callee = node.expression;
+        const called = ts.isPropertyAccessExpression(callee) ? callee.name.getText(sf) : callee.getText(sf);
+        const reader = readers.get(called);
+        if (inLoop && (FILE_READ_CALLS.has(called) || reader)) {
+          const cached = inCachingFn || (reader ? reader.cached : false);
+          sites.push({ file, line: lineOf(sf, node), callee: called, cached });
+        }
+        // 순회 메서드에 넘긴 콜백 본문은 루프 안으로 취급
+        if (ts.isPropertyAccessExpression(callee) && ITERATING_METHODS.has(callee.name.getText(sf))) {
+          for (const arg of node.arguments) {
+            if (isFnLike(arg)) walk(arg, true, childInCachingFn);
+          }
+        }
+      }
+      ts.forEachChild(node, (child) => {
+        const alreadyWalked =
+          ts.isCallExpression(node) &&
+          ts.isPropertyAccessExpression(node.expression) &&
+          ITERATING_METHODS.has(node.expression.name.getText(sf)) &&
+          isFnLike(child);
+        if (!alreadyWalked) walk(child, childInLoop, childInCachingFn);
+      });
+    };
+    ts.forEachChild(sf, (n) => walk(n, false, false));
+  }
+
+  const uncached = sites.filter((s) => !s.cached);
+  const readerList = [...readers.entries()].map(([name, r]) => ({ name, ...r }));
+  return {
+    readers: readerList.length,
+    uncachedReaders: readerList.filter((r) => !r.cached).length,
+    loopSites: sites.length,
+    uncachedLoopSites: uncached.length,
+    worst: uncached.slice(0, 5).map(({ file, line, callee }) => ({ file, line, callee })),
+  };
+}
+
+// 렌더 인질 — 데이터 하나를 기다리느라 그와 무관한 UI까지 통째로 못 그리는 자리.
+// `{data && <Nav a={local} b={data.x} onChange={fn} />}` 처럼 프롭 대부분이 이미 아는
+// 값인데 fetch 하나 때문에 전체가 대기하면, 사용자에겐 매번 로딩으로 보인다.
+// 게이트에 걸린 요소가 그 데이터에 실제로 의존하는 비율로 판정한다.
+const HOSTAGE_DEP_RATIO = 0.5; // 프롭 절반도 안 쓰면서 전체를 막고 있으면 인질
+
+function analyzeRenderGates(ts, fileContents) {
+  const findings = [];
+
+  for (const { file, content } of fileContents) {
+    if (!/\.(tsx|jsx)$/.test(file)) continue;
+    const sf = ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+
+    // 훅이 물어다 주는 값(로딩이 있는 값)을 찾는다: const { data: x } = useSomething()
+    const fetched = new Set();
+    const findHookVars = (n) => {
+      if (
+        ts.isVariableDeclaration(n) &&
+        n.initializer &&
+        ts.isCallExpression(n.initializer) &&
+        /^use[A-Z]/.test(
+          ts.isPropertyAccessExpression(n.initializer.expression)
+            ? n.initializer.expression.name.getText(sf)
+            : n.initializer.expression.getText(sf),
+        ) &&
+        ts.isObjectBindingPattern(n.name)
+      ) {
+        for (const el of n.name.elements) {
+          const source = (el.propertyName || el.name).getText(sf);
+          if (source === "data") fetched.add(el.name.getText(sf));
+        }
+      }
+      ts.forEachChild(n, findHookVars);
+    };
+    ts.forEachChild(sf, findHookVars);
+    if (fetched.size === 0) continue;
+
+    const rootName = (expr) => {
+      let cur = expr;
+      while (ts.isPropertyAccessExpression(cur) || ts.isElementAccessExpression(cur)) cur = cur.expression;
+      return ts.isIdentifier(cur) ? cur.getText(sf) : null;
+    };
+
+    /** 이 노드가 그 변수를 실제로 참조하는가 */
+    const references = (node, name) => {
+      let found = false;
+      const scan = (n) => {
+        if (found) return;
+        if (ts.isIdentifier(n) && n.getText(sf) === name) found = true;
+        else ts.forEachChild(n, scan);
+      };
+      scan(node);
+      return found;
+    };
+
+    /** 게이트에 쓰인 fetch 변수들 */
+    const gateVars = (expr) => {
+      const names = new Set();
+      const scan = (n) => {
+        if (ts.isIdentifier(n) && fetched.has(n.getText(sf))) names.add(n.getText(sf));
+        ts.forEachChild(n, scan);
+      };
+      scan(expr);
+      return [...names];
+    };
+
+    const inspectGate = (testExpr, element) => {
+      const vars = gateVars(testExpr);
+      if (vars.length === 0) return;
+      const el = ts.isJsxElement(element) ? element.openingElement : element;
+      if (!el.attributes) return;
+      const props = el.attributes.properties;
+      if (props.length < 2) return; // 프롭이 거의 없으면 판단할 근거가 없다
+
+      const dependent = props.filter((p) => vars.some((v) => references(p, v))).length;
+      const ratio = dependent / props.length;
+      if (ratio < HOSTAGE_DEP_RATIO) {
+        findings.push({
+          file,
+          line: sf.getLineAndCharacterOfPosition(el.getStart(sf)).line + 1,
+          element: el.tagName ? el.tagName.getText(sf) : "?",
+          gate: vars.join(", "),
+          dependentProps: dependent,
+          totalProps: props.length,
+        });
+      }
+    };
+
+    const walk = (n) => {
+      // {data && <El .../>}
+      if (
+        ts.isBinaryExpression(n) &&
+        n.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken &&
+        (ts.isJsxElement(n.right) || ts.isJsxSelfClosingElement(n.right))
+      ) {
+        inspectGate(n.left, n.right);
+      }
+      // {data ? <El .../> : null}
+      if (ts.isConditionalExpression(n) && (ts.isJsxElement(n.whenTrue) || ts.isJsxSelfClosingElement(n.whenTrue))) {
+        inspectGate(n.condition, n.whenTrue);
+      }
+      // 괄호로 감싼 JSX도 같은 취급
+      if (
+        ts.isBinaryExpression(n) &&
+        n.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken &&
+        ts.isParenthesizedExpression(n.right) &&
+        (ts.isJsxElement(n.right.expression) || ts.isJsxSelfClosingElement(n.right.expression))
+      ) {
+        inspectGate(n.left, n.right.expression);
+      }
+      ts.forEachChild(n, walk);
+    };
+    ts.forEachChild(sf, walk);
+    void rootName;
+  }
+
+  return {
+    hostages: findings.length,
+    worst: findings.slice(0, 5),
+  };
+}
+
 // 파일 분류 — frontend(UI) / backend(API·서버) / shared(공용 유틸)
 function classifyFile(filePath, content) {
   const rel = filePath.replace(/\\/g, "/");
@@ -439,10 +739,15 @@ const avgFileLines = files.length > 0 ? Math.round(codeLines / files.length) : 0
 //   ※ 파일 개수 기준 이진 카운트(200줄 넘으면 무조건 1) 대신 심각도 가중 — 살짝 넘는 파일과
 //     터무니없이 큰 파일을 구분하고, 파일 수 적은 프로젝트가 파일 1개만으로 즉시 만점 감점 맞는 절벽 방지.
 // / 평균 파일 길이 80줄 초과분 /5 (최대 10)
+// - 렌더 인질(fetch 하나가 무관한 UI까지 막는 자리) ×3 (최대 10)
+// - 루프 안 무캐시 파일읽기 사이트 ×4 (최대 20) ← 새 축. 코드 모양이 아무리 깔끔해도
+//   호출 1번이 파일 N번을 읽는 구조는 여기서만 드러난다(cognitive·중복으론 원리상 안 잡힘).
 let qualityScore;
 let cc = null;
 let cognitive = null;
 let duplication = null;
+let io = null;
+let renderGates = null;
 if (ts && allFns.length > 0) {
   const byCc = [...allFns].sort((a, b) => b.cc - a.cc);
   cc = {
@@ -469,6 +774,8 @@ if (ts && allFns.length > 0) {
   };
 
   duplication = analyzeDuplication(ts, fileContents);
+  io = analyzeIoDensity(ts, fileContents);
+  renderGates = analyzeRenderGates(ts, fileContents);
 
   const over15Pct = (cogOver15.length / allFns.length) * 100;
   const over25Pct = (cogOver25.length / allFns.length) * 100;
@@ -481,6 +788,8 @@ if (ts && allFns.length > 0) {
     - Math.min(25, Math.max(0, duplication.percent - 3) * 2.5)
     - Math.min(10, longFileSeverityPct * 1.5)
     - Math.min(10, Math.max(0, avgFileLines - 80) / 5)
+    - Math.min(20, io.uncachedLoopSites * 4)
+    - Math.min(10, renderGates.hostages * 3)
   ));
 } else {
   // regex 폴백 (typescript 미설치)
@@ -543,6 +852,8 @@ const stats = {
     grade: qualityGrade,
     cognitive,            // {avg, p90, max, over15, over25, worst[5]} — 중첩 가중 복잡도
     duplication,          // {percent, blocks, worstFiles, worstBlocks} — 토큰 중복 밀도
+    io,                   // {readers, uncachedReaders, loopSites, uncachedLoopSites, worst} — 루프 안 파일 읽기
+    renderGates,          // {hostages, worst} — fetch 하나가 무관한 UI까지 막고 있는 자리
     cc,                   // {functions, avg, p90, max, over10, over20, worst[5]} — McCabe (참고용)
     branchDensity,        // 100줄당 분기 수 (regex 근사, 참고용)
     branches: totalBranches,
@@ -588,6 +899,18 @@ if (cc) {
       console.log(`    중복 블록: ${ex.join(" ≒ ")}`);
     }
   }
+  if (renderGates.hostages > 0) {
+    console.log(`  렌더 인질: ${renderGates.hostages}곳 — 데이터를 기다리느라 이미 아는 UI까지 못 그립니다`);
+    for (const w of renderGates.worst) {
+      console.log(`    인질: <${w.element}> ${w.gate} 대기 (의존 프롭 ${w.dependentProps}/${w.totalProps}) — ${w.file}:${w.line}`);
+    }
+  }
+  if (io.uncachedLoopSites > 0) {
+    console.log(`  루프 안 파일읽기: ${io.uncachedLoopSites}곳 (캐시 없는 리더 ${io.uncachedReaders}/${io.readers}개) — 호출 1번이 파일 N번 읽습니다`);
+    for (const w of io.worst) {
+      console.log(`    반복 읽기: ${w.callee}() — ${w.file}:${w.line}`);
+    }
+  }
 } else {
   console.log(`  청결도: ${qualityGrade} (${qualityScore}점) — 분기밀도 ${branchDensity}/100줄, 평균 ${avgFileLines}줄/파일, 200줄+ ${longFiles}개 (regex 폴백 — typescript 설치 시 AST 정밀 분석)`);
 }

package/dist/index.d.mts

@@ -71,6 +71,10 @@ interface AppShellProps {
  * strip) rather than a hand-rolled height/centering div; without a sized
  * parent the shell just collapses to content height.
  *
+ * The shell and the credit strip are centered together as one group — the
+ * strip sits directly under the shell and moves with it, it does not pin to
+ * the screen's true bottom edge.
+ *
  * @example
  * <Watermark color="#e2603f" text="myapp">
  *   <AppShell>
@@ -84,8 +88,21 @@ interface AppShellHeaderProps {
     children: ReactNode;
     className?: string;
 }
+/**
+ * `AppShellHeader`'s rendered height (base 3.5rem/56px + the top safe-area
+ * inset on notched devices). Pass this as `<FetchProgress top={APP_SHELL_HEADER_HEIGHT}>`
+ * instead of hardcoding `56` so the progress bar still sits flush under the
+ * header on a device with a Dynamic Island / notch.
+ */
+declare const APP_SHELL_HEADER_HEIGHT = "calc(3.5rem + env(safe-area-inset-top))";
 /**
  * Sticky top header with blur backdrop.
+ *
+ * On mobile the shell is full-bleed (no `sm:` margin from Watermark), so this
+ * is the actual topmost element under the device status bar / Dynamic Island
+ * in an installed PWA — `min-height` (not `height`) plus `padding-top` let the
+ * safe-area inset grow the header without squeezing its content, the same
+ * ownership split PoweredByKit uses for the bottom inset.
  */
 declare function AppShellHeader({ children, className }: AppShellHeaderProps): react_jsx_runtime.JSX.Element;
 interface AppShellContentProps {
@@ -102,6 +119,8 @@ declare function AppShellContent({ children, className }: AppShellContentProps):
 interface FabProps {
     onClick: () => void;
     icon: ReactNode;
+    /** Accessible label — icon-only button has no other text for screen readers */
+    label: string;
     /** Accent background color. Default: zinc-900/white (follows dark mode) */
     color?: string;
     className?: string;
@@ -115,10 +134,10 @@ interface FabProps {
  * @example
  * <AppShellContent>
  *   {content}
- *   <Fab onClick={handleAdd} icon={<PlusIcon />} color="#6366f1" />
+ *   <Fab onClick={handleAdd} icon={<PlusIcon />} label="추가" color="#6366f1" />
  * </AppShellContent>
  */
-declare function Fab({ onClick, icon, color, className }: FabProps): react_jsx_runtime.JSX.Element;
+declare function Fab({ onClick, icon, label, color, className }: FabProps): react_jsx_runtime.JSX.Element;
 
 interface TabBarProps {
     children: ReactNode;
@@ -183,8 +202,13 @@ interface FetchProgressProps {
      * When omitted, the bar shows while ANY useFetch request is in flight.
      */
     active?: boolean;
-    /** Distance from the top of the positioned ancestor, in px (e.g. header height). Default: 0 */
-    top?: number;
+    /**
+     * Distance from the top of the positioned ancestor — a number of px, or any
+     * CSS length (e.g. `"calc(3.5rem + env(safe-area-inset-top))"` to sit below
+     * `AppShellHeader`, whose height grows with the safe-area inset on notched
+     * devices). Default: 0
+     */
+    top?: number | string;
     /** Bar thickness in px. Default: 3 */
     height?: number;
     className?: string;
@@ -1768,4 +1792,4 @@ declare function parseIsoDuration(duration: string): IsoDuration;
 /** "PT1H2M3S" → 3723 (초) */
 declare function isoDurationToSec(duration: string): number;
 
-export { ActionCard, type ActionCardLabels, type ActionCardProps, type ActionCardState, type ApiClient, type ApiClientOptions, ApiError, AppShell, AppShellContent, type AppShellContentProps, AppShellHeader, type AppShellHeaderProps, type AppShellProps, AsyncList, type AsyncListProps, type AsyncListStatus, Avatar, type AvatarProps, Badge, type BadgeProps, BarList, type BarListItem, type BarListProps, Button, type ButtonProps, Carousel, type CarouselProps, ChatBubble, type ChatBubbleProps, type ChatMessage, type ChatRole, CodeBlock, type CodeBlockProps, Collapsible, type CollapsibleProps, type ColorName, ColorPicker, type ColorPickerProps, CopyButton, type CopyButtonProps, Countdown, type CountdownLabels, type CountdownProps, type DateCount, type DayGroup, Dialog, type DialogProps, Divider, type DividerProps, EmojiButton, type EmojiButtonProps, EmojiPicker, type EmojiPickerLabels, type EmojiPickerProps, EmptyState, type EmptyStateProps, Fab, type FabProps, FetchProgress, type FetchProgressProps, Field, type FieldProps, FontLinks, type FontName, GrassMap, type GrassMapData, type GrassMapLabels, type GrassMapProps, IOSInstallSheet, IconButton, type IconButtonProps, Img, type ImgProps, InAppSheet, type InAppSheetProps, InlineEdit, type InlineEditProps, Input, type InputProps, type IsoDuration, KitStyles, LinkifiedText, type LinkifiedTextProps, ListRow, type ListRowProps, MediaCard, type MediaCardProps, MessageList, type MessageListProps, PWAInstallButton, type PWAInstallState, PoweredByKit, type PoweredByKitProps, ProgressRing, type ProgressRingProps, Section, SectionHeader, type SectionHeaderProps, type SectionProps, type SegmentOption, SegmentedControl, type SegmentedControlProps, Select, type SelectOption, type SelectProps, ShareButton, type ShareButtonProps, Skeleton, type SkeletonProps, StatChip, type StatChipProps, type Step, Stepper, type StepperProps, Switch, type SwitchProps, THEME_SCRIPT, Tab, TabBar, type TabBarProps, type TabProps, type TabRootProps, Textarea, type TextareaProps, ThemeButton, type ThemeButtonProps, ThemeDialog, type ThemeDialogLabels, type ThemeDialogProps, type ToastOptions, ToastProvider, type ToastVariant, Tooltip, type TooltipProps, Typewriter, type TypewriterProps, TypingIndicator, type TypingIndicatorProps, type UnderlineTab, UnderlineTabs, type UnderlineTabsProps, type UseFetchOptions, type UseFetchResult, type UseFormSubmitOptions, type UseFormSubmitResult, type UseInViewOptions, type UseInViewResult, type UsePWAInstallReturn, type UsePollingOptions, type UsePollingResult, type UseShareOptions, type UseShareReturn, Watermark, type WatermarkProps, type WatermarkSponsor, clearFetchCache, cn, colors, createApiClient, createManifest, fillDateSeries, fontFamily, fonts, formatDayLabel, formatDuration, formatKoreanNumber, formatNumber, formatPrice, getFetchActiveCount, groupByDay, invalidateFetch, isoDurationToSec, mobileViewport, parseIsoDuration, postJson, relativeTime, subscribeFetchActivity, svgIcon, useCopy, useDebounce, useEscapeKey, useFetch, useFocusTrap, useFormSubmit, useImageLoader, useInView, useLocalStorage, usePWAInstall, usePolling, usePortalTarget, useScrollLock, useShare, useToast };
+export { APP_SHELL_HEADER_HEIGHT, ActionCard, type ActionCardLabels, type ActionCardProps, type ActionCardState, type ApiClient, type ApiClientOptions, ApiError, AppShell, AppShellContent, type AppShellContentProps, AppShellHeader, type AppShellHeaderProps, type AppShellProps, AsyncList, type AsyncListProps, type AsyncListStatus, Avatar, type AvatarProps, Badge, type BadgeProps, BarList, type BarListItem, type BarListProps, Button, type ButtonProps, Carousel, type CarouselProps, ChatBubble, type ChatBubbleProps, type ChatMessage, type ChatRole, CodeBlock, type CodeBlockProps, Collapsible, type CollapsibleProps, type ColorName, ColorPicker, type ColorPickerProps, CopyButton, type CopyButtonProps, Countdown, type CountdownLabels, type CountdownProps, type DateCount, type DayGroup, Dialog, type DialogProps, Divider, type DividerProps, EmojiButton, type EmojiButtonProps, EmojiPicker, type EmojiPickerLabels, type EmojiPickerProps, EmptyState, type EmptyStateProps, Fab, type FabProps, FetchProgress, type FetchProgressProps, Field, type FieldProps, FontLinks, type FontName, GrassMap, type GrassMapData, type GrassMapLabels, type GrassMapProps, IOSInstallSheet, IconButton, type IconButtonProps, Img, type ImgProps, InAppSheet, type InAppSheetProps, InlineEdit, type InlineEditProps, Input, type InputProps, type IsoDuration, KitStyles, LinkifiedText, type LinkifiedTextProps, ListRow, type ListRowProps, MediaCard, type MediaCardProps, MessageList, type MessageListProps, PWAInstallButton, type PWAInstallState, PoweredByKit, type PoweredByKitProps, ProgressRing, type ProgressRingProps, Section, SectionHeader, type SectionHeaderProps, type SectionProps, type SegmentOption, SegmentedControl, type SegmentedControlProps, Select, type SelectOption, type SelectProps, ShareButton, type ShareButtonProps, Skeleton, type SkeletonProps, StatChip, type StatChipProps, type Step, Stepper, type StepperProps, Switch, type SwitchProps, THEME_SCRIPT, Tab, TabBar, type TabBarProps, type TabProps, type TabRootProps, Textarea, type TextareaProps, ThemeButton, type ThemeButtonProps, ThemeDialog, type ThemeDialogLabels, type ThemeDialogProps, type ToastOptions, ToastProvider, type ToastVariant, Tooltip, type TooltipProps, Typewriter, type TypewriterProps, TypingIndicator, type TypingIndicatorProps, type UnderlineTab, UnderlineTabs, type UnderlineTabsProps, type UseFetchOptions, type UseFetchResult, type UseFormSubmitOptions, type UseFormSubmitResult, type UseInViewOptions, type UseInViewResult, type UsePWAInstallReturn, type UsePollingOptions, type UsePollingResult, type UseShareOptions, type UseShareReturn, Watermark, type WatermarkProps, type WatermarkSponsor, clearFetchCache, cn, colors, createApiClient, createManifest, fillDateSeries, fontFamily, fonts, formatDayLabel, formatDuration, formatKoreanNumber, formatNumber, formatPrice, getFetchActiveCount, groupByDay, invalidateFetch, isoDurationToSec, mobileViewport, parseIsoDuration, postJson, relativeTime, subscribeFetchActivity, svgIcon, useCopy, useDebounce, useEscapeKey, useFetch, useFocusTrap, useFormSubmit, useImageLoader, useInView, useLocalStorage, usePWAInstall, usePolling, usePortalTarget, useScrollLock, useShare, useToast };

package/dist/index.d.ts

@@ -71,6 +71,10 @@ interface AppShellProps {
  * strip) rather than a hand-rolled height/centering div; without a sized
  * parent the shell just collapses to content height.
  *
+ * The shell and the credit strip are centered together as one group — the
+ * strip sits directly under the shell and moves with it, it does not pin to
+ * the screen's true bottom edge.
+ *
  * @example
  * <Watermark color="#e2603f" text="myapp">
  *   <AppShell>
@@ -84,8 +88,21 @@ interface AppShellHeaderProps {
     children: ReactNode;
     className?: string;
 }
+/**
+ * `AppShellHeader`'s rendered height (base 3.5rem/56px + the top safe-area
+ * inset on notched devices). Pass this as `<FetchProgress top={APP_SHELL_HEADER_HEIGHT}>`
+ * instead of hardcoding `56` so the progress bar still sits flush under the
+ * header on a device with a Dynamic Island / notch.
+ */
+declare const APP_SHELL_HEADER_HEIGHT = "calc(3.5rem + env(safe-area-inset-top))";
 /**
  * Sticky top header with blur backdrop.
+ *
+ * On mobile the shell is full-bleed (no `sm:` margin from Watermark), so this
+ * is the actual topmost element under the device status bar / Dynamic Island
+ * in an installed PWA — `min-height` (not `height`) plus `padding-top` let the
+ * safe-area inset grow the header without squeezing its content, the same
+ * ownership split PoweredByKit uses for the bottom inset.
  */
 declare function AppShellHeader({ children, className }: AppShellHeaderProps): react_jsx_runtime.JSX.Element;
 interface AppShellContentProps {
@@ -102,6 +119,8 @@ declare function AppShellContent({ children, className }: AppShellContentProps):
 interface FabProps {
     onClick: () => void;
     icon: ReactNode;
+    /** Accessible label — icon-only button has no other text for screen readers */
+    label: string;
     /** Accent background color. Default: zinc-900/white (follows dark mode) */
     color?: string;
     className?: string;
@@ -115,10 +134,10 @@ interface FabProps {
  * @example
  * <AppShellContent>
  *   {content}
- *   <Fab onClick={handleAdd} icon={<PlusIcon />} color="#6366f1" />
+ *   <Fab onClick={handleAdd} icon={<PlusIcon />} label="추가" color="#6366f1" />
  * </AppShellContent>
  */
-declare function Fab({ onClick, icon, color, className }: FabProps): react_jsx_runtime.JSX.Element;
+declare function Fab({ onClick, icon, label, color, className }: FabProps): react_jsx_runtime.JSX.Element;
 
 interface TabBarProps {
     children: ReactNode;
@@ -183,8 +202,13 @@ interface FetchProgressProps {
      * When omitted, the bar shows while ANY useFetch request is in flight.
      */
     active?: boolean;
-    /** Distance from the top of the positioned ancestor, in px (e.g. header height). Default: 0 */
-    top?: number;
+    /**
+     * Distance from the top of the positioned ancestor — a number of px, or any
+     * CSS length (e.g. `"calc(3.5rem + env(safe-area-inset-top))"` to sit below
+     * `AppShellHeader`, whose height grows with the safe-area inset on notched
+     * devices). Default: 0
+     */
+    top?: number | string;
     /** Bar thickness in px. Default: 3 */
     height?: number;
     className?: string;
@@ -1768,4 +1792,4 @@ declare function parseIsoDuration(duration: string): IsoDuration;
 /** "PT1H2M3S" → 3723 (초) */
 declare function isoDurationToSec(duration: string): number;
 
-export { ActionCard, type ActionCardLabels, type ActionCardProps, type ActionCardState, type ApiClient, type ApiClientOptions, ApiError, AppShell, AppShellContent, type AppShellContentProps, AppShellHeader, type AppShellHeaderProps, type AppShellProps, AsyncList, type AsyncListProps, type AsyncListStatus, Avatar, type AvatarProps, Badge, type BadgeProps, BarList, type BarListItem, type BarListProps, Button, type ButtonProps, Carousel, type CarouselProps, ChatBubble, type ChatBubbleProps, type ChatMessage, type ChatRole, CodeBlock, type CodeBlockProps, Collapsible, type CollapsibleProps, type ColorName, ColorPicker, type ColorPickerProps, CopyButton, type CopyButtonProps, Countdown, type CountdownLabels, type CountdownProps, type DateCount, type DayGroup, Dialog, type DialogProps, Divider, type DividerProps, EmojiButton, type EmojiButtonProps, EmojiPicker, type EmojiPickerLabels, type EmojiPickerProps, EmptyState, type EmptyStateProps, Fab, type FabProps, FetchProgress, type FetchProgressProps, Field, type FieldProps, FontLinks, type FontName, GrassMap, type GrassMapData, type GrassMapLabels, type GrassMapProps, IOSInstallSheet, IconButton, type IconButtonProps, Img, type ImgProps, InAppSheet, type InAppSheetProps, InlineEdit, type InlineEditProps, Input, type InputProps, type IsoDuration, KitStyles, LinkifiedText, type LinkifiedTextProps, ListRow, type ListRowProps, MediaCard, type MediaCardProps, MessageList, type MessageListProps, PWAInstallButton, type PWAInstallState, PoweredByKit, type PoweredByKitProps, ProgressRing, type ProgressRingProps, Section, SectionHeader, type SectionHeaderProps, type SectionProps, type SegmentOption, SegmentedControl, type SegmentedControlProps, Select, type SelectOption, type SelectProps, ShareButton, type ShareButtonProps, Skeleton, type SkeletonProps, StatChip, type StatChipProps, type Step, Stepper, type StepperProps, Switch, type SwitchProps, THEME_SCRIPT, Tab, TabBar, type TabBarProps, type TabProps, type TabRootProps, Textarea, type TextareaProps, ThemeButton, type ThemeButtonProps, ThemeDialog, type ThemeDialogLabels, type ThemeDialogProps, type ToastOptions, ToastProvider, type ToastVariant, Tooltip, type TooltipProps, Typewriter, type TypewriterProps, TypingIndicator, type TypingIndicatorProps, type UnderlineTab, UnderlineTabs, type UnderlineTabsProps, type UseFetchOptions, type UseFetchResult, type UseFormSubmitOptions, type UseFormSubmitResult, type UseInViewOptions, type UseInViewResult, type UsePWAInstallReturn, type UsePollingOptions, type UsePollingResult, type UseShareOptions, type UseShareReturn, Watermark, type WatermarkProps, type WatermarkSponsor, clearFetchCache, cn, colors, createApiClient, createManifest, fillDateSeries, fontFamily, fonts, formatDayLabel, formatDuration, formatKoreanNumber, formatNumber, formatPrice, getFetchActiveCount, groupByDay, invalidateFetch, isoDurationToSec, mobileViewport, parseIsoDuration, postJson, relativeTime, subscribeFetchActivity, svgIcon, useCopy, useDebounce, useEscapeKey, useFetch, useFocusTrap, useFormSubmit, useImageLoader, useInView, useLocalStorage, usePWAInstall, usePolling, usePortalTarget, useScrollLock, useShare, useToast };
+export { APP_SHELL_HEADER_HEIGHT, ActionCard, type ActionCardLabels, type ActionCardProps, type ActionCardState, type ApiClient, type ApiClientOptions, ApiError, AppShell, AppShellContent, type AppShellContentProps, AppShellHeader, type AppShellHeaderProps, type AppShellProps, AsyncList, type AsyncListProps, type AsyncListStatus, Avatar, type AvatarProps, Badge, type BadgeProps, BarList, type BarListItem, type BarListProps, Button, type ButtonProps, Carousel, type CarouselProps, ChatBubble, type ChatBubbleProps, type ChatMessage, type ChatRole, CodeBlock, type CodeBlockProps, Collapsible, type CollapsibleProps, type ColorName, ColorPicker, type ColorPickerProps, CopyButton, type CopyButtonProps, Countdown, type CountdownLabels, type CountdownProps, type DateCount, type DayGroup, Dialog, type DialogProps, Divider, type DividerProps, EmojiButton, type EmojiButtonProps, EmojiPicker, type EmojiPickerLabels, type EmojiPickerProps, EmptyState, type EmptyStateProps, Fab, type FabProps, FetchProgress, type FetchProgressProps, Field, type FieldProps, FontLinks, type FontName, GrassMap, type GrassMapData, type GrassMapLabels, type GrassMapProps, IOSInstallSheet, IconButton, type IconButtonProps, Img, type ImgProps, InAppSheet, type InAppSheetProps, InlineEdit, type InlineEditProps, Input, type InputProps, type IsoDuration, KitStyles, LinkifiedText, type LinkifiedTextProps, ListRow, type ListRowProps, MediaCard, type MediaCardProps, MessageList, type MessageListProps, PWAInstallButton, type PWAInstallState, PoweredByKit, type PoweredByKitProps, ProgressRing, type ProgressRingProps, Section, SectionHeader, type SectionHeaderProps, type SectionProps, type SegmentOption, SegmentedControl, type SegmentedControlProps, Select, type SelectOption, type SelectProps, ShareButton, type ShareButtonProps, Skeleton, type SkeletonProps, StatChip, type StatChipProps, type Step, Stepper, type StepperProps, Switch, type SwitchProps, THEME_SCRIPT, Tab, TabBar, type TabBarProps, type TabProps, type TabRootProps, Textarea, type TextareaProps, ThemeButton, type ThemeButtonProps, ThemeDialog, type ThemeDialogLabels, type ThemeDialogProps, type ToastOptions, ToastProvider, type ToastVariant, Tooltip, type TooltipProps, Typewriter, type TypewriterProps, TypingIndicator, type TypingIndicatorProps, type UnderlineTab, UnderlineTabs, type UnderlineTabsProps, type UseFetchOptions, type UseFetchResult, type UseFormSubmitOptions, type UseFormSubmitResult, type UseInViewOptions, type UseInViewResult, type UsePWAInstallReturn, type UsePollingOptions, type UsePollingResult, type UseShareOptions, type UseShareReturn, Watermark, type WatermarkProps, type WatermarkSponsor, clearFetchCache, cn, colors, createApiClient, createManifest, fillDateSeries, fontFamily, fonts, formatDayLabel, formatDuration, formatKoreanNumber, formatNumber, formatPrice, getFetchActiveCount, groupByDay, invalidateFetch, isoDurationToSec, mobileViewport, parseIsoDuration, postJson, relativeTime, subscribeFetchActivity, svgIcon, useCopy, useDebounce, useEscapeKey, useFetch, useFocusTrap, useFormSubmit, useImageLoader, useInView, useLocalStorage, usePWAInstall, usePolling, usePortalTarget, useScrollLock, useShare, useToast };