astro-book-bridge 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gabriel Kanev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,212 @@
+# astro-book-bridge
+
+Astro integration for a local, source-agnostic book catalog. It can import a
+Goodreads RSS shelf, fetch edition metadata from Open Library and Google Books,
+and merge all of it with notes, reviews and curation stored in the Astro
+project.
+
+## Installation
+
+```bash
+pnpm add astro-book-bridge
+```
+
+Register the integration in `astro.config.mjs`:
+
+```js
+import { defineConfig } from 'astro/config';
+import bookBridge from 'astro-book-bridge';
+
+export default defineConfig({
+  integrations: [
+    bookBridge({
+      rssUrl: 'https://www.goodreads.com/review/list_rss/USER_ID?shelf=read',
+      openLibrary: true,
+      googleBooks: { apiKey: process.env.GOOGLE_BOOKS_API_KEY },
+      overrides: 'src/content/book-overrides.json',
+      markdownOverrides: 'src/content/book-overrides',
+      cache: '.astro/book-bridge',
+      covers: { mode: 'local', directory: 'public/book-covers' },
+      output: 'src/generated/books.json', // optional
+    }),
+  ],
+});
+```
+
+## Use in an Astro page
+
+```astro
+---
+import { books, catalog } from 'astro-book-bridge:catalog';
+---
+
+<h1>Books ({books.length})</h1>
+{catalog.source.usedCache && <p>Showing the last cached RSS feed.</p>}
+<ul>
+  {books.map((book) => <li><a href={book.link}>{book.title}</a> — {book.author}</li>)}
+</ul>
+```
+
+The integration injects the TypeScript declaration for the virtual module into
+Astro automatically. Each book exposes its primary `source` and all merged
+`sources`, e.g. `['goodreads-rss', 'open-library']`.
+
+## Sources
+
+`rssUrl` is optional. With it, Goodreads continues to provide reading state
+(rating, date read and shelf), while the other providers fill richer edition
+metadata where ISBNs match.
+
+```js
+bookBridge({
+  rssUrl: 'https://www.goodreads.com/review/list_rss/USER_ID?shelf=read',
+  openLibrary: true,
+  googleBooks: true,
+});
+```
+
+For a catalog with no Goodreads dependency, supply ISBNs directly to either
+provider. `enrich: false` prevents the provider from also looking up ISBNs
+already returned by another source.
+
+```js
+bookBridge({
+  openLibrary: {
+    isbns: ['9780140328721', '9780441478125'],
+    enrich: false,
+  },
+  googleBooks: {
+    isbns: ['9780140328721'],
+    enrich: false,
+    apiKey: process.env.GOOGLE_BOOKS_API_KEY,
+  },
+});
+```
+
+Open Library is queried through its ISBN Books API. Google Books is queried by
+ISBN; an API key is optional in the integration configuration and lets a site
+use its own Google quota/credentials. Provider order is Goodreads → Open
+Library → Google Books, so later sources only fill missing remote fields.
+
+## Local overrides
+
+Create `src/content/book-overrides.json`. A book matches Goodreads ID first,
+then ISBN13, then ISBN. This rule works no matter which provider supplied the
+book. Local fields only replace remote fields when they are present.
+
+```json
+{
+  "books": [
+    {
+      "goodreadsId": "18423",
+      "slug": "the-left-hand-of-darkness",
+      "note": "A reread that gets better every time.",
+      "review": "My full review in Markdown or plain text.",
+      "recommended": true,
+      "featured": true,
+      "tags": ["science-fiction", "classics"]
+    },
+    {
+      "isbn13": "9780441478125",
+      "note": "This also matches when Goodreads ID is absent."
+    }
+  ]
+}
+```
+
+Duplicate Goodreads IDs, ISBNs or ISBN13 values are rejected with a build
+error. ISBN punctuation is ignored when matching, and supplied ISBNs must pass
+their ISBN-10/ISBN-13 checksum.
+
+### Markdown and MDX reviews
+
+For a longer review, add one `.md` or `.mdx` file per book under
+`src/content/book-overrides/`. The YAML frontmatter identifies the book and the
+body becomes `review` automatically.
+
+```md
+---
+isbn13: "9780441478125"
+featured: true
+tags: [science-fiction, classics]
+---
+
+# A returning favorite
+
+My long-form review goes here in Markdown.
+```
+
+JSON and Markdown overrides are merged together. Duplicated identity keys are
+still reported as a build error, which prevents two reviews from silently
+targeting the same book.
+
+## Operational behaviour
+
+- Configured providers are fetched when the virtual module is built or loaded.
+- The last successful RSS, Open Library and Google Books responses are cached
+  independently under `.astro/book-bridge/` by default. A changed ISBN list
+  gets a fresh provider cache entry.
+- When a provider is temporarily unavailable, its matching cache is used by
+  default with a warning. Set `staleIfError: false` to fail instead.
+- A failed metadata enrichment never discards data already returned by another
+  configured source.
+- Set `conflicts: 'error'` to stop the build when two providers return
+  different titles for the same Goodreads ID/ISBN. The default is a warning
+  that keeps the first configured source.
+- Editing the JSON overrides file triggers a full reload in development.
+- Set `cache: false` to disable all provider caches; `timeoutMs` defaults to
+  `10000`. A legacy `cache: '.astro/feed.json'` path continues to work.
+
+### Cover policy and attribution
+
+Remote cover URLs are retained by default. Set `covers.mode` to `local` to
+download provider covers into a directory below `public/`, which makes the
+catalog more reliable and avoids depending on a remote image at page load.
+Every book retains `coverSourceUrl` and `coverAttribution` for a visible credit
+or link in your template.
+
+```js
+bookBridge({
+  openLibrary: { isbns: ['9780140328721'] },
+  covers: {
+    mode: 'local',
+    directory: 'public/book-covers',
+    fallbackUrl: '/book-cover-fallback.svg',
+  },
+});
+```
+
+See [PLAN.md](./PLAN.md) for the delivery plan and next milestones.
+
+## Copy-ready design demo
+
+`examples/demo` is a small Astro app in this repository, built as a collection
+of sections rather than a full site. It deliberately includes no navigation,
+header or site layout, so users can drop the components into their own design
+system.
+
+```bash
+pnpm install
+pnpm dev:demo
+```
+
+The three copy-ready directions are all driven by the same `books` array from
+the virtual module:
+
+- `BookSections.astro` / `/` — bright, annotation-led **Margin Notes**.
+- `EditorialSections.astro` / `/editorial` — calm, long-form reading journal.
+- `DarkShelfSections.astro` / `/dark-shelf` — dark visual shelf with selected
+  book detail.
+
+All three use semantic headings, lists and cover alt text, provide compact
+mobile layouts, and avoid site-level chrome.
+
+Use `pnpm check:demo` for Astro diagnostics and `pnpm build:demo` to build all
+three pages as a static Astro site.
+
+## Quality and releases
+
+The repository uses pnpm and includes CI for type checks, unit tests, package
+build, Astro diagnostics, demo build and `pnpm pack --dry-run`. Add a release
+note with `pnpm changeset`; the release workflow then creates a version PR and,
+after it merges, publishes with the repository's `NPM_TOKEN` secret.

