The Windows app: C# on .NET 10 with WinUI 3, for Windows 10 1809 and later and Windows 11, on x64 and Arm64, over the shared Rust core in core/ (core/AGENTS.md). This folder holds the app, the interop library it reaches the core through, the SQL editor and data grid controls, and their tests.
This is the guide for work under windows/. The root AGENTS.md holds the rules every app shares. Claude Code loads this file through windows/CLAUDE.md once a file under windows/ is read; Codex reads it when started in windows/.
- Tests define behavior, as in the root
AGENTS.md. - Native only. WinUI 3 controls, used as the Fluent guidance describes. No custom control where WinUI has one, no web view, no cross-platform toolkit. The SQL editor is our own control because RichEditBox failed its gate (
docs/decisions/0002-sql-editor-control.md), and the data grid because WinUI has none (docs/decisions/0003-data-grid-control.md). - The core does the work. Drivers, sessions, the catalog, result sets and error codes live in
core/. This folder words, lays out and styles. What the core lacks is added there, with its Rust tests. - Nothing generated is edited.
src/TablePro.Interop/Generated/changes only through the generator (Bindings, below).
TablePro.slnx: the solution.global.json: the .NET 10 SDK, and Microsoft.Testing.Platform as the runnerdotnet testuses.Directory.Build.props: nullable, warnings as errors and the latest recommended analyzers for every project.Directory.Packages.props: every package version..editorconfig: the C# style.src/TablePro.Interop: the library the app calls. Its public API is hand-written;Generated/holds the uniffi-bindgen-cs and csbindgen output, allinternal, so a generator upgrade cannot change what the app sees. The project is AOT and trim compatible, and its analyzers fail the build otherwise.tests/TablePro.Interop.Tests: xunit v3 tests against the real core and real SQLite files.Live/reads a table, the core's value corpus (core/crates/test-support/corpus) and a save on each engine's server, or in process for DuckDB; a server's tests skip whereci/live-servers.ps1did not start it (docs/decisions/0016-live-server-tests.md).src/TablePro.Editor.Model: the editor's text, carets, undo history, find, line-state highlighter and the Vim engine (Vim/, a port of the macOS one). Plainnet10.0with no WinUI, sotests/TablePro.Editor.Model.Testsruns anywhere.src/TablePro.Graphics: the one text and drawing stack the controls share: Direct3D, Direct2D and DirectWrite through TerraFX, the editor's swap chain and line layouts, theme colors, and the font fallback warm-up. Its types are internal to the controls.src/TablePro.Editor: theSqlEditorcontrol over that model: Direct2D and DirectWrite in a SwapChainPanel, TSF, the UIA text provider, and the core's lexer throughCoreSqlLexer.src/TablePro.DataGrid.Model: the grid's columns, selection, keys, cell blocks read from the core (ResultSetData), pending edits laid over them (EditedGridData) and Excel-style copy. Plainnet10.0, sotests/TablePro.DataGrid.Model.Testsruns anywhere; itsNeeds=Coretests load the real core.src/TablePro.DataGrid: theDataGridViewcontrol: ItemsRepeater rows that draw their cells with DirectWrite into composition surfaces, frozen columns, the header row, in-place cell editing with pending-change marks, and UIA peers.tests/TablePro.DataGrid.Testsandtests/TablePro.Editor.Tests: each control in a real WinUI window on a thread of its own, the app and window fromtests/Shared/WinUiApp.cs. They run on Windows and only compile elsewhere.tests/TablePro.DataGrid.Gateandtests/TablePro.DataGrid.Gate.Uia: the grid's timing and behavior gate, outside the solution.ci/run-gate.ps1builds and runs it;.github/workflows/windows-grid-gate.ymlruns it by dispatch.src/TablePro.App: the WinUI app: one window, the rail, the Connections page, the connection form window, Settings and a workspace per connection (docs/decisions/0004-app-shell.md). Strings are inStrings/en-US/Resources.resw.src/TablePro.App.Model: the app's settings and session files, the library tree, the connection form's fields, the object folders, the tab and connection lifecycles over small session, editor and run interfaces, and a table tab's pending edits. Plainnet10.0, sotests/TablePro.App.Model.Testsruns anywhere.tests/TablePro.App.UITests: UI Automation tests (FlaUI) that launch the built app with a data folder of their own, and the installed MSIX onceTABLEPRO_PACKAGEnames its family.ci/live-servers.ps1: starts one server theLive/interop tests reach on the x64 runner, forwindows.yml.ci/desktop.ps1: readies a hosted runner's desktop for UI work (privacy settings window, WSL console, display size, window dragging), forwindows.yml,release-windows.ymland the grid gate.ci/winget-manifest.py: writes a release's winget manifest, forrelease-windows.yml.scripts/engine-glyphs.py: writessrc/TablePro.App/Resources/EngineGlyphs.xamlfrom the macOS app's engine artwork. Run it after that artwork changes or an engine is added.scripts/package-assets.py: writes the MSIX logos insrc/TablePro.App/Assetsfrom the app icon. Run it after the icon changes.scripts/editor-schemes.py: writessrc/TablePro.Editor.Model/ColorSchemes.Themes.cs, the editor's color schemes, from the macOS app's built-in themes. Run it after a theme changes.RELEASING.md: how a release is built, signed, published and sent to winget.docs/decisions/: the decisions only the Windows app makes.- The core's side of the boundary:
core/crates/ffi(core/ARCHITECTURE.md, Bindings).
- Every async call starts on the thread pool, because the generated code finishes a call on the thread that awaits it. Its continuation comes back to the caller's context as usual.
- A
CancellationTokenfires the core's own cancel token, since UniFFI cannot cancel a call. A cancelled call throwsOperationCanceledException; a failed one throwsTableProException, whoseCodethe app words. A statement the server refused is not an exception: the run endsQueryOutcome.Failed. QueryEditor.Runreturns at once. Read the run's events withReadEventsAsyncon the UI thread; rows that arrive while it is busy come as one event.- A grid reads a
ResultSetthroughResultCursor.Fetch, one window per visible range. A cursor belongs to one thread, and a window cannot be read after the cursor's next fetch. DataGridView.SetData(new ResultSetData(set, columns))shows a set. Call the grid'sRowsChangedafter eachRowsAppended. Sorting is the host's: the grid raisesSortRequestedand showsSort.EditedGridData.Arrangesets the columns the grid shows and their order, andRearrangeColumnstells the grid; the grid's columns are then display positions, whichDataColumnmaps to the set's.- The core writes every sorted statement:
ReadTablePageAsyncreads a table's page with its sort and filter on a pooled connection and returns its run,SortedQuerywrites a query result's, null when the statement cannot run again or the engine cannot name the column.ResultSet.SortedAsyncthen sorts the rows held (core/docs/decisions/0007-sorting-a-result.md).ReadTablePageAsynctakes the page's offset, or for an engine that pages on the server (CanSeekfalse, Cassandra) thePageResumethe page before handed back throughNextPage(), since an offset there reads through every row before it;CountRowsAsynccounts the rows the filter picks, andEstimateRowsAsyncgives the whole table's count from the engine's statistics, null where it keeps none. The filter's values are bound by the core, never written into SQL here (core/docs/decisions/0022-browsing-through-the-ffi.md). GetTableInfoAsyncgives a table's row estimate, comment and data, index and total size, each null where the engine keeps none.ConnectionLibrary.SetGroupColorAsyncsets or clears a group's colour, andTableProCore.CheckJumpHostschecks the SSH jump hosts as a connect reads them (docs/decisions/0013-row-details-column-layout-and-selection-summary.md).GetStructureAsyncgives a table's columns, indexes, foreign keys and CREATE script,GetObjectDefinitionAsynca routine's, trigger's or sequence's source,ExportRowsAsyncandExportTableAsyncwrite a file through the core's encoders, andTableProCore.OpenHistoryAsyncthe query history, which withholds what the engine says holds a secret and keeps the age and countPruneAsyncis given.DatabaseSession.CatalogAbilitiessays what the engine does to whole tables, schemas and databases, andPlanCatalogChangegives aCatalogChangewith its statements and Safe Mode gate, whichRunAsyncruns once;RefreshSchemasAsyncreads the schemas again.ExportRowsAsyncandExportTableAsyncreport the rows written to anIProgress<long>(docs/decisions/0012-catalog-operations-table-filters-and-export-progress.md).QueryHistory.OpenSavedQueriesandOpenFavouritesgive the saved queries with their folders and the marked tables and databases, per saved connection, from the history's database;SetPinnedAsyncpins a run andExportAsyncwrites runs to a file.DatabaseSession.OpenCsvImportAsyncgives aCsvImportthat previews a file, suggests a mapping, plans it with a Safe Mode gate and runs it once; a field a column cannot read comes back asCsvImportCheck.RowRefused, not an exception.ConnectionLibrary.DuplicateAsynccopies a connection with its secrets andExportAsyncwrites the connections file without them (core/docs/decisions/0030-storage-import-and-library-through-the-ffi.md).- A table tab edits through
DatabaseSession.OpenTableEditorAsync: the app sends what was typed (CellEdit) per row of the page'sResultSet, andTableEditor.Plangives aRowSavewith its statements and Safe Mode gate, whichRunAsyncsaves (core/docs/decisions/0019-row-edits-through-the-ffi.md). EachEditColumnsays what it holds (Kind) and an enum's or a set'sLabels, which pick its editor;AppLink.Parsereads atablepro://link with the core's grammar (docs/decisions/0018-links-files-notifications-type-editors-and-json.md). - A query result edits through
DatabaseSession.OpenResultEditorAsync(sql, rows), the sameTableEditorwith one column per result column; itsLocksays why a result is not one keyed table's rows. The app refuses a run with several results, an open or unknown transaction and a tab in another database before it asks (core/docs/decisions/0033-foreign-import-and-result-editing-through-the-ffi.md). TableProCore.GetForeignSourcesAsynclists the other apps found underForeignAppDirs.ForCurrentUser(),ReadForeignAsyncgives aForeignImportReviewwhoseChoices()follow each check, andApplyAsyncwrites the connections, their passwords into Credential Manager and the saved queries once; DataGrip's KeePass key opens with the user's DPAPI (core 0033).DatabaseSession.Layoutsays how the server's databases stand to the catalog,GetDatabasesAsynclists them, andOpenEditorAsync(database)opens an editor that runs in one (opened there or moved there; one that cannot reach it throws).QueryEditor.Databasefollows a typed USE.TableProCore.ConnectAsync(database:)opens a saved connection in another of its databases, andOpenKeyreads a key-value engine's key a window at a time (KeyReader).SqlSyntax.TokenizeandSqlSyntax.Statementsread SQL as the core does, from the editor's UTF-16 text with no copy into a UniFFI string;Statementssplits asStatementAtand the drivers do. A failed run'sCoreError.Server.Positioncounts characters from 1 from the start of the SQL the run was given.QueryEvent.Finished.Transactionis the transaction the editor's connection is left in. A session'sHealthis waited on withWaitForHealthChangeAsync, which returns once it differs from the one passed in.- The app starts the core with
TableProCore.CreateWithSystemSecrets, so the core keeps secrets in Credential Manager itself.ISecretStoreis for tests and hosts with a store of their own; the core calls it on a thread of its own. TableProCore.Libraryreads and writes the saved connections in the storage directory the configuration names. A list the app shows is rebuilt fromGetSnapshotAsyncafter each change.- A result share's columns start from
ResultSet.GetShareMaskingAsync(what the detectors see),GetShareSummaryAsyncsays what a share with the sheet's choices sends andGetSharePreviewAsyncshows it masked as sent;CreateShareAsynctakes the same choices. Nothing else masks (docs/decisions/0010-data-masking.md). TableProCore.Assistantkeeps provider keys in the core's store (HasKeyAsync,SetKeyAsync; a key never comes back), lists models, writes a conversation's system prompt from a session's catalog (StartConversationAsync) and returns anAiReplyat once, whoseReadEventsAsyncstreams the text and endsFinished,FailedorStopped. A saved connection underAiPolicy.Neveris refused withai.blocked; asking under Ask is the app's (docs/decisions/0014-ai-assistant.md).TableProCore.OpenAccountAsyncopens the TablePro account once per app;ReadStatusChangesAsyncgives its status on the UI thread, and its share calls (GetShareLimitsAsync,CreateShareAsyncfrom a finishedResultSet,ListSharesAsync,RevokeShareAsync,ExtendShareAsync,FetchSharedAsync) throwaccount.*codes.ShareLinksholds the core's secret scan and deep link rule (docs/decisions/0008-tablepro-account.md,docs/decisions/0009-share-links.md).
Run dotnet from windows/: global.json is found only from here, and without it dotnet test refuses the test project.
dotnet build TablePro.slnx
dotnet test --solution TablePro.slnxOn macOS the solution builds TablePro.Editor as a compile check only: WinUI's PRI and manifest tools run on Windows.
The app and its UI tests build on Windows only, so they sit outside the solution. The UI tests run the Native AOT publish, as CI does:
dotnet build src/TablePro.App -r win-x64 -p:Platform=x64
dotnet publish src/TablePro.App -c Release -r win-x64 -p:Platform=x64 -p:CargoProfile=dev
TABLEPRO_APP="$PWD/src/TablePro.App/bin/x64/Release/net10.0-windows10.0.26100.0/win-x64/publish/TablePro.exe" dotnet test --project tests/TablePro.App.UITestsUse win-arm64 and ARM64 on Arm64. dotnet build makes a JIT build for the debugger; dotnet publish compiles with Native AOT, and a trim or AOT warning fails it. Both run unpackaged with the Windows App SDK beside them and keep their files in %LOCALAPPDATA%\TablePro, or in TABLEPRO_DATA_DIR; the UI tests give each launch a new folder there. -p:WindowsPackageType=MSIX -p:GenerateAppxPackageOnBuild=true with dotnet publish makes the MSIX, as RELEASING.md does, signed with -p:PackageCertificateThumbprint= and a certificate whose subject is CN=TablePro Development. TABLEPRO_UI_SCREENSHOTS names a folder for the tests' light and dark screenshots.
The build runs cargo build -p tablepro-ffi for the runtime identifier, or for the SDK's own platform when none is given, and copies the library next to the assembly. -r win-x64 or -r win-arm64 picks the target, -c Release builds the core with Cargo's release profile unless -p:CargoProfile= names another, CARGO_TARGET_DIR is honoured, and -p:SkipCoreBuild=true leaves cargo out. On Windows the core links the hybrid CRT, so RUSTFLAGS gains CoreRustFlags from src/TablePro.Interop/TablePro.Interop.csproj (docs/decisions/0005-distribution.md). Building needs the Rust toolchain that rust-toolchain.toml names, with the target added, and the .NET 10 SDK; on Windows, MSVC.
The core's Rust tests: cargo test -p tablepro-ffi, from the top of the repository.
.claude/skills/fix-issue/scripts/verify.sh --platform windows <step> runs these with a verdict; its steps and when each runs: .claude/skills/fix-issue/references/platform-windows.md, Verify.
The generated files are committed: the API change is reviewed in the pull request, a build needs no generator, and an editor knows the types before the first build. CI's macOS job generates them again and fails when they differ.
After a change to the FFI crate's exported API, its UniFFI items or src/window_abi.rs, generate them and commit the result:
cargo install uniffi-bindgen-cs --locked --git https://github.com/NordSecurity/uniffi-bindgen-cs --tag v0.11.1+v0.31.0
dotnet msbuild src/TablePro.Interop -t:GenerateBindingsPass -p:UniffiBindgenCs=<path> when it is not on PATH; the target refuses another version. uniffi-bindgen-cs supports one UniFFI minor, 0.31, so it and the core's uniffi move together. Its settings are in core/crates/ffi/uniffi.toml, and csbindgen runs as the crate's csbindgen example.
- Tests. Behavior of the interop library gets a test in
tests/against a real database file. Behavior of the core gets its Rust test incore/crates/ffi. - Code style.
.editorconfigand the analyzers; a warning fails the build. A comment is one//line that says why, never what: no XML doc and no multi-line block. - Commits and pull requests follow the root rules, with scope
windowsorwindows-<area>.
.github/workflows/windows.yml, which ci.yml calls when the windows suite changed (.claude/rules/ci.md). It builds the core and runs the tests on x64, Arm64 and macOS runners, the Live/ tests against their servers on a second x64 runner, publishes the app with Native AOT and runs its UI tests on the Windows runners with their screenshots as an artifact, and on macOS checks the committed bindings. CI's Lint job runs zizmor on every workflow. .github/workflows/release-windows.yml builds and ships a release (RELEASING.md).