Introduce stable, human-readable canonical URLs for books and authors

[niklhut]

Problem

Library and author routes currently use opaque IDs. Human-readable URLs would make shared links easier to understand, but title and author strings are mutable and non-unique.

Scope

• Keep the existing stable identifier authoritative.
• Add an optional human-readable slug derived from the current title for books and author name for authors.
• Use URL shapes that retain the stable ID, such as /library/books/{id}-{slug} and /library/authors/{id}-{slug}.
• Redirect obsolete, missing, or malformed slugs to the canonical URL without breaking existing ID-only links.
• Define normalization, Unicode, punctuation, collision, and title/author-change behavior.
• Consider SEO only after confirming the privacy model and whether pages are intentionally public; this work is primarily for human-readable navigation.

Acceptance criteria

• Existing links continue to work.
• Two books or authors with identical names remain unambiguous.
• Renaming/correcting a title or author does not invalidate old links.
• Canonical links are used consistently in navigation and page metadata where applicable.
• Tests cover slug generation, canonicalization, and redirects.

[coderabbitai]

🔗 Related PRs

#20 - Normalize book authors into shared author tables [closed]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Derive slugs on demand from the current title or name with a pure, tested utility. Do not store slugs, so title and author changes never break links, because the embedded UUID stays authoritative.
• Serve book detail at /library/books/{id}-{slug} and author detail at /library/authors/{id}-{slug}. Parse the UUID with a strict regex, and redirect any obsolete, missing, malformed, or legacy ID-only URL to the canonical URL with HTTP 301.
• Route all navigation and links through buildBookPath and buildAuthorPath for consistent, human-readable URLs, and add author links so the author route is reachable.
• Skip SEO canonical meta tags, because both detail pages are always authenticated and never publicly indexable. Achieve canonicalization through URL redirects only.

Design Choices

Design Choice 1: Parsing of the composite {id}-{slug} route segment

Options Considered:

1. Keep a single dynamic segment ([id].vue) and parse the raw param with a strict UUID regex in a shared, tested utility.
2. Use a [id]-[slug].vue filename with a definePageMeta({ path }) regex override that constrains :id to the UUID shape so Vue Router exposes two params.
3. Use a single [slug] segment and extract the leading UUID with a regex inside each page.

Chosen Option: 1

Rationale: The UUID canonical form is 36 characters and contains four hyphens, so a naive split on - is ambiguous. A shared parser keeps route-matching simple, avoids Vue Router hyphen ambiguity, and centralizes parsing in one unit-tested function reused by both pages.

Design Choice 2: Character set for the generated slug

Options Considered:

1. Fold diacritics with Unicode NFKD, then keep [a-z0-9], replace other runs with a single hyphen, trim, and cap length. Non-Latin scripts reduce to an empty slug and produce an ID-only canonical URL.
2. Preserve Unicode letters and numbers with \p{L}\p{N} and rely on URL encoding.

Chosen Option: 1

Rationale: The codebase uses Unicode-aware normalization, but shared URLs read best as ASCII. ASCII slugs produce clean, portable shared links, and the empty-slug fallback stays valid because the slug is cosmetic and the ID remains authoritative.

Design Choice 3: Adding canonical metadata

Options Considered:

1. Do not add canonical link meta, because both detail pages are always authenticated and never publicly reachable.
2. Add canonical link meta anyway.

Chosen Option: 1

Rationale: The ticket asks to consider SEO only after confirming the privacy model. The pages are private with no public access path, so SEO canonical tags add no value; canonicalization is achieved by redirecting the browser URL instead.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Slug generation and parsing utility

This phase adds the pure, deterministic logic that converts a title or author name into a slug, builds canonical paths, and extracts the UUID from a composite route segment. The slug is never stored; it is derived on demand from the current title or name. When the title changes, a new canonical slug results, and the UUID keeps resolving old links.

Task 1: Add the slug utility

Create a shared, pure utility that all pages and links reuse.

