fix(web): register folder in SDK folderTree before file edit and version writes

[FSM1]

Summary

Fixes a regression from #494 (phase 47 SDK folder-state/publish consolidation) that broke the Web E2E suite on main.

#494 re-routed the owner file-edit save and the file-version restore/delete paths through new stateful CipherBoxClient methods (replaceFile, restoreFileVersion, deleteFileVersion). Each gates on the in-memory folderTree:

const folder = this.folderTree.get(parentIpnsName);
if (!folder) throw new Error('Folder not loaded');

The web app seeds folderTree only via ensureFolderRegistered (called from the upload/mutation hooks). #494 added the new client calls to useFileOperations/useFileVersions but dropped the ensureFolderRegistered seeding there. Navigation/read populate only the Zustand store, never folderTree — so after a client re-creation (e.g. page reload) with no intervening mutation, the folder is absent and the save/version op throws synchronously. In the editor the rejected save leaves the modal open, which surfaced as the 30s timeout at writable-shares.spec.ts:330 (4.3 Alice edits Bob's file).

Because Web E2E does not run on PRs (only on push to main), the regression wasn't caught until #494 merged.

Changes

Add ensureFolderRegistered(parentFolder) before the client call at the three missed sites, mirroring useFolderMutations/useDropUpload. No-op when the folder is already tracked.

Key files:

• apps/web/src/hooks/useFileOperations.ts — owner edit-save path (the one the E2E hit)
• apps/web/src/hooks/useFileVersions.ts — restoreVersion + deleteVersion paths (same latent throw)

Verification

• Web E2E — green on this branch via manual dispatch: run 27579074392 (writable-shares 4.3 + full suite passed; previously the only failure on main).
• tsc --noEmit (apps/web) and eslint on both changed files pass.

Confirmed deterministic, not a flake: parent commit 0c2422c8c passed Web E2E twice; #494's commit d17d42e5f failed it; the only diff between them is #494.

Key Decisions

• Scoped to the regression — the three dropped ensureFolderRegistered calls — rather than a broader refactor.
• A full audit of all 21 web call sites of folderTree-dependent client methods found everything else correctly guarded (mutations, uploads, shared-write, bin permanentDelete/emptyBin); shareFolder/revokeShare have no web callers.

Follow-up

The audit surfaced one pre-existing gap (since #296, not this regression): recycle-bin restore (useBin.ts) hits the same 'Folder not loaded' throw after a reload. Its root cause is architectural — the SDK client config lacks the root IPNS private key, so it can't self-bootstrap or lazy-load folderTree, which is why the ensureFolderRegistered workaround exists at all. Captured as a todo for a proper fix (rootIpnsKeypair in config + internal ensureFolderLoaded lazy walk).

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Improved reliability of file operations by ensuring proper folder initialization before processing updates, deletions, and restores. Addresses scenarios where operations could fail if the folder structure wasn't pre-loaded.

• Chores

  • Updated planning documentation with architecture improvements for folder tree initialization.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 03a3d6e0-5bde-42ff-8988-eb10b9482d9f

📥 Commits

Reviewing files that changed from the base of the PR and between d17d42e and d6ffb4b.

📒 Files selected for processing (4)

• .planning/STATE.md
• .planning/todos/pending/2026-06-16-sdk-client-self-bootstrap-folder-tree-from-root-ipns-key.md
• apps/web/src/hooks/useFileOperations.ts
• apps/web/src/hooks/useFileVersions.ts

---

Walkthrough

ensureFolderRegistered(parentFolder) is added as a pre-step in useFileOperations.handleUpdateFile and in both the restore and delete flows of useFileVersions, ensuring the SDK client's folderTree is seeded before any SDK operation. A new planning document and a STATE.md update record a future architecture todo for SDK-side self-bootstrapping via a root IPNS keypair.

Changes

FolderTree Pre-registration in Web Hooks

Layer / File(s)	Summary
ensureFolderRegistered pre-calls in hooks apps/web/src/hooks/useFileOperations.ts, apps/web/src/hooks/useFileVersions.ts	Both hooks add ensureFolderRegistered to their sdk-provider import and call it with parentFolder before handleUpdateFile, restore, and delete operations to seed the SDK folderTree prior to routing.
Architecture todo and state tracking .planning/todos/pending/2026-06-16-sdk-client-self-bootstrap-folder-tree-from-root-ipns-key.md, .planning/STATE.md	New todo document specifies the "Folder not loaded" root cause, the bin-restore-after-reload failure mode, and a proposed SDK fix via rootIpnsKeypair + DFS-based ensureFolderLoaded. STATE.md is updated to reference this pending item.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• FSM1/cipher-box#489: Modifies ensureFolderRegistered itself to reconcile folderTree via client.reconcileFolderState, directly affecting the behavior of the pre-registration calls added in this PR.
• FSM1/cipher-box#454: Also modifies handleUpdateFile in useFileOperations.ts, making it code-adjacent to the pre-registration step added here.

Suggested labels

release:web:fix

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main fix: adding folder registration before SDK method calls in web hooks for file and version operations.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/owner-edit-folder-not-loaded

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Release Preview

Package	Bump	Label	Source
web	minor	release:web:fix	Direct (fix commit)