@unitninety/site-kit 0.0.0-stage → 1.6.2

package/src/features/client/transport.ts

@@ -0,0 +1,310 @@
+import { acquireVerificationProof } from './verification'
+import { z } from 'zod'
+import { consumeAiStream } from './askAiStream'
+import {
+  AiConversationPageSchema,
+  AI_RECOVERY_MAX_BYTES,
+  AskAiInputSchema,
+  AiRatingInputSchema,
+  type AskAiInput,
+  type AiStreamEvent,
+} from '../contracts'
+import {
+  FeatureErrorSchema,
+  SearchQuerySchema,
+  SearchResponseSchema,
+  SEARCH_RESPONSE_BYTES,
+  FeedbackInputSchema,
+  type FeedbackInput,
+  type FeedbackReceipt,
+  PublicFeatureBaseSchema,
+  type FeatureErrorCode,
+  type PublicFeatureBase,
+} from '../contracts'
+
+export type VisitorVerification = {
+  acquireProof: (options: {
+    signal: AbortSignal
+    action?: import('../contracts').VerificationAction
+  }) => Promise<string | null>
+}
+export class FeatureClientError extends Error {
+  constructor(public readonly code: FeatureErrorCode = 'unavailable') {
+    super(
+      code === 'verification_required'
+        ? 'Verification required. Please retry.'
+        : 'Site features unavailable. Please retry.',
+    )
+    this.name = 'FeatureClientError'
+  }
+}
+export type FeatureTransportOptions = {
+  endpoint?: string
+  verification?: VisitorVerification
+  fetch?: typeof fetch
+}
+
+/** Same-origin browser transport. It never exposes or stores the HttpOnly credential. */
+export function createFeatureTransport(options: FeatureTransportOptions = {}) {
+  const endpoint = options.endpoint ?? '/api/u90/features/v1'
+  if (!/^\/(?!\/)[A-Za-z0-9/_-]+$/.test(endpoint))
+    throw new Error('Expected a same-origin feature endpoint.')
+  const request = async (operation: string, signal: AbortSignal, body?: unknown, cap = 65536) => {
+    signal.throwIfAborted()
+    const response = await (options.fetch ?? fetch)(`${endpoint}/${operation}`, {
+      method: body === undefined ? 'GET' : 'POST',
+      credentials: 'same-origin',
+      cache: 'no-store',
+      headers: body === undefined ? undefined : { 'content-type': 'application/json' },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal,
+    })
+    return readJson(response, cap)
+  }
+  const readJson = async (response: Response, cap: number) => {
+    // Bound even a misconfigured same-origin endpoint's response.
+    const reader = response.body?.getReader()
+    const chunks: Uint8Array[] = []
+    let bytes = 0
+    if (!reader) throw new FeatureClientError()
+    try {
+      for (;;) {
+        const { done, value } = await reader.read()
+        if (done) break
+        bytes += value.byteLength
+        if (bytes > cap) throw new FeatureClientError()
+        chunks.push(value)
+      }
+    } finally {
+      await reader.cancel().catch(() => {})
+    }
+    const all = new Uint8Array(bytes)
+    let offset = 0
+    for (const chunk of chunks) {
+      all.set(chunk, offset)
+      offset += chunk.byteLength
+    }
+    let data: unknown
+    try {
+      data = JSON.parse(new TextDecoder().decode(all))
+    } catch {
+      throw new FeatureClientError()
+    }
+    if (!response.ok) {
+      const parsed = FeatureErrorSchema.safeParse(data)
+      throw new FeatureClientError(parsed.success ? parsed.data.error.code : 'unavailable')
+    }
+    return data
+  }
+  const boundedSignal = (signal?: AbortSignal) =>
+    signal ? AbortSignal.any([signal, AbortSignal.timeout(10000)]) : AbortSignal.timeout(10000)
+  let pending: Promise<void> | undefined
+  const grants = new Map<string, { body: string; grant: string }>()
+  const proof = async (action: import('../contracts').VerificationAction, signal: AbortSignal) => {
+    const config = PublicFeatureBaseSchema.parse(await request('config', boundedSignal(signal)))
+    if (config.verification?.mode === 'disabled')
+      return acquireVerificationProof(config.verification, action, { signal })
+    if (options.verification)
+      return waitForSignal(options.verification.acquireProof({ signal, action }), signal)
+    if (!config.verification) throw new FeatureClientError('verification_required')
+    return acquireVerificationProof(config.verification, action, { signal })
+  }
+  return {
+    async aiMessage(
+      input: AskAiInput,
+      signal: AbortSignal,
+      receive: (event: AiStreamEvent) => void,
+    ) {
+      const response = await waitForSignal(
+        (options.fetch ?? fetch)(`${endpoint}/ask-ai/messages`, {
+          method: 'POST',
+          credentials: 'same-origin',
+          cache: 'no-store',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify(AskAiInputSchema.parse(input)),
+          signal,
+        }),
+        signal,
+      )
+      if (!response.ok) {
+        await readJson(response, 16384)
+        throw new FeatureClientError()
+      }
+      await consumeAiStream(response, input.requestId, receive, signal)
+    },
+    async aiConversation(id: string, cursor: string | null, signal: AbortSignal) {
+      if (
+        !/^[A-Za-z0-9_-]{1,128}$/.test(id) ||
+        (cursor !== null && !/^[A-Za-z0-9_-]{1,1024}$/.test(cursor))
+      )
+        throw new FeatureClientError('invalid_request')
+      const bounded = boundedSignal(signal)
+      return AiConversationPageSchema.parse(
+        await waitForSignal(
+          request(
+            `ask-ai/conversations/${id}${cursor ? '?cursor=' + cursor : ''}`,
+            bounded,
+            undefined,
+            AI_RECOVERY_MAX_BYTES,
+          ),
+          bounded,
+        ),
+      )
+    },
+    async aiRating(
+      id: string,
+      input: { requestId: string; rating: 'helpful' | 'unhelpful' },
+      signal: AbortSignal,
+    ) {
+      if (!/^[A-Za-z0-9_-]{1,128}$/.test(id)) throw new FeatureClientError('invalid_request')
+      const bounded = boundedSignal(signal)
+      const result = await waitForSignal(
+        request(`ask-ai/messages/${id}/rating`, bounded, AiRatingInputSchema.parse(input), 16384),
+        bounded,
+      )
+      if (!z.object({ version: z.literal(1), ok: z.literal(true) }).safeParse(result).success)
+        throw new FeatureClientError()
+    },
+    async search(query: string, signal: AbortSignal) {
+      const input = SearchQuerySchema.parse({ q: query })
+      const bounded = boundedSignal(signal)
+      const result = SearchResponseSchema.safeParse(
+        await waitForSignal(
+          request(
+            'search?' + new URLSearchParams(input),
+            bounded,
+            undefined,
+            SEARCH_RESPONSE_BYTES,
+          ),
+          bounded,
+        ),
+      )
+      if (!result.success) throw new FeatureClientError()
+      return result.data.results
+    },
+    async feedback(input: FeedbackInput, signal: AbortSignal): Promise<FeedbackReceipt> {
+      const body = FeedbackInputSchema.parse(input)
+      const serialized = JSON.stringify(body)
+      let prior = grants.get(body.requestId)
+      if (prior && prior.body !== serialized) throw new FeatureClientError('conflict')
+      if (!prior) {
+        await request('session', boundedSignal(signal), {
+          requestId: crypto.randomUUID(),
+          mode: 'identity',
+        })
+        const token = await proof('feedback_submit', signal)
+        const result = z
+          .object({ grant: z.string().min(1).max(4096) })
+          .parse(await request('verify', boundedSignal(signal), { body, proof: token }))
+        prior = { body: serialized, grant: result.grant }
+        if (grants.size >= 100) grants.delete(grants.keys().next().value!)
+        grants.set(body.requestId, prior)
+      }
+      const receipt = z
+        .object({ submissionId: z.string().min(1).max(128), receivedAt: z.iso.datetime() })
+        .safeParse(
+          await waitForSignal(
+            request('feedback', boundedSignal(signal), { body, grant: prior.grant }).catch(
+              (error) => {
+                if (
+                  error instanceof FeatureClientError &&
+                  ['forbidden', 'conflict'].includes(error.code)
+                )
+                  grants.delete(body.requestId)
+                throw error
+              },
+            ),
+            signal,
+          ),
+        )
+      if (!receipt.success) throw new FeatureClientError()
+      return receipt.data
+    },
+    async config(signal?: AbortSignal): Promise<PublicFeatureBase> {
+      const result = PublicFeatureBaseSchema.safeParse(
+        await request('config', boundedSignal(signal)),
+      )
+      if (!result.success) throw new FeatureClientError()
+      return result.data
+    },
+    ensureSession(signal?: AbortSignal): Promise<void> {
+      if (signal?.aborted) return Promise.reject(signal.reason)
+      if (pending) return pending
+      const bounded = signal
+        ? AbortSignal.any([signal, AbortSignal.timeout(120000)])
+        : AbortSignal.timeout(120000)
+      const requestId = crypto.randomUUID()
+      const post = async (proof?: string | null) => {
+        const data = (await request('session', boundedSignal(bounded), {
+          requestId,
+          ...(proof === undefined ? {} : { proof }),
+        })) as { version?: unknown; ok?: unknown }
+        if (data?.version !== 1 || data.ok !== true) throw new FeatureClientError()
+      }
+      pending = (async () => {
+        const attempt = async (proof?: string | null) => {
+          try {
+            await post(proof)
+          } catch (error) {
+            if (bounded.aborted || error instanceof FeatureClientError) throw error
+            // Uncertain issuance gets one cookie-only probe, with the same logical ID.
+            await post()
+          }
+        }
+        try {
+          await attempt()
+          return
+        } catch (error) {
+          if (!(error instanceof FeatureClientError) || error.code !== 'verification_required')
+            throw error
+        }
+        let token: string | null
+        try {
+          token = await new Promise<string | null>((resolve, reject) => {
+            const aborted = () => reject(bounded.reason)
+            bounded.addEventListener('abort', aborted, { once: true })
+            Promise.resolve()
+              .then(() => {
+                bounded.throwIfAborted()
+                return proof('ask_ai_session', bounded)
+              })
+              .then(resolve, reject)
+              .finally(() => bounded.removeEventListener('abort', aborted))
+          })
+        } catch {
+          throw new FeatureClientError('verification_required')
+        }
+        bounded.throwIfAborted()
+        if (token !== null && (!token || new TextEncoder().encode(token).length > 4096))
+          throw new FeatureClientError('verification_required')
+        await attempt(token)
+      })().finally(() => {
+        pending = undefined
+      })
+      return pending
+    },
+  }
+}
+
+/** Caller cancellation must not own root-coalesced session/proof work. */
+export function waitForSignal<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const aborted = () => {
+      cleanup()
+      reject(signal.reason)
+    }
+    const cleanup = () => signal.removeEventListener('abort', aborted)
+    signal.addEventListener('abort', aborted, { once: true })
+    promise.then(
+      (value) => {
+        cleanup()
+        resolve(value)
+      },
+      (error) => {
+        cleanup()
+        reject(error)
+      },
+    )
+    if (signal.aborted) aborted()
+  })
+}

