x12i-downloads 0.2.0 → 0.2.2

package/README.md

@@ -1,5 +1,7 @@
 # @x12i Total Downloads
 
+This is the `x12i-downloads` package in the x12i-stats monorepo (`packages/x12i-stats`). Run the commands below from this directory, or from the repo root with `npm run <script> -w x12i-downloads`.
+
 A React dashboard that counts cumulative npm downloads of every package the `@x12i` org has ever published, since March 20, 2026.
 
 Live: https://stats.x12i.com (also https://x12i-downloads.ami-3ad.workers.dev)
@@ -10,7 +12,7 @@ Live: https://stats.x12i.com (also https://x12i-downloads.ami-3ad.workers.dev)
 - `packages` remembers every package ever discovered. Each run counts the union of known packages and npm's current org listing, so a package that leaves the listing keeps counting.
 - `package_daily` stores per-package daily downloads. A stored day is only ever raised, never lowered or deleted, so the total cannot go down when npm revises or drops data.
 - A new total is refused (the published one is held) if it would be lower; `stats_history` keeps one row per published day.
-- npm publishes day D on D+1 at the earliest, sometimes stalls for days, and sometimes skips days for every package. Days npm reports as 0 for every package are estimated, through yesterday: each package gets the average of its last 7 days with downloads (within the 30 days before npm's last counted day), as an integer. "Skipped" days are ones npm moved past; "pending" days are after npm's latest counted day. Estimates are computed at publish time and never stored in `package_daily`, so npm's real counts replace them as soon as npm publishes or backfills those days. Because estimates skip zero days they run high, so when real counts arrive the total may be held for a while until real downloads catch up.
+- npm publishes day D on D+1 at the earliest, sometimes stalls for days, and sometimes skips days for every package. Days npm reports as 0 for every package are estimated, through yesterday: each package gets the average of its last 7 days with downloads (within the 30 days before npm's last counted day), as an integer, and the day's sum is capped at the org's real average over the 7 days npm counted before it (so sparse packages and org-wide sweep days don't inflate it). "Skipped" days are ones npm moved past; "pending" days are after npm's latest counted day. Estimates are computed at publish time and never stored in `package_daily`, so npm's real counts replace them as soon as npm publishes or backfills those days. If real counts arrive lower than the estimates, the total is held until real downloads catch up.
 
 ## Refresh schedule
 
@@ -92,7 +94,7 @@ npm test
 ## Main source files
 
 - `lib/npm-stats-live.ts` — refresh state machine and SQL (shared by Worker and local runner)
-- `lib/npm-client.ts` — npm registry / downloads API client with fetch budget and retries
+- `lib/npm-client.ts` — download-range client with a fetch budget. Org discovery goes through `@x12i/npm-core`
 - `migrations/` — D1 / SQLite schema
 - `lib/insights.mjs` — analytics SDK (leaders, movers, concentration, anomalies, lifecycle, report rendering)
 - `lib/sqlite-d1.mjs` — D1-compatible adapter over `node:sqlite`

package/app/admin/page.tsx

@@ -279,7 +279,8 @@ export default function AdminPage() {
             <h2>Estimated days ({estimatedDays.length})</h2>
             <p className="muted small">
               Days npm reports as 0 for every package. Each package is estimated as the average of its last 7 days
-              with downloads (within 30 days); npm&apos;s real counts replace these whenever npm publishes them.
+              with downloads (within 30 days), and each day is capped at the org&apos;s real average over the 7 days npm
+              counted before it. npm&apos;s real counts replace these whenever npm publishes them.
             </p>
             <div className="admin-table-wrap">
               <table className="admin-table">

package/app/globals.css

@@ -1,17 +1,41 @@
 @import "tailwindcss";
 
 :root {
-  --background: #0f172a;
+  color-scheme: dark;
+  --background: #0b1222;
   --surface: #111c30;
-  --surface-border: #253149;
-  --foreground: #f8fafc;
-  --muted: #94a3b8;
-  --muted-dark: #64748b;
+  --card: #0f1a2e;
+  --surface-border: #22304a;
+  --foreground: #f1f5f9;
+  --muted: #a3b2c7;
+  --muted-dark: #8293ab;
   --accent: #38bdf8;
+  --accent-strong: #7dd3fc;
   --accent-soft: rgba(56, 189, 248, 0.12);
-  --grid: #334155;
+  --grid: #26344d;
+  --command-bg: rgba(8, 15, 30, 0.6);
   --danger: #f87171;
-  --anim-duration: 2s;
+  --shadow: 0 28px 80px rgba(2, 6, 23, 0.45);
+}
+
+/* Light theme for the downloads card only; the stats admin page stays dark. */
+@media (prefers-color-scheme: light) {
+  :root:has(.dashboard-shell) {
+    color-scheme: light;
+    --background: #eef2f7;
+    --surface: #ffffff;
+    --card: #ffffff;
+    --surface-border: #dde3ec;
+    --foreground: #0f172a;
+    --muted: #475569;
+    --muted-dark: #5b6b82;
+    --accent: #0b7ea8;
+    --accent-strong: #075c7c;
+    --accent-soft: rgba(11, 126, 168, 0.1);
+    --grid: #e3e8f0;
+    --command-bg: #f5f7fb;
+    --shadow: 0 24px 60px rgba(15, 23, 42, 0.08);
+  }
 }
 
 * {
@@ -26,9 +50,7 @@ html {
 body {
   min-height: 100vh;
   margin: 0;
-  background:
-    radial-gradient(circle at 50% 0%, rgba(56, 189, 248, 0.08), transparent 32rem),
-    var(--background);
+  background: var(--background);
   color: var(--foreground);
   font-family: var(--font-geist-sans), Inter, ui-sans-serif, system-ui, sans-serif;
 }
@@ -40,144 +62,159 @@ select {
   font: inherit;
 }
 
+.sr {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  white-space: nowrap;
+}
+
+/* ── Card ──────────────────────────────────────────────── */
+
 .dashboard-shell {
   display: grid;
   min-height: 100vh;
   place-items: center;
-  padding: 2rem;
+  padding: 2rem 1rem;
 }
 
 .dashboard-card {
-  width: min(100%, 44rem);
-  overflow: hidden;
+  width: min(100%, 41rem);
+  padding: 2.25rem 2.25rem 2rem;
   border: 1px solid var(--surface-border);
-  border-radius: 1.75rem;
-  background: rgba(15, 23, 42, 0.82);
-  box-shadow: 0 32px 90px rgba(2, 6, 23, 0.48);
-  backdrop-filter: blur(16px);
-}
-
-.dashboard-content {
-  padding: 2.25rem 2.5rem 2.5rem;
+  border-radius: 1.5rem;
+  background: var(--card);
+  box-shadow: var(--shadow);
   text-align: center;
 }
 
-.eyebrow {
-  margin: 0.5rem 0 0;
-  color: var(--muted);
-  font-size: 0.72rem;
-  font-weight: 700;
-  letter-spacing: 0.18em;
-  text-transform: uppercase;
+.intro {
+  display: grid;
+  justify-items: center;
+  gap: 0.75rem;
 }
 
 .title {
   margin: 0;
-  font-size: clamp(2rem, 7vw, 2.75rem);
-  font-weight: 850;
-  letter-spacing: -0.045em;
+  max-width: 20ch;
+  font-size: clamp(1.6rem, 5.4vw, 2.2rem);
+  font-weight: 800;
+  letter-spacing: -0.03em;
+  line-height: 1.12;
+  text-wrap: balance;
+}
+
+.title-break {
+  display: block;
+}
+
+.description {
+  max-width: 30rem;
+  margin: 0;
+  color: var(--muted);
+  font-size: 1rem;
+  line-height: 1.55;
+  text-wrap: balance;
 }
 
 .metric-block {
-  margin: 2.5rem 0 2rem;
+  margin: 2.25rem 0 0.5rem;
 }
 
 .total {
-  min-height: 1.05em;
+  margin: 0;
   color: var(--accent);
-  font-size: clamp(3.5rem, 12vw, 5.25rem);
+  font-size: clamp(3.25rem, 15vw, 5.75rem);
   font-variant-numeric: tabular-nums;
-  font-weight: 900;
-  letter-spacing: -0.065em;
+  font-weight: 850;
+  letter-spacing: -0.045em;
   line-height: 1;
+  white-space: nowrap;
 }
 
-.total-pending {
-  color: var(--muted);
-  font-size: clamp(2.25rem, 8vw, 3.5rem);
-  letter-spacing: -0.045em;
+.total-placeholder {
+  color: var(--grid);
 }
 
-.metric-description {
-  margin: 0.65rem 0 0;
+.total-empty {
   color: var(--muted-dark);
-  font-size: 0.875rem;
 }
 
-.metric-description strong {
+.metric-label {
+  margin: 0.6rem 0 0;
   color: var(--foreground);
+  font-size: 1rem;
   font-weight: 700;
 }
 
-.metric-tagline {
-  margin: 0.4rem 0 0;
-  color: var(--muted-dark);
-  font-size: 0.8rem;
+.metric-scope {
+  margin: 0.25rem 0 0;
+  color: var(--muted);
+  font-size: 0.875rem;
 }
 
-.status-row {
-  display: flex;
-  min-height: 1.5rem;
-  align-items: center;
-  justify-content: center;
-  gap: 0.5rem;
-  margin-top: 0.4rem;
-  color: var(--muted-dark);
-  font-size: 0.75rem;
+.metric-status {
+  margin: 0.5rem 0 0;
+  color: var(--muted);
+  font-size: 0.8rem;
 }
 
-.status-row.error {
-  color: var(--danger);
+/* ── Chart ─────────────────────────────────────────────── */
+
+.chart-frame {
+  margin: 2rem 0 0;
+  text-align: left;
 }
 
-.spinner {
-  width: 0.75rem;
-  height: 0.75rem;
-  flex: none;
-  border: 2px solid rgba(56, 189, 248, 0.2);
-  border-top-color: var(--accent);
-  border-radius: 999px;
-  animation: spin 0.85s linear infinite;
+.chart-head {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 0.25rem 1rem;
+  margin-bottom: 0.6rem;
 }
 
-.retry-button {
-  margin-left: 0.25rem;
-  border: 0;
-  border-bottom: 1px solid currentColor;
-  padding: 0;
-  background: transparent;
-  color: inherit;
-  cursor: pointer;
-  font-weight: 700;
+.chart-title {
+  margin: 0;
+  color: var(--muted);
+  font-size: 0.78rem;
+  font-weight: 400;
 }
 
-.retry-button:focus-visible {
-  outline: 2px solid var(--accent);
-  outline-offset: 4px;
+.chart-readout {
+  margin: 0;
+  color: var(--muted);
+  font-size: 0.78rem;
+  font-variant-numeric: tabular-nums;
 }
 
-/* ── Chart ─────────────────────────────────────────────── */
+.chart-readout strong {
+  color: var(--foreground);
+  font-weight: 400;
+}
 
-.chart-frame {
+.chart-plot {
   position: relative;
-  width: 100%;
-  height: 16rem;
-  margin-top: 1rem;
+  height: 13.5rem;
 }
 
-.chart-frame svg {
+.chart-plot svg {
   display: block;
   width: 100%;
   height: 100%;
   overflow: visible;
+  cursor: crosshair;
+  outline: none;
+  touch-action: pan-y;
 }
 
-.chart-empty {
-  display: grid;
-  height: 100%;
-  place-items: center;
-  color: var(--muted-dark);
-  font-size: 0.8rem;
+.chart-plot svg:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 4px;
+  border-radius: 4px;
 }
 
 .chart-grid {
@@ -186,10 +223,8 @@ select {
   vector-effect: non-scaling-stroke;
 }
 
-.chart-y-label {
-  fill: var(--muted);
-  font-size: 12px;
-  font-variant-numeric: tabular-nums;
+.chart-area {
+  fill: url(#area-gradient);
 }
 
 .chart-line {
@@ -197,18 +232,192 @@ select {
   stroke: var(--accent);
   stroke-linecap: round;
   stroke-linejoin: round;
-  stroke-width: 3;
+  stroke-width: 2.5;
   vector-effect: non-scaling-stroke;
-  /* Draw animation — uses a very large dasharray; the offset animates to 0 */
-  stroke-dasharray: 2000;
-  stroke-dashoffset: 2000;
-  animation: draw-line var(--anim-duration) ease-out forwards;
 }
 
-.chart-area {
-  fill: url(#area-gradient);
-  opacity: 0;
-  animation: fade-area var(--anim-duration) ease-out forwards;
+.chart-guide {
+  stroke: var(--muted-dark);
+  stroke-width: 1;
+  stroke-dasharray: 3 4;
+  vector-effect: non-scaling-stroke;
+}
+
+.chart-dot {
+  position: absolute;
+  width: 11px;
+  height: 11px;
+  border: 2px solid var(--card);
+  border-radius: 50%;
+  background: var(--accent);
+  box-shadow: 0 0 0 4px var(--accent-soft);
+  transform: translate(-50%, -50%);
+  pointer-events: none;
+}
+
+.chart-y-axis {
+  position: absolute;
+  inset: 0 auto 0 0;
+  width: calc(64 / 760 * 100%);
+  pointer-events: none;
+}
+
+.chart-y-axis span {
+  position: absolute;
+  right: 0.6rem;
+  transform: translateY(-50%);
+  color: var(--muted-dark);
+  font-size: 0.72rem;
+  font-variant-numeric: tabular-nums;
+}
+
+.chart-x-axis {
+  position: absolute;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  height: 1.1rem;
+  pointer-events: none;
+}
+
+.chart-x-axis span {
+  position: absolute;
+  bottom: 0;
+  transform: translateX(-50%);
+  color: var(--muted-dark);
+  font-size: 0.72rem;
+  white-space: nowrap;
+}
+
+/* ── Agent setup ───────────────────────────────────────── */
+
+.setup {
+  display: grid;
+  justify-items: center;
+  gap: 0.55rem;
+  margin-top: 1.75rem;
+  padding-top: 1.5rem;
+  border-top: 1px solid var(--surface-border);
+}
+
+.setup-title {
+  margin: 0;
+  font-size: 1.05rem;
+  font-weight: 750;
+}
+
+.setup-description {
+  margin: 0;
+  color: var(--muted);
+  font-size: 0.92rem;
+}
+
+.setup-row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: center;
+  gap: 0.6rem 1rem;
+  width: 100%;
+  margin-top: 0.35rem;
+}
+
+.setup-command {
+  display: flex;
+  flex: 0 1 25rem;
+  align-items: center;
+  gap: 0.6rem;
+  min-width: 0;
+  min-height: 2.75rem;
+  padding: 0.3rem 0.3rem 0.3rem 0.9rem;
+  border: 1px solid var(--surface-border);
+  border-radius: 0.7rem;
+  background: var(--command-bg);
+  text-align: left;
+}
+
+.setup-prompt {
+  color: var(--muted-dark);
+  font-family: var(--font-geist-mono), ui-monospace, monospace;
+  font-size: 0.9rem;
+  user-select: none;
+}
+
+.setup-command code {
+  flex: 1;
+  min-width: 0;
+  color: var(--foreground);
+  font-family: var(--font-geist-mono), ui-monospace, monospace;
+  font-size: 0.9rem;
+  overflow-wrap: anywhere;
+  user-select: all;
+}
+
+.setup-copy {
+  display: inline-flex;
+  min-width: 2.5rem;
+  height: 2.25rem;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  gap: 0.35rem;
+  padding: 0 0.55rem;
+  border: 0;
+  border-radius: 0.5rem;
+  background: transparent;
+  color: var(--muted);
+  cursor: pointer;
+}
+
+.setup-copy:hover {
+  background: var(--accent-soft);
+  color: var(--foreground);
+}
+
+.copy-feedback {
+  color: var(--accent);
+  font-size: 0.8rem;
+  font-weight: 700;
+}
+
+.setup-copy:focus-visible,
+.catalog-link:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 3px;
+}
+
+.catalog-link {
+  display: inline-flex;
+  min-height: 2.75rem;
+  align-items: center;
+  padding: 0 0.4rem;
+  border-radius: 0.5rem;
+  color: var(--accent);
+  font-size: 0.92rem;
+  font-weight: 700;
+  text-underline-offset: 4px;
+}
+
+.catalog-link:hover {
+  color: var(--accent-strong);
+}
+
+.setup-help {
+  margin: 0;
+  color: var(--muted);
+  font-size: 0.82rem;
+}
+
+.setup-prompt-hint {
+  max-width: 30rem;
+  margin: 0.35rem 0 0;
+  color: var(--muted-dark);
+  font-size: 0.8rem;
+  line-height: 1.5;
+}
+
+.setup-prompt-hint q {
+  color: var(--muted);
 }
 
 /* ── Admin ─────────────────────────────────────────────── */
@@ -414,63 +623,48 @@ select {
   color: var(--danger);
 }
 
-/* ── Keyframes ────────────────────────────────────────── */
-
-@keyframes spin {
-  to { transform: rotate(360deg); }
-}
-
-@keyframes draw-line {
-  to { stroke-dashoffset: 0; }
-}
-
-@keyframes fade-area {
-  0%  { opacity: 0; }
-  40% { opacity: 0; }
-  100% { opacity: 1; }
-}
-
 /* ── Responsive ───────────────────────────────────────── */
 
 @media (max-width: 640px) {
   .dashboard-shell {
-    align-items: stretch;
-    padding: 0;
+    padding: 0.75rem;
   }
 
   .dashboard-card {
-    min-height: 100vh;
-    border: 0;
-    border-radius: 0;
+    padding: 1.6rem 1.15rem 1.25rem;
+    border-radius: 1.25rem;
   }
 
-  .dashboard-content {
-    padding: 3rem 1.25rem 2rem;
+  .title {
+    font-size: clamp(1.55rem, 7.4vw, 1.75rem);
+  }
+
+  .description {
+    font-size: 0.95rem;
   }
 
   .metric-block {
-    margin-top: 3rem;
+    margin-top: 1.9rem;
   }
 
-  .chart-frame {
-    height: 14rem;
-    margin-top: 2rem;
+  .chart-plot {
+    height: 11.5rem;
   }
-}
 
-@media (prefers-reduced-motion: reduce) {
-  .spinner {
-    animation-duration: 2s;
+  .chart-x-axis .tick-wide-only {
+    display: none;
+  }
+
+  .setup-row {
+    flex-direction: column;
+    align-items: stretch;
   }
 
-  .chart-line {
-    stroke-dasharray: none;
-    stroke-dashoffset: 0;
-    animation: none;
+  .setup-command {
+    flex-basis: auto;
   }
 
-  .chart-area {
-    opacity: 1;
-    animation: none;
+  .catalog-link {
+    justify-content: center;
   }
 }

package/app/layout.tsx

@@ -1,6 +1,5 @@
 import type { Metadata } from "next";
 import { Geist, Geist_Mono } from "next/font/google";
-import { PACKAGE_SCOPE } from "@/lib/config";
 import "./globals.css";
 
 const geistSans = Geist({
@@ -13,11 +12,9 @@ const geistMono = Geist_Mono({
   subsets: ["latin"],
 });
 
-const scopeDisplay = PACKAGE_SCOPE.replace(/\/$/, "");
-
 export const metadata: Metadata = {
-  title: `${scopeDisplay} Total Downloads`,
-  description: `Live cumulative downloads across every public ${scopeDisplay} npm package.`,
+  title: "x12i · SDK ecosystem",
+  description: "The SDK ecosystem built for coding agents: reusable packages for data, intelligence, logic, presentation and tools. npm downloads across the x12i package catalog.",
   other: {
     "codex-preview": "development",
   },