@unitninety/site-kit 0.0.0-stage → 1.6.2

package/src/features/client/README.md

@@ -0,0 +1,131 @@
+# Shared website features in Next
+
+The `@unitninety/site-kit/features` entry point targets Next 16.3.8–16.x and React 19.
+It uses Next's committed pathname updates; wrap `SiteFeatures` around the root layout's
+children from the first render, mount the server `ConsentDefaults` once before it, and import `@unitninety/site-kit/features/styles.css`. The internal pathname
+reporter has its own Suspense boundary. Pure `features/contracts` has no Next dependency.
+No non-Next runtime support is claimed. The package's Next peer is optional for consumers
+using only contracts or server APIs, but required for the feature client entry point.
+
+With the same-origin gateway installed, enabling Feedback in U90 renders the complete
+stock widget. No form declaration or site-specific payload mapping is required. Override
+`components.Feedback` with a stable React component to supply complete custom markup.
+Both presentations consume normalized `config.feedback` options (fallback:
+`FeedbackWidgetSettingsSchema.parse({})`), including labels and question visibility.
+The default comment label is **Tell us more**.
+
+```tsx
+import { FeatureDialog, useFeedback } from '@unitninety/site-kit/features'
+function MyFeedback() {
+  const { launcherRef, ...feedback } = useFeedback()
+  // Local answer fields belong inside this registered component.
+  return (
+    <>
+      <button ref={launcherRef} onClick={feedback.show}>
+        Feedback
+      </button>
+      <FeatureDialog name="feedback" label="Feedback">
+        <p>Feedback for {feedback.page?.path}</p>
+        {/* Render composition when idle; explicit retry/new actions on error. */}
+      </FeatureDialog>
+    </>
+  )
+}
+```
+
+`useFeedback(): FeedbackController` returns `open`, `status` (`idle | submitting |
+success | error`), safe `error`, `page` and `currentPage` (`Readonly<PageContext> | null`),
+`show()`, `hide()`, `submit({ rating?: 1|2|3|4|5, comment?: string }): Promise<void>`,
+`retry(): Promise<void>`, `startNew(): void`, and `launcherRef: RefCallback<HTMLButtonElement>`.
+Attach the ref to the presentation's single actual launcher. It restores focus to the
+current launcher if navigation replaced the original one. Switching panels preserves
+the original overlay's focus identity.
+
+The root owns submission state; every hook consumer joins the same pending attempt.
+Each valid intentional send receives one request ID and captures normalized answers,
+pathname and an optional bounded title. Invalid/blank answers require no session or proof.
+An uncertain result retains that exact attempt. `retry()` resends the same ID/page/answers;
+`submit()` in that state is also a retry and **ignores changed arguments**. Never label a
+new action “Retry”. `startNew()` explicitly abandons the old attempt and clears local draft;
+it is inert while a request is pending. Successful sends remain inert until startNew or
+pathname navigation. A browser abort cannot roll back a write that reached the server.
+
+Committed pathname changes remount **only** the registered Feedback presentation, clearing
+ordinary React draft state. Root children, Ask AI, coalesced session/proof and pending or
+uncertain Feedback snapshots survive. Show the captured `page` while pending/retrying;
+`currentPage` may differ after navigation. Query/hash/title-only changes do not clear drafts.
+Do not keep draft state in module singletons, sessionStorage or above the registered
+component: the boundary cannot reset external state. Hiding a panel does not cancel sending.
+Disabling Feedback clears unsent draft and cancels only its operation; re-enabling never
+automatically sends. Endpoint replacement/unmount discards that authority's state.
+
+Feedback uses the configured runtime endpoint and canonical `FeedbackInput`. Each new logical
+submission obtains a signed action grant, then sends the body with that grant. Public
+verification configuration is refreshed before proof acquisition. Saved Disabled mode returns
+`null` and skips provider scripts, widgets and injected browser adapters; the platform still
+checks its saved mode and issues the same signed authority. Default and custom providers fail
+closed on missing setup or failed checks. Proof, grants, tenant details and credentials never
+belong in answer fields.
+
+Interactive proof acquisition has a 120-second deadline; each HTTP exchange is bounded to ten
+seconds. Cancellation cannot cancel another feature's shared session wait. Known response
+fields are validated and response bodies are bounded before success. Hidden questions are
+omitted at first capture; later settings changes cannot alter a retry.
+
+The scoped theme variables are `--u90-feature-background`, `--u90-feature-foreground`,
+`--u90-feature-accent`, `--u90-feature-radius`, and `--u90-feature-shadow`.
+
+See [consent setup](../consent/README.md) for the server root bootstrap, optional custom registration, remote authority, lifecycle limits and preferences hook. Consent does not reset the Feedback presentation, session or focus lifetime.
+
+## Ask AI stock setup and remix
+
+Use the same root `SiteFeatures`, same-origin gateway, verification adapter and stylesheet
+setup above. Ask AI starts disabled. In U90, a manager connects a tenant-owned provider
+key, explicitly chooses an available model and allowances, selects eligible published
+knowledge (published FAQs can stand alone), and publishes the generation configuration.
+Enable Ask AI in feature settings to show the complete stock widget. Provider keys stay
+server-only; the browser never supplies a key, model or private prompt. See the
+[management contract](../../../../../docs/superpowers/specs/2026-10-05-ask-ai-management.md)
+for permissions, configuration and activation boundaries.
+
+For custom markup, register a stable component through `components.AskAI` in your existing
+client root wrapper. This example keeps the shared accessible conversation content:
+
+```tsx
+'use client'
+import type { SiteFeaturesProps } from '@unitninety/site-kit/features'
+import { AskAiContent, FeatureDialog, SiteFeatures, useAskAI } from '@unitninety/site-kit/features'
+
+function MyAskAI() {
+  const ai = useAskAI()
+  return (
+    <>
+      <button ref={ai.launcherRef} onClick={ai.show}>
+        {ai.settings.launcherLabel}
+      </button>
+      <FeatureDialog name="askAi" label={ai.settings.title}>
+        <AskAiContent controller={ai} />
+      </FeatureDialog>
+    </>
+  )
+}
+
+export function Features(props: SiteFeaturesProps) {
+  return <SiteFeatures {...props} components={{ ...props.components, AskAI: MyAskAI }} />
+}
+```
+
+Keep this root mounted across page navigation: it owns conversation, draft, session and
+pending-request state even when the presentation closes or remounts. Endpoint replacement
+or root unmount discards that authority's state. `useAskAI()` supports a complete remix;
+`AskAiContent` is optional. Honor remote copy/settings and deliberately document any brand
+colours or corners that your remix overrides; the stock widget honors saved appearance.
+
+For an uncertain send, `retry()` reuses the canonical request ID and captured body.
+`retryAnswer()` after a confirmed terminal failure is an explicit **new attempt** with a
+new ID and may incur a new charge; never label it as a same-request retry. Recovery uses
+GET and never generates an answer. Session storage persists only a known conversation ID,
+scoped by endpoint: no transcript, draft, request IDs, tokens or cursors. Refresh before the
+first receipt can lose recovery correlation. See the
+[widget contract](../../../../../docs/superpowers/specs/2026-10-05-ask-ai-widgets.md)
+for full hook, recovery, stop, focus and lifecycle behavior.