package/examples/demo/astro.config.mjs

@@ -0,0 +1,13 @@
+import { defineConfig } from 'astro/config';
+import bookBridge from 'astro-book-bridge';
+
+export default defineConfig({
+  integrations: [
+    bookBridge({
+      openLibrary: {
+        isbns: ['9780140328721', '9780441478125', '9780061120084', '9780141182803', '9780307277671', '9780385490818'],
+        enrich: false,
+      },
+    }),
+  ],
+});

package/examples/demo/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@astro-book-bridge/demo",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "check": "astro check",
+    "preview": "astro preview"
+  },
+  "dependencies": {
+    "astro-book-bridge": "workspace:*"
+  },
+  "devDependencies": {
+    "astro": "^7.1.3"
+  }
+}

package/examples/demo/src/components/BookGallery.astro

@@ -0,0 +1,44 @@
+---
+import type { Book } from 'astro-book-bridge';
+
+interface Props {
+  books: Book[];
+}
+
+const { books } = Astro.props;
+---
+
+<section class="book-gallery" aria-labelledby="library-heading">
+  <div class="section-heading">
+    <div>
+      <p class="eyebrow">Your catalog</p>
+      <h2 id="library-heading">Books worth passing on</h2>
+    </div>
+    <span class="book-count">{books.length} books</span>
+  </div>
+
+  <ul class="book-filters" aria-label="Book categories">
+    <li class="filter is-active">All books</li>
+    <li class="filter">Fiction</li>
+    <li class="filter">Nonfiction</li>
+    <li class="filter">Poetry</li>
+    <li class="filter">Essays</li>
+  </ul>
+
+  <div class="book-grid">
+    {books.map((book, index) => (
+      <article class:list={['book-card', { 'book-card--offset': index % 5 === 1 || index % 5 === 4 }]}>
+        {book.imageUrl ? (
+          <img class="book-cover" src={book.imageUrl} alt={`Cover of ${book.title}`} loading="lazy" />
+        ) : (
+          <p class="book-no-cover">Cover unavailable</p>
+        )}
+        <div class="book-copy">
+          <h3>{book.title}</h3>
+          {book.author && <p>{book.author}</p>}
+          {book.note && <p class="book-note">{book.note}</p>}
+        </div>
+      </article>
+    ))}
+  </div>
+</section>

