md-files/CLAUDE.md

Coding Standards

0. Product Spec (spec-driven development)

This app uses github/spec-kit for spec-driven development. Specs live under specs/<NNN>-<feature-name>/spec.md, one directory per feature.

• To start a new feature, run /speckit.specify <description> in Claude Code or Cursor. It generates a properly numbered feature directory and a spec to fill in. Then run /speckit.clarify → /speckit.plan → /speckit.tasks → /speckit.implement.
• When user-visible behavior changes in an existing feature, update its specs/<NNN>-<feature>/spec.md before or alongside the code change.
• When a feature integrates with backend data sources, the spec must document data models, APIs, and data contracts involved.

---

1. UI Components

Always check your chosen component library (e.g., Aura, shadcn/ui, Material-UI, Chakra UI) before reaching for a raw HTML element or custom CSS/Tailwind solution. If your component library has a component that covers the need, use it. Only fall back to custom solutions when the library genuinely doesn't cover the use case.

---

2. Host/Platform integration

When deploying to a host platform (Fusion, portal, dashboard, or embedded context), use the platform's official API to access host capabilities like navigation, auth, and state management. Reach for it whenever the situation calls for it — don't hand-roll an equivalent or read browser globals directly.

Decision rule for any new piece of state

Before adding useState, useReducer, or a store entry, ask: "would a user expect this to survive a page reload, or to be restored when someone opens a shared link?" If yes, it belongs in syncInternalState + initialState, not in plain React state.

• Yes, host-synced: current page / active view / route, selected tab, active filters, selected resource id, search query, sort order, expanded rows, focused row, side-panel open/closed — anything that drives what the user sees.
• No, local-only: in-flight form input before submit, hover/focus, transient toasts, animation state, optimistic UI mid-flight.

When in doubt, host-synced is the safer default — over-syncing is cheap, under-syncing breaks reload and share.

API surface

• Host-synced UI state → on startup, seed your state from the initialState string returned by connectToHostApp. On every change, call api.syncInternalState(JSON.stringify(state)). The host serializes this into the URL so reloads and shared links restore the same state. Do not hold state from the "host-synced" category above in plain useState / useRef / a local store.
• Navigating to another app or internal route → use the platform's navigateInternal() API instead of window.location to maintain state and context.
• Navigating to an external URL → use the platform's navigateExternal() API where available; ensure only safe URLs (https:) are allowed.
• Needing a base URL or access token for API requests → call the platform's getBaseUrl() / getAccessToken() helpers instead of hardcoding or reading from globals.
• Needing the current project/workspace identifier → call the platform's getter (e.g., getProject()) instead of reading from config or URL params.
• Exposing the app's capabilities to an agent or AI system → use the platform's agent registration API and clean up on unmount.

Get the platform API instance once at app startup and surface it to the rest of the app via React context so view models can depend on it through the patterns below.

Round-trip example: host-synced state

import { connectToHost, type HostAPI } from './platform'; // or your platform SDK

type AppState = { page: 'a' | 'b'; filters: string[] };
const DEFAULT_STATE: AppState = { page: 'a', filters: [] };

// On startup — seed from initialState, not from a hardcoded default.
const { api, initialState } = await connectToHost({ applicationName: 'my-app' });
const seeded: AppState = initialState ? (JSON.parse(initialState) as AppState) : DEFAULT_STATE;

// On every change — push the new state to the host so the URL stays in sync.
async function updateState(next: AppState, api: HostAPI) {
  setState(next); // your local React/store setter
  await api.syncInternalState(JSON.stringify(next));
}

initialState is the JSON string the host extracted from the URL on this load — the host owns the URL plumbing, the app just reads/writes the string.

---

3. Dependency Injection

All non-stateless dependencies must be injected. Never import and call a service, SDK client, or stateful module directly inside a component or hook — it makes the code untestable and tightly coupled.

