@m1kapp/kit 0.0.32 → 0.0.36

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>
@@ -458,14 +459,16 @@ npx m1kkit track https://myside.app
 ```
 
 ```bash
-# 2) .env 에 한 줄 → 이후 자동 집계 (스니펫 붙여넣기 불필요)
+# 2) Next.js면 .env 에 한 줄 → 이후 자동 집계 (스니펫 붙여넣기 불필요)
 NEXT_PUBLIC_M1K_SLUG=your-slug
 ```
 
+Vite 등 Next.js가 아닌 앱은 `NEXT_PUBLIC_*` env가 안 읽히니 `trackSlug` prop으로 직접 지정하세요:
+
 ```tsx
 // 끄기 / 명시 지정
 <Watermark track={false}>…</Watermark>        // 비콘 끔
-<Watermark trackSlug="your-slug">…</Watermark> // env 대신 직접 지정
+<Watermark trackSlug="your-slug">…</Watermark> // env 대신 직접 지정 (Vite는 이 방식 사용)
 // PoweredByKit 단독 사용 시: <PoweredByKit slug="your-slug" track={false} />
 ```
 
@@ -525,6 +528,20 @@ export async function GET() {
 <OGImage type="product" title="@m1kapp/kit" tagline="올인원 킷" features={["기능1", "기능2"]} color={c} bg={bg} />
 ```
 
+### CLI로 한 번에 (Next.js 라우트 없이)
+
+Vite 등 서버 없는 SPA라 `app/og/route.tsx`를 못 만든다면, 빌드 없이 CLI로
+파비콘부터 OG 이미지, manifest까지 한 번에 생성하세요:
+
+```bash
+npx m1kkit favicon --appname="My App" --slogan="한 줄 소개" --color=#3b82f6 --domain=myapp.com
+```
+
+`favicon.ico` · `apple-touch-icon.png` · `icon-192.png` · `icon-512.png` ·
+`icon-maskable-512.png` · `og-image.png`(1200×630, 위 `default` 템플릿 사용) ·
+`manifest.json` 7개가 `public/`(자동 감지)에 한 번에 생기고, `<head>`에 붙여넣을
+태그 스니펫도 콘솔에 출력됩니다.
+
 ### 폰트 & 이모지
 
 ```tsx

package/bin/favicon.mjs

@@ -1,16 +1,23 @@
 #!/usr/bin/env node
 /**
- * @m1kapp/kit favicon generator CLI
+ * @m1kapp/kit favicon + SEO 이미지 생성 CLI
  *
  * Usage:
  *   npx @m1kapp/kit favicon
  *   npx @m1kapp/kit favicon --text=kit --color=#0f0f1a
  *   npx @m1kapp/kit favicon --text=W --color=#7c3aed --out=./static
+ *   npx @m1kapp/kit favicon --appname="My App" --slogan="한 줄 소개" --domain=myapp.com
  *
  * Options:
- *   --text     표시할 텍스트 (기본: package.json name 첫 글자)
- *   --color    배경색 hex (기본: #0f0f1a)
+ *   --text     파비콘에 표시할 짧은 텍스트 (기본: package.json name 첫 글자)
+ *   --appname  OG 이미지/manifest용 앱 이름 (기본: package.json name)
+ *   --slogan   OG 이미지 부제
+ *   --domain   OG 이미지 하단 도메인 (선택)
+ *   --color    브랜드색 hex (기본: #0f0f1a)
  *   --out      출력 디렉토리 (기본: 자동 감지)
+ *
+ * 생성 파일: favicon.ico · apple-touch-icon.png · icon-192.png · icon-512.png ·
+ *           icon-maskable-512.png · og-image.png · manifest.json
  */
 
 import { ImageResponse } from "@vercel/og";
@@ -61,48 +68,90 @@ function detectOutDir() {
   return cwd;
 }
 
-/* ─── Auto-detect text ─── */
-function detectText() {
-  if (args.text) return args.text;
+function readPkgName() {
   try {
     const pkg = JSON.parse(fs.readFileSync(path.join(process.cwd(), "package.json"), "utf8"));
-    const name = (pkg.name ?? "app").replace(/^@[^/]+\//, ""); // scoped 패키지 처리
-    return name.slice(0, 3); // 최대 3글자
+    return (pkg.name ?? "app").replace(/^@[^/]+\//, ""); // scoped 패키지 처리
   } catch {
     return "app";
   }
 }
 
-/* ─── Load createFaviconElement from dist ─── */
+/* ─── Auto-detect short favicon text ─── */
+function detectText() {
+  if (args.text) return args.text;
+  return readPkgName().slice(0, 3); // 최대 3글자
+}
+
+/* ─── Auto-detect full app name (OG/manifest용) ─── */
+function detectAppName() {
+  if (args.appname) return args.appname;
+  return readPkgName();
+}
+
+/* ─── Load generators from dist ─── */
 const distPath = path.resolve(__dirname, "../dist/ogimage.mjs");
-const { createFaviconElement } = await import(distPath);
+const { createFaviconElement, OGImage } = await import(distPath);
 
 /* ─── Generate ─── */
 const text = detectText();
+const appName = detectAppName();
+const slogan = args.slogan;
+const domain = args.domain;
 const color = args.color ?? "#0f0f1a";
 const outDir = detectOutDir();
 
-async function generatePng(sizePx) {
+async function generatePng(sizePx, maskable = false) {
   const res = new ImageResponse(
-    h(createFaviconElement, { text, color, size: sizePx }),
+    h(createFaviconElement, { text, color, size: sizePx, maskable }),
     { width: sizePx, height: sizePx }
   );
   return Buffer.from(await res.arrayBuffer());
 }
 
-fs.mkdirSync(outDir, { recursive: true });
+function write(name, buffer) {
+  fs.writeFileSync(path.join(outDir, name), buffer);
+  console.log(`✓ ${path.relative(process.cwd(), path.join(outDir, name))}`);
+}
 
-const icoBuffers = await Promise.all([16, 32, 48].map(generatePng));
-const icoBuffer = await pngToIco(icoBuffers);
-fs.writeFileSync(path.join(outDir, "favicon.ico"), icoBuffer);
-console.log(`✓ ${path.relative(process.cwd(), path.join(outDir, "favicon.ico"))}`);
+fs.mkdirSync(outDir, { recursive: true });
 
-const appleBuffer = await generatePng(180);
-fs.writeFileSync(path.join(outDir, "apple-touch-icon.png"), appleBuffer);
-console.log(`✓ ${path.relative(process.cwd(), path.join(outDir, "apple-touch-icon.png"))}`);
+const icoBuffers = await Promise.all([16, 32, 48].map((s) => generatePng(s)));
+write("favicon.ico", await pngToIco(icoBuffers));
 
-const pwaBuffer = await generatePng(512);
-fs.writeFileSync(path.join(outDir, "icon-512.png"), pwaBuffer);
-console.log(`✓ ${path.relative(process.cwd(), path.join(outDir, "icon-512.png"))}`);
+write("apple-touch-icon.png", await generatePng(180));
+write("icon-192.png", await generatePng(192));
+write("icon-512.png", await generatePng(512));
+write("icon-maskable-512.png", await generatePng(512, true));
 
-console.log(`\n🎉 text="${text}" color="${color}" → ${path.relative(process.cwd(), outDir) || "."}/`);
+const ogRes = new ImageResponse(
+  h(OGImage, { type: "default", title: appName, sub: slogan, appName, color, domain }),
+  { width: 1200, height: 630 }
+);
+write("og-image.png", Buffer.from(await ogRes.arrayBuffer()));
+
+const manifest = {
+  name: appName,
+  short_name: appName,
+  start_url: "/",
+  display: "standalone",
+  background_color: color,
+  theme_color: color,
+  icons: [
+    { src: "/icon-192.png", sizes: "192x192", type: "image/png" },
+    { src: "/icon-512.png", sizes: "512x512", type: "image/png" },
+    { src: "/icon-maskable-512.png", sizes: "512x512", type: "image/png", purpose: "maskable" },
+  ],
+};
+write("manifest.json", JSON.stringify(manifest, null, 2) + "\n");
+
+console.log(`\n🎉 appname="${appName}" color="${color}" → ${path.relative(process.cwd(), outDir) || "."}/`);
+console.log(`
+<head>에 붙여넣기:
+  <link rel="icon" type="image/x-icon" href="/favicon.ico" />
+  <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
+  <link rel="manifest" href="/manifest.json" />
+  <meta property="og:image" content="https://<도메인>/og-image.png" />
+  <meta property="og:image:width" content="1200" />
+  <meta property="og:image:height" content="630" />
+`);

package/bin/skills/m1kapp-pwa.md

@@ -36,12 +36,19 @@ PWA 설정 현황
 
 빠진 항목에 대해 확인 후 적용한다.
 
-아이콘이 없으면: `npx m1kkit favicon` 명령어 안내
-manifest가 없으면: 앱 이름, 테마 컬러를 물어보고 `createManifest` 적용
+아이콘이 없으면: `npx m1kkit favicon --appname="[앱 이름]" --color="[테마 컬러]"` 안내
+— favicon.ico/apple-touch-icon/icon-192/icon-512/icon-maskable-512 뿐 아니라
+og-image.png와 manifest.json까지 한 번에 만들어줌.
+
+manifest가 없으면:
+- Next.js면 앱 이름·테마 컬러를 물어보고 `createManifest` 적용 (아래).
+- Vite 등 App Router가 없는 프로젝트면 `npx m1kkit favicon`이 만든
+  `public/manifest.json`을 그대로 쓰면 됨 — 따로 만들 필요 없음.
+
 viewport가 없으면: `mobileViewport` 적용
 
 ```ts
