@polderlabs/bizar 7.0.4 → 8.1.0

package/bizar-dash/src/web/v8/ui/agents/AgentStreamPanel.tsx

@@ -0,0 +1,371 @@
+import { useEffect, useRef, useState } from 'react';
+import { Terminal, RefreshCw, Loader2, AlertTriangle } from 'lucide-react';
+import { fetchJson, FetchError } from '../../data/fetcher.js';
+import { Box } from '../primitives/Box.js';
+import { Inline } from '../primitives/Inline.js';
+import { cx } from '../utils/cx.js';
+
+/**
+ * AgentStreamPanel — Sprint S15. Live CC agent output stream.
+ *
+ * Backed by:
+ *   - GET  /api/agent-stream/recent — initial buffered last-N events.
+ *   - GET  /api/agent-stream/live   — Server-Sent Events tail.
+ *
+ * Auto-reconnects with exponential backoff when the SSE stream drops.
+ * Renders role-tinted text + tool calls. Auto-scrolls to the newest event
+ * unless the user has scrolled up (then leaves them alone).
+ */
+
+export interface AgentStreamPanelProps {
+  sessionId: string;
+  /** Cap on how many events to keep in memory. Default 500. */
+  maxEvents?: number;
+  /** Optional className. */
+  className?: string;
+  /** Polished / verbose rendering (used by Drawer vs inline panel). */
+  density?: 'compact' | 'detailed';
+}
+
+export interface StreamEvent {
+  ts: number;
+  kind: 'text' | 'tool' | 'tool-result' | 'system';
+  role?: string;
+  content?: string;
+  toolName?: string;
+  toolInput?: string;
+  isError?: boolean;
+}
+
+const ROLE_TONE: Record<string, string> = {
+  user: 'var(--accent)',
+  assistant: 'var(--info)',
+  system: 'var(--warning)',
+};
+
+function timeShort(ts: number): string {
+  const d = new Date(ts);
+  return d.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit', second: '2-digit' });
+}
+
+export function AgentStreamPanel({
+  sessionId,
+  maxEvents = 500,
+  className,
+  density = 'detailed',
+}: AgentStreamPanelProps): JSX.Element {
+  const [events, setEvents] = useState<StreamEvent[]>([]);
+  const [status, setStatus] = useState<'idle' | 'loading' | 'live' | 'error' | 'ended'>('idle');
+  const [errorMsg, setErrorMsg] = useState<string | null>(null);
+  const bodyRef = useRef<HTMLDivElement>(null);
+  const pinnedBottomRef = useRef<boolean>(true);
+  const esRef = useRef<EventSource | null>(null);
+  const reconnectAttemptRef = useRef<number>(0);
+
+  // Track whether the user is scrolled away from the bottom; if so,
+  // don't yank them back when new events arrive.
+  const onScroll = (): void => {
+    const el = bodyRef.current;
+    if (!el) return;
+    const distance = el.scrollHeight - el.scrollTop - el.clientHeight;
+    pinnedBottomRef.current = distance < 24;
+  };
+
+  useEffect(() => {
+    if (!sessionId) return undefined;
+
+    let cancelled = false;
+    setStatus('loading');
+    setErrorMsg(null);
+
+    // 1) Hydrate with the buffered snapshot so the UI is non-empty while
+    //    the SSE connection negotiates.
+    (async () => {
+      try {
+        const r = await fetchJson<{ events?: StreamEvent[] }>(
+          `/api/agent-stream/recent?sessionId=${encodeURIComponent(sessionId)}&limit=100`,
+        );
+        if (cancelled) return;
+        setEvents(Array.isArray(r.events) ? r.events : []);
+      } catch (err) {
+        if (cancelled) return;
+        setErrorMsg(err instanceof FetchError ? err.message : (err as Error).message);
+      }
+    })();
+
+    // 2) Open SSE stream. Auto-reconnect with backoff on disconnect.
+    const openStream = (): void => {
+      if (cancelled) return;
+      const es = new EventSource(`/api/agent-stream/live?sessionId=${encodeURIComponent(sessionId)}`);
+      esRef.current = es;
+
+      es.addEventListener('snapshot', (e) => {
+        try {
+          const data = JSON.parse((e as MessageEvent).data) as { events: StreamEvent[] };
+          setEvents((prev) => mergeEvents(prev, data.events ?? [], maxEvents));
+        } catch { /* ignore */ }
+      });
+      es.addEventListener('append', (e) => {
+        try {
+          const data = JSON.parse((e as MessageEvent).data) as { events: StreamEvent[] };
+          setEvents((prev) => mergeEvents(prev, data.events ?? [], maxEvents));
+        } catch { /* ignore */ }
+      });
+      es.addEventListener('agent', () => {
+        setStatus('live');
+        reconnectAttemptRef.current = 0;
+      });
+      es.addEventListener('end', () => {
+        setStatus('ended');
+        es.close();
+      });
+      es.addEventListener('error', (e) => {
+        if (cancelled) return;
+        setStatus('error');
+        setErrorMsg((e as MessageEvent).data || 'stream error');
+        es.close();
+        const delay = Math.min(15_000, 500 * 2 ** reconnectAttemptRef.current);
+        reconnectAttemptRef.current += 1;
+        setTimeout(() => { if (!cancelled) openStream(); }, delay);
+      });
+    };
+
+    openStream();
+
+    return () => {
+      cancelled = true;
+      esRef.current?.close();
+      esRef.current = null;
+    };
+  }, [sessionId, maxEvents]);
+
+  // Auto-scroll on new events if the user is pinned to the bottom.
+  useEffect(() => {
+    const el = bodyRef.current;
+    if (!el) return;
+    if (pinnedBottomRef.current) {
+      el.scrollTop = el.scrollHeight;
+    }
+  }, [events.length]);
+
+  const refresh = (): void => {
+    setEvents([]);
+    setStatus('loading');
+    setErrorMsg(null);
+    esRef.current?.close();
+    reconnectAttemptRef.current = 0;
+    // The effect dependency array won't pick this up; force re-mount via key
+    // would be heavier. The open call inside the effect's reconnect handles it.
+    const es = new EventSource(`/api/agent-stream/live?sessionId=${encodeURIComponent(sessionId)}`);
+    esRef.current = es;
+    es.addEventListener('snapshot', (e) => {
+      try {
+        const data = JSON.parse((e as MessageEvent).data) as { events: StreamEvent[] };
+        setEvents((prev) => mergeEvents(prev, data.events ?? [], maxEvents));
+      } catch { /* ignore */ }
+    });
+    es.addEventListener('append', (e) => {
+      try {
+        const data = JSON.parse((e as MessageEvent).data) as { events: StreamEvent[] };
+        setEvents((prev) => mergeEvents(prev, data.events ?? [], maxEvents));
+      } catch { /* ignore */ }
+    });
+    es.addEventListener('agent', () => setStatus('live'));
+    es.addEventListener('error', () => setStatus('error'));
+  };
+
+  return (
+    <Box
+      className={cx('v8-agent-stream', className)}
+      style={{
+        background: 'var(--surface-0)',
+        border: '1px solid var(--border)',
+        borderRadius: 'var(--radius-md)',
+        overflow: 'hidden',
+        display: 'flex',
+        flexDirection: 'column',
+        height: density === 'compact' ? 220 : 360,
+      }}
+    >
+      <Inline
+        align="center"
+        justify="space-between"
+        style={{
+          padding: 'var(--space-2) var(--space-3)',
+          borderBottom: '1px solid var(--border)',
+          background: 'var(--surface-1)',
+          fontSize: 'var(--fs-12)',
+          color: 'var(--fg-muted)',
+        }}
+      >
+        <Inline align="center" gap={2}>
+          <Terminal size={12} aria-hidden />
+          <span style={{ fontFamily: 'var(--font-mono)' }}>{sessionId.slice(0, 12)}…</span>
+          <StatusPill status={status} />
+        </Inline>
+        <button
+          type="button"
+          onClick={refresh}
+          aria-label="Refresh stream"
+          title="Refresh"
+          style={{
+            display: 'inline-flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            width: 24,
+            height: 24,
+            borderRadius: 'var(--radius-sm)',
+            background: 'transparent',
+            border: '1px solid var(--border)',
+            color: 'var(--fg-muted)',
+            cursor: 'pointer',
+          }}
+        >
+          <RefreshCw size={12} aria-hidden />
+        </button>
+      </Inline>
+      <div
+        ref={bodyRef}
+        onScroll={onScroll}
+        className="v8-agent-stream__body"
+        style={{
+          flex: 1,
+          minHeight: 0,
+          overflowY: 'auto',
+          padding: 'var(--space-2)',
+          fontFamily: 'var(--font-mono)',
+          fontSize: 'var(--fs-12)',
+          lineHeight: 'var(--lh-snug)',
+        }}
+      >
+        {events.length === 0 && status === 'loading' && (
+          <Inline align="center" gap={2} style={{ color: 'var(--fg-muted)', padding: 'var(--space-2)' }}>
+            <Loader2 size={12} aria-hidden /> Loading stream…
+          </Inline>
+        )}
+        {events.length === 0 && status !== 'loading' && (
+          <Box style={{ padding: 'var(--space-3)', color: 'var(--fg-muted)' }}>
+            No events yet for this session.
+          </Box>
+        )}
+        {errorMsg !== null && (
+          <Inline align="center" gap={2} style={{ color: 'var(--warning)', padding: 'var(--space-2)' }}>
+            <AlertTriangle size={12} aria-hidden /> {errorMsg}
+          </Inline>
+        )}
+        {events.map((ev, i) => (
+          <StreamEventRow key={`${ev.ts}-${i}`} event={ev} density={density} />
+        ))}
+      </div>
+    </Box>
+  );
+}
+
+function StatusPill({ status }: { status: 'idle' | 'loading' | 'live' | 'error' | 'ended' }): JSX.Element {
+  const cfg = {
+    idle: { label: 'idle', tone: 'var(--fg-subtle)' },
+    loading: { label: 'connecting', tone: 'var(--info)' },
+    live: { label: 'live', tone: 'var(--success)' },
+    error: { label: 'reconnecting', tone: 'var(--warning)' },
+    ended: { label: 'ended', tone: 'var(--fg-muted)' },
+  }[status];
+  return (
+    <Inline align="center" gap={2} style={{ color: cfg.tone }}>
+      <span
+        aria-hidden
+        style={{
+          width: 6,
+          height: 6,
+          borderRadius: 'var(--radius-pill)',
+          background: cfg.tone,
+          boxShadow: status === 'live' ? `0 0 0 0 ${cfg.tone}` : 'none',
+          animation: status === 'live' ? 'v8-pulse 1.5s ease-out infinite' : 'none',
+        }}
+      />
+      {cfg.label}
+    </Inline>
+  );
+}
+
+function StreamEventRow({
+  event,
+  density,
+}: {
+  event: StreamEvent;
+  density: 'compact' | 'detailed';
+}): JSX.Element {
+  const roleColor = ROLE_TONE[event.role ?? 'system'] ?? 'var(--fg-muted)';
+  const ts = timeShort(event.ts);
+  if (event.kind === 'tool') {
+    return (
+      <Box style={{ padding: '4px 8px', borderLeft: `2px solid ${roleColor}` }}>
+        <Inline align="center" gap={2}>
+          <span style={{ color: 'var(--fg-subtle)' }}>{ts}</span>
+          <span style={{ color: roleColor, fontWeight: 600 }}>tool</span>
+          <span style={{ color: 'var(--accent)' }}>{event.toolName}</span>
+        </Inline>
+        {density === 'detailed' && event.toolInput && (
+          <Box style={{ color: 'var(--fg-muted)', marginTop: 2, paddingLeft: 12, whiteSpace: 'pre-wrap', wordBreak: 'break-word' }}>
+            {truncate(event.toolInput, 400)}
+          </Box>
+        )}
+      </Box>
+    );
+  }
+  if (event.kind === 'tool-result') {
+    return (
+      <Box style={{ padding: '4px 8px', borderLeft: `2px solid ${event.isError ? 'var(--danger)' : 'var(--success)'}` }}>
+        <Inline align="center" gap={2}>
+          <span style={{ color: 'var(--fg-subtle)' }}>{ts}</span>
+          <span style={{ color: event.isError ? 'var(--danger)' : 'var(--success)', fontWeight: 600 }}>
+            {event.isError ? 'tool-error' : 'result'}
+          </span>
+        </Inline>
+        {density === 'detailed' && event.content && (
+          <Box style={{ color: 'var(--fg-muted)', marginTop: 2, paddingLeft: 12, whiteSpace: 'pre-wrap', wordBreak: 'break-word' }}>
+            {truncate(event.content, 400)}
+          </Box>
+        )}
+      </Box>
+    );
+  }
+  if (event.kind === 'system') {
+    return (
+      <Box style={{ padding: '4px 8px', borderLeft: '2px solid var(--warning)' }}>
+        <Inline align="center" gap={2}>
+          <span style={{ color: 'var(--fg-subtle)' }}>{ts}</span>
+          <span style={{ color: 'var(--warning)', fontWeight: 600 }}>system</span>
+        </Inline>
+        {event.content && (
+          <Box style={{ color: 'var(--fg-muted)', marginTop: 2, paddingLeft: 12, whiteSpace: 'pre-wrap' }}>
+            {truncate(event.content, 200)}
+          </Box>
+        )}
+      </Box>
+    );
+  }
+  return (
+    <Box style={{ padding: '4px 8px', borderLeft: `2px solid ${roleColor}` }}>
+      <Inline align="center" gap={2}>
+        <span style={{ color: 'var(--fg-subtle)' }}>{ts}</span>
+        <span style={{ color: roleColor, fontWeight: 600 }}>{event.role ?? 'msg'}</span>
+      </Inline>
+      {event.content && (
+        <Box style={{ color: 'var(--fg)', marginTop: 2, paddingLeft: 12, whiteSpace: 'pre-wrap', wordBreak: 'break-word' }}>
+          {truncate(event.content, 800)}
+        </Box>
+      )}
+    </Box>
+  );
+}
+
+function truncate(s: string, max: number): string {
+  return s.length <= max ? s : `${s.slice(0, max)}…`;
+}
+
+function mergeEvents(prev: StreamEvent[], next: StreamEvent[], max: number): StreamEvent[] {
+  if (next.length === 0) return prev;
+  const out = prev.concat(next);
+  if (out.length <= max) return out;
+  return out.slice(out.length - max);
+}