package/src/features/client/useAskAI.ts

@@ -0,0 +1,45 @@
+'use client'
+import { createContext, useCallback, useContext, useRef, type RefCallback } from 'react'
+import type { AskAiWidgetSettings } from '../contracts'
+import type { AskAiMessage } from './askAiRecovery'
+import { useSiteFeatures } from './context'
+export type AskAiController = {
+  open: boolean
+  messages: AskAiMessage[]
+  status: 'idle' | 'sending' | 'streaming' | 'error'
+  error: string | null
+  ratingError: string | null
+  settings: AskAiWidgetSettings
+  draft: string
+  setDraft(value: string): void
+  recovering: boolean
+  hasEarlier: boolean
+  canRecover: boolean
+  awaitingAnswer: boolean
+  canRetry: boolean
+  canNewAttempt: boolean
+  ratings: Record<string, 'helpful' | 'unhelpful'>
+  show(): void
+  hide(): void
+  send(message: string): Promise<void>
+  stop(): void
+  startNewConversation(): void
+  retry(): Promise<void>
+  retryAnswer(): Promise<void>
+  recover(): Promise<void>
+  loadEarlier(): Promise<void>
+  rate(messageId: string, rating: 'helpful' | 'unhelpful'): Promise<void>
+  launcherRef: RefCallback<HTMLButtonElement>
+}
+export const AskAiContext = createContext<Omit<AskAiController, 'launcherRef'> | null>(null)
+export function useAskAI(): AskAiController {
+  const value = useContext(AskAiContext),
+    { registerLauncher } = useSiteFeatures(),
+    owner = useRef(Symbol('Ask AI launcher'))
+  const launcherRef = useCallback<RefCallback<HTMLButtonElement>>(
+    (node) => registerLauncher('askAi', owner.current, node),
+    [registerLauncher],
+  )
+  if (!value) throw Error('useAskAI requires a SiteFeatures root.')
+  return { ...value, launcherRef }
+}

