@lostgradient/cinder 0.6.0 → 0.8.0

package/src/components/review-editor/review-editor-anchors.svelte.ts

@@ -0,0 +1,219 @@
+/**
+ * Anchor management for ReviewEditor (DEP-422).
+ *
+ * Handles:
+ * - Anchor plugin creation and configuration
+ * - Thread-to-plugin synchronization
+ * - Re-anchoring for setState flow
+ * - Fingerprinting to prevent sync thrashing
+ *
+ * **Note:** This module is experimental and provides an alternative implementation
+ * to the inline anchor management in `review-editor.svelte`. It is exported for
+ * testing and potential future refactoring, but the component does not currently
+ * delegate to this factory.
+ *
+ * @module
+ * @experimental
+ */
+import { anchorPluginKey, createAnchorPlugin, } from '@lostgradient/cinder/commentary/anchor-decorations';
+import { ANCHOR_CONTEXT_LENGTH, reanchorQuote } from '@lostgradient/cinder/commentary/comments';
+import { textOffsetToProseMirrorPosition } from '@lostgradient/cinder/editor';
+import { contentEquals } from '@lostgradient/cinder/markdown/pipeline';
+/**
+ * Create fingerprint including all mutable anchor fields.
+ * This prevents sync thrashing when quote/prefix/suffix change.
+ */
+function createSyncFingerprint(threads) {
+    return threads
+        .map((thread) => {
+        const anchor = thread.anchor;
+        return `${thread.id}:${anchor.from}:${anchor.to}:${anchor.quote}:${anchor.prefix}:${anchor.suffix}:${anchor.lastKnownOffset ?? ''}`;
+    })
+        .join('|');
+}
+/**
+ * Create an anchor manager.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createAnchorManager } from './review-editor-anchors.svelte';
+ *
+ *   const anchorManager = createAnchorManager({
+ *     getThreads: () => threads,
+ *     setThreads: (t) => (threads = t),
+ *     getEditorView: () => editorRef?.getView(),
+ *     getMarkdown: () => editorRef?.getMarkdown() ?? value,
+ *     getValue: () => value,
+ *     onAnchorClick: threadManager.handleAnchorClick,
+ *     onthreaddelete,
+ *   });
+ *
+ *   // Use plugin in MarkdownEditor
+ *   // <MarkdownEditor plugins={[anchorManager.plugin]} />
+ *
+ *   // Sync threads when they change
+ *   $effect(() => {
+ *     if (editorRef?.getView() && !anchorManager.pendingState) {
+ *       anchorManager.syncThreadsToPlugin(threads);
+ *     }
+ *   });
+ * </script>
+ * ```
+ */
+export function createAnchorManager(options) {
+    const { getThreads, setThreads, getEditorView, getMarkdown, getValue, onAnchorClick, onthreaddelete, } = options;
+    // Non-reactive bookkeeping (not state - doesn't need reactivity)
+    let lastSyncedFingerprint = null;
+    // Pending state for deferred re-anchoring
+    let pendingState = $state(null);
+    /**
+     * Handle anchor position updates from the plugin.
+     */
+    function handleAnchorsUpdate(updates) {
+        const threads = getThreads();
+        const updatedThreads = threads.map((thread) => {
+            const update = updates.find((u) => u.threadId === thread.id);
+            if (update) {
+                return {
+                    ...thread,
+                    anchor: {
+                        ...thread.anchor,
+                        from: update.from,
+                        to: update.to,
+                        quote: update.quote,
+                        prefix: update.prefix,
+                        suffix: update.suffix,
+                        lastKnownOffset: update.lastKnownOffset,
+                    },
+                };
+            }
+            return thread;
+        });
+        setThreads(updatedThreads);
+        // Update fingerprint to skip re-sync
+        lastSyncedFingerprint = createSyncFingerprint(updatedThreads);
+    }
+    // Create anchor plugin in instance scope
+    const plugin = createAnchorPlugin({
+        onAnchorsUpdate: handleAnchorsUpdate,
+        onAnchorClick,
+    });
+    /**
+     * Sync threads to the anchor plugin via meta-transaction.
+     */
+    function syncThreadsToPlugin(threads) {
+        const view = getEditorView();
+        if (!view)
+            return;
+        const fingerprint = createSyncFingerprint(threads);
+        // Skip if already synced
+        if (fingerprint === lastSyncedFingerprint)
+            return;
+        lastSyncedFingerprint = fingerprint;
+        view.dispatch(view.state.tr.setMeta(anchorPluginKey, {
+            type: 'sync',
+            threads,
+            source: 'external',
+        }));
+    }
+    /**
+     * Attempt re-anchoring for pending state.
+     * Threads whose anchor text cannot be found are removed (auto-delete behavior).
+     */
+    function attemptReanchoring() {
+        if (!pendingState)
+            return;
+        const view = getEditorView();
+        if (!view)
+            return;
+        // Compare markdown using contentEquals (handles normalization)
+        const currentMarkdown = getMarkdown();
+        const expectedMarkdown = pendingState.content;
+        if (!contentEquals(currentMarkdown, expectedMarkdown)) {
+            // Content not synced yet - will retry when editor updates
+            return;
+        }
+        const state = pendingState;
+        pendingState = null;
+        const { doc } = view.state;
+        const documentText = doc.textBetween(0, doc.content.size, '\n');
+        // Re-anchor threads, filtering out those that can't be found
+        const reanchoredThreads = [];
+        for (const persistedThread of state.threads) {
+            const result = reanchorQuote(documentText, persistedThread.anchor);
+            // If anchor text not found, skip this thread (auto-delete)
+            if (!result.found) {
+                onthreaddelete?.({ threadId: persistedThread.id });
+                continue;
+            }
+            const from = textOffsetToProseMirrorPosition(doc, result.from);
+            const to = textOffsetToProseMirrorPosition(doc, result.to);
+            if (from !== null && to !== null) {
+                // Extract the matched quote and context from the current document
+                const matchedQuote = documentText.slice(result.from, result.to);
+                const newPrefix = documentText.slice(Math.max(0, result.from - ANCHOR_CONTEXT_LENGTH), result.from);
+                const newSuffix = documentText.slice(result.to, Math.min(documentText.length, result.to + ANCHOR_CONTEXT_LENGTH));
+                reanchoredThreads.push({
+                    ...persistedThread,
+                    anchor: {
+                        ...persistedThread.anchor,
+                        from,
+                        to,
+                        quote: matchedQuote,
+                        prefix: newPrefix,
+                        suffix: newSuffix,
+                        status: 'anchored',
+                        lastKnownOffset: result.from,
+                    },
+                });
+            }
+        }
+        setThreads(reanchoredThreads);
+        // Sync threads to plugin
+        syncThreadsToPlugin(reanchoredThreads);
+    }
+    // Retry re-anchoring when editor content changes (handles async content sync)
+    $effect(() => {
+        void getValue(); // Create dependency on value
+        if (pendingState && getEditorView()) {
+            attemptReanchoring();
+        }
+    });
+    return {
+        get plugin() {
+            return plugin;
+        },
+        get pendingState() {
+            return pendingState;
+        },
+        setPendingState(state) {
+            pendingState = state;
+        },
+        attemptReanchoring,
+        syncThreadsToPlugin,
+        createSyncFingerprint,
+        handleAnchorsUpdate,
+    };
+}
+/**
+ * Convert threads to persisted format for serialization.
+ *
+ * @param threads - Live threads with position info
+ * @returns Persisted threads suitable for storage
+ */
+export function toPersistedThreads(threads) {
+    return threads.map((thread) => ({
+        ...thread,
+        anchor: {
+            quote: thread.anchor.quote,
+            prefix: thread.anchor.prefix,
+            suffix: thread.anchor.suffix,
+            status: thread.anchor.status,
+            blockId: thread.anchor.blockId,
+            originalPosition: thread.anchor.originalPosition,
+            originalQuote: thread.anchor.originalQuote,
+            lastKnownOffset: thread.anchor.lastKnownOffset,
+        },
+    }));
+}

