@decentrys/ui-sdk 0.1.0

package/src/components/RiskDetailsModal.tsx

@@ -0,0 +1,229 @@
+/**
+ * "Why?" — answered completely.
+ *
+ * Everything the banner had to summarise is here in full: every explanation
+ * line, every fact with its source and timestamp, every capability, every
+ * signal including the ones that did not count, every evidence item with the
+ * source that produced it and whether an analyst confirmed it, every unknown,
+ * the score components with coverage labelled as coverage, and the model
+ * version the classification came from.
+ *
+ * This is the component that makes "nothing unexplained" true rather than
+ * aspirational. If a user disagrees with an assessment, this dialog is where
+ * they find the specific claim to disagree with.
+ *
+ * Accessibility here is functional, not decorative: the dialog takes focus on
+ * open and returns it on close, Escape closes it, the backdrop closes it, and
+ * it is labelled by its own heading. A modal that traps a wallet user with no
+ * keyboard route out is a worse bug than anything it was going to explain.
+ */
+
+import { useEffect, useId, useRef, type ReactNode } from 'react';
+import { createPortal } from 'react-dom';
+import type { ProtectResult } from '@decentrys/protect';
+import { useUiConfig } from '../context';
+import { themeStyle } from '../theme';
+import {
+  AvailabilityNote, CapabilityRow, type CommonProps, DemotedNote, EmptyNote, ExplanationList,
+  FactRow, HistoryNote, LevelBadge, Mono, Section, SignalList, StyleGate, UnknownRow, cx,
+} from '../primitives';
+import {
+  assessmentSections, componentRows, decisionPresentation, formatConfidence, formatTimestamp,
+  levelPresentation,
+} from '../presentation';
+
+export interface RiskDetailsModalProps extends CommonProps {
+  result: ProtectResult;
+  open: boolean;
+  onClose: () => void;
+  subjectNoun?: string;
+  /**
+   * Render into `document.body` rather than in place. Disable it for a shadow
+   * root, a React Native-style renderer or a server render.
+   */
+  portal?: boolean;
+}
+
+export function RiskDetailsModal({
+  result, open, onClose, subjectNoun = 'address', portal = true,
+  className, style, theme, copy: copyOverrides, levelLabels,
+}: RiskDetailsModalProps): ReactNode {
+  const { copy, theme: mergedTheme, emitStyles } = useUiConfig({ theme, copy: copyOverrides });
+  const titleId = useId();
+  const dialogRef = useRef<HTMLDivElement | null>(null);
+  const restoreFocusTo = useRef<Element | null>(null);
+
+  useEffect(() => {
+    if (!open) return undefined;
+    restoreFocusTo.current = typeof document === 'undefined' ? null : document.activeElement;
+    dialogRef.current?.focus();
+
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        event.stopPropagation();
+        onClose();
+      }
+    };
+    document.addEventListener('keydown', onKeyDown);
+    return () => {
+      document.removeEventListener('keydown', onKeyDown);
+      // Returning focus is the half of this that is usually skipped, and the
+      // half a keyboard user actually notices.
+      const previous = restoreFocusTo.current;
+      if (previous instanceof HTMLElement) previous.focus();
+    };
+  }, [open, onClose]);
+
+  if (!open) return null;
+
+  const { assessment, subject, decision, cached, demotedSignals } = result;
+  const level = levelPresentation(assessment.riskLevel, { labels: levelLabels });
+  const sections = assessmentSections(assessment, copy);
+  const policy = decisionPresentation(decision);
+
+  const dialog = (
+    <div
+      className={cx('dcy', 'dcy-backdrop')}
+      style={themeStyle(mergedTheme)}
+      data-dcy-component="risk-details-modal"
+      onClick={(event) => {
+        if (event.target === event.currentTarget) onClose();
+      }}
+    >
+      <StyleGate emit={emitStyles} />
+      <div
+        ref={dialogRef}
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby={titleId}
+        tabIndex={-1}
+        className={cx('dcy-modal', className)}
+        style={style}
+        data-dcy-level={assessment.riskLevel}
+        data-dcy-tone={level.tone}
+      >
+        <div className="dcy-modal-head">
+          <h2 className="dcy-title" id={titleId}>{copy.detailsTitle}</h2>
+          <button type="button" className="dcy-btn" onClick={onClose}>{copy.close}</button>
+        </div>
+
+        <div className="dcy-head">
+          <div className="dcy-head-main">
+            <h3 className="dcy-title">{level.label}</h3>
+            <p className="dcy-meaning">{level.meaning}</p>
+          </div>
+          <LevelBadge level={level} />
+        </div>
+
+        <dl className="dcy-kv">
+          <dt>Subject</dt>
+          <dd><Mono>{subject.identifier}</Mono></dd>
+          <dt>Chain</dt>
+          <dd>{subject.chain}</dd>
+          <dt>Kind</dt>
+          <dd>{subject.kind}</dd>
+          <dt>{copy.confidenceLabel}</dt>
+          <dd>{formatConfidence(assessment.confidence)} — {copy.confidenceCaveat}</dd>
+          <dt>{copy.modelLabel}</dt>
+          <dd><Mono>{assessment.modelVersion}</Mono></dd>
+          <dt>{copy.assessedLabel}</dt>
+          <dd>{formatTimestamp(assessment.assessedAt)}</dd>
+        </dl>
+
+        <AvailabilityNote assessment={assessment} />
+
+        <Section title="Why this level">
+          <ExplanationList explanation={assessment.explanation} />
+        </Section>
+
+        {sections.isEmpty ? <EmptyNote>{sections.emptyStatement}</EmptyNote> : null}
+
+        <Section title={copy.signalsHeading}>
+          <SignalList
+            signals={[...sections.activeSignals, ...sections.inertSignals]}
+            copy={copy}
+            subjectNoun={subjectNoun}
+            showEvidence
+          />
+        </Section>
+
+        <Section title={copy.capabilitiesHeading} note={copy.capabilitiesAreNotFindings}>
+          {sections.capabilities.length === 0 ? (
+            <EmptyNote>{copy.noCapabilities}</EmptyNote>
+          ) : (
+            <ul className="dcy-list">
+              {sections.capabilities.map((capability, index) => (
+                <CapabilityRow key={`${capability.type}:${index}`} capability={capability} copy={copy} />
+              ))}
+            </ul>
+          )}
+        </Section>
+
+        <Section title={copy.factsHeading} note={copy.factsAreNotFindings}>
+          {sections.facts.length === 0 ? (
+            <EmptyNote>{copy.noFacts}</EmptyNote>
+          ) : (
+            <ul className="dcy-list">
+              {sections.facts.map((fact, index) => (
+                <FactRow key={`${fact.type}:${index}`} fact={fact} copy={copy} />
+              ))}
+            </ul>
+          )}
+        </Section>
+
+        <Section title={copy.unknownsHeading} note={copy.unknownsAreNotRisk}>
+          {sections.unknowns.length === 0 ? (
+            <EmptyNote>{copy.noUnknowns}</EmptyNote>
+          ) : (
+            <ul className="dcy-list">
+              {sections.unknowns.map((unknown) => (
+                <UnknownRow key={unknown.field} unknown={unknown} copy={copy} />
+              ))}
+            </ul>
+          )}
+        </Section>
+
+        <Section title={copy.historyHeading}>
+          <HistoryNote status={assessment.historyStatus} copy={copy} />
+        </Section>
+
+        <Section title={copy.componentsHeading}>
+          <dl className="dcy-kv">
+            {componentRows(assessment.components, copy).map((row) => (
+              <ComponentEntry key={row.key} label={row.label} value={row.value} caveat={row.caveat} />
+            ))}
+          </dl>
+        </Section>
+
+        <DemotedNote demotedSignals={demotedSignals} copy={copy} />
+
+        <hr className="dcy-hr" />
+
+        <p className="dcy-note" data-dcy-decision={policy.action}>
+          <span className="dcy-chip">{policy.label}</span> {policy.statement} {copy.policyIsYours}
+        </p>
+
+        {cached ? <p className="dcy-note">{copy.cachedNotice}</p> : null}
+      </div>
+    </div>
+  );
+
+  if (portal && typeof document !== 'undefined') {
+    return createPortal(dialog, document.body);
+  }
+  return dialog;
+}
+
+function ComponentEntry({
+  label, value, caveat,
+}: { label: string; value: number; caveat?: string }): ReactNode {
+  return (
+    <>
+      <dt>{label}</dt>
+      <dd>
+        {Math.round(value)} / 100
+        {caveat ? <span className="dcy-note"> {caveat}</span> : null}
+      </dd>
+    </>
+  );
+}

