docs: add JSDoc to exported viewer and app shell components

src/app/layout.tsx

@@ -27,6 +27,11 @@ export const metadata: Metadata = {
   description: "A static, zero-retention artifact viewer shell for fragment-based markdown, code, diff, CSV, and JSON payloads.",
 };
 
+/**
+ * Root layout for the static shell that installs fonts and global theme context for all viewer states.
+ * Accepts `children` from Next.js app routing and wraps them with the shared `ThemeProvider`.
+ * Sets hydration-safe HTML/body structure used by lazy renderer mounts and fallback screens.
+ */
 export default function RootLayout({
   children,
 }: Readonly<{

src/app/page.tsx

@@ -1,5 +1,10 @@
 import { ViewerShell } from "@/components/viewer-shell";
 
+/**
+ * Entry page for the exported shell, routing users into the fragment-aware viewer workflow.
+ * It renders `ViewerShell` with no props because artifact state is derived from URL fragment parsing.
+ * Keeps page composition minimal so renderer loading and fallback logic stay inside the shell.
+ */
 export default function HomePage() {
   return <ViewerShell />;
 }

src/components/home/link-creator.tsx

@@ -72,6 +72,11 @@ function getDraftSignature(draft: LinkCreatorDraft) {
   return JSON.stringify(draft);
 }
 
+/**
+ * Builds shareable fragment links from pasted artifact content in the home empty state flow.
+ * Accepts `onPreviewHash` so the parent shell can preview the generated fragment before navigation.
+ * Generates links client-side with validation, and exposes inline copy/error/stale-result states.
+ */
 export function LinkCreator({ onPreviewHash }: LinkCreatorProps) {
   const [draft, setDraft] = useState<LinkCreatorDraft>(defaultLinkCreatorDraft);
   const [generatedLink, setGeneratedLink] = useState<GeneratedArtifactLink | null>(null);

src/components/renderers/code-renderer.tsx

@@ -146,6 +146,11 @@ const rainbowBrackets = ViewPlugin.fromClass(
   },
 );
 
+/**
+ * Presents code artifacts in a read-only CodeMirror surface for standalone and embedded renderer flows.
+ * Accepts `artifact`, optional `compact`, and `onReady` to notify parent renderers when mount is complete.
+ * Lazily loads language support, offers optional line wrapping, and falls back to baseline highlighting when needed.
+ */
 export function CodeRenderer({ artifact, compact = false, onReady }: CodeRendererProps) {
   const hostRef = useRef<HTMLDivElement | null>(null);
   const [wrapLines, setWrapLines] = useState(compact);

src/components/renderers/csv-renderer.tsx

@@ -12,6 +12,11 @@ type CsvRendererProps = {
 
 type CsvRow = Record<string, string>;
 
+/**
+ * Displays CSV artifacts as a read-only table grid in the viewer renderer slot.
+ * Takes `artifact` content and optional `onReady` callback for shell-level renderer readiness tracking.
+ * Parses CSV client-side and shows a clear fallback message when parsing fails.
+ */
 export function CsvRenderer({ artifact, onReady }: CsvRendererProps) {
   const parsed = useMemo(() => {
     const result = Papa.parse<string[]>(artifact.content, { skipEmptyLines: true });

src/components/renderers/diff-renderer.tsx

@@ -477,6 +477,11 @@ function DiffRendererContent({ artifact, onReady }: DiffRendererProps) {
   );
 }
 
+/**
+ * Renders diff artifacts as review-style unified/split views in the artifact stage.
+ * Uses `artifact` diff payload details and optional `onReady` callback when the active diff UI is mount-ready.
+ * Prefers parsed git patches, supports old/new content diffs, and falls back to raw patch output on parse/runtime errors.
+ */
 export function DiffRenderer({ artifact, onReady }: DiffRendererProps) {
   const resetKey = [
     artifact.id,

src/components/renderers/json-renderer.tsx

@@ -46,6 +46,11 @@ function JsonNode({ label, value, level = 0 }: { label?: string; value: JsonValu
   );
 }
 
+/**
+ * Shows JSON artifacts with a toggle between structured tree and raw code views.
+ * Receives `artifact` and optional `onReady`, including readiness updates across parse and view-mode changes.
+ * Falls back to raw-code display with an error notice when JSON parsing fails.
+ */
 export function JsonRenderer({ artifact, onReady }: JsonRendererProps) {
   const [view, setView] = useState<"tree" | "raw">("tree");
   const parsed = useMemo(() => {

src/components/renderers/markdown-renderer.tsx

@@ -55,6 +55,11 @@ const markdownSchema = {
   },
 };
 
+/**
+ * Displays markdown artifacts in the primary viewer stage using sanitized GFM output.
+ * Consumes `artifact` content and optional `onReady`, which fires after embedded fenced code blocks report ready.
+ * Reuses the CodeMirror renderer for code fences and keeps raw HTML disabled for safer rendering.
+ */
 export function MarkdownRenderer({ artifact, onReady }: MarkdownRendererProps) {
   const heading = artifact.title ?? artifact.filename ?? artifact.id;
   const embeddedBlockCount = useMemo(() => (artifact.content.match(/```[\s\S]*?```/g) ?? []).length, [artifact.content]);

src/components/theme-provider.tsx

@@ -2,6 +2,11 @@
 
 import { ThemeProvider as NextThemesProvider, type ThemeProviderProps } from "next-themes";
 
+/**
+ * Wraps the app shell with next-themes so viewer and renderer surfaces share a consistent theme context.
+ * Forwards standard `ThemeProviderProps`, including children and theme configuration from the root layout.
+ * Runs client-side to avoid hydration mismatches while preserving system-theme defaults.
+ */
 export function ThemeProvider({ children, ...props }: ThemeProviderProps) {
   return <NextThemesProvider {...props}>{children}</NextThemesProvider>;
 }

src/components/theme-toggle.tsx

@@ -9,6 +9,11 @@ type ThemeToggleProps = {
   className?: string;
 };
 
+/**
+ * Provides the viewer header control for switching between dark and light presentation modes.
+ * Uses an optional `className` and next-themes setters to update active theme selection.
+ * Delays interaction until mount so icon/label state remains hydration-safe.
+ */
 export function ThemeToggle({ className }: ThemeToggleProps) {
   const { resolvedTheme, setTheme } = useTheme();
   const [mounted, setMounted] = useState(false);

src/components/viewer/artifact-selector.tsx

@@ -12,6 +12,11 @@ type ArtifactSelectorProps = {
   getSupportingLabel: (artifact: ArtifactPayload) => string;
 };
 
+/**
+ * Renders artifact tabs in the viewer header so users can switch within a decoded bundle.
+ * Uses `artifacts`, `activeArtifactId`, and `onSelect` to drive selection, plus heading/label formatters.
+ * Keeps navigation in UI state with icon + metadata badges for each artifact kind.
+ */
 export function ArtifactSelector({
   artifacts,
   activeArtifactId,

src/components/viewer/fragment-details-disclosure.tsx

@@ -9,6 +9,11 @@ type FragmentDetailsDisclosureProps = {
   hashPreview: string;
 };
 
+/**
+ * Shows protocol diagnostics for the current fragment payload in a collapsible viewer panel.
+ * Receives status, codec, length budget, and hash preview props from the shell-level decode state.
+ * Stays read-only and provides quick visibility into transport/fallback conditions.
+ */
 export function FragmentDetailsDisclosure({
   statusLabel,
   statusMessage,