• Create shared/utils/slug.ts, following the normalization style of shared/utils/tag-ingestion.ts and shared/utils/book-location.ts.
• Add slugify(text): lowercase the text, apply Unicode NFKD, strip combining marks, replace each run of non-[a-z0-9] characters with a single hyphen, trim leading and trailing hyphens, and cap the result at a SLUG_MAX_LENGTH constant. Return an empty string when no usable characters remain.
• Add buildBookPath(id, title). It returns /library/books/{id} when the slug is empty, and /library/books/{id}-{slug} otherwise.
• Add buildAuthorPath(id, name). It returns /library/authors/{id} or /library/authors/{id}-{slug} with the same rule.
• Add parseIdSlug(param). It matches a strict UUID at the start of the raw route param and returns { id, slug }, where slug is the remainder after the UUID and its separating hyphen, or an empty string. It returns a null id when the param does not begin with a valid UUID.
• Document the collision and mutation behavior in JSDoc: the slug is cosmetic, the embedded UUID guarantees uniqueness, and identical titles remain unambiguous.

Task 2: Unit tests for the slug utility

Cover generation, parsing, and edge cases.

• Create test/unit/slug.test.ts, following the style of test/unit/isbn.test.ts and test/unit/location-hierarchy.test.ts.
• Assert slugify output for diacritics, punctuation, mixed case, collapsed whitespace, length capping, and non-Latin input that reduces to an empty slug.
• Assert buildBookPath and buildAuthorPath for both the empty-slug case and the populated-slug case.
• Assert parseIdSlug for an ID-only param, an {id}-{slug} param, a slug that itself contains hyphens, and a malformed non-UUID param.

🤖 Prompt for AI agents

Implement Phase 1: build the pure slug generation and parsing utility that later
phases depend on. Goal: produce deterministic slugs from titles and author
names, build canonical paths, and parse the UUID out of a composite route
segment, all without persisting any slug value.

- Create `shared/utils/slug.ts`, following the normalization style already used
in `shared/utils/tag-ingestion.ts` and `shared/utils/book-location.ts`.
- Implement `slugify(text)`: lowercase, apply Unicode NFKD normalization, strip
combining marks, replace each run of characters outside `[a-z0-9]` with a single
hyphen, trim leading and trailing hyphens, and cap the length using a
`SLUG_MAX_LENGTH` constant. Return an empty string when nothing usable remains.
- Implement `buildBookPath(id, title)`: return `/library/books/{id}` when the
computed slug is empty, otherwise `/library/books/{id}-{slug}`.
- Implement `buildAuthorPath(id, name)`: same empty-slug vs populated-slug rule,
using `/library/authors/{id}` and `/library/authors/{id}-{slug}`.
- Implement `parseIdSlug(param)`: match a strict UUID at the start of the raw
param, return `{ id, slug }` where `slug` is whatever follows the UUID and its
separating hyphen (empty string if nothing follows); return a null `id` if the
param does not start with a valid UUID.
- Add JSDoc documenting that the slug is cosmetic, the embedded UUID guarantees
uniqueness, and that identical titles or names remain unambiguous.
- Create `test/unit/slug.test.ts` in the style of `test/unit/isbn.test.ts` and
`test/unit/location-hierarchy.test.ts`. Test `slugify` against diacritics,
punctuation, mixed case, collapsed whitespace, length capping, and non-Latin
text reducing to an empty slug. Test `buildBookPath` and `buildAuthorPath` for
both empty-slug and populated-slug outputs. Test `parseIdSlug` against an
ID-only param, an `{id}-{slug}` param, a slug containing hyphens, and a
malformed non-UUID param.

Phase 2: Canonical routing and redirects

This phase moves the book detail page under /library/books/, adapts the author detail page to the new URL shape, and adds canonicalization redirects. Each detail page resolves data by the authoritative UUID, computes the canonical slug from the current title or name, and redirects with HTTP 301 when the requested slug is missing, obsolete, or malformed. Old ID-only links keep working through these redirects.

Task 1: Move and canonicalize the book detail page

Serve book detail at the new canonical URL shape.

• Create app/pages/library/books/[id].vue, moving the existing detail logic from app/pages/library/[id].vue (route param read, useFetch to /api/books/:id, useBookDetailActions, usePageTitle).
• Read the raw param and call parseIdSlug to obtain the authoritative id and the requested slug.
• Fetch the book by the extracted id, and preserve the existing "Book not found" fallback UI when the fetch resolves empty.
• After the book resolves, compute the canonical slug from book.title. When the requested slug differs from the canonical slug, return navigateTo(buildBookPath(id, book.title), { redirectCode: 301, replace: true }) at the top level so the redirect runs during SSR and client navigation.
• Keep usePageTitle. Do not add canonical link meta, per the privacy decision.

