Skip to content

This is the Crystal Lattice Control desktop frontend (React Native macOS), bootstrapped using @react-native-community/cli and react-native-macos.

Versions

  • Desktop: react-native@0.81.5 + react-native-macos@0.81.1 (desktop/crystal-lattice-control-desktop-rn/package.json:1)
  • Mobile (reference): react-native@0.82.1 (mobile/crystal-lattice-control-rn/package.json:1)

Monorepo shared packages

This app imports workspace packages via file: dependencies:

  • @crystal-lattice/frontend-sdk
  • @crystal-lattice/frontend-sdk-react
  • @crystal-lattice/frontend-rn-components

Metro + TS are configured to handle symlinks (desktop/crystal-lattice-control-desktop-rn/metro.config.js:1, desktop/crystal-lattice-control-desktop-rn/tsconfig.json:1).

User documentation

Codex login boundary

Codex browser login is supported only when the desktop browser and the connected backend run on the same host, because the auth plugin owns a temporary localhost callback listener on port 1455 or 1457. For a remote backend, use device-code login. The desktop app does not exchange OAuth tokens, host a public callback relay, or embed a provider WebView.

Development documentation

Getting Started

Note: Make sure you have completed the Set Up Your Environment guide before proceeding.

Step 1: Start Metro

First, you will need to run Metro, the JavaScript build tool for React Native.

To start the Metro dev server, run the following command from the root of your React Native project:

# Using npm
npm start

# OR using Yarn
yarn start

Step 2: Build and run your app

With Metro running, open a new terminal window/pane from the root of your React Native project, and use one of the following commands to build and run your Android or iOS app:

Android

# Using npm
npm run android

# OR using Yarn
yarn android

iOS

For iOS, remember to install CocoaPods dependencies (this only needs to be run on first clone or after updating native deps).

The first time you create a new project, run the Ruby bundler to install CocoaPods itself:

bundle install

Then, and every time you update your native dependencies, run:

bundle exec pod install

For more information, please visit CocoaPods Getting Started guide.

# Using npm
npm run ios

# OR using Yarn
yarn ios

macOS

macOS builds require Xcode, the Node version in the repository .nvmrc, and the Ruby version in .ruby-version. The desktop package intentionally uses the same Ruby and Bundler versions locally and in CI.

brew install rbenv ruby-build
rbenv init

cd desktop/crystal-lattice-control-desktop-rn
rbenv install -s "$(cat .ruby-version)"
RBENV_VERSION="$(cat .ruby-version)" rbenv exec gem install bundler -v 4.0.15
RBENV_VERSION="$(cat .ruby-version)" rbenv exec bundle install
npm run ruby:check
npm run pod-install
npm run macos

The npm Ruby commands use the current Ruby when it matches the repository versions. If rbenv is installed but the shell has not initialized its shims, they fall back to the Ruby selected by .ruby-version through rbenv exec.

Build a signed macOS DMG locally

After installing the JavaScript dependencies and CocoaPods dependencies above, configure the existing signing credentials as described in macOS release maintenance. Then run this from the repository root:

npm run desktop:macos:build

The command runs the same Fastlane release lane as the customer build: verification, a universal Apple silicon/Intel Release archive with bundled JavaScript, Developer ID signing, DMG creation, Apple notarization, stapling, and validation. It requires signing credentials and network access but no running Metro server. Signing retrieval is read-only and verification is enabled.

On success, the command prints the DMG's absolute path, version/build, checksum, and an open command. The default version's DMG can be opened from the root:

open "desktop/crystal-lattice-control-desktop-rn/build/macos-release/Crystal-Lattice-Desktop-v0.9.0-universal.dmg"

Quit the running app, then drag Crystal Lattice Desktop onto the Applications shortcut in the mounted DMG and confirm Replace if prompted. The build command does not install, change your version, publish, or push. Rebuild after editing code; prior output is retained under the ignored build/macos-release-history/ directory.

npm run desktop:install installs JavaScript dependencies; it does not install the macOS app. Local review builds use the ordinary application bundle identifier and share preferences with the distributed version. The CLI runtime remains a separate process. A signed/notarized build must still be launch-tested; keep a known-good DMG until the new app has been checked.

Troubleshooting Ruby selection

Do not use Apple Ruby from /usr/bin or an arbitrary latest Homebrew Ruby. Check the active toolchain from the desktop package:

rbenv version
rbenv which ruby
ruby --version
npm run ruby:check

If rbenv version is correct but ruby --version is not, initialize rbenv in the shell after other Ruby PATH changes:

eval "$(rbenv init - zsh)"

Put that command on its own line near the end of ~/.zshrc, then open a new terminal. bundle update --bundler is not a setup command; changing the locked Bundler version also changes the CI/release toolchain.

Troubleshooting Node in Xcode

The Xcode bundle phases source macos/.xcode.env and the ignored macos/.xcode.env.local. The tracked environment file resolves Node from the repository .nvmrc, NVM, or the standard Homebrew locations. Install the repository Node version before launching Xcode:

nvm install
nvm use

For a custom installation, create macos/.xcode.env.local containing:

export NODE_BINARY=/absolute/path/to/node

If everything is set up correctly, you should see your new app running in the Android Emulator, iOS Simulator, or your connected device.

This is one way to run your app — you can also build it directly from Android Studio or Xcode.

Desktop transient UI

On macOS, anchored transient controls such as action menus and session filters must use the native NSPopover bridge. Do not present these controls through React Native Modal or the shared modal-backed dropdown surface. Keep reusable content in shared React components and mount that content in the desktop popover root.

