Render uncommitted (dirty) changes + live-refresh the whole scene (#74) (#111)

* feat(scan): parse porcelain into a dirty-path set (#74)

* feat(manifest): FileNode.dirty + RepoStats.dirtyFileCount on the wire (#74)

Adds the pydantic + TypedDict + TS fields, bumps the manifest cache schema
to v16, and updates the hand-authored fixtures the new required fields
touch (test_models.py, EMPTY_REPO_STATS, and frontend FileNode literals)
so the suite stays green even though the scanner doesn't set `dirty` yet
(Task A3).

* feat(scan): dirty files carry the flag + working-tree mtime (#74)

Threads the dirty-paths set (Task A1's _collect_dirty_paths) from
scan_tree through _build_tree into _file_node, which stamps
FileNode.dirty and overrides `modified` to the working-tree mtime for
dirty files (their git-history date is stale by definition).

* feat(stats): dirtyFileCount rollup (#74)

compute_repo_stats now counts file nodes with dirty === true (media
included) into RepoStats.dirtyFileCount, alongside the existing
one-pass superlative accumulation.

* fix(scan): single porcelain call + import/doc cleanup (#74)

Collapse _collect_repo_info to a single `git status --porcelain -z`
call, returning the dirty-path set alongside RepoInfo so scan_tree no
longer walks it twice; the signature-scan path just discards the set.
Also moves test_scan_dirty.py's mid-file imports to the top (E402) and
documents that a dirty file's `modified` is always the working-tree
filesystem date, regardless of git history.

* feat(almanac): resurface the uncommitted-files stat (#74)

* feat(layout): computeLayoutSignature (structure + size) (#74)

* fix(layout): deterministic child order in layout signature + structure test (#74)

Sort children by path before walking in computeLayoutSignature, mirroring
compute_tree_signature's defensive sort in scan.py, so the hash is
deterministic regardless of manifest child order. Also add a test proving
the signature reflects the path SET, not just per-file size/date.

* fix(city): re-pack on content edits (layout-input reuse gate) (#74)

The layout-reuse gate keyed on tree_signature (paths + nesting only), so a
live content edit that changes a file's size (no rename) was wrongly treated
as a no-op and reused the frozen layout — streets/positions never re-solved.
Swap the gate to compare computeLayoutSignature (structure + per-file size)
of the new manifest against the committed one; a size change now bumps
structureRevision (full re-pack), a dates-only change still reuses.

applyManifestScenic.test.ts's manifest fixture lacked a `path` on its tree
root; computeLayoutSignature walks the tree (unlike the old string-field
compare) and needs it, so add it.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* feat(utils): findNodeByPath manifest lookup (#74)

* fix(sidebar): file/road panes re-derive from live MANIFEST (#74)

* fix: address final-review findings (porcelain rename, dirty-set signature, layout-sig media dims, stale comments, perf) (#74)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* fix(preview): re-fetch file content on live edit via mtime cache-buster (#74)

The right-sidebar file preview fetched content in an effect keyed only on
fullPath, so a live edit to the still-selected file left stale content until a
re-select. Thread the file's mtime through fileUrl/fetchFileText/fetchFileBytes
as a cache-busting version param and add it to the preview effect deps, so text,
font, and media previews (and the README pane) refresh on save.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* refactor(scan): name the created/modified locals instead of inline ternaries (#74)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* refactor(scan): split git collection into fresh state vs cached history (#74)

* refactor(scan): one-pass tree signals + backend layout_signature (#74)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* refactor(city): reuse gate reads backend layout_signature; drop frontend one (#74)

* test(city): make the reuse-gate test discriminate field vs tree gating (#74)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* refactor(scan): dirty is a per-file signature contribution, not repo-level (#74)

* refactor(scan): shared tracked-entry iteration for both walks (#74)

* fix(scan): dirty-parity test + layout-sig type marker + stale-doc cleanup (#74)

Co-Authored-By: Claude Sonnet 5 (1M context) <noreply@anthropic.com>

* docs(scan): trim the over-long file-date resolution comment (#74)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* refactor: rename signature→content_signature, tree_signature→structure_signature (#74)

Clarify the three-signature ladder on the manifest wire format: the bare
`signature` field (mtime/size/dirty/repo fingerprint) is easily confused
with `tree_signature`/`layout_signature`. Rename to `content_signature`
and `structure_signature` respectively, document the ladder at the
Manifest model/type, and bump the manifest cache schema version since
the field rename changes the cached shape.

* docs(scan): name content_signature in the layout-sig docstring (#74)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: thalida

api/models/manifest.py

@@ -26,6 +26,12 @@ class FileNode(BaseModel):
     size: int
     lines: int
     binary: bool
+    dirty: bool = Field(
+        description=(
+            "Working-tree differs from HEAD for this tracked file (staged or "
+            "unstaged). Always False for clean/remote repos."
+        )
+    )
     created: str = Field(
         description=(
             "ISO create date (UTC, Z-suffixed), resolved server-side: git "
@@ -35,7 +41,9 @@ class FileNode(BaseModel):
     modified: str = Field(
         description=(
             "ISO modify date (UTC, Z-suffixed), resolved server-side: git "
-            "history date when the file has one, filesystem date otherwise"
+            "history date when the file has one, filesystem date otherwise. "
+            "When dirty is true, this is always the working-tree filesystem "
+            "date, regardless of git history"
         )
     )
     mediaKind: Optional[Literal["image", "video"]] = Field(
@@ -205,6 +213,7 @@ class RepoStats(BaseModel):
     minMediaPixelsFile: Optional[FileLeader]
     mediaCount: int
     totalLines: int
+    dirtyFileCount: int
     codeBytes: int
     maxDepthDir: Optional[DirLeader]
     maxChildrenDir: Optional[DirLeader]
@@ -217,11 +226,20 @@ class RepoStats(BaseModel):
     authors: list[AuthorStat]
 
 
+# Three signatures form a ladder, each a superset of the one before:
+#   structure_signature: paths + nesting only. Drives icon-atlas assignment
+#     and skeleton/final render stability.
+#   layout_signature: structure, plus per-file size. Gates layout reuse (a
+#     size-only change can still skip a full relayout if paths didn't move).
+#   content_signature: structure, plus size, mtime, dirty, and repo HEAD. The
+#     full change-detection fingerprint: drives the live-update poll and is
+#     the manifest cache key.
 class Manifest(BaseModel):
     root: str
     scanned_at: str
-    signature: str
-    tree_signature: str
+    content_signature: str
+    structure_signature: str
+    layout_signature: str
     tree: DirNode
     repo: RepoInfo
     commits: list[CommitEntry]
@@ -233,7 +251,7 @@ class Manifest(BaseModel):
 class SignatureResponse(BaseModel):
     root: str
     scanned_at: str
-    signature: str
+    content_signature: str
 
 
 DirNode.model_rebuild()

api/routers/manifest.py

@@ -264,7 +264,7 @@ def _run() -> None:
                 # Signature (cache key) + warm-cache short-circuit.
                 sig = signature_tree(
                     str(path), use_cache=use_cache, extra_exclude_paths=excludes
-                )["signature"]
+                )["content_signature"]
                 holder["sig"] = sig
                 if use_cache:
                     cached = cache_load_manifest(path.resolve(), sig)

api/services/cache.py

@@ -70,7 +70,11 @@ class FileEntry(TypedDict):
     # v13: ext_breakdown `ext` is null (was "(none)") for extensionless files
     # v14: tree.name baked to the git remote's owner/repo at scan time
     # v15: sbom.json added to ALWAYS_SKIP
-    15
+    # v16: FileNode.dirty + RepoStats.dirtyFileCount; dirty files use working-tree mtime
+    # v17: layout_signature field; dirty in per-file signature
+    # v18: Manifest/SignatureResponse field `signature` renamed `content_signature`
+    #   (field rename is a shape change; old blobs lack the new key)
+    18
 )
 # Composite: invalidates when EITHER the manifest schema OR the git-history
 # shape changes. Stored as a string in the cache file's `version` field.
@@ -296,19 +300,21 @@ def cache_save_git_history(
     _atomic_write(_git_history_cache_path(abs_root), json.dumps(payload))
 
 
-def _manifest_cache_path(abs_root: Path, signature: str) -> Path:
-    return CACHE_ROOT / "manifests" / f"{repo_key(abs_root)}__{signature}.json.gz"
+def _manifest_cache_path(abs_root: Path, content_signature: str) -> Path:
+    return (
+        CACHE_ROOT / "manifests" / f"{repo_key(abs_root)}__{content_signature}.json.gz"
+    )
 
 
 def cache_load_manifest(
     abs_root: Path,
-    signature: str,
+    content_signature: str,
 ) -> "Manifest | None":
-    """Load the cached manifest for this (root, signature). Returns
+    """Load the cached manifest for this (root, content_signature). Returns
     None on any error (missing file, gzip corruption, JSON parse,
     schema/version mismatch). Same hygiene as the other cache loaders:
     a corrupt cache is treated as a miss, never a hard failure."""
-    path = _manifest_cache_path(abs_root, signature)
+    path = _manifest_cache_path(abs_root, content_signature)
     try:
         with gzip.open(path, "rb") as fh:
             raw = json.loads(fh.read().decode("utf-8"))
@@ -329,13 +335,13 @@ def cache_load_manifest(
 
 def cache_save_manifest(
     abs_root: Path,
-    signature: str,
+    content_signature: str,
     manifest: "Manifest",
 ) -> None:
-    """Atomically write the manifest cache for this (root, signature).
+    """Atomically write the manifest cache for this (root, content_signature).
     Swallows OSError — cache save failures must never break the
     response."""
-    path = _manifest_cache_path(abs_root, signature)
+    path = _manifest_cache_path(abs_root, content_signature)
     path.parent.mkdir(parents=True, exist_ok=True)
     payload = json.dumps(
         {

api/services/manifest_types.py

@@ -54,8 +54,13 @@ class FileNode(TypedDict):
     size: int
     lines: int
     binary: bool
+    # Working-tree differs from HEAD for this tracked file (staged or
+    # unstaged). Always False for clean/remote repos.
+    dirty: bool
     # Resolved server-side: git history date when the file has one,
     # filesystem date otherwise (e.g. staged-but-uncommitted files).
+    # When dirty is true, modified is always the working-tree filesystem
+    # date, regardless of git history.
     created: str
     modified: str
     # Optional pixel dimensions for recognized media files (png/jpg/svg/
@@ -256,6 +261,7 @@ class RepoStats(TypedDict):
     minMediaPixelsFile: FileLeader | None
     mediaCount: int
     totalLines: int
+    dirtyFileCount: int
     codeBytes: int
     maxDepthDir: DirLeader | None
     maxChildrenDir: DirLeader | None
@@ -274,8 +280,9 @@ class Manifest(TypedDict):
 
     root: str
     scanned_at: str
-    signature: str
-    tree_signature: str
+    content_signature: str
+    structure_signature: str
+    layout_signature: str
     tree: DirNode
     repo: RepoInfo
     commits: list[CommitEntry]
@@ -294,7 +301,7 @@ class SignatureResponse(TypedDict):
 
     root: str
     scanned_at: str
-    signature: str
+    content_signature: str
 
 
 class ScanStreamEvent(TypedDict):