package/src/features/client/useConsent.ts

@@ -0,0 +1,15 @@
+'use client'
+import { createContext, useContext } from 'react'
+import type { ConsentState } from '../contracts/consent'
+export type ConsentController = {
+  state: ConsentState
+  ready: boolean
+  error: string | null
+  openPreferences(): void
+}
+export const ConsentContext = createContext<ConsentController | null>(null)
+export function useConsent(): ConsentController {
+  const value = useContext(ConsentContext)
+  if (!value) throw new Error('Consent hooks require a SiteFeatures root.')
+  return value
+}

package/src/features/client/useFeedback.ts

@@ -0,0 +1,33 @@
+'use client'
+import { createContext, useCallback, useContext, useRef, type RefCallback } from 'react'
+import type { PageContext } from '../contracts'
+import { useSiteFeatures } from './context'
+export type FeedbackAnswer = { rating?: 1 | 2 | 3 | 4 | 5; comment?: string }
+export type FeedbackController = {
+  open: boolean
+  status: 'idle' | 'submitting' | 'success' | 'error'
+  error: string | null
+  page: Readonly<PageContext> | null
+  currentPage: Readonly<PageContext> | null
+  show(): void
+  hide(): void
+  submit(answer: FeedbackAnswer): Promise<void>
+  retry(): Promise<void>
+  startNew(): void
+  launcherRef: RefCallback<HTMLButtonElement>
+}
+export const FeedbackContext = createContext<Omit<FeedbackController, 'launcherRef'> | null>(null)
+/** Submission ownership is shared; register complete presentations via components.Feedback. */
+export function useFeedback(): FeedbackController {
+  const controller = useContext(FeedbackContext)
+  const { registerLauncher } = useSiteFeatures()
+  const owner = useRef(Symbol('feedback launcher'))
+  const launcherRef = useCallback<RefCallback<HTMLButtonElement>>(
+    (node) => {
+      registerLauncher('feedback', owner.current, node)
+    },
+    [registerLauncher],
+  )
+  if (!controller) throw new Error('useFeedback requires a SiteFeatures root.')
+  return { ...controller, launcherRef }
+}

