@burdenoff/website-sdk 2026.830.1 → 2026.922.1

package/README.md

@@ -161,8 +161,8 @@ function Header() {
 | `productSlug` | – | The site this page is on. A soft hint to the assistant, not a hard filter. |
 | `examplePrompts` | – | Prompt chips used only when the backend catalog supplies none. |
 | `className` | – | Extra classes on the page root. |
-| `heightMode` | `'viewport'` | `viewport` pins the chat to the screen with an internally scrolling transcript; `auto` lets the page grow (for embedding). |
-| `viewportOffset` | `0` | Chrome to subtract in `viewport` mode. A number is pixels; a string is any CSS length (`'4rem'`). |
+| `heightMode` | `'viewport'` | `viewport` pins the chat to the screen with an internally scrolling transcript, and is the only mode in which the component manages the host page's scroll position; `auto` lets the page grow and never touches its host's scrolling (for embedding). |
+| `viewportOffset` | `0` | Chrome to subtract in `viewport` mode, **before the first measurement only**. A number is pixels; a string is any CSS length (`'4rem'`). Once mounted the pane measures its own top and this value stops being used — so an approximate header height is fine, and the on-screen keyboard is handled for you. |
 | `onNavigate` | – | SPA navigation for internal CTA paths. Without it, CTAs render as plain links. |
 | `onSend` | – | Fired with the message text each time a send is accepted (analytics). |
 | `welcomeTitle` / `welcomeBody` | catalog values | Override the welcome copy. `welcomeTitle` **is** the page `<h1>`. |
@@ -191,10 +191,121 @@ with it. This is separate from the v2 checkbox used by `ContactPage`.
 setFocusProduct, send, stop, retry, reset, canSend }` — if you want to build a
 different shell around it.
 
+**Inline concept illustrations.** An answer may embed images from the product
+sites' concept pages (`![alt](url)`, followed by the backend's own caption
+line). They render only once the answer is `COMPLETED` — never from a streaming
+preview — and only when the URL is `https` on a catalog product's website
+(apex or `www.`); anything else renders nothing. Each image is lazy-loaded,
+links to the full file in a new tab (unless the markdown already wraps it in a
+link, which then stays the only link), carries a "Concept illustration" badge,
+and disappears entirely if it fails to load. Nothing to wire on the website.
+
 **Testing hooks.** Stable `data-boff-explore` attributes are attached for the
 end-to-end suite: `page`, `messages`, `composer`, `chip`, `thinking`, `user`,
 `assistant` (plus `data-status`), `reference`, `cta` (plus `data-kind`),
-`cta-header`, `cta-mobile`, `cta-floating`, `send`, `stop`, `new-chat`, `error`.
+`cta-header`, `cta-mobile`, `cta-floating`, `send`, `stop`, `new-chat`, `error`,
+`inline-image`.
+
+### Concepts (`/concepts` + `/concept/:slug`)
+
+`ConceptsPage` and `ConceptDetailPage` render a product's concepts: each one a
+feature or flow, shown through the mockups drawn for it and explained in
+reviewed copy. Every image is labelled an **illustration of the concept, not a
+screenshot of the actual product** (`CONCEPT_ILLUSTRATION_NOTICE`).
+
+The data is a generated `src/data/concepts.ts` in each site — never hand-edit
+it; regenerate with
+`python3 ~/products/dev/scripts/concepts/build_site_concepts.py site --product <p>`.
+Both pages take the data as props and make no requests, so they prerender
+completely. Import them from the package **root**, like every other page.
+
+```tsx
+import { Link, Navigate, Route, useParams } from 'react-router'
+import {
+  ConceptDetailPage,
+  ConceptsPage,
+  CONCEPTS_PATH,
+  getConceptBySlug,
+  type ConceptLinkProps,
+} from '@burdenoff/website-sdk'
+import { CONCEPT_CATEGORIES, CONCEPTS } from '@/data/concepts'
+
+const SITE_URL = 'https://vibecontrols.com'
+
+// Router adapter, so concept → concept navigation stays client-side.
+// Without `linkComponent` the pages render plain <a href> links.
+function ConceptLink({ href, className, children, 'aria-label': ariaLabel }: ConceptLinkProps) {
+  return (
+    <Link to={href} className={className} aria-label={ariaLabel}>
+      {children}
+    </Link>
+  )
+}
+
+// The site resolves the slug; an unknown one redirects to the landing page.
+function ConceptRoute() {
+  const { slug } = useParams()
+  const concept = getConceptBySlug(CONCEPTS, slug)
+  if (!concept) return <Navigate to={CONCEPTS_PATH} replace />
+  return (
+    <ConceptDetailPage
+      productName="VibeControls"
+      siteUrl={SITE_URL}
+      concept={concept}
+      concepts={CONCEPTS}
+      categories={CONCEPT_CATEGORIES}
+      linkComponent={ConceptLink}
+    />
+  )
+}
+
+// Routes
+<Route
+  path={CONCEPTS_PATH}
+  element={
+    <ConceptsPage
+      productName="VibeControls"
+      siteUrl={SITE_URL}
+      concepts={CONCEPTS}
+      categories={CONCEPT_CATEGORIES}
+      linkComponent={ConceptLink}
+    />
+  }
+/>
+<Route path="/concept/:slug" element={<ConceptRoute />} />
+```
+
+**`ConceptsPage` props**: `productName`, `siteUrl` (public origin, for
+canonical/OG/JSON-LD URLs), `concepts` (required); `categories` (section order
+and descriptions — a concept in an unlisted category still renders, last),
+`cta` (rendered in the hero), `linkComponent`, `title` (the `<h1>`, default
+`"<Product> concepts"`), `description` (meta description and hero lead; the
+default is built from the counts and stays within 160 characters), `className`.
+With no concepts at all the page says none are published yet, without the
+filter bar or zero counts.
+
+**`ConceptDetailPage` props**: `productName`, `siteUrl`, `concept`, `concepts`
+(all of them — for related concepts and previous / next by `order`);
+`categories`, `cta` (rendered as a band at the end), `linkComponent`,
+`className`.
+
+**Helpers**: `CONCEPTS_PATH` (`/concepts`), `CONCEPT_PATH_PREFIX` (`/concept`),
+`conceptPath(slug)`, `getConceptBySlug(concepts, slug)`; types `Concept`,
+`ConceptImage`, `ConceptCategory`, `ConceptLinkComponent`, `ConceptLinkProps`.
+
+**SEO and llms.** One `<h1>` per page, a self-canonical URL, absolute OG images
+and JSON-LD (`CollectionPage` + `ItemList` + `BreadcrumbList` on the landing
+page; `ImageGallery` + `BreadcrumbList` on a concept). Add `/concepts` and every
+`/concept/<slug>` to the site's prerender list and sitemap. Only the gallery
+images carry `data-llms-image` (one per image — the hero does not), and each is
+followed directly by its `<figcaption>`, which `scripts/llms.mjs` reads as the
+caption. The lightbox is a native `<dialog>` mounted only while open, so it is
+never in the prerendered HTML.
+
+**Testing hooks.** `data-concepts="landing" | "card" (plus data-slug) | "filter"
+| "notice" | "empty" (filters match nothing) | "none" (no concepts at all) |
+"detail" | "category" | "hero" | "illustration" | "related" | "pager" | "cta" |
+"lightbox"`, and `data-concepts-notice` on the notice.
 
 ### SEO Component
 

package/dist/components/contact.js

@@ -290,6 +290,9 @@ function resolveImageUrl(image, base) {
     return image;
   }
 }
+function serializeJsonLd(data) {
+  return JSON.stringify(data).replace(/</g, "\\u003c").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
 function PageHead({
   title,
   description,
@@ -331,7 +334,7 @@ function PageHead({
     fullImageUrl && /* @__PURE__ */ jsxRuntime.jsx("meta", { name: "twitter:image", content: fullImageUrl }),
     twitterHandle && /* @__PURE__ */ jsxRuntime.jsx("meta", { name: "twitter:creator", content: twitterHandle }),
     /* @__PURE__ */ jsxRuntime.jsx("meta", { name: "theme-color", content: themeColor }),
-    structuredDataItems.map((data, index) => /* @__PURE__ */ jsxRuntime.jsx("script", { type: "application/ld+json", children: JSON.stringify(data) }, `ld-${index}`)),
+    structuredDataItems.map((data, index) => /* @__PURE__ */ jsxRuntime.jsx("script", { type: "application/ld+json", children: serializeJsonLd(data) }, `ld-${index}`)),
     additionalMeta?.map((meta, index) => /* @__PURE__ */ jsxRuntime.jsx(
       "meta",
       {