JavaScript and TypeScript

This specification applies to sdk/js, shared JavaScript packages, Wails frontends, generated OpenAPI clients, and Node or Playwright test harnesses.

Types and Boundaries

• Give priority to using types and clients generated by Schema, and do not repeatedly splice endpoints or hand-write existing request/response shapes.
• External JSON, event, SSE, WebRTC, and RPC payloads must be validated at the boundary; do not mask undefined input with any, unchecked cast, or type assertions.
• Browser, Wails, Node and test runtime have different support for global, storage, crypto, URL, stream and timer. The target runtime must be specified before use.
• Regenerate the TypeScript surface after modifying the OpenAPI/RPC contract, without directly modifying the generated file manually.

Asynchronous and life cycle

• Promise must be await, returned, or handled explicitly; rejection must not be swallowed.
• Long requests, streams, subscriptions and UI effects should accept or create explicit abort/cancel paths and clean up on uninstall or end.
• timeout, retry and reconnect must be capped, with eventual failure reserved to the caller.
• The stream parser must handle fragmented messages, empty messages, malformed payloads, ordering, reconnection and terminal state.

SDK and front-end

• SDK method, cursor, stream shape and error payload must be consistent with the server contract.
• UI flow should clearly understand the loading, empty, error, success, stale data and permission denied states.
• The form validates input before sending the request and retains server-side errors for the user to understand.
• Interactive components must have keyboard reachability, focus behavior, label, disabled state, and stable button semantics.
• Do not present placeholder or roadmap behaviors as delivered functionality.

Dependencies, testing and verification

• New dependencies must be absolutely necessary; correct lockfiles are committed synchronously, and browser bundle and provider coupling are evaluated.
• Use unit test for parser, transformations, SDK helpers and error handling; use component or integration test across routing, API and UI state; use E2E when relying on real browser/Wails behavior.
• Prioritize running scripts defined by the package itself, for example:

npm --prefix sdk/js test
npm --prefix sdk/js/gizclaw test

Schema changes should also run the corresponding build command and verify the build diff.