npm - @hutusi/amytis - Versions diffs - 1.16.0 → 1.17.0 - Mend

@hutusi/amytis 1.16.0 → 1.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (51) hide show

package/.claude/rules/immersive-reading.md +21 -0
package/.claude/rules/rst.md +13 -0
package/CHANGELOG.md +16 -0
package/CLAUDE.md +10 -11
package/docs/ARCHITECTURE.md +81 -0
package/docs/DIGITAL_GARDEN.md +1 -1
package/docs/guides/importing-vuepress-books.md +95 -36
package/package.json +1 -1
package/scripts/sync-vuepress-book.ts +277 -66
package/site.config.example.ts +3 -3
package/site.config.ts +3 -3
package/src/app/[slug]/layout.tsx +30 -0
package/src/app/books/[slug]/layout.tsx +24 -0
package/src/app/books/[slug]/page.tsx +18 -2
package/src/app/globals.css +67 -0
package/src/app/page.tsx +6 -0
package/src/app/posts/layout.tsx +20 -0
package/src/app/series/[slug]/page.tsx +33 -9
package/src/components/BookReadingShell.tsx +145 -0
package/src/components/BookSidebar.tsx +0 -0
package/src/components/CuratedSeriesSection.tsx +28 -10
package/src/components/FeaturedStoriesSection.tsx +41 -20
package/src/components/Footer.tsx +1 -1
package/src/components/ImmersiveReader.tsx +130 -0
package/src/components/ImmersiveReaderTopBar.tsx +106 -0
package/src/components/ImmersiveReadingFlagHandler.tsx +40 -0
package/src/components/ImmersiveReadingPrefsPopover.tsx +249 -0
package/src/components/ImmersiveReadingProvider.tsx +168 -0
package/src/components/ImmersiveSeriesSidebar.tsx +143 -0
package/src/components/ImmersiveToggleButton.tsx +45 -0
package/src/components/MarkdownRenderer.tsx +31 -0
package/src/components/Navbar.tsx +3 -1
package/src/components/PostReadingShell.tsx +68 -0
package/src/components/ReadingProgressBar.tsx +1 -1
package/src/components/SelectedBooksSection.tsx +27 -8
package/src/hooks/useActiveHeading.ts +35 -13
package/src/hooks/useSidebarAutoScroll.ts +31 -7
package/src/i18n/translations.ts +42 -0
package/src/layouts/BookLayout.tsx +46 -89
package/src/layouts/PostLayout.tsx +154 -115
package/src/lib/immersive-reading-prefs.ts +104 -0
package/src/lib/markdown.ts +18 -11
package/src/lib/scroll-utils.ts +44 -6
package/src/lib/shuffle.ts +15 -1
package/src/lib/sort.ts +15 -0
package/src/lib/urls.ts +5 -0
package/tests/integration/book-index-cta.test.ts +87 -0
package/tests/integration/series-index-cta.test.ts +88 -0
package/tests/integration/sync-vuepress-book.test.ts +205 -2
package/tests/unit/immersive-reading-prefs.test.ts +144 -0
package/vercel.json +7 -0

package/.claude/rules/immersive-reading.md ADDED Viewed

