@semiont/react-ui 0.5.27 → 0.5.28

package/src/components/modals/ConfigureGenerationStep.tsx

@@ -35,14 +35,18 @@ export interface GenerationConfig {
 
 export interface ConfigureGenerationStepProps {
   context: GatheredContext;
+  /** Echo of the gather step's hint — the thing being steered stays visible (GEP D8). */
+  hintEcho?: { label: string; value: string };
   /** Owned by the wizard so Back is lossless (WIZARD-NAVIGATION D3). */
   config: GenerationDraft;
   onConfigChange: (config: GenerationDraft) => void;
-  onBack: () => void;
+  /** Absent in a single-stack host (GATHER-AT-THE-TOP D6) — the footer then renders no retreat. */
+  onBack?: () => void;
   onGenerate: (config: GenerationConfig) => void;
   translations: {
     resourceTitle: string;
     resourceTitlePlaceholder: string;
+    saveLocation: string;
     additionalInstructions: string;
     additionalInstructionsPlaceholder: string;
     language: string;
@@ -58,7 +62,7 @@ export interface ConfigureGenerationStepProps {
      * and `{{model}}`.
      */
     maxLengthCeiling: string;
-    back: string;
+    back?: string;
     generate: string;
   };
   /**
@@ -73,6 +77,7 @@ export interface ConfigureGenerationStepProps {
 
 export function ConfigureGenerationStep({
   context,
+  hintEcho,
   config,
   onConfigChange,
   onBack,
@@ -127,7 +132,15 @@ export function ConfigureGenerationStep({
   };
 
   return (
-    <form onSubmit={handleSubmit} className="semiont-form semiont-form--scrollable">
+    // No --scrollable: this form renders below the evidence display inside the
+    // host's single step-scroll pane — an independent scroll region here is
+    // what squeezed the parameters out of view (the measured failure).
+    <form onSubmit={handleSubmit} className="semiont-form">
+      {hintEcho && (
+        <p className="semiont-wizard__hint-echo">
+          {hintEcho.label}: {hintEcho.value}
+        </p>
+      )}
       {/* Resource Title */}
       <div className="semiont-form__field">
         <label htmlFor="wizard-title" className="semiont-form__label">
@@ -147,7 +160,7 @@ export function ConfigureGenerationStep({
       {/* Storage URI */}
       <div className="semiont-form__field">
         <label htmlFor="wizard-storagePath" className="semiont-form__label">
-          Save location
+          {t.saveLocation}
         </label>
         <div className="semiont-input-addon">
           <span className="semiont-input-addon__prefix">file://</span>
@@ -198,7 +211,7 @@ export function ConfigureGenerationStep({
           </select>
         </div>
 
-        <div className="semiont-form__field semiont-form__field--inline semiont-form__field--grow">
+        <div className="semiont-form__field semiont-form__field--inline semiont-form__field--slider">
           <label htmlFor="wizard-temperature" className="semiont-form__label">
             {t.creativity} ({temperature.toFixed(1)})
           </label>
@@ -218,7 +231,7 @@ export function ConfigureGenerationStep({
           </div>
         </div>
 
-        <div className="semiont-form__field semiont-form__field--inline semiont-form__field--narrow">
+        <div className="semiont-form__field semiont-form__field--inline semiont-form__field--narrow semiont-form__field--end">
           <label htmlFor="wizard-maxTokens" className="semiont-form__label">
             {t.maxLength}
           </label>
@@ -242,23 +255,26 @@ export function ConfigureGenerationStep({
             }}
             className="semiont-input"
           />
-          <p className="semiont-form__help">
-            {generationAgent?.limits
-              ? t.maxLengthCeiling
-                  .replace('{{maxOutputTokens}}', String(ceiling))
-                  .replace(
-                    '{{model}}',
-                    (generationAgent.agent as { model?: string; name?: string }).model
-                      ?? generationAgent.agent.name,
-                  )
-              : t.maxLengthHelp}
-          </p>
         </div>
       </div>
 
+      {/* The bound, as a full sentence — which is why it lives UNDER the row,
+          never inside the 5.5rem Max Length column: a sentence in that box
+          wraps one word per line and its height taxes the whole flex row. */}
+      <p className="semiont-form__help semiont-form__help--row">
+        {generationAgent?.limits
+          ? t.maxLengthCeiling
+              .replace('{{maxOutputTokens}}', String(ceiling))
+              .replace(
+                '{{model}}',
+                (generationAgent.agent as { model?: string; name?: string }).model
+                  ?? generationAgent.agent.name,
+              )
+          : t.maxLengthHelp}
+      </p>
+
       <WizardFooter
-        backLabel={t.back}
-        onBack={onBack}
+        {...(onBack && t.back ? { backLabel: t.back, onBack } : {})}
         primary={{ label: t.generate, type: 'submit' }}
       />
     </form>

package/src/components/modals/ConfigureSearchStep.tsx

@@ -16,8 +16,13 @@ export interface ConfigureSearchStepProps {
    * invites the press. The wizard owns it for the modal's lifetime instead.
    */
   config: SearchConfig;
+  /** Echo of the gather step's hint — the thing being steered stays visible (GEP D8). */
+  hintEcho?: { label: string; value: string };
   onConfigChange: (config: SearchConfig) => void;
   isSearching?: boolean;
+  /** A settled failure (emit refused, matcher error, timeout) — the spinner
+   *  must never outlive the request that fed it. */
+  searchError?: string | null;
   onBack: () => void;
   onSearch: (config: SearchConfig) => void;
   translations: {
@@ -27,13 +32,16 @@ export interface ConfigureSearchStepProps {
     back: string;
     search: string;
     searching: string;
+    searchFailed: string;
   };
 }
 
 export function ConfigureSearchStep({
   config,
+  hintEcho,
   onConfigChange,
   isSearching = false,
+  searchError = null,
   onBack,
   onSearch,
   translations: t,
@@ -45,6 +53,11 @@ export function ConfigureSearchStep({
 
   return (
     <form onSubmit={handleSubmit} className="semiont-form">
+      {hintEcho && (
+        <p className="semiont-wizard__hint-echo">
+          {hintEcho.label}: {hintEcho.value}
+        </p>
+      )}
       {/* Max Results */}
       <div className="semiont-form__field">
         <label htmlFor="wizard-limit" className="semiont-form__label">
@@ -78,6 +91,12 @@ export function ConfigureSearchStep({
         </p>
       </div>
 
+      {searchError && (
+        <div role="alert" style={{ textAlign: 'center', padding: '0.5rem 0', color: 'var(--semiont-color-red-600)' }}>
+          {t.searchFailed}: {searchError}
+        </div>
+      )}
+
       <WizardFooter
         backLabel={t.back}
         onBack={onBack}

package/src/components/modals/ContextSummary.tsx

@@ -1,13 +1,17 @@
 'use client';
 
-import { deriveViews, type GatheredContext } from '@semiont/core';
+import { deriveViews, getBodySource, getExactText, getTargetSelector, type GatheredContext } from '@semiont/core';
 
 export interface ContextSummaryTranslations {
   sourceContextLabel: string;
   connectionsLabel: string;
   citedByLabel: string;
-  userHintLabel: string;
-  userHintPlaceholder: string;
+  /** GEP P2: the graph pane's chrome travels with this component (D10). */
+  graphPaneTitle: string;
+  /** Strategy-relevant empty state — emptiness is evidence (GEP D1). */
+  graphEmpty: string;
+  /** Resource-level linking annotation whose target the graph can't name. */
+  resourceLinkLabel: string;
 }
 
 export interface ContextSummaryProps {
@@ -18,85 +22,194 @@ export interface ContextSummaryProps {
 export function ContextSummary({ context, translations: t }: ContextSummaryProps) {
   // Graph views are focus-agnostic — only the focal resource id (and an optional
   // focal annotation id) differ by kind.
+  // ResourceDescriptor's identifier is `@id` (JSON-LD) — its open index
+  // signature makes a bare `.id` deref compile and silently yield undefined.
   const mainResourceId = context.focus.kind === 'annotation'
-    ? String(context.focus.sourceResource.id)
-    : String(context.focus.resource.id);
+    ? context.focus.sourceResource['@id']
+    : context.focus.resource['@id'];
   const focalAnnotationId = context.focus.kind === 'annotation'
     ? context.focus.annotation.id
     : undefined;
-  const { connections, citedBy, citedByCount } = deriveViews(
+  const { connections, citedBy } = deriveViews(
     context.graph,
     mainResourceId,
     focalAnnotationId,
   );
 
+  // Sibling NODES — the same structural annotation-of walk core uses for its
+  // entity-type set, collected at node granularity because the viz draws them
+  // (GEP P4; core's `siblingEntityTypes` stays the prompt-side view).
+  const annotationOf = new Map<string, string>();
+  for (const edge of context.graph.edges) {
+    if (edge.type === 'annotation-of') annotationOf.set(edge.source, edge.target);
+  }
+  const siblings = context.graph.nodes.filter(
+    (n) => n.type === 'annotation' && n.id !== focalAnnotationId && annotationOf.get(n.id) === mainResourceId,
+  );
+
+  // Rarity-ranked entity types for hover-text — the IDF semantics
+  // `entityTypeFrequencies` was stored for (D3).
+  const freq: Record<string, number> =
+    (context.metadata?.entityTypeFrequencies as Record<string, number> | undefined) ?? {};
+  const rank = (types: string[]) => [...types].sort((a, b) => (freq[a] ?? 0) - (freq[b] ?? 0));
+
+  const firstBodyValue = (body: unknown): string | undefined => {
+    // Tagging-purpose bodies are the entity-type tag — already shown via
+    // entityTypes, so skip them rather than repeat the type in the hover.
+    for (const item of Array.isArray(body) ? body : [body]) {
+      if (item && typeof item === 'object' && 'value' in item
+        && (item as { purpose?: string }).purpose !== 'tagging') {
+        return (item as { value?: string }).value;
+      }
+    }
+    return undefined;
+  };
+
+  // ── Deterministic layered layout (D3): citers | focal + siblings | peers ──
+  // Positions derive from array order alone — no physics, no randomness.
+  // Geometry adapts to what's populated (no-clipping principle): an absent
+  // citer/peer layer frees its column for the sibling band to wrap into, and
+  // the viewBox shrinks to the columns actually used. Everything always draws
+  // — overflow rides the wizard pane's scroll, never a cap.
+  const NODE_W = 180;
+  const NODE_H = 34;
+  const ROW = 52;
+  const TOP = 8;
+  const COL_PITCH = 216;
+  const colX = (col: number) => 8 + col * COL_PITCH;
+
+  type DrawnNode = {
+    id: string; label: string; kind: 'focal' | 'resource' | 'annotation';
+    hover: string; x: number; y: number;
+  };
+  type DrawnEdge = { key: string; kind: 'cites' | 'peer' | 'annotation-of'; hover: string;
+    x1: number; y1: number; x2: number; y2: number };
+
+  const focalNode = context.graph.nodes.find((n) => n.id === mainResourceId);
+  const focalLabel = focalNode?.label
+    ?? (context.focus.kind === 'annotation' ? context.focus.sourceResource.name : context.focus.resource.name)
+    ?? mainResourceId;
+
+  const drawn: DrawnNode[] = [];
+  const drawnEdges: DrawnEdge[] = [];
+
+  // The sibling band wraps across the columns absent layers free (3 total).
+  const hasCiters = citedBy.length > 0;
+  const hasPeers = connections.length > 0;
+  const bandCols = Math.max(1, Math.min(
+    3 - (hasCiters ? 1 : 0) - (hasPeers ? 1 : 0),
+    siblings.length,
+  ));
+  const bandCol0 = hasCiters ? 1 : 0;
+  const numCols = (hasCiters ? 1 : 0) + bandCols + (hasPeers ? 1 : 0);
+
+  const focal: DrawnNode = { id: mainResourceId, label: focalLabel, kind: 'focal', hover: focalLabel, x: colX(bandCol0), y: TOP };
+  drawn.push(focal);
+
+  citedBy.forEach((c, i) => {
+    const node: DrawnNode = { id: c.resourceId, label: c.resourceName, kind: 'resource',
+      hover: `${c.resourceName}\n${t.citedByLabel}`, x: colX(0), y: TOP + i * ROW };
+    drawn.push(node);
+    drawnEdges.push({ key: `cites-${c.resourceId}`, kind: 'cites', hover: 'cites',
+      x1: node.x + NODE_W, y1: node.y + NODE_H / 2, x2: focal.x, y2: focal.y + NODE_H / 2 });
+  });
+
+  connections.forEach((c, i) => {
+    const types = rank(c.entityTypes);
+    const node: DrawnNode = { id: c.resourceId, label: c.resourceName, kind: 'resource',
+      hover: types.length ? `${c.resourceName}\n${types.join(', ')}` : c.resourceName,
+      x: colX(bandCol0 + bandCols), y: TOP + i * ROW };
+    drawn.push(node);
+    // With a multi-column band the line crosses the band's row 0, which only
+    // ever holds the focal node in the band's FIRST column — so it stays clear.
+    drawnEdges.push({ key: `peer-${c.resourceId}`, kind: 'peer',
+      hover: c.bidirectional ? `${t.connectionsLabel} · mutual` : t.connectionsLabel,
+      x1: focal.x + NODE_W, y1: focal.y + NODE_H / 2, x2: node.x, y2: node.y + NODE_H / 2 });
+  });
+
+  siblings.forEach((s, i) => {
+    // Discriminated: type === 'annotation' guarantees the embedded W3C
+    // annotation (P3/D11). The node's identity is the text it wraps — a
+    // column of motivation labels is uninterpretable; motivation shows as
+    // the node's styling and hover instead.
+    const ann = s.type === 'annotation' ? s.annotation : undefined;
+    const quote = ann ? getExactText(getTargetSelector(ann.target)) : '';
+    const motivation = ann?.motivation ?? s.label;
+    const body = ann ? firstBodyValue(ann.body) : undefined;
+    const types = rank(s.entityTypes ?? []);
+    // A resource-level annotation has no selector — nothing to quote — but is
+    // ABOUT a target resource: label it by what it links to. Raw motivation
+    // ("linking") is internal vocabulary and stays hover-only.
+    const linkTarget = !quote && ann ? getBodySource(ann.body) : null;
+    const linkedName = linkTarget
+      ? context.graph.nodes.find((n) => n.id === linkTarget)?.label
+      : undefined;
+    const label = quote
+      || (linkedName ? `→ ${linkedName}` : undefined)
+      || (linkTarget ? t.resourceLinkLabel : undefined)
+      || body
+      || s.label;
+    // Hover leads with the full label — the drawn one truncates (like the
+    // resource nodes, whose hover carries the full name). Deduped: a label
+    // that fell through to the body or motivation must not repeat below it.
+    const hover = Array.from(new Set(
+      [label, motivation, body, types.length ? types.join(', ') : undefined].filter(Boolean),
+    )).join('\n');
+    const node: DrawnNode = { id: s.id, label, kind: 'annotation',
+      hover, x: colX(bandCol0 + (i % bandCols)), y: TOP + (1 + Math.floor(i / bandCols)) * ROW };
+    drawn.push(node);
+    drawnEdges.push({ key: `annof-${s.id}`, kind: 'annotation-of', hover: 'annotation-of',
+      x1: focal.x + NODE_W / 2, y1: focal.y + NODE_H, x2: node.x + NODE_W / 2, y2: node.y });
+  });
+
+  const rows = Math.max(citedBy.length, 1 + Math.ceil(siblings.length / bandCols), connections.length);
+  const width = numCols * COL_PITCH - 20;
+  const height = TOP + rows * ROW + 8;
+  const truncate = (s: string) => (s.length > 22 ? `${s.slice(0, 21)}…` : s);
+  const hasBody = connections.length > 0 || citedBy.length > 0 || siblings.length > 0;
+
+  // GEP P4: this component IS the graph pane, and its body IS a graph — a
+  // hand-rolled deterministic SVG (D3: no physics, no library, no pan-zoom;
+  // a decision surface, not an explorer). Chrome travels with the component,
+  // so every consumer inherits it (D10). Emptiness is evidence (D1).
   return (
-    <>
-      {(connections.length > 0 || citedByCount > 0) && (
-        <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
-
-          {connections.length > 0 && (
-            <div>
-              <div style={{
-                fontSize: 'var(--semiont-text-xs)',
-                fontWeight: 700,
-                textTransform: 'uppercase',
-                letterSpacing: '0.06em',
-                color: 'var(--semiont-text-tertiary)',
-                marginBottom: '0.375rem',
-              }}>
-                {t.connectionsLabel}
-              </div>
-              <ul style={{ display: 'flex', flexDirection: 'column', gap: '0.375rem', listStyle: 'none', padding: 0, margin: 0 }}>
-                {connections.map(conn => (
-                  <li key={conn.resourceId} style={{
-                    display: 'flex',
-                    flexWrap: 'wrap',
-                    alignItems: 'center',
-                    gap: '0.375rem',
-                    fontSize: 'var(--semiont-text-sm)',
-                  }}>
-                    <span style={{ color: 'var(--semiont-text-primary)', fontWeight: 500 }}>{conn.resourceName}</span>
-                    {conn.bidirectional && (
-                      <span className="semiont-chip" style={{ fontSize: 'var(--semiont-text-xs)', padding: '0.125rem 0.375rem' }}>mutual</span>
-                    )}
-                    {conn.entityTypes && conn.entityTypes.map(et => (
-                      <span key={et} className="semiont-chip" style={{ fontSize: 'var(--semiont-text-xs)', padding: '0.125rem 0.375rem' }}>
-                        {et}
-                      </span>
-                    ))}
-                  </li>
-                ))}
-              </ul>
-            </div>
-          )}
-
-          {citedByCount > 0 && (
-            <div>
-              <div style={{
-                fontSize: 'var(--semiont-text-xs)',
-                fontWeight: 700,
-                textTransform: 'uppercase',
-                letterSpacing: '0.06em',
-                color: 'var(--semiont-text-tertiary)',
-                marginBottom: '0.375rem',
-              }}>
-                {t.citedByLabel} ({citedByCount})
-              </div>
-              {citedBy.length > 0 && (
-                <ul style={{ display: 'flex', flexDirection: 'column', gap: '0.25rem', listStyle: 'none', padding: 0, margin: 0 }}>
-                  {citedBy.map(ref => (
-                    <li key={ref.resourceId} style={{ fontSize: 'var(--semiont-text-sm)', color: 'var(--semiont-text-primary)', fontWeight: 500 }}>
-                      {ref.resourceName}
-                    </li>
-                  ))}
-                </ul>
-              )}
-            </div>
-          )}
-
-        </div>
+    <div className="semiont-gather-pane semiont-gather-pane--graph">
+      <div className="semiont-gather-pane__title">{t.graphPaneTitle}</div>
+      {context.inferredRelationshipSummary && (
+        <p className="semiont-gather-pane__summary">{context.inferredRelationshipSummary}</p>
+      )}
+      {!hasBody && (
+        <p className="semiont-gather-pane__empty">{t.graphEmpty}</p>
+      )}
+      {hasBody && (
+          <svg
+            className="semiont-graph"
+            viewBox={`0 0 ${width} ${height}`}
+            // Natural-size cap: 1 viewBox unit never exceeds 1px, so a compact
+            // graph renders small instead of stretching to fill the pane.
+            style={{ maxWidth: `${width}px` }}
+            role="img"
+            aria-label={t.graphPaneTitle}
+          >
+            {drawnEdges.map((e) => (
+              <g key={e.key} className={`semiont-graph__edge semiont-graph__edge--${e.kind}`}>
+                <line x1={e.x1} y1={e.y1} x2={e.x2} y2={e.y2} />
+                <title>{e.hover}</title>
+              </g>
+            ))}
+            {drawn.map((n) => (
+              <g
+                key={n.id}
+                className={`semiont-graph__node semiont-graph__node--${n.kind}`}
+                data-node-id={n.id}
+              >
+                <rect x={n.x} y={n.y} width={NODE_W} height={NODE_H} rx={6} />
+                <text x={n.x + 10} y={n.y + 22}>{truncate(n.label)}</text>
+                <title>{n.hover}</title>
+              </g>
+            ))}
+          </svg>
       )}
-    </>
+    </div>
   );
 }

package/src/components/modals/CorpusPane.tsx

@@ -0,0 +1,75 @@
+'use client';
+
+import type { GatheredContext } from '@semiont/core';
+
+export interface CorpusPaneTranslations {
+  corpusPaneTitle: string;
+  /** Strategy-relevant empty state — emptiness is evidence (GEP D1). */
+  corpusEmpty: string;
+  /** Label for the match's cosine score. */
+  score: string;
+  /** The filter receipt; interpolates `{{types}}`. */
+  excludedReceipt: string;
+  /** The trust marker for machine-read (OCR) sources. */
+  machineRead: string;
+}
+
+export interface CorpusPaneProps {
+  semanticContext: GatheredContext['semanticContext'];
+  translations: CorpusPaneTranslations;
+}
+
+/**
+ * The corpus pane (GEP D4): latent knowledge — ranked `SemanticMatch` cards,
+ * read-only. THE datum for Search-vs-Generate ("does the KB already discuss
+ * this?"). This is recall-at-gather evidence, not a preview of Search: the
+ * matcher re-runs fresh (selected text + hint, scoring) and may rank
+ * differently.
+ *
+ * Read-only for now by decision, not forever — when per-match actions arrive
+ * they route through the footer's fork or a designed extension of it, never
+ * ad-hoc buttons here.
+ */
+export function CorpusPane({ semanticContext, translations: t }: CorpusPaneProps) {
+  // Descending by score, whatever order the wire delivered.
+  const matches = [...(semanticContext?.similar ?? [])].sort((a, b) => b.score - a.score);
+  const excluded = semanticContext?.excludedEntityTypes ?? [];
+
+  return (
+    <div className="semiont-gather-pane semiont-gather-pane--corpus">
+      <div className="semiont-gather-pane__title">{t.corpusPaneTitle}</div>
+      {matches.length === 0 ? (
+        <p className="semiont-gather-pane__empty">{t.corpusEmpty}</p>
+      ) : (
+        <ul className="semiont-corpus__list">
+          {matches.map((m, i) => (
+            <li key={`${m.resourceId}-${i}`} className="semiont-corpus__card">
+              <div className="semiont-corpus__card-head">
+                <span className="semiont-corpus__source">{m.resourceName}</span>
+                {(m.entityTypes ?? []).map((et) => (
+                  <span key={et} className="semiont-chip" style={{ fontSize: 'var(--semiont-text-xs)', padding: '0.125rem 0.375rem', fontWeight: 400 }}>
+                    {et}
+                  </span>
+                ))}
+                {m.machineRead && (
+                  <span className="semiont-chip semiont-corpus__trust" style={{ fontSize: 'var(--semiont-text-xs)', padding: '0.125rem 0.375rem', fontWeight: 400 }}>
+                    {t.machineRead}
+                  </span>
+                )}
+                {/* 0–1 cosine to two places — deliberately NOT the search step's
+                    raw render, which is a different scale (logged deviation). */}
+                <span className="semiont-corpus__score">{t.score}: {m.score.toFixed(2)}</span>
+              </div>
+              <p className="semiont-corpus__snippet">{m.text}</p>
+            </li>
+          ))}
+        </ul>
+      )}
+      {excluded.length > 0 && (
+        <p className="semiont-corpus__receipt">
+          {t.excludedReceipt.replace('{{types}}', excluded.join(', '))}
+        </p>
+      )}
+    </div>
+  );
+}

package/src/components/modals/DiscardPrompt.tsx

@@ -0,0 +1,38 @@
+'use client';
+
+/**
+ * The inline discard band (COMPOSE-IN-MODAL D4, shared by GATHER-AT-THE-TOP
+ * P1): a modal dies on ✕/Escape/backdrop, but typed work must not die with
+ * it. Hosts route ALL dismissal through one handler; when the draft is dirty
+ * that handler shows this band instead of closing. Success paths never come
+ * here — the guard protects dismissal, not completion.
+ */
+interface DiscardPromptProps {
+  prompt: string;
+  discardLabel: string;
+  keepLabel: string;
+  onDiscard: () => void;
+  onKeepEditing: () => void;
+}
+
+export function DiscardPrompt({ prompt, discardLabel, keepLabel, onDiscard, onKeepEditing }: DiscardPromptProps) {
+  return (
+    <div className="semiont-wizard__discard-prompt" role="alert">
+      <span className="semiont-wizard__discard-prompt-text">{prompt}</span>
+      <button
+        type="button"
+        className="semiont-button--danger"
+        onClick={onDiscard}
+      >
+        {discardLabel}
+      </button>
+      <button
+        type="button"
+        className="semiont-button--secondary"
+        onClick={onKeepEditing}
+      >
+        {keepLabel}
+      </button>
+    </div>
+  );
+}