DEV Community: puffball1567

How to Write Object-Oriented Code in Go: Structs, Methods, Interfaces, and Composition

puffball1567 — Mon, 14 Sep 2026 02:59:00 +0000

Go does not have classes or inheritance, but it does not prevent object-oriented design. It simply moves the building blocks into different language features: structs hold state, methods attach behavior, interfaces describe capabilities, and composition assembles collaborating parts.

The productive question is not “how can I recreate a class hierarchy in Go?” It is “which data owns this behavior, and which dependency should this component require?” This article builds a small application service around that question.

Start with data and behavior

Suppose an application lets a user change their display name. The domain value is a struct, while the operation belongs on a service that has access to user storage.

package users

import (
    "context"
    "errors"
)

type User struct {
    ID          int64
    DisplayName string
}

type Repository interface {
    FindByID(ctx context.Context, id int64) (User, error)
    Save(ctx context.Context, user User) error
}

type Service struct {
    repository Repository
}

func NewService(repository Repository) *Service {
    return &Service{repository: repository}
}

func (s *Service) Rename(ctx context.Context, id int64, name string) (User, error) {
    if name == "" {
        return User{}, errors.New("display name is required")
    }

    user, err := s.repository.FindByID(ctx, id)
    if err != nil {
        return User{}, err
    }

    user.DisplayName = name
    if err := s.repository.Save(ctx, user); err != nil {
        return User{}, err
    }
    return user, nil
}

User is a value with data. Service is a struct with a dependency and a cohesive operation. The constructor function makes the dependency explicit at creation time. None of these types needs a base class to have a clear responsibility.

Define interfaces where they are consumed

The Repository interface above belongs next to Service, not necessarily next to a database implementation. The service states the smallest capability it needs: load a user and save a user. Any type with those methods satisfies the interface automatically.

That has two useful consequences. Production code can use a PostgreSQL-backed repository, while a test can use a small in-memory fake. Neither implementation needs to import a shared “repository base class” or declare that it implements the interface.

type MemoryRepository struct {
    users map[int64]User
}

func (r *MemoryRepository) FindByID(_ context.Context, id int64) (User, error) {
    user, ok := r.users[id]
    if !ok {
        return User{}, errors.New("user not found")
    }
    return user, nil
}

func (r *MemoryRepository) Save(_ context.Context, user User) error {
    r.users[user.ID] = user
    return nil
}

This is dependency inversion without a framework. The application service depends on a capability, rather than on a particular storage driver.

Prefer composition to inheritance

Go supports struct embedding, but embedding is not a substitute for a deep inheritance tree. It promotes fields and methods from one struct into another; it does not give Go classes, virtual methods, or a general subtype model.

For backend code, explicit fields are usually clearer than embedding. If a service needs a clock, a logger, and an email sender, name them as dependencies:

type EmailSender interface {
    Send(ctx context.Context, to string, subject string, body string) error
}

type NotificationService struct {
    users UserLookup
    email EmailSender
}

This makes the object graph visible, keeps testing straightforward, and avoids coupling unrelated behavior through a shared parent type. Use embedding when the promoted behavior genuinely reads as part of the receiving type, not merely to reduce typing.

Keep interfaces narrow and delay abstraction

Not every struct needs an interface. A useful default is to create a concrete type first, then introduce an interface at the consumer boundary when a second implementation or a test seam actually exists.

Large interfaces tend to become accidental framework contracts. Small interfaces are easier to implement, easier to test, and clearer about what an operation needs. Go’s standard library follows this style: a type only needs to provide the methods required by the consumer.

A practical Go OOP checklist

Use structs to group state.
Attach behavior with methods when that behavior naturally belongs to the state or service.
Use constructor functions to make required dependencies explicit.
Define small interfaces at the point where they are consumed.
Prefer explicit composition to inheritance-shaped abstractions.
Pass context.Context through request-scoped backend operations.
Keep transport concerns such as HTTP request parsing outside domain services.

This approach is object-oriented in the useful sense: state, behavior, dependencies, and boundaries have clear ownership. It just does not require a class hierarchy to achieve it. The official Go documentation on methods and interfaces is a good companion when learning the language mechanics.

Kinmokusei

Kinmokusei is a programming language with TypeScript-inspired syntax that compiles to readable Go. It is intended for writing web backends and Go libraries while using the normal Go toolchain and package ecosystem directly.

Kinmokusei v0.2.0: Generic OOP and Go Type Constraints for a TypeScript-Inspired Language

puffball1567 — Sat, 12 Sep 2026 18:37:19 +0000

Kinmokusei v0.2.0 expands the language in the places where application code and the Go ecosystem meet: generic object-oriented programming, generic constraints, type aliases, and JSON interop. Kinmokusei uses TypeScript-inspired syntax, but compiles to readable Go and uses the ordinary Go toolchain and package ecosystem directly. This release makes several of those boundaries more capable without treating generated Go as an opaque implementation detail.

Generic class inheritance and virtual dispatch

Classes in Kinmokusei are reference types. v0.2.0 adds generic class static methods, generic class inheritance, and generic virtual dispatch. A generic derived class can inherit a base class with concrete or remapped type arguments, retain the inherited state, and override a virtual member while preserving the expected dispatch behavior through the hierarchy.

That matters when a reusable abstraction carries its data type through more than one layer. A paged result, a domain-specific collection, or a typed application model should not need to discard its type parameter merely because it adds behavior in a derived class.

The release also adds descendant-aware class downcasts. A checked downcast can recover a more specific type within the same class hierarchy while keeping the failure path explicit, rather than silently assuming that every base-class value has the desired derived shape.

const [guide, ok] = animal as? GuideDog;
if (ok) {
  console(guide.speak());
}

The checked form returns a value together with a boolean result. It makes the runtime boundary visible at the call site, while reference identity and virtual dispatch remain part of the class model.

Use Go type-set constraints from Kinmokusei

Go libraries increasingly express generic capabilities through interface type sets. v0.2.0 lets Kinmokusei use exported constraints from the Go standard library and external Go modules, rather than limiting generic code to comparable.

For example, code can use a constraint such as cmp.Ordered when an operation really requires an ordered value:

import go cmp from "cmp";

function earlier<T extends cmp.Ordered>(left: T, right: T): boolean {
  return left < right;
}

This is useful because it keeps the constraint owned by the Go package that defines it. Kinmokusei code can participate in the same generic API shapes as Go code, instead of recreating a parallel constraint vocabulary.

Generic aliases without raising the minimum Go version

v0.2.0 also adds transparent generic aliases. An alias can give a reusable Kinmokusei name to a parameterized shape without introducing a new nominal type:

alias Values<T> = T[];
alias Lookup<K, V> = Map<K, V>;

The compiler expands a generic alias to its instantiated underlying type at generated-Go boundaries. That detail is important for compatibility: the emitted code remains usable with the project's Go 1.23 minimum instead of depending on later Go generic-alias declarations. Kinmokusei tooling still retains the source-level alias, while Go consumers see the concrete Go type they expect.

v0.2.0 also permits a native struct as the underlying representation of a distinct type. This gives application code a way to add nominal meaning to an existing value layout while keeping conversions explicit and retaining Go-compatible value behavior.

Stable JSON behavior for generic and inherited classes

JSON is often the point where a type system meets an external API, stored data, or a frontend. v0.2.0 stabilizes JSON interop for generic classes: public fields use stable Kinmokusei field names, inherited public state is included, and private or protected state is excluded.

Decoding into a class instance preserves the class's reference-oriented model. Constructor-created instances retain their identity and virtual dispatch behavior, rather than being reduced to an unstructured map at the application boundary. Where a wire format needs special initialization or a different representation, an application can still define its own JSON handling.

A release focused on typed boundaries

These features are connected by the same goal: carry useful type information across the boundaries that real Go applications need to cross. Generic classes can model reusable reference-oriented behavior, Go type sets make interop constraints available directly, generic aliases keep source code readable without increasing the Go version requirement, and stable JSON rules make external data handling predictable.

Kinmokusei v0.2.0 is available now. Developers with Go installed can try the release with:

go install github.com/puffball1567/kinmokusei/cmd/keika@v0.2.0
keika version

The compiler supports Go 1.23 through Go 1.27. The release notes, source, and executable examples are available in the Kinmokusei repository.

Introducing Kinmokusei: TypeScript-Inspired Syntax That Compiles to Readable Go

puffball1567 — Fri, 04 Sep 2026 16:31:55 +0000

On August 31, 2026, I released Kinmokusei v0.1.0, the first public preview of a programming language for writing web backends and Go libraries with TypeScript-inspired syntax and compiling them to readable Go source.

The compiler command is named keika, source files use the .km extension, and the generated program remains part of the ordinary Go ecosystem: it uses Go modules, the Go toolchain, the Go ABI, the Go runtime, and existing Go packages directly. Go—not TypeScript—is the compatibility target.

Repository: https://github.com/puffball1567/kinmokusei

What Kinmokusei is

Kinmokusei is a source language for the Go ecosystem. It resembles TypeScript, but it is not TypeScript. It is intended for developers who like TypeScript-shaped syntax but want to build and publish ordinary Go programs and libraries. Its syntax is the approachable frontend; Go is the platform underneath and the main compatibility boundary.

It is not a TypeScript-to-Go converter, transpiler, or TypeScript implementation. It does not accept .ts files or existing TypeScript projects and turn them into Go. It is also not Go source with alternate punctuation. Kinmokusei is a separate language with its own .km source, type system, and explicit constructs for behavior that must lower predictably to Go, including Go named types, pointers, multiple return values, interfaces, generics, channels, errors, and nil.

The central design choice is that generated Go is not a hidden temporary representation. It is deterministic, formatted with gofmt, readable by a Go developer, and suitable for inspection or publication.

.km source
    ↓ keika check / build / emit-go
readable Go source
    ↓ standard Go toolchain
native executable or Go library

Authors can distribute the .km source, the generated Go module, or both.

Go compatibility instead of npm compatibility

Kinmokusei deliberately does not target npm, Node.js, browser JavaScript, or the TypeScript package ecosystem. An npm package cannot be imported merely because the source looks similar to TypeScript, and JavaScript runtime behavior is not reproduced behind the generated program.

That is an intentional tradeoff rather than a missing transpiler feature. By giving up npm compatibility, the language can concentrate on Go compatibility: existing Go module graphs, exported package data, named types, pointers, structs, interfaces and method sets, multiple results, generics, channels, error, goroutines, the Go ABI, and the standard Go build toolchain.

The practical ecosystem escape hatch is therefore import go, not an npm compatibility layer. Higher-level Kinmokusei libraries can be built on that boundary, while the low-level types and behavior remain recognizable to Go developers.

A first program

The smallest program can import the real Go standard library through an explicit namespace:

import go fmt from "fmt";