package/src/features/client/useSiteSearch.ts

@@ -0,0 +1,50 @@
+'use client'
+import { useEffect, useMemo, useState } from 'react'
+import type { SearchHit } from '../contracts'
+import { useSiteFeatures } from './context'
+type Result = {
+  results: SearchHit[]
+  state: 'idle' | 'loading' | 'ready' | 'error'
+  error: string | null
+}
+const idle: Result = { results: [], state: 'idle', error: null }
+export function useSiteSearch(query: string): Result {
+  const { search, config } = useSiteFeatures()
+  const normalized = query.trim()
+  const enabled = config?.enabled.search === true
+  const input = useMemo(
+    () => ({ query: normalized, enabled, search }),
+    [normalized, enabled, search],
+  )
+  const [value, setValue] = useState<Result & { input: typeof input | null }>({
+    ...idle,
+    input: null,
+  })
+  useEffect(() => {
+    if (!input.enabled || input.query.length < 2) return
+    const controller = new AbortController()
+    const timer = setTimeout(() => {
+      void input.search(input.query, controller.signal).then(
+        (results) => {
+          if (!controller.signal.aborted) setValue({ input, results, state: 'ready', error: null })
+        },
+        () => {
+          if (!controller.signal.aborted)
+            setValue({
+              input,
+              results: [],
+              state: 'error',
+              error: 'Search unavailable. Please retry.',
+            })
+        },
+      )
+    }, 200)
+    return () => {
+      clearTimeout(timer)
+      controller.abort()
+    }
+  }, [input])
+  if (!enabled || normalized.length < 2) return idle
+  if (value.input !== input) return { results: [], state: 'loading', error: null }
+  return { results: value.results, state: value.state, error: value.error }
+}

