@m1kapp/kit 0.0.31 → 0.0.33

package/README.md

@@ -17,21 +17,25 @@ npm install @m1kapp/kit
 
 ```tsx
 // CSS 자동 주입 — 별도 import 불필요
-import { AppShell, AppShellHeader, AppShellContent, TabBar, Tab } from "@m1kapp/kit";
+import { Watermark, AppShell, AppShellHeader, AppShellContent, Section, TabBar, Tab } from "@m1kapp/kit";
 
 export default function App() {
   return (
-    <AppShell>
-      <AppShellHeader>
-        <h1>My App</h1>
-      </AppShellHeader>
-      <AppShellContent>
-        {/* 콘텐츠 */}
-      </AppShellContent>
-      <TabBar>
-        <Tab href="/" icon={<HomeIcon />} label="홈" />
-      </TabBar>
-    </AppShell>
+    // Watermark가 뷰포트 전체 높이/중앙정렬/하단 크레딧을 같이 줍니다.
+    // AppShell만 단독으로 쓰면 콘텐츠 높이만큼 쪼그라들어요.
+    <Watermark color="#e2603f" text="myapp">
+      <AppShell>
+        <AppShellHeader>
+          <h1>My App</h1>
+        </AppShellHeader>
+        <AppShellContent>
+          <Section className="pt-4">{/* 콘텐츠 — Divider로 섹션 구분 */}</Section>
+        </AppShellContent>
+        <TabBar>
+          <Tab href="/" icon={<HomeIcon />} label="홈" />
+        </TabBar>
+      </AppShell>
+    </Watermark>
   );
 }
 ```
