[kris1027]

What

Shoppers can now find products three ways: a page per visible category (linked from the header), a name search (a box in the header), and a home page that lists the whole catalog with paging. Every listing shares the same filters (price, option values like size and colour, in stock, on sale) and sort orders, and the URL holds the full state. Admins can also arrange the products inside a category.

Why

Implements docs/specs/0013-categories-search-filters/index.md (feature 13 on the scope). At a few hundred products, the spec picks one cached listing index filtered in plain code per request: no schema change and no database query per search. Options and reasoning are in rationale.md.

Changes

Listing engine (pure, in src/features/catalog/listing/)

• getListingIndex() reads every listable product (active, with at least one live variant) once into a 'use cache' entry tagged catalog and categories. It stores inStock as a boolean, never the stock count.
• buildListing() does search, variant level filters, facet counts, sorting and paging as pure functions.
• parseListingParams() and listingHref() turn the URL into state and back. Bad params are repaired or dropped silently, and one state always has one URL (stable param order, defaults left out).
• src/lib/search-text.ts adds foldText, searchWords and facetKey, so kosciol finds "Kościół" and "Colour" / "COLOUR" become one filter group.

Storefront

• New routes /categories/[slug] and /search. Home / becomes the full listing; the 48 product cap and getActiveProducts are gone.
• Header gets the category nav (desktop and mobile menu) and a search box that works as a plain GET form without JavaScript.
• New listing UI: filter panel (sidebar on desktop, Sheet on mobile), removable filter chips, sort select, numbered pagination, empty states, loading skeleton.
• With JavaScript, filters apply instantly via router.push so Back undoes the last change. Without it, the panel is a form with an Apply button.
• SEO: category titles and descriptions use the meta fields with fallbacks, /search is noindex, follow and never puts query text in metadata, and home and category pages declare their plain path as canonical.

Admin

• /admin/categories/<id> turns its product list into the shared sortable list with an explicit Save order. The new reorderCategoryProducts action locks the category row, refuses with stale unless the submitted ids match the current set exactly, and rewrites positions 0..n-1 in one statement.
• Every category write (create, update, delete, reorder, set products, the arrange action, plus updateProductCategories and createProduct) now expires the new categories cache tag, so changes show on the next storefront request.

How to test / verify

• pnpm test: pure rules in src/lib/search-text.test.ts and src/features/catalog/listing/*.test.ts (search folding, matching and ranking, filters, counts, params repair, paging).
• pnpm test:db (needs pnpm db:start): tests/db/catalog-listing.db.test.ts and tests/db/categories.db.test.ts (index contents, cache tags, the reorder action and its stale path).
• pnpm test:e2e tests/e2e/catalog/discovery.spec.ts: the discovery flows, filters, search and category arrange on desktop and mobile, plus axe on home, a category and /search with filters open.
• By hand, you might try: search kosciol for a product named "Kościół"; open /categories/<slug>?min=50&max=10&page=999&sort=zzz and see the range swapped, the last page and Featured order; copy a filtered URL into a private window and get the same results.

All 25 acceptance criteria were ticked in verify.md. Some value sourcing checks there are still open (unticked).

Risk & rollout

No migrations, no flags. The only write is product_categories.position, through the new admin action. The home page changes from a capped grid to the full paged listing, and every storefront page now reads the cached category nav. Rollback is a plain revert.

Notes for reviewers

• The whole catalog is filtered in memory per request. That is the deliberate call for a few hundred products (see the rationale); it would need revisiting for a much larger catalog.
• Under Cache Components, an unknown or hidden category renders the not found page with status 200, the same as the product page today (AC-2).
• The header search box never prefills (that would need useSearchParams and Suspense in every header); /search has its own prefilled box instead.
• Facet counts for one group ignore that group's own selection, so counts inside a group can add up to more than the total. That is intended (AC-14).
• tabTo in tests/e2e/a11y.ts now allows up to 200 presses, because category links in the header add tab stops and local e2e runs leave many categories behind.

🤖 Generated with Claude Code