@ogygia/devtools 0.0.0 → 0.11.1

package/dist/devtools/LedgerTab.svelte

@@ -0,0 +1,287 @@
+<!-- (its CSS injected into the dock's shadow root: see Devtools.svelte) -->
+<svelte:options css="injected" />
+
+<script>
+	/**
+	 * The Bytes tab (byte ledger): real over-the-wire JS per island entry chunk + the shared runtime
+	 * chunk, from PerformanceResourceTiming. Cold islands show `cold` and fill in live as the panel
+	 * ticks. Measures each island's OWN chunk (not transitive deps); dev sizes are flagged.
+	 */
+	import {
+		all_regions,
+		chunk_bytes,
+		basename,
+		kb,
+		region_name,
+		region_transitive
+	} from './regions.js';
+
+	import { page_ledger } from './ledger-dom.js';
+	import { profile_for, profiles_version } from './profile-store.js';
+
+	let { tick = 0 } = $props();
+	const IS_DEV = !!(import.meta.env && import.meta.env.DEV);
+
+	// THE EXACT LEDGER (a build): the page's island graph names every file each island needs, the
+	// browser says what each file weighed — each file counted once, and per island what only it needs
+	const exact = $derived.by(() => {
+		void tick;
+		return page_ledger();
+	});
+	// the modules the build shipped twice that this page loads both copies of (the last profile's)
+	const twice = $derived.by(() => {
+		void tick;
+		profiles_version();
+		return profile_for(location.pathname)?.assets?.twice ?? [];
+	});
+
+	const model = $derived.by(() => {
+		void tick; // refresh with the panel tick
+
+		// Group regions by entry chunk (dedupe: same component + strategy = ONE chunk, N instances).
+		const groups = new Map();
+		for (const r of all_regions()) {
+			if (!r.entry) continue;
+			const key = basename(r.entry);
+			const g = groups.get(key);
+			if (g) g.count++;
+			else groups.set(key, { entry: r.entry, kind: r.kind, wake: r.wake, count: 1 });
+		}
+
+		const rows = [...groups.values()]
+			.map((g) => {
+				const t = region_transitive(g.entry);
+				return {
+					...g,
+					...chunk_bytes(g.entry),
+					name: region_name(g.entry),
+					transitive: t ? t.bytes : 0,
+					modules: t ? t.modules : 0
+				};
+			})
+			// Sort by the real (transitive) cost when we have it, else by the entry-chunk wire size.
+			.sort((a, b) => b.transitive - a.transitive || b.wire - a.wire);
+
+		const runtimeSrc =
+			document.querySelector('script[data-ogygia-runtime]')?.getAttribute('src') || '';
+		const runtime = runtimeSrc ? { src: runtimeSrc, ...chunk_bytes(runtimeSrc) } : null;
+
+		// Page total over UNIQUE chunks (rows are already one-per-island). `wire` = wrapper chunks;
+		// `transitive` = each island's whole subgraph (the real-cost column).
+		const counted = new Set();
+		let wire = 0;
+		let transitive = 0;
+		for (const row of rows) {
+			const key = basename(row.entry);
+			if (counted.has(key)) continue;
+			counted.add(key);
+			if (row.loaded) wire += row.wire;
+			transitive += row.transitive;
+		}
+		if (runtime?.loaded && !counted.has(basename(runtime.src))) wire += runtime.wire;
+		return { rows, runtime, totalWire: wire, totalTransitive: transitive };
+	});
+</script>
+
+<h3>byte ledger — JavaScript per island</h3>
+{#if exact}
+	<div class="note" data-og-ledger-exact>
+		Every file each island needs, from the page's island graph, weighed by the browser (over the
+		wire).
+		<b>only it</b> is what that island alone needs: what removing it would save. <b>shared</b> it shares
+		with other islands. The page total counts each file once.
+	</div>
+	<table>
+		<thead>
+			<tr
+				><th>island</th><th>kind</th><th>files</th><th>loaded</th><th>only it</th><th>shared</th
+				></tr
+			>
+		</thead>
+		<tbody>
+			{#each exact.rows as row (row.entry)}
+				<tr>
+					<td title={row.entry}
+						><span class="nm">{row.name}</span>{#if row.count > 1}<span class="muted">
+								×{row.count}</span
+							>{/if}</td
+					>
+					<td>{row.kind}{row.kind === 'island' ? ' · ' + row.wake : ''}</td>
+					<td
+						>{row.files}{#if row.cold}<span class="muted"> · {row.cold} cold</span>{/if}</td
+					>
+					<td
+						>{#if row.files > row.cold}{kb(row.wire)}{:else}<span class="muted">cold</span>{/if}</td
+					>
+					<td><span class="strong">{kb(row.unique)}</span></td>
+					<td class="muted">{kb(row.shared)}</td>
+				</tr>
+			{/each}
+			<tr>
+				<td>ogygia runtime</td>
+				<td class="muted">every island</td>
+				<td>{exact.runtime.files}</td>
+				<td>{kb(exact.runtime.wire)}</td>
+				<td class="muted">—</td>
+				<td class="muted">—</td>
+			</tr>
+		</tbody>
+		<tfoot>
+			<tr>
+				<td>page</td>
+				<td class="muted">each file once</td>
+				<td
+					>{exact.page.files}{#if exact.page.cold}<span class="muted">
+							· {exact.page.cold} cold</span
+						>{/if}</td
+				>
+				<td>{kb(exact.page.wire)}</td>
+				<td colspan="2" class="muted">{kb(exact.page.raw)} decoded</td>
+			</tr>
+		</tfoot>
+	</table>
+	{#if exact.shared.length}
+		<h3 class="sub">shared files</h3>
+		<table data-og-ledger-shared>
+			<tbody>
+				{#each exact.shared.slice(0, 8) as s (s.url)}
+					<tr>
+						<td title={s.url}>{basename(s.url)}</td>
+						<td>{kb(s.wire)}</td>
+						<td class="muted"
+							>{s.users.length > 4
+								? `${s.users.slice(0, 3).join(', ')} and ${s.users.length - 3} more`
+								: s.users.join(', ')}</td
+						>
+					</tr>
+				{/each}
+			</tbody>
+		</table>
+	{/if}
+	{#if twice.length}
+		<!-- the last profile of this page: modules the build shipped twice, both copies loaded here -->
+		<h3 class="sub">loaded twice</h3>
+		<div class="note" data-og-ledger-twice>
+			One module reached by two paths (a package's source and its build, or two of its versions)
+			ships as two copies, and this page loads both: {kb(twice.reduce((s, d) => s + d.extra, 0))} of code
+			its browser downloads, parses and runs a second time. From the last profile.
+		</div>
+		<table>
+			<tbody>
+				{#each twice.slice(0, 8) as d (d.name)}
+					<tr>
+						<td>{d.name}</td>
+						<td>{kb(d.extra)}</td>
+						<td class="muted"
+							>{d.copies
+								.map((c) => `${basename(c.file)}${c.from ? ` (${c.from})` : ''}`)
+								.join(' · ')}</td
+						>
+					</tr>
+				{/each}
+			</tbody>
+		</table>
+	{/if}
+{:else}
+	<div class="note">
+		Each <b>+deps</b> figure is that island's <b>whole bundle</b> — the component plus every shared
+		function and utility it imports. Shared code is therefore counted in <em>every</em> island that
+		uses it, so the figures overlap and the page total over-counts code that actually ships once.{#if IS_DEV}
+			Dev estimate: sizes are unbundled/unminified — build + preview for shipped numbers.{/if} A cold
+		island (not yet woken) shows <b>—</b> until it loads.
+	</div>
+
+	<table>
+		<thead>
+			<tr><th>island</th><th>kind</th><th>wrapper</th><th>+deps</th></tr>
+		</thead>
+		<tbody>
+			{#each model.rows as row (row.entry)}
+				<tr>
+					<td title={row.entry}>
+						<span class="nm">{row.name}</span>{#if row.count > 1}<span class="muted">
+								×{row.count}</span
+							>{/if}
+					</td>
+					<td>{row.kind}{row.kind === 'island' ? ' · ' + row.wake : ''}</td>
+					<td
+						>{#if row.loaded}{kb(row.wire)}{:else}<span class="muted">cold</span>{/if}</td
+					>
+					<td>
+						{#if row.transitive}
+							<span class="strong">{kb(row.transitive)}</span><span class="muted">
+								· {row.modules} mod</span
+							>
+						{:else}<span class="muted">—</span>{/if}
+					</td>
+				</tr>
+			{:else}
+				<tr><td colspan="4" class="muted">no island chunks on this page</td></tr>
+			{/each}
+			{#if model.runtime}
+				<tr>
+					<td>ogygia runtime</td>
+					<td class="muted">shared</td>
+					<td>{model.runtime.loaded ? kb(model.runtime.wire) : '—'}</td>
+					<td class="muted">—</td>
+				</tr>
+			{/if}
+		</tbody>
+		<tfoot>
+			<tr>
+				<td>page total</td><td class="muted">unique · +deps</td>
+				<td>{kb(model.totalWire)}</td><td>{kb(model.totalTransitive)}</td>
+			</tr>
+		</tfoot>
+	</table>
+{/if}
+
+<style>
+	h3 {
+		margin: 0 0 8px;
+		font-size: 12px;
+		color: #5eead4;
+	}
+	h3.sub {
+		margin-top: 12px;
+	}
+	.note {
+		color: #94a3b8;
+		margin-bottom: 6px;
+	}
+	table {
+		border-collapse: collapse;
+		width: 100%;
+	}
+	th,
+	td {
+		text-align: right;
+		padding: 2px 8px;
+		white-space: nowrap;
+	}
+	th:first-child,
+	td:first-child,
+	th:nth-child(2),
+	td:nth-child(2) {
+		text-align: left;
+	}
+	thead th {
+		color: #94a3b8;
+		border-bottom: 1px solid rgba(148, 163, 184, 0.2);
+	}
+	tfoot td {
+		border-top: 1px solid rgba(148, 163, 184, 0.2);
+		color: #5eead4;
+		font-weight: 600;
+	}
+	.muted {
+		color: #94a3b8;
+	}
+	.nm {
+		color: #e2e8f0;
+		font-weight: 600;
+	}
+	.strong {
+		color: #e2e8f0;
+	}
+</style>

package/dist/devtools/LedgerTab.svelte.d.ts

@@ -0,0 +1,11 @@
+export default LedgerTab;
+type LedgerTab = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+declare const LedgerTab: import("svelte").Component<{
+    tick?: number;
+}, {}, "">;
+type $$ComponentProps = {
+    tick?: number;
+};

package/dist/devtools/LensTab.svelte

@@ -0,0 +1,290 @@
+<!-- (its CSS injected into the dock's shadow root: see Devtools.svelte) -->
+<svelte:options css="injected" />
+
+<script>
+	/**
+	 * The Lens tab: toggles the page-tinting {@link ./BoundaryOverlay.svelte overlay} and lists every
+	 * region by NAME with its kind / schedule / JS cost / hydration state. Hovering a row lights up the
+	 * matching box on the page (shared `focus`), and clicking a row smooth-scrolls that region into
+	 * view — so the roster is a live index into the page, not just a static table. The overlay itself is
+	 * drawn by BoundaryOverlay (a sibling under the root app); this tab controls it and mirrors it.
+	 */
+	import { all_regions, region_name, region_transitive } from './regions.js';
+
+	let {
+		tick = 0,
+		overlay = $bindable(false),
+		focus = $bindable(null),
+		selected = $bindable(null),
+		picking = $bindable(false)
+	} = $props();
+
+	const kb = (n) => (n < 1024 ? n + ' B' : (n / 1024).toFixed(1) + ' KB');
+
+	const regions = $derived.by(() => {
+		void tick; // refresh with the panel tick
+		return all_regions().map((r) => ({
+			r,
+			name: region_name(r.entry),
+			js: r.kind === 'island' ? region_transitive(r.entry) : null
+		}));
+	});
+	const summary = $derived.by(() => {
+		const c = { island: 0, lake: 0, hole: 0 };
+		let js = 0;
+		let cold = 0;
+		for (const { r, js: t } of regions) {
+			c[r.kind]++;
+			if (t) js += t.bytes;
+			if (r.kind === 'island' && !r.hydrated) cold++;
+		}
+		return { ...c, js, cold };
+	});
+
+	function state_of(r) {
+		// (a nested island rides the island around it: awake with it, never on its own)
+		if (r.kind === 'island' && r.rides)
+			return r.hydrated ? 'rides its parent' : 'cold (with its parent)';
+		if (r.kind === 'island') return r.hydrated ? 'hydrated' : 'cold';
+		return r.hydrated ? 'filled' : 'pending';
+	}
+	function toggle_pick() {
+		picking = !picking;
+		if (picking) overlay = true; // need the boxes visible to pick one on the page
+	}
+</script>
+
+<div class="cap">
+	boundary lens <span class="muted">· every region on the page, x-rayed</span>
+</div>
+
+<div class="controls">
+	<button
+		class="btn"
+		data-og-overlay-toggle
+		class:on={overlay}
+		onclick={() => (overlay = !overlay)}
+	>
+		<span class="eye"></span>{overlay ? 'hide overlay' : 'show overlay'}
+	</button>
+	<button
+		class="btn pick"
+		data-og-pick
+		class:on={picking}
+		onclick={toggle_pick}
+		title="then click an island on the page"
+	>
+		<span class="target"></span>{picking ? 'click an island…' : 'pick on page'}
+	</button>
+	<span class="legend">
+		<span class="sw og-island"></span>{summary.island}
+		<span class="sw og-lake"></span>{summary.lake}
+		<span class="sw og-hole"></span>{summary.hole}
+	</span>
+	{#if summary.js > 0}<span class="tot"
+			>{kb(summary.js)} JS{#if summary.cold}<span class="muted">
+					· {summary.cold} cold</span
+				>{/if}</span
+		>{/if}
+</div>
+
+<table>
+	<thead>
+		<tr><th>island</th><th>wake</th><th>js + deps</th><th>state</th></tr>
+	</thead>
+	<tbody>
+		{#each regions as { r, name, js } (r.el)}
+			<tr
+				class:on={focus === r.el}
+				class:cold={r.kind === 'island' && !r.hydrated}
+				onmouseenter={() => (focus = r.el)}
+				onmouseleave={() => (focus = null)}
+				onclick={() => {
+					selected = r.el;
+					picking = false;
+				}}
+				title="inspect this region"
+			>
+				<!-- the name is a button: Tab reaches the row, Enter opens it (the press bubbles to the row) -->
+				<td
+					><span class="dot og-{r.kind}"></span><button
+						class="nm rowbtn"
+						onfocus={() => (focus = r.el)}
+						onblur={() => (focus = null)}>{name}</button
+					></td
+				>
+				<td>{r.kind === 'island' ? r.wake : r.kind}</td>
+				<td class="mono">
+					{#if r.kind !== 'island'}<span class="muted">0 B</span>
+					{:else if js}{kb(js.bytes)}
+					{:else}<span class="muted">—</span>{/if}
+				</td>
+				<td class:coldstate={r.kind === 'island' && !r.hydrated}>{state_of(r)}</td>
+			</tr>
+		{:else}
+			<tr><td colspan="4" class="muted">no regions on this page</td></tr>
+		{/each}
+	</tbody>
+</table>
+
+<style>
+	.cap {
+		font-size: 12px;
+		color: #5eead4;
+		margin-bottom: 8px;
+	}
+	.controls {
+		display: flex;
+		align-items: center;
+		gap: 12px;
+		margin-bottom: 10px;
+	}
+	.btn {
+		display: inline-flex;
+		align-items: center;
+		gap: 7px;
+		padding: 5px 11px;
+		border-radius: 7px;
+		border: 1px solid rgba(148, 163, 184, 0.3);
+		background: #0d1526;
+		color: #e2e8f0;
+		cursor: pointer;
+		font: inherit;
+	}
+	.btn .eye {
+		width: 9px;
+		height: 9px;
+		border-radius: 50%;
+		border: 1.5px solid currentColor;
+		opacity: 0.7;
+	}
+	.btn.on {
+		background: #14b8a6;
+		color: #022;
+		border-color: #0d9488;
+	}
+	.btn.on .eye {
+		opacity: 1;
+		background: currentColor;
+	}
+	.btn.pick .target {
+		width: 10px;
+		height: 10px;
+		border-radius: 50%;
+		border: 1.5px solid currentColor;
+		position: relative;
+		opacity: 0.75;
+	}
+	.btn.pick .target::after {
+		content: '';
+		position: absolute;
+		inset: 3px;
+		border-radius: 50%;
+		background: currentColor;
+	}
+	.btn.pick.on {
+		background: #f59e0b;
+		color: #201400;
+		border-color: #d97706;
+	}
+	.btn.pick.on .target {
+		opacity: 1;
+	}
+	.legend {
+		color: #94a3b8;
+		display: flex;
+		align-items: center;
+		gap: 5px;
+	}
+	.tot {
+		margin-left: auto;
+		color: #5eead4;
+		font-weight: 600;
+	}
+	.sw {
+		display: inline-block;
+		width: 10px;
+		height: 10px;
+		border-radius: 3px;
+		margin-left: 6px;
+	}
+	.sw.og-island,
+	.dot.og-island {
+		background: #14b8a6;
+	}
+	.sw.og-lake,
+	.dot.og-lake {
+		background: #f59e0b;
+	}
+	.sw.og-hole,
+	.dot.og-hole {
+		background: #8b5cf6;
+	}
+	.dot {
+		display: inline-block;
+		width: 8px;
+		height: 8px;
+		border-radius: 50%;
+		margin-right: 7px;
+		vertical-align: 0;
+	}
+	.nm {
+		color: #e2e8f0;
+		font-weight: 600;
+	}
+	/* a button that reads as the name it was */
+	.rowbtn {
+		all: unset;
+		cursor: pointer;
+	}
+	/* (after the reset: the name's own look) */
+	.rowbtn.nm {
+		color: #e2e8f0;
+		font-weight: 600;
+	}
+	.rowbtn:focus-visible {
+		outline: 2px solid rgba(94, 234, 212, 0.7);
+		outline-offset: 2px;
+		border-radius: 3px;
+	}
+	table {
+		border-collapse: collapse;
+		width: 100%;
+	}
+	th,
+	td {
+		text-align: right;
+		padding: 3px 8px;
+		white-space: nowrap;
+	}
+	th:first-child,
+	td:first-child,
+	th:nth-child(2),
+	td:nth-child(2) {
+		text-align: left;
+	}
+	thead th {
+		color: #94a3b8;
+		border-bottom: 1px solid rgba(148, 163, 184, 0.2);
+	}
+	tbody tr {
+		cursor: pointer;
+		border-radius: 5px;
+	}
+	tbody tr:hover,
+	tbody tr.on {
+		background: rgba(94, 234, 212, 0.12);
+	}
+	tbody tr.on {
+		box-shadow: inset 2px 0 0 #5eead4;
+	}
+	.muted {
+		color: #94a3b8;
+	}
+	.mono {
+		font-variant-numeric: tabular-nums;
+	}
+	.coldstate {
+		color: #94a3b8;
+	}
+</style>

package/dist/devtools/LensTab.svelte.d.ts

@@ -0,0 +1,19 @@
+export default LensTab;
+type LensTab = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+declare const LensTab: import("svelte").Component<{
+    tick?: number;
+    overlay?: boolean;
+    focus?: any;
+    selected?: any;
+    picking?: boolean;
+}, {}, "focus" | "overlay" | "selected" | "picking">;
+type $$ComponentProps = {
+    tick?: number;
+    overlay?: boolean;
+    focus?: any;
+    selected?: any;
+    picking?: boolean;
+};