@shiinasaku/github-card 4.1.0 → 5.0.0

package/README.md

@@ -1,46 +1,111 @@
 <div align="center">
 
-<img src="assets/logo.svg" alt="GitHub Card" width="480" />
+<img src="assets/logo.svg" alt="GitHub Card" width="520" />
 
-# GitHub Card
+### Beautiful, blazing-fast GitHub profile cards
 
-**Beautiful, blazing-fast GitHub profile cards as dynamic SVGs.**
-Drop one line in your README — get a live, auto-updating stats card.
+Live SVG cards for your README — stars, commits, languages, all auto-updating. One line, zero config, edge-cached.
 
-[![Bun](https://img.shields.io/badge/Bun-1.x-f9f1e1?style=flat-square&logo=bun&logoColor=000)](assets/bun.svg)
-[![Elysia](https://img.shields.io/badge/ElysiaJS-1.x-7c3aed?style=flat-square)](assets/elysia.svg)
+<br/>
+
+[![npm](https://img.shields.io/npm/v/@shiinasaku/github-card?style=flat-square&label=npm&color=000)](https://www.npmjs.com/package/@shiinasaku/github-card)
+[![Bun](https://img.shields.io/badge/Bun-1.x-f9f1e1?style=flat-square&logo=bun&logoColor=000)](https://bun.sh)
+[![Elysia](https://img.shields.io/badge/Elysia-2_RC-7c3aed?style=flat-square)](https://next.elysiajs.com)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?style=flat-square&logo=typescript&logoColor=fff)](https://www.typescriptlang.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-34d399?style=flat-square)](LICENSE)
 [![Deploy with Vercel](https://img.shields.io/badge/Deploy-Vercel-000?style=flat-square&logo=vercel)](https://vercel.com/new/clone?repository-url=https://github.com/ShiinaSaku/Github-Card)
 
-<img src="https://card.shiina.xyz/card/shiinasaku?theme=shiina" alt="Live demo card" width="500" />
+<a href="https://card.shiina.xyz/card/shiinasaku?theme=shiina">
+  <img src="https://card.shiina.xyz/card/shiinasaku?theme=shiina" alt="Live demo — shiinasaku" width="520" />
+</a>
+
+<sub>Live instance · <code>shiinasaku</code> · theme <code>shiina</code> — updates itself as you code</sub>
 
 </div>
 
 ---
 
+### ✨ What's new in 4.2
+
+> System-font only · no shipped `.woff2` · crisper text (`geometricPrecision`, tabular numbers) · new 24 px icons (MingCute / Huge / Tabler) · airy stat stack with 7 px gaps, no boxes · default `affiliations=owner` — org stars excluded unless `?affiliations=affiliated` · fully typed `github.ts` & `github-client`, cache v9.
+
+---
+
 ## Quickstart
 
-Paste this into your profile README (replace `shiinasaku` with your username):
+Paste into your profile README — replace `shiinasaku` with your username:
 
 ```md
 [![GitHub Card](https://card.shiina.xyz/card/shiinasaku?theme=shiina)](https://github.com/shiinasaku)
 ```
 
-That's it. No sign-up, no build step — the card updates itself as you code.
+That's it. No sign-up, no build — the card refreshes automatically as cached data expires.
+
+<details>
+<summary><b>Self-host / local dev</b></summary>
+
+Requires Bun 1.4.4 or newer. The API uses Elysia 2 RC with pinned framework and plugin versions.
+
+```bash
+bun install
+cp .env.example .env   # add GITHUB_TOKEN
+bun dev                # http://localhost:3000
+```
+
+| Command             | Action               |
+| ------------------- | -------------------- |
+| `bun test`          | Run tests            |
+| `bun run typecheck` | Native `bun check`   |
+| `bun run fmt`       | Bun native formatter |
+| `bun run fmt:check` | Check formatting     |
+
+Formatting uses Bun's built-in `bun fmt`; no separate formatter or linter is installed.
+Bun 1.4.4 does not provide a built-in `bun lint` command. `bun check` enforces strict typing and
+unused-symbol checks. TypeScript is retained only to emit the library’s `.d.ts` files during builds.
+
+`src/index.ts` serves as the entrypoint for Vercel and local development, starting a listener
+only when run directly. The rendering library is unchanged.
+
+</details>
+
+---
 
 ## Why GitHub Card?
 
-- **One line, zero config** — an `<img>` tag is the entire integration.
-- **Edge-fast** — two-tier cache (in-memory + Redis) with stale-while-revalidate, ETag/304 support, and CDN cache headers. Warm requests render in microseconds.
-- **21 hand-tuned themes** — plus full per-slot color overrides with hex _or_ Tailwind palette tokens.
-- **Retina avatars** — profile images inlined as Base64 at 2x resolution.
-- **Adaptive layout** — width, text wrapping, and language legends are computed mathematically; nothing ever overlaps.
-- **Users _and_ orgs** — works for organization accounts out of the box.
-- **Glassmorphic depth** — layered ambient gradients track your accent color for volumetric light with zero runtime cost (pure SVG).
-- **OpenAPI documented** — explore the API interactively at [`/openapi`](https://card.shiina.xyz/openapi).
+<table>
+<tr>
+<td width="50%">
+
+**One line, zero config**<br/>
+An `<img>` tag is the entire integration. No OAuth, no action.
+
+**Edge-fast**<br/>
+L1 memory + L2 Redis SWR, `s-maxage=1800`, `stale-while-revalidate`, `ETag`/`304`. Warm hits render in microseconds.
+
+**Retina avatars**<br/>
+Profile images inlined as Base64 at 2×, clipped + ringed in pure SVG.
+
+</td>
+<td width="50%">
+
+**Adaptive layout**<br/>
+Width, wrapping, and legends measured with per-glyph metrics — nothing ever overlaps or clips.
+
+**Users _and_ orgs**<br/>
+`GET /card/:login` works for users and organizations.
+
+**Glassmorphic depth**<br/>
+Radial + linear ambient gradients track your accent for volumetric light at zero runtime cost.
+
+</td>
+</tr>
+</table>
+
+OpenAPI docs live at [`/openapi`](https://card.shiina.xyz/openapi). Pure ESM lib, zero server dep for `renderCard`.
+
+---
 
-## Themes
+## Themes — 21 hand-tuned
 
 Preview **every** theme with your own data:
 
@@ -54,31 +119,51 @@ Preview **every** theme with your own data:
 | `github_dark` · `dark` · `nord` · `dracula`        | `forest` · `rose` · `cobalt`                     |
 | `tokyonight` · `synthwave` · `radical` · `monokai` | `gruvbox` · `merko` · `onedark` · `highcontrast` |
 
+Add `?theme=tokyonight` or override any slot with hex or Tailwind tokens: `pink-400`, `#ff79c6`, `ff79c6`.
+
+---
+
 ## Customization
 
-Every visual slot is overridable. Colors accept hex (`ff79c6` or `#ff79c6`) and Tailwind tokens (`pink-400`).
-
-| Parameter      | Type     | Description                                                        |
-| -------------- | -------- | ------------------------------------------------------------------ |
-| `theme`        | string   | Built-in theme name (see table above)                              |
-| `bg_color`     | string   | Background fill                                                    |
-| `title_color`  | string   | Name / title text                                                  |
-| `text_color`   | string   | Stats, labels, and body text                                       |
-| `icon_color`   | string   | Stat icons and ambient glow                                        |
-| `border_color` | string   | Card outline stroke                                                |
-| `hide_border`  | boolean  | Remove the card outline                                            |
-| `compact`      | boolean  | Slim layout: hides bio, pronouns, Twitter, and the language legend |
-| `animate`      | boolean  | Fade-in stats + animated language bar                              |
-| `hide`         | string[] | Hide stats: `stars`, `commits`, `issues`, `repos`, `prs`           |
-| `hide_langs`   | string[] | Exclude languages by name (`hide_langs=html,css`)                  |
-| `show_langs`   | string[] | Include _only_ these languages                                     |
-| `lang_count`   | 1–10     | Number of top languages (default `5`)                              |
-| `scope`        | string   | `personal` (default), `org`, or `all` contribution scope           |
-| `orgs`         | string[] | Restrict org-scope stats to these organizations                    |
-| `affiliations` | string   | `affiliated` (default) or `owner` repositories                     |
-| `fields`       | string[] | Fetch only what you need (e.g. `fields=stats`)                     |
-
-### Examples
+| Parameter      |    Type    | Description                                                       |
+| -------------- | :--------: | ----------------------------------------------------------------- |
+| `theme`        |  `string`  | Built-in theme (table above)                                      |
+| `bg_color`     |  `string`  | Background fill                                                   |
+| `title_color`  |  `string`  | Name / title                                                      |
+| `text_color`   |  `string`  | Stats, labels, body                                               |
+| `icon_color`   |  `string`  | Icons + ambient glow                                              |
+| `border_color` |  `string`  | Card outline                                                      |
+| `hide_border`  | `boolean`  | Remove outline                                                    |
+| `compact`      | `boolean`  | Slim — hides bio/pronouns/Twitter/legend                          |
+| `animate`      | `boolean`  | Fade-in stats + animated language bar                             |
+| `hide`         | `string[]` | Hide stats: `stars`, `commits`, `issues`, `repos`, `prs`          |
+| `hide_langs`   | `string[]` | Exclude `hide_langs=html,css`                                     |
+| `show_langs`   | `string[]` | Only `show_langs=typescript,rust`                                 |
+| `lang_count`   |   `1–10`   | Top languages (default `5`)                                       |
+| `scope`        |  `string`  | `personal` (default), `org`, `all`                                |
+| `orgs`         | `string[]` | Restrict org stats to `orgs=vercel,elysiajs`                      |
+| `affiliations` |  `string`  | `owner` (default) or `affiliated` — org stars excluded by default |
+| `fields`       | `string[]` | Fetch only `fields=stats` for speed                               |
+
+#### What the numbers mean
+
+- Stars, repositories, and languages come from non-fork repositories in the requested scope.
+  `affiliations=owner` is the default for both the HTTP API and `getProfileData`.
+- User commits are contributions credited by GitHub from January 1 (UTC) to now, not lifetime
+  commit counts. Default user PR/issue totals are lifetime authored totals. With `scope=org`,
+  commits, PRs, and issues are this year's contributions to the selected organizations.
+- `scope=all` combines personal and contributed organization repositories without counting a repo
+  twice; its activity totals remain the user's totals. `orgs` filters the organization portion.
+- Organization accounts have repository/star/language data, but no computed activity totals.
+  Those metrics display `—` (and are `null` in `UserStats`), not a misleading zero.
+- Language filters run before `lang_count`. Percentages describe the displayed languages by code
+  size, not time spent coding. The bar and legend use the same “Other” group.
+- Results depend on what the GitHub token can access. GitHub's query limits still apply:
+  the top 10 languages per repository and up to 100 repositories in each org contribution
+  breakdown. Repository pagination supports up to 10,000 repos per connection; reaching that
+  limit with more pages remaining returns an error rather than caching incomplete totals.
+
+#### Examples
 
 ```md
 <!-- Dracula, no border, animated -->
@@ -89,107 +174,106 @@ Every visual slot is overridable. Colors accept hex (`ff79c6` or `#ff79c6`) and
 
 ![card](https://card.shiina.xyz/card/shiinasaku?bg_color=0d1117&title_color=58a6ff&text_color=9da7b3&icon_color=58a6ff)
 
-<!-- Compact, stats only, no languages -->
+<!-- Compact, no issues/prs -->
 
 ![card](https://card.shiina.xyz/card/shiinasaku?compact=true&hide=issues,prs&fields=stats)
 
-<!-- Organization card -->
+<!-- Include org stars explicitly -->
+
+![card](https://card.shiina.xyz/card/shiinasaku?affiliations=affiliated)
+
+<!-- Organization -->
 
 ![card](https://card.shiina.xyz/card/elysiajs)
 ```
 
+---
+
 ## Deploy your own
 
 [![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/ShiinaSaku/Github-Card)
 
-1. Click the button above (or fork + import into Vercel).
-2. Add environment variables:
+1. Click the button (or fork + import).
+2. Add env vars:
 
-   | Variable       | Required | Purpose                                   |
-   | -------------- | -------- | ----------------------------------------- |
-   | `GITHUB_TOKEN` | ✅       | GitHub PAT (read-only is enough)          |
-   | `REDIS_URL`    | ➖       | Redis/Upstash URL for the shared L2 cache |
+|    Variable    | Required | Purpose                             |
+| :------------: | :------: | ----------------------------------- |
+| `GITHUB_TOKEN` |    ✅    | GitHub PAT — read-only is enough    |
+|  `REDIS_URL`   |    ➖    | Redis / Upstash for shared L2 cache |
 
-3. Done. Your instance serves `/card/:username` on Vercel's CDN with `s-maxage=1800, stale-while-revalidate=1800`.
+3. Done — serves `/card/:username` on Vercel CDN `s-maxage=1800, stale-while-revalidate=1800`.
 
-> Redis is optional — without it, the in-memory cache still keeps each warm instance fast.
+> Without Redis, bounded in-memory cache (1000 entries, SWR 30 min) still keeps warm instances fast.
+
+---
 
 ## API
 
 | Endpoint                | Description                                 |
 | ----------------------- | ------------------------------------------- |
-| `GET /card/:username`   | SVG card (all query params above)           |
-| `GET /:username/themes` | One SVG showing **all themes** for a user   |
+| `GET /card/:username`   | SVG card — all params above                 |
+| `GET /:username/themes` | One SVG with **all themes** for a user      |
 | `GET /meta`             | Service metadata + theme list               |
 | `GET /health`           | Uptime, cache telemetry, Redis reachability |
 | `GET /openapi`          | Interactive OpenAPI docs                    |
 
-Responses are `image/svg+xml` with `ETag`, CORS (`*`), and CDN cache headers. Conditional requests (`If-None-Match`) return `304`.
+Responses: `image/svg+xml`, `ETag` + `CDN-Cache-Control` + CORS `*`. Conditional `If-None-Match` → `304`.
+
+---
 
 ## Use as a library
 
 ```bash
 bun add @shiinasaku/github-card     # Bun
-npm install @shiinasaku/github-card # Node / Next.js / Vite
+npm install @shiinasaku/github-card # Node / Next / Vite
 ```
 
 ```ts
 import { renderCard, themes } from "@shiinasaku/github-card";
 
 const svg = renderCard(user, stats, languages, { theme: "tokyonight" });
+// → SVG string, no network or server required
 ```
 
-Ships as a prebuilt ESM bundle with full `.d.ts` types (Bun resolves the raw TypeScript source automatically via the `bun` export condition). The renderer is pure — no server, no network, works in any JS runtime.
+Prebuilt `dist/lib.js` + `.d.ts`; Bun resolves raw TS via `bun` export condition. Pure renderer — no network, no server.
 
-## Releasing
+---
 
-Releases are fully automated:
+## Architecture
 
-1. **Actions → Bump** → choose `patch` / `minor` / `major`.
-2. The workflow bumps `package.json`, commits, and tags `vX.Y.Z`.
-3. The tag triggers **Release**: format, lint, typecheck, tests, dist build, tag↔version guard, `npm pack` verification, then publish to npm with [provenance](https://docs.npmjs.com/generating-provenance-statements) and a GitHub Release with auto-generated notes.
+```mermaid
+flowchart LR
+  A[GET /card/:username] --> B[Elysia<br/>validation · CORS · OpenAPI · timing]
+  B --> C{L1 memory<br/>SWR 30m}
+  C -- hit --> G[render SVG<br/>ETag/304 → CDN]
+  C -- miss --> D{L2 Redis<br/>SWR 30m}
+  D -- hit --> G
+  D -- miss --> E[GitHub GraphQL<br/>100/page, up to 100 pages, 6s/request]
+  E --> F[typed fetch<br/>+ avatar 150px]
+  F --> G
+  G --> H[Pure SVG<br/>system fonts · measured layout · glass]
+```
 
-## Local development
+- **Bun + Elysia** — one of the fastest HTTP stacks.
+- **Two-tier SWR** — stale served instantly + background refresh, request coalescing via `inFlight`.
+- **Typed upstream** — `RepoNode`/`ContributionEntry` generics, `T=unknown`, `TimeoutError`/`RateLimitError` mapping.
 
-```bash
-bun install
-cp .env.example .env   # add your GITHUB_TOKEN
-bun dev                # http://localhost:3000
-```
+---
 
-| Command             | Action                |
-| ------------------- | --------------------- |
-| `bun test`          | Run the test suite    |
-| `bun run typecheck` | Strict `tsc --noEmit` |
-| `bun run lint`      | oxlint                |
-| `bun run fmt`       | oxfmt                 |
+## Releasing
 
-## Architecture
+Fully automated:
 
-```
-GET /card/:username
-      │
-      ▼
-Elysia (validation, CORS, OpenAPI, server-timing)
-      │
-      ▼
-L1 in-memory cache ──hit──► render SVG ──► ETag/304 ──► CDN
-      │miss                         ▲
-      ▼                             │ stale-while-revalidate
-L2 Redis (SWR) ──hit──► serve stale + background refresh
-      │miss
-      ▼
-GitHub GraphQL (batched, paginated 100/page, 6s timeout)
-      │
-      ▼
-Pure SVG renderer (zero-dependency, dynamic layout engine)
-```
+1. **Actions → Bump** → `patch` / `minor` / `major`.
+2. Workflow bumps `package.json`, commits, tags `vX.Y.Z`.
+3. Tag triggers **Release**: `bun fmt --check` · `bun check` · `tests` · `dist` build · tag↔version guard · `npm pack` verify → publish with [provenance](https://docs.npmjs.com/generating-provenance-statements) + GitHub Release.
 
-- **Bun + Elysia** — one of the fastest HTTP stacks available.
-- **Two-tier SWR cache** — users never wait on GitHub's API.
-- **Request coalescing** — concurrent misses share a single upstream fetch.
-- **Defensive upstream** — timeouts, size caps, and typed errors (`401/404/429/502`).
+---
 
-## License
+<div align="center">
 
-[MIT](LICENSE) © [saku shiina](https://www.shiina.xyz)
+**[MIT](LICENSE) © [saku shiina](https://www.shiina.xyz)** — built with Bun, Elysia, and system fonts.
+
+<sub>Stars default to <code>owner</code> only in 4.2 — add <code>?affiliations=affiliated</code> to include orgs.</sub>
+
+</div>

package/dist/card.d.ts

@@ -1,16 +1,3 @@
-import type { UserProfile, UserStats, LanguageStat } from "./types";
-export type CardOpts = {
-    theme?: string;
-    title_color?: string;
-    text_color?: string;
-    icon_color?: string;
-    bg_color?: string;
-    border_color?: string;
-    hide_border?: boolean;
-    compact?: boolean;
-    hide?: string[];
-    hide_langs?: string[];
-    show_langs?: string[];
-    animate?: boolean;
-};
+import type { UserProfile, UserStats, LanguageStat, CardOptions } from "./types";
+export type CardOpts = CardOptions;
 export declare function renderCard(user: UserProfile, stats: UserStats, langs: LanguageStat[], opts?: CardOpts): string;

package/dist/lib.d.ts

@@ -7,7 +7,7 @@
 export { renderCard, type CardOpts } from "./card";
 export type { UserProfile, UserStats, LanguageStat, ProfileData, CardOptions } from "./types";
 export { themes, resolveColors, type Theme } from "./utils/themes";
-export { kFormat, escapeXml, wrapText } from "./utils/format";
+export { kFormat, escapeXml, wrapText, measureText } from "./utils/format";
 export { icons, icon } from "./utils/icons";
 export { getLangColor } from "./utils/languages";
 export { FONT_FACE, FONT_FAMILY } from "./utils/font";