pubuilder 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 taehoon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# pubuilder
+
+**In-app IA minimap & block inspector for React** — press a floating button in your dev build and see every page of your app laid out as live iframe thumbnails on a zoomable canvas. Click a page to zoom in, then hover-select sections and blocks devtools-style.
+
+Dev-only by design: `<PageMap>` renders nothing in production builds automatically.
+
+## Install
+
+```bash
+pnpm add -D pubuilder   # or npm i -D / yarn add -D
+```
+
+## Quick start
+
+```tsx
+// App.tsx
+import { PageMap } from 'pubuilder'
+import ia from './ia.config'
+
+<PageMap config={ia} />
+```
+
+That's it — in production bundles (`NODE_ENV === 'production'`) the component bails out on its own, so no manual guard is required. Wrapping it in your own dev flag still works and saves the bundle bytes:
+
+```tsx
+{import.meta.env.DEV && <PageMap config={ia} />}
+```
+
+## Generate `ia.config.ts` automatically (Next.js)
+
+```bash
+npx pubuilder scan            # scan app/ or pages/ routes and draft ia.config.ts
+npx pubuilder scan --dry-run  # preview without writing
+```
+
+- First run drafts the config — you only polish titles and replace `[param]` segments with sample paths (e.g. `/artflo/1`).
+- Re-running **merges**: your hand-tuned titles, hierarchy, and variants are preserved; only new routes are added. Routes that disappeared are reported, never deleted.
+- Keep `ia.config.ts` a pure data file (it is actually loaded during scan).
+- Non-Next.js projects aren't scannable yet (v1) — the CLI generates an annotated template to start from instead.
+
+## Writing the config by hand
+
+```ts
+// ia.config.ts
+import { defineIA } from 'pubuilder'
+
+export default defineIA({
+  pages: [
+    { path: '/login', title: 'Login' },
+    {
+      path: '/',
+      title: 'Home',
+      children: [
+        {
+          path: '/ai-agent',
+          title: 'AI Agent',
+          // screens that differ by query string become child nodes
+          variants: [
+            { title: 'All', query: { category: 'all' } },
+            { title: 'Art', query: { category: 'art', tab: 1 } },
+          ],
+        },
+        { path: 'https://example.com/brand', title: 'Brand', external: true },
+      ],
+    },
+  ],
+})
+```
+
+- `path` — route path; use a representative sample for dynamic routes (`/notice/1`)
+- `variants` — query-string variations, rendered as separate thumbnails
+- `external` — link-out node, no thumbnail/inspection (auto-detected for `http(s)://`)
+- `viewport` — virtual viewport for thumbnails, default `1440x900`
+
+## Requirements
+
+- React ≥ 18, same-origin pages (live thumbnails are iframes)
+- Node ≥ 18 for the CLI
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,330 @@
+#!/usr/bin/env node
+import { readFileSync as I, existsSync as w, readdirSync as N, realpathSync as q, writeFileSync as v } from "node:fs";
+import { join as g } from "node:path";
+import { fileURLToPath as G } from "node:url";
+import { createJiti as J } from "jiti";
+const M = { width: 1440, height: 900 };
+function E(t, n, e) {
+  e != null && t.append(n, String(e));
+}
+function W(t, n) {
+  const e = t.indexOf("#"), r = e >= 0 ? t.slice(e) : "", s = e >= 0 ? t.slice(0, e) : t, i = s.indexOf("?"), a = i >= 0 ? s.slice(0, i) : s, o = new URLSearchParams(i >= 0 ? s.slice(i + 1) : "");
+  for (const [c, h] of Object.entries(n.query))
+    if (o.delete(c), Array.isArray(h))
+      for (const m of h) E(o, c, m);
+    else
+      E(o, c, h);
+  const l = o.toString();
+  return `${a}${l ? `?${l}` : ""}${r}`;
+}
+function b(t) {
+  const n = [], e = /* @__PURE__ */ new Set(), r = (s, i, a) => {
+    for (const o of s) {
+      if (!o.path) throw new Error("[pubuilder] page.path는 필수입니다");
+      if (!o.title) throw new Error(`[pubuilder] "${o.path}"의 title이 없습니다`);
+      if (e.has(o.path)) throw new Error(`[pubuilder] 중복 path: ${o.path}`);
+      if (e.add(o.path), n.push({
+        id: o.path,
+        path: o.path,
+        title: o.title,
+        external: o.external ?? /^https?:\/\//.test(o.path),
+        parentId: i,
+        depth: a
+      }), o.variants?.length) {
+        if (o.external ?? /^https?:\/\//.test(o.path))
+          throw new Error(`[pubuilder] 외부 페이지에는 variants를 사용할 수 없습니다: ${o.path}`);
+        for (const l of o.variants) {
+          if (!l.title) throw new Error(`[pubuilder] "${o.path}" variant의 title이 없습니다`);
+          const c = W(o.path, l);
+          if (e.has(c)) throw new Error(`[pubuilder] 중복 path: ${c}`);
+          e.add(c), n.push({
+            id: c,
+            path: c,
+            title: l.title,
+            external: !1,
+            parentId: o.path,
+            depth: a + 1
+          });
+        }
+      }
+      o.children?.length && r(o.children, o.path, a + 1);
+    }
+  };
+  if (r(t.pages, null, 0), n.length === 0) throw new Error("[pubuilder] pages가 비어 있습니다");
+  return { nodes: n, viewport: t.viewport ?? M };
+}
+const p = "  ";
+function V(t) {
+  return t.split("/").map((n) => /^\[{1,2}\.{0,3}.*\]{1,2}$/.test(n) && n.startsWith("[") ? "1" : n).join("/");
+}
+function $(t) {
+  return JSON.stringify(t);
+}
+function k(t, n, e) {
+  const r = p.repeat(n), s = [];
+  t.path.includes("[") && s.push(`${r}// TODO: 샘플 경로로 교체 (예: ${V(t.path)})`);
+  const i = e.has(t.path) ? " // TODO: title 확인" : "";
+  if (!t.children?.length && !t.variants?.length && !t.external)
+    return s.push(`${r}{ path: ${$(t.path)}, title: ${$(t.title)} },${i}`), s;
+  if (s.push(`${r}{`), s.push(`${r}${p}path: ${$(t.path)},`), s.push(`${r}${p}title: ${$(t.title)},${i}`), t.external && s.push(`${r}${p}external: true,`), t.variants?.length) {
+    s.push(`${r}${p}variants: [`);
+    for (const o of t.variants)
+      s.push(
+        `${r}${p}${p}{ title: ${$(o.title)}, query: ${$(o.query)} },`
+      );
+    s.push(`${r}${p}],`);
+  }
+  if (t.children?.length) {
+    s.push(`${r}${p}children: [`);
+    for (const o of t.children) s.push(...k(o, n + 2, e));
+    s.push(`${r}${p}],`);
+  }
+  return s.push(`${r}},`), s;
+}
+function A(t, n = {}) {
+  const e = n.newPaths ?? /* @__PURE__ */ new Set(), r = [
+    'import { defineIA } from "pubuilder"',
+    "",
+    "export default defineIA({"
+  ];
+  t.viewport && r.push(`${p}viewport: ${$(t.viewport)},`), r.push(`${p}pages: [`);
+  for (const s of t.pages) r.push(...k(s, 2, e));
+  return r.push(`${p}],`), r.push("})"), r.push(""), r.join(`
+`);
+}
+function d(t) {
+  return t === "/" ? [] : t.replace(/^\//, "").split("/");
+}
+function z(t, n) {
+  return t.length >= n.length ? !1 : t.every((e, r) => e === n[r]);
+}
+function B(t) {
+  const n = [...t].sort((s, i) => {
+    const a = d(s.routePath).length - d(i.routePath).length;
+    return a !== 0 ? a : s.routePath.localeCompare(i.routePath);
+  }), e = [], r = [];
+  for (const s of n) {
+    const i = d(s.routePath), a = {
+      path: s.routePath,
+      title: s.title ?? i.at(-1) ?? "/"
+    };
+    let o;
+    for (const l of r)
+      z(l.segments, i) && (!o || l.segments.length > o.segments.length) && (o = l);
+    o ? (o.page.children ??= []).push(a) : e.push(a), r.push({ segments: i, page: a });
+  }
+  return e;
+}
+function R(t, n) {
+  const e = d(t), r = d(n);
+  for (let s = 0; s < r.length; s++) {
+    const i = r[s];
+    if (/^\[\[\.\.\..+\]\]$/.test(i))
+      return s <= e.length;
+    if (/^\[\.\.\..+\]$/.test(i))
+      return s < e.length;
+    if (s >= e.length) return !1;
+    if (!/^\[.+\]$/.test(i) && i !== e[s])
+      return !1;
+  }
+  return r.length === e.length;
+}
+function F(t, n = []) {
+  for (const e of t)
+    n.push({ page: e, segments: d(e.path) }), e.children && F(e.children, n);
+  return n;
+}
+function D(t) {
+  return t.external ?? /^https?:\/\//.test(t.path);
+}
+function X(t, n) {
+  const e = structuredClone(t), r = F(e.pages), s = r.filter((u) => !D(u.page)), i = (u) => s.some(
+    (f) => f.page.path === u.routePath || R(f.page.path, u.routePath)
+  ), a = n.filter((u) => !i(u)), o = (u) => n.some(
+    (f) => f.routePath === u.page.path || R(u.page.path, f.routePath)
+  ), l = s.filter((u) => !o(u)).map((u) => u.page.path), c = [], h = [...r], m = [...a].sort(
+    (u, f) => d(u.routePath).length - d(f.routePath).length
+  );
+  for (const u of m) {
+    const f = d(u.routePath), y = { path: u.routePath, title: u.title ?? f.at(-1) ?? "/" };
+    let P;
+    for (const x of h) {
+      if (D(x.page)) continue;
+      const S = x.segments;
+      S.length >= f.length || S.every((L, U) => L === f[U]) && (!P || S.length > P.segments.length) && (P = x);
+    }
+    P ? (P.page.children ??= []).push(y) : e.pages.push(y), h.push({ page: y, segments: f }), c.push(u.routePath);
+  }
+  return { config: e, added: c, removed: l };
+}
+const Q = /^page\.(tsx|jsx|ts|js)$/, Z = /^\(.+\)$/, H = /^\(\.{1,3}\)/;
+function O(t) {
+  for (const n of ["app", "src/app"])
+    if (w(g(t, n))) return g(t, n);
+  return null;
+}
+function K(t) {
+  const n = [];
+  for (const e of t) {
+    if (e.startsWith("@") || e.startsWith("_") || H.test(e)) return null;
+    Z.test(e) || n.push(e);
+  }
+  return `/${n.join("/")}`;
+}
+function Y(t) {
+  const n = t.match(
+    /export\s+const\s+metadata\s*(?::\s*[A-Za-z_$][\w$.]*\s*)?=\s*\{(?:[^{}]*?[,\s])?title\s*:\s*(['"])((?:\\.|(?!\1)[^\\])*)\1/
+  );
+  return n ? n[2] : void 0;
+}
+function _(t, n, e) {
+  for (const r of N(t, { withFileTypes: !0 }))
+    r.isDirectory() ? _(g(t, r.name), [...n, r.name], e) : Q.test(r.name) && e.push({ file: g(t, r.name), segments: n });
+}
+const tt = {
+  name: "next-app",
+  detect(t) {
+    return O(t) !== null;
+  },
+  scan(t) {
+    const n = O(t);
+    if (!n) return [];
+    const e = [];
+    _(n, [], e);
+    const r = [];
+    for (const { file: s, segments: i } of e) {
+      const a = K(i);
+      a !== null && r.push({
+        routePath: a,
+        isDynamic: /\[.+\]/.test(a),
+        title: Y(I(s, "utf8"))
+      });
+    }
+    return r;
+  }
+}, T = /\.(tsx|jsx|ts|js)$/, et = /* @__PURE__ */ new Set(["_app", "_document", "_error", "404", "500"]);
+function j(t) {
+  for (const n of ["pages", "src/pages"])
+    if (w(g(t, n))) return g(t, n);
+  return null;
+}
+function C(t, n, e) {
+  for (const r of N(t, { withFileTypes: !0 })) {
+    if (r.isDirectory()) {
+      if (n.length === 0 && r.name === "api") continue;
+      C(g(t, r.name), [...n, r.name], e);
+      continue;
+    }
+    if (!T.test(r.name)) continue;
+    const s = r.name.replace(T, "");
+    if (et.has(s)) continue;
+    const a = `/${(s === "index" ? n : [...n, s]).join("/")}`;
+    e.push({ routePath: a, isDynamic: /\[.+\]/.test(a) });
+  }
+}
+const nt = {
+  name: "next-pages",
+  detect(t) {
+    return j(t) !== null;
+  },
+  scan(t) {
+    const n = j(t);
+    if (!n) return [];
+    const e = [];
+    return C(n, [], e), e;
+  }
+}, rt = `import { defineIA } from "pubuilder"
+
+// pubuilder scan은 아직 이 프로젝트의 라우팅 방식을 지원하지 않아요 (v1은 Next.js 전용).
+// 아래 예시를 참고해 앱의 화면 구조를 직접 작성해주세요.
+// - path: 라우트 경로. 동적 라우트는 대표 샘플 경로 사용 (예: /notice/1)
+// - variants: query string으로 분기되는 화면 (자식 노드로 표시)
+// - external: 외부 URL은 링크아웃 노드로 표시
+export default defineIA({
+  pages: [
+    { path: "/login", title: "로그인" },
+    {
+      path: "/",
+      title: "홈",
+      children: [
+        { path: "/example", title: "예시 페이지" },
+      ],
+    },
+  ],
+})
+`, st = [tt, nt];
+function ot(t) {
+  const n = g(t, "package.json");
+  if (!w(n)) return !1;
+  try {
+    const e = JSON.parse(I(n, "utf8"));
+    return !!(e.dependencies?.next ?? e.devDependencies?.next);
+  } catch {
+    return console.warn("[pubuilder] package.json 파싱 실패 — JSON 문법을 확인해주세요"), !1;
+  }
+}
+function it(t) {
+  if (!ot(t)) return null;
+  const n = st.filter((s) => s.detect(t));
+  if (n.length === 0) return null;
+  const e = /* @__PURE__ */ new Map(), r = [];
+  for (const s of n)
+    for (const i of s.scan(t)) {
+      const a = e.get(i.routePath);
+      if (a) {
+        console.warn(`[pubuilder] path 충돌: ${i.routePath} (${a} 우선, ${s.name} 무시)`);
+        continue;
+      }
+      e.set(i.routePath, s.name), r.push(i);
+    }
+  return r;
+}
+async function at(t) {
+  const e = await J(import.meta.url).import(t, { default: !0 });
+  if (!e || !Array.isArray(e.pages))
+    throw new Error("[pubuilder] ia.config.ts의 default export에서 pages 배열을 찾지 못했어요");
+  return e;
+}
+async function ut(t, n) {
+  const e = it(t), r = g(t, "ia.config.ts");
+  if (e === null)
+    return console.error("[pubuilder] 지원하지 않는 라우팅 방식이에요. v1은 Next.js(App/Pages Router) 전용입니다."), !w(r) && !n.dryRun && (v(r, rt), console.log(`[pubuilder] 작성법 안내가 담긴 예시 템플릿을 생성했어요: ${r}`)), { kind: "unsupported" };
+  if (w(r)) {
+    const o = await at(r), { config: l, added: c, removed: h } = X(o, e);
+    b(l), n.dryRun || v(r, A(l, { newPaths: new Set(c) }));
+    for (const m of c) console.log(`[pubuilder] + 추가됨: ${m}`);
+    for (const m of h) console.log(`[pubuilder] - 라우트에서 사라짐 (config엔 유지): ${m}`);
+    return c.length === 0 && h.length === 0 && console.log("[pubuilder] 변경 없음"), n.dryRun && console.log("[pubuilder] (dry-run) 파일은 수정하지 않았어요"), { kind: "merged", added: c, removed: h };
+  }
+  const i = { pages: B(e) };
+  b(i);
+  const a = e.map((o) => o.routePath);
+  return n.dryRun ? console.log(`[pubuilder] (dry-run) 생성 예정: ${a.length}개 라우트. 파일은 수정하지 않았어요.`) : (v(r, A(i, { newPaths: new Set(a) })), console.log(`[pubuilder] ia.config.ts 초안을 생성했어요 (${a.length}개 라우트). title과 [param] 샘플 경로를 다듬어주세요.`)), { kind: "created", paths: a };
+}
+async function ct(t) {
+  const [n, ...e] = t;
+  if (n !== "scan")
+    return console.error("사용법: pubuilder scan [--dry-run]"), 1;
+  try {
+    return (await ut(process.cwd(), { dryRun: e.includes("--dry-run") })).kind === "unsupported" ? 1 : 0;
+  } catch (r) {
+    return console.error(`[pubuilder] 실패: ${r instanceof Error ? r.message : String(r)}`), 1;
+  }
+}
+function lt() {
+  const t = process.argv[1];
+  if (!t) return !1;
+  try {
+    return q(t) === G(import.meta.url);
+  } catch {
+    return !1;
+  }
+}
+lt() && ct(process.argv.slice(2)).then(
+  (t) => process.exit(t),
+  () => process.exit(1)
+);
+export {
+  ct as main,
+  ut as runScan
+};

package/dist/components/CanvasOverlay.d.ts

@@ -0,0 +1,4 @@
+import type { NormalizedIA } from '../config';
+export declare function CanvasOverlay({ ia }: {
+    ia: NormalizedIA;
+}): import("react").JSX.Element;

package/dist/components/Fab.d.ts

@@ -0,0 +1 @@
+export declare function Fab(): import("react").JSX.Element;

package/dist/components/PageMap.d.ts

@@ -0,0 +1,10 @@
+import type { IAConfig } from '../types';
+export interface PageMapProps {
+    config: IAConfig;
+    /**
+     * 렌더 여부. 기본 true. production 빌드에서는 이 값과 무관하게
+     * 자동으로 렌더하지 않는다 (dev 전용 안전장치).
+     */
+    enabled?: boolean;
+}
+export declare function PageMap({ config, enabled }: PageMapProps): import("react").ReactPortal | null;

package/dist/components/PageNode.d.ts

@@ -0,0 +1,13 @@
+import { type NodeProps } from '@xyflow/react';
+import type { IANode } from '../types';
+export interface PageNodeData {
+    page: IANode;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    thumbWidth: number;
+    bodyHeight: number;
+    [key: string]: unknown;
+}
+export declare const PageNode: import("react").NamedExoticComponent<NodeProps>;

package/dist/components/PageViewer.d.ts

@@ -0,0 +1,4 @@
+import type { NormalizedIA } from '../config';
+export declare function PageViewer({ ia }: {
+    ia: NormalizedIA;
+}): import("react").JSX.Element | null;

package/dist/components/SelectionPanel.d.ts

@@ -0,0 +1 @@
+export declare function SelectionPanel(): import("react").JSX.Element;

package/dist/config.d.ts

@@ -0,0 +1,12 @@
+import type { IAConfig, IANode } from './types';
+/** ia.config.ts 작성용 헬퍼 — 타입 추론만 제공 */
+export declare function defineIA(config: IAConfig): IAConfig;
+export interface NormalizedIA {
+    nodes: IANode[];
+    viewport: {
+        width: number;
+        height: number;
+    };
+}
+/** IAConfig 트리를 검증하고 평탄화한다 */
+export declare function normalizeIA(config: IAConfig): NormalizedIA;

package/dist/env.d.ts

@@ -0,0 +1,8 @@
+/**
+ * production 번들 여부. 소비 측 번들러(Next/Vite 등)가 process.env.NODE_ENV를
+ * 정적 치환하므로 앱 빌드 시 상수로 접힌다. 번들러 없는 환경(process 미정의)에서는
+ * false — 렌더를 막는 쪽이 아니라 허용하는 쪽이 안전한 기본값.
+ *
+ * 주의: 라이브러리 빌드가 이 표현식을 미리 치환하면 안 된다 — vite.config.ts 참고.
+ */
+export declare function isProductionEnv(): boolean;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { PageMap, type PageMapProps } from './components/PageMap';
+export { defineIA, normalizeIA, type NormalizedIA } from './config';
+export type { BlockSelection, Granularity, IAConfig, IANode, IAPage, } from './types';