package/src/components/review-editor/review-editor-controls.svelte

@@ -0,0 +1,201 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { classNames } from '../../utilities/class-names.ts';
+import Badge from '../badge/badge.svelte';
+import Button from '../button/button.svelte';
+import Segment from '../segment/segment.svelte';
+import SegmentedControl from '../segmented-control/segmented-control.svelte';
+import DiffStatistics from '../diff-statistics/diff-statistics.svelte';
+import FileText from 'lucide-svelte/icons/file-text';
+import GitBranch from 'lucide-svelte/icons/git-branch';
+import MessageSquare from 'lucide-svelte/icons/message-square';
+import Pencil from 'lucide-svelte/icons/pencil';
+import RotateCcw from 'lucide-svelte/icons/rotate-ccw';
+let { id, activeView, viewPanelIds, onViewChange, showDiffTabs = true, diffStats, diffViewMode = $bindable('unified'), hasContentChanges = false, readonly = false, onRevertAll, commentCount = 0, sidebarOpen = false, onSidebarToggle, trailing, class: className, } = $props();
+function handleViewChange(view) {
+    onViewChange?.(view);
+}
+const commentsToggleLabel = $derived(`${sidebarOpen ? 'Close' : 'Open'} comments sidebar (${commentCount} ${commentCount === 1 ? 'comment' : 'comments'})`);
+// Live announcer for comment count changes.
+let previousCommentCount = $state(null);
+let liveAnnouncementText = $state('');
+// This effect writes to the same $state it reads (previousCommentCount), which
+// would normally loop. It does not: each run sets previousCommentCount equal
+// to commentCount, so the re-run triggered by that write hits the
+// `commentCount === previousCommentCount` guard and exits without writing
+// again. Keep that invariant if you edit this — only write when the values
+// differ.
+$effect(() => {
+    // Do not announce on initial render — only on subsequent changes.
+    if (previousCommentCount === null) {
+        previousCommentCount = commentCount;
+        return;
+    }
+    if (commentCount !== previousCommentCount) {
+        previousCommentCount = commentCount;
+        liveAnnouncementText = `${commentCount} ${commentCount === 1 ? 'comment' : 'comments'}`;
+    }
+});
+</script>
+
+<div
+  {id}
+  class={classNames('review-editor-controls', className)}
+  role="toolbar"
+  aria-label="Review editor controls"
+>
+  <div class="controls-leading">
+    <SegmentedControl
+      id="{id}-view-mode"
+      label="Review editor view"
+      hideLabel
+      variant="tablist"
+      size="sm"
+      density="toolbar"
+      value={activeView}
+      onchange={handleViewChange}
+    >
+      <Segment value="editor" controls={viewPanelIds?.editor}>
+        {#snippet leading()}<Pencil class="cinder-icon-xs" />{/snippet}
+        Editor
+      </Segment>
+      {#if showDiffTabs}
+        <Segment value="diff" controls={viewPanelIds?.diff}>
+          {#snippet leading()}<GitBranch class="cinder-icon-xs" />{/snippet}
+          Diff
+        </Segment>
+        <Segment value="summary" controls={viewPanelIds?.summary}>
+          {#snippet leading()}<FileText class="cinder-icon-xs" />{/snippet}
+          Summary
+        </Segment>
+      {/if}
+    </SegmentedControl>
+
+    {#if diffStats && (diffStats.added > 0 || diffStats.removed > 0 || diffStats.modified > 0)}
+      <DiffStatistics
+        variant="compact"
+        density="toolbar"
+        added={diffStats.added}
+        removed={diffStats.removed}
+        modified={diffStats.modified}
+        hideZero
+      />
+    {/if}
+
+    {#if activeView === 'diff'}
+      <div class="controls-separator" aria-hidden="true"></div>
+      <SegmentedControl
+        id="{id}-diff-view-mode"
+        selectionMode="single"
+        size="sm"
+        density="toolbar"
+        label="Diff view mode"
+        hideLabel
+        bind:value={diffViewMode}
+      >
+        <Segment value="unified">Unified</Segment>
+        <Segment value="final">Final</Segment>
+        <Segment value="original">Original</Segment>
+      </SegmentedControl>
+    {/if}
+  </div>
+
+  <div class="controls-trailing">
+    {#if activeView === 'diff' && hasContentChanges && !readonly}
+      <Button
+        variant="ghost"
+        size="sm"
+        onclick={onRevertAll}
+        aria-label="Revert all changes"
+        title="Revert all changes"
+      >
+        <RotateCcw class="cinder-icon-sm" />
+        <span class="cinder-sr-only">Revert All</span>
+      </Button>
+    {/if}
+
+    <div class="comments-toggle-wrapper">
+      <Button
+        variant="ghost"
+        size="sm"
+        onclick={onSidebarToggle}
+        aria-expanded={sidebarOpen}
+        aria-controls="{id}-sidebar"
+        aria-label={commentsToggleLabel}
+        title={sidebarOpen ? 'Close comments sidebar' : 'Open comments sidebar'}
+      >
+        <MessageSquare class="cinder-icon-sm" />
+        <Badge aria-hidden="true" size="sm" variant="neutral">{commentCount}</Badge>
+      </Button>
+    </div>
+
+    {#if trailing}
+      {@render trailing()}
+    {/if}
+  </div>
+</div>
+
+<!-- Polite live announcer for comment count changes. Empty on initial render. -->
+<div
+  role="status"
+  aria-live="polite"
+  aria-atomic="true"
+  class="comments-count-announcer cinder-sr-only"
+>
+  {liveAnnouncementText}
+</div>
+
+<style>
+  .review-editor-controls {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--cinder-space-2);
+    padding: var(--cinder-space-1) var(--cinder-space-2);
+    /* Background inherited from .review-editor-container per surface nesting rule. */
+    border: 1px solid var(--cinder-border);
+    border-radius: var(--cinder-radius-md) var(--cinder-radius-md) 0 0;
+    border-bottom: none;
+    min-height: 2.5rem;
+    flex-wrap: wrap;
+  }
+
+  .controls-leading {
+    display: flex;
+    align-items: center;
+    gap: var(--cinder-space-2);
+    flex-wrap: wrap;
+  }
+
+  .controls-trailing {
+    display: flex;
+    align-items: center;
+    gap: var(--cinder-space-2);
+    flex-wrap: wrap;
+  }
+
+  .controls-separator {
+    width: 1px;
+    height: 1rem;
+    background: var(--cinder-border);
+    flex-shrink: 0;
+  }
+
+  /* =========================================================================
+   * Unified control heights
+   * The toolbar row uses --cinder-control-height-sm (32px) as the shared
+   * tier: SegmentedControl + DiffStatistics opt in via density="toolbar",
+   * Button (size="sm") already maps there through its alias. SegmentedControl's
+   * density="toolbar" pins min-block-size to that tier while delegating font
+   * and inline padding to its compact `sm` rule, so the toolbar row stays
+   * aligned without requiring per-instance height overrides below.
+   * ========================================================================= */
+
+  /* Comments toggle button with badge — locally scoped via the wrapper. */
+  .comments-toggle-wrapper :global(.cinder-button) {
+    gap: var(--cinder-space-1);
+  }
+</style>

package/src/components/review-editor/review-editor-exports.ts

@@ -0,0 +1,145 @@
+/**
+ * Pure export utilities for ReviewEditor.
+ *
+ * These functions work with ReviewState and don't require reactive context.
+ * They are stateless wrappers around the core export functions from @cinder/commentary/export.
+ *
+ * @module
+ */
+
+import type { ReviewState, Thread } from '@lostgradient/cinder/commentary/comments';
+import {
+  generateCommentsExport,
+  generateMarkdownSummary,
+  generateUnifiedDiff,
+  type MarkdownSummaryOptions,
+  type MarkdownSummaryResult,
+  type UnifiedDiffOptions,
+  type UnifiedDiffResult,
+} from '@lostgradient/cinder/commentary/export';
+
+/**
+ * FormData structure returned by buildFormData().
+ * Matches the hidden input values for form participation.
+ */
+export type ReviewFormData = {
+  /** Original/baseline content */
+  original: string;
+  /** Current edited content */
+  current: string;
+  /** Serialized comment threads as JSON */
+  comments: string;
+  /** Unified diff between original and current */
+  diff: string;
+  /** LLM-optimized summary markdown */
+  summary: string;
+};
+
+/**
+ * Build form data from review state.
+ *
+ * This pure function creates the same data structure that would be submitted
+ * via hidden form inputs. Use for programmatic API submissions.
+ *
+ * @param state - The current review state
+ * @returns Form data object matching hidden input values
+ */
+export function buildFormData(state: ReviewState): ReviewFormData {
+  return {
+    original: state.original ?? '',
+    current: state.content,
+    comments: JSON.stringify(state.threads),
+    diff: generateUnifiedDiff(state).diff,
+    summary: generateMarkdownSummary(state).markdown,
+  };
+}
+
+/**
+ * Build form data from individual values.
+ *
+ * Use this when you have the raw values but not a full ReviewState.
+ *
+ * @param original - Original/baseline content
+ * @param current - Current content
+ * @param threads - Comment threads
+ * @returns Form data object matching hidden input values
+ */
+export function buildFormDataFromValues(
+  original: string,
+  current: string,
+  threads: Thread[],
+): ReviewFormData {
+  const state: ReviewState = {
+    schemaVersion: 4,
+    content: current,
+    original,
+    threads: threads.map((t) => ({
+      ...t,
+      anchor: {
+        quote: t.anchor.quote,
+        prefix: t.anchor.prefix,
+        suffix: t.anchor.suffix,
+        status: t.anchor.status,
+        blockId: t.anchor.blockId,
+        originalPosition: t.anchor.originalPosition,
+        originalQuote: t.anchor.originalQuote,
+        lastKnownOffset: t.anchor.lastKnownOffset,
+      },
+    })),
+    updatedAt: new Date().toISOString(),
+  };
+
+  return buildFormData(state);
+}
+
+/**
+ * Export an LLM-optimized Markdown summary of the review.
+ *
+ * @param state - The review state to export
+ * @param options - Optional formatting options
+ * @returns Summary result with markdown content
+ */
+export function exportMarkdownSummary(
+  state: ReviewState,
+  options?: MarkdownSummaryOptions,
+): MarkdownSummaryResult {
+  return generateMarkdownSummary(state, options);
+}
+
+/**
+ * Export a Git-compatible unified diff.
+ *
+ * @param state - The review state to export
+ * @param options - Optional diff options (filename, context lines)
+ * @returns Diff result that can be applied with `git apply`
+ */
+export function exportUnifiedDiff(
+  state: ReviewState,
+  options?: UnifiedDiffOptions,
+): UnifiedDiffResult {
+  return generateUnifiedDiff(state, options);
+}
+
+/**
+ * Export comments as markdown.
+ *
+ * @param state - The review state to export
+ * @returns Markdown-formatted comments
+ */
+export function exportCommentsMarkdown(state: ReviewState): string {
+  return generateCommentsExport(state).markdown;
+}
+
+/**
+ * Get summary content without the heading.
+ *
+ * The heading is useful for clipboard exports but redundant in UI previews
+ * since the view tab already indicates this is a summary.
+ *
+ * @param state - The review state
+ * @returns Summary markdown without "# Review Summary" heading
+ */
+export function getSummaryContentWithoutHeading(state: ReviewState): string {
+  const result = generateMarkdownSummary(state);
+  return result.markdown.replace(/^# Review Summary\n+/, '');
+}