@@ -0,0 +1,21 @@
+---
+paths:
+  - "src/components/Immersive*.tsx"
+  - "src/components/PostReadingShell.tsx"
+  - "src/components/BookReadingShell.tsx"
+  - "src/components/Navbar.tsx"
+  - "src/components/Footer.tsx"
+  - "src/components/ReadingProgressBar.tsx"
+  - "src/lib/immersive-reading-prefs.ts"
+  - "src/app/books/**"
+  - "src/app/[slug]/**"
+  - "src/app/posts/**"
+  - "src/app/globals.css"
+---
+# Immersive reading gotchas
+- **Chrome-hiding hooks.** `Navbar`, `Footer`, and `ReadingProgressBar` carry stable `data-site-nav` / `data-site-footer` / `data-reading-progress` attributes that the CSS rules in `globals.css` use to hide chrome when `html[data-immersive="true"]` is set. Don't strip these attributes during refactors — the fullscreen `ImmersiveReader` overlay in books and series posts depends on them as defense-in-depth even though the overlay also covers them. Reading-theme overrides (Light / Sepia / Dark) are scoped to `[data-reader-overlay]`, not `<html>`, so they compose with the site's light/dark theme without leaking outside the overlay; the overlay also adds Tailwind's `.dark` class when `readingTheme === 'dark'` so `dark:prose-invert` fires inside it even when the site is in light mode.
+- **Provider is mounted at three layout boundaries**, one per content surface that supports the reader: `src/app/books/[slug]/layout.tsx` (chapter routes), `src/app/[slug]/layout.tsx` (series posts on autoPaths URLs, the default), and `src/app/posts/layout.tsx` (series posts on default-path URLs). Each layout mounts an independent provider instance — `enabled` state doesn't bleed between content types — but they all share the same localStorage key (`amytis-reader-prefs`), so a reader's font/theme/width prefs carry across books and series. Don't merge the three or move the provider to root layout: doing so would leak `enabled=true` to pages without a shell (PostReadingShell / BookReadingShell) to render the overlay, breaking the page.
+- **`ImmersiveReadingFlagHandler` must stay in its own `<Suspense>` boundary in each of those three layouts**, as a sibling of `{children}` (not inside the provider), because its `useSearchParams` triggers a static-export bailout — wrapping the provider would drag the chapter/post page out of static prerender. The handler must **not** use a one-shot ref guard either: caught in PR-#93 review, the ref survives client-side navigation under the persistent layout, so a second `?immersive=1` click in the same tab silently no-ops. Rely on `router.replace` stripping the flag (which re-fires the effect with the flag gone) instead.
+- **Prefs persistence quirks** (`src/components/ImmersiveReadingProvider.tsx` + `src/lib/immersive-reading-prefs.ts`): persist effect flips `hydratedRef` on its *first run* and returns — moving the flip into the hydration effect causes a default-clobbering race (the persist effect runs before React commits the stored values from the closure). Per-key defensive parsing on read is also load-bearing: a corrupt single value (schema drift, hand-edits) must fall back to default without discarding the whole blob. Both behaviours have unit/integration test coverage; don't regress them when refactoring the storage layer or the hydrate/persist effects.

package/.claude/rules/rst.md ADDED Viewed

