Zinto

Zinto is a desktop application framework. It uses Zig for the backend and Svelte for the frontend. Bun manages the build toolchain.

Core Stack

• Backend: Zig 0.15.2.
• Frontend: SvelteKit with adapter-static.
• Build Tool: Bun.
• Webview: turf.
• Async I/O: libxev.

Architecture

Process Model

The application runs as a single native binary. The main thread manages the OS window and webview loop. A background thread runs the libxev event loop for non-blocking I/O.

IPC Bridge

Communication between Svelte and Zig uses a JSON-based message bridge. Zig uses comptime reflection to parse and dispatch commands.

Asset Handling

Zig embeds the frontend production build directly into the binary. A custom URI scheme (zinto://) serves these assets from memory. The handler includes a fallback to index.html to support client-side routing.

Project Structure

• /src: Zig backend source code.

• main.zig: Entry point and window initialization.

• bridge.zig: Comptime IPC dispatcher.

• assets.zig: Embedded file map.

• /frontend: Svelte project.

• build.zig: Unified build script for Bun and Zig.

Build Pipeline

1. Frontend: build.zig executes bun install and bun run build.
2. Codegen: A build step scans frontend/dist and generates assets.zig.
3. Compilation: Zig compiles the backend code and embeds the assets.
4. Output: A single executable under 1MB.

Quickstart (Scaffold)

This repo now contains a working scaffold that matches the architecture described above:

• A Zig backend skeleton under src/ with:
  • src/bridge.zig: JSON IPC + comptime API dispatch (starter ping + echo)
  • src/assets.zig: placeholder asset server (overwritten by codegen)
  • src/webview_stub.zig: stub webview adapter so the project has a runnable contract even before integrating a real webview library
  • src/async.zig: background worker thread (placeholder for a real libxev loop)
• A SvelteKit + adapter-static frontend under frontend/ that builds to frontend/dist.

Prereqs

• Zig 0.15.2
• Node.js 25.3.0 (recommended for local tooling; Bun is the build tool)
• Bun

Commands

From repo root:

• Generate embedded assets + TypeScript API definitions:

  • zig build codegen

• Build:

  • zig build

• Run (stub webview prints the embedded index.html preview to stdout):

  • zig build run

Next integration steps

• Replace src/webview_stub.zig with a real implementation (e.g., turf/webview) and:
  • bind the zinto:// protocol handler to src/assets.zig
  • bind the IPC handler to src/bridge.zig and dispatch results back via the webview’s dispatch mechanism
• Replace src/async.zig’s placeholder loop with a libxev event loop and message passing as described below.

Implementation Requirements

Windowing

Initialize a native window using webview-zig. Bind the zinto:// protocol to the embedded asset map. Ensure the webview blocks the main thread.

Concurrency

Spawn a thread for libxev. Use an atomic queue to pass messages from the webview thread to the async thread. Use webview_dispatch to return results to the UI.

Type Safety

The build system must generate a TypeScript definition file (api.d.ts) based on the exported Zig functions in bridge.zig.