@@ -454,14 +458,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} />
 ```
 
@@ -521,6 +527,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/bin/stats.mjs

@@ -390,6 +390,7 @@ let totalBranches = 0;
 let totalFunctions = 0;
 let maxFile = { path: "", lines: 0 };
 let longFiles = 0; // 200줄 초과 파일 수
+let longFileSeverity = 0; // 200→400줄 0→1, 400→600줄 1→2로 완만하게 누적 (600줄+ 파일당 최대 2)
 const allImports = new Set();
 const ts = loadTypescript();
 const allFns = []; // AST 모드: {name, cc, cog, line, file}
@@ -417,7 +418,10 @@ for (const file of files) {
     fileContents.push({ file: rel, content });
   }
   if (counts.code > maxFile.lines) maxFile = { path: path.relative(process.cwd(), file), lines: counts.code };
-  if (counts.code > 200) longFiles++;
+  if (counts.code > 200) {
+    longFiles++;
+    longFileSeverity += Math.min(2, (counts.code - 200) / 200);
+  }
   const imports = detectKitImports(content);
   for (const imp of imports) allImports.add(imp);
 }
@@ -431,7 +435,10 @@ const avgFileLines = files.length > 0 ? Math.round(codeLines / files.length) : 0
 // - cog>15 함수 비율 ×3 (최대 25), cog>25 함수 비율 ×5 (최대 15)
 // - 최악 함수: cog 20 초과분 ×1 (최대 15)
 // - 중복 밀도: 3% 초과분 ×2.5 (최대 25) ← 새 축
-// - 200줄 초과 파일 비율 ×2 (최대 10) / 평균 파일 길이 80줄 초과분 /5 (최대 10)
+// - 200줄 초과 파일: 초과분에 비례한 심각도(200→400줄 0→1, 400→600줄 1→2, 600줄+ 캡) 비율 ×1.5 (최대 10)
+//   ※ 파일 개수 기준 이진 카운트(200줄 넘으면 무조건 1) 대신 심각도 가중 — 살짝 넘는 파일과
+//     터무니없이 큰 파일을 구분하고, 파일 수 적은 프로젝트가 파일 1개만으로 즉시 만점 감점 맞는 절벽 방지.
+// / 평균 파일 길이 80줄 초과분 /5 (최대 10)
 let qualityScore;
 let cc = null;
 let cognitive = null;
@@ -465,14 +472,14 @@ if (ts && allFns.length > 0) {
 
   const over15Pct = (cogOver15.length / allFns.length) * 100;
   const over25Pct = (cogOver25.length / allFns.length) * 100;
-  const longFilesPct = (longFiles / files.length) * 100;
+  const longFileSeverityPct = (longFileSeverity / files.length) * 100;
   qualityScore = Math.max(0, Math.round(
     100
     - Math.min(25, over15Pct * 3)
     - Math.min(15, over25Pct * 5)
     - Math.min(15, Math.max(0, maxCog - 20))
     - Math.min(25, Math.max(0, duplication.percent - 3) * 2.5)
-    - Math.min(10, longFilesPct * 2)
+    - Math.min(10, longFileSeverityPct * 1.5)
     - Math.min(10, Math.max(0, avgFileLines - 80) / 5)
   ));
 } else {
@@ -480,7 +487,7 @@ if (ts && allFns.length > 0) {
   qualityScore = Math.max(0, Math.round(
     100
     - Math.min(40, Math.max(0, branchDensity - 10) * 2)
-    - Math.min(30, longFiles * 5)
+    - Math.min(30, longFileSeverity * 2.5)
     - Math.min(30, Math.max(0, avgFileLines - 80) / 4)
   ));
 }

package/dist/index.d.mts

@@ -65,6 +65,19 @@ interface AppShellProps {
 /**
  * Mobile app-like container with rounded corners, shadow, and ring.
  * Centers content and constrains width for a phone-like viewport.
+ *
+ * `AppShell` fills `h-full` of its parent — it does not size itself. Wrap it
+ * in `<Watermark>` (gives `h-dvh` + centering + the `PoweredByKit` credit
+ * strip) rather than a hand-rolled height/centering div; without a sized
+ * parent the shell just collapses to content height.
+ *
+ * @example
+ * <Watermark color="#e2603f" text="myapp">
+ *   <AppShell>
+ *     <AppShellHeader>...</AppShellHeader>
+ *     <AppShellContent><Section>...</Section></AppShellContent>
+ *   </AppShell>
+ * </Watermark>
  */
 declare function AppShell({ children, className, maxWidth, maxHeight, accent, accentFg, style, }: AppShellProps): react_jsx_runtime.JSX.Element;
 interface AppShellHeaderProps {
@@ -80,7 +93,9 @@ interface AppShellContentProps {
     className?: string;
 }
 /**
- * Scrollable main content area.
+ * Scrollable main content area. Carries no padding of its own — build
+ * children from `<Section>` (px-4) blocks separated by `<Divider spacing="sm" />`,
+ * not a hand-rolled `<div className="p-4 flex flex-col gap-4">`.
  */
 declare function AppShellContent({ children, className }: AppShellContentProps): react_jsx_runtime.JSX.Element;
 
@@ -111,6 +126,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 {

package/dist/index.d.ts

@@ -65,6 +65,19 @@ interface AppShellProps {
 /**
  * Mobile app-like container with rounded corners, shadow, and ring.
  * Centers content and constrains width for a phone-like viewport.
+ *
+ * `AppShell` fills `h-full` of its parent — it does not size itself. Wrap it
+ * in `<Watermark>` (gives `h-dvh` + centering + the `PoweredByKit` credit
+ * strip) rather than a hand-rolled height/centering div; without a sized
+ * parent the shell just collapses to content height.
+ *
+ * @example
+ * <Watermark color="#e2603f" text="myapp">
+ *   <AppShell>
+ *     <AppShellHeader>...</AppShellHeader>
+ *     <AppShellContent><Section>...</Section></AppShellContent>
+ *   </AppShell>
+ * </Watermark>
  */
 declare function AppShell({ children, className, maxWidth, maxHeight, accent, accentFg, style, }: AppShellProps): react_jsx_runtime.JSX.Element;
 interface AppShellHeaderProps {
@@ -80,7 +93,9 @@ interface AppShellContentProps {
     className?: string;
 }
 /**
- * Scrollable main content area.
+ * Scrollable main content area. Carries no padding of its own — build
+ * children from `<Section>` (px-4) blocks separated by `<Divider spacing="sm" />`,
+ * not a hand-rolled `<div className="p-4 flex flex-col gap-4">`.
  */
 declare function AppShellContent({ children, className }: AppShellContentProps): react_jsx_runtime.JSX.Element;
 
@@ -111,6 +126,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 {