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, with current matcher/configuration contracts and explicitly marked historical v1 decisions.

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 change D1 lifetime equivalence:

• Split ratio — resizing does not change general lifetime equivalence. It does change exact saved configuration.

• 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 do not change D1 identity. Exact saved configuration still compares serialized presentation props.

Exact saved-configuration comparison

D1 remains the general lifetime matcher; do not add sizing to it. Pin Save uses pinConfigurationsEqual in tauri-app/renderer/utils/pin-template.ts instead. That comparison includes split sizing, normalized provider configuration and the structural AI source relation (target position in the tree, not generated frame IDs). It excludes note bodies, selection, open-note membership, editor state and conversation state. Object key order does not distinguish configurations.

findActivePinId prefers an exact match, then falls back to D1 plus structural AI relations. Duplicate Save uses only the exact comparison, including hidden Pins. A duplicate opens existing Pin settings; a modified configuration can become a new Pin even when the lifetime highlight remains on the old one.

Canonical TODO/Mind Map sources match by workspace and UUID after a move. A new UUID reusing the old path, or the same UUID in another workspace, does not match. Ordinary root documents keep path identity; invalid/incomplete canonical bindings are not silently reinterpreted as ordinary files.

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. This paragraph describes the historical single-temp UI. Current temporary-entry lifetime is documented in Frameset and Pin Architecture.

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

Structural live-tree changes must pass through the app's live-tree change path, so persistence and temporary-tree tracking observe the same result.

Why this matters

Provider swaps, split changes and structural configuration changes must reach handleLiveTreeChange. Bypassing it can lose divergence registration or persist a stale tree. The former v1 promise that every Note Tray layout change creates a new saved configuration no longer applies: Note Tray layout, selection and presentation live in its per-frame cache, outside serialized Pin configuration.

Consequence for new layout-aware providers

A provider that persists layout in its structural props must route that mutation through the live-tree change path. A provider whose layout is session state must use its cache/persistence coordinator instead; do not inject runtime layout or selection into Pin props solely to trigger divergence.

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

A board can promote an explicit initialBoardPath seed to its runtime routing path. For canonical TODO/Mind Map sources, the captured workspace and UUID remain authoritative on reopen: a move resolves the same note, and path reuse cannot select a different note. A saved path-only canonical board is refused rather than bound to whichever note now occupies that path. The explicit file picker can capture a new source binding. Ordinary root documents retain their path contract.

For Note Tray, normalizeInboxProviderConfig whitelists scope/defaults/policies; it does not interpret retired directory props. All folders includes Archives; folder scope includes descendants and may intersect an exact sticker. Defaults must create inside the scope. Applying scope changes does not retag/move existing notes or discard retained open editors.

Template application remints all frame/instance/branch IDs in two passes, then remaps active-frame intent and AI source targets that are valid Note Tray leaves. Missing or invalid source targets become null. This structural rule makes no claim about AI conversation ownership or server-side source enforcement.

ROOT generate-step settings isolation

Pin providerProps are not configurable at generation time. The ROOT's generate dialog has no settings step at all — it is a single step (app name, display name, workspace picker) and bakes no settings into the new LEAF — and 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.

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 for structural mutations. Note Tray runtime layouts instead use their per-frame cache; they must not be copied into saved configuration.

getActiveFramesetView caches on identity, not value

Historical v1 only: the WeakMap key was 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

The named function is historical v1. Current Save reads, validates, duplicate-checks and writes inside runSerializedSettingsWrite, sharing the existing settings queue with live-tree persistence. It captures the confirmed template before await but persists the latest live tree, checks workspace identity, and never installs a stale template snapshot after Save. See D9 for the original race, not an API to call today.

Draft exists iff draftFrameset !== undefined

Historical v1 only: 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.

• ピン — current end-user Pin operations.