package/src/components/ThreatSignalList.tsx

@@ -0,0 +1,76 @@
+/**
+ * Threat signals, with the reasons they do or do not count.
+ *
+ * Everything a signal carries is rendered: severity, confidence as a
+ * percentage rather than a word, hop distance as a sentence, status, and the
+ * evidence with its source and whether an analyst confirmed it. That is the
+ * "users should be shown why" half of the rule, and it is also what keeps the
+ * accusation honest — a claim rendered without its evidence is just a score.
+ *
+ * A signal that did not raise the level is still listed, and toned `inactive`
+ * with the reason attached. Dropping it would hide an observation; colouring
+ * it like one that counted would misstate the assessment.
+ */
+
+import { useState, type ReactNode } from 'react';
+import type { ThreatSignal } from '@decentrys/protect';
+import { useUiConfig } from '../context';
+import { themeStyle } from '../theme';
+import { type CommonProps, EmptyNote, Section, SignalList, StyleGate, cx } from '../primitives';
+
+export interface ThreatSignalListProps extends CommonProps {
+  signals: ThreatSignal[];
+  /** Used in hop wording: "an inference about a counterparty of this token". */
+  subjectNoun?: string;
+  /** Start with the evidence expanded. */
+  defaultShowEvidence?: boolean;
+  /** Remove the toggle and pin evidence to `defaultShowEvidence`. */
+  showEvidenceToggle?: boolean;
+  title?: string;
+}
+
+export function ThreatSignalList({
+  signals, subjectNoun = 'address', defaultShowEvidence = false, showEvidenceToggle = true, title,
+  className, style, theme, copy: copyOverrides,
+}: ThreatSignalListProps): ReactNode {
+  const { copy, theme: mergedTheme, emitStyles } = useUiConfig({ theme, copy: copyOverrides });
+  const [showEvidence, setShowEvidence] = useState(defaultShowEvidence);
+  const evidenceVisible = showEvidenceToggle ? showEvidence : defaultShowEvidence;
+
+  return (
+    <section
+      className={cx('dcy', 'dcy-card', className)}
+      style={themeStyle(mergedTheme, style)}
+      data-dcy-component="threat-signal-list"
+      data-dcy-signal-count={String(signals.length)}
+      aria-label={title ?? copy.signalsHeading}
+    >
+      <StyleGate emit={emitStyles} />
+      <Section title={title ?? copy.signalsHeading}>
+        {signals.length === 0 ? (
+          <EmptyNote>{copy.noSignals}</EmptyNote>
+        ) : (
+          <SignalList
+            signals={signals}
+            copy={copy}
+            subjectNoun={subjectNoun}
+            showEvidence={evidenceVisible}
+          />
+        )}
+      </Section>
+
+      {signals.length > 0 && showEvidenceToggle ? (
+        <div>
+          <button
+            type="button"
+            className="dcy-btn dcy-btn-quiet"
+            aria-expanded={evidenceVisible}
+            onClick={() => setShowEvidence((value) => !value)}
+          >
+            {evidenceVisible ? copy.hideEvidence : copy.showEvidence}
+          </button>
+        </div>
+      ) : null}
+    </section>
+  );
+}

