源码快照 @ 2026-09-01 (source-only, 剔除非源码素材)

packages/workspace/file-reference/README.md

@@ -0,0 +1,76 @@
+# @tutti-os/workspace-file-reference
+
+Reusable workspace file reference contracts, picker state, and optional React UI.
+
+This package owns host-neutral file reference selection behavior for workspace
+surfaces that need to browse, search, upload, preview, open, or share file
+references. Hosts provide concrete file-system access through package contracts;
+desktop preload calls, tuttid transport wiring, host absolute paths, and
+product-specific integration stay in the consuming host adapter.
+
+The package uses logical workspace paths and keeps reference picking reusable
+across shared workspace features such as the agent GUI and issue manager.
+
+Published React entry points use APIs available across the repository's
+supported React 19 hosts. Avoid runtime imports that only exist in a newer
+React minor: frameworks such as Next.js may alias React to their bundled
+runtime even when dependency resolution installs a newer version.
+
+It also provides host-neutral provenance filter contracts, an external-store
+controller, and a controlled filter view. Hosts inject available Agent/member
+options; source implementations declare which dimensions they can enforce and
+apply active constraints before pagination. The package does not fetch a
+catalog or infer product-specific membership itself. Disabled catalog options
+remain available to host logic but are hidden by the controlled filter view by
+default; a host can opt into rendering them with `showDisabledOptions`.
+
+Browse pagination and search pagination are separate contracts. Existing
+sources keep using the legacy growing-limit search protocol even when
+`capabilities.paginated` enables browse cursors. A cursor-paginated search
+source must explicitly declare `capabilities.searchPagination: "cursor"`.
+`SearchResult.searchPagination` may override that default for one query, for
+example when a source routes provenance search through a legacy backend.
+
+For cursor search, the picker passes the returned `nextCursor` into the next
+fixed-size request and incrementally deduplicates only the incoming page before
+appending it to an immutable, bounded-block result index in source order. The
+index copies at most one small tail block per page, so deep pagination neither
+rescans all historical entries nor mutates a snapshot already observed by a
+consumer. The picker renders a virtual search window over that index; the DOM,
+icon subscriptions, focus updates, and selection updates therefore stay
+bounded even when every backend result remains reachable by scrolling. Once
+the browser scroll range is compressed, reaching the virtual window's logical
+end drives cursor continuation directly, so appending a page does not depend
+on the browser emitting another native scroll event.
+Repeated or cyclic cursors stop
+continuation with `ReferenceSearchCursorLoopError` instead of requesting the
+same page forever. A host that receives an expired backend cursor
+may throw `ReferenceSearchCursorExpiredError`; the picker clears the stale
+result set and restarts the same search from its first page.
+
+## Optional host actions and selection commands
+
+`ReferenceSourcePicker` accepts an optional `renderSidebarActions` slot for
+fixed Host-owned actions above the source tree. The slot is absent by default,
+so existing markup and interaction remain unchanged. Picker action contexts
+expose `selectTargets` for locating and selecting several authoritative source
+targets after a Host mutation; each located node still passes through the
+picker's active node-kind and single/multiple selection policy.
+
+## Content error recovery
+
+`ReferenceSourcePicker` accepts `resolveContentErrorAction` when a host can
+offer recovery for selected content errors. Return an action label for errors
+that should be retryable, or `null` to keep the default message-only state.
+Selecting the action reruns the failed browse, search, or filtered-tree request.
+Search recovery starts again from page one and never reuses a continuation from
+the failed request.
+
+```tsx
+<ReferenceSourcePicker
+  resolveContentErrorAction={(error) =>
+    isRecoverable(error) ? { label: copy.t("actions.retry") } : null
+  }
+  {...props}
+/>
+```