CrystalOptics: Giving CrystalCatalyst a Way to See
This morning I added a small new companion module to CrystalCatalystLibrary: CrystalOptics. It is not a huge module, but it crosses an important boundary. CrystalCatalyst can now capture the desktop in a portable way and hand that image data back through the same kind of substrate the rest of the library already understands.
In simpler terms: the workspace now has eyes.
The Shape of the Module
CrystalOptics is built as a native companion library. It exposes a small capture API for listing displays, capturing the desktop, capturing a specific display, and capturing the active window. The native side returns image data as PixData, using a bgra:int8 pixel format.
On top of that, I added a managed wrapper, CrystalOptics.net, so .NET tools can call the native capture API directly. Then I added FacetCLI, a small command-line tool that makes the capture layer useful from scripts, shells, IDEs, and agent workflows.
The result is a compact stack:
CrystalOptics
native screen capture
CrystalOptics.net
managed wrapper
FacetCLI
command-line capture toolFacetCLI
FacetCLI is the part that makes this especially useful for agentic workflows. A tool or assistant does not need to know how to call X11, GDI, or a desktop portal directly. It can ask FacetCLI for a capture.
Example commands look like this:
FacetCLI list-displays
FacetCLI capture --desktop --format webp --out file --out-file screen.webp
FacetCLI capture --bounds 100,100,800,600 --grayscale --out base64It supports desktop capture, display capture, active-window capture, bounds cropping, grayscale conversion, several output formats, and output to stdout, base64, or a file.
That makes it useful for humans, but it is especially useful for agents. It creates a controlled observation primitive: a simple way for a tool-running assistant to capture what is on the screen without embedding platform-specific screenshot code everywhere.
Windows, X11, and Wayland
Screen capture is not the same problem on every platform. Each desktop environment has a different answer to the question: “Is this program allowed to see the screen?”
On Windows, CrystalOptics uses the normal GDI capture path. The --portal option is harmless there; it is a null operation.
On X11, direct capture works through the X11 APIs.X11 still allows this kind of direct framebuffer-style observation.
On Wayland, direct capture is intentionally blocked by the compositor. That is a security boundary, not a bug. For Wayland, the portal path is the right approach. FacetCLI supports --portal, and portal capture is selected automatically when Wayland is detected.
That matters because it lets the tool follow the platform’s trust model instead of fighting it.
Small Tool, Larger Meaning
This is a small module, but it connects to the recent portability work in NewAge.
The environment helpers answer:
Where am I?The portable $NewAge/bin command surface answers:
What can I run?CrystalOptics and FacetCLI now answer:
What can I see?That is a meaningful step for agentic tooling. An assistant operating inside the NewAge workspace can now enter the environment, run portable commands, and capture visual context in a platform-aware way.
I like this kind of infrastructure because it is humble. It does not try to be a full automation framework by itself. It simply gives the rest of the system one more reliable sense.
Why It Matters
Good tooling is often made of small pieces that compose well. CrystalOptics is one of those pieces. It turns screen capture into a reusable library boundary and a simple command-line capability.
For CrystalCatalyst, it adds a visual companion module. For NewAge, it adds another portable utility that can live in the workspace command surface. For agents, it adds an observation primitive.
That is small, but potentially very useful.