@lostgradient/cinder 0.3.0 → 0.4.0

package/src/components/radio-group/radio-group.examples.json

@@ -7,19 +7,19 @@
       "id": "basic",
       "title": "Basic radio group",
       "description": "Three options with a group legend; arrow keys move selection.",
-      "code": "<script lang=\"ts\">\n  import { RadioGroup } from '@lostgradient/cinder/radio-group';\n\n  let plan = $state('pro');\n</script>\n\n<RadioGroup name=\"plan\" legend=\"Pricing tier\" bind:value={plan}>\n  <RadioGroup.Option id=\"plan-free\" value=\"free\" label=\"Free — for individuals exploring Cinder\" />\n  <RadioGroup.Option id=\"plan-pro\" value=\"pro\" label=\"Pro — small teams, includes private support\" />\n  <RadioGroup.Option id=\"plan-team\" value=\"team\" label=\"Team — SSO, audit logs, role-based access\" />\n</RadioGroup>\n"
+      "code": "<script lang=\"ts\">\n  import { RadioGroup } from '@lostgradient/cinder/radio-group';\n\n  let plan = $state('pro');\n</script>\n\n<RadioGroup name=\"plan\" label=\"Pricing tier\" bind:value={plan}>\n  <RadioGroup.Option id=\"plan-free\" value=\"free\" label=\"Free — for individuals exploring Cinder\" />\n  <RadioGroup.Option id=\"plan-pro\" value=\"pro\" label=\"Pro — small teams, includes private support\" />\n  <RadioGroup.Option id=\"plan-team\" value=\"team\" label=\"Team — SSO, audit logs, role-based access\" />\n</RadioGroup>\n"
     },
     {
       "id": "disabled",
       "title": "Disabled radio group",
       "description": "Disabling the group disables every radio inside.",
-      "code": "<script lang=\"ts\">\n  import { RadioGroup } from '@lostgradient/cinder/radio-group';\n</script>\n\n<RadioGroup name=\"disabled-region\" legend=\"Region (locked for trial accounts)\" value=\"us\" disabled>\n  <RadioGroup.Option id=\"disabled-region-us\" value=\"us\" label=\"United States\" />\n  <RadioGroup.Option id=\"disabled-region-eu\" value=\"eu\" label=\"European Union\" />\n  <RadioGroup.Option id=\"disabled-region-ap\" value=\"ap\" label=\"Asia Pacific\" />\n</RadioGroup>\n"
+      "code": "<script lang=\"ts\">\n  import { RadioGroup } from '@lostgradient/cinder/radio-group';\n</script>\n\n<RadioGroup name=\"disabled-region\" label=\"Region (locked for trial accounts)\" value=\"us\" disabled>\n  <RadioGroup.Option id=\"disabled-region-us\" value=\"us\" label=\"United States\" />\n  <RadioGroup.Option id=\"disabled-region-eu\" value=\"eu\" label=\"European Union\" />\n  <RadioGroup.Option id=\"disabled-region-ap\" value=\"ap\" label=\"Asia Pacific\" />\n</RadioGroup>\n"
     },
     {
       "id": "with-error",
       "title": "Radio group with error",
       "description": "When validation fails, the group exposes an aria-describedby error message.",
-      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { RadioGroup } from '@lostgradient/cinder/radio-group';\n  let role = $state('');\n  let submitted = $state(false);\n  const showError = $derived(submitted && !role);\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 0.75rem; align-items: flex-start;\">\n  {#if showError}\n    <RadioGroup\n      name=\"with-error-role\"\n      legend=\"Role\"\n      description=\"Pick the role that best describes you.\"\n      bind:value={role}\n      error=\"Choose a role to continue.\"\n    >\n      <RadioGroup.Option id=\"with-error-role-engineer\" value=\"engineer\" label=\"Engineer\" />\n      <RadioGroup.Option id=\"with-error-role-designer\" value=\"designer\" label=\"Designer\" />\n      <RadioGroup.Option id=\"with-error-role-manager\" value=\"manager\" label=\"Manager\" />\n    </RadioGroup>\n  {:else}\n    <RadioGroup\n      name=\"with-error-role\"\n      legend=\"Role\"\n      description=\"Pick the role that best describes you.\"\n      bind:value={role}\n    >\n      <RadioGroup.Option id=\"with-error-role-engineer\" value=\"engineer\" label=\"Engineer\" />\n      <RadioGroup.Option id=\"with-error-role-designer\" value=\"designer\" label=\"Designer\" />\n      <RadioGroup.Option id=\"with-error-role-manager\" value=\"manager\" label=\"Manager\" />\n    </RadioGroup>\n  {/if}\n\n  <Button variant=\"secondary\" onclick={() => (submitted = true)}>Try to submit</Button>\n</div>\n"
+      "code": "<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { RadioGroup } from '@lostgradient/cinder/radio-group';\n  let role = $state('');\n  let submitted = $state(false);\n  const showError = $derived(submitted && !role);\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 0.75rem; align-items: flex-start;\">\n  {#if showError}\n    <RadioGroup\n      name=\"with-error-role\"\n      label=\"Role\"\n      description=\"Pick the role that best describes you.\"\n      bind:value={role}\n      error=\"Choose a role to continue.\"\n    >\n      <RadioGroup.Option id=\"with-error-role-engineer\" value=\"engineer\" label=\"Engineer\" />\n      <RadioGroup.Option id=\"with-error-role-designer\" value=\"designer\" label=\"Designer\" />\n      <RadioGroup.Option id=\"with-error-role-manager\" value=\"manager\" label=\"Manager\" />\n    </RadioGroup>\n  {:else}\n    <RadioGroup\n      name=\"with-error-role\"\n      label=\"Role\"\n      description=\"Pick the role that best describes you.\"\n      bind:value={role}\n    >\n      <RadioGroup.Option id=\"with-error-role-engineer\" value=\"engineer\" label=\"Engineer\" />\n      <RadioGroup.Option id=\"with-error-role-designer\" value=\"designer\" label=\"Designer\" />\n      <RadioGroup.Option id=\"with-error-role-manager\" value=\"manager\" label=\"Manager\" />\n    </RadioGroup>\n  {/if}\n\n  <Button variant=\"secondary\" onclick={() => (submitted = true)}>Try to submit</Button>\n</div>\n"
     }
   ]
 }

