ftui-simd (Reserved)

ftui-simd is a reserved sandbox crate. It sits in the workspace so that future SIMD-accelerated paths (render kernels, grapheme width tables, text shaping hot loops) have an obvious home — and so readers of the source tree see an intentional placeholder rather than wondering whether a broken crate has been forgotten.

Status: Reserved. The crate contains a module-level doc comment and no functional code. There is nothing to call, nothing to import, and no cargo feature that turns anything on yet. This page documents the reserved status and the design intent — not an API.

What the README says

In the workspace crate table, ftui-simd is listed explicitly as Reserved:


| ftui-simd | SIMD acceleration | Reserved |

That is not an oversight. It is the same status FrankenTUI uses for any crate that has a namespace claim but no shipping functionality — the crate exists to prevent name squatting, to host a clear statement of intent, and to give future work a place to land that will not require renaming or restructuring the workspace.

What is inside it today

The entire crate is this:


#![forbid(unsafe_code)]
 
//! Optional optimization crate.
//!
//! # Role in FrankenTUI
//! `ftui-simd` is a sandbox for safe, performance-oriented code paths. It
//! allows experimentation with autovec-friendly loops and portable SIMD
//! without imposing dependencies on the core crates.
//!
//! # How it fits in the system
//! This crate is optional and should be wired in via feature flags. The
//! render kernel or other performance-sensitive components can call into
//! this crate when enabled, but the base system remains fully functional
//! without it.
//!
//! Note: This project currently forbids unsafe code. This crate exists to
//! host safe optimizations behind feature flags without impacting the rest
//! of the workspace.

No public items. No tests. No hidden scaffolding. The comment is the specification.

Why reserve a crate this way

Three reasons, all of them about graph hygiene:

Dependency-free stub. ftui-simd has no [dependencies] section. That means merging it into the workspace graph cost zero compile time and pulled in zero transitive crates. When it grows real code, the blast radius is opt-in through feature flags.
Reviewer clarity. A new contributor who stumbles into crates/ftui-simd/ sees a single file with a block comment that says “reserved, here is why.” They do not file bugs, they do not waste time reading phantom APIs, and they do not assume a stalled refactor.
Future-proof naming. When portable SIMD stabilizes on the Rust toolchain FrankenTUI pins, we want the crate name already in the workspace. Changing crate names after the fact means breaking every downstream Cargo.toml that depends on us.

The unsafe-code bar

The whole workspace is #![forbid(unsafe_code)]. That rule is not negotiable. ftui-simd exists precisely because safe SIMD optimization paths — autovectorization, std::simd once stable, explicit portable SIMD through a safe abstraction crate — are a real and distinct design space that deserves its own crate. Spreading safe perf experiments across ftui-render or ftui-text would muddy both crates. Keeping them in a named, reserved sandbox with its own feature flag means:

the core crates stay focused on correctness,
experimental perf work has somewhere to land that does not break the rest of the workspace if it turns out to be a bad idea,
and an eventual opt-in feature flag like simd-hot-paths can wire things up without touching every consumer crate’s Cargo.toml.

The intended integration pattern — when the crate grows code

The shape of the eventual wiring is already sketched in the crate doc:

ftui-simd publishes safe implementations of specific hot kernels (e.g. buffer diff inner loop, packed-RGBA conversion, grapheme-width cache lookups).
Consumer crates (ftui-render, ftui-text, potentially ftui-extras) depend on ftui-simd behind an optional feature.
A top-level cargo feature (name TBD) toggles the set on or off. With the feature disabled, the scalar paths in the consumer crates remain fully functional — the SIMD version is always an optimization over an existing correct implementation, never the only implementation.
SIMD paths must pass the same golden tests the scalar paths pass. Equivalence is load-bearing: a test that only exercises the fast path is worthless if it does not also assert parity with the scalar path.

None of that is in place yet. The comment, the empty graph, and this documentation page are the entire status.

What you can and cannot do with the crate today

Action	Status
Add `ftui-simd` to your `Cargo.toml`	You can, but it exports nothing.
Enable a feature flag to “turn on SIMD”	No such flag exists yet.
File a bug against SIMD performance	There is no code to file against.
Propose an SIMD kernel	Yes — open an issue referencing this page and ADR-007 for the modular-feature-flag pattern.

Pitfalls

Do not document SIMD features that do not exist. When the crate grows, document each kernel under extras or under the crate that consumes it, not here. This page documents the reserved status.
Do not confuse “reserved” with “stalled.” Reserved is an active design decision. The crate is not waiting on anyone.
Do not sprinkle unsafe into a future SIMD implementation. The workspace-wide forbid(unsafe_code) applies here too. Use the portable SIMD path from std, or lean on autovectorization, or gate an unsafe dependency with a clearly named feature that is off by default and documented as an opt-in.