package/bizar-dash/src/web/v8/ui/controls/Button.tsx

@@ -0,0 +1,141 @@
+import { forwardRef, type ButtonHTMLAttributes, type ReactNode } from 'react';
+import { Slot } from '@radix-ui/react-slot';
+import { Loader2 } from 'lucide-react';
+import { cx } from '../utils/cx.js';
+
+/**
+ * Button — the v8 primary action surface.
+ *
+ * Variants:
+ *   - primary    — the only loud button. Use sparingly (DESIGN.md §1).
+ *   - secondary  — bordered, default for most actions.
+ *   - ghost      — text-only, used inside surfaces (toolbars, cards).
+ *   - danger     — destructive actions.
+ *
+ * Sizes:
+ *   - sm (28px), md (32px), lg (40px), icon (32px square)
+ *
+ * Loading: shows a spinner and disables interaction. Default label stays visible
+ * so the button doesn't reflow.
+ */
+
+export type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger' | 'outline';
+export type ButtonSize = 'sm' | 'md' | 'lg' | 'icon';
+
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+  /** When true, render as a Slot so the child <a> / <Link> inherits styling. */
+  asChild?: boolean;
+  loading?: boolean;
+  leftIcon?: ReactNode;
+  rightIcon?: ReactNode;
+  fullWidth?: boolean;
+}
+
+const SIZE: Record<ButtonSize, { h: number; px: number; fs: string }> = {
+  sm: { h: 28, px: 10, fs: 'var(--fs-12)' },
+  md: { h: 32, px: 14, fs: 'var(--fs-13)' },
+  lg: { h: 40, px: 18, fs: 'var(--fs-14)' },
+  icon: { h: 32, px: 0, fs: 'var(--fs-13)' },
+};
+
+const VARIANT_BG: Record<ButtonVariant, string> = {
+  primary: 'var(--accent)',
+  secondary: 'var(--surface-1)',
+  ghost: 'transparent',
+  danger: 'var(--danger)',
+  outline: 'transparent',
+};
+
+const VARIANT_FG: Record<ButtonVariant, string> = {
+  primary: 'var(--fg-on-accent)',
+  secondary: 'var(--fg)',
+  ghost: 'var(--fg-muted)',
+  danger: 'var(--fg-on-accent)',
+  outline: 'var(--fg)',
+};
+
+const VARIANT_BORDER: Record<ButtonVariant, string> = {
+  primary: 'transparent',
+  secondary: 'var(--border)',
+  ghost: 'transparent',
+  danger: 'transparent',
+  outline: 'var(--border)',
+};
+
+const VARIANT_HOVER_BG: Record<ButtonVariant, string> = {
+  primary: 'var(--accent-hover)',
+  secondary: 'var(--surface-2)',
+  ghost: 'var(--surface-1)',
+  danger: 'color-mix(in oklch, var(--danger), black 10%)',
+  outline: 'var(--surface-1)',
+};
+
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button(props, ref) {
+  const {
+    variant = 'secondary',
+    size = 'md',
+    asChild,
+    loading,
+    disabled,
+    leftIcon,
+    rightIcon,
+    fullWidth,
+    children,
+    className,
+    style,
+    type,
+    ...rest
+  } = props;
+
+  const Comp = (asChild ? Slot : 'button') as React.ElementType;
+  const sz = SIZE[size];
+  const isDisabled = disabled === true || loading === true;
+
+  const computedStyle = {
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: 'var(--space-2)',
+    height: sz.h,
+    paddingLeft: sz.px,
+    paddingRight: sz.px,
+    width: fullWidth === true ? '100%' : undefined,
+    fontSize: sz.fs,
+    fontWeight: 500,
+    lineHeight: 1,
+    letterSpacing: 'var(--tracking-base)',
+    background: VARIANT_BG[variant],
+    color: VARIANT_FG[variant],
+    border: '1px solid',
+    borderColor: VARIANT_BORDER[variant],
+    borderRadius: 'var(--radius-sm)',
+    cursor: isDisabled ? 'not-allowed' : 'pointer',
+    opacity: isDisabled ? 0.55 : 1,
+    transition:
+      'background var(--motion-fast) var(--ease-out), border-color var(--motion-fast) var(--ease-out), color var(--motion-fast) var(--ease-out)',
+    whiteSpace: 'nowrap',
+    userSelect: 'none',
+    ...style,
+  } as const;
+
+  // For hover effect we have to inject a CSS variable that :hover can use.
+  const hoverStyle = { '--btn-hover-bg': VARIANT_HOVER_BG[variant] } as React.CSSProperties;
+
+  return (
+    <Comp
+      ref={ref as React.Ref<HTMLElement>}
+      type={asChild ? undefined : type ?? 'button'}
+      disabled={isDisabled}
+      aria-busy={loading === true ? 'true' : undefined}
+      className={cx('v8-btn', `v8-btn--${variant}`, `v8-btn--${size}`, className)}
+      style={{ ...computedStyle, ...hoverStyle }}
+      {...rest}
+    >
+      {loading === true ? <Loader2 size={14} aria-hidden="true" className="v8-btn__spinner" /> : leftIcon}
+      {children}
+      {rightIcon}
+    </Comp>
+  );
+});