package/examples/demo/src/components/BookSections.astro

@@ -0,0 +1,22 @@
+---
+import type { Book } from 'astro-book-bridge';
+import BookGallery from './BookGallery.astro';
+import FeaturedNote from './FeaturedNote.astro';
+import ReadingList from './ReadingList.astro';
+
+interface Props {
+  books: Book[];
+}
+
+const { books } = Astro.props;
+const featured = books.find((book) => book.featured || book.note || book.review) ?? books[0];
+const readingList = books.filter((book) => book.recommended).slice(0, 4);
+---
+
+<main class="book-sections">
+  <BookGallery books={books} />
+  <div class="book-secondary-grid">
+    <FeaturedNote book={featured} />
+    <ReadingList books={readingList.length ? readingList : books.slice(1, 5)} />
+  </div>
+</main>

package/examples/demo/src/components/DarkShelfSections.astro

@@ -0,0 +1,44 @@
+---
+import type { Book } from 'astro-book-bridge';
+
+interface Props {
+  books: Book[];
+}
+
+const { books } = Astro.props;
+const selected = books.find((book) => book.featured || book.description) ?? books[0];
+---
+
+<main class="dark-shelf-sections">
+  <section class="dark-library" aria-labelledby="dark-library-heading">
+    <div class="dark-heading">
+      <div>
+        <p>Personal library</p>
+        <h1 id="dark-library-heading">All books</h1>
+      </div>
+      <span>{books.length} books</span>
+    </div>
+    <div class="dark-shelf-grid">
+      {books.map((book) => (
+        <article>
+          {book.imageUrl && <img src={book.imageUrl} alt={`Cover of ${book.title}`} loading="lazy" />}
+          <h2>{book.title}</h2>
+          <p>{book.author ?? 'Unknown author'}</p>
+        </article>
+      ))}
+    </div>
+  </section>
+
+  {selected && (
+    <aside class="dark-book-note" aria-labelledby="dark-book-note-heading">
+      {selected.imageUrl && <img src={selected.imageUrl} alt={`Cover of ${selected.title}`} />}
+      <div>
+        <p class="dark-state">Selected book</p>
+        <h2 id="dark-book-note-heading">{selected.title}</h2>
+        <p class="dark-author">{selected.author ?? 'Unknown author'}</p>
+        <p class="dark-description">{selected.note ?? selected.review ?? selected.description ?? 'Add a summary or a note from your own reading here.'}</p>
+        {selected.tags?.length ? <p class="dark-tags">{selected.tags.join(' · ')}</p> : <p class="dark-tags">{selected.sources.join(' · ')}</p>}
+      </div>
+    </aside>
+  )}
+</main>

package/examples/demo/src/components/EditorialSections.astro