function main(): void {
  fmt.Println("Hello from Kinmokusei");
}

Save this as hello.km, then check and run it:

keika check hello.km
keika run hello.km

keika emit-go hello.km prints the generated source:

// Code generated by Kinmokusei. DO NOT EDIT.
package main

import fmt "fmt"

func main() {
    fmt.Println("Hello from Kinmokusei")
}

There is no separate JavaScript runtime or compatibility layer in this path. The result is Go code that the normal Go toolchain can build.

TypeScript-inspired classes with Go underneath

Kinmokusei provides reference-type classes, interfaces, visibility, constructors, and explicit single inheritance. These features lower to Go structs, methods, embedding, and interfaces instead of introducing a second object runtime.

import { CounterValue } from "./counter-contract";

class Counter implements CounterValue {
  constructor(private value: int) {}

  public function increment(): void {
    this.value = this.value + 1;
  }

  public function current(): int {
    return this.value;
  }
}

Classes are reference types, while native struct declarations provide nominal Go-style value types with copy semantics. The language also includes interfaces, generic functions and types, fixed arrays and slices, maps, enums, defined types, nullable references, explicit Result<T> propagation, exceptions isolated from ordinary Go panics, channels, select, goroutines, and structured Task<T> values.

The aim is not to imitate every TypeScript or JavaScript behavior. The syntax should make the source approachable while preserving the distinctions that matter to generated Go, such as value versus reference semantics, copying versus aliasing, and a checked language null versus raw Go nil.

Use Go packages directly

The import go form is the low-level bridge to the Go ecosystem. It works with both the standard library and external modules:

import go gin from "github.com/gin-gonic/gin";
import go http from "net/http";

function NewRouter(): *gin.Engine {
  const router = gin.New();

  router.GET("/api/health", (ctx: *gin.Context): void => {
    ctx.JSON(http.StatusOK, {
      status: "ok",
      language: "Kinmokusei",
    });
  });

  return router;
}

The compiler reads exported Go package data and preserves Go types rather than flattening everything into a smaller foreign-function interface. Functions, constants, variables, structs, fields, methods, interfaces, pointers, multiple results, generics, callbacks, and explicit conversions are checked at the .km source location.

Kinmokusei can use an existing go.mod, or it can manage a locked module graph through its project manifest and lockfile. Normal checking and building validate that graph without silently updating dependencies.

Web backends are the first application target

The initial release focuses on web backends, Go library production, and goroutine-based workloads. The repository contains a JSON API built directly on net/http, an embedded HTTP package, and a full-stack example with one React and TypeScript frontend connected to interchangeable Gin and Fiber backends written in Kinmokusei.

Both framework examples call the real upstream Go packages. They compile into ordinary Go services and are tested against independently handwritten Go implementations of the same HTTP contract.

Kinmokusei also provides checked C boundaries for cases where Go is not the final consumer. Explicitly exported functions can produce a versioned C ABI, while incoming C FFI generation supports checked scalar, string, byte, array, struct, tagged-union, callback, error, handle, and ownership contracts.

The generated program must remain trustworthy

A source-to-source language can look convincing while small semantic differences accumulate underneath. Kinmokusei therefore keeps a registry of Go-equivalent runtime contracts. In v0.1.0, all 75 registered contracts have isolated differential tests against independently handwritten Go programs.

Generated programs are also compiled and tested across supported Go toolchains and target platforms. The release supports Go 1.23 through Go 1.27, and the published compiler is built with Go 1.27 so it can read export data produced by each supported toolchain.

This does not mean that Kinmokusei already covers the entire Go language or ecosystem. It means that accepted behavior is expected to be explicit, testable, and predictable instead of being passed through silently.

Compiler and editor support ship together

The keika distribution includes the compiler and keika lsp --stdio. The official Visual Studio Code extension is a thin client for that same language server, so diagnostics and semantic behavior stay aligned with the compiler version.

The current LSP provides diagnostics, hover, definition, references, rename, document symbols, completion, and signature help for Kinmokusei declarations and supported Go APIs. Matching VSIX files are attached to each release.

Try the public preview

Go 1.23 through Go 1.27 are supported. If Go is already installed, the tagged compiler can be installed with:

go install github.com/puffball1567/kinmokusei/cmd/keika@v0.1.0
keika version

Prebuilt archives for Linux, macOS, and Windows, checksums, and the matching Visual Studio Code extension are available on the v0.1.0 release page.

This is a pre-1.0 public preview. Source syntax and generated APIs may change between minor releases, and several areas remain intentionally incomplete. The current goal is to make the implemented boundary solid enough for real experiments, feedback, and incremental expansion.

If TypeScript-inspired source that produces readable Go sounds useful for a backend or library project, I would be glad to hear what you try, where the generated interface feels natural, and where it does not.

KoutenDB v0.14.0: A Self-Hosted Database with Docker and Verified Backups

puffball1567 — Sun, 30 Aug 2026 07:40:06 +0000

Starting a database container is easy. Operating that database after the first successful request is the harder part.

Backups need to be restorable, upgrades need a rollback path, certificates expire, unhealthy processes should not restart forever, and a database should not quietly cross an authorization boundary while answering a query.

KoutenDB v0.14.0, released on August 27, 2026, focuses on that operational layer. It adds a reproducible self-host path around KoutenDB with versioned multi-architecture images, TLS and authentication defaults, verified recovery workflows, bounded supervision, approval-gated capacity plans, and additional confidentiality hardening.

KoutenDB is a locality-first document and vector database written in Nim. Applications place related data into explicit coordinates called rings. At query time, KoutenDB first limits the candidates to the selected ring and then ranks the records within that smaller set. Previous releases established the storage, retrieval, persistence, cluster, and endurance foundations. Version 0.14.0 addresses the next practical challenge: operating the database on infrastructure controlled by its user.

Self-hosting a database is a lifecycle, not a Docker command

The new operational path is designed as a sequence of explicit, verifiable stages:

Versioned KoutenDB image
          ↓
Non-root Docker Compose deployment
          ↓
TLS, authentication, health checks, strong durability
          ↓
Checkpoint → export → independent restore → verification
          ↓
Upgrade or certificate rotation with rollback
          ↓
Capacity observation → immutable plan → explicit approval

Official OCI images are published for linux/amd64 and linux/arm64 through ghcr.io/puffball1567/koutendb. The included single-node Compose bundle runs with a non-root user, a read-only container root, persistent strong-durability storage, generated TLS and authentication configuration, ring-local disk reads, and health checks.

The bootstrap keeps secret values outside the JSON configuration files. It generates password and secret-key files, a local CA and server certificate for the initial deployment, and mounts the prepared runtime secrets read-only. The CA private key is not mounted into the database container.

The intent is not to turn KoutenDB into a cloud provisioning platform. Docker, Kubernetes, Terraform, a virtualization platform, or a human operator can prepare CPU, memory, disks, and machines. KoutenDB is responsible for database-specific safety: validating its topology, producing recovery artifacts, checking whether prepared capacity is usable, and executing only typed database actions.

A backup is not complete until a restored copy is verified

Creating an archive is only the first half of a database backup. The important question is whether the exported generation can be restored and opened independently.

The v0.14.0 self-host operator turns that into one controlled workflow:

Drain writes
    ↓
Create an immutable checkpoint
    ↓
Verify the checkpoint
    ↓
Copy it under a staging name
    ↓
Restore it into an independent temporary volume
    ↓
Verify the restored data and segment layout
    ↓
Publish the backup generation

The final backup directory appears only after the transported artifact and the independently restored copy pass verification. An interrupted or invalid candidate does not replace an existing destination.

From the generated deployment directory, a manual checkpoint, export, and independent restore drill look like this:

./operator.sh checkpoint-create before-upgrade

backup_dir=/mnt/koutendb-backups
./operator.sh checkpoint-export before-upgrade "$backup_dir"
./operator.sh restore-drill "$backup_dir/before-upgrade"

The same workflow is available as a scheduled backup operation. The included systemd timer runs the checkpoint, staged export, restore drill, verification, publication, and retention sequence under one lifecycle lock. Verified generations count toward retention; corrupt generations are preserved as diagnostic evidence instead of being treated as successful backups.

The complete scheduled transaction can also be run manually. The final argument is the number of verified exports to retain:

./operator.sh scheduled-backup /var/backups/koutendb 7

This distinction matters because a green “archive created” message does not prove that the database can recover from that archive. Version 0.14.0 makes the restore test part of the normal backup transaction.

Rollback-safe database upgrades and certificate rotation

The operator also handles upgrades using an explicitly versioned image or immutable digest. Mutable latest images are rejected.

Before replacement, the workflow validates the target image, drains and snapshots the active node, creates a checkpoint, and requires both the active and target images to verify that recovery generation. The configured image reference changes only after those checks. If the replacement fails its health check, the operator restores the previous image reference, recreates the service, verifies health, and resumes writes.

An upgrade takes a pinned image reference and a checkpoint name:

./operator.sh upgrade \
  ghcr.io/puffball1567/koutendb:0.14.0 \
  before-0.14.0

Certificate rotation follows a similar staged model. Before changing the active certificate set, KoutenDB checks the CA, certificate chain, hostname, validity window, private key, and certificate/key match. A failed TLS health check restores the previous files.

./operator.sh certificate-rotate \
  /mnt/koutendb-pki/server.crt \
  /mnt/koutendb-pki/server.key

Preflight new artifact
        ↓
Preserve a verified recovery point
        ↓
Stage and activate the change
        ↓
Health verification
   ↙ success      ↘ failure
keep new state     restore previous state

The same basic rule is used across the lifecycle: do not discard the last known-good state before the replacement has proved that it can operate.

Capacity planning without arbitrary infrastructure hooks

KoutenDB v0.14.0 records bounded numeric capacity history and can generate a provider-neutral plan from observed storage growth, memory, and CPU data.

Each plan includes a forecast horizon, required headroom, topology intent, prerequisites, and the KoutenDB actions that would consume already prepared resources. Its ID is a SHA-256 digest of the complete versioned plan. Approval is bound to that exact content, and execution rechecks the plan identity, expiry, observation freshness, live growth, service health, and currently available resources.

The operator does not execute an arbitrary shell hook or create cloud instances. Infrastructure can be prepared by the deployment's normal system; the approval gate then verifies that KoutenDB can safely use it. Modified, stale, repeated, unapproved, and under-provisioned plans are rejected.

The workflow records observations first, creates a plan for a requested horizon, and then requires the exact generated plan ID for approval and execution:

./capacity.sh sample
./capacity.sh plan 604800

plan_id="PASTE_GENERATED_PLAN_ID_HERE"
./capacity.sh approve "$plan_id"
./capacity.sh execute "$plan_id"
./capacity.sh status "$plan_id"

Stricter database access control and confidentiality boundaries

The operational work is accompanied by a broader security hardening pass.