What to inject: SDK clients, API services, analytics, timers (Date.now, setTimeout), random generators, external stores. What not to inject: pure functions, constants, type utilities.

Use narrow interfaces — depend only on the subset of a service you actually need.

React context (hooks and components)

const defaultDeps = { useDataSource, useAnalytics };
export type MyHookContextType = typeof defaultDeps;
export const MyHookContext = createContext<MyHookContextType>(defaultDeps);

export function useMyHook() {
  const { useDataSource } = useContext(MyHookContext);
}

Factory overrides (plain functions)

type Deps = { serviceFactory: () => SomeService };
const defaultDeps: Deps = { serviceFactory: () => new SomeServiceImpl() };

export const doWork = async (props: Props, overrides?: Partial<Deps>) => {
  const { serviceFactory } = { ...defaultDeps, ...overrides };
};

---

4. Interface-Based Services

Define an interface; implement with a class. Never reference the concrete class outside its own file.

export interface DataService {
  load(): Promise<Data>;
  save(data: Data): Promise<void>;
}

export class ApiDataService implements DataService {
  /* ... */
}

---

5. ViewModel Pattern

Business logic lives in use<Name>ViewModel. Components only render.

export function useTodoViewModel(): TodoViewModel {
  const { useTodoStorage, addTodoCommand } = useContext(TodoViewModelContext);
  const storage = useTodoStorage();
  const addTodo = useCallback(
    (text: string) => addTodoCommand(text, storage),
    [storage, addTodoCommand]
  );
  return { todos: storage.listAllTodos(), addTodo };
}

export const TodoView = () => {
  const { todos, addTodo } = useTodoViewModel();
  return <ul>{todos.map((t) => <TodoItem key={t.id} todo={t} onAdd={addTodo} />)}</ul>;
};

Where state lives

A ViewModel hook must not hold state with useState / useReducer directly. State lives in a shared storage layer — a context-backed hook (like useTodoStorage above), a store, or a *StateProvider rendered once near the root of the view tree. The ViewModel composes that storage with commands and derivations; it is itself stateless.

This matters because each call to a useState-backed hook creates an independent piece of React state. Two components calling the same ViewModel hook would each get their own copy and never sync.

⚠️ Anti-pattern: useState inside useFooViewModel, then two sibling components each call useFooViewModel(). Clicks update one copy; the other renders stale data.

How many times to call a ViewModel hook

• Backed by shared context / store → multiple components may call the hook; they all observe the same value. This is the default for non-trivial views.
• Not backed by shared state → call the hook once at the top of the view tree and pass values down as props. Never call it twice and expect them to stay in sync.

Host-synced state inside a ViewModel

When a ViewModel exposes state that falls under §2's "host-synced" category, the ViewModel — not the view component — is responsible for seeding from initialState and pushing changes via syncInternalState. The state itself still lives in the shared storage layer described above; the ViewModel just owns the read/write contract with the host.

---

6. Test-First Development

Write tests before implementation for all non-trivial behavior changes.

Preferred order

Start with behavior-focused tests so requirements are specified before implementation details:

1. Integration tests (user-visible behavior)
2. Unit tests (isolated module logic)
3. Source files to make tests pass

For bug fixes, start by adding a failing regression test that reproduces the issue.

Every new module with logic (service, hook, component, utility) must include a corresponding *.test.ts(x) file in the same changeset.

Reasonable exceptions

• Bootstrapping/entry files (for example main.tsx)
• Generated code
• Trivial pure-markup components with no logic or state

Test levels in this repo

• Integration test: validates behavior across boundaries (for example component + view model + service contract), mocking only external systems such as network APIs.
• Unit test: validates one module in isolation (service, hook, utility, or component behavior).

Minimum expected coverage by file type