package/src/components/TokenSecurityPanel.tsx

@@ -0,0 +1,168 @@
+/**
+ * A token, described in full.
+ *
+ * The panel most likely to be embedded on a swap screen, and therefore the one
+ * most under pressure to become a green tick or a red cross. It is neither.
+ * The four buckets stay four buckets — capabilities, facts, threat signals,
+ * unknowns — each with its own heading, its own row shape and its own tone
+ * family, and the coverage figure is labelled as coverage rather than folded
+ * into anything that looks like a score.
+ *
+ * A token deployed this morning by an anonymous team with no audit renders
+ * here as a list of true statements and a `LIMITED` history note in ordinary
+ * body type. That is the whole argument, in one component.
+ */
+
+import { type ReactNode } from 'react';
+import type { ProtectResult } from '@decentrys/protect';
+import { useUiConfig } from '../context';
+import { themeStyle } from '../theme';
+import {
+  AvailabilityNote, CapabilityRow, Chip, type CommonProps, DemotedNote, EmptyNote, ExplanationList,
+  FactRow, HistoryNote, LevelHeader, Mono, Section, SignalList, StyleGate, UnknownRow, cx,
+} from '../primitives';
+import { assessmentSections, componentRows, decisionPresentation, levelPresentation } from '../presentation';
+
+export interface TokenSecurityPanelProps extends CommonProps {
+  result: ProtectResult;
+  /** Shown beside the address when the integrator already knows it. */
+  tokenName?: string;
+  tokenSymbol?: string;
+  onViewDetails?: () => void;
+  /** Hide the numeric components. They are for developers more than users. */
+  showComponents?: boolean;
+}
+
+export function TokenSecurityPanel({
+  result, tokenName, tokenSymbol, onViewDetails, showComponents = true,
+  className, style, theme, copy: copyOverrides, levelLabels,
+}: TokenSecurityPanelProps): ReactNode {
+  const { copy, theme: mergedTheme, emitStyles } = useUiConfig({ theme, copy: copyOverrides });
+  const { assessment, subject, decision, cached, demotedSignals } = result;
+  const level = levelPresentation(assessment.riskLevel, { labels: levelLabels });
+  const sections = assessmentSections(assessment, copy);
+  const policy = decisionPresentation(decision);
+
+  return (
+    <section
+      className={cx('dcy', 'dcy-card', className)}
+      style={themeStyle(mergedTheme, style)}
+      data-dcy-component="token-security-panel"
+      data-dcy-level={assessment.riskLevel}
+      data-dcy-tone={level.tone}
+      aria-label={level.ariaLabel}
+    >
+      <StyleGate emit={emitStyles} />
+
+      <LevelHeader assessment={assessment} copy={copy} levelLabels={levelLabels} />
+
+      <p className="dcy-note">
+        {tokenName || tokenSymbol ? (
+          <>
+            <Chip>{tokenSymbol ?? tokenName}</Chip>{' '}
+            {tokenName && tokenSymbol ? `${tokenName} — ` : null}
+          </>
+        ) : null}
+        <Mono>{subject.identifier}</Mono> on {subject.chain}
+      </p>
+
+      <AvailabilityNote assessment={assessment} />
+
+      <ExplanationList explanation={assessment.explanation} />
+
+      {sections.isEmpty ? <EmptyNote>{sections.emptyStatement}</EmptyNote> : null}
+
+      <Section title={copy.capabilitiesHeading} note={copy.capabilitiesAreNotFindings}>
+        {sections.capabilities.length === 0 ? (
+          <EmptyNote>{copy.noCapabilities}</EmptyNote>
+        ) : (
+          <ul className="dcy-list">
+            {sections.capabilities.map((capability, index) => (
+              <CapabilityRow key={`${capability.type}:${index}`} capability={capability} copy={copy} />
+            ))}
+          </ul>
+        )}
+      </Section>
+
+      <Section title={copy.factsHeading} note={copy.factsAreNotFindings}>
+        {sections.facts.length === 0 ? (
+          <EmptyNote>{copy.noFacts}</EmptyNote>
+        ) : (
+          <ul className="dcy-list">
+            {sections.facts.map((fact, index) => (
+              <FactRow key={`${fact.type}:${index}`} fact={fact} copy={copy} />
+            ))}
+          </ul>
+        )}
+      </Section>
+
+      <Section title={copy.signalsHeading}>
+        <SignalList
+          signals={[...sections.activeSignals, ...sections.inertSignals]}
+          copy={copy}
+          subjectNoun="token"
+        />
+      </Section>
+
+      <Section title={copy.unknownsHeading} note={copy.unknownsAreNotRisk}>
+        {sections.unknowns.length === 0 ? (
+          <EmptyNote>{copy.noUnknowns}</EmptyNote>
+        ) : (
+          <ul className="dcy-list">
+            {sections.unknowns.map((unknown) => (
+              <UnknownRow key={unknown.field} unknown={unknown} copy={copy} />
+            ))}
+          </ul>
+        )}
+      </Section>
+
+      <HistoryNote status={assessment.historyStatus} copy={copy} />
+
+      {showComponents ? (
+        <Section title={copy.componentsHeading}>
+          <dl className="dcy-kv">
+            {componentRows(assessment.components, copy).map((row) => (
+              <ComponentEntry key={row.key} label={row.label} value={row.value} caveat={row.caveat} />
+            ))}
+          </dl>
+        </Section>
+      ) : null}
+
+      <DemotedNote demotedSignals={demotedSignals} copy={copy} />
+
+      <p className="dcy-note" data-dcy-decision={policy.action}>
+        <span className="dcy-chip">{policy.label}</span> {policy.statement}
+      </p>
+
+      {cached ? <p className="dcy-note">{copy.cachedNotice}</p> : null}
+
+      {onViewDetails ? (
+        <div>
+          <button type="button" className="dcy-btn dcy-btn-quiet" onClick={onViewDetails}>
+            {copy.viewDetails}
+          </button>
+        </div>
+      ) : null}
+    </section>
+  );
+}
+
+/**
+ * `historyConfidence` arrives here labelled "Coverage" and carrying its own
+ * caveat, because the one thing that must never happen to it is being read as
+ * a fourth risk number. Low coverage means we know little; it says nothing
+ * about the subject.
+ */
+function ComponentEntry({
+  label, value, caveat,
+}: { label: string; value: number; caveat?: string }): ReactNode {
+  return (
+    <>
+      <dt>{label}</dt>
+      <dd>
+        {Math.round(value)} / 100
+        {caveat ? <span className="dcy-note"> {caveat}</span> : null}
+      </dd>
+    </>
+  );
+}

