feat: atlas projections -- mirror rendering, traceability matrix, coverage (goal 0064, ADR-0038) (#152)

One graph, three read surfaces, no new storage: MirrorContent (Go-side
goldmark render for markdown, plain text passthrough, base64 image,
type+size fallback for everything else, size-capped) resolves a card's
MirrorPath into the overlay; an editable Mirror path field lets a card
point at a file directly, since no write path sets it yet. The
traceability matrix and coverage counts project entirely from the
frontend's already-fetched card/link/kind data -- no new bound method,
pure and unit-tested like atlasGrouping.ts's existing derivations.


Claude-Session: https://claude.ai/code/session_01FW5GkkAG8du7tNdYLk2zSd

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: alicoding

frontend/bindings/github.com/alicoding/mill/internal/domain/atlas/index.ts

@@ -2,6 +2,7 @@
 // This file is automatically generated. DO NOT EDIT
 
 export {
+    MirrorKind,
     ViewMode
 } from "./models.js";
 
@@ -11,5 +12,6 @@ export type {
     LensSetting,
     Link,
     LinkKind,
+    MirrorContent,
     Position
 } from "./models.js";

frontend/bindings/github.com/alicoding/mill/internal/domain/atlas/models.ts

@@ -179,6 +179,58 @@ export interface LinkKind {
     "Seed": seedorigin$0.Origin;
 }
 
+/**
+ * MirrorContent is a card's MirrorPath resolved into a read-only
+ * overlay preview (docs/goals/0064), returned by atlassvc.AtlasService.
+ * MirrorContent. Size is always populated (even when TooLarge or
+ * Kind==MirrorKindOther) so the overlay's type+size+reveal fallback
+ * always has something to show. Content holds rendered HTML for
+ * MirrorKindMarkdown, raw text for MirrorKindText, or base64-encoded
+ * bytes (paired with MimeType) for MirrorKindImage -- empty for
+ * MirrorKindOther or whenever TooLarge is true.
+ */
+export interface MirrorContent {
+    "Kind": MirrorKind;
+    "MimeType": string;
+    "Size": number;
+    "Content": string;
+    "TooLarge": boolean;
+}
+
+/**
+ * MirrorKind classifies a mirrored file for the card overlay's preview
+ * (docs/goals/0064): a pure, extension-only decision, no I/O -- the
+ * service layer (atlassvc) is what actually stats/reads the file this
+ * classifies.
+ */
+export enum MirrorKind {
+    /**
+     * The Go zero value for the underlying type of the enum.
+     */
+    $zero = "",
+
+    /**
+     * MirrorKindMarkdown renders through the markdown adapter to HTML.
+     */
+    MirrorKindMarkdown = "markdown",
+
+    /**
+     * MirrorKindText renders as plain, preformatted text.
+     */
+    MirrorKindText = "text",
+
+    /**
+     * MirrorKindImage renders inline as an image.
+     */
+    MirrorKindImage = "image",
+
+    /**
+     * MirrorKindOther never has its content loaded -- the overlay shows
+     * only its kind and size, plus the existing reveal-file action.
+     */
+    MirrorKindOther = "other",
+};
+
 /**
  * Position is a card's location within its PARENT's canvas -- only
  * meaningful when the parent's EffectiveViewMode is ViewModeCanvas;

frontend/bindings/github.com/alicoding/mill/internal/services/atlassvc/atlasservice.ts

@@ -154,6 +154,18 @@ export function Links(): $CancellablePromise<atlas$0.Link[] | null> {
     return $Call.ByID(1082434947);
 }
 
+/**
+ * MirrorContent resolves cardID's MirrorPath into a read-only overlay
+ * preview: markdown renders to HTML, plain text passes through as-is,
+ * an image becomes base64-encoded bytes paired with its MIME type, and
+ * anything else (or anything over mirrorPreviewMaxBytes) reports only
+ * its kind and size -- the overlay's existing reveal-file action is
+ * what a user reaches for beyond that.
+ */
+export function MirrorContent(cardID: string): $CancellablePromise<atlas$0.MirrorContent> {
+    return $Call.ByID(3797489642, cardID);
+}
+
 /**
  * MoveCard reparents a card (sibling-vs-child move, ADR-0038's
  * create-time framing extended to a later move) -- rejects a

frontend/e2e/atlas.spec.ts

@@ -347,3 +347,111 @@ test('the space toolbar Share menu bundles the space as context and copies its l
     await expect.poll(() => readClipboardText(page)).toBe('https://example.com/project-charter')
   })
 })
+
+// Atlas projections (docs/goals/0064, ADR-0038): mirror-content
+// rendering, the traceability matrix, and coverage -- each proven
+// against the real seed, the same pattern every test above follows.
+
+test('a card with a Mirror path pointing at a markdown file renders its content read-only in the overlay', async ({ page }) => {
+  const fs = await import('node:fs')
+  const os = await import('node:os')
+  const path = await import('node:path')
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'mill-e2e-atlas-mirror-'))
+  const file = path.join(dir, 'notes.md')
+  fs.writeFileSync(file, '# Field notes\n\nSome **captured** text.')
+
+  const title = 'ZzE2eAtlasMirrorCard'
+  await page.goto('/')
+  await page.getByRole('link', { name: 'Atlas' }).click()
+  await page.getByTestId('atlas-shelf-card').filter({ hasText: 'My space' }).click()
+  await expect(page.getByTestId('atlas-canvas')).toBeVisible()
+
+  await page.getByTestId('atlas-add-button').click()
+  await page.getByTestId('atlas-add-child').click()
+  await page.getByTestId('atlas-create-kind').selectOption({ label: '📄 Document' })
+  await page.getByTestId('atlas-create-title').fill(title)
+  await page.getByRole('button', { name: 'Create' }).click()
+
+  const newCard = page.getByTestId('atlas-canvas-card').filter({ hasText: title })
+  await expect(newCard).toBeVisible()
+  await newCard.getByTestId('atlas-card-info').click()
+  const overlay = page.locator('[data-component="atlas-card-overlay"]')
+  await expect(overlay).toBeVisible()
+
+  await overlay.getByTestId('atlas-overlay-mirror-path').fill(file)
+  await overlay.getByTestId('atlas-overlay-save').click()
+  await expect(overlay).not.toBeVisible()
+
+  await newCard.getByTestId('atlas-card-info').click()
+  await expect(overlay).toBeVisible()
+  await expect(overlay.getByTestId('atlas-mirror-markdown')).toBeVisible()
+  await expect(overlay.getByTestId('atlas-mirror-markdown')).toContainText('Field notes')
+  await expect(overlay.getByTestId('atlas-mirror-markdown').locator('strong')).toContainText('captured')
+
+  // Cleanup (testing.md's within-file cleanup discipline).
+  await overlay.getByTestId('atlas-overlay-delete').click()
+  await page.getByRole('alertdialog').getByRole('button', { name: 'Delete' }).click()
+  await expect(newCard).not.toBeVisible()
+})
+
+test('the traceability matrix pivots a space\'s cards by kind against link kinds, with an absent cell shown explicitly', async ({ page }) => {
+  await page.goto('/')
+  await page.getByRole('link', { name: 'Atlas' }).click()
+  await page.getByTestId('atlas-shelf-card').filter({ hasText: 'My space' }).click()
+  await page.getByTestId('atlas-canvas-card').filter({ hasText: 'Example area' }).click()
+  await expect(page.getByTestId('atlas-shelves')).toBeVisible()
+
+  await page.getByTestId('atlas-open-matrix').click()
+  const dialog = page.locator('[data-component="atlas-matrix-dialog"]')
+  await expect(dialog).toBeVisible()
+
+  // Row kind "Contact" -- the seeded "Ada Lovelace" card has an
+  // outgoing "relates to" link to "Project charter", so its cell names
+  // that target.
+  await dialog.getByTestId('atlas-matrix-row-kind').selectOption({ label: '👤 Contact' })
+  await expect(dialog.getByTestId('atlas-matrix-target').filter({ hasText: 'Project charter' })).toBeVisible()
+
+  // Row kind "Document" -- the seeded "Project charter" card has no
+  // OUTGOING links of its own (only an incoming one), so its cell is
+  // explicitly absent, never an ambiguous blank.
+  await dialog.getByTestId('atlas-matrix-row-kind').selectOption({ label: '📄 Document' })
+  await expect(dialog.getByTestId('atlas-matrix-absent-cell')).toBeVisible()
+  await expect(dialog.getByTestId('atlas-matrix-absent-cell')).toHaveText('None')
+
+  await page.keyboard.press('Escape')
+  await expect(dialog).not.toBeVisible()
+})
+
+test('coverage counts a space\'s cards missing a link and missing a mirror, with the missing list navigating to a card', async ({ page }) => {
+  await page.goto('/')
+  await page.getByRole('link', { name: 'Atlas' }).click()
+  await page.getByTestId('atlas-shelf-card').filter({ hasText: 'My space' }).click()
+  await expect(page.getByTestId('atlas-canvas')).toBeVisible()
+
+  // "My space" itself has exactly two seeded children: "Getting
+  // started" (has an outgoing "relates to" link to "Ada Lovelace") and
+  // "Example area" (the container card itself has no link of its own)
+  // -- a hand-countable 1/2 linked. Neither child carries a mirror at
+  // THIS level (the seeded mirror lives one level deeper, on "Project
+  // charter") -- a hand-countable 0/2 mirrored.
+  await page.getByTestId('atlas-open-coverage').click()
+  const dialog = page.locator('[data-component="atlas-coverage-dialog"]')
+  await expect(dialog).toBeVisible()
+
+  await expect(dialog.getByTestId('atlas-coverage-link-value')).toHaveText('1/2 linked')
+  await expect(dialog.getByTestId('atlas-coverage-mirror-value')).toHaveText('0/2 mirrored')
+
+  await dialog.getByTestId('atlas-coverage-link-toggle').click()
+  await expect(dialog.getByTestId('atlas-coverage-missing-item').filter({ hasText: 'Example area' })).toBeVisible()
+
+  await dialog.getByTestId('atlas-coverage-mirror-toggle').click()
+  const missingItem = dialog.getByTestId('atlas-coverage-missing-item').filter({ hasText: 'Getting started' })
+  await expect(missingItem).toBeVisible()
+  await missingItem.click()
+
+  await expect(dialog).not.toBeVisible()
+  const overlay = page.locator('[data-component="atlas-card-overlay"]')
+  await expect(overlay).toBeVisible()
+  await expect(overlay.getByTestId('atlas-overlay-title')).toHaveValue('Getting started')
+  await page.keyboard.press('Escape')
+})

frontend/src/atlas/AtlasCardMirrorPreview.module.css

@@ -0,0 +1,54 @@
+.markdownBody {
+    max-height: 480px;
+    overflow-y: auto;
+    padding: var(--base-size-8) var(--base-size-12);
+    border: 1px solid var(--borderColor-default);
+    border-radius: var(--borderRadius-medium);
+    color: var(--fgColor-default);
+    font-size: 14px;
+    line-height: 1.5;
+}
+.markdownBody :global(h1),
+.markdownBody :global(h2),
+.markdownBody :global(h3) {
+    border-bottom: 1px solid var(--borderColor-muted);
+    padding-bottom: var(--base-size-4);
+    margin-top: var(--base-size-16);
+    margin-bottom: var(--base-size-8);
+}
+.markdownBody :global(code) {
+    background-color: var(--bgColor-muted);
+    border-radius: var(--borderRadius-small);
+    padding: 0 var(--base-size-4);
+}
+.markdownBody :global(pre) {
+    background-color: var(--bgColor-muted);
+    border-radius: var(--borderRadius-medium);
+    padding: var(--base-size-8);
+    overflow-x: auto;
+}
+.markdownBody :global(table) {
+    border-collapse: collapse;
+}
+.markdownBody :global(th),
+.markdownBody :global(td) {
+    border: 1px solid var(--borderColor-default);
+    padding: var(--base-size-4) var(--base-size-8);
+}
+.textBody {
+    max-height: 480px;
+    overflow: auto;
+    padding: var(--base-size-8) var(--base-size-12);
+    border: 1px solid var(--borderColor-default);
+    border-radius: var(--borderRadius-medium);
+    background-color: var(--bgColor-muted);
+    font-size: 12px;
+    white-space: pre-wrap;
+    word-break: break-word;
+}
+.image {
+    max-width: 100%;
+    max-height: 480px;
+    border-radius: var(--borderRadius-medium);
+    border: 1px solid var(--borderColor-default);
+}

frontend/src/atlas/AtlasCardMirrorPreview.tsx

@@ -0,0 +1,76 @@
+import { useEffect, useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { Text } from '@primer/react'
+import { MirrorKind } from '../../bindings/github.com/alicoding/mill/internal/domain/atlas/models'
+import type { MirrorContent } from '../../bindings/github.com/alicoding/mill/internal/domain/atlas/models'
+import { AtlasService } from '../shared/bindings'
+import runbookStyles from '../shared/ListCard.module.css'
+import styles from './AtlasCardMirrorPreview.module.css'
+
+// 1000-based (KB/MB, not KiB/MiB) -- matches how a file's size is
+// quoted everywhere else a user sees one (Finder, most OS file
+// pickers), not the binary convention.
+function formatMirrorSize(bytes: number): string {
+  if (bytes < 1000) return `${bytes} B`
+  if (bytes < 1000 * 1000) return `${(bytes / 1000).toFixed(1)} KB`
+  return `${(bytes / (1000 * 1000)).toFixed(1)} MB`
+}
+
+// Renders a card's MirrorPath read-only inside the overlay (docs/
+// goals/0064): markdown through the Go-side converter (goldmark's
+// default safe-render mode -- MirrorContent's own doc comment covers
+// why dangerouslySetInnerHTML below is safe against an embedded raw
+// <script>), plain text preformatted, an image inline via a base64
+// data URI, and everything else (plus anything over the server's size
+// cap) as a plain kind+size line -- the overlay's existing "Show in
+// Finder" action covers the rest. Re-fetches whenever mirrorPath
+// changes (a fresh "Update now" refresh, or the field itself edited
+// and saved), never on every render.
+export function AtlasCardMirrorPreview({ cardID, mirrorPath }: { cardID: string; mirrorPath: string }) {
+  const { t } = useTranslation('atlas')
+  const [content, setContent] = useState<MirrorContent | null>(null)
+  const [error, setError] = useState('')
+
+  useEffect(() => {
+    setContent(null)
+    setError('')
+    AtlasService.MirrorContent(cardID)
+      .then(setContent)
+      .catch((err) => setError(String(err)))
+  }, [cardID, mirrorPath])
+
+  if (error) {
+    return <Text as="p" size="small" className={runbookStyles.error} data-testid="atlas-mirror-error">{error}</Text>
+  }
+  if (!content) {
+    return <Text as="p" size="small" className={runbookStyles.muted} data-testid="atlas-mirror-loading">{t('overlay.mirrorLoading')}</Text>
+  }
+
+  if (content.TooLarge || content.Kind === MirrorKind.MirrorKindOther) {
+    return (
+      <Text as="p" size="small" className={runbookStyles.muted} data-testid="atlas-mirror-fallback">
+        {content.TooLarge
+          ? t('overlay.mirrorTooLarge', { size: formatMirrorSize(content.Size) })
+          : t('overlay.mirrorUnsupported', { size: formatMirrorSize(content.Size) })}
+      </Text>
+    )
+  }
+
+  if (content.Kind === MirrorKind.MirrorKindMarkdown) {
+    return (
+      <div
+        className={styles.markdownBody}
+        data-testid="atlas-mirror-markdown"
+        // Safe: goldmark's default (non-unsafe) render mode never passes
+        // raw HTML through unescaped -- render_test.go pins that property.
+        dangerouslySetInnerHTML={{ __html: content.Content }}
+      />
+    )
+  }
+
+  if (content.Kind === MirrorKind.MirrorKindText) {
+    return <pre className={styles.textBody} data-testid="atlas-mirror-text">{content.Content}</pre>
+  }
+
+  return <img className={styles.image} data-testid="atlas-mirror-image" src={`data:${content.MimeType};base64,${content.Content}`} alt={mirrorPath} />
+}

frontend/src/atlas/AtlasCardOverlay.tsx

@@ -13,6 +13,7 @@ import { StatusStamp } from '../shared/StatusStamp'
 import { AtlasKindChip } from './AtlasKindChip'
 import { AtlasFieldsForm } from './AtlasFieldsForm'
 import { AtlasCardOverlayLinks } from './AtlasCardOverlayLinks'
+import { AtlasCardMirrorPreview } from './AtlasCardMirrorPreview'
 import { atlasCardShareActions } from './atlasCardShare'
 import { useConfirmDelete } from '../shared/useConfirmDelete'
 import runbookStyles from '../shared/ListCard.module.css'
@@ -38,6 +39,7 @@ export function AtlasCardOverlay({ card, kind, allCards, links, linkKinds, onClo
   const [note, setNote] = useState(card.Note)
   const [fields, setFields] = useState<Record<string, string>>((card.Fields ?? {}) as Record<string, string>)
   const [source, setSource] = useState(card.Source)
+  const [mirrorPath, setMirrorPath] = useState(card.MirrorPath)
   const [refreshWorkflowID, setRefreshWorkflowID] = useState(card.RefreshWorkflowID)
   const [saving, setSaving] = useState(false)
   const [error, setError] = useState('')
@@ -98,7 +100,7 @@ export function AtlasCardOverlay({ card, kind, allCards, links, linkKinds, onClo
     setSaving(true)
     setError('')
     try {
-      await AtlasService.UpdateCard(card.ID, title, note, fields, source, card.MirrorPath, refreshWorkflowID)
+      await AtlasService.UpdateCard(card.ID, title, note, fields, source, mirrorPath, refreshWorkflowID)
       onSaved()
       onClose()
     } catch (err) {
@@ -171,13 +173,21 @@ export function AtlasCardOverlay({ card, kind, allCards, links, linkKinds, onClo
           )}
         </FormControl>
 
-        {card.MirrorPath && (
-          <Text as="p" size="small" className={runbookStyles.muted}>{t('overlay.mirrorPath', { path: card.MirrorPath })}</Text>
-        )}
+        <FormControl>
+          <FormControl.Label>{t('overlay.mirrorPathLabel')}</FormControl.Label>
+          <TextInput value={mirrorPath} data-testid="atlas-overlay-mirror-path" onChange={(e) => setMirrorPath(e.target.value)} block />
+        </FormControl>
         <Text as="p" size="small" className={runbookStyles.muted}>
           {card.LastSyncedAt && formatUpdated(card.LastSyncedAt) ? t('overlay.lastSynced', { when: formatUpdated(card.LastSyncedAt) }) : t('overlay.neverSynced')}
         </Text>
 
+        {card.MirrorPath && (
+          <Stack direction="vertical" gap="condensed" data-testid="atlas-card-mirror-content">
+            <Text weight="semibold">{t('overlay.mirrorContentHeading')}</Text>
+            <AtlasCardMirrorPreview cardID={card.ID} mirrorPath={card.MirrorPath} />
+          </Stack>
+        )}
+
         <FormControl>
           <FormControl.Label>{t('overlay.refreshWorkflowLabel')}</FormControl.Label>
           <Stack direction="horizontal" gap="condensed" align="center">