Task 2: Adapt the author detail page to the new URL shape

Serve author detail at /library/authors/{id}-{slug} while the same page still accepts old ID-only links.

• Update app/pages/library/authors/[id].vue to parse its param with parseIdSlug and fetch by the extracted id (the existing /api/authors/:id/books pagination logic is unchanged).
• After the author resolves, compute the canonical slug from author.name. When the requested slug differs, return navigateTo(buildAuthorPath(id, author.name), { redirectCode: 301, replace: true }).
• The same page transparently handles the legacy /library/authors/{id} form, because parseIdSlug returns an empty slug for a bare UUID and the redirect then adds the canonical slug.

Task 3: Redirect legacy book ID-only links

Keep existing /library/{id} links working after the move.

• Replace the body of app/pages/library/[id].vue with a thin redirect: return navigateTo('/library/books/' + route.params.id, { redirectCode: 301, replace: true }).
• The target book page then computes and appends the canonical slug, so a legacy ID-only link resolves to the full canonical URL.
• Confirm this file no longer shadows /library/add, /library/index, or the /library/books/ and /library/authors/ folders (static and nested routes take priority over the single-segment [id]).

Task 4: Update the library list route-shape awareness

Keep scroll-preservation logic aligned with the new detail path.

• Update the onBeforeRouteLeave regex in app/pages/library/index.vue that currently matches /^\/library\/(?!add$)[^/]+$/, so it recognizes the new /library/books/{id}-{slug} detail path when preserving scroll position.

🤖 Prompt for AI agents

Implement Phase 2: move book detail to its new canonical route, adapt author
detail to the new URL shape, and add HTTP 301 redirects so every legacy,
missing, or malformed slug resolves to the canonical URL. Each page must resolve
data strictly by the authoritative UUID, and only afterward decide whether a
redirect to the canonical slug is needed.

- Create `app/pages/library/books/[id].vue` by moving the existing logic from
`app/pages/library/[id].vue`: the route param handling, `useFetch` call to
`/api/books/:id`, `useBookDetailActions`, and `usePageTitle`. Parse the raw
param with `parseIdSlug` to get the authoritative `id` and requested `slug`.
Fetch the book by `id`, preserving the existing "Book not found" fallback UI
when the fetch is empty. After the fetch resolves, compute the canonical slug
from `book.title`; if the requested slug does not match, return
`navigateTo(buildBookPath(id, book.title), { redirectCode: 301, replace: true
})` at the top level of the page setup so it applies during both SSR and client
navigation. Keep `usePageTitle`. Do not add canonical `<link>` meta tags.
- Update `app/pages/library/authors/[id].vue` to parse its param with
`parseIdSlug` and fetch by the extracted `id`, leaving the existing
`/api/authors/:id/books` pagination logic unchanged. After the author resolves,
compute the canonical slug from `author.name`; if the requested slug differs,
redirect with `navigateTo(buildAuthorPath(id, author.name), { redirectCode: 301,
replace: true })`. Confirm the legacy bare-UUID form is handled automatically
since `parseIdSlug` returns an empty slug in that case, triggering the same
redirect logic.
- Replace the body of `app/pages/library/[id].vue` with a thin redirect that
returns `navigateTo('/library/books/' + route.params.id, { redirectCode: 301,
replace: true })`. Verify this file does not shadow `/library/add`,
`/library/index`, or the new `/library/books/` and `/library/authors/` folders,
since static and nested routes take priority over the single-segment `[id]`
route.
- Update the `onBeforeRouteLeave` regex in `app/pages/library/index.vue`
(currently `/^\/library\/(?!add$)[^/]+$/`) so it also recognizes the new
`/library/books/{id}-{slug}` path for scroll-position preservation.

Phase 3: Canonical links in navigation

This phase makes every outbound link and programmatic navigation to a book or author use the canonical builders, so shared links are human-readable and consistent.

Task 1: Use canonical paths in book navigation components

Route all book links through buildBookPath.

• Update app/components/BookCard.vue NuxtLink target to buildBookPath(id, title) (both fields are already required props).
• Update the navigateTo calls in app/components/LoanedOutLoansSection.vue, app/components/add/ManualEntryTab.vue, and app/components/add/IsbnLookupTab.vue to use buildBookPath with the title already present on the relevant object.

Task 2: Link author names to the canonical author page

