@unitninety/site-kit 0.0.0-stage → 1.6.2

package/src/features/client/AskAiWidget.tsx

@@ -0,0 +1,222 @@
+'use client'
+import { useEffect, useRef, useState, type CSSProperties } from 'react'
+import { FeatureDialog } from './overlay'
+import { useAskAI, type AskAiController } from './useAskAI'
+/** Reusable accessible content; remixes may replace this entire presentation with the same hook. */
+export function AskAiContent({
+  controller: c,
+}: {
+  controller: Omit<AskAiController, 'launcherRef'>
+}) {
+  const log = useRef<HTMLDivElement>(null)
+  useEffect(() => {
+    if (log.current) log.current.scrollTop = log.current.scrollHeight
+  }, [c.messages, c.status])
+  const busy = c.status === 'sending' || c.status === 'streaming' || c.recovering
+  return (
+    <>
+      <div
+        className="u90-ai-log"
+        role="log"
+        aria-label="Conversation"
+        aria-live="polite"
+        aria-relevant="additions text"
+        ref={log}
+      >
+        {!c.messages.length && <p>{c.settings.greeting}</p>}
+        {c.messages.map((m) => (
+          <article key={m.id} className={'u90-ai-message u90-ai-' + m.role}>
+            <p className="u90-ai-role">
+              {m.role === 'user' ? 'You' : 'Assistant'}
+              {m.newAttempt ? ' · New attempt' : ''}
+            </p>
+            <p className="u90-ai-text">
+              {m.text ||
+                (m.state === 'queued'
+                  ? c.awaitingAnswer
+                    ? 'Saved answer is still pending.'
+                    : 'Sending… Keep this page open until the answer starts; refreshing now may prevent recovery.'
+                  : m.state === 'streaming'
+                    ? 'Preparing answer…'
+                    : 'No answer received.')}
+            </p>
+            {m.role === 'assistant' && (
+              <>
+                {m.sources.length > 0 && (
+                  <ul aria-label="Sources">
+                    {m.sources.map((s) => (
+                      <li key={JSON.stringify([s.kind, s.id])}>
+                        {s.path === null ? <span>{s.title}</span> : <a href={s.path}>{s.title}</a>}
+                      </li>
+                    ))}
+                  </ul>
+                )}
+                {['failed', 'aborted', 'unknown'].includes(m.state) && (
+                  <p className="u90-ai-state">
+                    {m.state === 'unknown'
+                      ? 'Unconfirmed answer — may be incomplete.'
+                      : 'Incomplete answer.'}
+                  </p>
+                )}
+                {!['queued', 'streaming'].includes(m.state) && (
+                  <div className="u90-ai-ratings" aria-label="Rate answer">
+                    {(['helpful', 'unhelpful'] as const).map((r) => (
+                      <button
+                        type="button"
+                        key={r}
+                        aria-pressed={c.ratings[m.id] === r}
+                        onClick={() => void c.rate(m.id, r)}
+                      >
+                        {r === 'helpful' ? 'Helpful' : 'Unhelpful'}
+                      </button>
+                    ))}
+                  </div>
+                )}
+              </>
+            )}
+          </article>
+        ))}
+      </div>
+      {!c.messages.length && c.settings.suggestions.length > 0 && (
+        <div className="u90-ai-suggestions">
+          {c.settings.suggestions.map((s) => (
+            <button type="button" key={s} onClick={() => c.setDraft(s)}>
+              {s}
+            </button>
+          ))}
+        </div>
+      )}
+      {c.hasEarlier && (
+        <p>
+          Some history has not been loaded.{' '}
+          <button type="button" disabled={busy} onClick={() => void c.loadEarlier()}>
+            Load earlier messages
+          </button>
+        </p>
+      )}
+      {c.error && (
+        <div role="alert" className="u90-ai-error">
+          <p>{c.error}</p>
+          {c.canRetry && (
+            <button type="button" onClick={() => void c.retry()}>
+              Retry same request
+            </button>
+          )}
+          {c.canNewAttempt && (
+            <button type="button" onClick={() => void c.retryAnswer()}>
+              Try a new answer
+            </button>
+          )}
+        </div>
+      )}
+      {c.canRecover && (
+        <button type="button" disabled={busy} onClick={() => void c.recover()}>
+          Check saved answer
+        </button>
+      )}
+      {c.ratingError && (
+        <p role="alert" className="u90-ai-error">
+          {c.ratingError}
+        </p>
+      )}
+      <p role="status" className="u90-ai-progress">
+        {c.recovering
+          ? 'Loading saved conversation…'
+          : c.awaitingAnswer
+            ? 'Saved answer is still pending. Check the saved answer to refresh it.'
+            : c.status === 'sending'
+              ? 'Sending… Keep this page open until the answer starts; refreshing now may prevent recovery.'
+              : c.status === 'streaming'
+                ? 'Answering…'
+                : ''}
+      </p>
+      <form
+        className="u90-ai-composer"
+        onSubmit={(e) => {
+          e.preventDefault()
+          void c.send(c.draft)
+        }}
+      >
+        <label>
+          Message
+          <textarea
+            rows={2}
+            maxLength={2000}
+            value={c.draft}
+            onChange={(e) => c.setDraft(e.target.value)}
+          />
+        </label>
+        <div>
+          <button
+            className="u90-ai-send"
+            type="submit"
+            disabled={busy || c.awaitingAnswer || !c.draft.trim() || c.canRetry || c.canNewAttempt}
+          >
+            Send
+          </button>
+          {busy && (
+            <button type="button" onClick={c.stop}>
+              Stop
+            </button>
+          )}
+          <button type="button" onClick={c.startNewConversation}>
+            New conversation
+          </button>
+        </div>
+      </form>
+    </>
+  )
+}
+export function askAiForeground(hex: string) {
+  const channels = [1, 3, 5]
+    .map((i) => parseInt(hex.slice(i, i + 2), 16) / 255)
+    .map((v) => (v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4))
+  const light = 0.2126 * channels[0] + 0.7152 * channels[1] + 0.0722 * channels[2]
+  return (light + 0.05) / 0.05 >= 1.05 / (light + 0.05) ? '#000000' : '#ffffff'
+}
+export default function AskAiWidget() {
+  const { launcherRef, ...c } = useAskAI(),
+    [viewport, setViewport] = useState({ height: 0, top: 0 })
+  useEffect(() => {
+    const vv = window.visualViewport
+    const measure = () =>
+      setViewport({ height: vv?.height ?? window.innerHeight, top: vv?.offsetTop ?? 0 })
+    measure()
+    vv?.addEventListener('resize', measure)
+    vv?.addEventListener('scroll', measure)
+    window.addEventListener('resize', measure)
+    return () => {
+      vv?.removeEventListener('resize', measure)
+      vv?.removeEventListener('scroll', measure)
+      window.removeEventListener('resize', measure)
+    }
+  }, [])
+  return (
+    <div
+      className="u90-ai"
+      style={
+        {
+          '--u90-ai-accent': c.settings.accentColor,
+          '--u90-ai-on-accent': askAiForeground(c.settings.accentColor),
+          '--u90-ai-radius': c.settings.cornerStyle === 'square' ? '0' : '1rem',
+          '--u90-ai-height': viewport.height ? viewport.height + 'px' : '100dvh',
+          '--u90-ai-top': viewport.top + 'px',
+        } as CSSProperties
+      }
+    >
+      <button
+        type="button"
+        className="u90-ai-launcher"
+        ref={launcherRef}
+        onClick={c.show}
+        aria-expanded={c.open}
+      >
+        {c.settings.launcherLabel}
+      </button>
+      <FeatureDialog name="askAi" label={c.settings.title} className="u90-ai-panel">
+        <h2>{c.settings.title}</h2>
+        <AskAiContent controller={c} />
+      </FeatureDialog>
+    </div>
+  )
+}