Version 0.14.0 separates reader, writer, replicator, and admin roles. Node-to-node traffic uses explicit peerAuth credentials instead of reusing an ordinary application identity. Authenticated sessions are bound to a galaxy, and ring authorization is applied to retrieval, listing, counting, querying, updates, deletes, and visible statistics.

Other changes include:

Argon2id password derivation and authenticated secretbox encryption for newly encrypted backups;
owner-managed files or environment variables for backup passphrases;
0700 POSIX data directories and 0600 managed artifacts at creation time;
rejection of symbolic-link output targets;
request and response framing limits before allocation;
bounded C ABI payload, vector, batch, string, boolean, and orbital inputs;
stable remote error categories that do not expose internal exception text;
fail-closed behavior for closed or unknown C ABI handles.

These boundaries are exercised by a checked-in Security Validation Matrix. The release validation covers authenticated TLS, galaxy and ring isolation, role and peer-service authorization, malformed protocol frames, encrypted-backup migration, POSIX artifact permissions, crash and storage-failure recovery, topology migration, coordinator failover, Universe synchronization, C ABI builds, and OCI image construction.

Trying the v0.14.0 self-host bundle

The complete self-host path is included in the release tag:

git clone https://github.com/puffball1567/koutendb.git
cd koutendb
git checkout v0.14.0

KOUTENDB_VERSION=0.14.0 \
  deploy/self-hosted/bootstrap.sh ../koutendb-deployment

cd ../koutendb-deployment
docker compose config
docker compose up -d
docker compose ps

The default listener binds to 127.0.0.1:7301. The generated bundle contains the Compose deployment, client and server configuration, operational scripts, recovery storage layout, and optional systemd timer units.

The full commands for health verification, checkpoint export, restore drills, scheduled backups, upgrades, certificate rotation, and capacity plans are documented in the single-node self-host guide.

From database features to a database that can be operated

KoutenDB began with a retrieval model: place related data together and avoid making unrelated records candidates in the first place. That remains the database's central idea, but a useful database also needs a credible path from a local experiment to a service someone can recover, update, and supervise.

Version 0.14.0 moves that path forward without hiding critical operations behind an unbounded automation layer. Recovery generations are verified, replacements keep a rollback route, capacity actions require exact approval, and authorization is applied at the data boundaries the database exposes.

I Built a Kawaii Native GUI with Nim and SDL3

puffball1567 — Sat, 22 Aug 2026 11:34:31 +0000

Native GUI demos often look like settings panels, administrative dashboards, or collections of standard controls. Those examples are useful, but they leave another question unanswered: can the same native UI foundation express a playful, consumer-facing visual language?

Clay Board Style System v0.5.0 includes a new Kawaii Companion demo built to explore that question. It renders a complete daily-companion concept in an SDL3 window with a soft color palette, mixed Japanese and English text, cards, progress indicators, and a two-head-tall character drawn directly through retained Canvas commands.

There is no browser or WebView behind this screen, and the character is not a PNG, SVG, or 3D model. The demo is assembled from the same public Box, Text, Canvas, Style, layout, and retained-rendering primitives intended for ordinary CBSS applications.

Clay Board Style System is abbreviated as CBSS throughout the rest of this article.

Why visual range matters in native GUI development

A UI toolkit can support rows, columns, text, borders, and input controls while still making every application look structurally similar. That is enough for many tools, but creative applications and consumer-facing desktop software also need control over composition, typography, color, illustration, spacing, and visual hierarchy.

The Kawaii Companion demo is therefore not mainly a test of whether CBSS can draw rounded rectangles. It tests whether its existing primitives can be composed into a coherent visual system that feels different from a conventional native GUI demo.

The screen combines:

a two-column application layout built from retained Box nodes;
Japanese and English text shaped through the configured text engine and font fallbacks;
cards, borders, shadows, gradients, spacing, and rounded geometry expressed through Style values;
a character illustration produced from Canvas drawing commands rather than an imported character asset;
several visually distinct sections that still share one palette and typography system.

This is important for CBSS because the project aims to provide reusable presentation primitives, not a fixed collection of applications that all inherit one visual identity.

Building a kawaii desktop UI without HTML or a WebView

The authoring model is CSS-inspired, but CBSS is not a browser CSS implementation. The demo creates retained nodes and typed style values in Nim. CBSS then resolves style, computes layout, prepares text and paint data, and sends the result through its SDL3 backend.

Nim application
  -> retained Box, Text, and Canvas nodes
  -> typed CBSS Style declarations
  -> style resolution, layout, text, and paint
  -> SDL3 backend
  -> native desktop window

For example, the left companion panel is a normal Box with layout and visual declarations:

let companion = ui.box(uiStyle([
  width(426), height(632), padding(23), gap(11),
  flexDirection(fdColumn),
  decl("background-color", colorValue(white)),
  borderRadius(8),
  borderWidth(1),
  decl("border-color", colorValue(rgba(0.31, 0.20, 0.38, 0.08))),
  decl("box-shadow", shadowValue(
    px(0), px(16), some(px(34)), some(px(-18)),
    some(rgba(0.30, 0.18, 0.40, 0.24))
  ))
]), parent = some(main))

Names such as padding, gap, flexDirection, background-color, and box-shadow make the intent familiar to web developers. Internally, however, these declarations feed CBSS's retained native UI pipeline rather than a DOM and browser rendering engine.

Drawing the character with retained Canvas commands

The character is the most immediately visible part of the screenshot, but it does not require a separate illustration file. The demo constructs a Canvas2D, records drawing commands, and mounts that canvas into the retained UI tree:

let mascot = newCanvas2D()
mascot.drawMascot()

discard ui.canvas(
  mascot,
  uiStyle([width(380), height(378)]),
  parent = some(companion),
  code = "daily-companion-character"
)

drawMascot layers rounded shapes, lines, a quadratic path, solid fills, and Oklab-interpolated linear gradients. The face, hair, clothing, highlights, shadow, and background decorations are all described in code. The result remains a 2D retained drawing; the sense of depth comes from layering, color, and highlights rather than a 3D asset pipeline.

This does not mean every application should generate all artwork procedurally. It shows that custom visual elements can live beside styled layout and text without requiring a separate rendering model for each component.

Mixed Japanese and English typography in a native UI

The screenshot also includes きょうも、いい日。 alongside English headings and supporting text. The demo configures the CBSS text path with font fallbacks before building the interface:

var fonts = initFontRegistry()
fonts.addFallbackFamily("Noto Sans")
fonts.addFallbackFamily("Noto Sans CJK JP")

var cosmic = initCosmicTextEngine(fonts)
ui.configureTextLayout(cosmic.textEngine(), fonts)

This is a small detail visually, but an important application-level test. A styled layout is not convincing if its text path works only for a narrow set of Latin demo strings. The Kawaii Companion screen exercises mixed-script shaping and fallback inside the same retained layout.

Run the Kawaii Companion demo with Nim and SDL3

The complete source is included in the v0.5.0 tag:

git clone https://github.com/puffball1567/clay-board-style-system.git
cd clay-board-style-system
git checkout v0.5.0
nimble setupBundled
nimble kawaiiCompanionDemo

The current package requires Nim 2.2 or newer. Rust and Cargo are also needed to build the native text and image bridges. Linux x86_64 with SDL3 is the Tier 1 runtime target; the portable test suite also covers Windows x86_64 and macOS arm64, while their complete native runtime paths still need broader contributor validation.

The full example is available in examples/kawaii_companion_demo.nim.

A native UI should not decide the personality of the application

The main result of this demo is not that CBSS has a built-in “kawaii theme.” It does not. The result is that application code can construct this visual language from general-purpose native layout, text, Canvas, and style primitives.

Native GUI development should not force every application toward the same visual personality. Kawaii Companion is one more test of whether CBSS can provide a familiar, expressive authoring model while remaining a native UI system rather than embedding a browser.

Perry vs scriptc: Comparing Two TypeScript-to-Native Compilers

puffball1567 — Mon, 17 Aug 2026 16:19:37 +0000

Two open-source projects now make a similar promise: write TypeScript or JavaScript, compile it ahead of time, and ship a native executable without requiring Node.js on the target machine.

Those projects are Perry and scriptc.

Their headlines sound similar, but they are not trying to build exactly the same product. Perry is growing into a cross-platform application platform with native UI, mobile targets, Node-compatible APIs, threading, and native integrations. scriptc is more narrowly centered on compiling ordinary TypeScript while making the boundary between static code, dynamic JavaScript, and unsupported code visible.

That distinction matters more than a benchmark table.

This comparison is based on each project's official repository, documentation, and published test methodology as reviewed on August 18, 2026. Perry was reviewed at commit e53de81, and scriptc at commit a737fde. Both projects are moving quickly, so check their current documentation before making a production decision.

Perry vs scriptc: the short answer

Question	Perry	scriptc
Primary direction	A broad native application platform built around TypeScript	A TypeScript-to-native compiler with an explicit static/dynamic/rejected contract
Frontend	SWC parser, then Perry's HIR and transforms	The TypeScript compiler for parsing and type checking, then a typed IR
Native backend	LLVM code generation and a system linker	LLVM IR compiled by clang; a readable C backend is also available for inspection
Default native path	No JavaScript engine; an optional JS runtime requires explicit opt-in	No JavaScript engine in a static build; `--dynamic` explicitly embeds quickjs-ng
TypeScript model	A practical subset; most type annotations are erased	Type information drives lowering, generic specialization, and checked boundaries
Node.js compatibility	A large native implementation of Node and web APIs, plus package-specific bindings	Supported Node APIs are implemented in the native runtime and tested against Node behavior
npm strategy	Native bindings, selected packages compiled through `compilePackages`, or an explicitly enabled JS runtime	npm package code normally enters an explicit dynamic island; static npm compilation is experimental
Native UI	Built-in declarative UI mapped to AppKit, UIKit, GTK4, Win32, and the DOM	No comparable application UI framework is documented
Cross-platform scope	Desktop, Apple platforms, Android/Wear OS, and Web/WASM	macOS, Linux, Windows, WASI, plus mobile library-mode archives
License	MIT	Apache-2.0

In practical terms, Perry is the more application-oriented choice. scriptc is the more compiler-contract-oriented choice.

What does "compile TypeScript to native" actually mean?

Neither project simply runs tsc and packages the resulting JavaScript. Both lower supported TypeScript or JavaScript constructs into native code and link support code for features such as strings, arrays, asynchronous work, and operating-system APIs.

For Perry, the documented pipeline is:

TypeScript
  -> SWC parser
  -> Perry HIR
  -> optimization and lowering passes
  -> LLVM
  -> object file
  -> system linker
  -> native executable

Perry's architecture documentation also describes its runtime library, including JavaScript value representations, garbage collection, arrays, strings, and UI handles.

For scriptc, the documented pipeline is:

