Shiocus v.1.0.0

Text that knows where it is.

Shiocus is a lightweight C++ terminal text-positioning library with word tracking, per-word focus colors, and index-based rendering.

---

Quick Demo

---

📖 Table of Contents

• Overview
• Features
• The Two Colors
• Architecture
• Quick Start
• Use Cases
• Why Shiocus
• Comparison
• Design Philosophy
• License

---

🌟 Overview

Shiocus is a lightweight C++ library for placing text on a terminal with precision. It doesn't animate, it doesn't decorate — it tracks. Every word you give it becomes a numbered entry. Every entry remembers where it lives and what color it should be. Then, on demand, you render — and Shiocus paints each word exactly where it belongs.

The name is a collision of two ideas: "shi" (shift) and "ocus" (focus). Focus highlights. Shiocus keeps your words where you left them — and lets you call any one of them into the light.

Why Word-Level Positioning?

Terminals are grids. Text is streams. The two don't naturally agree — once you print, the cursor moves, and the word you meant to highlight is already gone. Shiocus bridges that gap.

• Zero Dependencies — No libraries. No frameworks. No linker headaches. Just C++ and the terminal you're already sitting in.
• Self-Contained — One class. One behavior. One thing done well.
• True Color — Full 24-bit RGB, so your focus state can be any shade you want it to be.
• Words as objects — Each word has an identity: row, column, index, text, focus flag, color.
• Meant to be tuned — Focus, color, index — all exposed. All waiting for you.

---

✨ Features

🎨 Rich Color Control

• 24-bit True Color — Full RGB spectrum, no compromise
• Hex Color Support — #FF5733 format
• RGB Function Support — rgb(255,87,51) format
• Independent Default & Focus Colors — The focused word can be a completely different color from the rest

🚀 Positioning

• Automatic Word Wrapping — Text wraps inside the terminal bounds
• Newline Handling — \n advances the cursor to the next line
• Smart Chunking — Long words that exceed a line are split across lines
• Per-Word Indexing — Every word gets a unique index as it's placed
• Focus by Word or by Index — Two ways to call a word into the light

🧩 Developer-Friendly

• Simple Setup — Initialize an origin, set text, render
• Safe by Default — Bounds-checked placement, no out-of-terminal writes
• No Config Files — Everything is set in code
• Single Render Call — render() draws everything at once

---

🎭 The Two Colors

Shiocus has two states. Every word is in one of them.

▸ Default Color — The Quiet

Every word starts here. White by default, but configurable to anything you want. This is the resting state — text that's present but not called out.

engine.setDefaultWordColor("#FFFFFF");

▸ Focus Color — The Light

When you focus a word, it changes color and every other word drops back to default. Only one word is focused at a time. This is the state that says: look here.

engine.setWordOnFocusAndColor("Hello", "#FF0064");

Both states support hex and rgb(...) formats. Both are full 24-bit RGB. Focus by word matches on text — focus by index matches on position in the placement order.

---

🏗 Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Application Layer                      │
│   ┌──────────────┐  ┌────────────────┐  ┌───────────────┐  │
│   │   text()     │  │ setDefaultColor│  │ setFocusColor │  │
│   └──────────────┘  └────────────────┘  └───────────────┘  │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                     Placement Layer                         │
│   ┌────────────────────────────────────────────────────┐   │
│   │   Word Splitting  •  Wrapping  •  Cursor Advance   │   │
│   └────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                     Word Store                              │
│   ┌────────────────────────────────────────────────────┐   │
│   │   Row  •  Col  •  Index  •  Text  •  Focus  •  RGB │   │
│   └────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                     Terminal Layer                          │
│   ┌────────────────────────────────────────────────────┐   │
│   │   Cursor Positioning  •  Foreground Color          │   │
│   │   Bounds Checking     •  Flush                     │   │
│   └────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                            ↓
                    Terminal Display

Shiocus builds an in-memory word list first, then draws it on render(). There's no frame buffer, no diffing pass — just positions and colors, applied on demand.

---

🚀 Quick Start

Prerequisites

• C++11 or higher compiler
• POSIX terminal — Linux, macOS, BSD, WSL
• 24-bit true color support — Most modern terminals handle this

Installation

# Clone the repository
git clone https://github.com/intriXlabs/Shiocus.git

# Compile with optimizations
g++ -O3 -std=c++11 shiocus_demo.cpp -o shiocus

# Run the demo
./shiocus

Minimal Example

#include "shiocus.cpp"

int main() {
    Shiocus engine;

    // Define the origin: row, col
    engine.initialize(2, 4);

    // Set the resting color (hex)
    engine.setDefaultWordColor("#FFFFFF");

    // Place some text
    engine.text("Text that knows where it is.");

    // Call one word into the light
    engine.setWordOnFocusAndColor("knows", "rgb(255, 0, 100)");

    // Draw
    engine.render();

    return 0;
}

---

🎯 Use Cases

1. Highlighted CLI Output

Log lines, search results, status messages — anything where one word needs to stand out from the rest.

engine.text("Build succeeded in 4.2s");
engine.setWordOnFocusAndColor("succeeded", "#00FFAA");
engine.render();

2. Terminal Menus

Menu options, prompts, and selections where the active item needs to be visually distinct.

3. Status Dashboards

Fixed-position readouts — labels and values placed once, updated by re-rendering with new focus.

4. Debugging & Inspection

Print a block of text, then walk through it by index to see exactly where each word landed.

5. Personal Projects

Anywhere a plain printf leaves you guessing where the cursor went. Placement, made explicit.

---

🌈 Why Shiocus

Most terminal projects fall into one of two camps: they print text and forget it, or they build a whole TUI framework. Shiocus sits in between.

It doesn't want to render a full interface. It doesn't want to manage input. It doesn't want to own your terminal. It just wants to remember where your words are — and then let you point at one.

If you're placing text and you want to find it again — this is what it's for.

---

⚖️ Comparison

	Shiocus	Plain printf	Full TUI Libraries
Dependencies	None	None	Several
Setup	One class	Trivial	Framework to learn
Positioning	Tracked, per-word	Manual \033[H	Framework-managed
Color Control	Full RGB + focus	ANSI only	Varies
Scope	Word placement & focus	Print only	Full-screen UI
Feel	Precise, deliberate	Static	Functional, boxy
Learning curve	Minutes	Seconds	Hours to days

Shiocus isn't trying to replace your TUI library. It's trying to make the words inside it findable.

---

🧬 Design Philosophy

Shiocus is small on purpose.

• It doesn't try to be a rendering engine.
• It doesn't try to be a framework.
• It doesn't ask you to adopt a build system, a config file, or a new way of thinking.

It's one class that does one thing well.

Colors, focus, indices — these aren't buried constants. They're exposed, documented, and waiting for you to tune them. You're supposed to reshape it.

---

things to be noticed

when a word gets split across lines because it's too long for the remaining space, each chunk becomes its own word entry with its own index. setWordOnFocusAndColor("word", ...) will match every chunk with that exact text — so focusing a split word lights up all its pieces, not just one.

if you need to focus a single chunk, use setIndexOnFocusAndColor(index, ...) instead.

---

📄 License

Licensed under the MIT License. See LICENSE for details.

---

Built for the terminal.

"A word is placed. A word is found. The screen remembers."

⬆ Back to Top