-// app/manifest.ts
+// app/manifest.ts (Next.js App Router)
 import { createManifest } from "@m1kapp/kit/pwa"
 
 export default function manifest() {

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;
@@ -126,6 +145,13 @@ interface TabBarProps {
 }
 /**
  * Sticky bottom navigation tab bar.
+ *
+ * Carries no safe-area padding of its own — TabBar is meant to sit inside
+ * `AppShell`, which sits inside `Watermark`. `Watermark` appends its
+ * `PoweredByKit` credit strip right after `AppShell`, and that strip is the
+ * one that owns the home-indicator safe area (`variant="overlay"`). If
+ * TabBar also padded itself for the safe area, the reservation would be
+ * doubled — a blank gap between the tab icons and the credit strip.
  */
 declare function TabBar({ children, className }: TabBarProps): react_jsx_runtime.JSX.Element;
 interface TabRootProps {
@@ -176,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;
@@ -1761,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;
@@ -126,6 +145,13 @@ interface TabBarProps {
 }
 /**
  * Sticky bottom navigation tab bar.
+ *
+ * Carries no safe-area padding of its own — TabBar is meant to sit inside
+ * `AppShell`, which sits inside `Watermark`. `Watermark` appends its
+ * `PoweredByKit` credit strip right after `AppShell`, and that strip is the
+ * one that owns the home-indicator safe area (`variant="overlay"`). If
+ * TabBar also padded itself for the safe area, the reservation would be
+ * doubled — a blank gap between the tab icons and the credit strip.
  */
 declare function TabBar({ children, className }: TabBarProps): react_jsx_runtime.JSX.Element;
 interface TabRootProps {
@@ -176,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;
@@ -1761,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 };