[kris1027]

What

Every public storefront page now has full search and share metadata: a unique title and description, an absolute canonical link, and an Open Graph share card. Product pages also carry Product structured data (JSON-LD) with one Offer per variant, the "Was" price and the delivery fee. The store gains a robots.txt that blocks crawling everywhere except production, a sitemap of every public page, and a generated brand share card and logo. Nothing in the database changes.

Why

Implements spec 0018 (scope feature 17, Launch readiness). Shoppers should see real price, availability and sale in search results and a proper image when a link is shared; the store owner wants every public product and category found and nothing hidden indexed; and preview deploys must never compete with the real store in search. Options and reasoning are in rationale.md.

Changes

Shared SEO helpers (src/lib/seo/)

• pageMetadata builds title, description, absolute canonical, Open Graph and Twitter card for every indexable page. It replaces legalMetadata and the category page's hand written metadata. og:locale comes from STORE_LOCALE (pl_PL style, omitted for a bare language).
• The root layout sets metadataBase from NEXT_PUBLIC_SITE_URL, so every URL is absolute on the site's own origin.
• plainExcerpt turns Markdown into plain text and cuts it at a word boundary at 160 characters with …. It uses mdast-util-from-markdown and mdast-util-to-string (new direct dependencies, already inside the react-markdown tree).
• JsonLdScript is the one place JSON-LD is written, and it escapes every <, so admin text holding </script> cannot break out of the tag. JSON-LD is typed with schema-dts (dev dependency, types only).
• robotsRules(vercelEnv, siteUrl): under VERCEL_ENV=production, allow /, disallow /admin, /api, /auth, and name the sitemap. Anything else (preview, local, CI, unset) is Disallow: /.

Product pages

• Title and description from meta_title / meta_description, falling back to the name and the description's plain text. og:image is the first gallery photo, or the brand card when there is none.
• Product JSON-LD with every gallery image, the brand, and one Offer per live variant: SKU, price as a decimal string, currency, InStock / OutOfStock (low stock counts as in stock, and no stock count is ever written), NewCondition, a StrikethroughPrice when the compare at price is above the price, and shippingDetails from the same shippingCents rule the cart uses, read from the cached settings so an admin save shows on the next request.
• getProductBySlug now also returns metaTitle, metaDescription and each variant's sku.
• The script mounts after the not found check, so a hidden product gets none.

Listings (home and category)

• A pure listingCanonical rule on the parsed listing state: any filter or non default sort points at the plain path; an unfiltered paged view points at ?page=N, where N is the page actually shown. shownPage is now exported from listing.ts and used by both buildListing and the canonical rule, so they cannot drift. Unknown params like ?utm_source=x are ignored.
• Paged titles gain , page N. No search or filter text ever reaches metadata.
• Category descriptions fall back through plainExcerpt. Category pages render a BreadcrumbList; the home page renders Organization and WebSite JSON-LD in its static shell.
• /search stays noindex, follow, with no canonical, and now uses the brand card.

Brand images

• /brand-card.png (1200x630) and /logo.png (512x512) are fixed path next/og route handlers, prerendered at build. app/icon.tsx reuses the logo as the tab icon; favicon.ico stays.
• New brand.colors in src/lib/brand/brand.ts: sRGB hex copies of the background and foreground tokens, since next/og cannot read oklch.

Sitemap

• /sitemap.xml lists home, the five legal pages (dated by their updated front matter), every visible category, and every active product with a live variant plus its image URLs. Nothing else.
• Reads go through two 'use cache' functions tagged catalog and categories, so an existing product or category write shows up on the next request with no deploy.

Docs: spec 0018 with rationale and verify steps, scope feature 17 marked done (plus a new parked item for return window and delivery time as data), and src/features/legal/AGENTS.md updated for legalSeo.

How to test / verify

• pnpm install (two new dependencies, one new dev dependency). No migration.
• pnpm test for the metadata helper, excerpt, JSON-LD escaping, structured data builders, robots rule (both branches), canonical rule, product SEO and the sitemap composition.
• pnpm test:db -- tests/db/sitemap.db.test.ts for drafts, archived and variant less products and hidden categories staying out of the sitemap.
• pnpm test:e2e tests/e2e/seo for product, category, home, search and legal heads, JSON-LD, paged canonicals, the sitemap, robots, and hidden and private pages staying noindex.
• By hand: curl -s localhost:3000/robots.txt shows Disallow: / locally. Open /brand-card.png and /logo.png. When reading a page's head, send a Googlebot user agent, since Next only blocks on metadata for known bots.

The full checklist with results is in verify.md.

Risk & rollout

• No migration, no flags. Rollback is reverting the branch.
• Home and category metadata now render at request time, because they read searchParams for the canonical page. Normal browsers get the head streamed after the shell; crawlers still get it up front. The results were already request time, so the shells stay as they were.
• Robots defaults to blocking. Only a build with VERCEL_ENV=production allows crawling, and robots.ts prerenders at build, which matches how Vercel builds production deployments.
• Two verify steps are still open: running one product page through Google's Rich Results Test on a preview build, and the by hand check that publishing or hiding a product changes the sitemap with no deploy, including on pnpm build && pnpm start (the e2e test "the sitemap follows a publish and a hide on the next request" already covers it).
• Google's merchant report will warn about the missing return policy and delivery time until those exist as real data (parked in the scope).
• Before launch, the "Was" price marked as StrikethroughPrice needs to be the lowest price of the previous 30 days (EU Omnibus rule); see rationale.md.

Notes for reviewers

• Worth extra eyes: the canonical rule in src/features/catalog/listing/canonical.ts and its use of shownPage, and the Offer building in src/features/catalog/seo.ts.
• The brand card and logo are fixed path route handlers rather than the opengraph-image file convention on purpose: the convention gives a hashed URL the Organization logo cannot name, and Next merges openGraph shallowly, so a child page could drop the inherited image.
• This narrows spec 0013 AC-24: unfiltered paged listings now canonicalize to themselves, not the plain path.
• No /check review record exists yet for this branch in docs/reviews/.

🤖 Generated with Claude Code