API

Reference for the public surface of every package in the stack. Generated from the package source — see JSDoc for the full type-level view.

`@dev-bench/docstore`

Storage-agnostic interface package. No git knowledge — implementations include @dev-bench/gitapp (git-backed) and future obsidian-store / fs-store backends.

Interface

Export	Signature	Summary
`DocStore`	`interface`	Read / list / `runTransaction` / `watch` / `syncIn` / `drain`. Atomic mutations, opaque `versionToken` CAS.

Schemas + types (Zod)

Export	Kind	Summary
`ReadResult` / `ReadResultSchema`	union	`found \| missing` for `docStore.read`.
`DocEntry` / `DocEntrySchema`	type	Listing entry: `{ path, type, versionToken }`.
`IfMatch` / `IfMatchSchema`	union	Optimistic CAS token: `any \| absent \| version`.
`JsonPatchOp` / `JsonPatchOpSchema`	union	RFC-6902 op for `json-patch` mutations.
`FrontmatterBody` / `FrontmatterBodySchema`	union	Body for `upsert-frontmatter` mutations.
`IfMissing` / `IfMissingSchema`	enum	`create-empty \| fail` policy when target missing.
`Mutation` / `MutationSchema`	union	`put \| delete \| json-patch \| upsert-frontmatter`.
`ConflictPolicy` / `ConflictPolicySchema`	union	`fail \| retry-after-pull \| rebase-mutations`.
`Transaction` / `TransactionSchema`	type	Input to `runTransaction`.
`TransactionResult` / `TransactionResultSchema`	union	`ok \| conflict \| rejected \| network`.
`WatchEvent` / `WatchEventSchema`	union	Remote-driven change notification.
`SyncInResult` / `SyncInResultSchema`	union	Result of `syncIn()`.

Pin to the v1 API explicitly via @dev-bench/docstore/apis/v1.

`@dev-bench/git-fs`

Cross-platform git filesystem layer with browser / Node / in-memory adapters and provider-specific REST management.

Interfaces

Export	Kind	Summary
`GitFs`	`interface`	Read / list / commit / push / pull / clone / reset. Every method returns a discriminated union; nothing throws on user-recoverable conditions.
`RepoManagement`	`interface`	REST ops: `listMyRepos`, `createRepo`, `getRepo`, `currentLogin`. Provider-orthogonal.

Adapter factories (deep imports)

Import	Signature	Summary
`createBrowserGitFs`	`(BrowserGitFsConfig) => GitFs`	LightningFS (IndexedDB) + isomorphic-git web http.
`createInMemoryGitFs`	`(InMemoryGitFsConfig?) => GitFs`	Pure-memory fs for tests, sandboxes, fixtures.
`createInMemoryRemote`	`(id: string) => InMemoryRemote`	Pair with `createInMemoryGitFs` to simulate push/pull.
`createNodeGitFs`	`(NodeGitFsConfig) => GitFs`	Node fs + isomorphic-git node http.

Imports:

import { createBrowserGitFs } from "@dev-bench/git-fs/adapters/browser";
import { createInMemoryGitFs, createInMemoryRemote } from "@dev-bench/git-fs/adapters/in-memory";
import { createNodeGitFs } from "@dev-bench/git-fs/adapters/node";

REST management (deep imports)

Import	Signature	Summary
`githubManagement`	`(GithubManagementConfig) => RepoManagement`	GitHub REST.
`giteaManagement`	`(GiteaManagementConfig) => RepoManagement`	Gitea REST.
`gitlabManagement`	`(GitlabManagementConfig) => RepoManagement`	GitLab REST.

Imports:

import { githubManagement } from "@dev-bench/git-fs/mgmt/github";
import { giteaManagement } from "@dev-bench/git-fs/mgmt/gitea";
import { gitlabManagement } from "@dev-bench/git-fs/mgmt/gitlab";

ProviderId, TokenLookup (+ tokenAbsent / tokenPresent helpers), RepoRef, Author, FileChange, ReadFileResult, TreeEntry, HeadTreeState, CommitInput, CommitResult, PushResult, PullResult, ResetHeadResult, CloneResult, plus RepoInfo, CreateRepoArgs, CreatedRepo, RepoLookupResult, CurrentLoginResult for management ops. All exported as both *Schema (Zod) and T (inferred type).

Polyfills + tooling

Import	Summary
`@dev-bench/git-fs/polyfills/browser`	Web Crypto / SHA fallbacks for older browsers.
`@dev-bench/git-fs/metro-config`	Metro resolver tweaks for React Native.

`@dev-bench/gitapp`

Layer 2: a DocStore implementation that wires @dev-bench/git-fs storage into the @dev-bench/docstore interface.

Export	Signature	Summary
`createGitAppDocStore`	`(GitAppDocStoreConfig) => DocStore`	Build a `DocStore` from `gitFs`, `mgmt`, `repoRef`, `getToken`, `author`.
`GitAppDocStoreConfig`	`interface`	Config shape (see Getting Started).

