SRCL Documentation

Use this mapping to translate Sacred React components into Simulacrum CLI primitives:

The Python port of the Sacred framework is a one-to-one mirror of the JavaScript framework, but uses snake_case for all function and method names.

Note: button(hotkey, label) and the COLORS dictionary retain their original casing.

Follow these established patterns to maintain consistency:

• Comments: Use //NOTE(jimmylee): in TS/JS and # NOTE(jimmylee): in Python. Comment the why, not the what. If the code is clear, omit the comment.
• Naming: Use descriptive names (e.g., candidateCount instead of cnt). Do not use a __private prefix; use plain const for module-private state or React refs for internal state.
• Simulacrum CLI: This is a zero-dependency TypeScript framework run via tsx. Do not import its Node-only code (which uses process.stdout) into React components.
• Types: Prefer as const objects over enum to ensure zero runtime overhead and better tree-shaking. Avoid const enum due to isolatedModules: true constraints.

const DIRECTION = { Up: 'UP', Down: 'DOWN', Left: 'LEFT', Right: 'RIGHT' } as const;
type Direction = (typeof DIRECTION)[keyof typeof DIRECTION];

When writing code inside a requestAnimationFrame loop, follow these rules to minimize per-frame costs:

1. Cache refs and property chains: Hoist ref.current and property lookups into local variables before entering the loop.
2. Diff before DOM mutation: Only update textContent or style properties if the value has actually changed. This prevents unnecessary layout/reflow work.
3. Use indexed for-loops: Avoid map, filter, forEach, or sort inside the loop to prevent per-frame closure allocations. Avoid for...of as it invokes the iterator protocol.
4. Pre-allocate buffers: Allocate arrays and grids during setup/build phases. Never allocate new objects or arrays inside the frame loop to avoid GC pressure.
5. Guard the entire loop: Use an IntersectionObserver to stop the animation loop entirely when the component is off-screen.
6. Use bitwise floor for positive math: Use x | 0 instead of Math.floor(x) for truncating positive integers (e.g., grid indexing).
7. Maintain type lanes: Keep numbers in a consistent representation (e.g., keep loop indices as integers and wave math as doubles) to avoid V8 representation changes.
8. Strip diagnostic code: Remove console.log, JSON.stringify, and extra performance.now() calls from the production frame path.

To ensure your Python CLI matches the React implementation, use the built-in parity test suite.

Commands:

• npm run cli:python: Renders your specific screen in the terminal. Press ESC to quit.
• npm run test:python: Runs the Python-specific unit tests. This command regenerates the reference fixture (scripts/python/sacred_cli/__tests__/fixtures/reference.json) before running tests.
• npm test: Runs the full suite (JS framework tests + Python parity suite).

Troubleshooting Parity Failures: If a parity test fails, it usually means a TypeScript module was updated without updating its Python mirror.

1. Identify the failing assertion (e.g., test_format_row_status).
2. Compare the TS module (e.g., scripts/cli/lib/table.ts) with its Python mirror (scripts/python/sacred_cli/table.py).
3. Port the logic changes to Python using snake_case.
4. Re-run npm test to automatically update the reference fixture.

npm test                # JS framework unit tests + Python parity suite
npm run cli:python      # your screen renders, ESC quits cleanly
npm run test:python     # only the Python suite

Use this skill to transform a CLI screen written for the Simulacrum framework (found in scripts/cli/templates/*.ts or scripts/python/templates/*.py) into a React component. The goal is to achieve layout parity using sacred's existing React primitives without re-implementing animations or box-drawing logic.

Workflow

1. Analyze the CLI screen: Identify cardTop/cardRow/cardBot blocks and buttonRow structures.
2. Create the React file: Place in components/examples/ (for demos) or components/ (for reusable surfaces). Use 'use client' only if browser APIs are required.
3. Map components:
   • cardTop blocks $\rightarrow$ <Card title="...">.
   • Data tables $\rightarrow$ <SimpleTable data={[...]} />.
   • buttonRow $\rightarrow$ <RowSpaceBetween> with <ActionButton> children.
4. Inherit theming: Do not import scripts/cli/colors.json. The React components automatically consume the ANSI palette via CSS custom properties (e.g., var(--theme-background)) defined in global.css.

Layout & Constraints

• Width: Replace the CLI's innerW concept with fluid browser layouts. Use <ContentFluid> or <Block> containers.
• Avoid Canvas: Do not use <ASCIICanvas> or attempt to port CLI animations; focus on the static layout.
• Avoid CLI Libs: Do not copy scripts/cli/lib/* into the React tree; use CSS Modules instead.