Give the author route reachable, canonical inbound links.

• Update app/components/BookDetailHeader.vue to render each author name as a NuxtLink to buildAuthorPath(author.id, author.name), using the book.authors array that already carries id and name.

Task 3: End-to-end coverage for canonicalization and redirects

Verify existing links, canonical links, and redirects.

• Extend the Playwright specs under test/e2e/ (following test/e2e/20-library-mutations.spec.ts and the helpers in test/e2e/support/books.ts) to assert that clicking a book navigates to a /library/books/{id}-{slug} URL.
• Assert that visiting a legacy /library/{id} URL redirects to the canonical /library/books/{id}-{slug} URL.
• Assert that visiting a book URL with a wrong or missing slug redirects to the canonical URL, reusing the "assert URL shape, not exact value" regex convention already used in the specs.

🤖 Prompt for AI agents

Implement Phase 3: update every navigation link and programmatic navigation call
to use the canonical path builders from Phase 1, and add end-to-end coverage for
the new canonicalization and redirect behavior.

- Update `app/components/BookCard.vue` so its `NuxtLink` target uses
`buildBookPath(id, title)` instead of the raw ID; both `id` and `title` are
already required props on the component.
- Update the `navigateTo` calls in `app/components/LoanedOutLoansSection.vue`,
`app/components/add/ManualEntryTab.vue`, and
`app/components/add/IsbnLookupTab.vue` to build their target paths with
`buildBookPath`, using the title already available on the relevant object in
each case.
- Update `app/components/BookDetailHeader.vue` to render each author name as a
`NuxtLink` pointing to `buildAuthorPath(author.id, author.name)`, using the `id`
and `name` already present on entries in the `book.authors` array. This makes
the author route reachable from the UI.
- Extend the Playwright specs under `test/e2e/`, following the style of
`test/e2e/20-library-mutations.spec.ts` and the helpers in
`test/e2e/support/books.ts`. Add assertions that clicking a book navigates to a
`/library/books/{id}-{slug}` URL, that visiting a legacy `/library/{id}` URL
redirects to the canonical `/library/books/{id}-{slug}` URL, and that visiting a
book URL with a wrong or missing slug redirects to the canonical URL. Reuse the
existing convention of asserting URL shape via regex rather than an exact value.

Research

The app is a Nuxt 3 project. Book detail lives at app/pages/library/[id].vue and author detail lives at app/pages/library/authors/[id].vue. Both pages read route.params.id as an opaque UUID, fetch a user-scoped API (/api/books/:id, /api/authors/:id/books), and set the document title with usePageTitle. All domain IDs are UUID v4 strings. Neither books.title nor authors.name is unique, and titles plus book-author links can change through CSV re-import. Both detail pages require authentication through app/middleware/auth.global.ts; there is no public access path, so search engines cannot index them. Links to book detail come from app/components/BookCard.vue and several navigateTo call sites; author detail is not linked anywhere yet. String normalization follows a lightweight regex convention (see shared/utils/tag-ingestion.ts), and pure utilities have unit tests under test/unit/. No slug utility exists today.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement Phase 1: build the pure slug generation and parsing utility that later
phases depend on. Goal: produce deterministic slugs from titles and author
names, build canonical paths, and parse the UUID out of a composite route
segment, all without persisting any slug value.

- Create `shared/utils/slug.ts`, following the normalization style already used
in `shared/utils/tag-ingestion.ts` and `shared/utils/book-location.ts`.
- Implement `slugify(text)`: lowercase, apply Unicode NFKD normalization, strip
combining marks, replace each run of characters outside `[a-z0-9]` with a single
hyphen, trim leading and trailing hyphens, and cap the length using a
`SLUG_MAX_LENGTH` constant. Return an empty string when nothing usable remains.
- Implement `buildBookPath(id, title)`: return `/library/books/{id}` when the
computed slug is empty, otherwise `/library/books/{id}-{slug}`.
- Implement `buildAuthorPath(id, name)`: same empty-slug vs populated-slug rule,
using `/library/authors/{id}` and `/library/authors/{id}-{slug}`.
- Implement `parseIdSlug(param)`: match a strict UUID at the start of the raw
param, return `{ id, slug }` where `slug` is whatever follows the UUID and its
separating hyphen (empty string if nothing follows); return a null `id` if the
param does not start with a valid UUID.
- Add JSDoc documenting that the slug is cosmetic, the embedded UUID guarantees
uniqueness, and that identical titles or names remain unambiguous.
- Create `test/unit/slug.test.ts` in the style of `test/unit/isbn.test.ts` and
`test/unit/location-hierarchy.test.ts`. Test `slugify` against diacritics,
punctuation, mixed case, collapsed whitespace, length capping, and non-Latin
text reducing to an empty slug. Test `buildBookPath` and `buildAuthorPath` for
both empty-slug and populated-slug outputs. Test `parseIdSlug` against an
ID-only param, an `{id}-{slug}` param, a slug containing hyphens, and a
malformed non-UUID param.
===============================================================================