@@ -0,0 +1,45 @@
+---
+import type { Book } from 'astro-book-bridge';
+
+interface Props {
+  books: Book[];
+}
+
+const { books } = Astro.props;
+const featured = books.find((book) => book.featured || book.review || book.note) ?? books[0];
+const recent = books.filter((book) => book !== featured).slice(0, 6);
+---
+
+<main class="editorial-book-sections">
+  {featured && (
+    <section class="editorial-feature" aria-labelledby="editorial-feature-heading">
+      <div class="editorial-intro">
+        <p class="editorial-kicker">Reading journal</p>
+        <h1 id="editorial-feature-heading">{featured.title}</h1>
+        <p class="editorial-author">{featured.author ?? 'From your library'}</p>
+        <p class="editorial-note">{featured.review ?? featured.note ?? featured.description ?? 'A place for a considered note about the book that is sitting with you.'}</p>
+        <p class="editorial-source">Sources: {featured.sources.join(' · ')}</p>
+      </div>
+      {featured.imageUrl && <img class="editorial-cover" src={featured.imageUrl} alt={`Cover of ${featured.title}`} />}
+    </section>
+  )}
+
+  <section class="editorial-recent" aria-labelledby="editorial-recent-heading">
+    <div class="editorial-section-heading">
+      <p class="editorial-kicker">From the shelf</p>
+      <h2 id="editorial-recent-heading">Recently read</h2>
+    </div>
+    <ol>
+      {recent.map((book) => (
+        <li>
+          {book.imageUrl && <img src={book.imageUrl} alt="" loading="lazy" />}
+          <div>
+            <h3>{book.title}</h3>
+            <p>{book.author ?? 'Unknown author'}</p>
+          </div>
+          <p class="editorial-date">{book.readAt ?? book.publishedDate ?? 'On the shelf'}</p>
+        </li>
+      ))}
+    </ol>
+  </section>
+</main>

package/examples/demo/src/components/FeaturedNote.astro

@@ -0,0 +1,24 @@
+---
+import type { Book } from 'astro-book-bridge';
+
+interface Props {
+  book?: Book;
+}
+
+const { book } = Astro.props;
+---
+
+{book && (
+  <section class="featured-note" aria-labelledby="featured-heading">
+    <div class="featured-label">Featured note</div>
+    <div class="featured-content">
+      {book.imageUrl && <img src={book.imageUrl} alt={`Cover of ${book.title}`} loading="lazy" />}
+      <div>
+        <p class="eyebrow">{book.author ?? 'From your shelf'}</p>
+        <h2 id="featured-heading">{book.title}</h2>
+        <p class="featured-copy">{book.review ?? book.note ?? book.description ?? 'Leave a small note here: the line, idea, or feeling that made this book stay with you.'}</p>
+        {book.tags?.length ? <p class="tag-list">{book.tags.join(' · ')}</p> : <p class="tag-list">Personal pick · {book.sources.join(' + ')}</p>}
+      </div>
+    </div>
+  </section>
+)}

package/examples/demo/src/components/ReadingList.astro

@@ -0,0 +1,31 @@
+---
+import type { Book } from 'astro-book-bridge';
+
+interface Props {
+  books: Book[];
+}
+
+const { books } = Astro.props;
+---
+
+<section class="reading-list" aria-labelledby="reading-list-heading">
+  <div class="section-heading">
+    <div>
+      <p class="eyebrow">Keep nearby</p>
+      <h2 id="reading-list-heading">Reading list</h2>
+    </div>
+    <span class="book-count">{books.length} saved</span>
+  </div>
+  <ol>
+    {books.map((book) => (
+      <li>
+        {book.imageUrl && <img src={book.imageUrl} alt="" loading="lazy" />}
+        <div>
+          <h3>{book.title}</h3>
+          <p>{book.author ?? 'Unknown author'}</p>
+        </div>
+        <span class="save-mark">Saved</span>
+      </li>
+    ))}
+  </ol>
+</section>

package/examples/demo/src/pages/dark-shelf.astro

@@ -0,0 +1,8 @@
+---
+import { books } from 'astro-book-bridge:catalog';
+import DarkShelfSections from '../components/DarkShelfSections.astro';
+import '../styles/dark-shelf.css';
+---
+
+<!doctype html>
+<html lang="en"><head><meta charset="UTF-8" /><meta name="viewport" content="width=device-width" /><title>Dark shelf book sections</title></head><body><DarkShelfSections books={books} /></body></html>

package/examples/demo/src/pages/editorial.astro

@@ -0,0 +1,8 @@
+---
+import { books } from 'astro-book-bridge:catalog';
+import EditorialSections from '../components/EditorialSections.astro';
+import '../styles/editorial.css';
+---
+
+<!doctype html>
+<html lang="en"><head><meta charset="UTF-8" /><meta name="viewport" content="width=device-width" /><title>Editorial book sections</title></head><body><EditorialSections books={books} /></body></html>