package/src/components/TransactionRiskBanner.tsx

@@ -0,0 +1,123 @@
+/**
+ * The pre-signature banner.
+ *
+ * This is the component that will be seen the most, on the screen where a
+ * person is about to give away money, so it is also where the model is most
+ * easily betrayed. Three things it deliberately does not do:
+ *
+ *  - It does not render a verdict. The level label and the model's own words
+ *    for what that level means appear together, always, so "Informational"
+ *    never has to be interpreted from a colour.
+ *  - It does not hide what did not count. Signals below the confidence floor,
+ *    stale signals and unknowns are reported with the reason they did not
+ *    affect the assessment. Silence would read as "we checked and found
+ *    nothing", which is a different and stronger claim.
+ *  - It does not disable anything. `actions` is rendered as given; the
+ *    integrator's policy decides what a user may do, and this banner's job
+ *    ends at telling them why.
+ */
+
+import { type ReactNode } from 'react';
+import type { ProtectResult } from '@decentrys/protect';
+import { useUiConfig } from '../context';
+import { themeStyle } from '../theme';
+import {
+  AvailabilityNote, type CommonProps, DemotedNote, EmptyNote, ExplanationList, HistoryNote,
+  LevelHeader, Section, SignalList, StyleGate, UnknownRow, cx,
+} from '../primitives';
+import { assessmentSections, decisionPresentation, levelPresentation, plural } from '../presentation';
+
+export interface TransactionRiskBannerProps extends CommonProps {
+  result: ProtectResult;
+  /** What the subject should be called in hop wording. */
+  subjectNoun?: string;
+  /**
+   * The integrator's own controls. Rendered untouched — this package never
+   * supplies, styles or disables a proceed button.
+   */
+  actions?: ReactNode;
+  onViewDetails?: () => void;
+  /** Inline explanation lines. The rest remain available in the details view. */
+  maxExplanationLines?: number;
+}
+
+export function TransactionRiskBanner({
+  result, subjectNoun = 'transaction', actions, onViewDetails, maxExplanationLines = 4,
+  className, style, theme, copy: copyOverrides, levelLabels,
+}: TransactionRiskBannerProps): ReactNode {
+  const { copy, theme: mergedTheme, emitStyles } = useUiConfig({ theme, copy: copyOverrides });
+  const { assessment, decision, cached, demotedSignals } = result;
+  const level = levelPresentation(assessment.riskLevel, { labels: levelLabels });
+  const sections = assessmentSections(assessment, copy);
+  const policy = decisionPresentation(decision);
+
+  return (
+    <section
+      className={cx('dcy', 'dcy-card', className)}
+      style={themeStyle(mergedTheme, style)}
+      data-dcy-component="transaction-risk-banner"
+      data-dcy-level={assessment.riskLevel}
+      data-dcy-tone={level.tone}
+      /* Only levels the classifier can reach on threat evidence interrupt a
+         screen reader. Nothing at INFORMATIONAL has earned that. */
+      role={level.liveRegionRole}
+      aria-label={level.ariaLabel}
+    >
+      <StyleGate emit={emitStyles} />
+      <LevelHeader assessment={assessment} copy={copy} levelLabels={levelLabels} />
+
+      <AvailabilityNote assessment={assessment} />
+
+      <ExplanationList explanation={assessment.explanation.slice(0, maxExplanationLines)} />
+
+      {sections.isEmpty ? <EmptyNote>{sections.emptyStatement}</EmptyNote> : (
+        <p className="dcy-note" data-dcy-summary="">{sections.summary}</p>
+      )}
+
+      {sections.activeSignals.length > 0 ? (
+        <Section title={copy.signalsHeading}>
+          <SignalList signals={sections.activeSignals} copy={copy} subjectNoun={subjectNoun} />
+        </Section>
+      ) : null}
+
+      {sections.inertSignals.length > 0 ? (
+        <EmptyNote>
+          {sections.inertSignals.length}{' '}
+          {plural(sections.inertSignals.length, 'further signal was', 'further signals were')}{' '}
+          observed and did not affect this assessment. They are listed in full in the details.
+        </EmptyNote>
+      ) : null}
+
+      {sections.unknowns.length > 0 ? (
+        <Section title={copy.unknownsHeading} note={copy.unknownsAreNotRisk}>
+          <ul className="dcy-list">
+            {sections.unknowns.map((unknown) => (
+              <UnknownRow key={unknown.field} unknown={unknown} copy={copy} />
+            ))}
+          </ul>
+        </Section>
+      ) : null}
+
+      <HistoryNote status={assessment.historyStatus} copy={copy} />
+
+      <DemotedNote demotedSignals={demotedSignals} copy={copy} />
+
+      <p className="dcy-note" data-dcy-decision={policy.action}>
+        <span className="dcy-chip">{policy.label}</span> {policy.statement}
+      </p>
+
+      {cached ? <p className="dcy-note">{copy.cachedNotice}</p> : null}
+
+      {onViewDetails || actions ? (
+        <div className="dcy-head">
+          {onViewDetails ? (
+            <button type="button" className="dcy-btn dcy-btn-quiet" onClick={onViewDetails}>
+              {copy.viewDetails}
+            </button>
+          ) : null}
+          {actions}
+        </div>
+      ) : null}
+    </section>
+  );
+}