package/src/features/client/SiteFeatures.tsx

@@ -0,0 +1,250 @@
+'use client'
+import {
+  lazy,
+  Suspense,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentType,
+  type ReactNode,
+} from 'react'
+import type { FeedbackInput, PublicFeatureBase } from '../contracts'
+import { FeatureContext, type OverlayName } from './context'
+import { AskAiProvider } from './AskAiProvider'
+import { FeedbackProvider } from './FeedbackProvider'
+import { ConsentRuntime } from './ConsentRuntime'
+import type { CustomConsentRegistration } from '../consent/custom'
+import { acquireVerificationProof } from './verification'
+import type { VerificationAction } from '../contracts'
+import { createFeatureTransport, waitForSignal, type VisitorVerification } from './transport'
+
+const builtinLoaders: Partial<Record<OverlayName, () => Promise<{ default: ComponentType }>>> = {
+  feedback: () => import('./FeedbackWidget'),
+  askAi: () => import('./AskAiWidget'),
+}
+const builtins = Object.fromEntries(
+  Object.entries(builtinLoaders).map(([key, load]) => [key, lazy(load)]),
+) as Partial<Record<OverlayName, ComponentType>>
+export type SiteFeaturesProps = {
+  endpoint?: string
+  components?: { AskAI?: ComponentType; Feedback?: ComponentType }
+  verification?: VisitorVerification
+  customConsent?: CustomConsentRegistration
+  children?: ReactNode
+}
+export function SiteFeatures(props: SiteFeaturesProps) {
+  // A changed endpoint is a different authority and must not retain its configuration/panel.
+  return <Runtime key={props.endpoint ?? '/api/u90/features/v1'} {...props} />
+}
+function Runtime({
+  endpoint,
+  components,
+  verification,
+  customConsent,
+  children,
+}: SiteFeaturesProps) {
+  const adapter = useRef(verification)
+  useLayoutEffect(() => {
+    adapter.current = verification
+  }, [verification])
+  const transport = useRef<ReturnType<typeof createFeatureTransport> | null>(null)
+  const acquireProof = useCallback(
+    async (options: { signal: AbortSignal; action?: VerificationAction }) => {
+      if (adapter.current) return adapter.current.acquireProof(options)
+      // Refresh public connection configuration at the action boundary, so a saved
+      // provider replacement uses its new key even before the background refresh.
+      const config = await transport.current!.config(options.signal)
+      if (!config.verification) throw new Error('Verification unavailable')
+      return acquireVerificationProof(
+        config.verification,
+        options.action ?? 'ask_ai_session',
+        options,
+      )
+    },
+    [],
+  )
+  // Create the transport only from an effect or event. The root survives adapter
+  // updates, so an in-flight logical session attempt remains coalesced.
+  const getTransport = useCallback(() => {
+    if (!transport.current)
+      transport.current = createFeatureTransport({ endpoint, verification: { acquireProof } })
+    return transport.current
+  }, [endpoint, acquireProof])
+  const [config, setConfig] = useState<PublicFeatureBase | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [active, setActive] = useState<OverlayName | null>(null)
+  const [announcement, announce] = useState('')
+  const activeRef = useRef(active)
+  useLayoutEffect(() => {
+    activeRef.current = active
+  }, [active])
+  const lifetime = useRef<AbortController | null>(null)
+  useLayoutEffect(() => {
+    const controller = new AbortController()
+    lifetime.current = controller
+    return () => controller.abort()
+  }, [])
+  const committedConfig = useRef(config)
+  useLayoutEffect(() => {
+    committedConfig.current = config
+  }, [config])
+  const launchers = useRef(new Map<OverlayName, { owner: symbol; node: HTMLButtonElement }>())
+  const registerLauncher = useCallback(
+    (name: OverlayName, owner: symbol, node: HTMLButtonElement | null) => {
+      if (node) launchers.current.set(name, { owner, node })
+      else if (launchers.current.get(name)?.owner === owner) launchers.current.delete(name)
+    },
+    [],
+  )
+  const returnName = useRef<OverlayName | null>(null)
+  const returnFocus = useRef<HTMLElement | null>(null)
+  const abort = useRef<AbortController | null>(null)
+  const pending = useRef<Promise<void> | null>(null)
+  const lastRefresh = useRef(0)
+  const close = useCallback(() => {
+    setActive(null)
+    const target = returnFocus.current
+    const origin = returnName.current
+    returnFocus.current = null
+    returnName.current = null
+    // Effects release the dialog's focus containment before restoring the launcher.
+    queueMicrotask(() => {
+      const usable = (node?: HTMLElement | null) =>
+        node?.isConnected &&
+        !node.matches(':disabled') &&
+        !node.closest('[hidden], [inert], [aria-hidden="true"]') &&
+        node.getClientRects().length > 0 &&
+        getComputedStyle(node).visibility === 'visible'
+      if (usable(target)) target!.focus()
+      else {
+        const replacement = origin && launchers.current.get(origin)?.node
+        if (replacement && usable(replacement)) replacement.focus()
+      }
+    })
+  }, [])
+  const refresh = useCallback((): Promise<void> => {
+    if (pending.current) return pending.current
+    const controller = new AbortController()
+    abort.current = controller
+    lastRefresh.current = Date.now()
+    pending.current = getTransport()
+      .config(controller.signal)
+      .then((next) => {
+        if (controller.signal.aborted) return
+        setConfig((current) => (current && current.revision > next.revision ? current : next))
+        setError(null)
+        if (activeRef.current && !next.enabled[activeRef.current]) close()
+      })
+      .catch(() => {
+        if (!controller.signal.aborted) setError('Site features unavailable. Please retry.')
+      })
+      .finally(() => {
+        if (abort.current === controller) pending.current = null
+      })
+    return pending.current
+  }, [getTransport, close])
+  useEffect(() => {
+    void refresh()
+    const visibleRefresh = () => {
+      if (document.visibilityState === 'visible' && Date.now() - lastRefresh.current >= 60000)
+        void refresh()
+    }
+    const timer = setInterval(visibleRefresh, 60000)
+    document.addEventListener('visibilitychange', visibleRefresh)
+    return () => {
+      clearInterval(timer)
+      document.removeEventListener('visibilitychange', visibleRefresh)
+      abort.current?.abort()
+      pending.current = null
+    }
+  }, [refresh])
+  const open = useCallback(
+    (name: OverlayName) => {
+      if (!config?.enabled[name]) return
+      if (activeRef.current === null) {
+        returnFocus.current =
+          document.activeElement instanceof HTMLElement ? document.activeElement : null
+        returnName.current = name
+      }
+      setActive(name)
+      void refresh()
+    },
+    [config, refresh],
+  )
+  const overlay = useMemo(() => ({ active, open, close }), [active, open, close])
+  const ensureSession = useCallback(
+    async (signal?: AbortSignal) => {
+      try {
+        const rootSignal = lifetime.current!.signal
+        const work = getTransport().ensureSession(rootSignal)
+        await (signal ? waitForSignal(work, signal) : work)
+        if (!rootSignal.aborted && !signal?.aborted) setError(null)
+      } catch (cause) {
+        if (!lifetime.current?.signal.aborted && !signal?.aborted)
+          setError('Verification or session unavailable. Please retry.')
+        throw cause
+      }
+    },
+    [getTransport],
+  )
+  const submitFeedback = useCallback(
+    async (input: FeedbackInput, signal: AbortSignal) => {
+      const rootSignal = lifetime.current!.signal
+      const operationSignal = AbortSignal.any([signal, rootSignal])
+      operationSignal.throwIfAborted()
+      operationSignal.throwIfAborted()
+      if (!committedConfig.current?.enabled.feedback) throw new Error('Feedback disabled')
+      return getTransport().feedback(input, operationSignal)
+    },
+    [getTransport],
+  )
+  const search = useCallback(
+    (query: string, signal: AbortSignal) => getTransport().search(query, signal),
+    [getTransport],
+  )
+  const value = useMemo(
+    () => ({
+      config,
+      error,
+      refresh,
+      ensureSession,
+      overlay,
+      announce,
+      submitFeedback,
+      registerLauncher,
+      search,
+    }),
+    [config, error, refresh, ensureSession, overlay, submitFeedback, registerLauncher, search],
+  )
+  const AskAI = components?.AskAI ?? builtins.askAi
+  const Feedback = components?.Feedback ?? builtins.feedback
+  return (
+    <FeatureContext.Provider value={value}>
+      <ConsentRuntime
+        endpoint={endpoint ?? '/api/u90/features/v1'}
+        config={config}
+        customConsent={customConsent}
+      >
+        <AskAiProvider endpoint={endpoint ?? '/api/u90/features/v1'} getTransport={getTransport}>
+          <FeedbackProvider presentation={Feedback}>
+            {children}
+            <div className="u90-features">
+              <Suspense fallback={null}>{config?.enabled.askAi && AskAI && <AskAI />}</Suspense>
+              <div
+                className="u90-feature-announcement"
+                role="status"
+                aria-live="polite"
+                aria-atomic="true"
+              >
+                {error ?? announcement}
+              </div>
+            </div>
+          </FeedbackProvider>
+        </AskAiProvider>
+      </ConsentRuntime>
+    </FeatureContext.Provider>
+  )
+}

