@highjumpdigitalsoftware/blog-kit 0.6.0

package/INTEGRATION.md

@@ -0,0 +1,76 @@
+# Onboarding a site to blog-kit
+
+The repeatable recipe to point a site's `/blog` at the kit. Works for **Next.js** (React adapter) and **Astro** (Astro adapter) — the steps are identical except the adapter and how you load behaviours. This codifies the proven Capture AI integration.
+
+Mental model (5 steps): **drawer → paint → plug in → register → publish.**
+
+```
+content repo (theirs)        site repo (thin /blog route)        blog-publisher MCP
+  posts/*.mdx                  vendored src/_blogkit/              writes posts here
+  images/*                     /blog route + sync + theme         reads the manifest
+  theme.json  ────compiled───► _theme.css (.blog-root tokens)
+```
+
+---
+
+## 1. Drawer — content repo
+Create (or reuse) the site's content repo holding `content/posts/*.mdx`, `content/images/`, and a `content/theme.json` (see `templates/theme.example.json`). The site already fetches this at build (the existing `fetch-blog` step).
+
+## 2. Paint — theme
+Author `theme.json` (brand colours + font families only — everything else inherits the kit's neutral defaults). At build, compile it to the per-tenant token stylesheet:
+```
+node scripts/theme-to-css.mjs blog/content/theme.json src/app/blog/_theme.css
+```
+Map fonts to the host's `next/font` (or Astro font) CSS variables, e.g. `--blog-font-display: var(--font-cairo), 'Cairo', sans-serif`.
+
+## 3. Plug in — vendor the kit + wire the route
+- Copy `templates/sync-blog-kit.mjs` into the site's `scripts/` and run it once to vendor the kit into `src/_blogkit/` (`BLOG_KIT_ADAPTER=astro` for an Astro site). **COMMIT `src/_blogkit/` to the repo — do NOT gitignore it.** The build env (e.g. Railway) has no access to the canonical kit, so the vendored copy must be present in the repo or the `@/_blogkit` import fails the build. To update later: re-run the sync script, then commit the refreshed `src/_blogkit/`. (This is also what makes the site survive a disconnect — the rendering code lives in its own repo.)
+- **Load the CSS** in the blog route/layout, **after** the kit core:
+  ```ts
+  import "@/_blogkit/core/css/index.css";
+  import "./_theme.css";
+  ```
+- **Render the post body under `.blog-root`** with the kit's render map. Drop any host `prose`/design-system wrapper — the kit owns prose typography:
+  - **Next.js** (`/blog/[slug]` or root `/[slug]`):
+    ```tsx
+    import { MDXRemote } from "next-mdx-remote/rsc";   // v6+ required
+    import { blogComponents } from "@/_blogkit/react";
+    // ...
+    <div className="blog-root">
+      <div className="bk-prose">
+        <MDXRemote source={post.content} components={{ ...blogComponents, ...siteCustom }}
+          options={{ blockJS: false, mdxOptions: { /* remark/rehype */ } }} />
+      </div>
+    </div>
+    ```
+    ⚠️ **`next-mdx-remote` must be v6+ with `blockJS:false`.** v5 defaults to stripping JSX-expression attributes (`score={8}`), which silently breaks kit components.
+  - **Astro** (content collection): pass the kit's astro components to `<Content components={...} />` inside a `<div class="blog-root">`.
+- **Per-site custom components** (true one-offs) live in the site, merged on top: `{ ...blogComponents, ...siteCustom }`.
+- **Frame** components (hero, index listing) stay in the site — they're not part of the kit's MDX surface.
+
+## 4. Load behaviours (interactive components only)
+Interactive components (`TableOfContents`, `FAQList`, `ComparisonTable`, `CodeSnippet`, `KeywordTable`, `DeliveryComparison`) need their vanilla-JS behaviour activated once on the client. The kit ships a **drop-in loader** — you don't hand-roll an effect or wire individual scripts:
+
+- **Next.js:** render `<BlogBehaviors />` **once inside the post route's `.blog-root`** (it renders nothing):
+  ```tsx
+  import { blogComponents, BlogBehaviors } from "@/_blogkit/react";
+  // ...
+  <div className="blog-root">
+    <BlogBehaviors />
+    <div className="bk-prose"><MDXRemote … /></div>
+  </div>
+  ```
+  It re-runs on client navigation (keyed on the pathname) so a freshly mounted post gets wired.
+- **Astro:** drop `<BlogBehaviors />` from `@/_blogkit/astro/BlogBehaviors.astro` once inside the post layout's `.blog-root`. It runs on load and on `astro:page-load` (View Transitions).
+
+Under the hood the loader calls `initBlogBehaviors()` from `core/behaviors/index.js`, which fans out to each behaviour. Every behaviour is framework-neutral, **idempotent** (re-running only wires not-yet-enhanced markup), and a no-op when its component isn't on the page. The `TableOfContents` scans the prose region that contains it (`.bk-prose` → `.blog-root`), so it works without the site wrapping the body in any particular tag.
+
+## 5. Register — MCP
+In `blog-publisher/sites/<id>.json`, set `components` to the kit names the site exposes (+ optional `customComponents`, `+` the repo/deploy/brand blocks). The MCP reads the vendored manifest, so docs come for free; boot warns on any name not in the manifest.
+
+---
+
+## Notes
+- **URL shape is preserved per site** — parameterise the route prefix (Capture serves `/blog/[slug]`, HJD serves root `/[slug]`). Never change existing slugs.
+- **Old component names** keep working via the kit's alias map (e.g. `PullQuote`→`QuoteBlock`), so existing posts don't break during migration.
+- **Ownership / disconnect:** the content repo (theirs) + the vendored kit copy keep rendering with zero dependency on the MCP. The MCP is only the writer.

package/LICENSE

@@ -0,0 +1,74 @@
+High Jump Digital — Blog Kit Software Licence
+
+Copyright © High Jump Digital. All rights reserved.
+
+This software, including its source code, components, build output, and
+accompanying documentation (the "Software"), is proprietary and confidential to
+High Jump Digital ("High Jump Digital", "we", "us"). It is licensed, not sold.
+The Software is published to a public package registry only so that it can be
+installed conveniently; that public availability does not make the Software open
+source and does not grant any rights beyond those set out below.
+
+1. GRANT OF USE
+   Subject to the terms of this Licence, High Jump Digital grants a limited,
+   non-exclusive, non-transferable, revocable licence to use the Software to:
+   (a) High Jump Digital; and
+   (b) any client of High Jump Digital that we have authorised,
+   solely to operate a blog or website that is built or managed by High Jump
+   Digital for that client. No other use is permitted except as expressly stated
+   in this Licence.
+
+2. YOUR RIGHT TO KEEP USING YOUR OWN SITE (NO LOCK-IN)
+   This clause overrides any restriction below that would otherwise conflict with
+   it. A client retains the right to continue using the copy of the Software that
+   is already installed or deployed on that client's own website, indefinitely,
+   including after the client's engagement with High Jump Digital has ended. That
+   continued-use right covers operating, running, and serving the client's own
+   website from that already-deployed copy. It does not, by itself, grant any
+   right to obtain new versions, redistribute the Software, or use the Software
+   for anything beyond operating that client's own website.
+
+3. RESTRICTIONS
+   Except as expressly permitted in clauses 1 and 2, you may not:
+   (a) redistribute, resell, rent, lease, sublicense, publish, or otherwise make
+       the Software available to any third party;
+   (b) use the Software, or any part of it, to build, train, or operate any
+       product or service that competes with High Jump Digital;
+   (c) permit any party that High Jump Digital has not authorised to use the
+       Software, except for a client's continued-use right under clause 2;
+   (d) remove, obscure, or alter any copyright, trademark, or other proprietary
+       notice in the Software; or
+   (e) reverse engineer, decompile, or disassemble the Software, except to the
+       extent that this restriction is prohibited by applicable law. For the
+       avoidance of doubt, this does not prevent a client from reading, inspecting,
+       or operating the copy of the Software deployed on that client's own website
+       as permitted by clauses 1 and 2.
+
+4. OWNERSHIP
+   The Software is and remains the property of High Jump Digital. All right, title,
+   and interest in and to the Software, including all intellectual property rights,
+   remain with High Jump Digital. This Licence grants a right to use the Software
+   only; it does not transfer ownership of the Software or any part of it.
+
+5. NO WARRANTY
+   THE SOFTWARE IS PROVIDED "AS IS" AND "AS AVAILABLE", WITHOUT WARRANTY OF ANY
+   KIND, WHETHER EXPRESS, IMPLIED, OR STATUTORY, INCLUDING WITHOUT LIMITATION ANY
+   IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE,
+   AND NON-INFRINGEMENT. HIGH JUMP DIGITAL DOES NOT WARRANT THAT THE SOFTWARE WILL
+   BE UNINTERRUPTED, ERROR-FREE, OR SECURE.
+
+6. LIMITATION OF LIABILITY
+   TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, HIGH JUMP DIGITAL SHALL NOT
+   BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR EXEMPLARY
+   DAMAGES, OR FOR ANY LOSS OF PROFITS, REVENUE, DATA, OR GOODWILL, ARISING OUT OF
+   OR RELATED TO THE SOFTWARE OR THIS LICENCE, HOWEVER CAUSED AND UNDER ANY THEORY
+   OF LIABILITY, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. NOTHING IN
+   THIS LICENCE LIMITS ANY LIABILITY THAT CANNOT BE LIMITED OR EXCLUDED UNDER
+   APPLICABLE LAW.
+
+7. GENERAL
+   If any provision of this Licence is held to be unenforceable, the remaining
+   provisions remain in full force and effect. The governing law and jurisdiction
+   for this Licence are those of the relevant High Jump Digital entity.
+
+For permissions beyond the scope of this Licence, contact High Jump Digital.

package/README.md

@@ -0,0 +1,102 @@
+# blog-kit — shared, multi-framework blog component kit
+
+One canonical component library that every blog (Next.js **or** Astro) is built from. A site supplies only its **content** (the MDX in its content repo) and its **paint** (`theme.json`); everything structural — component markup, CSS, behaviours, and the component manifest — lives here and is shared.
+
+> Canonical copy lives at `/home/dan/blog-kit` (its own standalone project — destined for its own `highjumpdigital/blog-kit` repo). It is **vendored** into each consumer at build time (a per-site `sync-blog-kit.mjs` copies `core/` + the right adapter into the site). Edit the canonical copy; never hand-edit a vendored copy. Pin each site to a kit version.
+
+---
+
+## Two ways to consume the kit
+
+The kit serves both an in-house **vendored** path and an external **installable-package** path from one source of truth.
+
+1. **Vendored (our own sites).** `sync-blog-kit.mjs` copies `core/` + the right adapter (`react/` or `astro/`) into the site's `src/_blogkit/`, committed to the site repo. This is unchanged — see [INTEGRATION.md](./INTEGRATION.md). The blog-publisher MCP reads `core/manifest/` as its single source of truth.
+2. **Installable package `@highjumpdigitalsoftware/blog-kit` (external clients).** The same `core/` + `react/` + `astro/` ship as a published npm package with three extra abilities the vendored path doesn't need. **The managed path is dual-framework: a first-class Next.js path AND a first-class Astro path** — same content API, same swappable source, same eject.
+   - **A swappable content-source adapter** — `local` (read `.mdx` from the repo) **or** `hjd-api` (fetch MDX from our per-tenant content API over Bearer auth). The two satisfy the same `ContentSource` interface (framework-neutral), so eject is a one-line `source.mode` flip on either framework.
+   - **Route surfaces + a connect/init CLI** — `<Article>` (`/blog/[slug]`) and `<BlogIndex>` (`/blog`), source-agnostic, on both frameworks. `npx @highjumpdigitalsoftware/blog-kit connect <pairing-code>` (or `init`) scaffolds the routes + an optional revalidate route + writes config/env. **The framework is taken from the exchange, else `--framework next|astro`, else sniffed from the project.**
+     - **Next.js**: App-Router **ISR** routes (`export const revalidate`), MDX rendered via `next-mdx-remote/rsc`. New posts appear with no redeploy via the ISR timer; instant via `/api/blogkit/revalidate` (`revalidatePath`).
+     - **Astro**: **SSR** routes (`output: 'server'`, `prerender:false`). Astro has no ISR and its MDX is build-time-only, so the remote MDX string is **compiled at request time** with `@mdx-js/mdx` + the kit's React component map → static HTML injected via `set:html` (identical markup to the `.astro` components, eject-safe). Freshness = SSR always-fresh + an in-process TTL cache (the ISR analogue), busted instantly by the scaffolded `/api/blogkit/revalidate` Astro endpoint. Works on a host like Replit with zero cooperation.
+   - **npm packaging** — `npm run build` (`tsc -p tsconfig.package.json` + `scripts/pkg-copy-assets.mjs`) emits `dist/`; `npm run selfcheck` is a fast Node-only sanity check. The package source lives under `package/` (`package/astro/` = the Astro managed layer); the `.astro` route surfaces ship raw under `astro/blogkit/`. **The existing `core/` / `react/` components / `astro/` components / `demo/` / manifest are untouched** (the component maps were factored into `react/components-map.ts`, re-exported by `react/index.ts` — same public surface — so the Astro render path can import the map without pulling Next).
+
+   ```bash
+   # Next.js
+   npm i @highjumpdigitalsoftware/blog-kit
+   npm i next-mdx-remote remark-gfm rehype-slug rehype-autolink-headings rehype-pretty-code
+   npx @highjumpdigitalsoftware/blog-kit connect <pairing-code>   # scaffolds Next ISR routes + writes config/env
+
+   # Astro
+   npm i @highjumpdigitalsoftware/blog-kit
+   npm i @mdx-js/mdx react react-dom remark-gfm rehype-slug rehype-autolink-headings
+   npx astro add node                              # an SSR adapter; set output:"server"
+   npx @highjumpdigitalsoftware/blog-kit connect <pairing-code>   # scaffolds Astro SSR routes (framework from the exchange)
+   ```
+   ```ts
+   // Next: app/blogkit.config.ts   ·   Astro: src/blogkit.config.ts
+   import { defineConfig } from "@highjumpdigitalsoftware/blog-kit";        // Next
+   // import { defineConfig } from "@highjumpdigitalsoftware/blog-kit/astro"; // Astro
+   export default defineConfig({
+     source: { mode: "hjd-api" },          // URL+token from BLOGKIT_CONTENT_URL / BLOGKIT_SITE_TOKEN
+     brand:  { name: "Acme Co" },          // or { mode: "local", postsDir: "content/posts" } (ejected)
+   });
+   ```
+
+   See the design doc `hjd-app/docs/managed-blog-plan.md` (§7 adapter, §8 connection/API/freshness, §9 eject). The Astro path's request-time MDX compile is the key difference from Next's ISR — both meet "new posts appear with no redeploy".
+
+---
+
+## The shape
+
+```
+core/                         framework-AGNOSTIC — the real "build once"
+  css/
+    tokens.css                --blog-* default theme, declared on .blog-root
+    base.css                  scoped reset + prose typography (isolation layer)
+    components.css            every component's .bk-* BEM styling
+    index.css                 entrypoint: @imports the three above (in order)
+  icons.ts                    shared inline SVG strings
+  lib.ts                      shared prop logic (tone resolution, cx, …)
+  behaviors/                  shared vanilla JS for interactive bits (data-bk-* hooks)
+  manifest/
+    components.json           SINGLE source of truth — the MCP reads this
+    templates.json
+    frontmatter.json
+react/                        thin .tsx wrappers + blogComponents map (Next.js)
+astro/                        thin .astro wrappers (Astro)
+demo/index.html               static preview of components across themes
+```
+
+A **component = look + wrapper.** The *look* (HTML structure + CSS) is framework-agnostic and lives in `core/`. The *wrapper* is a ~10-line shim per framework that emits the agreed markup. Restyle = edit `core/css` once → every framework + every site updates. Add a component = CSS once + a tiny wrapper in `react/` and `astro/` + a `manifest` entry.
+
+---
+
+## The build contract (every component MUST follow)
+
+1. **Styling lives only in `core/css/components.css`** as global `.bk-<name>` BEM classes. No Astro `<style>` blocks, no Tailwind, no inline `style=` with literal colours. This is what lets React and Astro render byte-identically.
+2. **Every value keys off a `--blog-*` token** (see `tokens.css`). Never hardcode a brand colour, font, radius, or shadow. A tenant re-skins by overriding tokens only.
+3. **Everything renders under `.blog-root`.** The base layer re-asserts inherited properties there, so the host page's CSS can't bleed in and the blog can't leak out. The only sanctioned inbound channel is the `--blog-*` token layer.
+4. **Shared logic goes in `core/lib.ts`; shared markup (icons) in `core/icons.ts`; shared interactivity in `core/behaviors/*.js`** (attached via `data-bk-*` attributes). Wrappers stay thin and identical across frameworks.
+5. **Both adapters emit the same tag, classes, and structure.** The React wrapper uses `className` + `dangerouslySetInnerHTML`; the Astro wrapper uses `class` + `set:html` + `<slot/>`. Nothing else should differ.
+6. **Renamed components keep an alias.** If a canonical name differs from what a live site already authored, add the old name to `aliasComponents` (React) / the Astro barrel and to the manifest entry's `aliases`, so existing published posts never break.
+7. **Add a `manifest/components.json` entry** (`description`, `props`, `example`, `role`, `recommendedFor`, `pack`, `frameworks`, `aliases`). The MCP surfaces this verbatim to authoring agents.
+
+`CalloutBox` is the reference implementation of all seven rules — copy its pattern.
+
+## Packs
+
+- **core** — universal components every site gets.
+- **capture** / **hjd** — domain packs (review/SaaS vs SEO-agency) enabled per site via the MCP's `components` allowlist.
+- per-site **custom** — code that lives in the site repo's overlay, merged into the render map; not in this kit.
+
+## Loading behaviours
+
+The handful of interactive components (`TableOfContents`, `FAQList`, `ComparisonTable`, `CodeSnippet`) get their behaviour from framework-neutral vanilla JS in `core/behaviors/*.js`. The wrappers only render the markup + a `data-bk-*` hook; **the script must be loaded once per site** for the behaviour to attach. Each script auto-initialises on `DOMContentLoaded` (and is idempotent, so loading more than once is harmless).
+
+Per-site wiring (handled by `sync-blog-kit.mjs` + the `/blog` route):
+- **Next.js** — import the needed behaviours in the blog route/layout (`import "@blogkit/core/behaviors/toc.js"`), or emit `<script src="/_blogkit/behaviors/toc.js" defer>` in the post layout.
+- **Astro** — add `<script src="/_blogkit/behaviors/toc.js"></script>` (or `import`) in the post layout.
+
+Only load the behaviours for components a site actually uses. A behaviour with no matching markup on the page is a no-op.
+
+## Theming
+
+A tenant's `theme.json` (in its content repo) is compiled to a stylesheet that overrides `--blog-*` tokens on `.blog-root`, loaded *after* `core/css/index.css`. Only brand colours + font families change; structure stays shared. See `demo/index.html` for the same components under the Capture (orange) and HJD (cyan) themes.

package/astro/AdPreview.astro

@@ -0,0 +1,64 @@
+---
+interface Props {
+  platform?: "meta" | "google";
+  brand?: string;
+  sponsored?: string;
+  copy?: string;
+  image?: string;
+  buttonText?: string;
+  site?: string;
+  url?: string;
+  headline?: string;
+  description?: string;
+  sitelinks?: string[];
+}
+
+const {
+  platform = "meta",
+  brand,
+  sponsored = "Sponsored",
+  copy,
+  image,
+  site,
+  buttonText,
+  headline,
+  url,
+  description,
+  sitelinks,
+} = Astro.props;
+---
+{platform === "google" ? (
+  <div class="bk-ad-preview bk-ad-preview--google">
+    <div class="bk-ad-preview__g-head">
+      <span class="bk-ad-preview__g-tag">Ad</span>
+      <span class="bk-ad-preview__g-dot" aria-hidden="true">·</span>
+      <span class="bk-ad-preview__g-site">{site}</span>
+    </div>
+    <div class="bk-ad-preview__g-url" set:html={url || ""} />
+    <h4 class="bk-ad-preview__g-headline">{headline}</h4>
+    <p class="bk-ad-preview__g-desc">{description}</p>
+    {sitelinks && sitelinks.length > 0 && (
+      <div class="bk-ad-preview__g-sitelinks">
+        {sitelinks.map((s) => (
+          <span class="bk-ad-preview__g-sitelink">{s}</span>
+        ))}
+      </div>
+    )}
+  </div>
+) : (
+  <div class="bk-ad-preview">
+    <div class="bk-ad-preview__head">
+      <div class="bk-ad-preview__avatar">{(brand || "").slice(0, 2).toUpperCase()}</div>
+      <div class="bk-ad-preview__head-text">
+        <div class="bk-ad-preview__brand">{brand}</div>
+        <div class="bk-ad-preview__sponsored">{sponsored}</div>
+      </div>
+    </div>
+    <div class="bk-ad-preview__copy" set:html={copy || ""} />
+    <div class="bk-ad-preview__media">{image && <img src={image} alt="" />}</div>
+    <div class="bk-ad-preview__cta">
+      <div class="bk-ad-preview__site"><strong>{site}</strong></div>
+      <button class="bk-ad-preview__btn" type="button">{buttonText || "Learn more"}</button>
+    </div>
+  </div>
+)}

package/astro/AdPreviewPair.astro

@@ -0,0 +1,10 @@
+---
+/* blog-kit Astro adapter — AdPreviewPair
+   Thin wrapper emitting the SAME markup/classes as the React adapter.
+   Styling: core/css/components.css. A layout container that lays two
+   ad-mockup cards side by side, collapsing to one column on narrow screens.
+   NOTE: deliberately no <style> block — the kit's CSS is shared/global,
+   not Astro-scoped, so React and Astro render byte-identically. */
+---
+
+<div class="bk-ad-preview-pair"><slot /></div>

package/astro/AuditFindings.astro

@@ -0,0 +1,29 @@
+---
+interface AuditFindingRow {
+  title: string;
+  description?: string;
+  count?: string | number;
+  severity?: "high" | "med" | "low";
+}
+
+interface Props {
+  rows?: AuditFindingRow[];
+}
+
+const { rows = [] } = Astro.props;
+---
+<div class="bk-audit-findings">
+  {rows.map((r) => (
+    <div class="bk-audit-findings__row">
+      <span
+        class={`bk-audit-findings__sev bk-audit-findings__sev--${r.severity || "med"}`}
+        aria-hidden="true"
+      />
+      <div class="bk-audit-findings__body">
+        <div class="bk-audit-findings__title">{r.title}</div>
+        {r.description && <div class="bk-audit-findings__desc">{r.description}</div>}
+      </div>
+      {r.count != null && <span class="bk-audit-findings__count">{r.count}</span>}
+    </div>
+  ))}
+</div>

package/astro/AuditScores.astro

@@ -0,0 +1,60 @@
+---
+interface AuditScoreItem {
+  label: string;
+  sub?: string;
+  score: number;
+}
+
+interface Props {
+  items?: AuditScoreItem[];
+}
+
+type Tone = "good" | "warn" | "bad";
+
+/** Threshold ladder ported verbatim from the hjd source. */
+function scoreTone(score: number): Tone {
+  if (score >= 80) return "good";
+  if (score >= 50) return "warn";
+  return "bad";
+}
+
+/** End point of the progress arc along the semicircle (r=40, cx=50, cy=50). */
+function arcEnd(score: number): { x: string; y: string } {
+  const angle = Math.PI * (1 - score / 100);
+  return {
+    x: (50 - 40 * Math.cos(angle)).toFixed(2),
+    y: (50 - 40 * Math.sin(angle)).toFixed(2),
+  };
+}
+
+const { items = [] } = Astro.props;
+---
+<div class="bk-audit-scores">
+  {items.map((it, i) => {
+    const tone = scoreTone(it.score);
+    const { x, y } = arcEnd(it.score);
+    return (
+      <div class={`bk-audit-scores__card bk-audit-scores__card--${tone}`}>
+        <svg class="bk-audit-scores__gauge" viewBox="0 0 100 60" aria-hidden="true">
+          <path
+            class="bk-audit-scores__track"
+            d="M10 50 A 40 40 0 0 1 90 50"
+            fill="none"
+            strokeWidth="8"
+            strokeLinecap="round"
+          />
+          <path
+            class="bk-audit-scores__arc"
+            d={`M10 50 A 40 40 0 0 1 ${x} ${y}`}
+            fill="none"
+            strokeWidth="8"
+            strokeLinecap="round"
+          />
+        </svg>
+        <div class="bk-audit-scores__num">{it.score}</div>
+        <div class="bk-audit-scores__label">{it.label}</div>
+        {it.sub && <div class="bk-audit-scores__sub">{it.sub}</div>}
+      </div>
+    );
+  })}
+</div>

package/astro/AuthorCard.astro

@@ -0,0 +1,32 @@
+---
+import { authorInitials, type AuthorLink } from "../core/lib";
+interface Props {
+  name: string;
+  role?: string;
+  avatar?: string;
+  bio?: string;
+  links?: AuthorLink[];
+}
+const { name, role, avatar, bio, links } = Astro.props;
+---
+<div class="bk-author">
+  <div class="bk-author__media">
+    {avatar ? (
+      <img class="bk-author__avatar" src={avatar} alt={name} />
+    ) : (
+      <span class="bk-author__avatar bk-author__avatar--fallback" aria-hidden="true">{authorInitials(name)}</span>
+    )}
+  </div>
+  <div class="bk-author__body">
+    <p class="bk-author__name">{name}</p>
+    {role && <p class="bk-author__role">{role}</p>}
+    {bio && <p class="bk-author__bio">{bio}</p>}
+    {links && links.length > 0 && (
+      <div class="bk-author__links">
+        {links.map((l) => (
+          <a class="bk-author__link" href={l.href}>{l.label} &rarr;</a>
+        ))}
+      </div>
+    )}
+  </div>
+</div>

package/astro/BeforeAfter.astro

@@ -0,0 +1,26 @@
+---
+interface BeforeAfterSide {
+  title: string;
+  content: string;
+  value?: string;
+}
+interface Props {
+  before: BeforeAfterSide;
+  after: BeforeAfterSide;
+}
+const { before, after } = Astro.props;
+---
+{before && after && (
+  <div class="bk-before-after">
+    <div class="bk-before-after__card bk-before-after__card--before">
+      <div class="bk-before-after__label">{before.title}</div>
+      {before.value && <div class="bk-before-after__value">{before.value}</div>}
+      <p class="bk-before-after__body">{before.content}</p>
+    </div>
+    <div class="bk-before-after__card bk-before-after__card--after">
+      <div class="bk-before-after__label">{after.title}</div>
+      {after.value && <div class="bk-before-after__value">{after.value}</div>}
+      <p class="bk-before-after__body">{after.content}</p>
+    </div>
+  </div>
+)}

package/astro/BlogBehaviors.astro

@@ -0,0 +1,15 @@
+---
+/**
+ * Activates the kit's interactive components on an Astro site
+ * (TableOfContents scrollspy, FAQ JSON-LD, table scroll hints, code
+ * copy). Drop it once inside the `.blog-root` of the post layout — it
+ * renders only a module <script>. It runs on first load and again on
+ * `astro:page-load` so View-Transitions navigations re-wire the new
+ * post; each behaviour is idempotent, so re-running is safe.
+ */
+---
+<script>
+  import { initBlogBehaviors } from "../core/behaviors/index.js";
+  initBlogBehaviors();
+  document.addEventListener("astro:page-load", initBlogBehaviors);
+</script>

package/astro/CTABanner.astro

@@ -0,0 +1,28 @@
+---
+import { ICONS } from "../core/icons";
+interface Props {
+  heading?: string;
+  description?: string;
+  ctaText?: string;
+  ctaHref?: string;
+}
+const {
+  heading = "See it on your own site",
+  description = "Capture AI deploys in under ten minutes — paste a tag, point at your content, watch leads land.",
+  ctaText = "Book a demo",
+  ctaHref = "/book-demo",
+} = Astro.props;
+---
+<div class="bk-cta-banner">
+  <span class="bk-cta-banner__glow" aria-hidden="true"></span>
+  <div class="bk-cta-banner__inner">
+    <div class="bk-cta-banner__copy">
+      <h3 class="bk-cta-banner__heading">{heading}</h3>
+      <p class="bk-cta-banner__desc">{description}</p>
+    </div>
+    <a class="bk-cta-banner__cta" href={ctaHref}>
+      <span class="bk-cta-banner__cta-label">{ctaText}</span>
+      <span class="bk-cta-banner__cta-icon" aria-hidden="true" set:html={ICONS["arrowRight"]} />
+    </a>
+  </div>
+</div>

package/astro/CalloutBox.astro

@@ -0,0 +1,28 @@
+---
+/* blog-kit Astro adapter — CalloutBox
+   Thin wrapper emitting the SAME markup/classes as the React adapter.
+   Styling: core/css/components.css. Logic: core/lib.ts. Icons: core/icons.ts.
+   NOTE: deliberately no <style> block — the kit's CSS is shared/global,
+   not Astro-scoped, so React and Astro render byte-identically. */
+import { ICONS } from "../core/icons";
+import { resolveCalloutTone, CALLOUT_DEFAULT_TITLE } from "../core/lib";
+
+interface Props {
+  tone?: string;
+  type?: string;
+  variant?: string;
+  title?: string;
+}
+
+const { tone, type, variant, title } = Astro.props;
+const t = resolveCalloutTone(tone ?? type ?? variant);
+const heading = title ?? CALLOUT_DEFAULT_TITLE[t];
+---
+
+<aside class={`bk-callout bk-callout--${t}`}>
+  <p class="bk-callout__title">
+    <span class="bk-callout__icon" set:html={ICONS[t]} />
+    {heading}
+  </p>
+  <div class="bk-callout__body"><slot /></div>
+</aside>

package/astro/CaseStudyHero.astro

@@ -0,0 +1,45 @@
+---
+interface CaseStudyResult {
+  num: string;
+  label: string;
+}
+
+interface Props {
+  logoImage?: string;
+  logo?: string;
+  client?: string;
+  chips?: string[];
+  title?: string;
+  sub?: string;
+  results?: CaseStudyResult[];
+}
+
+const { logoImage, logo, client, chips = [], title, sub, results = [] } = Astro.props;
+const logoHtml = logo || client?.replace(/ /g, "<br/>") || "";
+---
+<div class="bk-case-study-hero">
+  <div class="bk-case-study-hero__logo">
+    {logoImage ? (
+      <img src={logoImage} alt={client ? `${client} logo` : "Client logo"} />
+    ) : (
+      <strong set:html={logoHtml} />
+    )}
+  </div>
+  <div class="bk-case-study-hero__body">
+    <div class="bk-case-study-hero__chips">
+      {chips.map((c) => (
+        <span class="bk-case-study-hero__chip">{c}</span>
+      ))}
+    </div>
+    <h2 class="bk-case-study-hero__heading">{title}</h2>
+    <p class="bk-case-study-hero__sub">{sub}</p>
+    <div class="bk-case-study-hero__results">
+      {results.map((r) => (
+        <div class="bk-case-study-hero__result">
+          <div class="bk-case-study-hero__result-num">{r.num}</div>
+          <div class="bk-case-study-hero__result-label">{r.label}</div>
+        </div>
+      ))}
+    </div>
+  </div>
+</div>

package/astro/ChannelMixBars.astro

@@ -0,0 +1,33 @@
+---
+interface Row {
+  name: string;
+  value: number;
+  display?: string;
+}
+interface Props {
+  rows?: Row[];
+  total?: string;
+  period?: string;
+}
+
+const { rows = [], total, period } = Astro.props;
+const max = Math.max(...rows.map((r) => Number(r.value) || 0), 1);
+---
+<div class="bk-channel-mix">
+  <div class="bk-channel-mix__head">
+    <div class="bk-channel-mix__title">{period || "Channel split"}</div>
+    {total && <div class="bk-channel-mix__total">Total · {total}</div>}
+  </div>
+  {rows.map((r, i) => (
+    <div class="bk-channel-mix__row">
+      <div class="bk-channel-mix__name">{r.name}</div>
+      <div class="bk-channel-mix__bar">
+        <div
+          class={`bk-channel-mix__fill${i > 0 ? ` bk-channel-mix__fill--${Math.min(i + 1, 5)}` : ""}`}
+          style={`width: ${(Number(r.value) / max) * 100}%`}
+        />
+      </div>
+      <div class="bk-channel-mix__val">{r.display || r.value}</div>
+    </div>
+  ))}
+</div>