Internals (escape hatches)

These let advanced consumers assemble their own DocStore using the same building blocks the canonical implementation uses.

Export	Signature	Summary
`SerialQueue`	`class`	FIFO promise queue; one-at-a-time transaction execution.
`WatchRegistry`	`class`	Prefix-keyed subscriber registry for `docStore.watch`.
`runTransaction`	`(RunnerConfig, Transaction) => Promise<TransactionResult>`	Bare transaction runner — no queue, no watch.
`runSyncIn`	`(RunnerConfig) => Promise<SyncInResult>`	Bare pull + watch-emit cycle.
`RunnerConfig`	`type`	Shared deps for `runTransaction` / `runSyncIn`.

`@dev-bench/gitapp-ui`

Layer 3: cross-platform UI primitives + components for any app built on top of the docstore. One codebase: React Native + react-native-web.

Peer dependencies: react, react-native (or react-native-web), react-native-svg.

Theme

Export	Kind	Summary
`ThemeProvider`, `useTheme`	component / hook	Theme injection.
`defaultLightTheme`	const	Light theme v1.
`mergeTheme`	function	Deep-merge a partial theme into another.
`Theme`, `ThemeColors`, `ThemeFonts`, `ThemeRadii`, `ThemeSpacing`, `ThemeShadow`, `ThemeShadows`, `ThemeTypography`	types	Token shapes.

Cross-component types

Export	Kind	Summary
`Resource`	const	Idle / loading / ready / error sentinel constructors.
`Resource<T>` (`ResourceT`)	type	The 4-state discriminated union every async control branches on.
`Err`, `StatusTone`, `Connectivity`, `ProviderId`	types	Shared across components.

Primitives

Component	Summary
`Icon` (+ `IconName`)	Themed icon set (RN-svg).
`Spinner`	Animated busy indicator.
`Chip`	Tag / pill.
`Dot`	Status dot.
`Banner`	Inline banner (info / warning / error).
`Button`	Themed pressable.
`Card`	Surface container.
`Skeleton`	Loading placeholder.
`ProgressBar`	Determinate progress.

Components

Each component takes a *ViewModel / *Model prop the host app implements. Async actions render the full idle / loading / ready / error cycle.

Component	Summary
`ConnectionPanel`	OAuth / PAT connection flow.
`RepoPickerSheet` (+ `RepoRow`)	Pick a repo from the user's accessible list.
`CreateRepoForm`	Create a new repo on the active provider.
`InitializationSequence` (+ `InitStepRow`)	Multi-step init progress (clone, validate, …).
`SyncStatusBar`	Reference 4-state sync indicator.
`SyncStatusBadge`	Compact always-visible sync state badge.
`ConflictShell` (+ `FileTreeRow`)	Layout shell for the conflict resolver.
`BranchGraph`	Divergence visualization.
`DivergenceExplainer`	Plain-English explanation of why local and remote diverged.
`ConflictResolverSheet` (+ `TextPreview`)	Per-file conflict resolution.
`RepoStateRecoveryPanel` (+ `FindingItem`)	Diagnose + recover a broken local repo.
`ValidationFailureBanner` (+ `FailureRow`)	Show schema-validation failures from a transaction.
`RepoStatusRow`	Single-line repo status.
`ResourceButton`	Button that renders a `Resource<T>` lifecycle.
`DiagnosticsSheet` (+ `DiagnosticsRow`)	Live diagnostics log surface.
`ProviderSelector`	GitHub / Gitea / GitLab picker.
`EditorialBadge`	Editorial-state chip (draft / pr-open / merged / …).
`ForkRepoButton`	4-state fork action.
`PullRequestComposer`	Compose / publish a PR over the docstore.
`EditorialQueueScreen` (+ `EditorialQueueRowCard`)	Top-level kanban/list of content records.
`RecordReviewSheet`	Per-record PR review (approve / request-changes / close).

Preview-slot adapters

Drop-in renderers for common record types in editorial UIs:

Component	Record type
`PreviewPpaTask`	PPA task.
`PreviewCmsArticle`	CMS article (frontmatter diff aware).
`PreviewBookmark`	Bookmark.
`PreviewPasswordEntry`	Password entry.

Domain types

Export	Kind	Summary
`RepoMode` (+ `RepoModeSchema`, `isWritable`, `describeMode`)	union + helpers	Read-only / writable repo mode.
`RecordEditorialState` (+ schema, `describeEditorialState`)	union	Editorial lifecycle of a single record.
`RepoEditorialMode` (+ schema)	union	Repo-level editorial mode (direct / pr-only / …).
`PullRequestRef` (+ schema)	type	Reference to a PR.
`readEditorialConfig`	function	Read editorial config from a `EditorialConfigSource`.

API