macOS UI tests

The desktop app uses the existing XCUITest target on the host Mac rather than Detox. Run all macOS UI tests with:

npm run test:macos-ui

Most focused UI tests use Debug harness launches, so an ordinary Release instance can remain open during those tests. The human-time suite uses Release to prevent React Native development overlays from covering the bottom composer; macOS therefore terminates an already-running app with the same bundle identifier when that suite launches.

Run the focused native session-filter popover test with:

npm run test:macos-ui:session-filters

The focused command launches a deterministic harness that renders the production sessions panel and shared filter controls.

Run the focused production-flow human-time collection test with:

npm run test:macos-ui:human-time

The command starts a hermetic local backend, seeds sessions through the public SDK, drives the production connection/settings/chat/list UI, and verifies the sent user message plus a positive session SQLite row. It invokes XCTest in Release and should be run only when native UI test execution is intended.

Human-time integration test

The focused real-backend test exercises the production transport, server, duration-tracking plugin, and SQLite store without launching XCTest:

npm run test:integration -- \
  --runTestsByPath __integration__/humanTimeSpanUpload.realBackend.integration.test.ts

Inspect agent instructions

Crystal Lattice compiles project guidance into the effective developer/system message used by an agent session. To include task-file guidance:

  1. Open the active chat.
  2. Select Settings.
  3. In the Session settings window, enable Include TASKS Guidance.

Open the chat's session actions and select Show compiled system message to display the effective message in a separate action-display window. Inspection does not send a model request, save the session, or add to the conversation. Lengthy prompts scroll inside the window. Check that the expected project instructions and, when enabled, task guidance are present.

Step 3: Modify your app

Now that you have successfully run the app, let's make changes!

Open App.tsx in your text editor of choice and make some changes. When you save, your app will automatically update and reflect these changes — this is powered by Fast Refresh.

When you want to forcefully reload, for example to reset the state of your app, you can perform a full reload:

  • Android: Press the R key twice or select "Reload" from the Dev Menu, accessed via Ctrl + M (Windows/Linux) or Cmd ⌘ + M (macOS).
  • iOS: Press R in iOS Simulator.

Congratulations! :tada:

You've successfully run and modified your React Native App. :partying_face:

Now what?

  • If you want to add this new React Native code to an existing application, check out the Integration guide.
  • If you're curious to learn more about React Native, check out the docs.

Troubleshooting

If you're having issues getting the above steps to work, see the Troubleshooting page.

Learn More

To learn more about React Native, take a look at the following resources:

Transcript scroll diagnostics

Desktop transcript navigation and content-follow diagnostics are disabled by default. Enable concise lifecycle logging before the app is registered:

globalThis.CLC_DEBUG_CHAT_SCROLL_COORDINATOR = true;

Lifecycle mode reports navigation start/completion, bounded content-follow lease start/renewal/expiration, interaction cancellation, and operation timeouts. Repeated lease renewals are rate-limited so streaming logs remain copyable.

For frame-level native observations and correction writes, additionally set:

globalThis.CLC_DEBUG_CHAT_SCROLL_COORDINATOR_VERBOSE = true;

Verbose mode is intended for focused manual or harness runs and should normally remain disabled.

The entry point emits one [chatScrollBootstrap] line when lifecycle diagnostics are enabled. Each mounted transcript then emits one configuration event. Check both lines before interpreting a trace:

maxEdgeCorrections=60
manualBottomConvergenceMaxMs=15000
initialBottomConvergenceMaxMs=15000

Far FlatList item-anchor navigation additionally reports:

listAnchorStarted
listAnchorProgress
listAnchorCompleted
listAnchorStopped

The start event includes the effective timeoutMs and maxAttempts. These settings can be configured before application modules are loaded:

globalThis.CLC_FLATLIST_MAX_EDGE_CORRECTIONS = 60;
globalThis.CLC_FLATLIST_ITEM_ANCHOR_TIMEOUT_MS = 15000;
globalThis.CLC_FLATLIST_ITEM_ANCHOR_MAX_ATTEMPTS = 200;

Stable-geometry manual detachment

The coordinator classifies movement away from a pinned bottom using native event-to-event bottom gaps and geometry revisions.

An unexplained movement with stable content/viewport geometry reports:

awayMotionCandidate
reason=stableGeometryAwayMotion

The event includes bottom-gap and offset deltas, geometry revisions, active operation details, and whether the movement opposed a recent programmatic target.

An accepted candidate immediately reports:

manualBottomDetached
reason=stableGeometryAwayMotion

It latches manuallyDetached affinity, clears any follow lease, and cancels the active content-follow operation. Semantic content changes cannot reattach the transcript.

Stable manual movement back toward the bottom that crosses into the measured bottom threshold reports:

manualBottomReattachCandidate
manualBottomReattached

This changes affinity back to pinned without issuing a scroll command or starting a lease. The next semantic content change can then use normal bounded following. Active or recent programmatic navigation cannot trigger this manual-return transition. Successful explicit bottom navigation also reattaches after convergence.

A candidate that is compatible with a recent programmatic target is retained as a diagnostic but reports:

awayMotionDetachSuppressed
reason=recentProgrammaticMovementNotOpposed

An away movement observed while layout or semantic content is still settling reports:

awayMotionIgnored
reason=geometryChanged|recentGeometryChange|semanticContentPending

Candidate output is rate-limited to four lines per second and ignored output to two lines per second so a short manual gesture remains copyable.

License

Copyright 2026 Dynamic Programming Solutions Kft.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.