package/src/features/client/verification.ts

@@ -0,0 +1,141 @@
+'use client'
+import { useCallback } from 'react'
+import {
+  ProofSchema,
+  VerificationConfigSchema,
+  type VerificationAction,
+  type VerificationConfig,
+} from '../contracts'
+export { VERIFICATION_CSP } from '../contracts'
+type Google = {
+  ready(cb: () => void): void
+  execute(key: string, options: { action: string }): Promise<string>
+}
+type Turnstile = {
+  render(container: HTMLElement, options: Record<string, unknown>): string
+  remove(id: string): void
+}
+type Providers = { grecaptcha?: Google & { enterprise?: Google }; turnstile?: Turnstile }
+const scripts = new Map<string, Promise<void>>()
+function wait<T>(work: Promise<T>, signal: AbortSignal): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const abort = () => {
+      signal.removeEventListener('abort', abort)
+      reject(signal.reason)
+    }
+    signal.addEventListener('abort', abort, { once: true })
+    work.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort))
+    if (signal.aborted) abort()
+  })
+}
+function load(url: string): Promise<void> {
+  const existing = scripts.get(url)
+  if (existing) return existing
+  const work = new Promise<void>((resolve, reject) => {
+    const script = document.createElement('script')
+    script.src = url
+    script.async = true
+    const timeout = setTimeout(() => {
+      script.remove()
+      reject(Error('Verification script unavailable.'))
+    }, 10000)
+    script.onload = () => {
+      clearTimeout(timeout)
+      resolve()
+    }
+    script.onerror = () => {
+      clearTimeout(timeout)
+      script.remove()
+      reject(Error('Verification script unavailable.'))
+    }
+    document.head.append(script)
+  })
+  scripts.set(url, work)
+  void work.catch(() => scripts.delete(url))
+  return work
+}
+/** Lazy, single-use proof. Nothing loads until the caller submits a protected action. */
+export async function acquireVerificationProof(
+  config: VerificationConfig,
+  action: VerificationAction,
+  options: { signal?: AbortSignal } = {},
+): Promise<string | null> {
+  const parsed = VerificationConfigSchema.parse(config)
+  if (parsed.readiness !== 'configured' || (parsed.mode !== 'disabled' && !parsed.siteKey))
+    throw Error('Verification unavailable. Please retry or contact the site owner.')
+  const signal = options.signal
+    ? AbortSignal.any([options.signal, AbortSignal.timeout(120000)])
+    : AbortSignal.timeout(120000)
+  signal.throwIfAborted()
+  if (parsed.mode === 'disabled') return null
+  const siteKey = parsed.siteKey!
+  const providers = window as unknown as Providers
+  if (parsed.provider !== 'turnstile') {
+    const enterprise = parsed.provider === 'google-cloud'
+    const script =
+      'https://www.google.com/recaptcha/' +
+      (enterprise ? 'enterprise.js' : 'api.js') +
+      '?render=' +
+      encodeURIComponent(siteKey)
+    await wait(load(script), signal)
+    const api = enterprise ? providers.grecaptcha?.enterprise : providers.grecaptcha
+    if (!api) throw Error('Verification unavailable. Please retry.')
+    await wait(new Promise<void>((resolve) => api.ready(resolve)), signal)
+    return ProofSchema.parse(await wait(api.execute(siteKey, { action }), signal))
+  }
+  await wait(load('https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit'), signal)
+  const api = providers.turnstile
+  if (!api) throw Error('Verification unavailable. Please retry.')
+  const previous = document.activeElement
+  const dialog = document.createElement('dialog')
+  dialog.className = 'u90-verification-dialog'
+  dialog.setAttribute('aria-label', 'Verify your submission')
+  const title = document.createElement('p')
+  title.textContent = 'Complete this check to send your submission.'
+  const container = document.createElement('div')
+  container.setAttribute('aria-label', 'Security check')
+  container.tabIndex = 0
+  const cancel = document.createElement('button')
+  cancel.type = 'button'
+  cancel.textContent = 'Cancel verification'
+  dialog.append(title, container, cancel)
+  document.body.append(dialog)
+  dialog.showModal()
+  container.focus()
+  let id: string | undefined
+  try {
+    return ProofSchema.parse(
+      await wait(
+        new Promise<string>((resolve, reject) => {
+          const cancelled = () => reject(Error('Verification cancelled. Your draft is preserved.'))
+          cancel.onclick = cancelled
+          dialog.addEventListener('cancel', cancelled, { once: true })
+          id = api.render(container, {
+            sitekey: siteKey,
+            action,
+            callback: resolve,
+            'error-callback': () => reject(Error('Verification failed. Please retry.')),
+            'expired-callback': () => reject(Error('Verification expired. Please retry.')),
+          })
+        }),
+        signal,
+      ),
+    )
+  } finally {
+    if (id !== undefined) api.remove(id)
+    dialog.close()
+    dialog.remove()
+    if (previous instanceof HTMLElement && previous.isConnected) previous.focus()
+  }
+}
+/** Custom forms call this on submit and forward the proof separately from answer values. */
+export function useFormVerification(config: VerificationConfig | undefined) {
+  return useCallback(
+    (options: { signal?: AbortSignal } = {}) => {
+      if (!config)
+        return Promise.reject(Error('Verification unavailable. Please contact the site owner.'))
+      return acquireVerificationProof(config, 'form_submit', options)
+    },
+    [config],
+  )
+}

