jiplak 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wahyu Agus Arifin
+
+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.id.md

@@ -0,0 +1,312 @@
+<div align="center">
+
+# jiplak
+
+**Skeleton loading otomatis, dijiplak dari tampilan asli aplikasi React kamu.**
+
+Bungkus komponen. Jalankan satu perintah. Skeleton langsung sama persis.
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![React](https://img.shields.io/badge/React-%E2%89%A518-149eca?logo=react&logoColor=white)](https://react.dev)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ready-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+[![Sponsored by Lokio](https://img.shields.io/badge/sponsored%20by-Lokio-FF7A57)](https://lokio.link)
+
+[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20coffee-FFDD00?style=for-the-badge&logo=buymeacoffee&logoColor=black)](https://buymeacoffee.com/wahyuagusarifin)
+
+[English](./README.md) · Bahasa Indonesia
+
+</div>
+
+---
+
+## Kenapa jiplak?
+
+Skeleton yang digambar manual cepat tidak sesuai lagi begitu layout berubah.
+jiplak memotret komponen asli di browser dan menyimpan bentuknya. Kamu tidak
+perlu menggambar skeleton lagi.
+
+- **Tanpa menggambar.** Bentuk diambil dari DOM asli: teks, gambar, tombol.
+- **Tanpa daftar route.** CLI menjelajah aplikasi lewat link-nya sendiri.
+- **Responsif.** Dipotret di beberapa lebar layar, dipilih otomatis saat tampil.
+- **Satu file YAML.** `jiplak.yaml`, cukup satu baris untuk mulai.
+- **Mode gelap.** Mengikuti class `.dark` (konvensi Tailwind).
+- **Runtime kecil.** Satu komponen React; alat pemotret tidak ikut ke browser.
+
+## Daftar isi
+
+- [Mulai cepat](#mulai-cepat)
+- [Pertanyaan umum](#pertanyaan-umum)
+- [Konfigurasi](#konfigurasi)
+- [API](#api)
+- [Cara kerja](#cara-kerja)
+- [Sponsor](#sponsor)
+- [Pembuat](#pembuat)
+- [Lisensi](#lisensi)
+
+## Mulai cepat
+
+### 1. Install
+
+```bash
+npm install jiplak
+# atau
+bun add jiplak
+```
+
+### 2. Bungkus komponen yang menunggu data
+
+```tsx
+import { Skeleton } from 'jiplak/react'
+
+function Profil() {
+  const { data, isLoading } = useProfil()
+
+  return (
+    <Skeleton name="profil-card" loading={isLoading}>
+      <ProfilCard user={data} />
+    </Skeleton>
+  )
+}
+```
+
+### 3. Buat `jiplak.yaml` di root project
+
+```yaml
+url: http://localhost:3000
+```
+
+### 4. Jalankan aplikasi, lalu potret
+
+```bash
+npm run dev
+```
+
+Di terminal lain:
+
+```bash
+npx jiplak build
+```
+
+### 5. Import registry hasil build sekali saja
+
+Import dari komponen client yang selalu dimuat, misalnya providers:
+
+```tsx
+'use client'
+import './bones/registry'
+```
+
+Selesai. Saat `loading` bernilai `true`, skeleton tampil otomatis.
+
+## Pertanyaan umum
+
+<details>
+<summary><b>Apakah setiap screen harus diberi <code>&lt;Skeleton&gt;</code>?</b></summary>
+
+Tidak. Bungkus hanya bagian yang menunggu data, misalnya card, list, atau
+tabel. Bagian statis seperti header dan menu tidak perlu. Satu screen bisa
+punya beberapa `<Skeleton>` dengan `name` yang berbeda.
+
+</details>
+
+<details>
+<summary><b>Apakah skeleton benar-benar dibuat otomatis?</b></summary>
+
+Ya. `jiplak build` menjelajah aplikasi lewat link, menemukan setiap
+`<Skeleton>`, lalu mencatat bentuknya. Tugas kamu hanya membungkus komponen.
+
+</details>
+
+<details>
+<summary><b>Kapan harus menjalankan <code>jiplak build</code> lagi?</b></summary>
+
+Setelah layout komponen yang dibungkus berubah, atau setelah menambah
+`<Skeleton>` baru. Commit folder `src/bones/` supaya tim tidak perlu build
+ulang.
+
+</details>
+
+<details>
+<summary><b>Bagaimana sebelum build pertama?</b></summary>
+
+Aplikasi berjalan normal. Komponen tampil seperti biasa, hanya tanpa
+skeleton.
+
+</details>
+
+<details>
+<summary><b>Komponen saya kosong tanpa data.</b></summary>
+
+Beri contoh isi lewat `fixture`. jiplak memotret `fixture`, bukan komponen
+aslinya:
+
+```tsx
+<Skeleton name="profil-card" loading={isLoading} fixture={<ProfilCard user={contohUser} />}>
+  <ProfilCard user={data} />
+</Skeleton>
+```
+
+</details>
+
+<details>
+<summary><b>Ada halaman yang tidak ketemu.</b></summary>
+
+Penjelajah hanya menemukan halaman yang punya link dari halaman lain.
+Tambahkan halaman tanpa link sebagai titik awal:
+
+```yaml
+routes:
+  - /
+  - /pengaturan/profil
+```
+
+</details>
+
+<details>
+<summary><b>Ada halaman yang tidak boleh dikunjungi.</b></summary>
+
+Link logout dan file (pdf, gambar, csv) selalu dilewati. Untuk path lain:
+
+```yaml
+ignore:
+  - /admin
+```
+
+</details>
+
+<details>
+<summary><b>Build berhenti di <code>maxPages</code>.</b></summary>
+
+Penjelajah berhenti di 50 halaman supaya route dinamis (`/post/1`,
+`/post/2`, …) tidak dijelajah tanpa akhir. Naikkan bila perlu:
+
+```yaml
+maxPages: 200
+```
+
+</details>
+
+<details>
+<summary><b>Halaman saya butuh login.</b></summary>
+
+Kirim cookie sesi:
+
+```yaml
+cookies:
+  - session=isi-cookie-kamu
+```
+
+</details>
+
+<details>
+<summary><b>Browser tidak ditemukan.</b></summary>
+
+Pakai Chrome yang sudah terpasang:
+
+```yaml
+channel: chrome
+```
+
+Atau unduh Chromium sekali:
+
+```bash
+npx playwright install chromium
+```
+
+</details>
+
+## Konfigurasi
+
+Semua key opsional. Nilai di bawah adalah default. Key yang salah ketik
+langsung ditolak dengan pesan error.
+
+```yaml
+# pemotretan
+url: http://localhost:3000       # alamat aplikasi yang berjalan
+routes: [/]                      # titik awal jelajah
+ignore: []                       # path yang tidak dikunjungi
+maxPages: 50                     # batas jumlah halaman
+breakpoints: [375, 768, 1280]    # lebar layar yang dipotret
+out: ./src/bones                 # folder hasil
+wait: 800                        # jeda (ms) setelah halaman dimuat
+channel: chrome                  # opsional: pakai Chrome yang terpasang
+cookies: []                      # opsional: name=value
+
+# tampilan (props di <Skeleton> menimpa nilai ini)
+animate: pulse                   # pulse | shimmer | solid
+color: "#ececec"                 # mode terang
+darkColor: "#262626"             # mode gelap (class .dark)
+shimmerColor: "#f7f7f7"
+darkShimmerColor: "#323232"
+speed: 1.6s
+```
+
+## API
+
+### `<Skeleton>`
+
+| Prop | Wajib | Fungsi |
+| --- | --- | --- |
+| `name` | ya | Nama unik: huruf, angka, `-`, `_` |
+| `loading` | ya | `true` saat data belum datang |
+| `fixture` | tidak | Contoh isi yang dipotret saat build |
+| `animate`, `color`, `darkColor`, `shimmerColor`, `darkShimmerColor`, `speed` | tidak | Menimpa `jiplak.yaml` untuk skeleton ini saja |
+| `options` | tidak | `{ exclude: ['.badge'] }` melewati elemen; `{ leafTags: ['section'] }` menjadikan satu tag satu kotak |
+| `bones` | tidak | Data skeleton langsung, tanpa registry |
+| `className` | tidak | Class untuk elemen pembungkus |
+
+### Fungsi
+
+| Fungsi | Kegunaan |
+| --- | --- |
+| `registerBones(map)` | Mendaftarkan bones per nama. Dipanggil oleh registry hasil build. |
+| `configureJiplak(theme)` | Mengatur tampilan global. Dipanggil oleh registry dengan nilai dari YAML. |
+
+### CLI
+
+```bash
+jiplak build [url] [--config jiplak.yaml]
+```
+
+## Cara kerja
+
+1. `jiplak build` membuka aplikasi di browser tanpa tampilan, mulai dari
+   `routes`, lalu mengikuti link di domain yang sama.
+2. Di setiap lebar layar, setiap `<Skeleton>` dipotret. Teks, gambar, dan
+   tombol dicatat sebagai kotak ("bones").
+3. Kotak disimpan ke `src/bones/<name>.bones.json`, ditambah `registry.ts`
+   yang memuatnya.
+4. Saat `loading`, kotak digambar di atas komponen yang disembunyikan,
+   memakai lebar layar yang paling cocok dengan lebar container.
+
+## Pengembangan
+
+```bash
+bun install
+bun test
+bun run typecheck
+bun run build
+```
+
+Issue dan pull request terbuka di
+[GitHub](https://github.com/ItPohgero/jiplak/issues).
+
+## Sponsor
+
+<a href="https://lokio.link">
+  <img src="https://raw.githubusercontent.com/ItPohgero/jiplak/main/.github/assets/lokio.png" alt="Lokio" width="72" />
+</a>
+
+jiplak disponsori oleh **[Lokio](https://lokio.link)**.
+
+Suka jiplak? Dukung pengembangannya:
+
+[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20coffee-FFDD00?style=for-the-badge&logo=buymeacoffee&logoColor=black)](https://buymeacoffee.com/wahyuagusarifin)
+
+## Pembuat
+
+**Wahyu Agus Arifin** · [@ItPohgero](https://github.com/ItPohgero)
+
+## Lisensi
+
+[MIT](./LICENSE) © 2026 Wahyu Agus Arifin

package/README.md

@@ -1,3 +1,313 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# jiplak
+
+**Pixel-perfect skeleton loading screens, auto-captured from your real React UI.**
+
+Wrap a component. Run one command. Get a skeleton that matches it exactly.
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![React](https://img.shields.io/badge/React-%E2%89%A518-149eca?logo=react&logoColor=white)](https://react.dev)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ready-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org)
+[![Sponsored by Lokio](https://img.shields.io/badge/sponsored%20by-Lokio-FF7A57)](https://lokio.link)
+
+[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20coffee-FFDD00?style=for-the-badge&logo=buymeacoffee&logoColor=black)](https://buymeacoffee.com/wahyuagusarifin)
+
+English · [Bahasa Indonesia](./README.id.md)
+
+</div>
+
+---
+
+## Why jiplak?
+
+Hand-drawn skeletons drift out of sync with the real UI the moment a layout
+changes. jiplak ("to trace" in Indonesian) traces your rendered components in
+a real browser and stores their exact shape. You never draw a skeleton again.
+
+- **Zero drawing.** Bones come from the real DOM: text, images, buttons.
+- **Zero route list.** The CLI crawls your app through its own links.
+- **Responsive.** Captured at several screen widths; the right one is picked at runtime.
+- **One YAML file.** `jiplak.yaml`, one line to start.
+- **Dark mode.** Follows the `.dark` class (Tailwind convention).
+- **Tiny runtime.** One React component; the capture tooling never ships to the browser.
+
+## Contents
+
+- [Quick start](#quick-start)
+- [FAQ](#faq)
+- [Configuration](#configuration)
+- [API](#api)
+- [How it works](#how-it-works)
+- [Sponsor](#sponsor)
+- [Author](#author)
+- [License](#license)
+
+## Quick start
+
+### 1. Install
+
+```bash
+npm install jiplak
+# or
+bun add jiplak
+```
+
+### 2. Wrap components that wait for data
+
+```tsx
+import { Skeleton } from 'jiplak/react'
+
+function Profile() {
+  const { data, isLoading } = useProfile()
+
+  return (
+    <Skeleton name="profile-card" loading={isLoading}>
+      <ProfileCard user={data} />
+    </Skeleton>
+  )
+}
+```
+
+### 3. Add `jiplak.yaml` to your project root
+
+```yaml
+url: http://localhost:3000
+```
+
+### 4. Start your app, then capture
+
+```bash
+npm run dev
+```
+
+In a second terminal:
+
+```bash
+npx jiplak build
+```
+
+### 5. Import the generated registry once
+
+Import it from a client component that always loads, such as your providers:
+
+```tsx
+'use client'
+import './bones/registry'
+```
+
+Done. While `loading` is `true`, the skeleton shows automatically.
+
+## FAQ
+
+<details>
+<summary><b>Do I wrap every screen?</b></summary>
+
+No. Wrap only the parts that wait for data, such as cards, lists, or tables.
+Static parts like headers and menus need nothing. One screen can hold several
+`<Skeleton>` components with different names.
+
+</details>
+
+<details>
+<summary><b>Is the skeleton really generated automatically?</b></summary>
+
+Yes. `jiplak build` crawls your app through its links, finds every
+`<Skeleton>`, and records its shape. Your only job is to wrap components.
+
+</details>
+
+<details>
+<summary><b>When do I run <code>jiplak build</code> again?</b></summary>
+
+After a wrapped component changes its layout, or after you add a new
+`<Skeleton>`. Commit the `src/bones/` folder so your team does not need to
+rebuild.
+
+</details>
+
+<details>
+<summary><b>What happens before the first build?</b></summary>
+
+Your app works as usual. Components render normally, just without a
+skeleton.
+
+</details>
+
+<details>
+<summary><b>My component is empty without data.</b></summary>
+
+Pass sample content through `fixture`. jiplak captures the fixture instead of
+the real children:
+
+```tsx
+<Skeleton name="profile-card" loading={isLoading} fixture={<ProfileCard user={sampleUser} />}>
+  <ProfileCard user={data} />
+</Skeleton>
+```
+
+</details>
+
+<details>
+<summary><b>A page was not found.</b></summary>
+
+The crawler finds only pages that another page links to. Add unlinked pages
+as extra start points:
+
+```yaml
+routes:
+  - /
+  - /settings/profile
+```
+
+</details>
+
+<details>
+<summary><b>Some pages must never be visited.</b></summary>
+
+Logout links and files (pdf, images, csv) are always skipped. Skip other
+paths with `ignore`:
+
+```yaml
+ignore:
+  - /admin
+```
+
+</details>
+
+<details>
+<summary><b>The build stopped at <code>maxPages</code>.</b></summary>
+
+The crawler stops at 50 pages so dynamic routes (`/post/1`, `/post/2`, …)
+cannot run forever. Raise the limit if needed:
+
+```yaml
+maxPages: 200
+```
+
+</details>
+
+<details>
+<summary><b>My pages need a login.</b></summary>
+
+Send a session cookie:
+
+```yaml
+cookies:
+  - session=your-session-cookie
+```
+
+</details>
+
+<details>
+<summary><b>Browser not found.</b></summary>
+
+Use the Chrome you already have:
+
+```yaml
+channel: chrome
+```
+
+Or download Chromium once:
+
+```bash
+npx playwright install chromium
+```
+
+</details>
+
+## Configuration
+
+Every key is optional. Values below are the defaults. Unknown keys fail with
+a clear error, so typos never pass silently.
+
+```yaml
+# capture
+url: http://localhost:3000       # your running app
+routes: [/]                      # crawl start points
+ignore: []                       # path prefixes never visited
+maxPages: 50                     # crawl limit
+breakpoints: [375, 768, 1280]    # screen widths to capture
+out: ./src/bones                 # output folder
+wait: 800                        # ms to wait after page load
+channel: chrome                  # optional: use installed Chrome
+cookies: []                      # optional: name=value
+
+# look (props on <Skeleton> override these)
+animate: pulse                   # pulse | shimmer | solid
+color: "#ececec"                 # light mode
+darkColor: "#262626"             # dark mode (.dark class)
+shimmerColor: "#f7f7f7"
+darkShimmerColor: "#323232"
+speed: 1.6s
+```
+
+## API
+
+### `<Skeleton>`
+
+| Prop | Required | Description |
+| --- | --- | --- |
+| `name` | yes | Unique name: letters, digits, `-`, `_` |
+| `loading` | yes | `true` while data is loading |
+| `fixture` | no | Sample content captured at build time |
+| `animate`, `color`, `darkColor`, `shimmerColor`, `darkShimmerColor`, `speed` | no | Override `jiplak.yaml` for this skeleton |
+| `options` | no | `{ exclude: ['.badge'] }` skips elements; `{ leafTags: ['section'] }` turns a tag into one bone |
+| `bones` | no | Bones passed directly instead of the registry |
+| `className` | no | Class for the wrapper element |
+
+### Functions
+
+| Function | Description |
+| --- | --- |
+| `registerBones(map)` | Register bones by name. The generated registry calls it. |
+| `configureJiplak(theme)` | Set global look defaults. The generated registry calls it with your YAML values. |
+
+### CLI
+
+```bash
+jiplak build [url] [--config jiplak.yaml]
+```
+
+## How it works
+
+1. `jiplak build` opens your app in a headless browser, starting at
+   `routes`, and follows links on the same origin.
+2. At each breakpoint, every `<Skeleton>` on the page is captured. Text
+   blocks, images, and controls become rectangles ("bones").
+3. Bones are saved to `src/bones/<name>.bones.json`, plus a `registry.ts`
+   that loads them.
+4. At runtime, while `loading` is `true`, the bones are drawn over the hidden
+   component, using the breakpoint that fits the container width.
+
+## Development
+
+```bash
+bun install
+bun test
+bun run typecheck
+bun run build
+```
+
+Issues and pull requests are welcome on
+[GitHub](https://github.com/ItPohgero/jiplak/issues).
+
+## Sponsor
+
+<a href="https://lokio.link">
+  <img src="https://raw.githubusercontent.com/ItPohgero/jiplak/main/.github/assets/lokio.png" alt="Lokio" width="72" />
+</a>
+
+jiplak is proudly sponsored by **[Lokio](https://lokio.link)**.
+
+Like jiplak? Support its development:
+
+[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20coffee-FFDD00?style=for-the-badge&logo=buymeacoffee&logoColor=black)](https://buymeacoffee.com/wahyuagusarifin)
+
+## Author
+
+**Wahyu Agus Arifin** · [@ItPohgero](https://github.com/ItPohgero)
+
+## License
+
+[MIT](./LICENSE) © 2026 Wahyu Agus Arifin

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import { mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { chromium } from 'playwright';
+import { crawlPaths, loadConfig, registrySource, themeOf, validName } from './config.js';
+const USAGE = `Usage: jiplak build [url] [--config jiplak.yaml]
+
+Starts at each route in jiplak.yaml, follows same-origin links, captures
+every <Skeleton name="..."> at every breakpoint, and writes
+<out>/<name>.bones.json plus <out>/registry.ts.`;
+const { positionals, values } = parseArgs({
+    allowPositionals: true,
+    options: { config: { type: 'string', default: 'jiplak.yaml' }, help: { type: 'boolean', short: 'h' } },
+});
+if (values.help || positionals[0] !== 'build') {
+    console.log(USAGE);
+    process.exit(values.help ? 0 : 1);
+}
+let configText = '';
+try {
+    configText = readFileSync(resolve(values.config), 'utf8');
+}
+catch {
+    console.warn(`jiplak: ${values.config} not found, using defaults`);
+}
+const config = loadConfig(configText);
+const origin = (positionals[1] ?? config.url).replace(/\/$/, '');
+const out = resolve(config.out);
+const browser = await chromium.launch({ channel: config.channel });
+const context = await browser.newContext();
+await context.addInitScript(() => {
+    window.__JIPLAK_BUILD = true;
+});
+if (config.cookies.length > 0) {
+    await context.addCookies(config.cookies.map(c => {
+        const i = c.indexOf('=');
+        return { name: c.slice(0, i), value: c.slice(i + 1), url: origin };
+    }));
+}
+const captured = {};
+const page = await context.newPage();
+const queue = [...new Set(config.routes)];
+const seen = new Set(queue);
+try {
+    for (let route = queue.shift(); route !== undefined; route = queue.shift()) {
+        for (const [i, width] of config.breakpoints.entries()) {
+            await page.setViewportSize({ width, height: 900 });
+            await page.goto(origin + route, { waitUntil: 'load' });
+            await page.waitForTimeout(config.wait);
+            if (i === 0) {
+                if (!page.url().startsWith(origin)) {
+                    console.warn(`  ${route}: redirected off-origin to ${page.url()}, skipped`);
+                    break;
+                }
+                const hrefs = await page.$$eval('a[href]', as => as.map(a => a.href));
+                for (const path of crawlPaths(hrefs, origin, config.ignore)) {
+                    if (seen.size >= config.maxPages)
+                        break;
+                    if (!seen.has(path)) {
+                        seen.add(path);
+                        queue.push(path);
+                    }
+                }
+            }
+            const found = await page.evaluate(() => {
+                const snap = window.__JIPLAK_SNAPSHOT;
+                if (!snap)
+                    return null;
+                const result = {};
+                for (const el of document.querySelectorAll('[data-jiplak]')) {
+                    const opts = el.dataset.jiplakOptions ? JSON.parse(el.dataset.jiplakOptions) : {};
+                    result[el.dataset.jiplak] = snap(el, opts);
+                }
+                return result;
+            });
+            if (!found) {
+                continue; // page does not load jiplak/react
+            }
+            for (const [name, capture] of Object.entries(found)) {
+                if (!validName(name)) {
+                    console.warn(`  skip "${name}": use letters, digits, - or _`);
+                    continue;
+                }
+                ;
+                (captured[name] ??= {})[width] = capture;
+            }
+            if (Object.keys(found).length > 0)
+                console.log(`  ${route} @${width}: ${Object.keys(found).join(', ')}`);
+        }
+    }
+}
+finally {
+    await browser.close();
+}
+mkdirSync(out, { recursive: true });
+for (const [name, bones] of Object.entries(captured)) {
+    writeFileSync(join(out, `${name}.bones.json`), JSON.stringify(bones) + '\n');
+}
+// Skeletons not visited this run keep their previous bones.
+const names = readdirSync(out)
+    .filter(f => f.endsWith('.bones.json'))
+    .map(f => f.slice(0, -'.bones.json'.length));
+writeFileSync(join(out, 'registry.ts'), registrySource(names, themeOf(config)));
+if (seen.size >= config.maxPages)
+    console.warn(`jiplak: stopped at maxPages (${config.maxPages}); raise it in jiplak.yaml if pages were missed`);
+console.log(`jiplak: ${seen.size} page(s) crawled, ${Object.keys(captured).length} skeleton(s) captured, ${names.length} in ${config.out}/registry.ts`);

package/dist/config.d.ts

@@ -0,0 +1,30 @@
+import type { Theme } from './core.js';
+export interface Config extends Theme {
+    /** Origin of the running app, e.g. http://localhost:3000. */
+    url: string;
+    /** Start paths. Same-origin links found on each page are followed too. */
+    routes: string[];
+    /** Upper bound on pages visited, so dynamic routes (/item/1, /item/2, ...) cannot run forever. */
+    maxPages: number;
+    /** Path prefixes never visited, e.g. /admin. Logout links are always skipped. */
+    ignore: string[];
+    /** Viewport widths captured per route. */
+    breakpoints: number[];
+    /** Output directory for `<name>.bones.json` and `registry.ts`. */
+    out: string;
+    /** ms to wait after load before capture. */
+    wait: number;
+    /** Playwright browser channel, e.g. `chrome` to reuse installed Chrome instead of downloading Chromium. */
+    channel?: string;
+    /** Cookies sent with every page, `name=value`. */
+    cookies: string[];
+}
+/** Parse and validate jiplak.yaml text; unknown keys are rejected so typos surface. */
+export declare function loadConfig(text: string): Config;
+export declare function themeOf(config: Config): Theme;
+/** Source of the generated registry: imports every bones file and applies the yaml theme. */
+export declare function registrySource(names: string[], theme: Theme): string;
+/** Same-origin paths from link hrefs worth crawling: no query/hash, no logout, no files, no ignored prefixes. */
+export declare function crawlPaths(hrefs: string[], origin: string, ignore: string[]): string[];
+/** Skeleton names become file names; keep them safe for the filesystem and imports. */
+export declare const validName: (name: string) => boolean;

package/dist/config.js

@@ -0,0 +1,108 @@
+import { parse } from 'yaml';
+const DEFAULTS = {
+    url: 'http://localhost:3000',
+    routes: ['/'],
+    maxPages: 50,
+    ignore: [],
+    breakpoints: [375, 768, 1280],
+    out: './src/bones',
+    wait: 800,
+    cookies: [],
+};
+const THEME_KEYS = ['color', 'darkColor', 'shimmerColor', 'darkShimmerColor', 'speed'];
+const ANIMATIONS = ['pulse', 'shimmer', 'solid'];
+function fail(msg) {
+    throw new Error(`jiplak.yaml: ${msg}`);
+}
+const isStrings = (v) => Array.isArray(v) && v.every(s => typeof s === 'string');
+/** Parse and validate jiplak.yaml text; unknown keys are rejected so typos surface. */
+export function loadConfig(text) {
+    const raw = parse(text) ?? {};
+    if (typeof raw !== 'object' || Array.isArray(raw))
+        fail('root must be a mapping');
+    const c = { ...DEFAULTS, ...raw };
+    const known = new Set([...Object.keys(DEFAULTS), ...THEME_KEYS, 'animate', 'channel']);
+    for (const key of Object.keys(c))
+        if (!known.has(key))
+            fail(`unknown key "${key}"`);
+    if (typeof c.url !== 'string' || !/^https?:\/\//.test(c.url))
+        fail('url must start with http:// or https://');
+    if (!isStrings(c.routes) || c.routes.length === 0)
+        fail('routes must be a non-empty list of paths');
+    if (c.routes.some(r => !r.startsWith('/')))
+        fail('every route must start with "/"');
+    if (!Number.isInteger(c.maxPages) || c.maxPages < 1)
+        fail('maxPages must be a positive integer');
+    if (!isStrings(c.ignore) || c.ignore.some(r => !r.startsWith('/')))
+        fail('ignore must be a list of paths starting with "/"');
+    const bps = c.breakpoints;
+    if (!Array.isArray(bps) || bps.length === 0 || !bps.every(b => Number.isInteger(b) && b > 0))
+        fail('breakpoints must be a non-empty list of positive integers');
+    if (typeof c.out !== 'string' || c.out === '')
+        fail('out must be a path');
+    if (typeof c.wait !== 'number' || c.wait < 0)
+        fail('wait must be a number >= 0');
+    if (c.channel !== undefined && typeof c.channel !== 'string')
+        fail('channel must be a string');
+    if (!isStrings(c.cookies) || c.cookies.some(s => !s.includes('=')))
+        fail('cookies must be a list of name=value');
+    for (const key of THEME_KEYS)
+        if (c[key] !== undefined && typeof c[key] !== 'string')
+            fail(`${key} must be a string`);
+    if (c.animate !== undefined && !ANIMATIONS.includes(c.animate))
+        fail(`animate must be one of ${ANIMATIONS.join(', ')}`);
+    return c;
+}
+export function themeOf(config) {
+    const theme = {};
+    for (const key of THEME_KEYS)
+        if (config[key] !== undefined)
+            theme[key] = config[key];
+    if (config.animate)
+        theme.animate = config.animate;
+    return theme;
+}
+/** Source of the generated registry: imports every bones file and applies the yaml theme. */
+export function registrySource(names, theme) {
+    const sorted = [...names].sort();
+    return [
+        '// Generated by `jiplak build`. Do not edit.',
+        "'use client'",
+        '',
+        "import { configureJiplak, registerBones, type Bones } from 'jiplak/react'",
+        ...sorted.map((n, i) => `import b${i} from './${n}.bones.json'`),
+        '',
+        `configureJiplak(${JSON.stringify(theme)})`,
+        '',
+        'registerBones({',
+        ...sorted.map((n, i) => `  ${JSON.stringify(n)}: b${i} as unknown as Bones,`),
+        '})',
+        '',
+    ].join('\n');
+}
+// Visiting these with a GET can end the session or download files.
+const NEVER_VISIT = /(log-?out|sign-?out|keluar)(\/|$)|\.(pdf|zip|png|jpe?g|gif|svg|webp|mp4|csv|xlsx?)$/i;
+/** Same-origin paths from link hrefs worth crawling: no query/hash, no logout, no files, no ignored prefixes. */
+export function crawlPaths(hrefs, origin, ignore) {
+    const paths = new Set();
+    for (const href of hrefs) {
+        let u;
+        try {
+            u = new URL(href, origin);
+        }
+        catch {
+            continue;
+        }
+        if (u.origin !== new URL(origin).origin)
+            continue;
+        const path = u.pathname.replace(/(.)\/$/, '$1');
+        if (NEVER_VISIT.test(path))
+            continue;
+        if (ignore.some(p => path === p || path.startsWith(p.replace(/\/$/, '') + '/')))
+            continue;
+        paths.add(path);
+    }
+    return [...paths];
+}
+/** Skeleton names become file names; keep them safe for the filesystem and imports. */
+export const validName = (name) => /^[a-z0-9][a-z0-9-_]*$/i.test(name);

package/dist/core.d.ts

@@ -0,0 +1,27 @@
+/** One placeholder rect: x and w are % of capture width, y and h are px, r is border-radius. */
+export type Bone = [x: number, y: number, w: number, h: number, r: number | string];
+/** Layout of one `<Skeleton>` captured at one viewport width. */
+export interface Capture {
+    width: number;
+    height: number;
+    bones: Bone[];
+}
+/** Captures keyed by viewport width, as written to `<name>.bones.json`. */
+export type Bones = Record<string, Capture>;
+export type Animate = 'pulse' | 'shimmer' | 'solid';
+/** Runtime look, shared by jiplak.yaml and `configureJiplak`. */
+export interface Theme {
+    color?: string;
+    darkColor?: string;
+    shimmerColor?: string;
+    darkShimmerColor?: string;
+    animate?: Animate;
+    speed?: string;
+}
+/**
+ * Pick the capture whose captured container width is nearest to `width`.
+ * Compares container to container (keys are viewport widths, and a container is
+ * usually narrower than its viewport). Nearest, not floor, so a scrollbar that
+ * shaves a few px off the live container still picks the matching capture.
+ */
+export declare function pickCapture(bones: Bones, width: number): Capture | undefined;

package/dist/core.js

@@ -0,0 +1,14 @@
+/**
+ * Pick the capture whose captured container width is nearest to `width`.
+ * Compares container to container (keys are viewport widths, and a container is
+ * usually narrower than its viewport). Nearest, not floor, so a scrollbar that
+ * shaves a few px off the live container still picks the matching capture.
+ */
+export function pickCapture(bones, width) {
+    let best;
+    for (const c of Object.values(bones)) {
+        if (!best || Math.abs(c.width - width) < Math.abs(best.width - width))
+            best = c;
+    }
+    return best;
+}

package/dist/react.d.ts

@@ -0,0 +1,29 @@
+import { type ReactNode } from 'react';
+import { type Bones, type Theme } from './core.js';
+import { snapshot, type SnapshotOptions } from './snapshot.js';
+export type { Bone, Bones, Capture, Theme, Animate } from './core.js';
+export type { SnapshotOptions } from './snapshot.js';
+export { snapshot };
+declare global {
+    interface Window {
+        __JIPLAK_BUILD?: boolean;
+        __JIPLAK_SNAPSHOT?: typeof snapshot;
+    }
+}
+/** Called by the generated registry; may also be called by hand. */
+export declare function registerBones(map: Record<string, Bones>): void;
+/** Global look defaults; jiplak.yaml values land here through the generated registry. */
+export declare function configureJiplak(next: Theme): void;
+export interface SkeletonProps extends Theme {
+    /** Key used by the CLI to capture and by the runtime to look up bones. */
+    name: string;
+    loading: boolean;
+    children?: ReactNode;
+    /** Rendered instead of children while the CLI captures (mock data, no auth). */
+    fixture?: ReactNode;
+    /** Bones passed directly instead of resolved from the registry. */
+    bones?: Bones;
+    options?: SnapshotOptions;
+    className?: string;
+}
+export declare function Skeleton({ name, loading, children, fixture, bones, options, className, ...look }: SkeletonProps): import("react").JSX.Element;

package/dist/react.js

@@ -0,0 +1,77 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { pickCapture } from './core.js';
+import { snapshot } from './snapshot.js';
+export { snapshot };
+const isBuild = typeof window !== 'undefined' && window.__JIPLAK_BUILD === true;
+if (isBuild)
+    window.__JIPLAK_SNAPSHOT = snapshot;
+const registry = new Map();
+let theme = {
+    color: '#ececec',
+    darkColor: '#262626',
+    shimmerColor: '#f7f7f7',
+    darkShimmerColor: '#323232',
+    animate: 'pulse',
+    speed: '1.6s',
+};
+/** Called by the generated registry; may also be called by hand. */
+export function registerBones(map) {
+    for (const [name, bones] of Object.entries(map))
+        registry.set(name, bones);
+}
+/** Global look defaults; jiplak.yaml values land here through the generated registry. */
+export function configureJiplak(next) {
+    theme = { ...theme, ...next };
+}
+const KEYFRAMES = '@keyframes jiplak-pulse{50%{opacity:.45}}' +
+    '@keyframes jiplak-shimmer{from{background-position:200% 0}to{background-position:-200% 0}}';
+export function Skeleton({ name, loading, children, fixture, bones, options, className, ...look }) {
+    const ref = useRef(null);
+    const [width, setWidth] = useState(0);
+    const [dark, setDark] = useState(false);
+    useEffect(() => {
+        const el = ref.current;
+        if (!el || isBuild)
+            return;
+        const ro = new ResizeObserver(([entry]) => setWidth(Math.round(entry.contentRect.width)));
+        ro.observe(el);
+        const checkDark = () => setDark(!!el.closest('.dark'));
+        checkDark();
+        const mo = new MutationObserver(checkDark);
+        mo.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] });
+        return () => {
+            ro.disconnect();
+            mo.disconnect();
+        };
+    }, []);
+    if (isBuild) {
+        return (_jsx("div", { ref: ref, className: className, "data-jiplak": name, "data-jiplak-options": options && JSON.stringify(options), children: fixture ?? children }));
+    }
+    const t = { ...theme, ...look };
+    const source = bones ?? registry.get(name);
+    const capture = loading && source && width > 0 ? pickCapture(source, width) : undefined;
+    const color = dark ? t.darkColor : t.color;
+    const highlight = dark ? t.darkShimmerColor : t.shimmerColor;
+    return (_jsxs("div", { ref: ref, className: className, "aria-busy": loading || undefined, style: { position: 'relative', minHeight: capture?.height }, children: [_jsx("div", { style: capture ? { visibility: 'hidden' } : undefined, children: children }), capture && (_jsxs("div", { "aria-hidden": true, style: { position: 'absolute', inset: 0, overflow: 'hidden', pointerEvents: 'none' }, children: [_jsx("style", { children: KEYFRAMES }), capture.bones.map(([x, y, w, h, r], i) => {
+                        const style = {
+                            position: 'absolute',
+                            left: `${x}%`,
+                            top: y,
+                            // Circles keep their shape when the container is wider or narrower than at capture.
+                            width: r === '50%' ? h : `${w}%`,
+                            height: h,
+                            borderRadius: r,
+                            background: color,
+                        };
+                        if (t.animate === 'pulse')
+                            style.animation = `jiplak-pulse ${t.speed} ease-in-out infinite`;
+                        if (t.animate === 'shimmer') {
+                            style.background = `linear-gradient(110deg, ${color} 30%, ${highlight} 50%, ${color} 70%)`;
+                            style.backgroundSize = '200% 100%';
+                            style.animation = `jiplak-shimmer ${t.speed} linear infinite`;
+                        }
+                        return _jsx("div", { style: style }, i);
+                    })] }))] }));
+}

package/dist/snapshot.d.ts

@@ -0,0 +1,13 @@
+import type { Capture } from './core.js';
+/** Per-skeleton capture tuning, passed as `<Skeleton options>`. */
+export interface SnapshotOptions {
+    /** Extra tags captured as one bone while they hold only inline content. */
+    leafTags?: string[];
+    /** CSS selectors skipped together with their descendants. */
+    exclude?: string[];
+}
+/**
+ * Walk the rendered children of `root` and record every visible leaf
+ * (text block, media, form control, childless element) as a bone.
+ */
+export declare function snapshot(root: Element, options?: SnapshotOptions): Capture;

package/dist/snapshot.js

@@ -0,0 +1,50 @@
+const LEAF_TAGS = ['p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'li', 'td', 'th', 'label'];
+const ATOMIC = new Set(['img', 'svg', 'video', 'canvas', 'picture', 'input', 'button', 'textarea', 'select']);
+const pct = (v, total) => (total > 0 ? +((v / total) * 100).toFixed(3) : 0);
+function visible(el) {
+    const s = getComputedStyle(el);
+    return s.display !== 'none' && s.visibility !== 'hidden' && s.opacity !== '0';
+}
+function radius(el, rect, tag) {
+    const square = Math.abs(rect.width - rect.height) < 4;
+    const s = getComputedStyle(el);
+    const r = parseFloat(s.borderTopLeftRadius) || 0;
+    if (r === 0)
+        return square && ATOMIC.has(tag) && tag !== 'input' && tag !== 'button' ? '50%' : 6;
+    if (s.borderRadius.includes('%') || r >= Math.min(rect.width, rect.height) / 2)
+        return square ? '50%' : 9999;
+    return s.borderRadius;
+}
+/**
+ * Walk the rendered children of `root` and record every visible leaf
+ * (text block, media, form control, childless element) as a bone.
+ */
+export function snapshot(root, options = {}) {
+    const base = root.getBoundingClientRect();
+    const leafTags = new Set([...LEAF_TAGS, ...(options.leafTags ?? [])]);
+    const exclude = options.exclude?.join(',');
+    const bones = [];
+    const walk = (el) => {
+        if (!visible(el) || (exclude && el.matches(exclude)))
+            return;
+        const tag = el.tagName.toLowerCase();
+        const kids = [...el.children].filter(visible);
+        const inlineOnly = kids.every(k => ['inline', 'contents'].includes(getComputedStyle(k).display));
+        if (kids.length > 0 && !ATOMIC.has(tag) && !(leafTags.has(tag) && inlineOnly)) {
+            kids.forEach(walk);
+            return;
+        }
+        const rect = el.getBoundingClientRect();
+        if (rect.width < 1 || rect.height < 1)
+            return;
+        bones.push([
+            pct(rect.left - base.left, base.width),
+            Math.round(rect.top - base.top),
+            pct(rect.width, base.width),
+            Math.round(rect.height),
+            radius(el, rect, tag),
+        ]);
+    };
+    [...root.children].forEach(walk);
+    return { width: Math.round(base.width), height: Math.round(base.height), bones };
+}

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "jiplak",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Pixel-perfect skeleton loading screens, auto-captured from your real React UI.",
+  "keywords": [
+    "skeleton",
+    "skeleton-loader",
+    "loading",
+    "placeholder",
+    "react",
+    "playwright",
+    "yaml",
+    "ui"
+  ],
+  "author": "Wahyu Agus Arifin (https://github.com/ItPohgero)",
+  "homepage": "https://github.com/ItPohgero/jiplak#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ItPohgero/jiplak.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ItPohgero/jiplak/issues"
+  },
+  "funding": [
+    {
+      "type": "buymeacoffee",
+      "url": "https://buymeacoffee.com/wahyuagusarifin"
+    },
+    {
+      "type": "sponsor",
+      "url": "https://lokio.link"
+    }
+  ],
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "jiplak": "./dist/cli.js"
+  },
+  "exports": {
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README.id.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "bun run build && bun test"
+  },
+  "dependencies": {
+    "playwright": "^1.56.0",
+    "yaml": "^2.8.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^5.9.0"
+  }
+}