# Mirrored source-file study documents Use this workflow when comparing corresponding source files across platforms. The established example is `docs/render-platform-comparison.html`. For a single-file study, follow `docs/file-summary.md` instead. ## Source and scope - Read sources from the exact requested Git revision with `git show REV:path`. If no revision is specified, use HEAD and record its full commit hash. - Discover matching relative filenames beneath the two platform directories. State which platform-only files are excluded; never invent a counterpart. - Produce one downloadable, self-contained HTML document in `docs/`, with navigation links and one section per file pair. Preserve earlier documents unless removal is requested. - Record both source paths and the source revision. Preserve every source line, original line number, indentation and blank line. Escape HTML characters. ## Comparison layout - Use one table per pair with three columns: first platform's numbered source, second platform's numbered source, and explanation. Do not create separate line-by-line explanation tables or a Status column. - Align corresponding function starts where possible. Insert missing-line placeholders to keep later functions aligned; preserve source order and original numbers. For example, macOS renderEffect line 12 aligns with iOS line 16 at revision f0972f0d5ba796e3fa417081f43c00a9654b2aa6. - Within each function or intervening block, align lines sequentially unless better semantic alignment is needed. Equal line numbers need not share a row when function alignment requires padding. - Compare the exact source text in each aligned row, including whitespace. Fill BOTH line-number backgrounds green when they match. Fill numbers orange when they differ. A missing line is an orange-filled dash, not a plain dash. Keep code backgrounds neutral and retain syntax highlighting. - Include two filled statistics boxes beneath each section heading: green for matching line count and percentage, orange for mismatched count and percentage. Show the total line count as plain text alongside them. - Count actual lines across BOTH files, including blank lines. A matching pair contributes two matching lines; a differing pair contributes two mismatches; a platform-only line contributes one mismatch. Missing placeholders do not count. Percentages use the combined actual-line total. Recalculate after any alignment change, and explain this counting convention in the document. ## Explanations - Explain each distinct point once across the document, at its first relevant occurrence. Leave later cells empty unless they add information. - Eliminate semantic repetition, not just identical sentences. Do not repeat platform/import boilerplate such as “UIKit serves iOS” for every import. - Explain shared behavior once. Label iOS/macOS details only when needed to distinguish behavior. Explain the reason or consequence of platform differences. - Avoid redundant function summaries when the individual operations already explain the same behavior. Leave blank lines and closing braces unexplained. - When realigning rows, anchor each platform-specific explanation to its own source line rather than to the old visual row. ## Presentation and verification - Inline all CSS and syntax highlighting; no external fonts, scripts or requests. - Use `
`, `white-space: pre-wrap`, and `overflow-wrap: anywhere`.
  Give the code columns equal width; ensure long lines remain readable without
  horizontal scrolling. Do not use striped row shading.
- Verify every source line and number against the named Git revision, in order,
  with no omissions or duplicates. Check function anchors, placeholder fills,
  both matching-number fills, statistics, and explanation attachment.
- Review explanations for repeated clauses as well as repeated sentences.
- Inspect the rendered HTML for layout problems. Return a clickable file link;
  tell the user to refresh an already open document after updates.