package/src/components/radio-group/radio-group.svelte

@@ -25,11 +25,12 @@
     errorId as buildErrorId,
   } from '../../_internal/field-control.ts';
   import { classNames } from '../../utilities/class-names.ts';
+  import { devWarn } from '../../utilities/dev-warn.ts';
 
   let {
     value = $bindable(''),
     name,
-    legend,
+    label: legend,
     description,
     error,
     disabled = false,
@@ -66,6 +67,20 @@
       value = next;
     },
   });
+
+  // Warn once when no accessible group name is provided. The `hasWarned` flag
+  // stops the effect re-firing on every `legend` change — matching the
+  // tree.svelte convention and dev-warn.ts's guidance against a warn-only
+  // effect that re-subscribes on each update.
+  let hasWarnedNoLegend = false;
+  $effect(() => {
+    if (!legend && !hasWarnedNoLegend) {
+      hasWarnedNoLegend = true;
+      devWarn(
+        '[cinder/RadioGroup] A <fieldset> was rendered without a label prop. The fieldset will have no <legend>, which makes it inaccessible. Provide a label prop to describe the group.',
+      );
+    }
+  });
 </script>
 
 <!--
@@ -86,7 +101,12 @@
   data-variant={variant === 'card' ? 'card' : undefined}
 >
   {#if legend}
-    <legend class="cinder-radio-group__legend">{legend}</legend>
+    <legend class="cinder-radio-group__legend">
+      {legend}
+      {#if required}
+        <span class="cinder-_required-marker" aria-hidden="true">*</span>
+      {/if}
+    </legend>
   {/if}
 
   <div class="cinder-radio-group__items">

package/src/components/radio-group/radio-group.types.ts

@@ -24,8 +24,12 @@ export type RadioGroupProps = {
   value?: string;
   /** Shared `name` for all radios in the group; required for native form submission. */
   name: string;
-  /** Optional legend rendered as a `<legend>` inside the `<fieldset>`. */
-  legend?: string;
+  /**
+   * Visible group caption. Rendered as a `<legend>` inside the `<fieldset>`.
+   * Named `label` for consistency with every other form control — the element
+   * is a `<legend>` because the group is a fieldset.
+   */
+  label?: string;
   /** Helper text displayed below the group; wired via `aria-describedby` on the fieldset. */
   description?: string;
   /** Validation error message; sets `aria-invalid="true"` on the group's children. */

package/src/components/rating/README.md

@@ -17,24 +17,24 @@ Star rating control with bindable numeric value, optional half-star precision, a
 
 <!-- generated:props:start -->
 
-| Prop              | Type                  | Required | Default | Description                                                                                                                                                                                                                        |
-| ----------------- | --------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `aria-label`      | `string`              | no       | —       | Group accessible name when no visible `label` is supplied.                                                                                                                                                                         |
-| `aria-labelledby` | `string`              | no       | —       | Space-separated list of ids that label the group when no `label` is supplied.                                                                                                                                                      |
-| `class`           | `string`              | no       | —       | Extra class names appended to the root group element.                                                                                                                                                                              |
-| `count`           | `number`              | no       | —       | Number of rating slots. Normalized to an integer in `[1, 10]`; non-finite or out-of-range values fall back to `5`.                                                                                                                 |
-| `description`     | `string`              | no       | —       | Optional description text rendered below the rating.                                                                                                                                                                               |
-| `disabled`        | `boolean`             | no       | —       | Disable every rating control and the hidden input.                                                                                                                                                                                 |
-| `error`           | `string`              | no       | —       | Optional error message; sets `aria-invalid="true"` on the rating group.                                                                                                                                                            |
-| `hideLabel`       | `boolean`             | no       | —       | Visually hide the rendered `label` while keeping it programmatically associated.                                                                                                                                                   |
-| `id`              | `string`              | yes      | —       | Stable id used as the radio-group id prefix and as the hidden input id.                                                                                                                                                            |
-| `label`           | `string`              | no       | —       | Visible group label rendered above the rating.                                                                                                                                                                                     |
-| `name`            | `string`              | no       | —       | Form-control name applied to the hidden `<input>` that submits with the form.                                                                                                                                                      |
-| `precision`       | `"whole"` \| `"half"` | no       | —       | Precision of each step. Defaults to `'whole'`.                                                                                                                                                                                     |
-| `readonly`        | `boolean`             | no       | —       | Render a non-interactive display with an accessible text equivalent.                                                                                                                                                               |
-| `required`        | `boolean`             | no       | —       | Mark the group as required for assistive technology.                                                                                                                                                                               |
-| `value`           | `number`              | no       | —       | Bindable rating value. `0` represents an unrated state. External values are clamped into `[0, count]` and snapped to the nearest precision step.                                                                                   |
-| `onchange`        | `(opaque)`            | no       | —       | Fires only for user-initiated committed value changes (click, arrow keys, Space/Enter). Never fires for hover preview or external prop synchronization. Not expressible in JSON Schema; see the component types for the signature. |
+| Prop              | Type                  | Required | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ----------------- | --------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `aria-label`      | `string`              | no       | —       | Group accessible name when no visible `label` is supplied.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `aria-labelledby` | `string`              | no       | —       | Space-separated list of ids that label the group when no `label` is supplied.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `class`           | `string`              | no       | —       | Extra class names appended to the root group element.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `count`           | `number`              | no       | —       | Number of rating slots. Normalized to an integer in `[1, 10]`; non-finite or out-of-range values fall back to `5`.                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `description`     | `string`              | no       | —       | Optional description text rendered below the rating.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `disabled`        | `boolean`             | no       | —       | Disable every rating control and the hidden input.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `error`           | `string`              | no       | —       | Optional error message; sets `aria-invalid="true"` on the rating group.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `hideLabel`       | `boolean`             | no       | —       | Visually hide the rendered `label` while keeping it programmatically associated.                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `id`              | `string`              | yes      | —       | Stable id used as the radio-group id prefix and as the hidden input id.                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `label`           | `string`              | no       | —       | Visible group label rendered above the rating.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `name`            | `string`              | no       | —       | Form-control name applied to the hidden `<input>` that submits with the form.                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `precision`       | `"whole"` \| `"half"` | no       | —       | Precision of each step. Defaults to `'whole'`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `readonly`        | `boolean`             | no       | —       | Render a non-interactive display with an accessible text equivalent.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `required`        | `boolean`             | no       | —       | Mark the group as required for assistive technology.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `value`           | `number`              | no       | —       | Bindable rating value. `0` represents an unrated state. External values are clamped into `[0, count]` and snapped to the nearest precision step. **No write-back normalization.** The bound prop reflects exactly what the consumer set — it is NOT mutated back to the clamped/snapped value. The displayed and submitted value is normalized via `$derived`, but the binding itself is left untouched. This is intentional: the consumer owns the source of truth, and silent mutation of a bound prop is a surprising side-effect. |
+| `onchange`        | `(opaque)`            | no       | —       | Fires only for user-initiated committed value changes (click, arrow keys, Space/Enter). Never fires for hover preview or external prop synchronization. Not expressible in JSON Schema; see the component types for the signature.                                                                                                                                                                                                                                                                                                    |
 
 <!-- generated:props:end -->
 

package/src/components/rating/rating.svelte

@@ -79,14 +79,6 @@
 
   const resolvedValue = $derived(snapToOption(value ?? 0));
 
-  // Mirror normalized value back onto the prop without firing onchange so
-  // consumers always see a normalized number even when they pass garbage in.
-  $effect(() => {
-    if (resolvedValue !== value) {
-      value = resolvedValue;
-    }
-  });
-
   let hoverValue = $state<number | null>(null);
   const displayValue = $derived(hoverValue ?? resolvedValue);
 

package/src/components/rating/rating.types.ts

@@ -14,6 +14,12 @@ export type RatingProps = {
   /**
    * Bindable rating value. `0` represents an unrated state. External values
    * are clamped into `[0, count]` and snapped to the nearest precision step.
+   *
+   * **No write-back normalization.** The bound prop reflects exactly what the
+   * consumer set — it is NOT mutated back to the clamped/snapped value. The
+   * displayed and submitted value is normalized via `$derived`, but the binding
+   * itself is left untouched. This is intentional: the consumer owns the source
+   * of truth, and silent mutation of a bound prop is a surprising side-effect.
    */
   value?: number;
   /**

package/src/components/review-editor/comment-list.svelte

@@ -1,6 +1,6 @@
 <script lang="ts" module>
   import type { Comment } from '@lostgradient/cinder/commentary/comments';
-  import type { ReviewMode } from './review-editor-types.ts';
+  import type { ReviewMode } from './review-editor.types.ts';
 
   export type CommentListProps = {
     /** Comments to display */

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

@@ -18,7 +18,7 @@ export type {
   ReviewEditorViewType,
   ReviewFormData,
   ReviewMode,
-} from './review-editor-types';
+} from './review-editor.types.ts';
 
 // DEP-422: Extracted runes modules for state management (experimental)
 export { createReviewEditorState } from './review-editor-state.svelte';

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

@@ -3,7 +3,7 @@
   import type {
     ReviewEditorDiffViewMode as DiffViewMode,
     ReviewEditorViewType as ViewType,
-  } from './review-editor-types.ts';
+  } from './review-editor.types.ts';
 
   export type ReviewEditorControlsProps = {
     /** Unique ID for accessibility */
@@ -175,7 +175,7 @@
         title="Revert all changes"
       >
         <RotateCcw class="icon-sm" />
-        <span class="sr-only">Revert All</span>
+        <span class="cinder-sr-only">Revert All</span>
       </Button>
     {/if}
 
@@ -201,7 +201,12 @@
 </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 sr-only">
+<div
+  role="status"
+  aria-live="polite"
+  aria-atomic="true"
+  class="comments-count-announcer cinder-sr-only"
+>
   {liveAnnouncementText}
 </div>
 

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

@@ -7,9 +7,9 @@
     ReviewState,
     AnchorUpdate,
   } from '@lostgradient/cinder/commentary/comments';
-  import type { ReviewEditorProps, ReviewFormData } from './review-editor-types.ts';
+  import type { ReviewEditorProps, ReviewFormData } from './review-editor.types.ts';
 
-  export type { ReviewMode, ReviewEditorProps, ReviewFormData } from './review-editor-types.ts';
+  export type { ReviewMode, ReviewEditorProps, ReviewFormData } from './review-editor.types.ts';
 
   /** Type alias for thread ID to improve readability in state declarations */
   type ThreadId = string;
@@ -58,7 +58,7 @@
   import type {
     ReviewEditorDiffViewMode as DiffViewMode,
     ReviewEditorViewType as ViewType,
-  } from './review-editor-types.ts';
+  } from './review-editor.types.ts';
   import {
     getSelectionAnchorPosition,
     type SelectionAnchorPosition,
@@ -1000,7 +1000,9 @@
    * Includes document changes and comment threads
    * in a structured format suitable for LLM analysis.
    */
-  export function exportMarkdownSummary(options?: MarkdownSummaryOptions): MarkdownSummaryResult {
+  export function exportMarkdownSummary(
+    options: MarkdownSummaryOptions | undefined = undefined,
+  ): MarkdownSummaryResult {
     return generateMarkdownSummary(getState(), options);
   }
 
@@ -1008,7 +1010,9 @@
    * Export a Git-compatible unified diff.
    * The output can be applied with `git apply` or `patch` command.
    */
-  export function exportUnifiedDiff(options?: UnifiedDiffOptions): UnifiedDiffResult {
+  export function exportUnifiedDiff(
+    options: UnifiedDiffOptions | undefined = undefined,
+  ): UnifiedDiffResult {
     return generateUnifiedDiff(getState(), options);
   }
 
@@ -1683,12 +1687,12 @@
           plugins={[anchorPlugin]}
           {snapshotMode}
           onchange={handleEditorBodyChange}
-          onReady={() => {
+          onready={() => {
             if (!editorViewReady) {
               editorViewReady = true;
             }
           }}
-          onSelectionChange={handleSelectionChange}
+          onselectionchange={handleSelectionChange}
         />
       </div>
     {:else if activeView === 'diff'}

package/src/components/review-editor/review-editor-selection-types.ts

@@ -8,7 +8,7 @@ import type {
   PopoverPosition,
   ReviewMode,
   ReviewEditorViewType as ViewType,
-} from './review-editor-types.ts';
+} from './review-editor.types.ts';
 
 /**
  * Options for creating the selection popover manager.

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

@@ -25,7 +25,7 @@ import { extractMentions, generateId } from '@lostgradient/cinder/commentary/com
 import { devWarn } from '../../utilities/dev-warn.ts';
 import { getSelectionAnchorPosition } from './review-editor-selection-geometry.ts';
 import type { SelectionPopover, SelectionPopoverOptions } from './review-editor-selection-types.ts';
-import type { PopoverPosition } from './review-editor-types';
+import type { PopoverPosition } from './review-editor.types.ts';
 
 /** Debounce delay for selection position calculation (ms) */
 const SELECTION_DEBOUNCE_MS = 20;

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

@@ -20,7 +20,7 @@ import { normalize } from '@lostgradient/cinder/markdown/pipeline';
 import type {
   ReviewEditorDiffViewMode as DiffViewMode,
   ReviewEditorViewType as ViewType,
-} from './review-editor-types';
+} from './review-editor.types.ts';
 
 /**
  * Diff statistics for tracking content changes.

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

@@ -35,13 +35,13 @@ import {
 } from '@lostgradient/cinder/commentary/comments';
 import type { EditorView } from '@milkdown/kit/prose/view';
 import { devWarn } from '../../utilities/dev-warn.ts';
-import type { PopoverPosition, ReviewMode } from './review-editor-types';
+import type { PopoverPosition, ReviewMode } from './review-editor.types.ts';
 
 /** Type alias for thread ID to improve readability */
 type ThreadId = string;
 
 // Re-export PopoverPosition for backwards compatibility
-export type { PopoverPosition } from './review-editor-types';
+export type { PopoverPosition } from './review-editor.types.ts';
 
 /**
  * Options for creating the thread manager.

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

@@ -1,4 +1,92 @@
-import type { ReviewEditorProps as ReviewEditorImplementationProps } from './review-editor-types.ts';
+/**
+ * Shared types for ReviewEditor modules (DEP-422).
+ *
+ * @module
+ */
 
-/** Props for the ReviewEditor component. */
-export type ReviewEditorProps = ReviewEditorImplementationProps;
+import type {
+  CommentCreateEvent,
+  CommentDeleteEvent,
+  CommentUpdateEvent,
+  Thread,
+  ThreadCreateEvent,
+  ThreadDeleteEvent,
+} from '@lostgradient/cinder/commentary/comments';
+
+/** Review editor mode: edit allows full editing, readonly is view-only. */
+export type ReviewMode = 'edit' | 'readonly';
+
+/** Available review document views. */
+export type ReviewEditorViewType = 'editor' | 'diff' | 'summary';
+
+/** Available diff rendering modes in the review editor. */
+export type ReviewEditorDiffViewMode = 'unified' | 'final' | 'original';
+
+/** FormData structure returned by getFormData(). */
+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;
+};
+
+export type ReviewEditorProps = {
+  /** Unique identifier for accessibility (required). */
+  id: string;
+  /** Original/baseline content for diff comparison. */
+  original?: string;
+  /** Current markdown content (two-way bindable). */
+  value?: string;
+  /** Comment threads (two-way bindable). */
+  threads?: Thread[];
+  /** Editor mode. */
+  mode?: ReviewMode;
+  /** Current user ID for permissions. */
+  currentUserId?: string | undefined;
+  /** Placeholder text when empty. */
+  placeholder?: string;
+  /** Form field name prefix for hidden inputs (enables form participation). */
+  name?: string;
+  /** Additional CSS classes. */
+  class?: string;
+  /** Called when content changes. */
+  onchange?: (value: string) => void;
+  /** Called when user initiates thread creation. */
+  onthreadcreate?: (event: ThreadCreateEvent) => void;
+  /** Called when a thread is deleted. */
+  onthreaddelete?: (event: ThreadDeleteEvent) => void;
+  /** Called when a comment is created in an existing thread. */
+  oncommentcreate?: (event: CommentCreateEvent) => void;
+  /** Called when a comment is updated. */
+  oncommentupdate?: (event: CommentUpdateEvent) => void;
+  /** Called when a comment is deleted. */
+  oncommentdelete?: (event: CommentDeleteEvent) => void;
+
+  /**
+   * Snapshot mode for visual regression testing.
+   *
+   * When `true`:
+   * - Applies `caret-color: transparent` and `user-select: none` to the editor
+   *   root via a `data-snapshot-mode` attribute, producing a stable visual
+   *   state (no blinking cursor, no selection highlights).
+   * - Blurs any focused element inside the component on mount so the initial
+   *   screenshot does not capture a focused ring or active caret.
+   * - The inner MarkdownEditor instance also receives `snapshotMode={true}`.
+   *
+   * This is a purely visual / CSS concern. It does NOT affect editability,
+   * ProseMirror state, or any prop controlled by `readonly` / `mode`.
+   */
+  snapshotMode?: boolean;
+};
+
+/** Position for fixed-position popovers (viewport-relative coordinates) */
+export interface PopoverPosition {
+  x: number;
+  y: number;
+}

package/src/components/review-editor/thread-popover.svelte

@@ -1,6 +1,6 @@
 <script lang="ts" module>
   import type { Thread } from '@lostgradient/cinder/commentary/comments';
-  import type { ReviewMode } from './review-editor-types.ts';
+  import type { ReviewMode } from './review-editor.types.ts';
 
   export type ThreadPopoverProps = {
     /** Unique ID for accessibility */

package/src/components/run-step-timeline/README.md

@@ -1,6 +1,6 @@
 # RunStepTimeline
 
-Ordered step-by-step execution rail for async operations. Shows pending, running, succeeded, failed, cancelled, skipped, and retrying states with per-step durations, attempt counts, optional progress indicators, and expandable inline detail panels for logs, payloads, and errors.
+Ordered step-by-step execution rail for async operations. Shows pending, running, waiting approval, succeeded, failed, cancelled, skipped, and retrying states with per-step durations, attempt counts, action counts, optional progress indicators, nested child-workflow lanes, links, and expandable inline detail panels for logs, payloads, and errors.
 
 Use `RunStepTimeline` for CI jobs, workflow engine runs, import pipelines, deployment flows, and queue workers. Use `Timeline` for timestamp-first event logs. Use `Steps` for interactive wizard navigation.
 
@@ -12,10 +12,13 @@ Use `RunStepTimeline` for CI jobs, workflow engine runs, import pipelines, deplo
 - A status badge (text label so state is not communicated by color alone)
 - Start time, end time, and duration when available
 - An attempt count badge when the step has been retried
-- A progress bar for `running` or `retrying` steps with a known `progress` value
+- An action count badge when actions are available
+- An optional link rendered with `Link`
+- A progress bar for `running`, `retrying`, or `waiting_approval` steps with a known `progress` value
+- Indented child-workflow lanes from recursive `children`
 - Expandable Collapsible panels for logs, payloads, and errors via the `details` array
 
-The component marks the currently active step with `aria-current="step"`.
+The component marks the currently active step with `aria-current="step"`. `running`, `retrying`, and `waiting_approval` are current, non-terminal states.
 
 ## Usage
 
@@ -39,6 +42,10 @@ The component marks the currently active step with `aria-current="step"`.
       status: 'running',
       startTime: '2026-06-01T11:02:00Z',
       progress: 40,
+      link: {
+        href: '/runs/run-123/build',
+        label: 'Open logs',
+      },
     },
     {
       id: 'deploy',
@@ -93,12 +100,42 @@ The component marks the currently active step with `aria-current="step"`.
 </script>
 ```
 
+### With nested child-workflow lanes
+
+```svelte
+<script lang="ts">
+  import type { RunStep } from '@lostgradient/cinder/run-step-timeline';
+
+  const steps: RunStep[] = [
+    {
+      id: 'workflow',
+      label: 'Workflow',
+      status: 'running',
+      children: [
+        {
+          id: 'tool',
+          label: 'Run repository tool',
+          status: 'succeeded',
+          actionsCount: 2,
+        },
+        {
+          id: 'approval',
+          label: 'Await approval',
+          status: 'waiting_approval',
+        },
+      ],
+    },
+  ];
+</script>
+```
+
 ## Step states
 
 `RunStepStatus` is intentionally domain-agnostic. Map your domain state onto one of these:
 
 - `pending` — not yet started
-- `running` — currently executing (only one step should be running)
+- `running` — currently executing within its lane
+- `waiting_approval` — paused on required approval and expected to continue
 - `succeeded` — completed successfully
 - `failed` — completed with a terminal error
 - `cancelled` — stopped before it could complete
@@ -126,9 +163,12 @@ startTime    string           optional  ISO datetime when the step started.
 endTime      string           optional  ISO datetime when the step ended.
 duration     string           optional  Human-readable duration string, e.g. "1m 23s".
 attemptCount number           optional  Total attempts made; badge shown when greater than 1.
+actionsCount number           optional  Total associated actions; badge shown when greater than 0.
 progress     number           optional  Determinate progress value (0 to progressMax).
 progressMax  number           optional  Upper bound for progress. Defaults to 100.
 details      RunStepDetail[]  optional  Expandable inline panels for logs, payloads, errors.
+link         RunStepLink      optional  Link rendered in the step header.
+children     RunStep[]        optional  Nested child-workflow steps rendered as indented lanes.
 ```
 
 ### RunStepDetail shape
@@ -139,13 +179,20 @@ label    string  required  Trigger label on the Collapsible header.
 content  string  required  Pre-formatted content shown inside the panel.
 ```
 
+### RunStepLink shape
+
+```
+href   string  required  Destination URL for the step link.
+label  string  required  Visible link text.
+```
+
 ## Accessibility
 
 `RunStepTimeline` renders an `ol` (ordered list) because steps are numbered and sequential. The list takes an accessible name via `label` (used as `aria-label` when neither `aria-label` nor `aria-labelledby` is provided directly).
 
-The active step (`running` or `retrying`) receives `aria-current="step"` on its `li` element, matching the same pattern used by the `Steps` component. This allows assistive technology to identify which step is currently executing without requiring a live region announcement.
+The active step (`running`, `retrying`, or `waiting_approval`) receives `aria-current="step"` on its `li` element, matching the same pattern used by the `Steps` component. This allows assistive technology to identify which step is current without requiring a live region announcement.
 
-Status dots on the rail are decorative: the marker element is marked `aria-hidden="true"` and `inert`. The status badge rendered as text ensures the step state is communicated to assistive technology through text, not color alone (WCAG 1.4.1).
+Status dots on the rail are decorative: the marker element is marked `aria-hidden="true"` and `inert`. The status badge rendered as text includes an accessible label such as "Status: Waiting approval", so the step state is communicated to assistive technology through text, not color alone (WCAG 1.4.1).
 
 Progress bars include an `aria-label` derived from the step label (e.g. "Build Docker image progress"), satisfying the ARIA progressbar accessible name requirement.
 

package/src/components/run-step-timeline/index.ts

@@ -5,7 +5,13 @@ export default RunStepTimeline;
 export type {
   RunStep,
   RunStepDetail,
+  RunStepLink,
   RunStepStatus,
   RunStepTimelineProps,
+  RunStepTimelineSchemaChildStep,
+  RunStepTimelineSchemaGrandchildStep,
+  RunStepTimelineSchemaGreatGrandchildStep,
+  RunStepTimelineSchemaProps,
+  RunStepTimelineSchemaStep,
 } from './run-step-timeline.types.ts';
 export { RunStepTimeline };