@semiont/react-ui 0.5.26 → 0.5.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semiont/react-ui",
-  "version": "0.5.26",
+  "version": "0.5.28",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -22,7 +22,6 @@
     "./styles": "./src/styles/index.css",
     "./styles/index.css": "./src/styles/index.css",
     "./styles/variables.css": "./src/styles/variables.css",
-    "./tailwind": "./src/integrations/tailwind-plugin.cjs",
     "./integrations/css-modules": {
       "types": "./dist/integrations/css-modules-helper.d.ts",
       "import": "./dist/integrations/css-modules-helper.js",
@@ -37,6 +36,7 @@
   },
   "files": [
     "dist",
+    "!dist/**/*.map",
     "src/styles",
     "src/components",
     "src/features",
@@ -92,21 +92,21 @@
   },
   "devDependencies": {
     "@headlessui/react": "^2.2.10",
-    "@testing-library/jest-dom": "^6.1.5",
+    "@testing-library/jest-dom": "^7.0.1",
     "@testing-library/react": "^16.1.0",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.4",
     "@vitest/coverage-v8": "^4.1.8",
     "autoprefixer": "^10.5.4",
     "axe-core": "^4.12.1",
-    "cssnano": "^8.0.2",
+    "cssnano": "^8.0.5",
     "fast-check": "^4.9.0",
-    "jest-axe": "^10.0.0",
+    "jest-axe": "^11.0.0",
     "jsdom": "^29.1.1",
     "postcss-import": "^16.1.1",
     "rollup": "^4.62.3",
     "rollup-plugin-dts": "^6.4.1",
-    "styled-components": "^6.4.3",
+    "styled-components": "^6.5.2",
     "tsup": "^8.0.1",
     "typescript": "^6.0.2",
     "vitest": "^4.1.10"
@@ -118,13 +118,14 @@
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/The-AI-Alliance/semiont.git",
+    "url": "git+https://github.com/The-AI-Alliance/semiont.git",
     "directory": "packages/react-ui"
   },
   "dependencies": {
-    "@semiont/core": "0.5.26",
-    "@semiont/http-transport": "0.5.26",
-    "@semiont/sdk": "0.5.26",
+    "@semiont/core": "0.5.28",
+    "@semiont/http-transport": "0.5.28",
+    "@semiont/sdk": "0.5.28",
+    "clsx": "^2.1.1",
     "pdfjs-dist": "^6.2.108",
     "react-error-boundary": "^6.1.2",
     "react-markdown": "^10.1.0",

package/src/components/AssistProgress.tsx

@@ -1,181 +1,225 @@
 'use client';
 
 import type { components } from '@semiont/core';
-import { EntityFoundLog } from './EntityFoundLog';
+import { ItemFoundLog } from './ItemFoundLog';
 
 type JobProgress = components['schemas']['JobProgress'];
+type JobProgressMessage = components['schemas']['JobProgressMessage'];
 
 /**
- * Every string this component renders. Required by default and with NO
- * English fallbacks (ASSIST-SURFACE-WARTS Lane A): a `tr.x || 'X'` default
- * turns a forgotten key into English text in a Japanese UI, silently and
- * only at runtime. Required keys make the same mistake a type error at the
- * call site. Only genuinely conditional copy is optional.
+ * Every string this component renders. Required by default and with NO English
+ * fallbacks (ASSIST-SURFACE-WARTS Lane A): a `tr.x || 'X'` default turns a
+ * forgotten key into English text in a Japanese UI, silently and only at
+ * runtime. Required keys make the same mistake a type error at the call site.
+ *
+ * The nine wire codes collapse to ONE required function rather than nine keys:
+ * the code→copy switch belongs in one place, and threading nine strings through
+ * five call sites would put five copies of it in the tree. Build it with
+ * `assistProgressCopy(t)`.
  */
 export interface AssistProgressTranslations {
-  /** Header title (e.g. "Annotating Entity References" / "Generating Resource"). Omit for the headerless inline style. */
-  title?: string;
-  /** Cancel-button title attribute. */
+  /** Control label while the run is in flight. */
   cancel: string;
-  /** Default in-progress status message (used when the job sends no `message`). */
+  /** Control label once the run has ended. */
+  close: string;
+  /** Localized copy for a progress code. */
+  message: (m: JobProgressMessage) => string;
+  /**
+   * Shown when no code has arrived yet — a pure liveness heartbeat, or an event
+   * predating the coded wire. `JobProgress.message` is optional for exactly
+   * these cases.
+   */
   inProgress: string;
-  /** Status copy for the terminal 'complete' stage. */
-  complete: string;
-  /** Fallback status copy for the terminal 'error' stage. */
-  failed: string;
-  /** Request-parameters block heading. */
-  paramsTitle: string;
-  /** Current-work detail line — the generic form, used by every flow. */
-  processing: (label: string) => string;
+  /**
+   * The subject line: what is being worked on, with its position when known.
+   * Takes the wire's `{ kind, value }` — the localized name for `kind` is the
+   * translation layer's business, not this component's.
+   */
+  subject: (current: NonNullable<JobProgress['current']>, done?: number, total?: number) => string;
+  /**
+   * Localized NAME for an echoed request parameter. The wire sends a code
+   * (`instructions`, `tone`, …); the VALUE beside it is the user's own words
+   * and is never translated.
+   */
+  paramLabel: (code: string) => string;
   /** Completed entity-type log line (reference flow only). */
   found?: (count: number) => string;
-  /** Current-work detail line, reference-flow wording; falls back to `processing`. */
-  current?: (label: string) => string;
-  /** Dismiss-button label. */
-  close: string;
 }
 
+/**
+ * The CSS `data-type` hook: five motivations plus generation. A closed set, so
+ * it is typed as one — a typo used to produce unstyled chrome, silently
+ * (CLEAN-PROGRESS A9).
+ */
+export type AssistDataType =
+  | 'highlight' | 'comment' | 'assessment' | 'reference' | 'tag' | 'generation';
+
 export interface AssistProgressProps {
   progress: JobProgress;
-  /** CSS `data-type` hook ('highlight' | 'comment' | … | 'reference' | 'tag' | 'generation'). */
-  dataType: string;
-  /** Cancel the underlying job — rendered while running when provided. Caller wires `client.job.cancelRequest(...)`. */
-  onCancel?: () => void;
+  dataType: AssistDataType;
+  /**
+   * What the finished run produced, offered as a link in the ended frame
+   * (GENERATE-FROM-RESOURCE D8). The label is the artifact's own name — user
+   * content, never translated. Rendered only once `ended`: mid-run there is no
+   * outcome to offer, whatever the caller has wired.
+   */
+  outcome?: { label: string; onOpen: () => void } | undefined;
+  /**
+   * The owner's terminal sentence, rendered in place of the payload message
+   * once `ended` (GENERATION-ARRIVAL P1). The producer's final frame is a
+   * fire-and-forget emit that can lose the race with `job:complete`, so an
+   * ended frame must not trust the last payload to describe the ending —
+   * the owner, which signalled `ended`, supplies the words too. Inert while
+   * the run is live.
+   */
+  endedMessage?: string;
   /**
-   * Dismiss the display — rendered whenever provided. WHEN dismissal is
-   * offered is the caller's policy (AssistShell withholds the callback while
-   * the assist is still running). Caller wires `client.mark.dismissProgress()`.
+   * The run has ENDED. The owner's fact, not the payload's
+   * (ASSIST-PROGRESS-CONSOLIDATION D7): terminality is signalled on
+   * `job:complete` / `job:fail`, which `AssistShell` already observes via
+   * `isAssisting`. This component deliberately does not read `progress.stage` —
+   * no producer in the repo emits a terminal stage, and the two branches that
+   * believed the schema's description were unreachable for exactly that reason.
+   *
+   * REQUIRED (CLEAN-PROGRESS A1). It was optional, and the one call site that
+   * forgot it shipped a flow that could never reach the ended state at all.
+   * Nothing about a progress payload can tell this component the run is over,
+   * so the owner must say — and a default of `false` is a wrong answer, not a
+   * safe one.
    */
+  ended: boolean;
+  /** Cancel the underlying job. Caller wires `client.job.cancelRequest(...)`. */
+  onCancel?: () => void;
+  /** Dismiss the display. Caller wires `client.mark.dismissProgress()`. */
   onDismiss?: () => void;
-  /** Render the percentage bar (tag flow's visual; percentage itself comes from `progress`). */
-  showPercentBar?: boolean;
   translations: AssistProgressTranslations;
 }
 
 /**
- * The one job-progress renderer (#7) — unifies the three previous shapes
- * (AssistSection's inline block, the reference/generation widget, TaggingPanel's
- * inline block). Presentational and provider-free: no session, no context —
- * cancel/dismiss arrive as callbacks, so it renders identically on the page and
- * in embeddable (bring-your-own-session) hosts. Feature blocks are
- * data-presence-driven: each call site keeps its established visuals by passing
- * the data and translations it always had.
+ * The one job-progress renderer, for all five motivations.
+ *
+ * Presentational and provider-free: no session, no context — cancel/dismiss
+ * arrive as callbacks, so it renders identically on the page and in embeddable
+ * (bring-your-own-session) hosts.
+ *
+ * One shape for every flow. What varies is DATA, not flags: a bar appears
+ * because there is a fraction to fill it, a subject line appears because there
+ * is a subject. The previous `title` / `showPercentBar` / `found` / `current`
+ * opt-ins produced four unrelated layouts from one component, which is what
+ * generated the duplicate renders and doubled chrome this replaces.
  */
 export function AssistProgress({
   progress,
   dataType,
+  ended,
+  outcome,
+  endedMessage,
   onCancel,
   onDismiss,
-  showPercentBar = false,
   translations: tr,
 }: AssistProgressProps) {
-  const terminal = progress.stage === 'complete' || progress.stage === 'error';
-  // The reference flow words this line its own way; everyone else gets the
-  // generic one. Both are translated — there is no untranslated branch.
-  const currentLabel = tr.current ?? tr.processing;
+  // One vocabulary, so no guessing (CLEAN-PROGRESS D2). This used to be a pair
+  // of `??` chains reconciling entity-type fields with category fields — the
+  // component had to know which flow it was drawing to find the same two facts.
+  const current = progress.current;
+  const done = progress.processed;
+  const total = progress.total;
 
-  return (
-    <div className="semiont-annotation-progress" data-status={progress.stage} data-type={dataType}>
-      {/* Header (title + cancel) — reference/generation style; omitted inline */}
-      {tr.title && (
-        <div className="semiont-annotation-header">
-          <h3 className="semiont-annotation-title">
-            <span className="semiont-annotation-sparkle">✨</span>
-            {tr.title}
-          </h3>
-          {onCancel && !terminal && (
-            <button
-              onClick={onCancel}
-              className="semiont-annotation-cancel"
-              title={tr.cancel}
-              aria-label={tr.cancel}
-              type="button"
-            >
-              ✕
-            </button>
-          )}
-        </div>
-      )}
+  // H1: the params line earns its space only when it says something the status
+  // line does not. The ONLY redundant case is a single entity type, where the
+  // subject beneath already names it — so that case alone is suppressed.
+  //
+  // Deliberately NOT `total > 1`: other flows send params that never restate the
+  // subject (a highlight run reports Instructions and Density), and those have
+  // no `total` at all. Gating on the presence of a count would have hidden
+  // genuinely informative parameters — an over-application of H1 caught by
+  // AssistSection's highlight fixture.
+  const params = total === 1 ? undefined : progress.requestParams;
+
+  // `percentage` is REQUIRED on JobProgress, so every progress event can fill a
+  // bar — the bar's existence is not conditional on anything.
+  //
+  // It used to also require the fraction (`done`/`total`), which SILENTLY
+  // REMOVED THE TAG FLOW'S BAR: `processTagJob` reports percentage only and
+  // emits no category fields at all, so `done`/`total` are permanently
+  // undefined there (caught in review of PR #1179). The fraction is a richer,
+  // optional signal that only flows counting per-item work have; it belongs to
+  // the SUBJECT line, not to whether a bar exists.
 
-      {/* Request parameters */}
-      {progress.requestParams && progress.requestParams.length > 0 && (
-        <div className="semiont-annotation-progress__params" data-type={dataType}>
-          <div className="semiont-annotation-progress__params-title">{tr.paramsTitle}</div>
-          {progress.requestParams.map((param, idx) => (
-            <div key={idx} className="semiont-annotation-progress__param">
-              <span className="semiont-annotation-progress__param-label">{param.label}:</span> <span>{param.value}</span>
-            </div>
+  return (
+    <div className="semiont-assist-progress" data-type={dataType} data-ended={ended}>
+      {params && params.length > 0 && (
+        <div className="semiont-assist-progress__params" data-testid="semiont-assist-params">
+          {/* H1 removed the BLOCK HEADING ("Request Parameters:"), not the
+              per-parameter labels: a bare "5" for Density says nothing. */}
+          {params.map((param, idx) => (
+            <span key={idx} className="semiont-assist-progress__param">
+              <span className="semiont-assist-progress__param-label">
+                {tr.paramLabel(param.label)}:
+              </span>{' '}
+              <span>{param.value}</span>
+            </span>
           ))}
         </div>
       )}
 
-      {/* Completed entity-type log (reference flow) */}
-      {tr.found && progress.completedEntityTypes && (
-        <EntityFoundLog entries={progress.completedEntityTypes} formatFound={tr.found} />
+      {/* H2: kept uncapped — per-item counts are small in practice. */}
+      {tr.found && progress.completedItems && (
+        <ItemFoundLog entries={progress.completedItems} formatFound={tr.found} />
       )}
 
-      {/* Status line with stage branching */}
-      <div className="semiont-annotation-progress__status">
-        {progress.stage === 'complete' ? (
-          <div className="semiont-annotation-progress__message">
-            <span className="semiont-annotation-progress__icon">✅</span>
-            {/* Same precedence as 'error' below: the job's own message carries
-                detail no static string can ("Created 14 highlights"), and
-                `tr.complete` covers the required-but-possibly-'' case so a
-                terminal line is never blank. NOTE: job messages are composed
-                backend-side and are not localized — a real gap, but a backend
-                one; see ASSIST-SURFACE-WARTS watch-items. */}
-            <span>{progress.message || tr.complete}</span>
-          </div>
-        ) : progress.stage === 'error' ? (
-          <div className="semiont-annotation-progress__message">
-            <span className="semiont-annotation-progress__icon">❌</span>
-            <span>{progress.message || tr.failed}</span>
-          </div>
-        ) : (
-          <div className="semiont-annotation-progress__message">
-            <span className="semiont-annotation-progress__icon">✨</span>
-            <span>
-              {progress.message
-                || (progress.currentEntityType ? currentLabel(progress.currentEntityType) : tr.inProgress)}
-            </span>
-          </div>
-        )}
+      <div className="semiont-assist-progress__status">
+        <span className="semiont-assist-progress__icon" aria-hidden="true">
+          {ended ? '✅' : '✨'}
+        </span>
+        <span data-testid="semiont-assist-status">
+          {ended && endedMessage
+            ? endedMessage
+            : progress.message ? tr.message(progress.message) : tr.inProgress}
+        </span>
+      </div>
 
-        {/* Current-work detail while running */}
-        {!terminal && progress.currentEntityType && (
-          <div className="semiont-annotation-progress__details">
-            {currentLabel(progress.currentEntityType)}
-          </div>
-        )}
-        {!terminal && progress.currentCategory && (
-          <div className="semiont-annotation-progress__details">
-            {tr.processing(progress.currentCategory)}
-            {progress.processedCategories !== undefined && progress.totalCategories !== undefined && (
-              <> ({progress.processedCategories}/{progress.totalCategories})</>
-            )}
-          </div>
-        )}
+      {/* H3: stage above, subject beneath. */}
+      {current && (
+        <div className="semiont-assist-progress__subject" data-testid="semiont-assist-subject">
+          {tr.subject(current, done, total)}
+        </div>
+      )}
 
-        {/* Dismiss — rendered whenever the caller offers it */}
-        {onDismiss && (
-          <button
-            onClick={onDismiss}
-            className="semiont-annotation-progress__close"
-            aria-label={tr.close}
-            title={tr.close}
-            type="button"
-          >
-            ×
-          </button>
-        )}
+      {/* D8: the finished run's artifact, by name. */}
+      {ended && outcome && (
+        <button
+          type="button"
+          onClick={outcome.onOpen}
+          className="semiont-assist-progress__outcome"
+          data-testid="semiont-assist-outcome"
+        >
+          {outcome.label}
+        </button>
+      )}
+
+      {/* An ended run is 100% done by definition — the last payload's number
+          is a mid-run fact and must not survive the ending (A1). */}
+      <div className="semiont-progress-bar" data-testid="semiont-assist-bar">
+        <div
+          className="semiont-progress-bar__fill"
+          data-type={dataType}
+          style={{ width: `${ended ? 100 : progress.percentage}%` }}
+        />
       </div>
 
-      {/* Percentage bar (tag flow) */}
-      {showPercentBar && progress.percentage !== undefined && (
-        <div className="semiont-progress-bar">
-          <div className="semiont-progress-bar__fill" data-type={dataType} style={{ width: `${progress.percentage}%` }} />
-        </div>
+      {/* D3: ONE control, its meaning set by the lifecycle. */}
+      {(ended ? onDismiss : onCancel) && (
+        <button
+          onClick={ended ? onDismiss : onCancel}
+          className="semiont-assist-progress__control"
+          data-testid="semiont-assist-control"
+          title={ended ? tr.close : tr.cancel}
+          aria-label={ended ? tr.close : tr.cancel}
+          type="button"
+        >
+          ✕
+        </button>
       )}
     </div>
   );

package/src/components/CodeMirrorRenderer.tsx

@@ -37,7 +37,7 @@ interface Props {
   onTextSelect?: (exact: string, position: { start: number; end: number }) => void;
   onChange?: (content: string) => void;
   editable?: boolean;
-  newAnnotationIds?: Set<string>;
+  sparkleAnnotationIds?: Set<string>;
   hoveredAnnotationId?: string | null;
   scrollToAnnotationId?: string | null;
   sourceView?: boolean; // If true, show raw source (no markdown rendering)
@@ -52,7 +52,7 @@ interface Props {
 // Effect to update annotation decorations with segments and new IDs
 interface AnnotationUpdate {
   segments: TextSegment[];
-  newAnnotationIds?: Set<string>;
+  sparkleAnnotationIds?: Set<string>;
 }
 
 const updateAnnotationsEffect = StateEffect.define<AnnotationUpdate>();
@@ -70,10 +70,10 @@ const updateWidgetsEffect = StateEffect.define<WidgetUpdate>();
 // Build CodeMirror decorations from pure metadata
 function buildAnnotationDecorations(
   segments: TextSegment[],
-  newAnnotationIds?: Set<string>
+  sparkleAnnotationIds?: Set<string>
 ): DecorationSet {
   const builder = new RangeSetBuilder<Decoration>();
-  const entries = computeAnnotationDecorations(segments, newAnnotationIds);
+  const entries = computeAnnotationDecorations(segments, sparkleAnnotationIds);
 
   for (const { start, end, meta } of entries) {
     const decoration = Decoration.mark({
@@ -103,7 +103,7 @@ function createAnnotationDecorationsField() {
 
       for (const effect of tr.effects) {
         if (effect.is(updateAnnotationsEffect)) {
-          decorations = buildAnnotationDecorations(effect.value.segments, effect.value.newAnnotationIds);
+          decorations = buildAnnotationDecorations(effect.value.segments, effect.value.sparkleAnnotationIds);
         }
       }
 
@@ -175,7 +175,7 @@ export function CodeMirrorRenderer({
   segments = [],
   onChange,
   editable = false,
-  newAnnotationIds,
+  sparkleAnnotationIds,
   hoveredAnnotationId,
   scrollToAnnotationId,
   sourceView = false,
@@ -410,9 +410,9 @@ export function CodeMirrorRenderer({
     if (!viewRef.current) return;
 
     viewRef.current.dispatch({
-      effects: updateAnnotationsEffect.of({ segments: convertedSegments, ...(newAnnotationIds && { newAnnotationIds }) })
+      effects: updateAnnotationsEffect.of({ segments: convertedSegments, ...(sparkleAnnotationIds && { sparkleAnnotationIds }) })
     });
-  }, [convertedSegments, newAnnotationIds]);
+  }, [convertedSegments, sparkleAnnotationIds]);
 
   // Update widgets when content, segments, or generatingReferenceId changes
   useEffect(() => {

package/src/components/{EntityFoundLog.tsx → ItemFoundLog.tsx}

@@ -1,18 +1,19 @@
 'use client';
 
-export interface EntityFoundEntry {
-  entityType: string;
+export interface ItemFoundEntry {
+  /** The item itself — an entity type, a tag category — shown verbatim. */
+  value: string;
   foundCount: number;
 }
 
-export interface EntityFoundLogProps {
-  entries: EntityFoundEntry[];
+export interface ItemFoundLogProps {
+  entries: ItemFoundEntry[];
   /** Formats the per-entity count line, e.g. `(n) => t('found', { count: n })`. */
   formatFound: (count: number) => string;
 }
 
 /**
- * "✓ Person: 5 found" — the completed entity-type log.
+ * "✓ Person: 5 found" — the completed-items log.
  *
  * One markup for one concept (ASSIST-SURFACE-WARTS Lane B). This was two
  * class families a single panel apart: the live progress display used
@@ -20,8 +21,12 @@ export interface EntityFoundLogProps {
  * `semiont-assist-widget__log*`, with the same rows rendered by hand in both.
  * Presentational and provider-free, like AssistProgress — the caller brings
  * the formatter.
+ *
+ * Item-shaped rather than entity-type-shaped (CLEAN-PROGRESS D2): the tag flow
+ * counts categories the same way the reference flow counts entity types, and a
+ * shared component should not be named for one of its callers.
  */
-export function EntityFoundLog({ entries, formatFound }: EntityFoundLogProps) {
+export function ItemFoundLog({ entries, formatFound }: ItemFoundLogProps) {
   if (entries.length === 0) return null;
 
   return (
@@ -29,7 +34,7 @@ export function EntityFoundLog({ entries, formatFound }: EntityFoundLogProps) {
       {entries.map((item, index) => (
         <div key={index} className="semiont-annotation-log-item">
           <span className="semiont-annotation-check">✓</span>
-          <span className="semiont-annotation-entity-type">{item.entityType}:</span>
+          <span className="semiont-annotation-entity-type">{item.value}:</span>
           <span>{formatFound(item.foundCount)}</span>
         </div>
       ))}

package/src/components/ProtectedErrorBoundary.css

@@ -88,8 +88,10 @@
   color: var(--semiont-color-gray-700);
 }
 
+/* gray-500 is thin for this size on a near-black surface, and the hover below
+   already lifts to gray-300 — resting darker than its own hover target. */
 [data-theme="dark"] .semiont-protected-error-boundary-summary {
-  color: var(--semiont-color-gray-500);
+  color: var(--semiont-color-gray-400);
 }
 
 [data-theme="dark"] .semiont-protected-error-boundary-summary:hover {

package/src/components/StatusDisplay.css

@@ -414,7 +414,7 @@
 }
 
 [data-theme="dark"] .semiont-icon-warning {
-  color: var(--semiont-color-amber-400);
+  color: var(--semiont-color-warning-light);
 }
 
 [data-theme="dark"] .semiont-async-error-title {

package/src/components/Toast.css

@@ -26,8 +26,10 @@
   animation: slideIn var(--semiont-duration-base) var(--semiont-ease);
 }
 
+/* Separation, not decoration: a 10%-black shadow is invisible against a dark
+   backdrop, so the dark theme takes the deeper one. */
 [data-theme="dark"] .semiont-toast {
-  box-shadow: var(--semiont-shadow-lg);
+  box-shadow: var(--semiont-shadow-xl);
 }
 
 @keyframes slideIn {