ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.
Python astracloudflarecontrol-panelcyberpaneldnsfablehosting-control-panelhosting-panelkimi-k3server-managementserverkitubuntu-web-panelwebserver
feat(frontend): dev-time skeleton bone capture + bones replay (plan 50 phase 2)
Juan Denis67142efd1363
diff --git a/frontend/package-lock.json b/frontend/package-lock.jsonindex 68bf68df..d3ace8f6 100644--- a/frontend/package-lock.json+++ b/frontend/package-lock.json@@ -45,6 +45,7 @@"@types/react": "^18.3.3","@types/react-dom": "^18.3.0","@vitejs/plugin-react": "^6.0.3",+ "boneyard-js": "^1.9.0","eslint": "^9.9.0","eslint-plugin-react": "^7.35.0","eslint-plugin-react-hooks": "^5.1.0-rc.0",@@ -66,6 +67,14 @@"node": ">=6.9.0"}},+ "node_modules/@chenglou/pretext": {+ "version": "0.0.5",+ "resolved": "https://registry.npmjs.org/@chenglou/pretext/-/pretext-0.0.5.tgz",+ "integrity": "sha512-A8GZN10REdFGsyuiUgLV8jjPDDFMg5GmgxGWV0I3igxBOnzj+jgz2VMmVD7g+SFyoctfeqHFxbNatKSzVRWtRg==",+ "dev": true,+ "license": "MIT",+ "optional": true+ },"node_modules/@emnapi/core": {"version": "1.11.1","resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.11.1.tgz",@@ -3114,6 +3123,54 @@"dev": true,"license": "MIT"},+ "node_modules/boneyard-js": {+ "version": "1.9.0",+ "resolved": "https://registry.npmjs.org/boneyard-js/-/boneyard-js-1.9.0.tgz",+ "integrity": "sha512-FlIHm7YyQ6GMBPaNY6um5ESHNyZGONoSZ0IMhayuyemBsCUhhDl4nC/gMTOi/25ojtrlnRInTWKqFKb7hGK6Cg==",+ "dev": true,+ "license": "MIT",+ "dependencies": {+ "playwright": "^1.58.2"+ },+ "bin": {+ "boneyard-js": "bin/cli.js"+ },+ "optionalDependencies": {+ "@chenglou/pretext": "^0.0.5"+ },+ "peerDependencies": {+ "@angular/core": ">=14",+ "preact": ">=10",+ "react": ">=18",+ "react-native": ">=0.71",+ "svelte": ">=5.29",+ "vite": ">=5",+ "vue": ">=3"+ },+ "peerDependenciesMeta": {+ "@angular/core": {+ "optional": true+ },+ "preact": {+ "optional": true+ },+ "react": {+ "optional": true+ },+ "react-native": {+ "optional": true+ },+ "svelte": {+ "optional": true+ },+ "vite": {+ "optional": true+ },+ "vue": {+ "optional": true+ }+ }+ },"node_modules/brace-expansion": {"version": "1.1.16","resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.16.tgz",@@ -5701,6 +5758,53 @@"url": "https://github.com/sponsors/jonschlinkert"}},+ "node_modules/playwright": {+ "version": "1.61.1",+ "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.61.1.tgz",+ "integrity": "sha512-DWnY5o3YbLWK4GovuAVwpqL+1VwGNdUGrRr++8j8PtQQzvAVZUIMjKQ90fY689sEJZJBbZVw1rXaOKSTitkzPQ==",+ "dev": true,+ "license": "Apache-2.0",+ "dependencies": {+ "playwright-core": "1.61.1"+ },+ "bin": {+ "playwright": "cli.js"+ },+ "engines": {+ "node": ">=18"+ },+ "optionalDependencies": {+ "fsevents": "2.3.2"+ }+ },+ "node_modules/playwright-core": {+ "version": "1.61.1",+ "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.61.1.tgz",+ "integrity": "sha512-h7Qlt6m4REp25qvIdvbDtVmD4LqVXfpRxhORv9L0jzETM05p4fuPJ3dKyuSXQxDSbXnmS79HAgi9589lGSpLkg==",+ "dev": true,+ "license": "Apache-2.0",+ "bin": {+ "playwright-core": "cli.js"+ },+ "engines": {+ "node": ">=18"+ }+ },+ "node_modules/playwright/node_modules/fsevents": {+ "version": "2.3.2",+ "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",+ "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",+ "dev": true,+ "hasInstallScript": true,+ "license": "MIT",+ "optional": true,+ "os": [+ "darwin"+ ],+ "engines": {+ "node": "^8.16.0 || ^10.6.0 || >=11.0.0"+ }+ },"node_modules/possible-typed-array-names": {"version": "1.1.0","resolved": "https://registry.npmjs.org/possible-typed-array-names/-/possible-typed-array-names-1.1.0.tgz",diff --git a/frontend/package.json b/frontend/package.jsonindex accf2d9a..3e897459 100644--- a/frontend/package.json+++ b/frontend/package.json@@ -8,6 +8,7 @@"build": "vite build","lint": "eslint . && node scripts/check-settings-index.mjs","lint:settings-index": "node scripts/check-settings-index.mjs",+ "capture:skeletons": "node scripts/capture-skeletons.mjs","preview": "vite preview"},"optionalDependencies": {@@ -51,6 +52,7 @@"@types/react": "^18.3.3","@types/react-dom": "^18.3.0","@vitejs/plugin-react": "^6.0.3",+ "boneyard-js": "^1.9.0","eslint": "^9.9.0","eslint-plugin-react": "^7.35.0","eslint-plugin-react-hooks": "^5.1.0-rc.0",diff --git a/frontend/scripts/capture-skeletons.mjs b/frontend/scripts/capture-skeletons.mjsnew file mode 100644index 00000000..09456b99--- /dev/null+++ b/frontend/scripts/capture-skeletons.mjs@@ -0,0 +1,203 @@+#!/usr/bin/env node+/**+ * Dev-time skeleton bone capture (Phase 2 of docs/plans/50_SKELETON_LOADING_UX_PLAN.md).+ *+ * Boneyard's insight is that the most accurate loading skeleton is the *real*+ * rendered layout, measured. This script drives a headless browser against a+ * running dev server (logged in as admin/admin, with seeded dev data), snapshots+ * designated page regions into "bones" — `{x, y, w, h, r}` where x/w are+ * percentages of the region width and y/h are absolute pixels — and bakes the+ * result into `frontend/src/skeletons/<key>.json` as a static asset.+ *+ * `SkeletonBoundary`'s optional `bones` prop replays these via `renderBones`+ * (SCSS-classed absolutely-positioned divs), so the shipped product never+ * imports boneyard or runs a browser — it just reads the baked JSON.+ *+ * The in-page snapshot below is a faithful port of boneyard-js `snapshotBones`+ * (github: boneyard-js, `packages/boneyard/src/extract.ts`). We embed it rather+ * than injecting the npm ESM bundle into the page so the script stays runnable+ * from a fresh checkout; `boneyard-js` is kept as a devDependency for parity and+ * as the upstream source of truth for the bone format.+ *+ * Usage:+ * 1. Start the dev stack (backend on :47927, `npm run dev` frontend) with+ * seeded data and the default admin/admin credentials.+ * 2. npm run capture:skeletons # captures every target in TARGETS+ * SK_ONLY=ssl npm run capture:skeletons # just one target+ *+ * Env knobs:+ * SK_BASE_URL frontend base URL (default http://127.0.0.1:41921)+ * SK_USER login username (default admin)+ * SK_PASS login password (default admin)+ * SK_ONLY comma list of target keys to capture (default: all)+ * SK_HEADED set to watch the browser (default headless)+ * SK_WIDTH viewport width used for the capture (default 1440)+ */+import { mkdir, writeFile } from 'node:fs/promises';+import path from 'node:path';+import { fileURLToPath } from 'node:url';++const __dirname = path.dirname(fileURLToPath(import.meta.url));+const FRONTEND_DIR = path.resolve(__dirname, '..');+const OUT_DIR = path.join(FRONTEND_DIR, 'src', 'skeletons');++const BASE = (process.env.SK_BASE_URL || 'http://127.0.0.1:41921').replace(/\/$/, '');+const USER = process.env.SK_USER || 'admin';+const PASS = process.env.SK_PASS || 'admin';+const HEADLESS = !process.env.SK_HEADED;+const WIDTH = Number(process.env.SK_WIDTH) || 1440;+const ONLY = (process.env.SK_ONLY || '').split(',').map((s) => s.trim()).filter(Boolean);++// Regions to snapshot. `selector` is the element whose subtree becomes bones;+// `waitFor` gates the capture until the real (non-skeleton) content has rendered.+const TARGETS = [+ { key: 'ssl', path: '/ssl', selector: '.ssl-page', waitFor: '.ssl-status-bar' },+ { key: 'wordpress-list', path: '/wordpress', selector: '.wordpress-page', waitFor: '.sk-table, .wp-sites-grid, .empty-state' },+];++const log = (...a) => console.log('[bones]', ...a);++// ---- the in-page snapshot (faithful port of boneyard snapshotBones) --------+// Serialized into the page via Playwright's evaluate. Returns a SkeletonResult:+// { name, viewportWidth, width, height, bones: [{x, y, w, h, r, c?}] }+// x/w are percentages of the root width; y/h are absolute px from the root top.+function inPageSnapshot(el, name) {+ const round = (n) => Math.round(n);+ const round4 = (n) => Math.round(n * 10000) / 10000;+ const MEDIA = new Set(['IMG', 'SVG', 'VIDEO', 'CANVAS']);+ const FORM = new Set(['INPUT', 'BUTTON', 'TEXTAREA', 'SELECT']);+ const LEAF_TAGS = new Set(['P', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6', 'LI', 'TD', 'TH']);+ const rootRect = el.getBoundingClientRect();+ const bones = [];++ const parseRadius = (cs) => {+ const r = cs.borderTopLeftRadius;+ if (!r || r === '0px') return null;+ const px = parseFloat(r);+ return Number.isFinite(px) ? px : null;+ };+ const visible = (node) => {+ const cs = getComputedStyle(node);+ return cs.display !== 'none' && cs.visibility !== 'hidden' && cs.opacity !== '0';+ };+ const relX = (rect) => round4(((rect.left - rootRect.left) / rootRect.width) * 100);+ const relW = (rect) => round4((rect.width / rootRect.width) * 100);++ const walk = (node) => {+ if (!(node instanceof Element) || !visible(node)) return;+ const cs = getComputedStyle(node);+ const kids = Array.from(node.children).filter((c) => c instanceof Element && visible(c));+ const tag = node.tagName;+ const isLeaf = kids.length === 0 || MEDIA.has(tag) || FORM.has(tag) || LEAF_TAGS.has(tag);++ if (isLeaf) {+ const rect = node.getBoundingClientRect();+ if (rect.width < 1 || rect.height < 1) return;+ const squarish = MEDIA.has(tag) && Math.abs(rect.width - rect.height) < 4;+ const r = squarish ? '50%' : (parseRadius(cs) ?? 8);+ bones.push({ x: relX(rect), y: round(rect.top - rootRect.top), w: relW(rect), h: round(rect.height), r });+ return;+ }++ // Non-leaf: emit a lighter container bone for visual surfaces, then recurse.+ const hasBg = cs.backgroundColor && cs.backgroundColor !== 'rgba(0, 0, 0, 0)' && cs.backgroundColor !== 'transparent';+ const hasBgImage = cs.backgroundImage && cs.backgroundImage !== 'none';+ const hasBorder = parseFloat(cs.borderTopWidth) > 0+ && cs.borderTopColor && cs.borderTopColor !== 'rgba(0, 0, 0, 0)';+ const hasRadius = parseFloat(cs.borderTopLeftRadius) > 0;+ if (hasBg || hasBgImage || (hasBorder && hasRadius)) {+ const rect = node.getBoundingClientRect();+ if (rect.width >= 1 && rect.height >= 1) {+ bones.push({ x: relX(rect), y: round(rect.top - rootRect.top), w: relW(rect), h: round(rect.height), r: parseRadius(cs) ?? 8, c: true });+ }+ }+ kids.forEach(walk);+ };++ Array.from(el.children).forEach(walk);+ return {+ name: name || 'component',+ viewportWidth: round(rootRect.width),+ width: round(rootRect.width),+ height: round(rootRect.height),+ bones,+ };+}++// ---- driver ---------------------------------------------------------------+async function loadPlaywright() {+ try {+ return (await import('playwright')).chromium;+ } catch {+ console.error(+ 'Playwright is required for bone capture but is not installed.\n' ++ 'Install it once (dev-only, not shipped):\n' ++ ' npm i -D playwright && npx playwright install chromium',+ );+ process.exit(2);+ }+}++async function login(page) {+ await page.goto(`${BASE}/login`, { waitUntil: 'domcontentloaded', timeout: 30000 });+ // Already authenticated? A redirect away from /login means we're in.+ if (!/\/login/.test(page.url())) return;+ const user = page.locator('input[name="username"], input[type="text"]').first();+ const pass = page.locator('input[type="password"]').first();+ if (await user.count()) {+ await user.fill(USER);+ await pass.fill(PASS);+ await Promise.all([+ page.waitForNavigation({ waitUntil: 'domcontentloaded', timeout: 30000 }).catch(() => {}),+ page.locator('button[type="submit"], button:has-text("Sign in"), button:has-text("Log in")').first().click(),+ ]);+ }+}++async function main() {+ await mkdir(OUT_DIR, { recursive: true });+ const targets = ONLY.length ? TARGETS.filter((t) => ONLY.includes(t.key)) : TARGETS;+ if (!targets.length) { console.error(`No targets matched SK_ONLY=${ONLY.join(',')}`); process.exit(2); }++ const chromium = await loadPlaywright();+ const browser = await chromium.launch({ headless: HEADLESS });+ const context = await browser.newContext({ viewport: { width: WIDTH, height: 900 }, deviceScaleFactor: 1 });+ const page = await context.newPage();++ let failed = 0;+ try {+ await login(page);+ for (const t of targets) {+ process.stdout.write(`[bones] ${t.key.padEnd(16)} `);+ try {+ await page.goto(`${BASE}${t.path}`, { waitUntil: 'domcontentloaded', timeout: 30000 });+ await page.waitForSelector(t.waitFor, { timeout: 15000, state: 'visible' });+ await page.waitForTimeout(600); // let layout settle+ const snapshot = await page.evaluate(+ ({ selector, key, fnSrc }) => {+ const el = document.querySelector(selector);+ if (!el) return null;+ // eslint-disable-next-line no-new-func+ const fn = new Function(`return (${fnSrc})`)();+ return fn(el, key);+ },+ { selector: t.selector, key: t.key, fnSrc: inPageSnapshot.toString() },+ );+ if (!snapshot || !snapshot.bones.length) throw new Error(`no bones captured for ${t.selector}`);+ await writeFile(path.join(OUT_DIR, `${t.key}.json`), JSON.stringify(snapshot, null, 2) + '\n');+ console.log(`OK (${snapshot.bones.length} bones, ${snapshot.height}px)`);+ } catch (e) {+ failed += 1;+ console.log(`FAIL ${e.message}`);+ }+ }+ } finally {+ await context.close();+ await browser.close();+ }++ log(`done -> ${OUT_DIR}`);+ if (failed) process.exit(1);+}++main().catch((e) => { console.error(e); process.exit(1); });diff --git a/frontend/src/components/SkeletonBoundary.jsx b/frontend/src/components/SkeletonBoundary.jsxindex f5ed853d..2af38777 100644--- a/frontend/src/components/SkeletonBoundary.jsx+++ b/frontend/src/components/SkeletonBoundary.jsx@@ -1,5 +1,6 @@import { Children, useEffect, useState } from 'react';import { cn } from '@/lib/utils';+import { renderBones } from './renderBones';/*** SkeletonBoundary — paints a loading skeleton over the real content box.@@ -25,8 +26,14 @@ import { cn } from '@/lib/utils';* `aria-hidden`. Shimmer and the optional fade honour `prefers-reduced-motion`* via `styles/components/_skeleton.scss`.*+ * A captured bone layout (baked into `frontend/src/skeletons/*.json` by+ * `npm run capture:skeletons`) can be passed as `bones` instead of composing a+ * `skeleton` by hand — the boundary replays it via `renderBones`. `bones` wins+ * over `skeleton` when both are given.+ ** @param {boolean} loading Whether content is still loading.* @param {React.ReactNode} skeleton Placeholder rendered while loading.+ * @param {object} [bones] Captured SkeletonResult (`{width,height,bones}`); replaces `skeleton` when set.* @param {React.ReactNode} children Real content (may be data-gated/absent).* @param {boolean} [transition] Fade the skeleton out on load (~200ms, opacity only).* @param {string} [as] Container tag name (default 'div').@@ -35,6 +42,7 @@ import { cn } from '@/lib/utils';export function SkeletonBoundary({loading,skeleton,+ bones = null,children,transition = false,as: Tag = 'div',@@ -60,6 +68,7 @@ export function SkeletonBoundary({// Overlay mode needs a real box to cover — only when in-flow children exist.const hasContent = Children.toArray(children).length > 0;+ const skeletonContent = bones ? renderBones(bones) : skeleton;return (<Tag@@ -79,7 +88,7 @@ export function SkeletonBoundary({)}aria-hidden="true">- {skeleton}+ {skeletonContent}</div>)}</Tag>diff --git a/frontend/src/components/renderBones.jsx b/frontend/src/components/renderBones.jsxnew file mode 100644index 00000000..be976c64--- /dev/null+++ b/frontend/src/components/renderBones.jsx@@ -0,0 +1,51 @@+import { cn } from '@/lib/utils';++/**+ * Replay a captured bone layout (baked into `frontend/src/skeletons/*.json` by+ * `npm run capture:skeletons`) as positioned skeleton placeholders.+ *+ * Bone geometry model (from boneyard-js `snapshotBones`): `x`/`w` are+ * PERCENTAGES of the captured region width, `y`/`h` are ABSOLUTE PIXELS from the+ * region top, and `r` is a number (px) or a CSS string. Container bones+ * (`c: true`) are background surfaces — skipped so only the leaf placeholders+ * paint, matching boneyard's own renderer.+ *+ * The per-bone `left/top/width/height/borderRadius` are true dynamic values+ * (measured, not guessed), which the styling standard permits as inline styles;+ * the shimmer, color, and reduced-motion handling all come from `.skeleton`.+ *+ * @param {{width?:number,height?:number,bones?:Array}|null} snapshot A captured+ * SkeletonResult, or null (renders nothing).+ * @returns {JSX.Element|null}+ */+export function renderBones(snapshot) {+ if (!snapshot || !Array.isArray(snapshot.bones)) return null;+ const { height = 0, bones } = snapshot;+ return (+ <div+ className="skeleton-bones"+ style={{ height: height ? `${height}px` : undefined }}+ aria-hidden="true"+ >+ {bones.filter((b) => !b.c).map((b, i) => {+ const isCircle = b.r === '50%';+ const radius = typeof b.r === 'number' ? `${b.r}px` : b.r;+ return (+ <span+ key={i}+ className={cn('skeleton', 'skeleton-bone')}+ style={{+ left: `${b.x}%`,+ top: `${b.y}px`,+ width: isCircle ? `${b.h}px` : `${b.w}%`,+ height: `${b.h}px`,+ borderRadius: radius,+ }}+ />+ );+ })}+ </div>+ );+}++export default renderBones;diff --git a/frontend/src/skeletons/README.md b/frontend/src/skeletons/README.mdnew file mode 100644index 00000000..1b9eb582--- /dev/null+++ b/frontend/src/skeletons/README.md@@ -0,0 +1,64 @@+# Baked skeleton bones++These `*.json` files are **measured loading-skeleton layouts** — the real+rendered UI of a page region, snapshotted into positioned "bones". They are+static assets: the shipped product reads them, but never runs a browser or+imports `boneyard-js` to produce them.++`SkeletonBoundary`'s optional `bones` prop replays a file here via `renderBones`,+giving a pixel-accurate placeholder instead of a hand-composed one:++```jsx+import sslBones from '@/skeletons/ssl.json';++<SkeletonBoundary loading={loading} bones={sslBones}>+ {status && <SslContent data={status} />}+</SkeletonBoundary>+```++## Bone format++Each file is a `SkeletonResult` (the `boneyard-js` shape):++```jsonc+{+ "name": "ssl",+ "viewportWidth": 1440, // capture viewport width+ "width": 1200, // captured region width (px)+ "height": 320, // captured region height (px)+ "bones": [+ // x, w are PERCENTAGES of the region width (responsive)+ // y, h are ABSOLUTE PIXELS from the region top+ // r is a number (px) or a CSS string ("50%" = circle)+ // c: true marks a background/container bone (skipped on render)+ { "x": 1.5, "y": 0, "w": 5.3, "h": 44, "r": "50%" },+ { "x": 8.0, "y": 6, "w": 40, "h": 20, "r": 6 }+ ]+}+```++## Regenerating (dev-only)++Bones drift when the UI changes. Re-capture from a **running, logged-in** dev+session with seeded data:++```bash+# one-time: the capture tool needs a headless browser (dev-only, not shipped)+npm i -D playwright && npx playwright install chromium++# with the backend (:47927) and `npm run dev` frontend up, admin/admin:+npm run capture:skeletons # all targets in scripts/capture-skeletons.mjs+SK_ONLY=ssl npm run capture:skeletons # just one+```++The script logs in, navigates each target page, waits for the real content, and+writes `<key>.json` here. Add/adjust targets in+`frontend/scripts/capture-skeletons.mjs`.++> **PR checklist:** if you change the layout of a page that has baked bones,+> re-run `npm run capture:skeletons` for that page and commit the updated JSON,+> or the skeleton will drift from the real layout.++`example.json` is a **format sample only** (a 3-row list), committed so the shape+is self-documenting and the render path has fixture data; real captures are named+after their page key (`ssl.json`, `wordpress-list.json`, …).diff --git a/frontend/src/skeletons/example.json b/frontend/src/skeletons/example.jsonnew file mode 100644index 00000000..cf338f65--- /dev/null+++ b/frontend/src/skeletons/example.json@@ -0,0 +1,18 @@+{+ "name": "example",+ "note": "Format sample only (a 3-row avatar+two-line list). Not a real capture; see README.md. Real captures are named after their page key.",+ "viewportWidth": 1440,+ "width": 600,+ "height": 180,+ "bones": [+ { "x": 2, "y": 14, "w": 5.34, "h": 32, "r": "50%" },+ { "x": 9, "y": 12, "w": 40, "h": 12, "r": 6 },+ { "x": 9, "y": 32, "w": 25, "h": 10, "r": 6 },+ { "x": 2, "y": 74, "w": 5.34, "h": 32, "r": "50%" },+ { "x": 9, "y": 72, "w": 40, "h": 12, "r": 6 },+ { "x": 9, "y": 92, "w": 25, "h": 10, "r": 6 },+ { "x": 2, "y": 134, "w": 5.34, "h": 32, "r": "50%" },+ { "x": 9, "y": 132, "w": 40, "h": 12, "r": 6 },+ { "x": 9, "y": 152, "w": 25, "h": 10, "r": 6 }+ ]+}diff --git a/frontend/src/styles/components/_skeleton.scss b/frontend/src/styles/components/_skeleton.scssindex aafd37ae..6f8b7466 100644--- a/frontend/src/styles/components/_skeleton.scss+++ b/frontend/src/styles/components/_skeleton.scss@@ -164,6 +164,18 @@}}+// Captured-bone replay (renderBones): a positioned canvas of leaf placeholders+// measured from the real layout. Each .skeleton-bone carries its own dynamic+// left/top/width/height inline; the look comes from the shared .skeleton class.+.skeleton-bones {+ position: relative;+ width: 100%;+}++.skeleton-bone {+ position: absolute;+}+@media (prefers-reduced-motion: reduce) {.skeleton::after {animation: none;