package/src/features/consent/README.md

@@ -0,0 +1,70 @@
+# Consent setup and lifecycle
+
+Install the existing same-origin feature gateway. Mount this standard setup once in the consuming server root layout, independently of whether Consent is currently enabled:
+
+```tsx
+import { SiteFeatures } from '@unitninety/site-kit/features'
+import { ConsentDefaults } from '@unitninety/site-kit/features/server'
+import '@unitninety/site-kit/features/styles.css'
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return <html lang="en"><body>
+    <ConsentDefaults />
+    <SiteFeatures>{children}</SiteFeatures>
+  </body></html>
+}
+```
+
+Keep the root around children from their first render, including while choosing custom presentations. Remote accepted configuration controls activation, provider/source, Google mode and integrations. No installation, grant or mode prop is supported. Later administration does not require layout edits. Reuse the native gateway handlers; never add a competing catch-all.
+
+`ConsentDefaults` is exported only through the server entry. It renders a stable-ID denied-only `next/script` with `beforeInteractive`, without provider IDs, tag sources, configuration fetches or pageviews. Installed Next 16.3.4 queues App Router scripts before hydration; this does not promise native parser-time execution or control unmanaged async scripts. Remove old CMP, GA and other raw optional installers. The browser driver defensively runs the same initializer before its own first managed Google insertion if its marker is absent; conflicting unmanaged Google ownership aborts insertion. The marker is bookkeeping, never consent authority, and defaults never replay on refresh/navigation/regrant.
+
+`useConsent()` exposes exactly `{ state, ready, error, openPreferences }`. A real preferences button calls `openPreferences`; unavailable or throwing providers produce a handled error. The root supplies an accessible status/retry control and a visitor-controlled **Reload to apply consent changes** button when needed. It never reloads automatically on Close or assumes any event confirms a saved choice. Existing preferences controls remain usable during disable/withdrawal where the provider is still available.
+
+## Banner embed URL
+
+The Cookies workspace accepts an HTTPS script URL from any banner provider. With an active
+`custom` installation and no `customConsent` registration, Site Kit inserts that script once per
+document. No adapter or consent event is required just to display the provider's banner. The URL
+must point to its external JavaScript, not a provider dashboard, iframe page or pasted HTML. Providers
+that need inline initialization, extra attributes or synchronous parser execution may still need
+website code. The website Content Security Policy must allow the provider’s script origin and
+any additional resources it needs; saving a URL does not relax that policy. Custom script changes retain the existing `code.write` permission requirement.
+
+Embedding does not grant U90 consent: `useConsent().ready` stays false, all U90-managed optional
+integrations remain denied, and the provider's own controls handle preferences. Unregistered
+`u90:consent` events are ignored. Successful loading alone is not a consent signal. A missing optional
+registration is not an installation error; actual network failures/timeouts still surface normally.
+Already executed scripts cannot be undone by disabling the feature; reload the document to apply
+URL removal/replacement. Remove duplicate legacy installers before enabling the embed.
+
+Recognized direct CookieScript URLs retain their built-in category connection automatically. Other
+URLs use the same provider-independent embed path. Existing saved installations remain compatible.
+
+## Optional custom consent connection
+
+The optional `SiteFeatures` prop `customConsent?: CustomConsentRegistration` selects exactly one code-owned registration, only when the accepted remote provider is `custom`:
+
+```ts
+// Stable module identity, or useMemo with stable callback/adapter dependencies.
+const customConsent = { adapter: myConsentAdapter }
+// Alternatively: const customConsent = { openPreferences: reopenMyCMP }
+```
+
+The adapter supplies `read`, `subscribe` (returning cleanup) and `openPreferences`. The event bridge supplies only the reopen callback and publishes a fresh complete validated `ConsentState` in `window` event `u90:consent` during its active subscription. An event before registration cannot qualify. Missing/conflicting registration, invalid/unready snapshots and missing reopening deny optional code. An absent registration still permits the banner embed described above; an explicitly invalid registration remains an error. There is no arbitrary-window-global fallback. Factories are side-effect free; committed ownership subscribes before provider insertion and immediately reads current state.
+
+Keep actual adapter identity stable. For a bridge keep both its registration object and reopen callback stable. Replacement after activation requires a document reload and cannot transfer old events/grants. Render-only/suspended updates do not install listeners or replace authority.
+
+## Runtime guarantees and limits
+
+A document-owned registry retains execution records across navigation, React replay, root remount, integration removal and endpoint replacement. Equivalent settings revisions do not reinstall scripts or resubscribe. Last accepted config remains authoritative during failed/rejected refresh; real provider failures, committed disable and endpoint/provider replacement still deny immediately. Session/Feedback errors never decide consent. Disabled Consent does not grant categories.
+
+The fixed `createConsentLoader(driver)` API exposes `apply(state, integrations): Promise<void>` and `dispose(): void`. `IntegrationDriver` remains `start(integration): Promise<void>` and `stop(id): Promise<'stopped' | 'reload-required'>`. Starts deduplicate; withdrawal invokes stop immediately even during an unresolved start, and late initialization is stopped again. Built-in vetoes are synchronous. Drivers supplied by code must honor that same emission-veto obligation. Ten-second load/stop bounds surface failure and uncertainty. A network load error is retryable; possibly executing timed-out code requires reload.
+
+Basic Google mode makes no managed Google tag request before consent. Explicit advanced mode permits only classified Google requests while denied and may produce vendor consent-mode traffic; generic rows remain category-gated. Google defaults/update, `ga-disable`, `send_page_view:false` and current-permission checks guard Site Kit-owned SPA pageviews. Denied queued navigation is discarded; regrant emits only the current page.
+
+The shared closed classifier determines new GA4/ContentSquare drivers and approved executable attributes. An already executed GA source retains its proven teardown on category-policy changes, but its events require **both current row-category permission and analytics consent**. That historical capability never changes classification, code.write authorization or advanced eligibility for the edited row. New recategorized rows are generic.
+
+ContentSquare uses documented `optout` and requires reload; no web optin or cookie-clearing workaround is supplied. Its persisted opt-out may still affect regrant after reload. Attempted generic/Maps code requires reload regardless of a requested `stop` policy. Removing a script node is not teardown. Any reload requirement blocks every optional restart, including renamed/readded rows, until a real document reload. Previously executed third-party code cannot be rolled back.
+
+Tests use deterministic local DOM/provider doubles only. Task3 supplies actual production Next browser tag/beacon proof, both public projections, settings authorization/UI, the standard starter mount and exact KAW fixture transforms. No live-vendor account, regional/legal compliance, ContentSquare delivery/regrant or production rollout is certified.