Frameset–Pin Contract

Design-decision record for the frameset/pin matching, draft-divergence, live- tree selector, pristine-snapshot rollback, and debounced-save flush subsystem introduced in Epic #1744 (Wave 5, sub #1757). Implementors must treat this document as normative: if code disagrees with the spec here, the spec wins.

Why this contract exists

The Frameset Pin Architecture epic (#1744) replaced the previous ad-hoc frameset switching with a principled system: every saved frameset is a named, identity-comparable snapshot, and the live UI tree is continuously matched against that set. When the live tree diverges from all saved framesets, the app enters a "draft" mode rather than silently corrupting the saved copy. This document captures the ten design decisions that make that system correct and deterministic.

D1 — Matcher equivalence rule

Two frameset trees are equivalent iff they share the same structure shape, the same providerId at every leaf, and the same matchIdentity(props) value at every leaf. Split ratio, frameId, instanceId, and per-leaf state are NOT compared.

Implementation

framesetsEquivalent in packages/frameset/src/matcher.ts recursively canonicalises both trees via canonicalize, then JSON-stringifies and compares the result. canonicalize descends the tree and at each leaf node calls:

registry.getProvider(leaf.providerId)?.matchIdentity(leaf.props)
  ?? defaultMatchIdentity(leaf.props)

where defaultMatchIdentity returns { layoutId: props.layoutId ?? null } from raw JsonValue.

Provider matchIdentity table

core.external-file-editor uses a sorted set of open paths so that opening the same files in a different order still produces a match. "Opening a different file" means a different set of open paths — adding or removing even one file produces a distinct identity.

What is NOT compared

The following differences do NOT cause divergence:

• Split ratio — resizing a divider between panes is cosmetic.

• frameId — generated per tree-restructure; carries no semantic identity.

• instanceId — survives provider swap and pop-out; not a structural key.

• Leaf state ("normal" / "collapsed" / "zoomed" / "popped-out") — visibility variants of the same provider instance.

• Embedded-pane collapse — EFE treeCollapsed and Doc Cloud outlineCollapsed persist as presentation state but never change pin identity.

Defining matchIdentity on a new provider

Add matchIdentity(props: JsonValue): unknown to the provider object. Return a JSON-comparable value whose equality implies "same logical content". The returned value is passed through JSON.stringify and compared as a string, so nested objects and arrays are fine — just ensure order stability for arrays (sort them). If your provider does not declare matchIdentity, the default { layoutId } identity is used automatically.

D2 — Draft frameset slot

AppSettings.draftFrameset is an ephemeral field that is present when and only when the live tree has diverged from all saved framesets. currentFramesetId ALWAYS resolves to a real saved-frameset id — there is no "draft" sentinel value for that field.

Type signatures

// packages/app-defaults/src/types.ts

interface AppSettings {
  // …other fields…

  /** Id of the currently-active saved frameset. */
  currentFramesetId: string;

  /**
   * Present when the live tree has diverged from every saved frameset.
   * Absence (undefined) means the live tree matches currentFramesetId exactly.
   * Design decision D2 (#1744): currentFramesetId ALWAYS resolves to a saved
   * frameset — "user is on a draft" is expressed only via this field's presence.
   */
  draftFrameset?: {
    tree: FramesetTree;
    activeFrameId?: string;
    /** The saved frameset the user was on when they first diverged. */
    originFramesetId: string;
    createdAt: number;
    updatedAt: number;
  };
}

Lifecycle

The draft's originFramesetId records which saved frameset the user was on immediately before they first diverged. Discard restores currentFramesetId to that value.

D3 — Live-tree selector

All consumers of the current frameset tree MUST read from getActiveFramesetView (tauri-app/renderer/lib/frameset-selectors.ts). Direct indexing of framesets[] by currentFramesetId is forbidden.

ActiveFramesetView interface

interface ActiveFramesetView {
  /** The tree to render. Draft tree when isDraft; saved tree otherwise. */
  tree: FramesetTree;
  /** Active frame within the tree (if known). */
  activeFrameId?: string;
  /** True when the live tree is a draft (diverged from all saved framesets). */
  isDraft: boolean;
  /** Id of the saved frameset this view is logically tied to. */
  savedFramesetId: string;
  /** Present only when isDraft; the saved frameset the user diverged from. */
  originFramesetId?: string;
}

getActiveFramesetView contract

function getActiveFramesetView(
  framesets: Frameset[],
  currentFramesetId: string,
  draftFrameset?: DraftFrameset,
): ActiveFramesetView | null

• Returns null only when framesets is empty (app is initialising).

• Falls back to the inbox frameset or framesets[0] when currentFramesetId is not found (e.g. deleted frameset id still in settings).

• When draftFrameset is present, tree is draftFrameset.tree and isDraft = true; otherwise tree is the matching saved frameset's tree.

• WeakMap-cached. The selector memoises on (framesets, currentFramesetId, draftFrameset) identity so callers do not re-render from reference churn.

Why not index directly

framesets is an array. Finding the active frameset by currentFramesetId is a linear scan. More importantly: during the brief window after a draft is promoted or discarded, the live currentFramesetId may not yet match any entry in the serialised framesets[] snapshot the component sees. getActiveFramesetView handles these edge cases uniformly; ad-hoc indexing at every call site re-creates the same bugs.

D4 — Pin highlight derivation

Pin highlight state is a pure derivation — it is never stored. A pin is highlighted iff the live tree currently matches the pin's saved frameset AND no draft is active.

Derivation rule (pseudocode)

const isHighlighted =
  !draftFrameset &&
  pin.framesetId === currentFramesetId &&
  useCurrentMatchingFramesetId() === pin.framesetId;

The double guard is necessary:

1. pin.framesetId === currentFramesetId — the pin points to the currently-selected saved frameset.

2. useCurrentMatchingFramesetId() === pin.framesetId — the live tree currently matches that saved frameset (not some other saved frameset the user navigated to mid-draft).

Without guard 2, a pin would stay highlighted even when the user navigates away but has not yet diverged. Without guard 1, the wrong pin would highlight when the user happens to match a non-current frameset.

Temp pin

When draftFrameset is present, no saved pin is highlighted. Instead, a temp pin (TempPin component in toolbar.tsx) appears with a LayoutGrid icon in the left cluster. It represents the unsaved diverged tree. See Temp pin UX in the user guide for the interaction details.

D8 — Pristine snapshot rollback

Each saved frameset has a pristine baseline snapshot, seeded from the on-disk tree at hook load. When the live tree diverges from a saved frameset, that frameset's stored tree is rolled back to its pristine baseline — preventing the saved frameset from silently tracking in-flight mutations.

Implementation

useSavedFramesets (tauri-app/renderer/hooks/use-saved-framesets.ts) maintains:

const pristineTreeByFramesetIdRef = useRef<Map<string, FramesetTree>>(new Map());

The map is seeded once, when the hook first loads framesets from disk. It is never updated after that seed (unless a frameset is created, at which point its initial tree is added).

When handleLiveTreeChange detects divergence from frameset F:

1. It reads pristineTreeByFramesetIdRef.current.get(F.id) to get the baseline.

2. It writes the baseline tree back into F's stored entry in settings.

3. It sets draftFrameset to the current live tree.

This ensures that if the user discards the draft, the saved frameset is the same shape it had when the user last explicitly saved it — not some intermediate state the live tree happened to pass through.

Why the name "pristine"

"Pristine" = untouched by in-flight mutations. The baseline is the snapshot from disk, before any live-tree changes. Contrast with "saved" (which in casual speech could mean "last-written-to-disk", including intermediate writes the hook does for other reasons).

D9 — Debounced-save flush contract

promoteDraftToPin and discardDraft MUST call flushPendingSave() before writing any new settings state. Skipping the flush can cause a debounced save to overwrite the newly-written state.

Context

useSavedFramesets debounces settings writes: live-tree changes queue a save that fires 300 ms after the last change. promoteDraftToPin and discardDraft also write settings. If the debounced timer fires between the point where the action reads the current state and the point where it writes, the debounced write overwrites the action's result.

flushPendingSave() cancels the pending timer and executes the save immediately, so the state the action reads is the same state on disk when it writes.

Call order

async function promoteDraftToPin(opts) {
  flushPendingSave();           // ← must be first
  // … build new Frameset + HeaderLeftPin …
  await writeSettings(next);    // ← safe: no pending timer can race
  await validateSettings(next);
  await syncToDisk(next);
}

async function discardDraft(opts) {
  flushPendingSave();           // ← must be first
  // … restore originFramesetId, clear draft …
  await writeSettings(next);
}

Any future action that reads-then-writes settings within a component that owns a debounced save MUST follow the same pattern.

D10 — Layout-change divergence routing

Layout-change events from useInboxLayoutPersistence and useArchivesLayoutPersistence route through handleLiveTreeChange rather than calling updateFramesetTree directly. This ensures that switching layouts can trigger draft mode when the new layout does not match any saved frameset.

Why this matters

Layout persistence hooks listen for FRAME_LAYOUT_CHANGE_EVENT and update the leaf's layoutId prop inside the live tree. Before D10, they called updateFramesetTree directly — bypassing the matcher. This meant that switching from "list" to "now" on the inbox never produced a draft, even if no saved frameset had layoutId: "now" at that leaf.

After D10, every live-tree mutation (resize, layout switch, provider swap) routes through handleLiveTreeChange. The matcher runs on every mutation and diverges the tree into draft mode if needed.

Consequence for new layout-aware providers

Any provider that emits layout changes (via FRAME_LAYOUT_CHANGE_EVENT or equivalent) MUST wire its persistence hook to handleLiveTreeChange. Calling updateFramesetTree directly is forbidden — it bypasses the matcher and prevents draft mode from triggering correctly.

D5 — Pin providerProps schema

HeaderLeftPin.providerProps is a typed per-provider map. New provider-specific providerProps keys MUST be added to PinProviderPropsByProviderId in packages/app-defaults/src/types.ts.

Schema table

PinProviderPropsByProviderId in @takazudo/app-defaults maps each provider id to its known providerProps fields:

Doc Cloud pins always contain one core.doc-cloud leaf. The outline is an embedded pane, never a second provider or a two-leaf template.

The old standalone Directory View provider is a deliberate pre-release break: there is no migration for pins or trees that still name it. Validation may preserve an opaque old pin, which can render provider-not-found until the user removes it or resets settings; no local file content is changed. The retired id must not be registered as a compatibility provider.

Promotion semantics for initialBoardPath

todoBoardProvider.deserialize (and the kanban / mindmap equivalents) checks whether base.filePath === "" and the serialised JSON carries a non-empty initialBoardPath. If so, it promotes the pin field to filePath on first deserialise. This allows pins to encode a target file path without the provider needing to understand how pins work.

ROOT generate-step settings isolation

Pin providerProps are not configurable from the ROOT's generate-child settings step (Step 2 of the generation flow). The shared settings sections in packages/settings-sections/src/sections/ contain neither terminal settings nor pin editors. Pin providerProps are configured per-pin inside the generated LEAF app's Manage header pins dialog, not at generation time.

Watch-for-next-time patterns

These patterns are known footguns. They appear here so the next implementor does not rediscover them.

Provider matchIdentity with arrays — sort them

If matchIdentity includes an array (e.g. the list of open paths in core.external-file-editor), the array must be sorted before returning it. canonicalize uses JSON.stringify for comparison; ["a","b"] and ["b","a"] stringify differently even though they represent the same set. core.external-file-editor sorts openPaths alphabetically before returning { layoutId, paths }.

Do not call updateFramesetTree from layout-persistence hooks

See D10. Every live-tree mutation must go through handleLiveTreeChange. Ad-hoc calls to updateFramesetTree bypass the matcher and silently suppress draft mode.

getActiveFramesetView caches on identity, not value

The WeakMap key is the framesets array reference and the draftFrameset object reference. If a caller recreates these on every render (e.g. via useMemo with too broad a dependency), the cache misses on every call. Ensure framesets comes from a stable store slice and draftFrameset is the same object reference between renders when it has not changed.

flushPendingSave before any read-modify-write on settings

Any action that (1) reads the current settings, (2) does async work, and then (3) writes new settings, MUST call flushPendingSave() before step 1. A pending debounced write that fires between steps 1 and 3 will overwrite step 3's result. See D9.

Draft exists iff draftFrameset !== undefined

Do not test draftFrameset === null — the field is undefined when absent, not null. JSON.parse of a settings file that omits draftFrameset returns an object with the key absent (not null). A null check will pass when it should not.

See also

• Frame Component Contract — provider shape, leaf-state schema, toolbar slot, and active-frame border.

• Header Pins Architecture — data-flow, routing trade-off, and the two metadata-only registries.

• Header Pins User Guide — creating, editing, and managing pins; divergence flow and the temp pin UX.