package/examples/demo/src/pages/index.astro

@@ -0,0 +1,18 @@
+---
+import { books } from 'astro-book-bridge:catalog';
+import BookSections from '../components/BookSections.astro';
+import '../styles/demo.css';
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width" />
+    <meta name="description" content="A copy-ready book catalog section for Astro." />
+    <title>Book sections demo</title>
+  </head>
+  <body>
+    <BookSections books={books} />
+  </body>
+</html>

package/examples/demo/src/styles/dark-shelf.css

@@ -0,0 +1,22 @@
+:root { color: #e8eefb; background: #061121; font-family: Inter, ui-sans-serif, system-ui, sans-serif; }
+* { box-sizing: border-box; }
+body { margin: 0; }
+img { display: block; max-width: 100%; }
+.dark-shelf-sections { width: min(1280px, calc(100% - 48px)); margin: 0 auto; padding: clamp(44px, 8vw, 108px) 0; }
+.dark-heading { display: flex; justify-content: space-between; align-items: end; gap: 24px; margin-bottom: 34px; }
+.dark-heading p, .dark-state { margin: 0 0 8px; color: #75a9ff; font-size: .74rem; font-weight: 800; letter-spacing: .13em; text-transform: uppercase; }
+.dark-heading h1 { margin: 0; font-size: clamp(2.6rem, 6vw, 5.4rem); letter-spacing: -.065em; line-height: .88; }
+.dark-heading > span { color: #9eacc2; font-size: .9rem; }
+.dark-shelf-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 28px 16px; }
+.dark-shelf-grid article { min-width: 0; }
+.dark-shelf-grid img { width: 100%; aspect-ratio: 2 / 3; object-fit: cover; border: 1px solid #203457; border-radius: 5px; }
+.dark-shelf-grid h2 { margin: 10px 0 4px; font-size: .92rem; letter-spacing: -.02em; line-height: 1.2; }
+.dark-shelf-grid p { margin: 0; color: #9eacc2; font-size: .78rem; }
+.dark-book-note { display: grid; grid-template-columns: 132px 1fr; gap: 26px; margin-top: 68px; padding: clamp(22px, 4vw, 42px); border: 1px solid #203457; background: #0b1a30; }
+.dark-book-note > img { width: 132px; aspect-ratio: 2 / 3; object-fit: cover; }
+.dark-book-note h2 { margin: 0 0 8px; font-size: clamp(1.8rem, 4vw, 3.5rem); letter-spacing: -.055em; line-height: .94; }
+.dark-author { margin: 0 0 22px; color: #9eacc2; }
+.dark-description { max-width: 54ch; margin: 0; color: #d1d9e8; line-height: 1.62; }
+.dark-tags { margin: 24px 0 0; color: #75a9ff; font-size: .8rem; font-weight: 700; }
+@media (min-width: 700px) { .dark-shelf-grid { grid-template-columns: repeat(6, minmax(0, 1fr)); } }
+@media (max-width: 560px) { .dark-shelf-sections { width: min(100% - 32px, 1280px); } .dark-book-note { grid-template-columns: 92px 1fr; gap: 18px; } .dark-book-note > img { width: 92px; } }

package/examples/demo/src/styles/demo.css

@@ -0,0 +1,64 @@
+:root {
+  --paper: #fffdf8;
+  --ink: #181713;
+  --blue: #1746d0;
+  --red: #ef4a2f;
+  --yellow: #f8bd14;
+  --lilac: #bca4e8;
+  --line: #e6e0d7;
+  font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  color: var(--ink);
+  background: var(--paper);
+}
+
+* { box-sizing: border-box; }
+body { margin: 0; }
+img { display: block; max-width: 100%; }
+
+.book-sections { width: min(1200px, calc(100% - 48px)); margin: 0 auto; padding: clamp(44px, 8vw, 112px) 0; }
+.section-heading { display: flex; align-items: end; justify-content: space-between; gap: 24px; margin-bottom: 24px; }
+.eyebrow { margin: 0 0 8px; color: var(--blue); font-size: .72rem; font-weight: 800; letter-spacing: .12em; text-transform: uppercase; }
+h2, h3, p { margin-top: 0; }
+h2 { margin-bottom: 0; font-size: clamp(2rem, 5vw, 4.4rem); letter-spacing: -.065em; line-height: .94; }
+h3 { font-size: 1rem; letter-spacing: -.025em; line-height: 1.15; }
+.book-count { color: #6c6860; font-size: .88rem; white-space: nowrap; }
+.book-filters { display: flex; flex-wrap: wrap; gap: 10px; margin: 0 0 42px; }
+.filter { border: 1px solid var(--line); border-radius: 99px; padding: 9px 16px; font-size: .9rem; }
+.filter.is-active { border-color: var(--blue); background: var(--blue); color: white; }
+.book-grid { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 42px 24px; }
+.book-card { min-width: 0; }
+.book-card--offset { transform: translateY(28px); }
+.book-cover { aspect-ratio: 2 / 3; width: 100%; border-radius: 4px; object-fit: cover; box-shadow: 0 10px 20px rgb(35 29 18 / .14); }
+.book-no-cover { display: grid; aspect-ratio: 2 / 3; place-items: center; margin: 0; border: 1px solid var(--line); color: #6c6860; font-size: .88rem; text-align: center; }
+.book-copy { padding: 14px 4px 0; }
+.book-copy h3 { margin-bottom: 5px; }
+.book-copy p { margin-bottom: 0; color: #625d55; font-size: .88rem; }
+.book-copy .book-note { margin-top: 8px; color: var(--red); font-style: italic; }
+.book-secondary-grid { display: grid; grid-template-columns: 1.2fr .8fr; gap: clamp(48px, 8vw, 112px); align-items: start; margin-top: 110px; }
+.featured-label { display: inline-block; margin-bottom: 14px; padding-bottom: 4px; border-bottom: 3px solid var(--red); color: var(--red); font-weight: 800; font-size: 1.05rem; transform: rotate(-2deg); }
+.featured-content { display: grid; grid-template-columns: minmax(120px, 34%) 1fr; gap: 24px; padding: clamp(20px, 4vw, 36px); background: #fff1ed; }
+.featured-content > img { width: 100%; aspect-ratio: 2 / 3; object-fit: cover; box-shadow: 0 8px 18px rgb(65 31 23 / .18); }
+.featured-content h2 { font-size: clamp(1.75rem, 3vw, 3.1rem); margin-bottom: 16px; }
+.featured-copy { color: #423d37; font-size: .98rem; line-height: 1.62; }
+.tag-list { margin-bottom: 0; color: var(--blue); font-size: .82rem; font-weight: 700; }
+.reading-list h2 { font-size: clamp(1.75rem, 3vw, 3rem); }
+.reading-list ol { list-style: none; margin: 0; padding: 0; border-top: 1px solid var(--line); }
+.reading-list li { display: grid; grid-template-columns: 46px 1fr auto; align-items: center; gap: 14px; padding: 13px 0; border-bottom: 1px solid var(--line); }
+.reading-list li img { width: 46px; height: 62px; object-fit: cover; }
+.reading-list h3 { margin-bottom: 4px; font-size: .92rem; }
+.reading-list p { margin-bottom: 0; color: #6c6860; font-size: .82rem; }
+.save-mark { color: var(--blue); font-size: .72rem; font-weight: 800; letter-spacing: .08em; text-transform: uppercase; }
+
+@media (min-width: 760px) {
+  .book-grid { grid-template-columns: repeat(6, minmax(0, 1fr)); }
+  .book-card--offset { transform: translateY(30px); }
+}
+
+@media (max-width: 700px) {
+  .book-sections { width: min(100% - 32px, 1200px); }
+  .section-heading { align-items: start; flex-direction: column; gap: 10px; }
+  .book-grid { gap: 30px 14px; }
+  .book-card--offset { transform: none; }
+  .book-secondary-grid { grid-template-columns: 1fr; margin-top: 64px; }
+  .featured-content { grid-template-columns: 100px 1fr; gap: 16px; }
+}

package/examples/demo/src/styles/editorial.css

@@ -0,0 +1,21 @@
+:root { color: #28241f; background: #f6f1e7; font-family: Georgia, "Times New Roman", serif; }
+* { box-sizing: border-box; }
+body { margin: 0; }
+img { display: block; max-width: 100%; }
+.editorial-book-sections { width: min(1160px, calc(100% - 48px)); margin: 0 auto; padding: clamp(48px, 8vw, 110px) 0; }
+.editorial-feature { display: grid; grid-template-columns: 1fr minmax(240px, 360px); gap: clamp(38px, 8vw, 100px); align-items: center; padding-bottom: clamp(64px, 10vw, 130px); }
+.editorial-kicker { margin: 0 0 18px; color: #8b2830; font: 700 .72rem/1 ui-sans-serif, system-ui, sans-serif; letter-spacing: .14em; text-transform: uppercase; }
+.editorial-feature h1 { max-width: 9ch; margin: 0 0 16px; font-size: clamp(3.2rem, 8vw, 7rem); font-weight: 500; letter-spacing: -.075em; line-height: .83; }
+.editorial-author { margin: 0 0 30px; color: #6b6258; font-style: italic; font-size: 1.1rem; }
+.editorial-note { max-width: 40ch; font-size: 1.08rem; line-height: 1.65; }
+.editorial-source { margin: 24px 0 0; color: #8b2830; font: 700 .75rem/1.3 ui-sans-serif, system-ui, sans-serif; letter-spacing: .08em; text-transform: uppercase; }
+.editorial-cover { width: 100%; aspect-ratio: 2 / 3; object-fit: cover; box-shadow: 12px 16px 0 #d7c5a3; }
+.editorial-section-heading { display: flex; align-items: end; justify-content: space-between; border-bottom: 1px solid #cfc3b1; padding-bottom: 18px; }
+.editorial-section-heading h2 { margin: 0; font-size: clamp(2rem, 4vw, 3.8rem); font-weight: 500; letter-spacing: -.05em; }
+.editorial-recent ol { margin: 0; padding: 0; list-style: none; }
+.editorial-recent li { display: grid; grid-template-columns: 52px 1fr minmax(110px, 180px); align-items: center; gap: 20px; padding: 17px 0; border-bottom: 1px solid #d9cfbf; }
+.editorial-recent li img { width: 52px; height: 70px; object-fit: cover; }
+.editorial-recent h3 { margin: 0 0 5px; font-size: 1.12rem; font-weight: 500; }
+.editorial-recent li p { margin: 0; color: #6b6258; font-size: .9rem; }
+.editorial-date { text-align: right; font: .75rem/1.3 ui-sans-serif, system-ui, sans-serif; }
+@media (max-width: 640px) { .editorial-book-sections { width: min(100% - 32px, 1160px); } .editorial-feature { grid-template-columns: 1fr; } .editorial-cover { max-width: 240px; } .editorial-recent li { grid-template-columns: 44px 1fr; gap: 14px; } .editorial-recent li img { width: 44px; height: 60px; } .editorial-date { display: none; } }

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "astro-book-bridge",
+  "version": "0.2.0",
+  "packageManager": "pnpm@12.4.2",
+  "description": "Build a typed, locally enriched Astro book catalog from Goodreads RSS, Open Library and Google Books.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "examples/demo/src",
+    "examples/demo/astro.config.mjs",
+    "examples/demo/package.json"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "dev:demo": "pnpm --dir examples/demo dev",
+    "build:demo": "pnpm --dir examples/demo build",
+    "check:demo": "pnpm --dir examples/demo check",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "pnpm build && changeset publish"
+  },
+  "keywords": [
+    "astro",
+    "goodreads",
+    "open-library",
+    "google-books",
+    "rss",
+    "books"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MrGKanev/astro-books-bridge.git"
+  },
+  "homepage": "https://github.com/MrGKanev/astro-books-bridge#readme",
+  "bugs": {
+    "url": "https://github.com/MrGKanev/astro-books-bridge/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "astro": ">=4.0.0"
+  },
+  "dependencies": {
+    "fast-xml-parser": "^5.2.5",
+    "yaml": "^2.9.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.9",
+    "@changesets/cli": "^2.31.1",
+    "@types/node": "^26.1.1",
+    "astro": "^7.1.3",
+    "typescript": "^5.8.3",
+    "vite": "^8.1.5",
+    "vitest": "^4.1.10"
+  }
+}