File type	Required test cases
Service (*Service.ts)	Correct request construction; response parsing; error thrown on non-OK status
ViewModel hook (use*ViewModel.ts)	Loading state; success state with correct derived values; error state
Pure utility / helper	Every exported function and all meaningful branches
View component	Renders expected content from props; loading/error/empty states where applicable

Conventions

• Files: *.test.ts(x); runner: Vitest (npm test or vitest run)
• Structure: Arrange / Act / Assert (add explicit comments for longer tests)
• One behavior per test
• Keep helper functions at the bottom of the file
• Prefer dependency/context injection over vi.mock; add a short reason when vi.mock is unavoidable

Type-safe mocks

// Preferred: vi.fn(() => ...) for consistent behavior
mockContext = { useUserInfo: vi.fn(() => ({ data: mockUser, isFetched: true })) };

// Per-test reconfiguration
mockContext = { useUserInfo: vi.fn() };
vi.mocked(mockContext.useUserInfo).mockReturnValue({ data: undefined, isFetched: true });

For full interface mocks, use assert.fail on methods the unit under test should never call, or preferably define a narrower interface.

mockStorage = {
  list: vi.fn(),
  retrieve: vi.fn(() => {
    assert.fail('Not implemented');
  }),
};

React hook test pattern

describe(useMyHook.name, () => {
  let mockContext: MyContextType;
  let wrapper: ComponentType<{ children: ReactNode }>;

  beforeEach(() => {
    mockContext = { useUserInfo: vi.fn(() => ({ data: mockUser })) };
    wrapper = ({ children }) => (
      <MyHookContext.Provider value={mockContext}>{children}</MyHookContext.Provider>
    );
  });

  it('should ...', async () => {
    const { result } = renderHook(() => useMyHook(), { wrapper });
    await act(async () => {
      await result.current.someAction();
    });
    await waitFor(() => expect(result.current.isLoading).toBe(false));
  });
});

Shared mock data

Place reusable factories in src/__mocks__/. Use .test TLD for fake URLs (RFC 2606).

---

7. TypeScript Rules

• Never use any; prefer unknown or explicit strong types
• Never use as casts — they silence the compiler without providing safety. Use type guards instead.
• Exception: Partial<T> as T is acceptable for test mocks only.
• All function parameters must have type annotations.
• Use direct React type imports: import type { ComponentType, ReactNode } from 'react'

// ❌ Never
const x: any = data;
const y = data as SomeType;
const z = {} as unknown as Window;
function process(data) { ... }         // missing parameter type

// ✅ Type guard
function isSomeType(value: unknown): value is SomeType {
  return typeof value === 'object' && value !== null && 'id' in value;
}
if (isSomeType(data)) { /* TypeScript now knows */ }

// ✅ Test mock only
const mock = { postMessage: vi.fn() } as Partial<Window> as Window;

---

8. SDK / API client and authentication

Auth and API client setup should be handled at the app root via a provider (e.g., SdkProvider, AuthProvider, etc.). Nested components access the client via a context hook (e.g., useSdk(), useClient()). Centralize all authentication logic in one place for consistency and testability.

---

9. Commits and pull requests

Use Conventional Commits v1.0.0.

• Commit in small, buildable steps while lint and tests remain green for this repo. Split unrelated edits into separate commits before opening a pull request.
• Subject line: type[(scope)][!]: description — imperative mood, no trailing period, blank line before an optional body. Use ! before : and/or a BREAKING CHANGE: footer for incompatible changes (full rules in the link above).
• Types (pick the narrowest match): feat, fix, docs, style, refactor, perf, test, build, ci, chore. Scope: optional short area (auth, chat, deps); omit if it would be vague.
• Body: only for non-obvious motivation or behaviour; keep it short and do not repeat the diff. Footers (for example Fixes #123) when this project tracks issues that way.
• Pull requests: title and Summary should match the same vocabulary; do not replace conventional commits with only a PR headline.
• Before committing: review git status and git diff (including staged); unstage and commit separately if the index mixes unrelated concerns.

---