package/bizar-dash/src/web/v8/ui/controls/ButtonGroup.tsx

@@ -0,0 +1,32 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+import { cx } from '../utils/cx.js';
+
+/**
+ * ButtonGroup — a horizontal cluster of buttons that share borders + radius.
+ *
+ * Renders a single bordered container with internal dividers so adjacent
+ * buttons look like one segmented control.
+ */
+export interface ButtonGroupProps extends HTMLAttributes<HTMLDivElement> {
+  children: ReactNode;
+  attached?: boolean;
+}
+
+export function ButtonGroup({ children, attached = true, className, style, ...rest }: ButtonGroupProps) {
+  return (
+    <div
+      role="group"
+      className={cx('v8-btn-group', attached && 'is-attached', className)}
+      style={{
+        display: 'inline-flex',
+        border: attached ? '1px solid var(--border)' : 'none',
+        borderRadius: 'var(--radius-sm)',
+        overflow: 'hidden',
+        ...style,
+      }}
+      {...rest}
+    >
+      {children}
+    </div>
+  );
+}

package/bizar-dash/src/web/v8/ui/controls/Checkbox.tsx

@@ -0,0 +1,49 @@
+import { forwardRef, type ComponentPropsWithoutRef } from 'react';
+import * as RxCheckbox from '@radix-ui/react-checkbox';
+import { Check, Minus } from 'lucide-react';
+import { cx } from '../utils/cx.js';
+
+/**
+ * Checkbox — controlled or uncontrolled boolean input.
+ *
+ * Built on Radix Checkbox for keyboard + screen reader correctness.
+ * Use inside <Field> for label/hint/error.
+ */
+
+export type CheckboxProps = ComponentPropsWithoutRef<typeof RxCheckbox.Root>;
+
+export const Checkbox = forwardRef<HTMLButtonElement, CheckboxProps>(function Checkbox(
+  props,
+  ref,
+) {
+  const { className, disabled, ...rest } = props;
+  return (
+    <RxCheckbox.Root
+      ref={ref}
+      disabled={disabled}
+      className={cx('v8-checkbox', className)}
+      style={{
+        width: 16,
+        height: 16,
+        display: 'inline-flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        background: 'var(--input-bg)',
+        border: '1px solid var(--border-strong)',
+        borderRadius: 'var(--radius-sm)',
+        cursor: disabled === true ? 'not-allowed' : 'pointer',
+        opacity: disabled === true ? 0.55 : 1,
+        transition: 'background var(--motion-fast) var(--ease-out), border-color var(--motion-fast) var(--ease-out)',
+      }}
+      {...rest}
+    >
+      <RxCheckbox.Indicator>
+        {rest.checked === 'indeterminate' ? (
+          <Minus size={12} aria-hidden="true" style={{ color: 'var(--fg-on-accent)' }} />
+        ) : (
+          <Check size={12} aria-hidden="true" style={{ color: 'var(--fg-on-accent)' }} />
+        )}
+      </RxCheckbox.Indicator>
+    </RxCheckbox.Root>
+  );
+});

