Ceedoku Client

The desktop client for Ceedoku.

Ceedoku Client packages the Ceedoku web game into a lightweight desktop application with local caching and offline fallback support.

Features

• Desktop Ceedoku — Run Ceedoku as a standalone application.
• Automatic updates — A separate native updater checks for Ceedoku Client releases and refreshes the Ceedoku game files.
• Offline fallback — If an update cannot be downloaded, the client can continue using the last cached version.
• .CSF support — Open Ceedoku Save Format (.csf) files directly with the client.
• Single instance — Opening the client again while it is already running forwards supported arguments to the existing window.

How it works

The native updater checks the latest Ceedoku Client release and compares the current game page with the cached copy. It opens its update window only when the client or game files need updating; when both are current, it starts the game directly. Client installers from new version tags are published as GitHub Releases.

On startup, the client:

1. Checks GitHub Releases for a newer client version and checks whether the cached game page has changed.
2. Starts the game directly when no update is needed.
3. Otherwise, shows the standalone native update window, installs the matching platform update when available, and refreshes changed game files through a hidden client process.

If an update check is unavailable but a previous cached game exists, the client launches using that cached version.

If no cached version exists, the client displays an offline page.

In development, the Electron client uses the local assets/loading.html loading screen. Installed releases run the native updater at startup, but show its window only when an update is needed.

Project structure

The client is an Electron application. Its main process is responsible for:

• Creating the application window
• Downloading and caching Ceedoku
• Handling redirects
• Resolving Ceedoku resources
• Opening .csf files
• Managing the application's single-instance lock
• Providing an offline fallback

The native updater source is in updater/. It is compiled separately for each release platform and packaged outside the Electron application bundle so it can remain running while a client update is installed. Windows releases use a Rust installer that embeds the packaged client and updater, shows installation progress, and installs per-user; Linux AppImage and macOS DMG releases continue to use electron-builder.

Releasing

The GitHub Actions workflow builds Windows, Linux, and macOS installers. A manual workflow run (workflow_dispatch) uploads the installers as workflow artifacts for testing. Pushing a tag matching package.json also publishes those installers as a GitHub Release; the tag must be v<version> (for example, v1.3.0).

To release after committing the changes:

git push origin main
git tag v1.3.0
git push origin v1.3.0

The Windows job packages the Electron app directory, embeds it with the native updater into the Rust installer, then uploads the architecture-specific installer. Linux and macOS jobs continue to produce AppImage and DMG installers. The package job combines all platform installers and attaches them to the GitHub Release for pushed version tags.

Development

Requirements

• Node.js
• npm
• Electron
• Rust and Cargo (for building the native updater and Windows installer)

Clone the repository:

git clone https://github.com/ceebug/ceedoku-client.git
cd ceedoku-client

Install dependencies:

npm install

Start the client:

npm start

Updating Ceedoku

The client pulls its game files from the Ceedoku website:

https://ceedoku.github.io

Only files hosted by the Ceedoku website are accepted by the cache downloader. This keeps the client tied to the official Ceedoku deployment rather than arbitrary external resources.

The client downloads the files required by Ceedoku, including the puzzle worker at:

src/js/puzzle-worker.js

Offline mode

Ceedoku Client is designed to keep a previously downloaded version available.

Error handling flow

Latest version
      ↓
 Download fails
      ↓
Cached version exists?
   ↙           ↘
 Yes            No
  ↓              ↓
Load cache    Offline page

This means a temporary network or server problem does not necessarily prevent Ceedoku from launching.

Ceedoku Save Format

Ceedoku Client supports opening Ceedoku Save Format (CSF) files.

CSF files can be passed to the application when launching it, allowing saved Ceedoku games to be opened directly in the client.

For more information about the format, see the Ceedoku CSF specification.

License

See the LICENSE file for licence information.

---

Ceedoku is free, open-source, and made by Ceebug.