@dipz/fca-ui-guardrail

Tiny dev-only guardrail to keep UI aligned with intent.

If you like calm frontend code, this helps.
If not, you probably won’t use it.

Install

npm install @dipz/fca-ui-guardrail

Copy–Paste Usage (the whole pattern)

import {
  explain,
  assertActionAllowed,
  guardIntent,
} from "@dipz/fca-ui-guardrail";

export function CheckoutButton({ intent, dispatch }) {
  // 1. Guard the intent (dev only)
  const safeIntent = guardIntent(intent);

  // 2. Declare what this component uses
  explain(safeIntent, {
    component: "CheckoutButton",
    uses: [
      "ui.visibility.checkoutButton",
      "ui.enabled.checkoutButton",
      "actions.primary",
    ],
  });

  // 3. Render purely from intent
  if (!safeIntent.ui.visibility.checkoutButton) return null;

  return (
    <button
      disabled={!safeIntent.ui.enabled.checkoutButton}
      onClick={() => {
        assertActionAllowed(safeIntent, "primary");
        dispatch(safeIntent.actions.primary);
      }}
    >
      Checkout
    </button>
  );
}

That’s it.
No other setup required.

What This Does

• Throws if UI reads a field that doesn’t exist
• Throws if UI dispatches a forbidden action
• Prevents UI from inventing logic
• Makes refactors safer
• Keeps AI edits from drifting

Errors are loud and immediate.

What This Does NOT Do

• Does not decide business logic
• Does not manage state
• Does not run in production
• Does not replace your framework

Dev-time guard only.

Optional: Project Awareness (CLI)

This package also includes an optional CLI that scans your project and builds a lightweight UI usage map.

Run the scanner

npx fca-ui-guardrail

This will generate:

docs/
  ai/
    bridge.json
    summary.md

Accept intentional changes

npx fca-ui-guardrail --update

Mental Rule

UI reads intent.
UI does not think.

License

MIT