package/src/context.tsx

@@ -0,0 +1,89 @@
+/**
+ * Shared configuration, and where the stylesheet comes from.
+ *
+ * Every component works standalone — drop `<AddressRiskBadge>` into a page and
+ * it renders correctly with no provider, because it emits the stylesheet
+ * itself. Wrapping a tree in `<DecentrysUiProvider>` does two things: it sets
+ * theme and copy once for everything inside, and it emits the stylesheet a
+ * single time so the components inside stop emitting their own.
+ *
+ * The alternative — a module-level "have I injected yet" flag — is the pattern
+ * that breaks under server rendering and hydration, because the flag is set
+ * during the server pass and the client then renders a tree with no styles in
+ * it. A context read is correct in both passes.
+ */
+
+import { createContext, useContext, type ReactNode } from 'react';
+import { DECENTRYS_UI_CSS } from './styles';
+import { resolveCopy, type UiCopy } from './copy';
+import type { DecentrysTheme } from './theme';
+
+interface UiContextValue {
+  theme?: DecentrysTheme;
+  copy?: Partial<UiCopy>;
+  stylesProvided: boolean;
+}
+
+const UiContext = createContext<UiContextValue | null>(null);
+
+/** The default stylesheet as a `<style>` element. Safe to render more than once. */
+export function DecentrysUiStyles(): ReactNode {
+  return <style data-decentrys-ui="">{DECENTRYS_UI_CSS}</style>;
+}
+
+export interface DecentrysUiProviderProps {
+  /** Token overrides applied to every component beneath. */
+  theme?: DecentrysTheme;
+  /** Copy overrides — including translation — applied to every component beneath. */
+  copy?: Partial<UiCopy>;
+  /**
+   * Set false when placing `DECENTRYS_UI_CSS` yourself, in a `<head>`, a
+   * bundled stylesheet or a shadow root. Components beneath still will not
+   * emit their own, because the provider has taken responsibility for it.
+   */
+  injectStyles?: boolean;
+  children?: ReactNode;
+}
+
+export function DecentrysUiProvider({
+  theme,
+  copy,
+  injectStyles = true,
+  children,
+}: DecentrysUiProviderProps): ReactNode {
+  return (
+    <UiContext.Provider value={{ theme, copy, stylesProvided: true }}>
+      {injectStyles ? <DecentrysUiStyles /> : null}
+      {children}
+    </UiContext.Provider>
+  );
+}
+
+export interface UiConfigInput {
+  theme?: DecentrysTheme;
+  copy?: Partial<UiCopy>;
+}
+
+export interface ResolvedUiConfig {
+  theme?: DecentrysTheme;
+  copy: UiCopy;
+  /** True when this component must emit the stylesheet itself. */
+  emitStyles: boolean;
+}
+
+/**
+ * Merge provider configuration with a component's own props.
+ *
+ * The component's props win, so a single banner can be re-themed inside an
+ * otherwise uniform tree without unpicking the provider.
+ */
+export function useUiConfig(local: UiConfigInput = {}): ResolvedUiConfig {
+  const ctx = useContext(UiContext);
+  const theme =
+    ctx?.theme || local.theme ? { ...(ctx?.theme ?? {}), ...(local.theme ?? {}) } : undefined;
+  return {
+    theme,
+    copy: resolveCopy({ ...(ctx?.copy ?? {}), ...(local.copy ?? {}) }),
+    emitStyles: !ctx?.stylesProvided,
+  };
+}