@sonordev/site-kit 7.0.1 → 7.0.2

package/src/engage/README.md

@@ -0,0 +1,241 @@
+# Engage — `@sonordev/site-kit/engage`
+
+Popups, nudges, bars, slide-ins, and chat widgets — all configured from the Sonor dashboard.
+
+## Usage
+
+Auto-included by `SiteKitLayout`. For standalone use:
+
+```tsx
+'use client'
+import { EngageWidget } from '@sonordev/site-kit/engage'
+
+export default function Layout({ children }) {
+  return (
+    <>
+      {children}
+      <EngageWidget />
+    </>
+  )
+}
+```
+
+## Props
+
+```ts
+interface EngageWidgetProps {
+  apiUrl?: string             // Default: https://api.sonor.io
+  apiKey?: string             // From SiteKitLayout or env
+  projectId?: string          // For chat routing
+  position?: 'bottom-right' | 'bottom-left'  // Default: 'bottom-right'
+  offsetBottom?: string | number             // Default: '20px'. See "Launcher placement"
+  zIndex?: number             // Default: 9999. Popups, nudges, bars and the chat. See "Stacking"
+  chatEnabled?: boolean       // Default: true. See "The chat switch"
+  debug?: boolean
+}
+```
+
+Through `SiteKitLayout`, the same options go in `engage={{ ... }}`.
+
+## The chat switch
+
+Echo follows the project's **Enable Chat Widget** switch in Sonor (Engage,
+Chat settings). A project that has never saved chat settings counts as on, so
+Echo is on by default and only an owner who switches it off hides it. It also
+needs the project's **Engage** module on (Project Settings); without it Sonor
+answers off, since the chat has nowhere to take a visitor's message.
+
+- The launcher appears once `GET /engage/widget/config` answers. Nothing
+  renders before that, so a switched-off site never flashes a launcher, and
+  it never starts Echo's availability polling.
+- If the config can't be fetched, the launcher stays hidden. The chat can't
+  run without the API anyway.
+- `chatEnabled: false` (or `engage={false}`) in code still turns chat off
+  whatever the switch says. Code can turn Echo off; it can't force it on over
+  the owner's switch.
+
+## Liquid Glass (6.1.0)
+
+Echo's launcher and chat window are made of the kit's shared Liquid Glass
+recipe (`src/shared/glass.tsx`), the same material as the mobile CTA bar
+(`@sonordev/site-kit/cta-bar`), so the two always match.
+
+- **Launcher:** brand-tinted glass (86% brand over a blurred backdrop) with a
+  specular rim. The icon turns dark on a light brand colour; it used to stay
+  white and disappear.
+- **Chat window:** a glass panel (86% tint, 28px blur) that grows out of the
+  launcher's corner. The header is part of the sheet, washed with the brand
+  at the top, and the brand sits on the avatar tile, the visitor's bubbles,
+  the send button and the launcher.
+- **Bubbles and the composer stay near-opaque** (94%). The glass is depth,
+  never the surface text reads against.
+- **Brand text always reads (6.1.2).** Where the brand is text on the panel
+  (quick-action chips, the phone link, link buttons, suggestion chips, "Talk
+  to a person"), Echo uses the brand as-is when it clears WCAG AA against the
+  panel, and otherwise pulls it toward black (light panel) or white (dark
+  panel) just far enough to clear it: `#d4af37` gold becomes `#887023`. Fills
+  (launcher, avatar, the visitor's bubbles, buttons) keep the raw brand. One
+  helper decides this, `src/engage/brand-color.ts`; route any new brand
+  foreground through it. `--sk-primary` can be hex, `rgb()` or `hsl()`.
+- **Fields are 16px.** iOS Safari zooms the whole page into any focused field
+  under 16px; the chat input and the inline Echo forms were 13.5-14px.
+- **Fallbacks:** no `backdrop-filter`, reduced transparency, or more contrast
+  all get the same surfaces solid. Reduced motion skips the open animation.
+
+Tune it with the shared tokens, from your own stylesheet:
+
+```css
+:root {
+  --sk-glass-panel-opacity: 92%;   /* denser chat window (default 86%) */
+  --sk-glass-brand-opacity: 100%;  /* solid brand launcher (default 86%) */
+  --sk-glass-tint: #0b0b0c;        /* dark glass; pair with --sk-text-primary */
+}
+```
+
+`--sk-glass-panel-opacity: 100%` gives the pre-6.1 solid window back, with the
+glass header.
+
+## Launcher placement
+
+The Echo launcher is a 60px circle, fixed 20px from the side and 20px above
+the bottom edge. Its placement is an inline style, so a stylesheet can't move
+it without `!important`. Don't write that override; declare the offset instead.
+
+**A fixed offset, every page:** pass `offsetBottom`.
+
+```tsx
+<SiteKitLayout engage={{ offsetBottom: '88px' }}>{children}</SiteKitLayout>
+```
+
+Any CSS length works (`'5.5rem'`, `'calc(4rem + 8px)'`); a number is pixels.
+The device's safe-area inset is added on top, so pass the clearance you want
+above your own UI, not the inset.
+
+**An offset that depends on the page or the breakpoint:** set the
+`--sk-echo-offset-bottom` custom property from your stylesheet. The launcher
+is portalled to `<body>`, so a declaration on `body` or `:root` reaches it,
+and the property wins over `offsetBottom`. This clears a sticky mobile bar
+only on the pages that render one:
+
+```css
+@media (max-width: 1023.98px) {
+  body:has(.sticky-cta) {
+    --sk-echo-offset-bottom: 5.5rem;
+  }
+}
+```
+
+Pages without the bar, desktop, and any browser without `:has()` keep the
+default. No `!important`, no selector on the kit's markup.
+
+**Using the kit's `<CtaBar>`?** Write nothing. It sets
+`--sk-echo-offset-bottom` itself while it's on screen, below its breakpoint,
+and the launcher glides up and back down as the bar shows and hides. Delete
+any rule like the one above that was written for a hand-rolled bar.
+
+**The popup follows.** It opens 10px above the launcher and keeps 30px clear
+of the top edge, wherever the offset puts the launcher. (An override that
+moved only the `<button>` left the popup behind, with the launcher over its
+input row.)
+
+The resolved position is:
+
+```
+launcher bottom = offset + env(safe-area-inset-bottom) + var(--sk-vv-layout-gap, 0px)
+popup bottom    = launcher bottom + 70px
+popup maxHeight = 100dvh - launcher bottom - 100px
+```
+
+### Stacking
+
+`zIndex` is the one layer everything Engage renders sits on: popups, nudges,
+bars and the chat launcher. The chat popup sits one layer beneath the
+launcher. The default is 9999, above almost anything a site draws, so lower it
+when your own fixed UI (a mobile menu, a cookie banner) has to cover the chat:
+
+```tsx
+<SiteKitLayout engage={{ zIndex: 40 }}>{children}</SiteKitLayout>
+```
+
+```
+launcher z-index = zIndex (default 9999)
+popup z-index    = zIndex - 1
+```
+
+At `zIndex` 0 or below the popup shares the launcher's layer instead, because
+-1 would put it behind the page's own content. The launcher still paints on
+top.
+
+### Layout vs visual viewport on phones
+
+On a phone the layout viewport can be taller than what the visitor can see
+(browser chrome, in-app browsers, pinch zoom), and `position: fixed` is
+measured against the layout viewport, so a bottom-fixed launcher can sit
+below the fold. Mount `VisualViewportGap` to publish the difference as
+`--sk-vv-layout-gap` on `<html>`. The launcher and popup already read it, and
+your own fixed bottom UI can too:
+
+```tsx
+import { VisualViewportGap } from '@sonordev/site-kit/client'
+
+<SiteKitLayout>
+  <VisualViewportGap />
+  {children}
+</SiteKitLayout>
+```
+
+```css
+.mobile-cta {
+  bottom: calc(24px + env(safe-area-inset-bottom, 0px) + var(--sk-vv-layout-gap, 0px));
+}
+```
+
+It's opt-in: while a field has focus the gap grows to the keyboard's height,
+so everything that reads it rides above the keyboard. `useVisualViewportGap()`
+is the hook form for an existing client component.
+
+## Element Types
+
+| Type | Description |
+|------|-------------|
+| `popup` | Modal overlay with CTA |
+| `nudge` | Small corner notification |
+| `bar` | Top/bottom sticky bar |
+| `slide-in` | Side panel |
+| `chat` | AI/live chat widget |
+
+## Targeting & Triggers
+
+All configured in the Sonor dashboard — no code changes needed:
+
+- **Page targeting** — include/exclude paths with wildcard support
+- **Device targeting** — desktop, mobile, tablet
+- **Visitor targeting** — new vs returning visitors
+- **Triggers** — immediate, delay (seconds), scroll (%), exit-intent, click, custom
+- **Frequency capping** — once, once-per-session, every N days
+
+## Chat Widget
+
+Supports AI mode (Echo), live mode, and hybrid (AI + human handoff):
+
+```ts
+interface ChatConfig {
+  position: 'bottom-right' | 'bottom-left'
+  offsetBottom?: string | number   // See "Launcher placement"
+  zIndex?: number                  // Default: 9999. See "Stacking"
+  mode: 'ai' | 'live' | 'hybrid'
+  buttonColor?: string
+  aiSettings?: {
+    skillId?: string
+    handoffToLive?: boolean
+    handoffKeywords?: string[]
+  }
+  operatingHours?: { ... }
+  offlineMode?: 'form' | 'ai' | 'message'
+  offlineFormSlug?: string
+}
+```
+
+## Tracking
+
+Impressions and clicks are automatically tracked via the Sonor API. Shares visitor ID (`_sk_vid`) with Analytics for cross-module attribution.

package/src/forms/README.md

@@ -0,0 +1,219 @@
+# Forms — `@sonordev/site-kit/forms`
+
+Sonor-managed forms with multi-step support, conditional logic, validation, anti-bot protection, and automatic CRM routing.
+
+## Usage
+
+### Option 1: Managed (simplest)
+
+```tsx
+import { ManagedForm } from '@sonordev/site-kit/forms'
+
+export default function ContactPage() {
+  return <ManagedForm formId="contact-form" />
+}
+```
+
+Fetches form config from Sonor, renders fields, handles submission, routes to CRM.
+
+## Experiences (4.0)
+
+Since 4.0 that one line gets you the **spotlight** experience by default: the
+familiar layout, alive. A glowing ring visits the field you're in, completed
+fields earn a check, and each finished row collapses into a sentence the form
+says back — "Nice to meet you, Jordan." / "We'll follow up at jordan@…" — with
+an edit control to reopen it.
+
+| Experience | What it is | How to get it |
+|---|---|---|
+| `spotlight` | **Default.** Fields perform in place; answered rows become sentences | nothing to do |
+| `stage` | Accordion: one beat at a time on a single surface, answered beats settle into filled rows | `experience="stage"` |
+| `classic` | The plain grid form, no choreography | `experience="classic"` |
+
+```tsx
+<ManagedForm formId="contact-form" />                      // spotlight
+<ManagedForm formId="contact-form" experience="stage" />   // accordion
+<ManagedForm formId="contact-form" experience="classic" /> // opt out
+```
+
+Sonor can decide instead of the site, with no deploy on either side — set the
+form's `layout` to `classic`, `stage`, or `spotlight`. An explicit
+`experience` prop always wins over the config.
+
+Three things hold for every experience:
+
+- **The lead is always capturable.** SSR and no-JS render the plain classic
+  form; the experience layers on after hydration. If its chunk never arrives,
+  the form still works and still submits.
+- **Nobody pays for what they don't use.** Experience code is loaded on
+  demand, so a `classic` form downloads none of it.
+- **Same engine.** Identical validation, honeypot, reCAPTCHA, and CRM routing
+  — an experience is a rendering, not a fork.
+
+### Editing what the form says back
+
+The sentence for a row comes from the kit's built-in wording unless you write
+your own in Sonor: set **`completion_message`** on a field (the first answered
+field in the row that has one wins). Tokens:
+
+| Token | Resolves to |
+|---|---|
+| `{value}` | this field's answer |
+| `{label}` | this field's label |
+| `{first_name}` | the form's first-name answer, if any |
+| `{any_field_slug}` | that field's answer |
+
+```
+Welcome aboard, {first_name}. We'll reach you at {email}.
+```
+
+Leave it empty to keep the built-in sentence. Unknown or unanswered tokens
+render as nothing — never raw braces.
+
+### Option 2: Headless Hook (full UI control)
+
+```tsx
+'use client'
+import { useForm } from '@sonordev/site-kit/forms'
+
+export function ContactForm() {
+  const {
+    fields, values, errors, setFieldValue, submit, isSubmitting,
+    step, totalSteps, isMultiStep, nextStep, prevStep, isLastStep,
+  } = useForm('contact-form')
+
+  return (
+    <form onSubmit={(e) => { e.preventDefault(); submit() }}>
+      {fields.map(field => (
+        <div key={field.slug}>
+          <label>{field.label}</label>
+          <input
+            value={String(values[field.slug] || '')}
+            onChange={(e) => setFieldValue(field.slug, e.target.value)}
+          />
+          {errors[field.slug] && <span className="error">{errors[field.slug]}</span>}
+        </div>
+      ))}
+      {isMultiStep && !isLastStep && <button type="button" onClick={nextStep}>Next</button>}
+      {isLastStep && <button type="submit" disabled={isSubmitting}>Submit</button>}
+    </form>
+  )
+}
+```
+
+### Option 3: Render Prop
+
+```tsx
+<ManagedForm formId="contact-form">
+  {({ fields, values, setFieldValue, submit }) => (
+    <MyCustomFormUI fields={fields} values={values} onChange={setFieldValue} onSubmit={submit} />
+  )}
+</ManagedForm>
+```
+
+### Option 4: Programmatic API
+
+```ts
+import { formsApi, field, configureFormsApi } from '@sonordev/site-kit/forms'
+
+configureFormsApi({ baseUrl: 'https://api.sonor.io', apiKey: 'sonor_...' })
+
+const form = await formsApi.create({
+  projectId: 'xxx',
+  slug: 'newsletter',
+  name: 'Newsletter Signup',
+  formType: 'newsletter',
+  fields: [
+    field.email('email', 'Email', { isRequired: true }),
+    field.text('name', 'Name'),
+  ],
+})
+```
+
+## ManagedForm Props
+
+```ts
+interface ManagedFormProps {
+  formId: string                              // Form slug or ID
+  className?: string
+  onSuccess?: (submission: FormSubmitResult) => void
+  onError?: (error: Error) => void
+  children?: (renderProps: UseFormReturn) => ReactNode  // Render prop override
+}
+```
+
+## useForm Return
+
+```ts
+interface UseFormReturn {
+  form: ManagedFormConfig | null
+  isLoading: boolean
+  fetchError: Error | null
+  allFields: FormField[]
+  fields: FormField[]               // Current step's fields
+  visibleFields: FormField[]         // After conditional logic
+  values: Record<string, unknown>
+  errors: Record<string, string>
+  setFieldValue: (key: string, value: unknown) => void
+  step: number
+  totalSteps: number
+  isMultiStep: boolean
+  progress: number                   // 0-100
+  nextStep: () => void
+  prevStep: () => void
+  goToStep: (n: number) => void
+  canGoNext: boolean
+  canGoPrev: boolean
+  isLastStep: boolean
+  validate: () => boolean
+  submit: () => Promise<void>
+  isSubmitting: boolean
+  isComplete: boolean
+  reset: () => void
+}
+```
+
+## Field Types
+
+`text`, `email`, `phone`, `tel`, `number`, `textarea`, `select`, `multi-select`, `checkbox`, `radio`, `date`, `time`, `datetime`, `file`, `signature`, `rating`, `slider`, `hidden`, `heading`, `section_header`, `paragraph`
+
+## Field Builder
+
+```ts
+field.text(slug, label, options?)
+field.email(slug, label, options?)
+field.phone(slug, label, options?)
+field.textarea(slug, label, options?)
+field.select(slug, label, { options: [{ value, label }] })
+field.date(slug, label, options?)
+field.checkbox(slug, label, options?)
+field.rating(slug, label, options?)
+```
+
+## Form Routing
+
+Submissions auto-route based on `form_type`:
+
+| Form Type | Routes To | Use Case |
+|-----------|-----------|----------|
+| `prospect` / `lead-capture` / `contact` | CRM Contacts | Sales inquiries, quotes |
+| `support` | Support Tickets | Help requests |
+| `feedback` | Feedback entries | User feedback |
+| `newsletter` | Email Subscribers | Newsletter signups |
+| `custom` | Form Submissions only | Custom handling |
+
+## Anti-Bot Protection
+
+- **Honeypot fields** — hidden fields that bots fill (server-side rejection)
+- **reCAPTCHA Enterprise** — optional Google reCAPTCHA v3 scoring
+- **Submission timing** — forms that submit in < 3 seconds are flagged
+- **Composite spam scoring** — name patterns, email domain, user-agent, IP rate, message content
+- **NestJS ThrottlerGuard** — 10 requests/minute per IP at HTTP level
+
+## Styles
+
+```tsx
+import '@sonordev/site-kit/forms/styles.css'  // Optional default styles
+```
+
+All components use `.sk-form__*` class names. Override with `className` prop or CSS variables.

package/src/images/README.md

@@ -0,0 +1,74 @@
+# Images — `@sonordev/site-kit/images`
+
+Sonor-managed image slots with dev-mode editing, focal point support, and image picker.
+
+## Usage
+
+```tsx
+import { ManagedImage } from '@sonordev/site-kit/images'
+
+export default function HeroSection() {
+  return (
+    <ManagedImage
+      slotId="hero-background"
+      alt="Hero background"
+      width={1920}
+      height={1080}
+      objectFit="cover"
+      fallback="/images/default-hero.jpg"
+    />
+  )
+}
+```
+
+## Props
+
+```ts
+interface ManagedImageProps {
+  slotId: string                     // Unique slot identifier (e.g., 'hero-background')
+  pagePath?: string                  // Page-specific slots (defaults to current path)
+  alt?: string                       // Fallback alt text
+  className?: string
+  width?: number | string
+  height?: number | string
+  objectFit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down'
+  fallback?: string                  // Fallback image URL when slot is empty
+  placeholder?: React.ReactNode     // Custom placeholder component
+  onLoad?: () => void
+  onError?: (error: Error) => void
+  priority?: boolean                 // Eager loading (Next.js Image priority)
+  style?: React.CSSProperties
+  forceDevMode?: boolean             // Enable dev picker outside localhost
+}
+```
+
+## Dev Mode
+
+Dev mode is on when `NODE_ENV` is `development`, on `localhost` / `127.0.0.1`, on any host with `?sonor_dev=true` in the URL, or with `forceDevMode`:
+- Click any `ManagedImage` to open the image picker modal
+- Browse files by folder, search, upload new images
+- Set alt text and focal point
+- Shows slot ID in empty states for debugging
+
+## Focal Point
+
+When an image has `focal_point_x` / `focal_point_y` set in Sonor, the component auto-calculates `object-position` so the focal area stays visible during cropping.
+
+## API Functions
+
+```ts
+import { fetchManagedImage, uploadImage, assignImageToSlot } from '@sonordev/site-kit/images'
+
+const image = await fetchManagedImage(slotId, pagePath)
+const uploaded = await uploadImage(file, { folder: 'heroes', category: 'background' })
+await assignImageToSlot(slotId, uploaded.id, pagePath)
+```
+
+## Favicon
+
+```tsx
+import { ManagedFavicon } from '@sonordev/site-kit/images'
+
+// In layout <head>:
+<ManagedFavicon />  // Fetches Sonor logo as favicon link tags
+```

package/src/layout/README.md

@@ -0,0 +1,66 @@
+# Layout — `@sonordev/site-kit/layout`
+
+RSC-compatible master layout that auto-composes all site-kit features.
+
+## Usage
+
+```tsx
+// app/layout.tsx
+import { SiteKitLayout } from '@sonordev/site-kit/layout'
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <SiteKitLayout>{children}</SiteKitLayout>
+      </body>
+    </html>
+  )
+}
+```
+
+Zero-config: reads `SONOR_API_KEY` from env, injects it into client modules automatically.
+
+## Props
+
+```ts
+interface SiteKitLayoutProps {
+  children: React.ReactNode
+  apiKey?: string                         // Defaults to SONOR_API_KEY env var
+  apiUrl?: string                         // Defaults to SONOR_API_URL, then https://api.sonor.io
+  projectId?: string                      // For Engage chat routing (auto-resolved if omitted)
+  analytics?: boolean | AnalyticsConfig   // Default: true
+  engage?: boolean | EngageConfig         // Default: true
+  signal?: boolean | SignalConfig         // Default: false
+  sitemapSync?: boolean                   // Default: false (build-time + server reconciler own this)
+  fleet?: boolean                         // Default: true (once-per-session kit version heartbeat)
+  defer?: boolean                         // Default: true (client modules wait for load + idle)
+  favicon?: boolean                       // Default: true
+  managedScripts?: boolean                // Default: true
+  debug?: boolean                         // Default: false
+  showLlmsTxtFooterLink?: boolean         // Default: false (prefer middleware discovery headers)
+  speculation?: boolean | { mode?: 'prerender' | 'prefetch'; exclude?: string[] } // Default: false
+}
+```
+
+Module options live with each module: [Analytics](../analytics/README.md) (`trackPageViews`, `excludePaths`, `site`, `allowInFrame`, `allowLocalhost`) and [Engage](../engage/README.md) (`position`, `chatEnabled`, and launcher placement).
+
+## What It Composes
+
+**Server-side (RSC):**
+- `ManagedFavicon` — Sonor logo as `<link>` tags
+- `ManagedScripts` — tracking pixels/analytics tags in `<head>` and body-end positions
+- API preconnect/dns-prefetch hints
+
+**Client-side (lazy-loaded island):**
+- `AnalyticsProvider` — page views, scroll depth, heatmap clicks, Web Vitals
+- `EngageWidget` — popups, nudges, chat
+- `SignalBridge` — A/B experiments, behavior tracking (opt-in)
+- `SitemapSync` — parses `/sitemap.xml` and syncs to Sonor (opt-in)
+- `FleetHeartbeat` — reports the kit version and enabled modules once per session
+
+Since 4.0.0 none of these wrap your page. `{children}` renders first and every module mounts after it as a childless sibling, so `SiteKitLayout` never pushes a route to client rendering. Analytics, Engage, SitemapSync and the heartbeat also wait for window load + idle (or the first interaction) unless you pass `defer={false}`. `SignalBridge` isn't deferred, so experiment variants apply early. Visitor and session IDs come from a shared storage singleton rather than a provider.
+
+## Note
+
+`SiteKitProvider` was **removed in 4.0.0**. It wrapped the whole tree client-side, which broke RSC. Migrate an older layout with `npx sonor-setup codemod --only provider-to-layout --write`.