package/src/features/client/askAiRecovery.ts

@@ -0,0 +1,92 @@
+import {
+  AiConversationPageSchema,
+  type AiMessagePart,
+  type AiSource,
+  type AiTurnState,
+} from '../contracts'
+export type AskAiMessage = {
+  id: string
+  requestId: string
+  role: 'user' | 'assistant'
+  text: string
+  sources: AiSource[]
+  state: AiTurnState
+  sequence: number
+  newAttempt?: boolean
+}
+export type RecoveryState = {
+  conversationId: string
+  historyEpoch: number | null
+  messages: AskAiMessage[]
+  fragments: Map<string, AiMessagePart>
+  cursor: string | null
+  snapshot: number | null
+}
+export const emptyRecovery = (conversationId: string): RecoveryState => ({
+  conversationId,
+  historyEpoch: null,
+  messages: [],
+  fragments: new Map(),
+  cursor: null,
+  snapshot: null,
+})
+/** Fragments never modify displayed text until their whole immutable revision is available. */
+export function mergeRecoveryPage(current: RecoveryState, input: unknown): RecoveryState {
+  const page = AiConversationPageSchema.parse(input)
+  if (page.conversationId !== current.conversationId) throw Error('Changed conversation')
+  const reset = current.historyEpoch !== null && current.historyEpoch !== page.historyEpoch
+  if (
+    !reset &&
+    current.cursor &&
+    current.snapshot !== null &&
+    current.snapshot !== page.snapshotUpperSequence
+  )
+    throw Error('Changed snapshot')
+  const state: RecoveryState = {
+    ...current,
+    historyEpoch: page.historyEpoch,
+    snapshot: page.snapshotUpperSequence,
+    cursor: page.nextCursor,
+    messages: reset ? [] : [...current.messages],
+    fragments: reset ? new Map() : new Map(current.fragments),
+  }
+  for (const part of page.parts) {
+    const prior = state.fragments.get(part.messageId)
+    let assembled = part
+    if (part.textStart !== 0) {
+      if (
+        !prior ||
+        prior.textEnd !== part.textStart ||
+        prior.contentRevision !== part.contentRevision ||
+        prior.requestId !== part.requestId ||
+        prior.sequence !== part.sequence ||
+        prior.role !== part.role ||
+        prior.state !== part.state ||
+        prior.totalLength !== part.totalLength ||
+        JSON.stringify(prior.sources) !== JSON.stringify(part.sources)
+      )
+        throw Error('Changed fragment')
+      assembled = { ...part, text: prior.text + part.text, textStart: 0 }
+    }
+    if (!assembled.lastPart) {
+      state.fragments.set(part.messageId, assembled)
+      continue
+    }
+    state.fragments.delete(part.messageId)
+    // A recovered local request replaces both placeholder identity and any previously streamed text.
+    state.messages = state.messages.filter(
+      (m) => m.id !== part.messageId && !(m.requestId === part.requestId && m.role === part.role),
+    )
+    state.messages.push({
+      id: part.messageId,
+      requestId: part.requestId,
+      sequence: part.sequence,
+      role: part.role,
+      text: assembled.text,
+      sources: part.sources,
+      state: part.state,
+    })
+  }
+  state.messages.sort((a, b) => a.sequence - b.sequence)
+  return state
+}