TypeScript
  -> TypeScript compiler: parse and type-check
  -> lowering
  -> typed IR
  -> LLVM IR
  -> clang
  -> native executable

scriptc also retains a readable C backend for debugging and inspection. Its How It Works documentation says that the LLVM backend is the production default and that runtime features are split into link-gated units.

This is an important clarification: "no runtime" in compiler marketing should usually be read as "no Node.js or general JavaScript engine in the normal static output," not "the executable contains no support code at all." Both projects link native runtime components needed to preserve useful JavaScript behavior.

The biggest architectural difference: how TypeScript types are used

Perry uses SWC to parse TypeScript and lowers the result into its own high-level intermediate representation. Its documentation describes support for a practical subset of TypeScript and states that interfaces, type aliases, and most annotations are erased. Perry also documents that annotations do not automatically become runtime validators. These rules are explicit in Perry's supported features and limitations.

scriptc uses the TypeScript compiler itself for parsing and type checking. It then uses the checker's type and narrowing results when building its typed IR. Generics can be monomorphized, unions can become tagged representations, and crossings from dynamic code into statically typed code can be validated at runtime. The project documents this model in How It Works.

That does not mean scriptc accepts every program that tsc accepts. Its limitations page says it uses its own type world based on es2025 plus its ambient declarations, and it deliberately tightens some signatures to match what the compiler can implement. A program may therefore need changes even if it already passes ordinary TypeScript checking.

The trade-off is clear:

Perry owns more of the language-to-runtime mapping and can shape it around a broad native platform.
scriptc treats TypeScript's type information as part of the compilation contract and exposes a stricter boundary around what it can prove and lower.

Static compilation, dynamic JavaScript, and npm packages

Both projects prefer engine-free native code, but neither can statically compile arbitrary JavaScript behavior. Dynamic property patterns, runtime-generated code, and real-world npm packages eventually force a choice: reject the code, port it, replace it with a native implementation, or embed an interpreter.

Perry's npm and JavaScript runtime strategy

Perry offers several paths for dependencies:

built-in or third-party native bindings can map familiar package APIs to Rust functions linked into the executable;
selected pure TypeScript or JavaScript packages can be pulled into Perry's compiler through perry.compilePackages;
JavaScript files that need interpretation can use Perry's optional JS runtime.

The important safety and deployment detail is that the interpreter is not supposed to appear silently. Perry's current JS runtime opt-in documentation describes perry-jsruntime as QuickJS-based and says the build refuses to link it unless the application opts in through configuration, a CLI flag, or an environment variable.

Perry also labels its current compilePackages porting workflow as experimental. Packages based heavily on features such as Proxy, or packages that depend on Node's native addon ABI, may need replacement or a Perry-specific native binding.

scriptc's dynamic island

scriptc divides a program into three visible tiers:

code compiled statically;
code that can run only when --dynamic is enabled;
code that is rejected.

Its coverage command reports how many statements compile statically and identifies dynamic or unsupported sites with diagnostic codes. A static build never silently adds an engine.

When --dynamic is enabled, scriptc embeds quickjs-ng for npm package implementations and any-typed code. Values crossing back into static code are copied and validated. The npm dependencies documentation explicitly warns that CPU-bound dependency code in this island is slower than V8 and that its Node built-ins are shims rather than Node itself.

scriptc also has an experimental --npm-static mode, but its own documentation says package coverage is partial and unsupported sites can remain deferred or prevent static compilation.

The key difference is not that one project has an escape hatch and the other does not. Both do. The difference is how prominently the boundary is exposed. scriptc makes the static/dynamic split a first-class report for each program, while Perry combines native compilation with package bindings, package porting, and explicit interpreter opt-in as part of a wider application platform.

Node.js compatibility: published claims are not the same as guarantees

Perry documents native implementations for a broad set of Node modules and web APIs. Its current supported-features page reports roughly 97% passing results across 53 node:* modules from Node's own test suite, with roughly 95% overall Node/TypeScript compatibility. Those are Perry's published project results, not an independent certification that every Node application will compile unchanged.

The limitations remain significant for some projects. Perry documents restrictions around runtime-generated code, general user-space CommonJS require(), reflection, and dynamic language features. Its package-porting guide also explains why Node-API/N-API, NAN, V8, or libuv-based native addons cannot simply pass through compilePackages.

scriptc takes a different evidence approach. Its repository says the test corpus runs each program under Node and as a compiled binary, then compares stdout, stderr, and exit codes byte for byte. It also reruns the corpus with AddressSanitizer and a reference-count audit. That methodology is documented in both the repository README and How It Works.

However, scriptc does not claim universal Node compatibility. Its limitations documentation lists deliberate behavioral differences, unsupported standard-library surfaces, constraints on any, dense-array behavior, FFI restrictions, and differences inside the dynamic island.

So the fair reading is:

Perry publishes a wide compatibility surface and a high project-reported pass rate.
scriptc emphasizes differential testing and enumerated divergences for the narrower surface it accepts.
neither result means that an arbitrary Node.js application or npm dependency graph is guaranteed to work.

Cross-platform native UI, mobile apps, and WebAssembly

This is where Perry's broader product scope becomes most obvious.

Perry includes a declarative perry/ui framework. Its widgets map to AppKit on macOS, UIKit on iOS, GTK4 on Linux, Win32 on Windows, and DOM elements on the web. Perry's platform overview also covers Android, Wear OS, watchOS, tvOS, visionOS, and WebAssembly-related targets.

scriptc targets macOS, Linux, Windows, and WebAssembly through WASI Preview 1. Its current platform documentation also describes iOS and Android static archives in library mode, intended to be linked into a host mobile application. It does not document a Perry-like cross-platform widget framework.

That creates a straightforward decision boundary. If the goal is to build a native desktop or mobile interface directly from the same TypeScript-oriented platform, Perry is attempting to provide much more of the stack. If the goal is to compile typed application logic, a CLI, a server, a WASI module, or a library core while keeping the host UI separate, scriptc's narrower model may be easier to reason about.

What about TypeScript-to-native performance?

Perry publishes an open benchmark harness and reports both workloads it wins and workloads where Node.js or Bun is faster. That is better evidence than a table containing only favorable cases, and the exact harness is linked from Perry's README.

But those numbers do not answer "Is Perry faster than scriptc?" scriptc uses different runtime representations, a different compatibility contract, and different dynamic fallback behavior. No same-program, same-commit, same-machine comparison between the two projects was performed for this article.

A fair benchmark would need to separate at least these cases:

fully static code in both compilers;
code that activates either project's optional JavaScript engine;
startup time, steady-state throughput, peak memory, and binary size;
correct output and error behavior, not only elapsed time;
the exact compiler commits, optimization flags, toolchain, and operating system.

Until that experiment exists, a performance winner would be speculation.

Which TypeScript native compiler should you try?

Try Perry first when:

native desktop or mobile UI is central to the project;
you want a broad batteries-included platform around TypeScript;
Perry's native modules or package-specific bindings cover your stack;
its real-thread APIs and cross-platform application targets are important.

Try scriptc first when:

you want the TypeScript compiler's type information to drive native lowering;
you need a report showing exactly which parts of your application stay static;
explicit rejection is preferable to silently accepting unsupported behavior;
you are building a CLI, server, WASI module, or embeddable native library without needing a built-in UI toolkit.

For either project, start with a representative slice of the real application rather than a Fibonacci demo. Include the npm dependencies, Node APIs, error paths, asynchronous behavior, target platforms, and deployment constraints that will determine whether the experiment succeeds.

Conclusion

Perry and scriptc share an attractive headline: compile TypeScript to native code and ship without requiring Node.js. Under that　headline, they optimize for different outcomes.

Perry is building outward toward a complete cross-platform native application environment. scriptc is building inward around an inspectable compilation contract: static, explicitly dynamic, or rejected.

That is why the useful question is not simply "Which compiler is faster?" It is "Which project's compatibility boundary and product scope match the application I want to build?"

Primary sources

Kinmokusei

I Built CSS-Like Native UI Animations with Nim and SDL3

puffball1567 — Thu, 13 Aug 2026 02:03:48 +0000

Can CSS-like keyframe animations and hover transitions work in a native GUI without a browser or WebView? Clay Board Style System v0.4.1, released on August 12, 2026, includes a new SDL3 demo that shows them running in a native UI built with Nim.

Select the preview to open the full MP4 recording.

Clay Board Style System is abbreviated as CBSS throughout the rest of this article.

Why CSS-like animation is useful in native GUI development

The first version of a native UI animation often starts with a timer and a mutable position:

every frame
  -> calculate elapsed time
  -> interpolate a value
  -> update the widget
  -> rebuild what changed
  -> request another frame

That is manageable for one object. It becomes harder when one component combines a hover transition, several named animations, delays, easing functions, alternating directions, cancellation, and reduced-motion behavior.

The host application also needs to distinguish work that changes layout from work that changes only presentation. Moving a box with a paint transform should not require the complete style and layout pipeline to run again on every frame.

CBSS addresses this by keeping motion declarations in the style model and sampling only active tracks when their next frame deadline arrives.

What the Clay Board Style System v0.4.1 animation demo shows

The declarative motion runtime itself landed in v0.4.0 on August 11. Version 0.4.1 is a smaller, intentionally focused release: it adds a polished example, GIF and MP4 recordings, and roadmap documentation for exposing declarative motion through the C ABI in Version 0.5 and later.

The new demo makes four behaviors visible in one native SDL3 window:

automatic horizontal travel with eased keyframes;
an in-place 2D flip expressed with a typed transform;
background color, text color, and opacity animations sharing one retained node;
a reversible hover transition for color, opacity, translation, scale, and rotation.

This matters because an API can look complete in unit tests while still being awkward to compose. The demo exercises multiple tracks, negative delays, alternate directions, inherited text color, hover state changes, paint, hit testing, and the SDL3 host loop together.

Several objects moving smoothly at once is not unusual by itself; mature UI frameworks already do that. The purpose of this demo is to show that CSS-inspired keyframes and transitions can compose inside one retained native UI model, using typed Nim declarations and an SDL3 event loop.

Writing native keyframe animation without a manual interpolation loop

The horizontal movement in the demo is registered as named style keyframes. The application describes the values at four offsets; the motion runtime owns timing and interpolation between them.

ui.registerStyleKeyframes(styleKeyframes("ease-shuttle", [
  styleKeyframe(0, [
    decl("transform", transformValue(translate(px(0), px(0))))
  ]),
  styleKeyframe(0.12, [
    decl("transform", transformValue(translate(px(0), px(0))))
  ]),
  styleKeyframe(0.88, [
    decl("transform", transformValue(translate(px(350), px(0))))
  ]),
  styleKeyframe(1, [
    decl("transform", transformValue(translate(px(350), px(0))))
  ])
]))