package/bizar-dash/src/web/v8/ui/controls/Field.tsx

@@ -0,0 +1,78 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import { cx } from '../utils/cx.js';
+
+/**
+ * Field — form field wrapper that pairs a label with a control and optional
+ * hint / error message.
+ *
+ * Use for any form input so labels, hints, and errors render consistently.
+ * Accessibility: the label is properly associated with the control via
+ * `htmlFor` + `id`. The hint and error share `aria-describedby`.
+ */
+export interface FieldProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+  /** Unique id used for the input + label-for relationship. */
+  id: string;
+  /** Visible label text. */
+  label: ReactNode;
+  /** Optional descriptive hint below the control. */
+  hint?: ReactNode;
+  /** Optional error message. When present, the field renders the error tone. */
+  error?: ReactNode;
+  /** Whether the field is required (adds a red asterisk). */
+  required?: boolean;
+  /** The form control. Field renders the label and styling around it. */
+  children: ReactNode;
+}
+
+export const Field = forwardRef<HTMLDivElement, FieldProps>(function Field(props, ref) {
+  const { id, label, hint, error, required, children, className, ...rest } = props;
+  const hintId = hint !== undefined ? `${id}-hint` : undefined;
+  const errorId = error !== undefined ? `${id}-error` : undefined;
+
+  return (
+    <div
+      ref={ref}
+      className={cx('v8-field', error !== undefined && 'has-error', className)}
+      style={{ display: 'flex', flexDirection: 'column', gap: 'var(--space-2)' }}
+      {...rest}
+    >
+      <label
+        htmlFor={id}
+        style={{
+          fontSize: 'var(--fs-13)',
+          fontWeight: 500,
+          color: 'var(--fg)',
+          display: 'flex',
+          alignItems: 'center',
+          gap: 'var(--space-1)',
+        }}
+      >
+        {label}
+        {required === true && (
+          <span aria-hidden="true" style={{ color: 'var(--danger)' }}>
+            *
+          </span>
+        )}
+      </label>
+      {/* Children must wire `id={id}` to their input for the label to work. */}
+      {children}
+      {hint !== undefined && error === undefined && (
+        <div
+          id={hintId}
+          style={{ fontSize: 'var(--fs-12)', color: 'var(--fg-muted)' }}
+        >
+          {hint}
+        </div>
+      )}
+      {error !== undefined && (
+        <div
+          id={errorId}
+          role="alert"
+          style={{ fontSize: 'var(--fs-12)', color: 'var(--danger)' }}
+        >
+          {error}
+        </div>
+      )}
+    </div>
+  );
+});

package/bizar-dash/src/web/v8/ui/controls/Form.tsx

@@ -0,0 +1,23 @@
+import { forwardRef, type FormHTMLAttributes, type ReactNode } from 'react';
+import { cx } from '../utils/cx.js';
+
+/**
+ * Form — top-level form surface. Currently a thin styled wrapper around <form>.
+ *
+ * The v8 dashboard forms are intentionally minimal — most fields are wired
+ * via <Field> + native input events. For complex forms (Settings pages,
+ * kanban quick-add) use react-hook-form in the consumer; this primitive
+ * just provides consistent layout + a handle for future form-level tooling.
+ */
+export interface FormProps extends FormHTMLAttributes<HTMLFormElement> {
+  children: ReactNode;
+}
+
+export const Form = forwardRef<HTMLFormElement, FormProps>(function Form(props, ref) {
+  const { children, className, ...rest } = props;
+  return (
+    <form ref={ref} className={cx('v8-form', className)} style={{ display: 'flex', flexDirection: 'column', gap: 'var(--space-4)' }} {...rest}>
+      {children}
+    </form>
+  );
+});