optima/.github/copilot-instructions.md

Copilot Instructions — electron-svelte (SveltronKit)

This repo is an Electron + SvelteKit app (SveltronKit). The goal of this document is to give an AI coding agent immediate, actionable knowledge about architecture, conventions, and common tasks so suggestions and changes are correct and context-aware.

Big picture

• App = Electron main + SvelteKit renderer. See electron/main.ts and renderer sources under src/.
• Renderer is a normal SvelteKit app but configured to use the hash router — all routed links expected in the app should begin with #/ when constructing absolute links for the packaged Electron app (see README).
• Electron main process loads the Vite dev server when MAIN_WINDOW_VITE_DEV_SERVER_URL is set; otherwise loads the built renderer. See electron/main.ts.

How to run & build (developer workflows)

• Uses pnpm. Always use pnpm install first.
• Dev (runs Electron + Vite via Electron Forge): pnpm run start (invokes electron-forge start).
• Build & package: pnpm run package (builds renderer with vite build then runs electron-forge package).
• Create distributable: pnpm run make.
• Tests: unit tests via vitest and e2e via Playwright. pnpm run test runs both (test:unit and test:e2e). See package.json scripts.

Key files & patterns to reference

• Electron bootstrap: electron/main.ts — env vars used: MAIN_WINDOW_VITE_DEV_SERVER_URL, MAIN_WINDOW_VITE_NAME.
• Preload bridge: electron/preload.ts (currently empty) — add safe, whitelisted APIs here when exposing functionality to the renderer.
• SvelteKit entry routes: src/routes/ (examples: src/routes/+page.svelte, src/routes/companies/+page.svelte).
• API client: src/lib/axios.ts — api is created from PUBLIC_API_URL ($env/static/public).
• Auth helper: src/lib/authUri.ts — example of calling backend /v1/auth/uri.
• Data access: src/lib/companies.ts — fetchMany(accessToken) demonstrates header usage Authorization: Bearer <token>.
• Global styles: src/app.css (Tailwind is present in the project).
• Patches: patches/ contains @sveltejs__kit.patch and is referenced in package.json via patchedDependencies — don't remove or ignore without verifying its purpose.

Project-specific conventions and examples

• Router: Because of the hash-router configuration, when constructing absolute links in a packaged app prefer #/path (README highlights this). For client navigation within components prefer goto() from $app/navigation (see src/routes/+page.svelte).
• Env & API: Use PUBLIC_API_URL (imported from $env/static/public) as the renderer-side base URL. For backend calls that require auth, pass Authorization: Bearer <token> headers (see src/lib/companies.ts).
• IPC surface: The preload file is where to expose limited, safe APIs to the renderer. The main process defines windows and startup behavior — avoid adding unsafe globals to the renderer.
• TypeScript & Svelte: The project uses TypeScript + Svelte 5 — keep code consistent with existing component patterns (script blocks, $: reactivity, svelte:head, named +page routes).

Tests & tooling

• Unit tests: vitest (run pnpm run test:unit). Look at demo.spec.ts and src/routes/page.svelte.test.ts for existing examples.
• E2E: Playwright tests live under e2e/ and are run with pnpm run test:e2e.
• Sync: prepare script runs svelte-kit sync. Running pnpm run check runs svelte-check too; use it when editing routes/type-heavy code.

When making changes, be conservative

• Changing build or packaging behavior affects developers' ability to run the app locally. Prefer edits to renderer code (under src/) unless the user asked to adjust packaging.
• If adding new native electron APIs, update electron/preload.ts to expose a minimal API surface and document it.

Useful snippets / concrete examples

• Navigate programmatically: import { goto } from "$app/navigation"; goto('/logout'); (see src/routes/+page.svelte).
• API client usage: import { api } from 'src/lib/axios'; const res = await api.get('/v1/...');
• Auth redirect fetch: const { uri, callbackKey } = await fetchAuthRedirectUri(apiUrl); (see src/lib/authUri.ts).

If anything is ambiguous or you need additional examples (tests, CI, or a missing preload implementation), ask the maintainer which behavior they want (safe IPC surface, packaging targets, or CI test matrix) before making large changes.

-- End