binaryx logo

Minimal, precise, and explanatory tools for working with numbers across bases. Includes step-by-step conversions, fraction support, base-aware rounding, two's complement (C2) when appropriate, and endianness views.

License: AGPL-3.0 PRs welcome Status: active

🇪🇸 Versión en Español

• Table of Contents
• Features
• Routes
• Getting Started
  • Requirements
  • Install
  • Develop
  • Build & Run
  • Tests
• Model & Architecture
  • Relevant Structure
  • Conversion Flow
• Converters & Rules
  • Decimal → Binary
  • Binary → Decimal
  • Decimal → Octal
  • Decimal → Hex
  • Binary → Octal / Hex
  • Hex ↔ Binary
  • Octal ↔ Binary / Decimal / Hex
• Two’s Complement (C2)
  • When it applies
  • Minimum width in Decimal → Hex
  • Signed interpretation in Hex → Decimal
  • Endianness
• Precision & Rounding
• Code Standards
• Contributing
• Bug Reports & Support
• Security
• Source link (AGPL §13)
• Status
• License

• Stepwise base conversions (separate integer/fraction tables, recap & join).
• Fraction support with fixed 20 decimal digits in decimal outputs.
• Base-aware rounding (e.g., in hex round if next digit ≥ 8).
• Two’s complement (C2) only when appropriate (see rules), with minimum byte width for negative dec→hex.
• Endianness views by byte (Big/Little) for C2 representations.
• Clean, responsive UI; "Signed" toggle appears only when it makes sense.
• Modular code and BigNumber precision for large integers & fractions.

• / — Landing page with CTA and features.
• /conversiones — Conversion panel with input, results, and steps.
• /operaciones — Operations & visualizations (sums/subtractions, Booth for integers, fixed-point for fractional).

• Bun 1.1+ (recommended) or Node.js 18.18+
• pnpm or npm if you don’t use Bun

bun install
# or
pnpm install

# from repo root
bun run dev:web
# or
cd apps/web && bun run dev

Open http://localhost:3001

# build all (turborepo)
bun run build
# run only the web app
cd apps/web
bun run start

Vitest config lives in apps/web/vitest.config.ts:

cd apps/web
bunx vitest

• Framework: Next.js 15 (App Router) + React 19
• Precision: BigNumber (fractions & large integers)
• UI: modular conversion components + a results orchestrator

apps/web/src/app/
 page.tsx
 (routes)/conversiones/page.tsx
 (routes)/operaciones/page.tsx
apps/web/src/components/
 conversion-results-panel.tsx # orchestrates result views
 input-results-panel.tsx # input + results
 results/<conv>/{summary,analysis,steps,final}.tsx
 theme-switch.tsx
 LetterGlitch.tsx
apps/web/src/lib/
 base-conversions.ts # conversion core
 utils/* # types, helpers, formatting, etc.

1. Input validation by base.
2. Conversion with pure functions (integer/fraction split when applicable).
3. Produce a ConversionResult with:
   • magnitude (unsigned), output (string), signedResult?, twosComplementHex?
   • steps integerSteps? / fractionalSteps?
4. UI decides whether to show "Unsigned/Signed" and endianness based on rules.

• Integers: successive division by 2, reverse remainders.
• Fractions: multiply by 2 storing bits; compute 20+1 bits to decide rounding (if next bit is 1, round; carry into integer if needed).
• Signs:
  • Positive or negative (explicit sign): Unsigned view only prepends - to magnitude.
  • "Signed (C2)" only for explicit negatives.

• Positional: bit ×ばつ 2^n for integer; bit ×ばつ 2^-k for fractions with BigNumber.
• "Signed (C2)" view available when:
  • No explicit - and the integer MSB is 1 (signed interpretation).

• Integer: divide by 8; fraction: multiply by 8 (+ base-8 rounding if next digit ≥ 4).
• Signs: only prepend - in unsigned view; no C2 in octal.

• Integer: divide by 16; fraction: multiply by 16 with base-16 rounding (next digit ≥ 8).
• Signs:
  • Positives & fractions: no C2.
  • Negative integers: compute C2 with minimum byte width (power of 2; min 16 bits). C2 output is uppercase.
• Endianness: Big/Little-endian by bytes (display omits leading 00 rows for clarity; actual value remains unchanged).

• Grouping: 3 bits → octal, 4 bits → hex. For fractions, group to the right.

• Expand/contract by nibbles (4 bits per hex digit). Trim leading/trailing zeros where appropriate.

• Via 3-bit grouping (octal) or powers of 8 for decimal.

• Never for positives.
• Never for fractions.
• Applies in:
  • Decimal → Hex when the decimal is negative and integer.
  • Hex → Decimal ("Signed" mode) when there’s no explicit -, it’s integer, and the MS nibble ≥ 8.

• Use the smallest byte width (power of 2) that can represent |N| in C2; min 16 bits.
• Examples:
  • -20 → FFEC
  • -276 → FEEC
  • -2076 → F7E4
  • -9999 → D8F1
  • -999999 → FFF0BDC1

• If MS nibble ≥ 8 (and input is integer without -), Signed (C2) does:
  1. subtract 1
  2. invert nibbles (15 − digit)
  3. conceptually add 1 → magnitude
  4. convert to decimal, then prefix -
• UI shows the inversion table explicitly.

• When showing C2 (dec→hex negative), render byte tables for Big/Little endian.
• Omit superfluous leading 00 rows (value itself is unchanged).

• BigNumber avoids scientific notation and preserves high precision.
• Decimal fractions: fixed 20 digits for visual stability.
• Base-aware rounding:
  • base-2: next bit 1 rounds the last kept position (carry to integer if needed)
  • base-8: next digit ≥ 4
  • base-16: next digit ≥ 8

• Strict TypeScript, React 19, Next.js 15.
• Pure logic separated from UI.
• Clear names; avoid cryptic abbreviations.
• Grouping/formatting of digits is a UI task (not core logic).

See CONTRIBUTING. We follow Conventional Commits and welcome:

• Bug reports with minimal repro
• Feat proposals with clear use-cases
• Docs and tests

When opening an issue, include:

• Conversion path (from → to), exact input (with/without -, with/without fraction)
• Expected vs. actual (and why)
• Browser/OS + screenshots/logs if helpful
• Minimal steps to reproduce

Feature requests: describe use case, scope, and impact.

Please do not disclose exploitable details in public issues. Follow SECURITY for private reporting.

If you deploy binaryx as a network service, expose a visible "Source" link in the UI pointing to this repository (and ideally the current commit).

Minimal example for a footer component:

// apps/web/src/components/SourceLink.tsx
"use client";
export default function SourceLink() {
 const sha = process.env.NEXT_PUBLIC_GIT_SHA ?? "main";
 return (
 <a
 href={`https://github.com/ApocalixDeLuque/binaryx/tree/${sha}`}
 target="_blank"
 rel="noreferrer"
 className="underline hover:no-underline"
 aria-label="View source code on GitHub"
 >
 Source
 </a>
 );
}

Active — roadmap includes BCD/Gray/base-N, overflow viz, bit-flip timelines, and digital logic (gates, truth tables, circuits).

AGPL-3.0. See LICENSE.