Skip to content

feat(epic): folder-tree breadcrumb redesign — WebView2 breadcrumb UI backed by a live folder-hierarchy provider#357

Merged
drmoisan merged 30 commits into
mainfrom
epic/folder-tree-breadcrumb-redesign-integration
Jul 18, 2026
Merged

feat(epic): folder-tree breadcrumb redesign — WebView2 breadcrumb UI backed by a live folder-hierarchy provider#357
drmoisan merged 30 commits into
mainfrom
epic/folder-tree-breadcrumb-redesign-integration

Conversation

@drmoisan

@drmoisan drmoisan commented Jul 18, 2026

Copy link
Copy Markdown
Owner

feat(epic): folder-tree breadcrumb redesign — WebView2 breadcrumb UI backed by a live folder-hierarchy provider

Summary

Why

The EfcViewer matching-folders control renders folder suggestions as an indented multi-row tree, which forces users to decode hierarchy from indentation and can push the prediction percentage out of view at small window sizes; the QuickFiler folder ComboBox gives no hierarchy context at all. Rendering each suggestion as a single-line breadcrumb anchored at the predicted leaf lets a user read the full filing location at a glance, expand a segment to reach subfolders that never ranked among the top suggestions, and always see the model's confidence. Hosting the control in WebView2 preserves the UI investment across the planned VSTO migration.

What Changed

