@xemahq/ui-kernel 0.1.6 → 0.1.8

package/src/lib/biome-host/host-bridge.ts

@@ -58,6 +58,28 @@ export interface HostBridgeAuth {
   getProjectId(): string | null;
   /** Returns the current actor's user id (subject), or null. */
   getUserId(): string | null;
+  /**
+   * Proactively refresh the actor token if it is within `minValiditySeconds`
+   * of expiry, then return a guaranteed-valid bearer. The refresh + any
+   * redirect-on-failure stays HOST-owned (the host owns the auth client and
+   * the single-flight login guard) — biomes only reach it through this method
+   * so an Orval client's `getAuthToken` can be wired against the SAME refresh
+   * path the host uses, instead of each biome re-implementing token freshness.
+   *
+   * @param minValiditySeconds Refresh when fewer than this many seconds of
+   *   validity remain. Defaults to a host-chosen safe window.
+   * @returns A valid bearer token string. Implementations that cannot produce
+   *   one (session expired) trigger the host login redirect and reject.
+   */
+  ensureFreshToken(minValiditySeconds?: number): Promise<string>;
+  /**
+   * Handle a 401 from a downstream API call: force-refresh the token and, if
+   * that fails, redirect to login. HOST-owned for the same reason as
+   * {@link HostBridgeAuth.ensureFreshToken} — there is ONE login-redirect
+   * single-flight guard and one refresh-dedup path in the host; biomes funnel
+   * 401 recovery through here rather than forking that logic.
+   */
+  onUnauthorized(): Promise<void>;
 }
 
 export interface HostBridgeToast {

package/src/lib/biome-host/host-sources.ts

@@ -25,6 +25,19 @@ export interface AuthSource {
   getProjectId(): string | null;
   /** Subject (user) id of the actor, or null when unauthenticated. */
   getUserId(): string | null;
+  /**
+   * Proactively refresh the token if it is within `minValiditySeconds` of
+   * expiry and return a valid bearer. Backed by the host's auth client
+   * (keycloak-js `updateToken`, …) and its single-flight login redirect.
+   * Mirrors {@link HostBridgeAuth.ensureFreshToken} — the bridge delegates
+   * straight through to this source.
+   */
+  ensureFreshToken(minValiditySeconds?: number): Promise<string>;
+  /**
+   * Force-refresh on a 401 and redirect to login on failure. Backed by the
+   * host's auth-guard. Mirrors {@link HostBridgeAuth.onUnauthorized}.
+   */
+  onUnauthorized(): Promise<void>;
 }
 
 /**

package/src/lib/biome-host/index.ts

@@ -14,10 +14,11 @@
  */
 export * from './frontend-biome';
 export * from './host-bridge';
+export * from './create-biome-orval-config';
 export * from './biome-registry';
 export * from './session-contributions';
 export * from './session-profiles';
 export * from './host-sources';
 export * from './nav';
 export * from './biome-mode';
-export * from './composition-validation';
+export * from './agent-validation';

package/src/registry/index.ts

@@ -1,5 +1,5 @@
 export * from './lib/extension-points';
-export * from './lib/composition-validation-host';
+export * from './lib/agent-validation-host';
 export * from './lib/biome-slot';
 export * from './lib/biomes-enabled-context';
 export * from './lib/session-selectors';

package/src/registry/lib/extension-points.ts

@@ -18,7 +18,7 @@
  *      readable via the host bridge's location").
  *   2. Mount `<BiomeSlot name={HostExtensionSlots.X} />` in the host
  *      page.
- *   3. Document the slot in `data/docs/public/biomes/04-frontend-extensions.md`.
+ *   3. Document the slot in the xema-docs repo (`content/biomes/04-frontend-extensions.md`).
  *
  * Removing a host slot is a breaking change — bump the kernel package
  * major version.

package/src/session-kit/approvals/ApprovalButton.tsx

@@ -0,0 +1,89 @@
+/**
+ * Minimal action button used by the approval surfaces (card / sticky bar /
+ * Center). The kit carries no button primitive, so this is a small,
+ * inline-styled control matching the design's `Btn` (ghost / soft /
+ * primary, with an optional accent override for critical-tier approve).
+ *
+ * Kept inside the approvals folder because it is only the approval
+ * actions — it is NOT a general-purpose kit button.
+ */
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+
+export type ApprovalButtonVariant = 'ghost' | 'soft' | 'primary';
+export type ApprovalButtonSize = 'xs' | 'sm';
+
+export interface ApprovalButtonProps {
+  readonly variant?: ApprovalButtonVariant;
+  readonly size?: ApprovalButtonSize;
+  /** Accent for the `primary` variant background (e.g. portal/risk accent). */
+  readonly accent?: string;
+  readonly icon?: ReactNode;
+  readonly disabled?: boolean;
+  readonly onClick?: () => void;
+  readonly children: ReactNode;
+}
+
+const PAD: Record<ApprovalButtonSize, string> = {
+  xs: '3px 9px',
+  sm: '5px 11px',
+};
+
+const FONT: Record<ApprovalButtonSize, number> = { xs: 12, sm: 12.5 };
+
+export function ApprovalButton({
+  variant = 'ghost',
+  size = 'sm',
+  accent = 'hsl(var(--primary))',
+  icon,
+  disabled = false,
+  onClick,
+  children,
+}: ApprovalButtonProps): ReactElement {
+  const base: CSSProperties = {
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: 5,
+    padding: PAD[size],
+    fontSize: FONT[size],
+    fontWeight: 550,
+    borderRadius: 7,
+    cursor: disabled ? 'not-allowed' : 'pointer',
+    opacity: disabled ? 0.5 : 1,
+    whiteSpace: 'nowrap',
+    lineHeight: 1.2,
+  };
+  const variantStyle = resolveVariantStyle(variant, accent);
+  return (
+    <button
+      type="button"
+      disabled={disabled}
+      onClick={onClick}
+      style={{ ...base, ...variantStyle }}
+    >
+      {icon}
+      {children}
+    </button>
+  );
+}
+
+function resolveVariantStyle(
+  variant: ApprovalButtonVariant,
+  accent: string,
+): CSSProperties {
+  switch (variant) {
+    case 'primary':
+      return { background: accent, color: '#fff', border: '1px solid transparent' };
+    case 'soft':
+      return {
+        background: 'hsl(var(--muted))',
+        color: 'hsl(var(--ink))',
+        border: '1px solid hsl(var(--rule))',
+      };
+    case 'ghost':
+      return {
+        background: 'transparent',
+        color: 'hsl(var(--ink-2))',
+        border: '1px solid transparent',
+      };
+  }
+}

package/src/session-kit/approvals/ApprovalCard.tsx

@@ -0,0 +1,336 @@
+/**
+ * The GENERIC approval frame (HANDOFF §6) — identical platform-wide.
+ *
+ * Header: "Approval required" + RiskPill (reused from the kit) + mono
+ * capability ref + serif title + summary. Then the biome-supplied
+ * `ScopedBody`. Then obligations chips (closed `PolicyObligationKind`
+ * taxonomy), approver role, and quorum dots. Actions: Deny / Allow once /
+ * Approve — low risk gets "Approve & remember"; high & critical are
+ * explicit Approve only (no allow-once-remember). The accent rail uses the
+ * SAME risk→colour mapping as the pill.
+ *
+ * Resolved state collapses to a compact confirmation row; a
+ * quorum-approved request reads "approved · waiting on N more approver".
+ *
+ * Controlled OR uncontrolled: pass `decision` to control the resolved
+ * state from the host (the real flow), or omit it and the card tracks its
+ * own optimistic resolved state. `onResolve(decision, request)` always
+ * fires.
+ */
+import { useState, type ReactElement } from 'react';
+
+import {
+  ApprovalDecision,
+  isExplicitApprovalTier,
+  isQuorum,
+  type ApprovalRequest,
+} from './approval-model';
+import { ApprovalButton } from './ApprovalButton';
+import { Obligation, QuorumDots } from './Obligation';
+import { RISK_ACCENT } from './risk-accent';
+import { ScopedBody } from './ScopedBody';
+import { RiskPill } from '../primitives/RiskPill';
+
+import type { ApprovalIcons } from './approval-icons';
+
+export interface ApprovalCardProps {
+  readonly request: ApprovalRequest;
+  readonly icons: ApprovalIcons;
+  /** Resolution callback. Fires before/after the host updates `decision`. */
+  readonly onResolve: (
+    decision: ApprovalDecision,
+    request: ApprovalRequest,
+  ) => void;
+  /**
+   * Controlled resolved state. Omit for uncontrolled (the card collapses
+   * optimistically on click). The real host flow passes the server-known
+   * decision so the collapse reflects committed state.
+   */
+  readonly decision?: ApprovalDecision | null;
+  /** Portal/brand accent for the (non-critical) primary approve button. */
+  readonly accent?: string;
+}
+
+export function ApprovalCard({
+  request,
+  icons,
+  onResolve,
+  decision,
+  accent = 'hsl(var(--primary))',
+}: ApprovalCardProps): ReactElement {
+  const [localDecision, setLocalDecision] = useState<ApprovalDecision | null>(
+    null,
+  );
+  const resolved = decision ?? localDecision;
+  const r = RISK_ACCENT[request.riskTier];
+  const explicit = isExplicitApprovalTier(request.riskTier);
+  const quorum = isQuorum(request);
+  const approveLabel = resolveApproveLabel(request, quorum, explicit);
+
+  function resolve(d: ApprovalDecision): void {
+    if (decision === undefined) setLocalDecision(d);
+    onResolve(d, request);
+  }
+
+  if (resolved) {
+    const approved = resolved === ApprovalDecision.Approved;
+    const remaining =
+      (request.requireApproverCount ?? 1) - ((request.approvalsIn ?? 0) + 1);
+    const approvedLabel =
+      quorum && remaining > 0
+        ? `approved · waiting on ${remaining} more approver${remaining === 1 ? '' : 's'}`
+        : 'approved, capability resumed';
+    return (
+      <div
+        style={{
+          marginTop: 9,
+          display: 'flex',
+          alignItems: 'center',
+          gap: 10,
+          padding: '11px 14px',
+          borderRadius: 11,
+          border: `1px solid ${
+            approved ? 'hsl(var(--success) / 0.3)' : 'hsl(var(--rule))'
+          }`,
+          background: approved
+            ? 'hsl(var(--success) / 0.06)'
+            : 'hsl(var(--muted))',
+        }}
+      >
+        <span
+          style={{
+            color: approved ? 'hsl(var(--success))' : 'hsl(var(--ink-3))',
+            display: 'inline-flex',
+          }}
+        >
+          {approved ? icons.approved(17) : icons.denied(17)}
+        </span>
+        <span style={{ fontSize: 13, color: 'hsl(var(--ink-2))' }}>
+          <strong style={{ color: 'hsl(var(--ink))', fontWeight: 600 }}>
+            {request.title}
+          </strong>{' '}
+          — {approved ? approvedLabel : 'denied'}
+        </span>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      style={{
+        marginTop: 9,
+        borderRadius: 12,
+        overflow: 'hidden',
+        border: `1px solid ${explicit ? r.bd : 'hsl(var(--rule-2))'}`,
+        boxShadow: 'var(--shadow-2)',
+        background: 'hsl(var(--paper-elev))',
+      }}
+    >
+      <div style={{ display: 'flex' }}>
+        {/* accent rail — same risk→colour mapping as the pill */}
+        <div
+          style={{
+            width: 3,
+            flexShrink: 0,
+            background: explicit ? r.fg : 'hsl(var(--rule-2))',
+          }}
+        />
+        <div style={{ flex: 1, minWidth: 0 }}>
+          {/* header — generic */}
+          <div
+            style={{
+              padding: '11px 14px 9px',
+              borderBottom: '1px solid hsl(var(--rule))',
+            }}
+          >
+            <div
+              style={{
+                display: 'flex',
+                alignItems: 'center',
+                gap: 8,
+                marginBottom: 6,
+              }}
+            >
+              <span
+                style={{
+                  color: explicit ? r.fg : 'hsl(var(--primary))',
+                  display: 'inline-flex',
+                }}
+              >
+                {icons.shield(16)}
+              </span>
+              <span
+                className="cap"
+                style={{ color: 'hsl(var(--ink-3))', letterSpacing: '0.1em' }}
+              >
+                Approval required
+              </span>
+              <RiskPill tier={request.riskTier} size="xs" />
+              <span style={{ flex: 1 }} />
+              <span
+                className="mono"
+                style={{
+                  fontSize: 10.5,
+                  color: 'hsl(var(--ink-4))',
+                  display: 'inline-flex',
+                  alignItems: 'center',
+                  gap: 4,
+                  overflow: 'hidden',
+                  textOverflow: 'ellipsis',
+                  whiteSpace: 'nowrap',
+                  maxWidth: '50%',
+                }}
+              >
+                {icons.capability(11)}
+                {request.capability}
+              </span>
+            </div>
+            <div
+              className="serif"
+              style={{
+                fontSize: 15,
+                fontWeight: 600,
+                color: 'hsl(var(--ink))',
+                lineHeight: 1.3,
+              }}
+            >
+              {request.title}
+            </div>
+            <div
+              style={{
+                fontSize: 12.5,
+                color: 'hsl(var(--ink-3))',
+                marginTop: 2,
+              }}
+            >
+              {request.summary}
+            </div>
+          </div>
+
+          {/* SCOPED biome body */}
+          <div
+            style={{ padding: '10px 14px', background: 'hsl(var(--paper) / 0.5)' }}
+          >
+            <div
+              style={{
+                display: 'flex',
+                alignItems: 'center',
+                gap: 6,
+                marginBottom: 8,
+              }}
+            >
+              <span
+                className="cap"
+                style={{ fontSize: 9.5, color: 'hsl(var(--ink-4))' }}
+              >
+                Details from {request.biomeName}
+              </span>
+              <span
+                style={{ flex: 1, height: 1, background: 'hsl(var(--rule))' }}
+              />
+            </div>
+            <ScopedBody scope={request.scope} renderIcon={icons.scope} />
+          </div>
+
+          {/* obligations + approver requirement — generic */}
+          <div
+            style={{
+              padding: '10px 14px',
+              borderTop: '1px solid hsl(var(--rule))',
+              display: 'flex',
+              flexDirection: 'column',
+              gap: 9,
+            }}
+          >
+            {request.obligations && request.obligations.length > 0 && (
+              <div style={{ display: 'flex', flexWrap: 'wrap', gap: 6 }}>
+                {request.obligations.map((o) => (
+                  <Obligation
+                    key={o.kind}
+                    obligation={o}
+                    renderIcon={icons.obligation}
+                  />
+                ))}
+              </div>
+            )}
+            <div
+              style={{
+                display: 'flex',
+                alignItems: 'center',
+                gap: 10,
+                flexWrap: 'wrap',
+              }}
+            >
+              {request.requireRole && (
+                <span
+                  style={{
+                    display: 'inline-flex',
+                    alignItems: 'center',
+                    gap: 5,
+                    fontSize: 12,
+                    color: 'hsl(var(--ink-3))',
+                  }}
+                >
+                  {icons.user(13)}approver role{' '}
+                  <span className="mono" style={{ color: 'hsl(var(--ink-2))' }}>
+                    {request.requireRole}
+                  </span>
+                </span>
+              )}
+              {quorum && (
+                <QuorumDots
+                  have={request.approvalsIn ?? 0}
+                  need={request.requireApproverCount ?? 1}
+                  usersIcon={icons.users(13)}
+                />
+              )}
+              <span style={{ flex: 1 }} />
+              <ApprovalButton
+                variant="ghost"
+                size="sm"
+                onClick={() => resolve(ApprovalDecision.Denied)}
+              >
+                Deny
+              </ApprovalButton>
+              {!explicit && (
+                <ApprovalButton
+                  variant="soft"
+                  size="sm"
+                  icon={icons.check(13)}
+                  onClick={() => resolve(ApprovalDecision.Approved)}
+                >
+                  Allow once
+                </ApprovalButton>
+              )}
+              <ApprovalButton
+                variant="primary"
+                size="sm"
+                icon={icons.shield(13)}
+                accent={explicit ? r.fg : accent}
+                onClick={() => resolve(ApprovalDecision.Approved)}
+              >
+                {approveLabel}
+              </ApprovalButton>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * The primary-button label: a quorum step ("Approve (1 of 2)"), a plain
+ * "Approve" for explicit (high/critical) tiers, or "Approve & remember"
+ * for low/medium where allow-once-remember is offered.
+ */
+function resolveApproveLabel(
+  request: ApprovalRequest,
+  quorum: boolean,
+  explicit: boolean,
+): string {
+  if (quorum) {
+    return `Approve (${(request.approvalsIn ?? 0) + 1} of ${request.requireApproverCount})`;
+  }
+  return explicit ? 'Approve' : 'Approve & remember';
+}