Task: 2

Implement Phase 2: move book detail to its new canonical route, adapt author
detail to the new URL shape, and add HTTP 301 redirects so every legacy,
missing, or malformed slug resolves to the canonical URL. Each page must resolve
data strictly by the authoritative UUID, and only afterward decide whether a
redirect to the canonical slug is needed.

- Create `app/pages/library/books/[id].vue` by moving the existing logic from
`app/pages/library/[id].vue`: the route param handling, `useFetch` call to
`/api/books/:id`, `useBookDetailActions`, and `usePageTitle`. Parse the raw
param with `parseIdSlug` to get the authoritative `id` and requested `slug`.
Fetch the book by `id`, preserving the existing "Book not found" fallback UI
when the fetch is empty. After the fetch resolves, compute the canonical slug
from `book.title`; if the requested slug does not match, return
`navigateTo(buildBookPath(id, book.title), { redirectCode: 301, replace: true
})` at the top level of the page setup so it applies during both SSR and client
navigation. Keep `usePageTitle`. Do not add canonical `<link>` meta tags.
- Update `app/pages/library/authors/[id].vue` to parse its param with
`parseIdSlug` and fetch by the extracted `id`, leaving the existing
`/api/authors/:id/books` pagination logic unchanged. After the author resolves,
compute the canonical slug from `author.name`; if the requested slug differs,
redirect with `navigateTo(buildAuthorPath(id, author.name), { redirectCode: 301,
replace: true })`. Confirm the legacy bare-UUID form is handled automatically
since `parseIdSlug` returns an empty slug in that case, triggering the same
redirect logic.
- Replace the body of `app/pages/library/[id].vue` with a thin redirect that
returns `navigateTo('/library/books/' + route.params.id, { redirectCode: 301,
replace: true })`. Verify this file does not shadow `/library/add`,
`/library/index`, or the new `/library/books/` and `/library/authors/` folders,
since static and nested routes take priority over the single-segment `[id]`
route.
- Update the `onBeforeRouteLeave` regex in `app/pages/library/index.vue`
(currently `/^\/library\/(?!add$)[^/]+$/`) so it also recognizes the new
`/library/books/{id}-{slug}` path for scroll-position preservation.
===============================================================================

Task: 3

Implement Phase 3: update every navigation link and programmatic navigation call
to use the canonical path builders from Phase 1, and add end-to-end coverage for
the new canonicalization and redirect behavior.

- Update `app/components/BookCard.vue` so its `NuxtLink` target uses
`buildBookPath(id, title)` instead of the raw ID; both `id` and `title` are
already required props on the component.
- Update the `navigateTo` calls in `app/components/LoanedOutLoansSection.vue`,
`app/components/add/ManualEntryTab.vue`, and
`app/components/add/IsbnLookupTab.vue` to build their target paths with
`buildBookPath`, using the title already available on the relevant object in
each case.
- Update `app/components/BookDetailHeader.vue` to render each author name as a
`NuxtLink` pointing to `buildAuthorPath(author.id, author.name)`, using the `id`
and `name` already present on entries in the `book.authors` array. This makes
the author route reachable from the UI.
- Extend the Playwright specs under `test/e2e/`, following the style of
`test/e2e/20-library-mutations.spec.ts` and the helpers in
`test/e2e/support/books.ts`. Add assertions that clicking a book navigates to a
`/library/books/{id}-{slug}` URL, that visiting a legacy `/library/{id}` URL
redirects to the canonical `/library/books/{id}-{slug}` URL, and that visiting a
book URL with a wrong or missing slug redirects to the canonical URL. Reuse the
existing convention of asserting URL shape via regex rather than an exact value.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!