package/src/features/client/askAiStream.ts

@@ -0,0 +1,59 @@
+import { AiStreamEventSchema, type AiStreamEvent } from '../contracts'
+import { FeatureClientError, waitForSignal } from './transport'
+/** One HTTP response is one sequence lifetime. Terminal replay starts at zero again. */
+export async function consumeAiStream(
+  response: Response,
+  requestId: string,
+  receive: (event: AiStreamEvent) => void,
+  signal: AbortSignal,
+) {
+  if (!response.headers.get('content-type')?.startsWith('text/event-stream'))
+    throw new FeatureClientError()
+  const reader = response.body?.getReader()
+  if (!reader) throw new FeatureClientError()
+  const decoder = new TextDecoder('utf-8', { fatal: true })
+  let buffer = '',
+    sequence = -1,
+    terminal = false,
+    total = 0
+  const invalid = () => new FeatureClientError('unavailable')
+  try {
+    for (;;) {
+      const { done, value } = await waitForSignal(reader.read(), signal)
+      if (done) break
+      total += value.byteLength
+      if (total > 2 * 1024 * 1024) throw invalid()
+      buffer += decoder.decode(value, { stream: true })
+      for (;;) {
+        const match = /\r?\n\r?\n/.exec(buffer)
+        if (!match) break
+        const frame = buffer.slice(0, match.index)
+        buffer = buffer.slice(match.index + match[0].length)
+        if (!frame || frame.startsWith(':')) continue
+        if (new TextEncoder().encode(frame).length > 131072) throw invalid()
+        if (!frame.startsWith('data: ') || frame.includes('\n')) throw invalid()
+        const parsed = AiStreamEventSchema.safeParse(JSON.parse(frame.slice(6)))
+        if (!parsed.success || parsed.data.requestId.toLowerCase() !== requestId.toLowerCase())
+          throw invalid()
+        const event = parsed.data
+        if (event.sequence <= sequence) continue
+        if (
+          terminal ||
+          event.sequence !== sequence + 1 ||
+          (sequence === -1 && event.type !== 'start') ||
+          (sequence >= 0 && event.type === 'start')
+        )
+          throw invalid()
+        sequence = event.sequence
+        terminal = event.type === 'done' || event.type === 'error'
+        receive(event)
+      }
+      if (new TextEncoder().encode(buffer).length > 131072) throw invalid()
+    }
+    buffer += decoder.decode()
+    if (buffer.trim() || !terminal) throw invalid()
+  } finally {
+    await reader.cancel().catch(() => {})
+    reader.releaseLock()
+  }
+}