Core feature — shared provider (#350)

  • IFolderHierarchyProvider (shared contract), FolderBreadcrumbSegment (immutable, net48-safe DTO), OutlookFolderHierarchyProvider (host-neutral facade over the reused IOutlookFolderTreeService seam), and pure FolderTreeSnapshotQueries.GetAncestorChain with cycle guard.

Core feature — EfcViewer breadcrumb (#349)

  • Replaces the EfcViewer folder tree with a WebView2 breadcrumb control; wires the provider contract into the suggestion form; 97 new tests.

Core feature — QuickFiler breadcrumb (#351)

  • Replaces CboFolders with the WebView2 breadcrumb in the live ItemViewer; adds a breadcrumb bridge protocol, async message router, selection map, host-neutral BreadcrumbStateModel/BreadcrumbRenderProjection, WebView2 messenger seam, and breadcrumb page resource; reroutes keyboard, theme, and controller surfaces; 114 new tests.
  • Cross-feature name collisions with Feature: efcviewer-breadcrumb-webview2 #349 resolved during rebase by renaming this feature's own types only (BreadcrumbRow → BreadcrumbStateRow; BreadcrumbBridgeRouter → FolderBreadcrumbBridgeRouter).

Docs / evidence

  • Full epic preparation and delivery artifacts per feature folder: research, spec, user story, atomic plans, QA-gate evidence dossiers, and feature-review audits (policy, code, feature) for all three children.
  • Epic manifest and kickoff artifacts under docs/features/epics/folder-tree-breadcrumb-redesign/.
  • Orchestrator agent-memory records from the epic run.

Dependency updates (merged from main)

  • Dependabot NuGet bumps carried in by the origin/main merge, including Microsoft.Web.WebView2 1.0.4078.44 and test-framework/package updates across VBFunctions and QuickFiler.Test.

Diff scale: 171 files changed, +16,549/−740 (65 .cs, 4 .csproj, 1 .html, 1 .resx, 100 .md).

Architecture / How It Fits Together

OutlookFolderHierarchyProvider implements IFolderHierarchyProvider over the existing IOutlookFolderTreeService seam, exposing breadcrumb segments and live subfolder listings without new COM surface. Both UI consumers depend only on the contract: the EfcViewer suggestion form (#349) and the QuickFiler ItemViewer (#351) each host a WebView2 control whose page resource renders the breadcrumb; a bridge protocol with an async message router carries state and selection between the managed host and the web page. Pure state modeling (BreadcrumbStateModel, render projections, ancestor-chain queries) is host-neutral and unit-tested; WebView2 and Outlook I/O sit behind seams.

Verification

Completed (from context and child evidence)

Recommended

  • Full toolchain on this merged head: csharpier .; msbuild TaskMaster.sln /t:Build /p:Configuration=Debug /p:Platform="Any CPU" /p:EnableNETAnalyzers=true /p:EnforceCodeStyleInBuild=true; nullable build; vstest.console.exe <test assemblies> /EnableCodeCoverage.
  • Manual runtime QA in live Outlook (see Risks) before or shortly after release.

Backward Compatibility / Migration Notes

  • Legacy FolderSuggestionTree.BuildFromRows / FolderHierarchyBuilder.Build were kept intact through wave 0 and rewired per-consumer in Feature: efcviewer-breadcrumb-webview2 #349/Feature: quickfiler-breadcrumb-webview2 #351; the QuickFiler CboFolders control is decommissioned (see cbofolders-decommission-verification evidence).
  • New WebView2 runtime dependency in the QuickFiler/EfcViewer UI paths (package Microsoft.Web.WebView2 1.0.4078.44); machines require the WebView2 Evergreen runtime.
  • No changes to classifier/prediction plumbing; feature-324 probability plumbing untouched.

Risks and Mitigations

  • Host-bound acceptance criteria are not runtime-verified by agents. Several ACs (live rendering, live subfolder listing, runtime percentage visibility, bridge round-trip, keyboard/focus hand-off, selection contract) depend on a live Outlook process and are intentionally unchecked in the child specs; each is pinned by unit tests plus structural-impossibility dossiers marked MANUAL-VERIFICATION-REQUIRED. Mitigation: maintainer runtime QA pass in live Outlook; unit/bridge tests pin the delivered behavior.
  • WebView2 resource cost. Feature: quickfiler-breadcrumb-webview2 #351 retains eager per-pooled-viewer initialization (DECISION: EAGER-RETAINED-PENDING-RUNTIME-OBSERVATION); if live cost is prohibitive, lazy-init is a prepared follow-up.
  • CI on child PRs was vacuous by epic design (ci.yml does not trigger on PRs to the integration branch); this PR to main is the first CI execution of the combined tree. Mitigation: merge only on green CI here; rollback is a revert of this single merge commit.

Review Guide

  1. Provider contract first: IFolderHierarchyProvider, FolderBreadcrumbSegment, OutlookFolderHierarchyProvider, FolderTreeSnapshotQueries (Feature: folder-hierarchy-live-provider #350, commit 158ccb84).
  2. EfcViewer swap (Feature: efcviewer-breadcrumb-webview2 #349, commit be6f38d1): control replacement and provider wiring.
  3. QuickFiler bridge stack (Feature: quickfiler-breadcrumb-webview2 #351, commits 84180cf0..33ac6a3f): state model → bridge protocol/router → messenger seam/page resource → live ItemViewer rewire; then the rebase collision-rename commit 8e4e896d.
  4. The ~100 Markdown files are epic preparation/evidence artifacts; they can be reviewed last or sampled.
  5. The origin/main merge commit (16671d6a) is mechanical dependency alignment.

Follow-ups

  • Maintainer runtime QA of the host-bound ACs listed above in live Outlook.
  • Candidate issue: lazy WebView2 initialization for pooled QuickFiler viewers if runtime observation shows prohibitive cost.
  • Post-merge: archive the epic feature folders per the feature lifecycle and delete the integration branch.

GitHub Auto-close

drmoisan and others added 30 commits July 16, 2026 21:49
@drmoisan @claude
docs(epic): author folder-tree-breadcrumb-redesign manifest
e50173e 
Epic-planner manifest for the WebView2 breadcrumb redesign. Three children:
9101 live folder-hierarchy provider (wave 0, C3); 9102 EfcViewer WebView2
breadcrumb (wave 1, C4); 9103 QuickFiler WebView2 breadcrumb (wave 1, C4).
issue_num values are provisional placeholders back-filled at promotion.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018s32dQa8QYDzJaCo3GuQ3z
@drmoisan @claude
docs(9101): prepare live folder-hierarchy provider feature (#350)
ddc4fd8 
Preparation-mode outputs for epic folder-tree-breadcrumb-redesign child
feature 9101 (wave 0, complexity C3): promotion (issue #350), research,
spec.md, user-story.md, and the preflight-cleared atomic plan.

Scope: 9101 adds the IFolderHierarchyProvider contract, FolderBreadcrumbSegment
DTO, a pure FolderTreeSnapshotQueries.GetAncestorChain helper, and a thin
OutlookFolderHierarchyProvider facade over the existing IOutlookFolderTreeService
seam (no new live-COM seam). It does not delete FolderSuggestionTree.BuildFromRows
or FolderHierarchyBuilder.Build or rewire their UI callers, so it stays
independently mergeable; removal/rewire is executed by consumers 9102/9103.
Scoring/ranking and the feature 324 probability plumbing are unchanged.

Atomic execution, PR authoring, and CI monitoring are out of scope for this
preparation run and are executed later by epic-orchestrator.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018s32dQa8QYDzJaCo3GuQ3z
@drmoisan @claude
chore(memory): record orchestrator-state validator flat-key + enum sc…
205b5e0 
…hema

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018s32dQa8QYDzJaCo3GuQ3z
@drmoisan @claude
docs(349): prepare EfcViewer WebView2 breadcrumb feature (epic child …
72e1ad0 
…9102)

Preparation-mode outputs for epic child 9102 (folder-tree-breadcrumb-redesign,
wave 1, band C4, depends_on 9101): promoted potential entry, active feature
folder (issue.md, spec.md, user-story.md), task-researcher findings, and the
preflight-cleared atomic plan (plan.2026-07-16T21-52.md).

Behavioral WebView2 conversion targets the live EfcViewer + EfcFormController
only; EfcViewer3 is dead code and receives a mechanical Designer-only swap.
Consumes the 9101 live folder-hierarchy provider contract. Atomic execution,
PR authoring, CI, and feature review are out of scope (executed later by
epic-orchestrator).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018s32dQa8QYDzJaCo3GuQ3z
@drmoisan @claude
docs(351): prepare quickfiler-breadcrumb-webview2 epic child (researc…
1fa2c85 
…h, spec, plan)

Preparation-mode outputs for epic folder-tree-breadcrumb-redesign child
feature #351 (wave 1, C4), fanned into the integration branch:

- Promotion: issue #351 (full-feature), active folder
  docs/features/active/2026-07-16-quickfiler-breadcrumb-webview2-351/
- Research: re-verified ItemViewer is the single live QuickFiler viewer
  variant; documented CboFolders surface, the existing WebView2 message-body
  pattern, the new JS<->.NET bridge (none exists today), the 9101 provider
  contract (ASSUMED-PENDING-9101-MERGE), the percentage-obscuring defect
  hypothesis, and testability seams.
- spec.md / user-story.md: full-feature documents (FR-1..FR-7, AC-1..AC-13,
  US-1..US-8), scope decision ItemViewer-only, 9101 dependency cited.
- plan.2026-07-16T21-53.md: 8-phase atomic plan; MCP plan validator pass;
  atomic-executor preflight PREFLIGHT: ALL CLEAR.

Atomic execution, PR authoring, and CI monitoring are out of scope for this
preparation run and are executed later by epic-orchestrator.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018s32dQa8QYDzJaCo3GuQ3z
@drmoisan
merge(epic): fan in folder-hierarchy-live-provider (#350) prepared child
58b1458
@drmoisan
merge(epic): fan in efcviewer-breadcrumb-webview2 (#349) prepared child
74493e8
@drmoisan
merge(epic): fan in quickfiler-breadcrumb-webview2 (#351) prepared child
90332b2
@drmoisan @claude
docs(epic): back-fill resolved issue numbers and add kickoff artifact
3d322cf 
Back-fill folder-tree-breadcrumb-redesign manifest placeholders 9101/9102/9103
with the real promoted issue numbers 350/349/351 and resolved active feature
folders. Add the epic-orchestrator kickoff artifact. All three child preparations
are fanned in with PREFLIGHT: ALL CLEAR.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018s32dQa8QYDzJaCo3GuQ3z
@drmoisan @claude
feat(350): add live Outlook folder-hierarchy provider contract
158ccb8 
Introduce the epic's shared upstream contract for the folder-tree
breadcrumb redesign (wave 0):

- IFolderHierarchyProvider: ancestor-chain, immediate-subfolders, and
  path-resolution queries returning breadcrumb segments.
- FolderBreadcrumbSegment: immutable, net48-safe, probability-free DTO.
- OutlookFolderHierarchyProvider: host-neutral facade over the reused
  IOutlookFolderTreeService seam (no new COM code, not coverage-exempt).
- FolderTreeSnapshotQueries.GetAncestorChain: pure root-to-leaf walk with
  a defensive cycle guard and documented invariants.

Adds the provider without deleting the legacy prefix-matching methods or
rewiring their UI callers, preserving wave-0 mergeability. Scoring and
feature-324 probability plumbing are unchanged. MSTest + Moq +
FluentAssertions; new production code coverage 96.92% (>= 90%), no repo
floor regression. Toolchain green (csharpier, analyzers, nullable, tests).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147fAkr46FBRGMUuyUbzQ9V
@drmoisan @claude
docs(350): add feature-review audit artifacts (policy, code, feature)
ad0e3da 
All three audits PASS with zero blocking findings; combined
blocking_count 0, READY-TO-MERGE. Wave-0 mergeability boundary
confirmed intact and new-code coverage 96.92%.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147fAkr46FBRGMUuyUbzQ9V
@drmoisan
Merge pull request #353 from drmoisan/feature/folder-hierarchy-live-p…
8e24269 
…rovider-350

feat(350): live Outlook folder-hierarchy provider contract
@drmoisan @claude
feat(349): replace EfcViewer folder tree with WebView2 breadcrumb con…
be6f38d 
…trol

Single-line breadcrumb per suggestion via WebView2 (HTML/CSS/JS) with
JS<->.NET bridge; consumes the #350 IFolderHierarchyProvider contract
for real subfolder listing; CSS flex fix keeps prediction percent
always visible. Adds host-neutral row model/state machine, message
codec, HTML renderer, bridge router with pre-init outbound queue, and
97 MSTest tests (new modules >= 90% line coverage). EfcViewer3 gets
the mechanical Designer-only swap. Includes plan check-off, evidence
artifacts, and AC updates.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147fAkr46FBRGMUuyUbzQ9V
@drmoisan @claude
docs(349): add feature-review audit artifacts (policy, code, feature)
fece796 
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147fAkr46FBRGMUuyUbzQ9V
@drmoisan
Merge pull request #355 from drmoisan/feature/efcviewer-breadcrumb-we…
5108fa8 
…bview2-349

feat(349): replace EfcViewer folder tree with WebView2 breadcrumb control
@drmoisan @claude
docs(agent-memory): record collect_pr_context session-root write beha…
219145e 
…vior verified in child 349

Preserves the orchestrator agent-memory refinement from the epic child 349
run (PR #355): collect_pr_context writes pr_context.* to the session root
even when workspace_root targets the agent worktree, and the portable
SubagentStop gate is authoritative on integration-based branches.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147fAkr46FBRGMUuyUbzQ9V
@drmoisan @claude
docs(351): capture Phase 0 policy-read, baseline toolchain, and 9101 …
e2b94b0 
…contract evidence

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147fAkr46FBRGMUuyUbzQ9V
@drmoisan @claude
docs(351): Phase 1 fail-before exception dossier and reproduction ana…
95e2b3e 
…lysis

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147fAkr46FBRGMUuyUbzQ9V
@drmoisan @claude
test(351): reconcile merged 9101 contract (DIRECT-CONSUME) and pin pr…
4102eb3 
…ovider shape for the breadcrumb consumer

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147fAkr46FBRGMUuyUbzQ9V
@drmoisan @claude
feat(351): add host-neutral BreadcrumbStateModel and BreadcrumbRender…
84180cf 
…Projection with unit tests

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147fAkr46FBRGMUuyUbzQ9V
@drmoisan @claude
feat(351): add breadcrumb bridge protocol, async message router, and …
160ead6 
…selection map with unit tests

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147fAkr46FBRGMUuyUbzQ9V
@drmoisan @claude
feat(351): add WebView2 messenger seam, breadcrumb page resource, and…
fabc641 
… bridge coordinator with tests

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147fAkr46FBRGMUuyUbzQ9V
@drmoisan @claude
feat(351): replace CboFolders with WebView2 breadcrumb in live ItemVi…
33ac6a3 
…ewer; reroute keyboard, theme, and controller surfaces

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147fAkr46FBRGMUuyUbzQ9V
@drmoisan @claude
docs(351): Phase 6 structural-impossibility dossiers for runtime veri…
fab4891 
…fication evidence

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147fAkr46FBRGMUuyUbzQ9V
@drmoisan @claude
test(351): close final QA loop — coverage-gap tests, JaCoCo gate arti…
756414b 
…fact, delta verification, AC check-offs, evidence audit

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147fAkr46FBRGMUuyUbzQ9V
@drmoisan @claude
docs(351): add feature-review audit artifacts (policy, code, feature)…
43354fb 
… — blocking_count 0

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147fAkr46FBRGMUuyUbzQ9V
@drmoisan @claude
fix(351): resolve cross-feature name collisions with #349 after rebas…
8e4e896 
…e onto integration tip

Sibling feature #349 (EfcViewer breadcrumb) introduced BreadcrumbRow and
QuickFiler.Controllers.BreadcrumbBridgeRouter into the shared namespaces.
Rename this feature's types to remove CS0101/CS0104 collisions:
- BreadcrumbRow (inner row type of BreadcrumbStateModel) -> BreadcrumbStateRow
- UtilitiesCS BreadcrumbBridgeRouter -> FolderBreadcrumbBridgeRouter (file moved, csproj updated)
Identifier renames only; no behavior change. Full toolchain green in a single
pass after rebase: csharpier clean, analyzer build 0 errors, nullable build 0
warnings, vstest 5049/5049 passed with coverage.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147fAkr46FBRGMUuyUbzQ9V
@drmoisan
Merge pull request #356 from drmoisan/feature/quickfiler-breadcrumb-w…
cf1d21f 
…ebview2-351

feat(351): QuickFiler WebView2 breadcrumb replaces CboFolders (epic: folder-tree-breadcrumb-redesign)
@drmoisan @claude
docs(agent-memory): record parallel-epic-children name-collision patt…
9f8e61d 
…ern from child 351

Preserves the orchestrator agent-memory entry written during the epic
child 351 run (PR #356): sibling features executing in parallel against
the same integration base can introduce colliding type names; resolve by
renaming the later feature's own types during rebase, never editing
sibling-owned files.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0147fAkr46FBRGMUuyUbzQ9V
@drmoisan
Merge remote-tracking branch 'origin/main' into epic/folder-tree-brea…
16671d6 
…dcrumb-redesign-integration
@drmoisan
drmoisan merged commit 9bad9d9 into main Jul 18, 2026
2 checks passed
@drmoisan drmoisan mentioned this pull request Jul 18, 2026
Merged
@drmoisan
drmoisan deleted the epic/folder-tree-breadcrumb-redesign-integration branch July 19, 2026 01:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Feature: quickfiler-breadcrumb-webview2 Feature: folder-hierarchy-live-provider Feature: efcviewer-breadcrumb-webview2

1 participant

@drmoisan