package/src/features/client/ConsentRuntime.tsx

@@ -0,0 +1,95 @@
+'use client'
+import {
+  Suspense,
+  useCallback,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react'
+import type { PublicFeatureBase } from '../contracts'
+import { deniedConsentState } from '../contracts/consent'
+import type { CustomConsentRegistration } from '../consent/custom'
+import { consentRegistry } from '../consent/registry'
+import { ConsentContext } from './useConsent'
+import { PageReporter } from './PageReporter'
+const ignoreTitle = () => {}
+/** Commit-only ownership: rendering never installs listeners, scripts, or authority. */
+export function ConsentRuntime({
+  endpoint,
+  config,
+  customConsent,
+  children,
+}: {
+  endpoint: string
+  config: PublicFeatureBase | null
+  customConsent?: CustomConsentRegistration
+  children: ReactNode
+}) {
+  const owner = useRef({})
+  const registry = useRef<ReturnType<typeof consentRegistry> | null>(null)
+  const [snapshot, setSnapshot] = useState(() => ({
+    state: deniedConsentState(),
+    ready: false,
+    error: null as string | null,
+    reloadRequired: false,
+  }))
+  useLayoutEffect(() => {
+    const current = consentRegistry(window)
+    registry.current = current
+    const off = current.subscribe(() => setSnapshot(current.read()))
+    const currentOwner = owner.current
+    current.attach(currentOwner)
+    return () => {
+      off()
+      current.detach(currentOwner)
+      registry.current = null
+    }
+  }, [])
+  useLayoutEffect(() => {
+    registry.current!.commit(
+      owner.current,
+      endpoint,
+      config?.enabled.consent ?? false,
+      config?.consent,
+      customConsent,
+    )
+    setSnapshot(registry.current!.read())
+  }, [endpoint, config, customConsent, customConsent?.adapter, customConsent?.openPreferences])
+  const openPreferences = useCallback(() => registry.current?.openPreferences(), [])
+  const page = useCallback((path: string) => registry.current?.page(path), [])
+  const value = useMemo(
+    () => ({
+      state: snapshot.state,
+      ready: snapshot.ready,
+      error: snapshot.error,
+      openPreferences,
+    }),
+    [snapshot, openPreferences],
+  )
+  return (
+    <ConsentContext.Provider value={value}>
+      {children}
+      <Suspense fallback={null}>
+        <PageReporter report={page} titleChanged={ignoreTitle} />
+      </Suspense>
+      {snapshot.error && (
+        <div className="u90-features u90-consent-status">
+          <p role="status" aria-live="polite">
+            {snapshot.error}
+          </p>
+          {snapshot.reloadRequired ? (
+            <button type="button" data-u90-consent-reload onClick={() => window.location.reload()}>
+              Reload to apply consent changes
+            </button>
+          ) : (
+            <button type="button" onClick={() => registry.current?.retry()}>
+              Retry consent setup
+            </button>
+          )}
+        </div>
+      )}
+    </ConsentContext.Provider>
+  )
+}

package/src/features/client/FeedbackProvider.tsx

@@ -0,0 +1,231 @@
+'use client'
+import {
+  Suspense,
+  useCallback,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentType,
+  type ReactNode,
+} from 'react'
+import {
+  FeedbackInputSchema,
+  FeedbackWidgetSettingsSchema,
+  type FeedbackInput,
+  type PageContext,
+} from '../contracts'
+import { useSiteFeatures } from './context'
+import { FeedbackContext, type FeedbackAnswer, type FeedbackController } from './useFeedback'
+import { PageReporter } from './PageReporter'
+
+type Status = FeedbackController['status']
+const defaults = FeedbackWidgetSettingsSchema.parse({})
+const uncertain =
+  'We could not confirm your feedback. Retry the same feedback, or start new feedback.'
+/** Independent of presentation remounts, but owned by the endpoint-keyed root. */
+export function FeedbackProvider({
+  children,
+  presentation: Presentation,
+}: {
+  children: ReactNode
+  presentation?: ComponentType
+}) {
+  const runtime = useSiteFeatures()
+  const [currentPage, setPage] = useState<Readonly<PageContext> | null>(null)
+  const [capturedPage, setCapturedPage] = useState<Readonly<PageContext> | null>(null)
+  const [epoch, setEpoch] = useState(0)
+  const [status, setStatus] = useState<Status>('idle')
+  const [error, setError] = useState<string | null>(null)
+  const attempt = useRef<FeedbackInput | null>(null)
+  const state = useRef<Status>('idle')
+  const pending = useRef<Promise<void> | null>(null)
+  const operation = useRef<AbortController | null>(null)
+  const alive = useRef(false)
+  const titleReady = useRef(false)
+  const committed = useRef({
+    enabled: false,
+    page: null as Readonly<PageContext> | null,
+    settings: defaults,
+    send: runtime.submitFeedback,
+  })
+  const transition = useCallback((next: Status, message: string | null = null) => {
+    state.current = next
+    setStatus(next)
+    setError(message)
+  }, [])
+  useLayoutEffect(() => {
+    alive.current = true
+    return () => {
+      alive.current = false
+      operation.current?.abort()
+    }
+  }, [])
+  useLayoutEffect(() => {
+    const enabled = Boolean(runtime.config?.enabled.feedback)
+    const wasEnabled = committed.current.enabled
+    committed.current = {
+      ...committed.current,
+      enabled,
+      settings: runtime.config?.feedback ?? defaults,
+      send: runtime.submitFeedback,
+    }
+    if (wasEnabled && !enabled) {
+      operation.current?.abort()
+      operation.current = null
+      pending.current = null
+      setEpoch((value) => value + 1)
+      if (state.current === 'submitting') transition('error', uncertain)
+      else if (!attempt.current) transition('idle')
+    }
+  }, [runtime.config, runtime.submitFeedback, transition])
+  const report = useCallback(
+    (path: string) => {
+      if (committed.current.page?.path === path) return
+      titleReady.current = committed.current.page === null
+      const page = Object.freeze({ path })
+      committed.current = { ...committed.current, page }
+      setPage(page)
+      setEpoch((value) => value + 1)
+      if (!attempt.current || state.current === 'success') {
+        attempt.current = null
+        setCapturedPage(null)
+        transition('idle')
+      }
+    },
+    [transition],
+  )
+  const titleChanged = useCallback(() => {
+    if (committed.current.page?.path === window.location.pathname) titleReady.current = true
+  }, [])
+  const run = useCallback((): Promise<void> => {
+    if (pending.current) return pending.current
+    if (
+      !alive.current ||
+      !committed.current.enabled ||
+      !attempt.current ||
+      state.current === 'success'
+    )
+      return Promise.resolve()
+    const captured = attempt.current
+    const controller = new AbortController()
+    operation.current = controller
+    transition('submitting')
+    const signal = AbortSignal.any([controller.signal, AbortSignal.timeout(120000)])
+    const current = () =>
+      alive.current &&
+      committed.current.enabled &&
+      operation.current === controller &&
+      attempt.current === captured &&
+      !signal.aborted
+    // The pending slot is claimed synchronously, before either consumer can submit again.
+    const promise = Promise.resolve()
+      .then(async () => {
+        signal.throwIfAborted()
+        await committed.current.send(captured, signal)
+        if (current()) transition('success')
+      })
+      .catch(() => {
+        if (
+          alive.current &&
+          committed.current.enabled &&
+          operation.current === controller &&
+          attempt.current === captured
+        )
+          transition('error', uncertain)
+      })
+      .finally(() => {
+        if (operation.current === controller) {
+          operation.current = null
+          pending.current = null
+        }
+      })
+    pending.current = promise
+    return promise
+  }, [transition])
+  const submit = useCallback(
+    (answer: FeedbackAnswer): Promise<void> => {
+      if (pending.current) return pending.current
+      if (attempt.current) return run() // Retried answers and source are immutable.
+      const { enabled, page, settings } = committed.current
+      if (!alive.current || !enabled) return Promise.resolve()
+      if (!page || page.path !== window.location.pathname) {
+        setError('The page is changing. Please try again once it is ready.')
+        return Promise.resolve()
+      }
+      const comment = settings.showComment ? answer.comment?.trim() : undefined
+      // Validate before allocating an intentional request identity.
+      const parsed = FeedbackInputSchema.safeParse({
+        requestId: '00000000-0000-4000-8000-000000000000',
+        page: {
+          path: page.path,
+          ...(titleReady.current && document.title ? { title: document.title.slice(0, 200) } : {}),
+        },
+        ...(settings.showRating && answer.rating !== undefined ? { rating: answer.rating } : {}),
+        ...(comment ? { comment } : {}),
+      })
+      if (!parsed.success) {
+        setError('Choose a rating or enter a comment of up to 2,000 characters.')
+        return Promise.resolve()
+      }
+      attempt.current = Object.freeze({
+        ...parsed.data,
+        page: Object.freeze(parsed.data.page),
+        requestId: crypto.randomUUID(),
+      })
+      setCapturedPage(attempt.current.page)
+      return run()
+    },
+    [run],
+  )
+  const startNew = useCallback(() => {
+    if (state.current === 'submitting') return
+    attempt.current = null
+    setCapturedPage(null)
+    transition('idle')
+    setEpoch((value) => value + 1)
+  }, [transition])
+  const { open, close } = runtime.overlay
+  const show = useCallback(() => open('feedback'), [open])
+  const value = useMemo(
+    () => ({
+      open: runtime.overlay.active === 'feedback',
+      status,
+      error,
+      currentPage,
+      page: capturedPage ?? currentPage,
+      show,
+      hide: close,
+      submit,
+      retry: run,
+      startNew,
+    }),
+    [
+      runtime.overlay.active,
+      status,
+      error,
+      currentPage,
+      capturedPage,
+      show,
+      close,
+      submit,
+      run,
+      startNew,
+    ],
+  )
+  return (
+    <FeedbackContext.Provider value={value}>
+      <Suspense fallback={null}>
+        <PageReporter report={report} titleChanged={titleChanged} />
+      </Suspense>
+      {children}
+      {runtime.config?.enabled.feedback && Presentation && (
+        <Suspense fallback={null}>
+          <div className="u90-features">
+            <Presentation key={epoch} />
+          </div>
+        </Suspense>
+      )}
+    </FeedbackContext.Provider>
+  )
+}

package/src/features/client/FeedbackWidget.tsx

@@ -0,0 +1,101 @@
+'use client'
+import { useId, useState } from 'react'
+import { FeedbackWidgetSettingsSchema } from '../contracts'
+import { useSiteFeatures } from './context'
+import { useFeedback, type FeedbackAnswer } from './useFeedback'
+import { FeatureDialog } from './overlay'
+const defaults = FeedbackWidgetSettingsSchema.parse({})
+export default function FeedbackWidget() {
+  const { launcherRef, ...feedback } = useFeedback()
+  const settings = useSiteFeatures().config?.feedback ?? defaults
+  const [rating, setRating] = useState<FeedbackAnswer['rating']>()
+  const [comment, setComment] = useState('')
+  const id = useId()
+  return (
+    <>
+      <button
+        className="u90-feedback-launcher"
+        ref={launcherRef}
+        type="button"
+        aria-expanded={feedback.open}
+        onClick={feedback.show}
+      >
+        {settings.launcherLabel}
+      </button>
+      <FeatureDialog name="feedback" label={settings.title} className="u90-feedback-panel">
+        <h2>{settings.title}</h2>
+        <p className="u90-feedback-page">Feedback for {feedback.page?.path ?? 'this page'}</p>
+        {feedback.page?.path !== feedback.currentPage?.path && (
+          <p>
+            You are now on {feedback.currentPage?.path}. This feedback still belongs to{' '}
+            {feedback.page?.path}.
+          </p>
+        )}
+        {feedback.status === 'idle' && (
+          <form
+            onSubmit={(event) => {
+              event.preventDefault()
+              void feedback.submit({ rating, comment })
+            }}
+          >
+            {settings.showRating && (
+              <fieldset>
+                <legend>{settings.ratingLabel}</legend>
+                <div className="u90-feedback-ratings">
+                  {([1, 2, 3, 4, 5] as const).map((value) => (
+                    <label key={value}>
+                      <input
+                        type="radio"
+                        name={id}
+                        aria-label={`${value} out of 5`}
+                        checked={rating === value}
+                        onChange={() => setRating(value)}
+                      />
+                      <span>{value}</span>
+                    </label>
+                  ))}
+                </div>
+              </fieldset>
+            )}
+            {settings.showComment && (
+              <label className="u90-feedback-comment">
+                {settings.commentLabel}
+                <textarea
+                  value={comment}
+                  onChange={(event) => setComment(event.target.value)}
+                  maxLength={2000}
+                  rows={4}
+                  placeholder={settings.commentPlaceholder}
+                />
+              </label>
+            )}
+            {feedback.error && <p role="alert">{feedback.error}</p>}
+            <button className="u90-feedback-submit" type="submit">
+              {settings.submitLabel}
+            </button>
+          </form>
+        )}
+        {feedback.status === 'submitting' && <p role="status">Sending feedback…</p>}
+        {feedback.status === 'error' && (
+          <>
+            <p role="alert">{feedback.error}</p>
+            <button type="button" onClick={() => void feedback.retry()}>
+              Retry feedback
+            </button>
+            <button type="button" onClick={feedback.startNew}>
+              Start new feedback
+            </button>
+          </>
+        )}
+        {feedback.status === 'success' && (
+          <>
+            <p role="status">{settings.successMessage}</p>
+            <button type="button" onClick={feedback.startNew}>
+              Start new feedback
+            </button>
+          </>
+        )}
+      </FeatureDialog>
+    </>
+  )
+}

package/src/features/client/PageReporter.tsx

@@ -0,0 +1,26 @@
+'use client'
+import { useLayoutEffect } from 'react'
+import { usePathname } from 'next/navigation'
+/** Isolated Suspense leaf: only committed navigation advances the presentation lifetime. */
+export function PageReporter({
+  report,
+  titleChanged,
+}: {
+  report: (path: string) => void
+  titleChanged: () => void
+}) {
+  const pathname = usePathname()
+  useLayoutEffect(() => {
+    report(window.location.pathname)
+    let title = document.title
+    const observer = new MutationObserver(() => {
+      if (document.title !== title) {
+        title = document.title
+        titleChanged()
+      }
+    })
+    observer.observe(document.head, { subtree: true, childList: true, characterData: true })
+    return () => observer.disconnect()
+  }, [pathname, report, titleChanged])
+  return null
+}