The component then associates the animation name with its duration, timing function, iteration count, direction, and fill mode:

uiStyle([
  animationNames("ease-shuttle"),
  animationDurations(2.6'f32),
  animationTimingFunctions("cubic-bezier(0.42, 0, 0.58, 1)"),
  decl("animation-iteration-count", keyword("infinite")),
  animationDirection(adAlternate),
  animationFillMode(afBoth)
])

The syntax is CSS-inspired, but the values are authored through typed Nim helpers. There is no DOM, WebView, JavaScript animation loop, or string selector involved.

Running multiple CSS-like animations on one native UI node

The color panel demonstrates a case that is easy to underestimate: two animations run on the same node with different durations and delays.

uiStyle([
  animationNames("palette-cycle", "opacity-breathe"),
  animationDurations(6.2'f32, 3.1'f32),
  animationDelays(0.0'f32, -0.9'f32),
  animationTimingFunctions("ease-in-out", "ease-in-out"),
  decl("animation-iteration-count", keyword("infinite, infinite")),
  animationDirections(adAlternate, adNormal),
  animationFillModes(afBoth, afBoth)
])

CBSS keeps the tracks independent and applies declaration order when animated values overlap. CSS-like list cycling is supported for animation names, durations, delays, timing functions, iteration counts, directions, fill modes, play states, and composition.

Creating a reversible hover transition in a native GUI

The interactive panel starts with normal style and adds a hover style. The transition declarations describe how the runtime moves between the two states.

transitionProperties("background-color", "opacity", "transform")
transitionDurations(0.42'f32, 0.24'f32, 0.52'f32)
transitionTimingFunctions(
  "ease-out",
  "ease-out",
  "cubic-bezier(0.16, 1, 0.3, 1)"
)

When the pointer enters or leaves the button, CBSS resolves the new state and reconciles the transition once. Active samples then update paint data and, while geometry changes, hit-test data. Reversing the hover state starts from the current presented value rather than visibly jumping to an endpoint.

How the SDL3 animation loop stays event-driven

Declarative motion does not mean rendering continuously when nothing is active. The scheduler computes the next deadline and lets the SDL3 event loop wait until either an input/window event arrives or that deadline is due.

state or input event
  -> resolve style and reconcile motion once
  -> schedule the next active-track deadline

deadline arrives
  -> sample active transitions and keyframes
  -> refresh paint and, if required, hit data
  -> render
  -> wait for the next event or deadline

The important boundary is between layout and presentation. The demo's transforms, colors, and opacity can be sampled through paint and hit updates without running style resolution or layout on every animation frame. Layout still runs when a real layout-affecting change, such as a resize, makes it necessary.

Run the Nim and SDL3 native UI animation demo

The reproducible source for the recording is included in the v0.4.1 tag:

git clone https://github.com/puffball1567/clay-board-style-system.git
cd clay-board-style-system
git checkout v0.4.1
nimble setupBundled
nimble declarativeMotionDemo

The current requirements are Nim 2.2 or newer plus Rust and Cargo for the native text and image bridges. Linux x86_64 with SDL3 remains the Tier 1 runtime target. Windows x86_64 and macOS arm64 are covered by the portable CI suite, but their complete native runtime paths still need contributor validation.

The complete example is available in examples/declarative_motion_demo.nim.

Current limits of CSS-like native UI animation in CBSS

Version 0.4.1 remains a developer preview, so public APIs may change before 1.0.

The current declarative motion path focuses on opacity, foreground and background colors, and typed 2D transforms. Additional values, filters, 3D transforms, and CPU effects remain roadmap work. Reduced-motion handling exists in the Nim runtime, while foreign-language keyframe registration and transition control through the C ABI are planned for Version 0.5 and later; v0.4.1 documents that boundary but does not claim it is already implemented.

Release and demo timestamps

GitHub lists v0.4.1 as a non-prerelease published at 2026-08-12 11:26:51 JST (02:26:51 UTC). The GIF and MP4 demo assets were uploaded to the same release during the 11:26 JST minute. Both URLs in this article are pinned to v0.4.1 rather than the moving main branch.

Implementing CSS ex and ch Units in a Native UI Style Engine

puffball1567 — Thu, 06 Aug 2026 12:57:16 +0000

The devel branch of Clay Board Style System now supports four more font-relative length units: ex, ch, rex, and rch.

For readability, I will refer to Clay Board Style System as CBSS below.
CBSS is a CSS-inspired primitive engine for native GUI toolkits written mainly in Nim. It does not use a DOM or WebView, and it is not intended to reproduce the entire browser platform.

This update began with a small-looking requirement:

decl("width", ex(20))
decl("min-width", ch(12))

Adding four unit tags was easy. Resolving them correctly was not.

Unlike px, these units depend on the selected font. Unlike em, they cannot be calculated from font-size alone. The style resolver needs information from the text engine, but the core layout and style layers should not depend on one concrete font library.

This devlog explains how commit
8629108
addresses that boundary.

The feature is currently on devel and is intended for the v0.4 development line. It is not part of the current v0.3.2 release.

What ex, ch, rex, and rch mean

The distinction between the units matters to the implementation:

Unit	Reference used by CBSS
`ex`	x-height of the current element's selected font
`ch`	advance measure of the `0` glyph in the current selected font
`rex`	root element's `ex` value
`rch`	root element's `ch` value

These definitions follow the font-relative units in the CSS Values and Units specification.

The specification also defines a 0.5em fallback when the x-height or the horizontal 0 advance cannot be determined.

CBSS is CSS-inspired rather than a conforming browser engine, and the current adapter has one implementation difference worth making explicit. The CSS specification defines font-relative lengths without shaping, while the current cosmic-text adapter obtains ch by shaping "0" with the resolved text
configuration. This article describes the CBSS contract as it exists in this commit, not a claim of complete CSS conformance.

That fallback is important for a native style engine. CBSS must still behave deterministically in headless tests, through its C ABI, or when an application has not installed a full text engine.

Why font-relative units cross subsystem boundaries

A normal absolute length can be resolved inside the style system:

20px -> 20 layout pixels

An ex value needs a longer path:

font declarations
  -> selected font face and variation settings
  -> x-height in font units
  -> scale by the computed font size
  -> resolve ex into layout pixels

ch also depends on the font selection, but its reference is the shaped advance of the 0 glyph.

CBSS already has a replaceable TextEngine abstraction. Text shaping is provided by a cosmic-text adapter today, while layout and style resolution remain independent of cosmic-text. Importing the cosmic-text bridge directly into the property resolver would have broken that boundary.

The new implementation therefore introduces a small callback contract instead:

type
  FontUnitMetrics = object
    version: uint32
    xHeight: float32
    zeroAdvance: float32

  FontUnitMetricsResolver = proc(
    style: ComputedTextStyle
  ): FontUnitMetrics {.closure.}

The style resolver describes the resolved font selection. The installed text adapter answers with only the two measurements required for these units. Neither side needs to own the other subsystem.

Why the metrics contract is versioned

FontUnitMetrics carries a contract version even though it currently contains
only two values.

That gives CBSS an explicit compatibility boundary. A future text adapter may be built separately from the style engine, especially when accessed through a native language boundary. Returning structurally similar data is not enough if the two sides disagree about its meaning.

The resolver rejects an incompatible version and validates the fields independently. A non-finite or non-positive x-height does not invalidate a usable zero advance, and vice versa. Each invalid field falls back to 0.5em.

The same fallback is used when no provider is installed:

let halfEm = fontSize * 0.5

FontUnitMetrics(
  version: fontUnitMetricsContractVersion,
  xHeight: halfEm,
  zeroAdvance: halfEm
)

This keeps the default debug engine, headless style tests, and the C ABI deterministic without pretending that the fallback is a measured font metric.

Resolution order is the difficult part

The style resolver cannot ask for current font metrics before it knows the current font. At the same time, a declaration such as this refers to font metrics:

decl("font-size", ex(2))

The implementation resolves a node in stages:

Partition font-size, line-height, other font-* descriptors, and the remaining declarations.
Resolve font-size with the parent font metrics available.
Resolve the descriptors needed to choose the current font.
Ask the metrics provider for the current x-height and zero advance.
Resolve line-height and the remaining properties with the appropriate current and root metrics.
Pass stable root metrics and current metrics to child resolution.

This avoids a cycle and follows the important CSS distinction: font-relative units used in font-* properties resolve from the parent metrics, while ex and ch used in line-height continue to use the element's own metrics.

Root variants need another invariant. rex and rch must continue to refer to the root text style while descendants and independently invalidated subtrees are resolved. CBSS stores the root x-height and root zero advance in the resolution environment rather than recalculating them from each descendant.

Measuring real metrics with cosmic-text

The default full text adapter crosses from Nim into a Rust bridge built around cosmic-text.

For ex, the bridge selects the configured font face, applies variable-font settings, reads the face's x-height through ttf-parser, and scales the result from font units to the computed font size. If the font does not provide a valid x-height, the bridge returns the half-em fallback.

For ch, it shapes the string "0" with the resolved text configuration and uses the resulting layout-run width as the zero advance. If shaping cannot produce a positive finite value, it also falls back to half an em.

The metrics are cached by the resolved font configuration. This matters because style resolution may ask the same question for many nodes. Reopening font data or shaping 0 for every declaration would turn a small relative-unit feature into repeated text-engine work.

The cache is deliberately bounded. In this commit, the text adapter retains at most 128 font-metric entries.

The public units remain typed

The Nim API adds explicit constructors:

ex(2)
ch(3)
rex(1)
rch(8)

Internally, the corresponding unit kinds were appended after the existing public ordinals. This preserves the numeric values of earlier unit tags.

The versioned C ABI follows the same append-only rule. Its ABI version moves from 0x00010007 to 0x00010008, and the four new unit constants are added without renumbering the existing ones.

The C ABI uses the deterministic fallback metrics because a concrete text engine remains an application-side adapter concern at that boundary. A C consumer can therefore use ex and ch, but it should not mistake the fallback for a measurement from a particular installed font.

What the tests protect

The commit adds a dedicated 213-line unit test file and expands the cosmic-text and C-consumer tests.

The test matrix covers:

stable public unit ordinals;
0.5em behavior without a metrics provider;
metrics based on the current font family and size;
stable rex and rch values across descendants;
ex and ch inside line-height;
independent fallback for invalid provider fields;
diagnostics when standalone resolution has no font context;
reuse of root and parent metrics during subtree resolution;
cosmic-text x-height and zero-advance reporting;
agreement between the reported zero advance and measured 0 width;
C ABI construction and layout using the fallback path.

This is more test surface than the four new enum values suggest, but most bugs in relative-unit handling come from resolution context rather than arithmetic.

The larger design lesson

CSS-inspired native UI is not mainly a matter of copying property names.
Familiar syntax carries assumptions about font selection, inheritance, resolution order, fallback, and root-relative state.

For CBSS, the useful design was not to make the style resolver understand cosmic-text. It was to define the smallest versioned question the resolver could ask a text engine:

Given this resolved text style,
what are its x-height and zero-glyph advance?

That keeps the style system replaceable, the text engine replaceable, and the headless fallback deterministic.

The result is a small author-facing feature built on an explicit subsystem boundary:

ui.box(uiStyle([
  decl("font-size", px(18)),
  decl("width", ch(24)),
  decl("min-height", ex(3))
])):
  ui.text("Font-relative native layout")

Repository:
puffball1567/clay-board-style-system

About cosmic-text

This implementation builds on cosmic-text, a pure Rust library for multiline text shaping, layout, rendering, font fallback, and editing.

cosmic-text was created by Jeremy Soller and is developed in the pop-os/cosmic-text repository with contributions from its open-source community. CBSS uses it through a Rust bridge for native text shaping and measurement. The font-relative unit work in this devlog would be much larger without that foundation.

Why Filtered Vector Search Returns Fewer Than K Results

puffball1567 — Thu, 06 Aug 2026 12:36:51 +0000

Vector similarity is rarely the only rule that decides whether a result is useful.

A support assistant may need documents for one tenant and one product version.
A code assistant may need the active repository and branch. An internal RAG system may need to enforce permissions, publication status, language, and a date range before it returns any text to a model.

These constraints are commonly called metadata filters. But adding a filter to an API request does not tell us when the filter is applied or how much vector search work it avoids.

That distinction matters:

A filter can reduce the final result set without reducing the vector search.

This article focuses on that execution boundary. A broader guide to reducing the candidate set is available in
RAG Retrieval Optimization: Reduce Vector Search Before Ranking.

Pre-filtering vs post-filtering in vector search

Consider a search over one million document vectors:

tenant_id = "acme"
product = "billing"
language = "en"
version = "2026.2"
published = true

Suppose only 2,000 vectors satisfy all five conditions. The application asks for the ten most similar eligible documents.

There are several ways a system can execute that request:

Strategy	Simplified execution
Post-filtering	Search broadly, then remove results that fail the filter
Overfetch and post-filter	Search for more than ten candidates, filter them, then keep ten
Pre-filtering	Build an eligible set first, then search within it
Filter-aware ANN search	Use metadata indexes while traversing the vector index
Namespace or partition search	Select a smaller stored subset, then run vector search
Application routing	Route directly to a known tenant, repository, or data neighborhood

All six can expose an API that looks like "vector search with metadata filtering." Their cost and failure behavior are not the same.

Why post-filtered vector search returns fewer than k results

Post-filtering first asks the vector index for its nearest results and then removes candidates that do not satisfy the metadata conditions.

If the unfiltered search returns 50 candidates but only 0.2 percent of the corpus is eligible, many requests may produce fewer than ten valid results.

Some may produce none, even when matching documents exist elsewhere in the index.

Overfetching reduces that risk:

wanted results: 10
initial vector candidates: 500
apply metadata filter
return the first 10 eligible results

But the correct overfetch factor depends on filter selectivity and on how eligible vectors are distributed in the vector space. A fixed multiplier may work for one tenant and fail for another. A retry loop can improve completeness, but it adds work and makes tail latency harder to predict.

Post-filtering is still reasonable when filters are broad, the candidate pool is already small, or occasional short result sets are acceptable. It is a poor default for strict authorization boundaries or highly selective filters.

Weaviate's documentation describes the same two post-filtering risks: an unpredictable result count and the possibility that a restrictive filter leaves no match in the initial vector results. Its implementation uses pre-filtering with an allow list instead.

Weaviate filtering concepts

Pre-filtering changes the eligible search space

Pre-filtering determines which records are eligible before similarity ranking.
A simplified plan looks like this:

authorization filter
  -> tenant and product scope
  -> eligible vector IDs
  -> vector similarity search
  -> optional reranking
  -> context construction

This makes the result contract easier to understand: the nearest neighbors are selected from the eligible set rather than selected globally and checked later.

However, "pre-filtering" does not necessarily mean that the engine performs an exact scan over every eligible vector. An implementation may combine an inverted metadata index with an ANN graph, pass an allow list into graph traversal, choose between exact and approximate search based on cardinality, or use another filter-aware strategy.

The important questions are therefore practical:

Is eligibility established before results enter the top-k set?
Can the vector index traverse efficiently under a selective filter?
Does the engine fall back to an exact scan for some filter shapes?
Which metadata fields require their own indexes?
What happens when the eligible set is empty or extremely small?

For example, Qdrant recommends creating payload indexes for fields used in filters, preferably before ingestion. Its documentation treats fields such as availability, location, and price as business constraints that embeddings do not express reliably.

Qdrant filtering documentation

How filter selectivity changes vector search performance

Filter selectivity is the fraction of the corpus that remains eligible. A filter matching 800,000 of one million records has 80 percent selectivity. A filter matching 2,000 records has 0.2 percent selectivity.

That number can change the best execution plan:

a broad filter may add metadata work without removing many vector candidates;
a selective post-filter may discard almost every ANN result;
a selective pre-filter may make an exact scan of the eligible set practical;
an intermediate filter may need filter-aware graph traversal;
a stable and highly selective scope may be better represented by routing or partitioning.

Do not infer performance from the final result count. Two queries can both return ten rows while one considers thousands more vector candidates. Record eligible cardinality and vector work for every important filter shape.

Metadata correctness comes before metadata performance

Filtering is not only an optimization. Some filters define whether a document may be considered at all.

A useful order for a RAG retrieval pipeline is:

enforce authorization and tenant isolation;
select a stable application scope such as repository, product, or version;
apply dynamic metadata such as status, language, and date;
perform vector or hybrid candidate ranking;
rerank the bounded candidate set;
project fields and enforce the context budget.

Authorization should not depend on whether an ineligible vector happens to miss the top-k cutoff. It should be enforced as a hard boundary independently of relevance ranking.

The metadata model also needs explicit semantics. For example:

Field	Useful question
`tenant_id`	Is this a security boundary, a routing boundary, or both?
`repository`	Can one query intentionally search multiple repositories?
`version`	Should older versions be excluded or merely ranked lower?
`language`	Is fallback to another language allowed?
`published`	Can drafts ever enter model context?
`valid_from` and `valid_to`	Which time is authoritative for the request?

A vector database cannot infer these policies from an embedding. The application still owns the meaning of the fields and the rules for combining them.

Tenant-scoped vector search: filter or namespace?

Namespaces and partitions can reduce the search space before vector ranking, but they are not a replacement for metadata indexes.

A good routing or partition boundary is usually:

known before retrieval;
stable enough that records do not move constantly;
selective enough to exclude substantial unrelated data;
meaningful to authorization or application behavior;
limited to a manageable number of scopes.

Tenant, repository, product, and corpus source often fit. Free-form tags, temporary UI filters, arbitrary price ranges, and frequently changing status values usually fit metadata filtering better.

For multi-tenant vector search, the choice depends on the workload. A namespace or routed partition makes tenant scope explicit and can avoid cross-tenant search work. A tenant_id metadata filter is more flexible when queries may legitimately span tenants or when creating many physical scopes would be operationally expensive.

Neither choice automatically implements authorization. Tenant identity must come from an authenticated context, and every retrieval path must enforce the same policy.

This produces a layered design:

stable scope
  -> dynamic metadata filter
  -> vector or hybrid ranking
  -> reranking
  -> LLM context

The stable scope makes the first problem smaller. Metadata filters express conditions inside that scope. Vector similarity orders the remaining semantic candidates.

How to measure vectors scanned in filtered vector search

Returning ten results does not mean that only ten vectors were considered.
When evaluating filtered vector search, record at least:

total vectors in the corpus;
vectors in the selected namespace or partition;
records eligible after metadata filtering;
vector candidates visited or scored;
results remaining after filtering;
recall at k for the eligible ground truth;
empty-result and short-result rates;
p50 and p95 retrieval latency;
candidates passed to the reranker;
tokens passed to the model.

Test several filter selectivities. A query matching 80 percent of a collection has a different execution shape from one matching 0.1 percent. Also test correlation: eligible vectors may be clustered together in the vector space or scattered across it.

Finally, include a deliberately wrong scope in the evaluation. A narrow query can be fast because it excluded the correct documents. Latency improvement is not useful unless recall and authorization correctness remain intact.

A practical decision checklist

Before shipping vector search metadata filtering, ask:

Which filters are authorization rules rather than relevance hints?
Are filters applied before or after the vector top-k is formed?
Which filter fields have indexes?
How does performance change as filter selectivity changes?
Can a stable namespace or application route reduce the search space first?
Does overfetching hide an incomplete post-filtering design?
Are recall, vectors examined, latency, and context tokens measured together?
What is the fallback when the chosen scope is wrong or empty?

Filtered vector search FAQ

Does metadata filtering reduce vector search work?

Only when the engine uses the filter before or during vector candidate selection, or when the application routes the query to a smaller scope. A post-filter can reduce the returned rows while leaving the original vector search unchanged.

Why does vector search return fewer results than k?

The corpus may contain fewer than k eligible records. If enough eligible records do exist, a post-filter may have removed too many of the initial ANN candidates, or an approximate filtered search may have exhausted its search budget before finding k matches.

Does pre-filtering reduce vector search recall?

Recall must be measured against the eligible ground truth. A correct filter intentionally excludes out-of-scope records, but a wrong filter can exclude the answer. Filtered ANN traversal can also have different recall behavior from an unfiltered graph, so it should be compared with exact search over the same eligible set.

Should tenant ID use a metadata filter or a namespace?

Use a namespace or routing boundary when tenant scope is stable, selective, and almost every query belongs to one tenant. Use an indexed metadata filter when the scope is dynamic or legitimate cross-tenant queries are common. Some systems combine both: route to a tenant-level scope, then apply metadata filters inside it.

A different approach: placement-aware retrieval in KoutenDB

Metadata filtering is not the only way to reduce vector work before ranking.
When a useful search scope is predictable while data is being stored, placement itself can provide the first candidate boundary.

KoutenDB is an open-source document and vector database written in Nim.

KoutenDB does not implement a ring as a conventional metadata filter. A ring is an application-defined locality coordinate chosen when data is placed. The same coordinate can later become the starting scope for retrieval.

For example, documentation for different Laravel releases can remain in separate rings while a stellar lens records that they belong to the same framework context. The lens changes visibility metadata; it does not copy the document payloads between rings:

import koutendb

var db = koutendb.open(dataDir = "data")
db.attachStellar("framework/laravel", "docs/laravel/10")
db.attachStellar("framework/laravel", "docs/laravel/11")

let queryVec = @[1.0'f32, 0.0'f32]
let relatedVersions = db.readStellar("framework/laravel")
let hits = db.retrieve(
  queryVec,
  ring = "docs/laravel/11",
  budget = 8
)

The stellar read keeps the Laravel 10 and Laravel 11 results grouped by their original ring, so the application can see them as related without collapsing their version boundaries. subrings can narrow a stellar read when only one member coordinate is needed.

The current vector retrieve API does not use a stellar lens as an implicit vector filter. After the appropriate member ring is selected, KoutenDB scans the vectors stored in that ring, computes their exact cosine similarity, and returns up to eight results. It does not first run a global vector search and discard results from other versions afterward.

This is placement-aware retrieval rather than general-purpose metadata filtering. Rings preserve stable distinctions such as framework version, tenant, product, language, or document family. Stellar lenses can expose related rings through one read context without erasing those distinctions.
Frequently changing conditions such as publication status or price may still need ring-read filters, application logic, or an indexed metadata filtering system. A ring or lens also should not be treated as authorization by itself;

authentication and access policy remain separate concerns.

The trade-off is explicit. KoutenDB works best when the application, import rule, or operator can express a useful locality while storing the data. If no meaningful locality is known, retrieval without a ring becomes a broad exact scan. KoutenDB also exposes retrieval statistics such as totalVectors,
scanned, skippedVectors, and candidateReduction, making the amount of vector work observable instead of inferring it from the number of returned results.

The goal is not to avoid vector search. It is to make vector search operate on the smallest valid candidate set. Metadata filters determine which records are\ eligible. When a useful scope is known in advance, placement-aware retrieval can make that eligible set smaller before ranking starts.

KoutenDB v0.10.0: 72 Hours, Three Persistent Nodes, and Zero Client Errors

puffball1567 — Mon, 03 Aug 2026 12:23:51 +0000

I released KoutenDB v0.10.0.

Release:

https://github.com/puffball1567/koutendb/releases/tag/v0.10.0

KoutenDB is a ring-oriented document and vector database written in Nim. Its core idea is to make an application's locality boundary part of the read path:
place related data together, select that boundary before retrieval, and avoid making unrelated records candidates in the first place.

That idea needs more than a clean benchmark. A database also has to keep running while it writes persistent state, serves reads, tracks topology state, and eventually shuts down for verification.

For v0.10.0, I ran a local persistent three-node cluster continuously for 72 hours. The result was simple and useful: the run completed with zero client errors, and all three data directories passed offline verification after the servers stopped.

What the endurance run did

The runner started three local TCP nodes with persistence enabled and exercised
a mixed workload every 250 ms for 259,200 seconds.

The workload included:

TCP writes;
point reads using IDs returned by earlier writes;
JSON projection queries;
bounded ring reads with sort and limit;
ring-scoped exact vector retrieval;
metrics collection;
a final snapshot and offline verification after shutdown.

The runner builds its own copy of the server, CLI, and workload binaries under the run directory before it starts. This matters because rebuilding the source tree during a long run cannot silently change the executable being tested.

The exact run used commit 87c755c9130ec0bbf70a3903c75fd2bdae8b084b.

Final result

Operation	Completed
PUT	969,281
returned-ID GET	969,281
projection query	969,281
bounded ring read	969,281
ring-scoped retrieve	96,928
metrics read	48,464
client errors	0

That is 4,022,516 completed logical client operations across the 72-hour period.

After the workload finished, the runner took its final snapshot, stopped the three nodes, and ran offline kouten verify against every persistent data directory. All three verifications succeeded.

The final operational counters also showed:

zero pending handoffs;
zero handoff queue depth;
zero handoff failures, stale acknowledgements, or queue-full events;
zero remaining migrations;
zero universe-sync errors;
zero global retrieval requests.

The last point is important for KoutenDB's design. The workload used ring-scoped retrieval, and the metrics confirmed that it did not silently fall back to a cluster-wide retrieval path.

Why this is more useful than a startup smoke test

A startup test can show that a server accepts a request. It does not show what happens after hundreds of thousands of persistent writes, repeated read paths, periodic metrics calls, topology bookkeeping, and a full stop-and-reopen boundary.

This run specifically exercised the persistent cluster path over time:

records were written to disk-backed nodes;
later requests read data that had been accumulated by the same run;
cluster handoff and migration counters were observed throughout the run;
the servers were stopped cleanly;
the on-disk state was opened and verified offline.

It does establish a concrete baseline: KoutenDB can sustain a mixed, persistent local cluster workload for three days without a client-visible error or an offline integrity failure.

What changed in v0.10.0

The endurance runner is one part of a larger operational hardening release.

Operational configuration can now be loaded and verified before a server is used.
Write guardrails, audit events, capacity thresholds, and backup verification provide explicit operational checks.
Explicit scale-in migration and rolling topology activation add controlled drain, handoff, and progress behavior.
Cluster retrieval now remains in the requested ring rather than falling back to a cluster-wide scan.
Physical placement is decoupled from the logical orbit schedule, so a logical orbit boundary does not stall local request processing.
Handoff I/O is kept off the request loop, and stale handoff replay cannot resurrect an older mutation.
The optional FAISS backend was removed. Vector retrieval now follows the core KoutenDB model directly: select a ring first, then perform exact cosine ranking over that bounded candidate set.

These are not unrelated features. They move the project from a collection of locality experiments toward an operable persistent service: know what the server is configured to do, constrain unsafe operation, observe background state, and verify the data after a long workload.

Reproducing the run

The runner is included in the repository:

KOUTEN_SOAK_SECONDS=259200 \
KOUTEN_SOAK_WORKDIR=/tmp/koutendb-soak-72h \
examples/soak_72h.sh

It writes JSON Lines progress, node logs, final metrics, a final snapshot, offline verification output, the workload configuration, and a completed.ok marker only after all final verification steps succeed.

The full configuration and scope are documented here:

https://github.com/puffball1567/koutendb/blob/main/docs/soak-testing.md

The run is intentionally not a CI job. A three-day endurance test is useful because it is long enough to observe persistent operational behavior; it would make normal pull-request feedback unusably slow.

The next reliability question

This result validates the current local, disk-backed, buffered-durability cluster mode. The next endurance variants are clear: strong-durability writes, TLS and authenticated transport, Docker/container deployment, and eventually multiple machines.

Those tests extend this baseline rather than replace it. The v0.10.0 result is now a documented, reproducible reference point for future changes to storage, handoff, topology, and retrieval behavior.

Source:

https://github.com/puffball1567/koutendb

Clay Board Style System update: Link Navigation

puffball1567 — Mon, 03 Aug 2026 11:52:50 +0000

Clay Board Style System now provides typed native Link Navigation.

For readability, I will refer to Clay Board Style System as CBSS below.
CBSS is only an abbreviation used in this article; the project's official name
is Clay Board Style System.

The feature lets a native application move between screens with a flow similar
to a Single-Page Application: the window remains open, the navigation menu
remains in place, and only the active screen changes.

In this tutorial, we will build a small navigation menu with three destinations:

Home
Projects
Settings

Clicking a menu item switches the visible screen inside the same native SDL3
window. No DOM, browser history, WebView, or URL-string router is required.

Run the finished demo

The complete interactive demo is already included in the repository:

git clone https://github.com/puffball1567/clay-board-style-system.git
cd clay-board-style-system
nimble setupBundled
nimble navigationDemo

The full source is available in
examples/navigation_demo.nim.

Step 1: Define the screens

Start by describing the destinations as a normal Nim enum:

import clay_board_style_system

type Screen = enum
  homeScreen,
  projectsScreen,
  settingsScreen

let navigator = initStackNavigator(homeScreen)

navigator now owns the screen history. The initial destination is
homeScreen.

Because destinations are Nim values, invalid destinations are caught by the
compiler instead of becoming malformed route strings at runtime.

Step 2: Define a small set of styles

The navigation behavior does not impose a visual design. These styles create a
simple sidebar and content area:

proc appStyle(): UiStyle =
  uiStyle([
    decl("width", px(900)),
    decl("height", px(520)),
    decl("flex-direction", keyword("row")),
    decl("background-color", colorValue(rgb(0.04, 0.05, 0.08)))
  ])

proc menuStyle(): UiStyle =
  uiStyle([
    decl("width", px(220)),
    decl("height", px(520)),
    decl("padding", px(20)),
    decl("gap", px(10)),
    decl("flex-direction", keyword("column")),
    decl("background-color", colorValue(rgb(0.07, 0.09, 0.13)))
  ])

proc contentStyle(): UiStyle =
  uiStyle([
    decl("width", px(680)),
    decl("height", px(520)),
    decl("position", keyword("relative")),
    decl("overflow", keyword("hidden"))
  ])

proc screenStyle(): UiStyle =
  uiStyle([
    decl("position", keyword("absolute")),
    decl("left", px(0)),
    decl("top", px(0)),
    decl("width", px(680)),
    decl("height", px(520)),
    decl("padding", px(28)),
    decl("gap", px(12)),
    decl("flex-direction", keyword("column")),
    decl("background-color", colorValue(rgb(0.04, 0.05, 0.08)))
  ])

proc linkStyle(): UiStyle =
  uiStyle([
    decl("width", px(180)),
    decl("height", px(40)),
    decl("padding", px(10)),
    decl("align-items", keyword("center")),
    decl("background-color", colorValue(rgb(0.11, 0.15, 0.21))),
    decl("border-radius", px(6)),
    decl("cursor", keyword("pointer"))
  ])

proc linkTextStyle(): UiStyle =
  uiStyle([
    decl("font-size", px(14)),
    decl("line-height", px(20)),
    decl("color", colorValue(rgb(0.91, 0.94, 0.98)))
  ])

These are ordinary CBSS styles. A component library can replace all of them
without changing the navigation code.

Step 3: Build the menu and screens

Keep the three screen roots so they can be registered with the navigator. We
also keep the Back and Forward buttons for the next step.

type AppView = object
  home: NodeHandle
  projects: NodeHandle
  settings: NodeHandle
  backButton: ButtonHandle
  forwardButton: ButtonHandle
  refreshProjects: ButtonHandle
  notifications: CheckboxHandle

proc buildView(ui: UiRoot; navigator: Navigator[Screen]): AppView =
  ui.box(appStyle()):
    ui.box(menuStyle()):
      ui.text("My application")

      ui.link(
        navigator,
        homeScreen,
        "Home",
        style = linkStyle(),
        textStyle = linkTextStyle()
      )

      ui.link(
        navigator,
        projectsScreen,
        "Projects",
        style = linkStyle(),
        textStyle = linkTextStyle()
      )

      ui.link(
        navigator,
        settingsScreen,
        "Settings",
        style = linkStyle(),
        textStyle = linkTextStyle()
      )

      result.backButton = ui.button("Back")
      result.forwardButton = ui.button("Forward")

    ui.box(contentStyle()):
      ui.box(result.home, screenStyle()):
        ui.text("Home")
        ui.text("Welcome to the native application.")

      ui.box(result.projects, screenStyle()):
        ui.text("Projects")
        ui.text("Project data will be displayed here.")
        result.refreshProjects = ui.button("Refresh projects")

      ui.box(result.settings, screenStyle()):
        ui.text("Settings")
        result.notifications =
          ui.checkbox("Enable notifications", checked = true)

The hierarchy is visible directly in the code:

application
├── navigation menu
│   ├── Home Link
│   ├── Projects Link
│   ├── Settings Link
│   ├── Back button
│   └── Forward button
└── content area
    ├── Home screen
    ├── Projects screen
    └── Settings screen

ui.link() is a style-neutral native Link. It handles pointer activation,
Enter-key activation, keyboard focus, disabled state, and accessibility
semantics.

Step 4: Register the screens

Build the view once, then associate each typed destination with its screen root:

let ui = initUiRoot()
let navigator = initStackNavigator(homeScreen)
let view = buildView(ui, navigator)

let host = initNavigationScreenHost(ui, navigator)
host.registerScreen(homeScreen, view.home)
host.registerScreen(projectsScreen, view.projects)
host.registerScreen(settingsScreen, view.settings)

var interaction = initInteractionState()

if not host.sync(interaction):
  raise newException(ValueError, "initial screen could not be activated")

At this point, only Home is active.

When a Link receives a click or Enter-key event, it updates the navigator. After
the current platform-event batch, synchronize the screen host:

let screenChanged = host.sync(interaction)

In a real application this line belongs in the central event loop, after CBSS
has dispatched the current batch of SDL3 events. The complete demo shows that
integration without hiding it behind tutorial pseudocode.

Only the active screen participates in layout, painting, hit testing, keyboard
focus, and the visible accessibility tree. The other screens remain retained
but inert.

That is the SPA-like part: switching screens does not reconstruct the complete
application tree or open another native window.

Add Back and Forward

The same navigator provides history operations:

view.backButton.onClick = proc(event: DispatchResult): bool =
  if not navigator.back():
    echo "Already at the first screen"
  true

view.forwardButton.onClick = proc(event: DispatchResult): bool =
  if not navigator.forward():
    echo "Already at the latest screen"
  true

push, replace, back, and forward operate on typed history entries. Two
visits to Projects remain two separate entries, which allows CBSS to restore
focus for the correct visit when navigating through history.

Request data with Joubako

Navigation belongs to CBSS, while HTTP communication belongs to the
application's data layer.

I am also developing
Joubako, a separate async transport
client for Nim. It supports HTTP(S), typed JSON, standard Nim await,
result-aware callback composition, WebSockets, local IPC, and optional NIF/BIF
data exchange.

It can be started from a normal CBSS event handler without coupling networking
to the navigation system:

import std/asyncdispatch
import joubako

type Project = object
  id: int
  name: string

let api = newClient(newHttpTransport(), "https://api.example.com/")

proc loadProjects() {.async.} =
  let outcome = await api.getJson("projects", seq[Project])
  if outcome.isErr:
    echo "Request failed: ", outcome.error.msg
    return

  echo "Loaded projects: ", outcome.value.len
  # Update application state and mark the affected view dirty here.

view.refreshProjects.onClick = proc(event: DispatchResult): bool =
  asyncCheck loadProjects()
  true

Joubako is not bundled with CBSS and is not required for Link Navigation. An
application can use Joubako, another HTTP client, IPC, an FFI service, or a
fully local data source behind the same event-handler boundary.

Optional features

The basic menu above is enough for normal in-process screen navigation. CBSS
also provides optional APIs for:

focus restoration for each history entry;
animated screen transitions;
validated application deep links;
replacing one retained screen without rebuilding the application; and
injecting a custom navigation driver.

These features are documented in the
Native Navigation guide.

Why use typed destinations?

A browser URL is useful when the URL is the application's public address. A
native in-process screen does not always need that string boundary.

With CBSS:

navigator.push(projectsScreen)

is checked against Screen by Nim. A larger application can replace the enum
with a variant object that carries typed parameters, such as a project ID.

External deep links can still be decoded into the same destination type at the
edge of the application. Internal navigation remains typed.

Current status

Clay Board Style System v0.3 is a developer preview. Linux x86_64 with SDL3 is
currently the Tier 1 runtime. Windows and macOS portable builds run in CI, while
complete runtime validation on those platforms remains contributor-driven.

Link Navigation is covered by unit tests, retained-screen tests, transition and
focus tests, performance checks, and a real SDL3/Wayland E2E scenario.

Links

Feedback on the Link API and the navigation-menu authoring experience is very
welcome.

RAG Retrieval Optimization: Reduce Vector Search Before Ranking

puffball1567 — Mon, 03 Aug 2026 04:21:03 +0000

Most RAG performance advice begins at the ranking stage: choose a faster embedding model, tune an ANN index, reduce the result count, add a reranker, or cache common queries.

Those are useful techniques. But RAG retrieval optimization should start one step earlier:

Why is this query considering these vectors at all?

A request often already contains a reliable boundary: tenant, repository, product, language, document type, version, date range, permission scope, or the object currently open in the application. Applying that knowledge before vector ranking can reduce RAG latency, vector-search memory use, and unrelated context.

This is the difference between searching a whole corpus for similar documents and searching the authorized, relevant part of that corpus. It is also the specific problem that a locality-aware RAG database such as
KoutenDB explores.

Vector search metadata filtering is not one operation

Vector search metadata filtering commonly restricts a query by fields such as:

tenant_id = "acme"
AND product = "billing"
AND language = "en"
AND published = true
AND version = "2026.2"

Those constraints are necessary for both relevance and security. Their placement in the read path, however, changes the cost:

Strategy	What happens
Filter after broad retrieval	Rank widely, then discard ineligible candidates.
Filter-aware vector index	Use indexed metadata while selecting vector candidates.
Namespace or partition selection	Select an eligible subset, then search it.
Application-local routing	Route directly to a known tenant, source, or related-data neighborhood.

The first approach can still enforce correct access rules, but it may score vectors that should never have been candidates. The latter two are valuable when the application already knows a stable boundary.

For a multi-tenant support assistant, the tenant boundary is not merely a relevance hint. It is an authorization rule and a natural first search scope.
For a code assistant, the active repository and branch often serve the same purpose. For a product assistant, version and language can rule out most of the corpus before similarity becomes useful.

RAG optimization starts with the working set

The working set is everything a request touches: candidate vectors, metadata,payload bytes, reranker inputs, and finally model context. Reducing it changes several costs at once:

fewer vectors to score;
less vector memory to read;
fewer payloads to filter and project;
fewer candidates for a reranker;
less irrelevant context competing for the prompt budget.

This is not an argument for creating a partition for every tag. A pre-ranking boundary should be stable, known at request time, meaningful to the application,and strong enough to exclude large amounts of unrelated data. Tenant, source,product, and document-version boundaries often qualify; free-form tags usually do not.

There is also an essential quality check: a smaller scope is only an optimization if it retains the documents the user needs. A wrong partition can be fast because it is wrong.

KoutenDB: locality first, exact vector ranking second

KoutenDB is an open-source, embedded-capable document and vector database written in Nim. It is not a general replacement for PostgreSQL, a mature ANN vector database, or a global secondary-index engine.

Its vector path makes a focused trade-off:

the application chooses a ring, a semantic locality boundary;
KoutenDB retrieves candidates from that ring;
it performs dependency-free exact cosine ranking over that bounded set.

For example, a RAG application that already knows the tenant and product can place and query documentation in a corresponding ring:

import koutendb

var db = koutendb.open(dataDir = "data")
let hits = db.retrieve(
  @[1.0'f32, 0.0'f32],
  ring = "tenant/acme/product/billing",
  budget = 8
)

The ring is chosen by application logic, policy, or an import rule; KoutenDB does not claim to infer the right security or business boundary from embedding similarity. JSONL ingestion can derive rings from a field, for example with a tenant field and a tenant prefix.

Filters and projections still narrow results, but only after the local ring has been selected. This boundary is important: KoutenDB is a good fit when an application can name a meaningful pre-ranking scope. It is not the right primary tool when every query must perform global, cross-corpus discovery.

Measure vectors scanned, not only results returned

Returning fewer hits does not prove that a system did less search work. A useful RAG database should expose whether unrelated candidates were skipped before ranking.

KoutenDB reports total vectors, scanned candidates, skipped vectors, rings touched, candidate reduction, payload bytes, and estimated tokens. Its included working-set benchmark uses 10,000 vectors across 100 rings. In one local run, global retrieval scanned 10,000 vectors per query, while routed retrieval scanned 100: a 99% reduction. Measured latency in that run was 1,954.9 microseconds for the global path and 31.4 microseconds for the routed path.

An included RAG-style test kept recall at 1.000 for the correctly routed ring while reducing scanned candidates from 400 to 40 and estimated tokens from 615.2 to 231.6. It also demonstrates the failure case: selecting the wrong ring keeps the small scan but produces zero recall.

These are local synthetic measurements, not a universal latency claim or a claim that KoutenDB beats every vector database. They demonstrate a narrower invariant: candidates in unrelated rings are skipped before exact vector scoring, rather than discarded after a broad search.

When locality-first retrieval is useful

This approach is particularly relevant for:

multi-tenant RAG and tenant-based data isolation;
support systems scoped to a customer, product, or deployment;
code assistants scoped to a repository or service;
documentation assistants with known language and version;
local AI or desktop applications with a bounded local corpus;
systems that need nearby application history as well as similar chunks.

It is less suitable when global discovery is the core job, or when the application cannot identify a trustworthy boundary before retrieval. In that case, a broad ANN-oriented vector database with filter-aware indexing is often the better primary retrieval layer.

A checklist for RAG retrieval optimization

Before tuning a model or index, ask:

Which tenant, permission, source, version, or task boundary is known before retrieval?
Is that boundary enforced before candidates are ranked?
How many vectors are scanned, rather than merely returned?
Does scoped retrieval preserve recall on representative queries?
Can the system explain why each document was eligible?
Are payload projection and context budgets applied before the LLM call?
Can the same routing rules be validated offline?

The answer may lead to namespaces, metadata indexes, database partitions, or a locality-aware database. The common requirement is to make the pre-ranking boundary explicit and measurable.

Conclusion

The best way to reduce RAG cost or RAG latency is not always a more complicated ranking algorithm. Often it is avoiding a ranking problem that the application already knows is irrelevant.

Use metadata filtering for correctness. Use tenant, source, version, and task locality to reduce the eligible search space when those boundaries are trustworthy. Then measure scanned candidates, recall, latency, and context size together.

That is the design space KoutenDB explores: a database for RAG where application-level locality becomes part of the retrieval path before exact vector ranking begins.