package/src/features/client/context.tsx

@@ -0,0 +1,24 @@
+'use client'
+import { createContext, useContext } from 'react'
+import type { SearchHit, FeedbackInput, FeedbackReceipt, PublicFeatureBase } from '../contracts'
+export type OverlayName = 'askAi' | 'feedback'
+export type FeatureRuntime = {
+  config: PublicFeatureBase | null
+  error: string | null
+  refresh: () => Promise<void>
+  ensureSession: (signal?: AbortSignal) => Promise<void>
+  overlay: { active: OverlayName | null; open: (name: OverlayName) => void; close: () => void }
+  search: (query: string, signal: AbortSignal) => Promise<SearchHit[]>
+  submitFeedback: (input: FeedbackInput, signal: AbortSignal) => Promise<FeedbackReceipt>
+  registerLauncher: (name: OverlayName, owner: symbol, node: HTMLButtonElement | null) => void
+  announce: (message: string) => void
+}
+export const FeatureContext = createContext<FeatureRuntime | null>(null)
+export function useSiteFeatures(): FeatureRuntime {
+  const context = useContext(FeatureContext)
+  if (!context) throw new Error('Feature hooks require a SiteFeatures root.')
+  return context
+}
+export function useFeatureOverlay() {
+  return useSiteFeatures().overlay
+}

package/src/features/client/index.ts

@@ -0,0 +1,24 @@
+'use client'
+export { acquireVerificationProof, useFormVerification, VERIFICATION_CSP } from './verification'
+export { SiteFeatures, type SiteFeaturesProps } from './SiteFeatures'
+export {
+  useSiteFeatures,
+  useFeatureOverlay,
+  type FeatureRuntime,
+  type OverlayName,
+} from './context'
+export { FeatureDialog } from './overlay'
+export { FeatureClientError, type VisitorVerification } from './transport'
+
+export { useFeedback, type FeedbackController, type FeedbackAnswer } from './useFeedback'
+
+export { cookieScriptAdapter, normalizeCookieScript } from '../consent/cookieScript'
+export { customConsentAdapter, type CustomConsentRegistration } from '../consent/custom'
+
+export { useConsent, type ConsentController } from './useConsent'
+export { createConsentLoader } from '../consent/loader'
+
+export { useSiteSearch } from './useSiteSearch'
+
+export { useAskAI, type AskAiController } from './useAskAI'
+export { AskAiContent } from './AskAiWidget'