@@ -0,0 +1,13 @@
+---
+paths:
+  - "src/lib/rst*.ts"
+  - "src/lib/shiki-rst.ts"
+  - "src/components/RstRenderer.tsx"
+---
+# rST rendering gotchas
+- **rST needs Python `docutils`.** Set `AMYTIS_RST_PYTHON=/path/to/python` if not on `$PATH`. Without it, falls back to a lower-fidelity built-in parser.
+- **sanitize-html allowlist must keep `style` + `data-*` on `pre`/`code`/`span`/`div`.** Stripping any of these silently kills Shiki output (monochrome text in prod, looks fine locally because dev rST isn't sanitized). See `src/components/RstRenderer.tsx`.
+- **Code-group tabs add `<input type="radio">` + `<label>` to the sanitize-html allowlist.** Keep the `transformTags` guard in `RstRenderer.tsx` that strips any `<input>` whose `type !== "radio"` — that's the defense against an rST author injecting password/file/etc. inputs through raw HTML.
+- **Bump `RST_RENDERER_DISK_CACHE_VERSION` (`src/lib/rst-renderer.ts`) on highlighter-output changes.** Stale on-disk caches in `.cache/rst-renderer/` will serve old markup otherwise. Run `rm -rf .cache/rst-renderer` after pulling such a change.

package/CHANGELOG.md CHANGED Viewed

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [1.17.0] - 2026-06-11
+### Added
+- **Immersive Reading Mode**: A fullscreen, distraction-free reader for book chapters and series posts, launched from new "Immersive reading" CTAs on book and series index pages (deep-linkable via `?immersive=1`). Includes an `Aa` preferences popover (font size, Light / Sepia / Dark reading theme, column width) persisted in `localStorage` with a reset button, a reading progress bar under the top bar, and dedicated sidebars — the book sidebar with collapsible sections, plus a new series sidebar that inlines the active post's table of contents.
+- **Homepage Section Ordering**: The curated homepage sections (`featured-posts`, `featured-series`, `featured-books`) accept an optional per-section `order` field — `shuffle`, `date-desc`, or `date-asc`.
+- **VuePress Importer Upgrades**: `bun run sync-vuepress-book` understands VuePress 1.x sidebar shapes, gains `--skip-common` / `--skip` flags, supports narrow `chapters:`-only re-syncs, and falls back to `README.md` / `README.mdx` when resolving chapter ids.
+### Changed
+- **Homepage shuffle** now reshuffles on every visit instead of rotating daily.
+- **Vercel builds** are pinned via `vercel.json` and install with `--frozen-lockfile`.
+### Fixed
+- **Immersive Reader Robustness**: Active-heading tracking and anchor scrolling now target the overlay's scroll container; the overlay is preserved when navigating across a collection; sidebar scroll position survives chapter/post clicks; the reading-theme override reliably flips the theme; the `Aa` popover stacks above code blocks; the chrome-hiding CSS is no longer stripped by Lightning CSS; and the first persist run no longer clobbers stored preferences.
+- **Shuffle PRNG**: Small seeds are decorrelated with a splitmix32 finalizer and guarded against a zero state locking xorshift32; the featured-posts shuffle button is hidden when every slot is pinned.
+- **Book Chapter Layout**: Chapter column width aligned with the site navbar and the article centered in its column; React warnings from VuePress-imported tags are silenced.
 ## [1.16.0] - 2026-06-01
 ### Added

package/CLAUDE.md CHANGED Viewed

@@ -23,7 +23,7 @@ Content-creation scripts, test layout, validate pipeline → `docs/CONTRIBUTING.
 Quick "where do routes live" lookup. Full reference: `docs/ARCHITECTURE.md`.
-- Standard routes follow folder names under `src/app/`: `/posts`, `/series`, `/tags`, `/notes`, `/books`, `/authors`, `/archive`, `/graph`, `/flows/[year]/[month]/[day]`.
+- Standard routes follow folder names under `src/app/`: `/posts`, `/series`, `/tags`, `/notes`, `/books`, `/authors`, `/archive`, `/graph`, `/flows/[year]/[month]/[day]`. Book chapters are a catch-all: `books/[slug]/[...chapter]` (supports nested chapter IDs like `maths/linear/intro`).
 - **Top-level `[slug]` and `[slug]/[postSlug]`** resolve `redirectFrom` aliases and `series.customPaths` — highest-risk dynamic surface; touch with care.
 - Feeds at `feed.xml` / `feed.atom` / `all.xml` / `all.atom` / `flows/feed.{xml,atom}`; sitemap at `sitemap.ts`; search index at `search.json`.
 - Rendering pipeline lives in `src/lib/`: Shiki (`shiki.ts`, `shiki-rst.ts`), remark/rehype plugins (`remark-github-alerts`, `remark-wikilinks`, `remark-code-group`, `rehype-fence-meta`, `rehype-image-metadata`), redirects (`series-redirects.ts`), feeds/JSON-LD (`feed-utils.ts`, `json-ld.ts`).
@@ -32,7 +32,7 @@ Quick "where do routes live" lookup. Full reference: `docs/ARCHITECTURE.md`.
 - **Strict build over silent runtime failure.** Static export means misconfiguration must fail at build time. Use `throw` in `generateStaticParams` and similar — never silent skips or `console.warn`. Precedent: `validateSeriesAutoPaths` throws on slug collisions; `redirectFrom` alias conflicts (reserved slug or duplicate) should also throw, not produce broken redirects.
   - **Exception**: fence-language resolution in `src/lib/shiki.ts` deliberately degrades to `plaintext` + a deduped `console.warn` instead of throwing. Authors can't reliably predict Shiki's alias coverage, and "typo" vs "legitimate community alias" are indistinguishable from our side, so production deploys shouldn't fail on a single unhighlighted code block. Real typos still surface via the warn output in local/CI build logs.
-- **Validate author input at build time; keep content portable.** Frontmatter via Zod; slug / redirect conflicts throw. Files on disk stay valid `.md` / `.mdx` / `.rst` — no Amytis-specific syntax that breaks other tools.
+- **Validate author input at build time; keep content portable.** Frontmatter via Zod. Files on disk stay valid `.md` / `.mdx` / `.rst` — no Amytis-specific syntax that breaks other tools.
 ## Integration-point rules (always go through X)
@@ -47,30 +47,28 @@ Quick "where do routes live" lookup. Full reference: `docs/ARCHITECTURE.md`.
 ## Gotchas (things Claude will get wrong on first try)
+Feature-local gotchas live in path-scoped rules under `.claude/rules/` and auto-load when you touch matching files: `rst.md` (docutils setup, sanitize-html allowlist, disk-cache version) and `immersive-reading.md` (chrome-hiding hooks, provider boundaries, prefs persistence).
 - **`turbopackIgnore` on fs reads.** Any `fs.readFileSync()` path expression must be preceded by `/* turbopackIgnore: true */` (see `src/lib/markdown.ts`, `src/lib/rehype-image-metadata.ts`). Missing it causes incorrect bundling.
 - **No AVIF for `coverImage`.** Upstream bug in `next-image-export-optimizer` emits `.webp` files but a `srcset` pointing at `.avif` → 404 in prod. Use `.jpg` / `.png` / `.webp`. See `docs/TROUBLESHOOTING.md`.
 - **Unicode slugs.** Dynamic route pages call `safeDecodeParam()` and try decoded / raw / NFC / NFD variants — don't shortcut with bare `decodeURIComponent()` (it throws on malformed input). When touching dynamic routes, verify both ASCII and Unicode slugs.
 - **`generateStaticParams` returns raw values.** Don't `encodeURIComponent` route params; Next.js handles encoding. Don't link to placeholder routes like `/posts/[slug]` — always link to concrete URLs.
 - **Series format is locked.** A series index can be `index.md` / `.mdx` / `README.md` / `README.mdx` / `index.rst` / `README.rst` (first match wins). All child posts must match. Mixing formats is a build error.
-- **rST needs Python `docutils`.** Set `AMYTIS_RST_PYTHON=/path/to/python` if not on `$PATH`. Without it, falls back to a lower-fidelity built-in parser.
 - **Pagefind index.** `bun run build:dev` regenerates `public/pagefind/`; search returns stale results until you rerun it after content changes.
 - **`trailingSlash: true` is load-bearing.** Lets co-located post assets (`posts/slug/images/`) coexist with `posts/slug/index.html`. Don't flip it in `next.config.ts`.
 - **Shiki highlighter is a `globalThis` singleton.** Never instantiate it per render — `createHighlighter` loads Oniguruma WASM + grammars (~1–2 s). See `src/lib/shiki.ts`.
-- **rST sanitize-html allowlist must keep `style` + `data-*` on `pre`/`code`/`span`/`div`.** Stripping any of these silently kills Shiki output (monochrome text in prod, looks fine locally because dev rST isn't sanitized). See `src/components/RstRenderer.tsx`.
-- **Bump `RST_RENDERER_DISK_CACHE_VERSION` (`src/lib/rst-renderer.ts`) on highlighter-output changes.** Stale on-disk caches in `.cache/rst-renderer/` will serve old markup otherwise. Run `rm -rf .cache/rst-renderer` after pulling such a change.
 - **Fence meta needs `rehype-fence-meta` BEFORE `rehype-raw`.** `mdast-util-to-hast` stores fence meta on `node.data.meta`, which `rehype-raw` drops during HTML round-trip. The plugin copies it to a real `data-meta` attribute first. Order matters in `MarkdownRenderer.tsx`.
-- **Code-group tabs add `<input type="radio">` + `<label>` to the rST sanitize-html allowlist.** Keep the `transformTags` guard in `RstRenderer.tsx` that strips any `<input>` whose `type !== "radio"` — that's the defense against an rST author injecting password/file/etc. inputs through raw HTML.
 - **GitHub alerts (`> [!NOTE]`, etc.) need the custom `remarkGithubAlerts` plugin.** `remark-gfm` v4 does NOT transform `[!TYPE]` blockquotes — they pass through as plain blockquotes with the literal marker visible. The custom plugin in `src/lib/remark-github-alerts.ts` is what detects them and routes to `<GithubAlert>`. If a future remark-gfm adds native alert support, that's a regression to watch for (covered by an integration test).
 - **Single-line block math `$$ x $$` is silently inline.** `micromark-extension-math` (under `remark-math` v6) requires the `$$` markers on their own lines — single-line collapses to *inline* math (no `katex-display` wrapper, no centering, no display margin) and looks like a subtly under-styled formula. `src/lib/normalize-vuepress-math.ts` expands single-line `$$ x $$` to opener / body / closer before parsing, so authored content stays portable. If a chapter formula stops centering, suspect the normalizer's regex first.
 ## Development workflow
-- **Don't push or open PRs unless asked.** Local commits are fine; anything touching the remote needs explicit go-ahead.
-- **Commit in focused slices.** Keep `bun run validate` green at each commit so the branch stays bisectable.
+For a new feature or non-trivial change:
+- **Branch.** Work on a dedicated `<type>/<topic>` branch off `main`, not directly on `main`.
+- **Commit in focused slices.** One commit per logical slice (e.g. split a dead-code removal from the feature that replaces it). Keep `bun run lint` green at each commit so the branch stays bisectable. Conventional Commits: `feat | fix | refactor | perf | chore | docs | test | release`; subject under ~70 chars; body explains *why*; no `Co-Authored-By` trailers.
 - **Tests + docs in the same change.** Update `docs/ARCHITECTURE.md` / `docs/CONTRIBUTING.md` / `docs/TROUBLESHOOTING.md` alongside seam/workflow/invariant changes — not as a follow-up.
-- **Commits** follow Conventional Commits: `feat | fix | refactor | perf | chore | docs | test | release`. Subject under ~70 chars; body explains *why*.
-- **Branches:** `<type>/<kebab-slug>` matching commit prefixes.
-- **No Claude attribution.** Do not add `Co-Authored-By: Claude ...` trailers to commit messages or the `🤖 Generated with [Claude Code]` footer to PR descriptions. The default templates in the harness include both — strip them.
+- **Open a PR** into `main` when the branch is green. Do not add the `🤖 Generated with [Claude Code]` footer to PR descriptions. Pushing, and opening PRs are actions the user authorizes — don't push or open a PR unless asked.
 ## Verifying a change
@@ -97,6 +95,7 @@ When compressing history, preserve in priority order:
 - `docs/ARCHITECTURE.md` — route map, content model, components, data layer, frontmatter schemas, full configuration reference
 - `docs/CONTRIBUTING.md` — full command list, test layout, content-creation scripts
 - `docs/TROUBLESHOOTING.md` — known issues (AVIF, dev-mode browser-extension CSP/SharedStorage noise)
+- `docs/ALERTS.md` / `docs/CODE-BLOCKS.md` / `docs/DIGITAL_GARDEN.md` — content-feature references (alert callouts, code-block features, garden philosophy)
 - `docs/deployment.md` — production deploy steps
 - `docs/guides/` — task-oriented walkthroughs (e.g. `importing-vuepress-books.md`)
 - `site.config.ts` — live config (read it directly; don't infer from this file)

package/docs/ARCHITECTURE.md CHANGED Viewed

@@ -305,6 +305,87 @@ happens automatically inside `BookLayout`), two extra plugins fire:
 Mermaid diagrams in book chapters already work via the existing `Mermaid` component (any
 \`\`\`mermaid fenced block, with or without a `compact` modifier after the language tag).
+#### Immersive reading mode
+Book chapters AND series posts support an "immersive reading" mode: a
+fullscreen overlay with a top bar, a content-type-specific sidebar on the
+left, and the article in a centred scrollable column. Entered two ways —
+the toggle button in the article header (chapter header for books, post
+header for series), or the secondary "Immersive reading" CTA on the book
+index (`/books/<slug>`) or series index (`/series/<slug>`), which links to
+the first chapter/post with `?immersive=1` appended.
+**Generic reader, content-type-specific shells.** The overlay
+(`src/components/ImmersiveReader.tsx`) and top bar
+(`src/components/ImmersiveReaderTopBar.tsx`) are content-type-agnostic —
+both take `rootHref` / `rootTitle` / `currentTitle` props plus a pre-rendered
+`sidebar` ReactNode. Two shells consume the reader:
+- `src/components/BookReadingShell.tsx` for chapters — passes
+  `<BookSidebar mode="fill" ...>` as the sidebar.
+- `src/components/PostReadingShell.tsx` for series posts — passes
+  `<SeriesList mode="fill" ...>`. The toggle is gated on `post.series`;
+  non-series posts don't see a useless button.
+**Layout boundaries.** The provider needs to survive client-side navigation
+between sibling items within a content unit. Three layout files mount it:
+- `src/app/books/[slug]/layout.tsx` — books reader (chapter-to-chapter).
+- `src/app/[slug]/layout.tsx` — series posts on autoPaths URLs
+  (`/<series-slug>/<post>`), which is the default.
+- `src/app/posts/layout.tsx` — series posts on default-path URLs
+  (`/posts/<slug>`), for sites with `series.autoPaths: false`.
+Each layout file is identical: wraps `{children}` in
+`<ImmersiveReadingProvider>` plus a `<Suspense>`-isolated
+`<ImmersiveReadingFlagHandler />`. The three layouts each mount independent
+provider instances — `enabled` state doesn't bleed between content types —
+but localStorage prefs are shared (same `amytis-reader-prefs` key), so a
+reader's font/theme/width choices carry across books and series.
+**State + persistence.** `src/components/ImmersiveReadingProvider.tsx` holds
+the context. Preferences (`fontSize`, `readingTheme`, `columnWidth`,
+`sidebarOpen`) persist to `localStorage` under `amytis-reader-prefs` via the
+helpers in `src/lib/immersive-reading-prefs.ts`; the read path is per-key
+defensive so schema drift or hand-edited values fall back to their default
+without discarding the whole blob. `enabled` and `prefsPanelOpen` are
+deliberately **not** persisted — entering the reader is a per-visit intent,
+not a preference.
+**`?immersive=1` URL flag.** `src/components/ImmersiveReadingFlagHandler.tsx`
+sits as a sibling of `{children}` inside each layout (wrapped in its own
+`<Suspense>`), reads the query param via `useSearchParams`, calls
+`provider.enter()`, then strips the flag via `router.replace`. The Suspense
+boundary is load-bearing — `useSearchParams` triggers a static-export bailout,
+so wrapping the provider instead would drag the chapter/post page out of
+static prerender.
+**Overlay anatomy** (`ImmersiveReader.tsx`, `position: fixed inset-0 z-40`):
+- `ImmersiveReaderTopBar` — sidebar toggle, breadcrumb (book/chapter or
+  series/post), `Aa` button, exit (✕). The header is `relative z-30` so its
+  `backdrop-blur-md` stacking context paints above article-area code blocks.
+- `ImmersiveReadingPrefsPopover` — anchored under the `Aa` button. Four
+  control groups with visual previews: font size (4 sizes, `A` letters at the
+  actual size), reading theme (Auto / Light / Sepia / Dark colour swatches —
+  Auto reads as a split light/dark gradient), column width (Narrow / Medium /
+  Wide / Full as stacked line-icons), and a "Reset to defaults" link at the
+  bottom (one-click, no confirmation). Dismisses on outside `pointerdown` or
+  ESC; ESC with the popover closed exits the reader.
+- Sidebar in `mode="fill"` — either `BookSidebar` or `SeriesList`, without
+  their page-mode positioning classes. Auto-collapsed below `lg`
+  (one-directional: never auto-opens on resize to wide).
+- Main scroll area — article centred at the column width the user picked
+  (`max-w-2xl` to `max-w-none`).
+**CSS scoping.** `html[data-immersive]` hides site chrome via the three stable
+hooks `data-site-nav` / `data-site-footer` / `data-reading-progress` —
+defense-in-depth (the fixed overlay covers them anyway). Reading-theme
+overrides are scoped to `[data-reader-overlay]` so they don't leak outside the
+reader; when `readingTheme === 'dark'` the overlay also gets Tailwind's `.dark`
+class so `dark:prose-invert` fires regardless of the underlying site theme.
+Shiki code blocks deliberately keep their normal theme.
 ## Configuration Reference (`site.config.ts`)
 | Field | Notes |

package/docs/DIGITAL_GARDEN.md CHANGED Viewed

@@ -92,4 +92,4 @@ Related settings that shape the digital-garden experience live alongside that fl
 - `flows.recentCount`: controls how many flow entries appear on the homepage.
 - `pagination.flows` and `pagination.notes`: control listing page sizes.
-- `homepage.sections`: lets you enable, disable, or reorder homepage sections such as recent flows.
+- `homepage.sections`: lets you enable, disable, or reorder homepage sections such as recent flows. The three curated sections (`featured-posts`, `featured-series`, `featured-books`) also accept an `order` field — `'shuffle'` (default, daily-seeded permutation), `'date-desc'`, or `'date-asc'` — to choose how items inside the section are arranged.

package/docs/guides/importing-vuepress-books.md CHANGED Viewed

@@ -1,10 +1,14 @@
-# Importing a VuePress 2 book
+# Importing a VuePress book
-Amytis can host a VuePress 2 book natively. `bun run sync-vuepress-book`
+Amytis can host a VuePress book natively. `bun run sync-vuepress-book`
 copies the upstream `docs/` tree into a slug under `content/books/`, derives
 Amytis's nested-section book TOC from the VuePress sidebar config, and
 preserves any user-controlled fields you've added to the book's `index.mdx`.
+Both VuePress 2 and VuePress 1 sidebars are supported — the importer
+auto-detects the shape per entry, so a single config can mix `{ text, link }`
+(VP2) and `{ title, path }` (VP1) without configuration.
 The importer is idempotent — re-running mirrors the current state of the
 source (including upstream deletions). You should *not* edit chapter
 markdown files in the dest: they get overwritten on every sync. Customize
@@ -14,8 +18,8 @@ the book's metadata in `index.mdx` (preserved) or extend the source repo.
 ## Prerequisites
-- The source must be a VuePress 2 project where the docs root contains a
-  `.vuepress/` directory with a `config.js` or `config.mjs`.
+- The source must be a VuePress project (1.x or 2.x) where the docs root
+  contains a `.vuepress/` directory with a `config.js` or `config.mjs`.
 - `config.ts` is **not supported** — acorn (used to AST-extract the sidebar)
   parses JS only. Compile to JS first (`tsc`, `bun build --no-bundle`, …) or
   rename to `.mjs` if the config is pure ESM.
@@ -32,6 +36,9 @@ bun run sync-vuepress-book \
 # Positional shorthand:
 bun run sync-vuepress-book /path/to/your-book/docs content/books/your-book
+# Skip extra files alongside the built-in defaults:
+bun run sync-vuepress-book /path/to/docs content/books/foo --skip '*.bak,dist'
 # Then rebuild + preview locally:
 bun run build:dev
 bun dev
@@ -44,8 +51,24 @@ The script prints a one-line summary on completion:
 ```
 It will also warn about anomalies it noticed in the sidebar — empty section
-placeholders, sections with their own page-link header, dropped meta-nav
-leaves (see [Conventions](#conventions) below), etc.
+placeholders, dropped meta-nav leaves (see [Conventions](#conventions)
+below), files filtered out by skip rules, etc.
+## Skip rules
+A VuePress repo's docs root often carries non-content files (lockfiles,
+package manifests, CI configs) that shouldn't land under
+`content/books/<slug>/`. Two flags control filtering:
+| Flag | Default | Effect |
+| --- | --- | --- |
+| `--skip-common` / `--no-skip-common` | on | Skip `package.json`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lock`, `bun.lockb`. |
+| `--skip <pattern,pattern,…>` | empty | Skip files/dirs whose **basename** matches any of the supplied glob patterns. `*` and `?` are supported. Repeatable. Applied to both files and directories anywhere in the tree. |
+Files filtered out by either rule are listed in the run summary. They're
+also pruned from the dest on subsequent re-syncs (the mirror logic applies
+to the same skip rules, so toggling `--no-skip-common` mid-stream brings
+the lockfiles back).
 ## What the script does
@@ -55,9 +78,22 @@ leaves (see [Conventions](#conventions) below), etc.
    literals to a plain JS structure. Unsupported AST shapes throw — silent
    drops would produce a half-correct TOC.
 3. Maps every VuePress sidebar item to one of:
-   - `{ title, id }` for a leaf (`{ text, link }` in VuePress).
-   - `{ section, items, collapsible? }` for a group (`{ text, children }`),
-     recursive — VuePress's two layers of nesting map 1:1.
+   - `{ title, id }` for a leaf. Accepted shapes:
+     - VP2: `{ text, link }`
+     - VP1: `{ title, path }` (no `children`)
+     - VP1: a bare string path (e.g. `'/intro/about-me'`) — the title is
+       read from the source file's frontmatter `title`, falling back to the
+       first H1, then a slug-derived fallback.
+   - `{ section, items, collapsible? }` for a group. Accepted shapes:
+     - VP2: `{ text, children, collapsible? }`
+     - VP1: `{ title, children, collapsable? }` (VP1's `collapsable` is
+       aliased to `collapsible`)
+   - A group entry that carries **both** `path` (VP1) or `link` (VP2) AND
+     `children` (a "section + index page" — common in VP1 books where
+     `/foo/` is the section's README) has its index page **promoted as the
+     first chapter** of the section. The promoted chapter's title is read
+     from the README's frontmatter or first H1, not from the section title,
+     so the sidebar doesn't show the section name twice.
    - Mixed/unknown shapes are warned and skipped.
 4. Validates that every leaf's resolved chapter id has a real source file at
    one of `<id>.md`, `<id>.mdx`, `<id>/README.md(x)`, or `<id>/index.md(x)`.
@@ -75,37 +111,59 @@ leaves (see [Conventions](#conventions) below), etc.
 ## Conventions
-- The sidebar leaf with id `contents` is dropped from the generated TOC —
-  it's a VuePress convention for a hand-written table-of-contents page, and
-  Amytis's book landing page already renders one. The `contents.md` file
-  itself is still copied so the dest layout matches upstream; it just
-  isn't reachable from the TOC.
-- Sections with `collapsible: false` on the VuePress side keep that hint —
-  the Amytis sidebar honors it (forces the section open).
-- A group whose VuePress entry has both `link` and `children` is treated as
-  a pure group; the group's own page link is dropped (warned).
+- Sidebar leaves whose id (case-insensitive, basename only) matches
+  `contents` or `SUMMARY` are dropped from the generated TOC. They're
+  VuePress/GitBook conventions for a hand-written table-of-contents page,
+  and Amytis's book landing page already renders one. The source files are
+  still copied so the dest layout matches upstream; they just aren't
+  reachable from the TOC.
+- Sections with `collapsible: false` (or VP1's `collapsable: false`) on the
+  VuePress side keep that hint — the Amytis sidebar honors it (forces the
+  section open).
+- A group whose VuePress entry has both `link`/`path` and `children` has
+  the index page promoted as the section's first chapter (see "Maps every
+  VuePress sidebar item …" above). Earlier versions dropped the link with
+  a warning; the current behavior is strictly more useful and matches the
+  upstream VuePress click-the-section-title UX.
+- Path normalization is identical for VP1 and VP2: leading `/` stripped,
+  trailing `/` stripped (so `/guide/` resolves to id `guide` and the file
+  is found via the `guide/README.md` or `guide/index.md` candidate), and
+  any `.md`/`.mdx` suffix stripped. Both build-time validation and the
+  runtime chapter resolver accept `<id>.md`, `<id>.mdx`, `<id>/index.md`,
+  `<id>/index.mdx`, `<id>/README.md`, `<id>/README.mdx`.
 ## User-controlled fields in `index.mdx`
-The script forces `chapters:` to whatever the current sidebar produces, but
-leaves the rest of the frontmatter alone if it's already populated:
+The script's footprint on `index.mdx` is deliberately narrow:
+- **First sync** (no `index.mdx` exists yet): a stub is created with
+  `title` (from the VuePress config), today's `date`, `draft: false`,
+  `featured: false`, and the parsed `chapters:`. Plus a one-line prose
+  body identifying the upstream source. These defaults exist solely so
+  the book is loadable by the runtime's Zod schema out of the box.
+- **Every re-sync after that**: only `chapters:` is touched. Every other
+  frontmatter key, including ones you've added (`coverImage`, `excerpt`,
+  `authors`, `latex`, `showChapterExcerpt`, anything else) and any value
+  you've cleared (including intentionally-blank `date: ""`), is preserved
+  exactly. The prose body below the frontmatter is preserved too.
+In other words: edit `index.mdx` once after the first sync, then never
+worry about the script rewriting your choices.
+The handful of fields that matter for book rendering:
-| Field        | Behavior |
+| Field        | Notes |
 | --- | --- |
-| `title`      | Preserved if set; else derived from the VuePress config's `title` |
-| `excerpt`    | Preserved |
-| `date`       | Preserved if set; else today |
-| `coverImage` | Preserved |
-| `featured`   | Preserved (defaults to `false` on first sync) |
-| `draft`      | Preserved (defaults to `false` on first sync) |
-| `authors`    | Preserved |
-| `latex`      | Preserved — set to `true` for math-heavy books to enable KaTeX globally for the book |
-| `showChapterExcerpt` | Preserved (defaults to `false`). Set to `true` if you want the chapter's `excerpt` rendered as a subtitle under the chapter title. The default suppresses it because most chapters open with their own lede paragraph that duplicates the excerpt. |
-| `chapters`   | **Always rewritten** from the sidebar |
-The prose body below the frontmatter is also preserved, so you can write a
-custom landing-page introduction and re-running the script won't blow it
-away.
+| `title`      | Required by the runtime — keep something here. |
+| `excerpt`    | Optional one-liner shown on book listings. |
+| `date`       | Optional. |
+| `coverImage` | Optional. |
+| `featured`   | Show on the home page's featured strip. |
+| `draft`      | Hides the book from listings when `true`. |
+| `authors`    | Optional list. |
+| `latex`      | Set to `true` for math-heavy books to enable KaTeX globally for the book. |
+| `showChapterExcerpt` | Defaults to `false`. Set to `true` if you want each chapter's `excerpt` rendered as a subtitle under the chapter title; most chapters open with their own lede paragraph so the default suppresses it. |
+| `chapters`   | **Always rewritten** from the sidebar. |
 ## What about VuePress-specific content?
@@ -175,4 +233,5 @@ output under `public/books/<slug>/` and the Pagefind search index.
   pipeline plugins listed above.
 - `tests/integration/sync-vuepress-book.test.ts` — covers AST extraction,
   mirror semantics, folder-index links, TS-config rejection, dotfile
-  preservation, and the `contents` skip.
+  preservation, the `contents` skip, and the VP1 sidebar shape (bare-string
+  children, `title`/`collapsable`, README promotion, `SUMMARY` drop).

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@hutusi/amytis",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "A high-performance digital garden and blog engine with Next.js 16 and Tailwind CSS v4",
   "repository": {
     "type": "git",