janus

Imported from ggghhhjjj/janus (AGENTS.md). Install upstream with npx skills add ggghhhjjj/janus. Copyright stays with the author.

Agent Instructions — Hello Cordova (Angular + Browser)

Project Overview

Apache Cordova app targeting the browser platform, with Angular 21 as the UI framework.

• Angular source: src/ — always edit files here
• Build output: www/ — generated by npm run build, do not edit
• Cordova output: platforms/browser/www/ — generated by Cordova, do not edit
• App config: config.xml
• Dependencies: package.json

Key Source Files

Build & Run Commands

npm install          # First time or after package.json changes
npm run build        # ng build → www/ → cordova build browser
npm run cordova:run  # Build + serve in browser
npm run watch        # ng build --watch (Angular only, no Cordova step — fast dev loop)
npm test             # Vitest (watch mode auto-starts)
npm run clean        # Delete www/ output directory

Requires cordova CLI: npm install -g cordova

How It Works

1. npm run build → ng build compiles src/ → www/
2. Cordova copies www/ → platforms/browser/www/ and serves it
3. The before_prepare hook fires npm run build on every cordova run/build/prepare

Angular Conventions

• Standalone components — always standalone: true, no NgModule.
• Signals for reactive state: signal(), computed(). No manual subscriptions for local state.
• Component naming: app.ts, app.html, app.css (no .component. infix).
• CordovaService.deviceReady$ is the only entry point for Cordova plugin access.

Widget Architecture

Dashboard sections are self-sufficient widgets — each widget owns its data, presentation, and styles without receiving inputs from its host.

Rules:

• Widgets inject StateService (or other services) directly — never use @Input() to pass data that could be fetched from a service.
• Exception: ActionMenuComponent is a reusable UI primitive that legitimately receives ActionMenuItem[] via @Input() — this is not a dashboard widget.
• Use toSignal(inject(StateService).fifoState$, { initialValue: null }) as the standard pattern to subscribe to reactive state.
• Widget CSS files are self-contained — include .card, .card__title, utility classes like .text-right etc. if used in the template.
• .card base styles are defined globally in src/styles.css — no need to redeclare; declare only widget-specific overrides.
• The DashboardComponent is layout-only: it may contain conditional rendering (@if) but no data-derivation logic.

Template for a new widget:

@Component({
  selector: 'app-my-widget',
  standalone: true,
  imports: [CurrencyPipe],  // only what the template uses
  templateUrl: './my-widget.html',
  styleUrl: './my-widget.css',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class MyWidgetComponent {
  private readonly fifoState = toSignal(inject(StateService).fifoState$, { initialValue: null });
  readonly i18n = inject(I18nService);
  readonly myData = computed(() => this.fifoState()?.someField ?? defaultValue);
}

See src/app/components/total-gain-loss/ for the simplest widget example.

CSS Conventions

All CSS in this project must follow BEM (Block Element Modifier) naming.

Rules:

• Block: the component root class, e.g. .swap-modal, .transaction-table.
• Element: a child of a block, joined with __, e.g. .swap-modal__title, .swap-radio-label__input.
• Modifier: a variant of a block or element, joined with --, e.g. .type-badge--buy, .modal-card--wide.
• Never use nested tag selectors to style elements — e.g. .swap-radio-label input is wrong; use .swap-radio-label__input instead.
• Never use ID selectors (#foo) for styling.
• Pseudo-classes and pseudo-elements are allowed directly on a BEM class — e.g. .swap-radio-label__input:checked::before is correct.
• Each BEM block maps to one component CSS file; blocks are not shared across components (except globals in src/styles.css and the transaction-cell design system in src/app/components/shared/tx-table/tx-table.css).
• Never redeclare .type-badge*, .num-cell*, .col-date__*, .tx-ticker__meta, .tx-row--conflict, or .notes-cell in any consumer component CSS — they live in tx-table.css.
• Never add inline styles to elements that have a corresponding class in tx-table.css (e.g. .tx-ticker__meta, .tx-total, .tx-fee are already styled there).

CSS Shared via ViewEncapsulation.None

TxTableComponent uses ViewEncapsulation.None so its styles apply to projected content from any parent component. Angular's emulated encapsulation stamps projected DOM elements with the providing component's _ngcontent attribute — not the wrapper's — so scoped CSS rules on the wrapper cannot match them. None makes the styles global; BEM class names are the safety boundary.

Rules for this pattern:

• Use only when the same CSS classes need to apply to content projected from multiple different parent components.
• Always set your-element-selector { display: block; } in the CSS file — HTML custom elements default to display: inline, which can disrupt block layout of children.
• Consumer components must add TxTableComponent to their imports array and wrap the table in <app-tx-table>.

Examples:

/* ✅ Correct BEM */
.swap-radio-label { }
.swap-radio-label__input { }
.swap-radio-label__input:checked { }
.swap-radio-label__input:checked::before { }
.type-badge--buy { }

/* ❌ Wrong — nested tag selector */
.swap-radio-label input[type="radio"] { }

/* ❌ Wrong — nesting without BEM element class */
.swap-radio-label > span { }

Service Conventions

• Pure/sync services: Business-logic services (FifoService, MatchingService) are stateless and synchronous — no async, no RxJS, no Angular injection needed to instantiate them in tests.
• Rounding: always import round2 from src/app/utils/number-utils.ts. Never redefine a local rounding helper.
• Responsibilities:
  • FifoService — canonical FIFO math, produces FifoState (single source of truth for numbers).
  • MatchingService — presentation transform only: flattens FifoState → rows/totals/verification. No DB or state writes.
  • StateService — reactive bridge; calls FifoService.calculate() and exposes fifoState$ to the UI.
• Testing: pure services can be unit-tested by new FifoService() / new MatchingService() directly — no TestBed.
• MatchingService verification: uses epsilon 0.01 to compare detailed gain sum vs fifoState.totalRealizedGainLoss.

Tests

• Runner: Vitest (npm test → ng test). Watch mode starts automatically.
• Location: co-located spec files (*.spec.ts) next to the source they test.
• Style: describe / it / expect from vitest — see src/app/services/fifo.service.spec.ts for reference.
• Transaction factory pattern: use a makeTx(overrides) helper that spreads defaults (including required time: '00:00:00.000' and currency: 'USD') before overrides.
• Transaction.seqNo is optional — used for conflict ordering when multiple transactions share the same date + time + ticker. Use StateService.swapSeqNos() to resolve conflicts.
• For MatchingService tests compose FifoService.calculate(txs) to produce canonical FifoState, then assert MatchingService.computeMatching(state) — see src/app/services/matching.service.spec.ts.
• No Angular TestBed is needed for pure service tests.

i18n Conventions

See full documentation in I18N.md. Use /add-i18n skill for step-by-step help.

• All user-facing strings must use i18n.translate('key') — no hardcoded English or Bulgarian text in templates.
• Source of truth: src/app/services/translations.generated.ts — edit this directly to add/update keys.
• Supported locales: en (English), bg (Bulgarian, default).
• Service injection: readonly i18n = inject(I18nService); in component class body.
• Template patterns:

  {{ i18n.translate('myKey') }}
  [placeholder]="i18n.translate('myKey')"
  [attr.aria-label]="i18n.translate('myKey')"

• Never use Angular's i18n attribute or ng extract-i18n — not compatible with this runtime approach.

Cordova Conventions

• Always use CordovaService.deviceReady$ — never add raw deviceready listeners.
• cordova.js is injected at runtime by the platform — do not move the <script src="cordova.js"> tag.
• CSP is set via <meta http-equiv="Content-Security-Policy"> in src/index.html.
• Plugins: cordova plugin add <plugin-id>, declared in config.xml.

Common Pitfalls

• Never edit www/ or platforms/browser/www/ — auto-generated.
• No hardcoded UI strings — all text goes through i18n.translate().
• CSP failures are silent — if an API call fails, check src/index.html CSP header.
• cordova object undefined in dev — always guard with typeof cordova !== 'undefined'.
• ViewEncapsulation.None styles are global — classes in tx-table.css apply everywhere once TxTableComponent is mounted. Never add generic or short class names to this file; BEM is the only safety net.
• Custom elements default to display:inline — any new ViewEncapsulation.None wrapper component must include selector { display: block; } in its CSS file.