feat(desktop): custom base URL (proxy/relay) support + handoff notes

Onboarding now exposes an "Advanced — custom base URL" input under the
API key field, so users on third-party gateways or self-hosted relays
can validate against and route generation through their own endpoint.

- shared/config: add `BaseUrlRef` + `Config.baseUrls` + `OnboardingState.baseUrl`
- main/onboarding-ipc: persist baseUrl per provider in config.toml; expose
  `getBaseUrlForProvider()` for the generate IPC
- main/index: thread stored baseUrl into `core.generate()` (renderer-supplied
  baseUrl in the IPC payload still takes precedence if present)
- preload: add `baseUrl` to saveKey signature
- renderer/onboarding/PasteKey: collapsible details with URL input,
  validation re-runs on baseUrl change, plumbed through `onValidated`
- renderer/onboarding/index: forward baseUrl to saveKey

Plus: docs/HANDOFF.md — kickoff guide for the second contributor (read order,
open PRs, suggested next 5 things, gotchas, demo verification checklist).

All checks green.

Signed-off-by: hqhq1025 <1506751656@qq.com>

Author: hqhq1025

apps/desktop/src/main/index.ts

@@ -6,7 +6,12 @@ import { BRAND, CodesignError, GeneratePayload } from '@open-codesign/shared';
 import { BrowserWindow, app, ipcMain, shell } from 'electron';
 import { autoUpdater } from 'electron-updater';
 import { registerExporterIpc } from './exporter-ipc';
-import { getApiKeyForProvider, loadConfigOnBoot, registerOnboardingIpc } from './onboarding-ipc';
+import {
+  getApiKeyForProvider,
+  getBaseUrlForProvider,
+  loadConfigOnBoot,
+  registerOnboardingIpc,
+} from './onboarding-ipc';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -55,12 +60,14 @@ function registerIpcHandlers(): void {
   ipcMain.handle('codesign:generate', async (_e, raw: unknown) => {
     const payload = GeneratePayload.parse(raw);
     const apiKey = getApiKeyForProvider(payload.model.provider);
+    const storedBaseUrl = getBaseUrlForProvider(payload.model.provider);
+    const baseUrl = payload.baseUrl ?? storedBaseUrl;
     return generate({
       prompt: payload.prompt,
       history: payload.history,
       model: payload.model,
       apiKey,
-      ...(payload.baseUrl !== undefined ? { baseUrl: payload.baseUrl } : {}),
+      ...(baseUrl !== undefined ? { baseUrl } : {}),
     });
   });
 }

apps/desktop/src/main/onboarding-ipc.ts

@@ -15,6 +15,7 @@ interface SaveKeyInput {
   apiKey: string;
   modelPrimary: string;
   modelFast: string;
+  baseUrl?: string;
 }
 
 interface ValidateKeyInput {
@@ -53,22 +54,36 @@ export function getApiKeyForProvider(provider: string): string {
   return decryptSecret(ref.ciphertext);
 }
 
+export function getBaseUrlForProvider(provider: string): string | undefined {
+  const cfg = getCachedConfig();
+  if (cfg === null) return undefined;
+  const ref = cfg.baseUrls?.[provider as keyof typeof cfg.baseUrls];
+  return ref?.baseUrl;
+}
+
 function toState(cfg: Config | null): OnboardingState {
   if (cfg === null) {
-    return { hasKey: false, provider: null, modelPrimary: null, modelFast: null };
+    return { hasKey: false, provider: null, modelPrimary: null, modelFast: null, baseUrl: null };
   }
   if (!isSupportedOnboardingProvider(cfg.provider)) {
-    return { hasKey: false, provider: null, modelPrimary: null, modelFast: null };
+    return { hasKey: false, provider: null, modelPrimary: null, modelFast: null, baseUrl: null };
   }
   const ref = cfg.secrets[cfg.provider];
   if (ref === undefined) {
-    return { hasKey: false, provider: cfg.provider, modelPrimary: null, modelFast: null };
+    return {
+      hasKey: false,
+      provider: cfg.provider,
+      modelPrimary: null,
+      modelFast: null,
+      baseUrl: null,
+    };
   }
   return {
     hasKey: true,
     provider: cfg.provider,
     modelPrimary: cfg.modelPrimary,
     modelFast: cfg.modelFast,
+    baseUrl: cfg.baseUrls?.[cfg.provider]?.baseUrl ?? null,
   };
 }
 
@@ -81,6 +96,7 @@ function parseSaveKey(raw: unknown): SaveKeyInput {
   const apiKey = r['apiKey'];
   const modelPrimary = r['modelPrimary'];
   const modelFast = r['modelFast'];
+  const baseUrl = r['baseUrl'];
   if (typeof provider !== 'string' || !isSupportedOnboardingProvider(provider)) {
     throw new CodesignError(
       `Provider "${String(provider)}" is not supported in v0.1.`,
@@ -96,7 +112,16 @@ function parseSaveKey(raw: unknown): SaveKeyInput {
   if (typeof modelFast !== 'string' || modelFast.trim().length === 0) {
     throw new CodesignError('modelFast must be a non-empty string', 'IPC_BAD_INPUT');
   }
-  return { provider, apiKey, modelPrimary, modelFast };
+  const out: SaveKeyInput = { provider, apiKey, modelPrimary, modelFast };
+  if (typeof baseUrl === 'string' && baseUrl.trim().length > 0) {
+    try {
+      new URL(baseUrl);
+    } catch {
+      throw new CodesignError(`baseUrl "${baseUrl}" is not a valid URL`, 'IPC_BAD_INPUT');
+    }
+    out.baseUrl = baseUrl.trim();
+  }
+  return out;
 }
 
 function parseValidateKey(raw: unknown): ValidateKeyInput {
@@ -135,6 +160,12 @@ export function registerOnboardingIpc(): void {
   ipcMain.handle('onboarding:save-key', async (_e, raw: unknown): Promise<OnboardingState> => {
     const input = parseSaveKey(raw);
     const ciphertext = encryptSecret(input.apiKey);
+    const nextBaseUrls = { ...(cachedConfig?.baseUrls ?? {}) };
+    if (input.baseUrl !== undefined) {
+      nextBaseUrls[input.provider] = { baseUrl: input.baseUrl };
+    } else {
+      delete nextBaseUrls[input.provider];
+    }
     const next: Config = {
       version: 1,
       provider: input.provider,
@@ -144,6 +175,7 @@ export function registerOnboardingIpc(): void {
         ...(cachedConfig?.secrets ?? {}),
         [input.provider]: { ciphertext },
       },
+      baseUrls: nextBaseUrls,
     };
     await writeConfig(next);
     cachedConfig = next;

apps/desktop/src/preload/index.ts

@@ -57,6 +57,7 @@ const api = {
       apiKey: string;
       modelPrimary: string;
       modelFast: string;
+      baseUrl?: string;
     }) => ipcRenderer.invoke('onboarding:save-key', input) as Promise<OnboardingState>,
     skip: () => ipcRenderer.invoke('onboarding:skip') as Promise<OnboardingState>,
   },

apps/desktop/src/renderer/src/onboarding/PasteKey.tsx

@@ -18,12 +18,18 @@ type ValidationState =
   | { kind: 'error'; code: ValidateKeyError['code'] | 'unsupported'; message: string };
 
 interface PasteKeyProps {
-  onValidated: (provider: SupportedOnboardingProvider, apiKey: string) => void;
+  onValidated: (
+    provider: SupportedOnboardingProvider,
+    apiKey: string,
+    baseUrl: string | null,
+  ) => void;
   onBack: () => void;
 }
 
 export function PasteKey({ onValidated, onBack }: PasteKeyProps) {
   const [apiKey, setApiKey] = useState('');
+  const [baseUrl, setBaseUrl] = useState('');
+  const [advancedOpen, setAdvancedOpen] = useState(false);
   const [provider, setProvider] = useState<SupportedOnboardingProvider | null>(null);
   const [state, setState] = useState<ValidationState>({ kind: 'idle' });
   const reqIdRef = useRef(0);
@@ -34,6 +40,7 @@ export function PasteKey({ onValidated, onBack }: PasteKeyProps) {
   }, []);
 
   const trimmed = apiKey.trim();
+  const trimmedBaseUrl = baseUrl.trim();
 
   useEffect(() => {
     if (trimmed.length === 0) {
@@ -95,6 +102,7 @@ export function PasteKey({ onValidated, onBack }: PasteKeyProps) {
         result = await window.codesign.onboarding.validateKey({
           provider: detected,
           apiKey: trimmed,
+          ...(trimmedBaseUrl.length > 0 ? { baseUrl: trimmedBaseUrl } : {}),
         });
       } catch (err) {
         if (reqId !== reqIdRef.current) return;
@@ -115,7 +123,7 @@ export function PasteKey({ onValidated, onBack }: PasteKeyProps) {
     }, VALIDATE_DEBOUNCE_MS);
 
     return () => window.clearTimeout(handle);
-  }, [trimmed]);
+  }, [trimmed, trimmedBaseUrl]);
 
   const helpUrl = useMemo(() => {
     if (provider === null) return null;
@@ -124,7 +132,7 @@ export function PasteKey({ onValidated, onBack }: PasteKeyProps) {
 
   function handleContinue() {
     if (state.kind !== 'ok' || provider === null) return;
-    onValidated(provider, trimmed);
+    onValidated(provider, trimmed, trimmedBaseUrl.length > 0 ? trimmedBaseUrl : null);
   }
 
   return (
@@ -162,6 +170,41 @@ export function PasteKey({ onValidated, onBack }: PasteKeyProps) {
 
       <StatusLine provider={provider} state={state} helpUrl={helpUrl} />
 
+      <details
+        open={advancedOpen}
+        onToggle={(e) => setAdvancedOpen((e.currentTarget as HTMLDetailsElement).open)}
+        className="text-[13px] text-[var(--color-text-secondary)]"
+      >
+        <summary
+          className="cursor-pointer select-none text-[12px] text-[var(--color-text-muted)] hover:text-[var(--color-text-secondary)] transition-colors"
+          style={{ fontFamily: 'var(--font-mono)' }}
+        >
+          Advanced — custom base URL (proxy / relay)
+        </summary>
+        <label className="flex flex-col gap-2 mt-3">
+          <span
+            className="text-[10px] uppercase tracking-[0.08em] text-[var(--color-text-muted)] font-medium"
+            style={{ fontFamily: 'var(--font-mono)' }}
+          >
+            Base URL
+          </span>
+          <input
+            type="url"
+            value={baseUrl}
+            onChange={(e) => setBaseUrl(e.target.value)}
+            placeholder="https://your-proxy.example.com/v1"
+            spellCheck={false}
+            style={{ fontFamily: 'var(--font-mono)' }}
+            className="w-full h-[40px] px-3 rounded-[var(--radius-md)] bg-[var(--color-surface)] border border-[var(--color-border)] text-[13px] text-[var(--color-text-primary)] placeholder:text-[var(--color-text-muted)] focus:outline-none focus:border-[var(--color-accent)] focus:shadow-[0_0_0_3px_var(--color-focus-ring)] transition-[box-shadow,border-color] duration-150 ease-[cubic-bezier(0.16,1,0.3,1)]"
+          />
+          <span className="text-[12px] text-[var(--color-text-muted)] leading-[1.5]">
+            Override the default endpoint for your provider. Useful for relay services
+            (e.g. third-party AI gateways) and self-hosted proxies. Leave empty for the
+            official endpoint.
+          </span>
+        </label>
+      </details>
+
       <div className="flex justify-between gap-2 pt-2">
         <Button type="button" variant="ghost" onClick={onBack}>
           Back

apps/desktop/src/renderer/src/onboarding/index.tsx

@@ -13,12 +13,14 @@ export function Onboarding() {
   const [step, setStep] = useState<Step>('welcome');
   const [provider, setProvider] = useState<SupportedOnboardingProvider | null>(null);
   const [apiKey, setApiKey] = useState('');
+  const [baseUrl, setBaseUrl] = useState<string | null>(null);
   const [saving, setSaving] = useState(false);
   const [errorMessage, setErrorMessage] = useState<string | null>(null);
 
-  function handleValidated(p: SupportedOnboardingProvider, key: string) {
+  function handleValidated(p: SupportedOnboardingProvider, key: string, url: string | null) {
     setProvider(p);
     setApiKey(key);
+    setBaseUrl(url);
     setStep('model');
   }
 
@@ -36,6 +38,7 @@ export function Onboarding() {
         apiKey,
         modelPrimary,
         modelFast,
+        ...(baseUrl !== null ? { baseUrl } : {}),
       });
       completeOnboarding(next);
     } catch (err) {

docs/HANDOFF.md

@@ -0,0 +1,139 @@
+# Handoff Notes — open-codesign
+
+For the second contributor joining the project. Goal: pick up where main was left, ship the remaining v0.1 quality bar, then move to v0.2 features.
+
+Last updated: 2026-04-18 by hqhq1025.
+
+---
+
+## 0. First 30 minutes
+
+```bash
+git clone git@github.com:OpenCoworkAI/open-codesign.git
+cd open-codesign
+pnpm install
+pnpm --filter @open-codesign/desktop dev
+```
+
+Open Settings on the welcome screen, paste a real API key (Anthropic / OpenAI / OpenRouter), pick models, then try a starter prompt. If you see a generated HTML mockup in the right pane and can export it via the toolbar, you have a working baseline.
+
+If you use a proxy / relay (中转站), expand **Advanced — custom base URL** under the API key field and paste the relay endpoint (must be a full URL including `/v1`).
+
+---
+
+## 1. Read first
+
+Read these in order before changing anything substantial:
+
+1. [`docs/CONSENSUS.md`](./docs/CONSENSUS.md) — single source of truth for decisions, current state, gotchas
+2. [`CLAUDE.md`](./CLAUDE.md) — repo conventions
+3. [`docs/PRINCIPLES.md`](./docs/PRINCIPLES.md) — CI-enforced engineering rules (especially §5b)
+4. [`docs/VISION.md`](./docs/VISION.md) — what the product is and isn't
+5. [`docs/COLLABORATION.md`](./docs/COLLABORATION.md) — workflow (worktrees, PRs, squash-merge cadence)
+6. [`docs/RESEARCH_QUEUE.md`](./docs/RESEARCH_QUEUE.md) — the 9 research reports under `docs/research/` and what each one decided
+
+---
+
+## 2. State of the union
+
+**On `main` and working today:**
+- Onboarding wizard (3 steps) with `safeStorage`-encrypted keychain
+- Custom base URL (proxy / relay) input under "Advanced" in the paste-key step
+- 4 starter demo prompts (`packages/templates/src/index.ts`)
+- HTML generation via `@mariozechner/pi-ai` → streaming artifact parser → iframe preview
+- HTML export via `dialog.showSaveDialog`
+- Marketing site (VitePress) at `website/`
+- Tokenized design system in `packages/ui/src/tokens.css` (Wordmark, EmptyMark, full text/leading/tracking/space/motion scales)
+
+**Open PRs that need conflict resolution before they merge:**
+
+| # | Branch | What it adds | Conflicts on |
+|---|---|---|---|
+| 2 | `wt/i18n` | `packages/i18n` (en + zh-CN), locale IPC, per-locale demo prompts, system-locale auto-detect | `App.tsx`, `store.ts`, `main/index.ts`, `preload/index.ts` |
+| 3 | `wt/preview-ux` | Settings overlay (4 tabs), command palette (Cmd+K), Toast, Sidebar/PreviewPane/TopBar extraction, theme toggle | `App.tsx`, `store.ts` |
+| 6 | `wt/reliability` | Error boundaries, AbortController cancellation, `completeWithRetry` with 429 handling, iframe error reporting | `App.tsx`, `store.ts`, `core/index.ts`, `providers/index.ts` |
+| 7 | `wt/exporters` | Real PDF (puppeteer-core + system Chrome), real PPTX (pptxgenjs + CJK fix), real ZIP (zip-lib) | `package.json`, `PreviewToolbar.tsx` |
+
+These branches are valuable but the App.tsx/store.ts conflicts are 4-way (we have onboarding + first-demo + UIUX iteration on main now). Resolution strategy options:
+
+- **Option A** (recommended): cherry-pick the new files (those are conflict-free) and rewrite the App.tsx/store.ts integration by hand on top of current main.
+- **Option B**: rebase each branch carefully and resolve the merge markers manually.
+- **Option C**: close the PRs and reimplement the missing features as fresh small PRs against the current main.
+
+I tried option B for #2 and hit four-way merges in store.ts. Option A is what I would do next.
+
+---
+
+## 3. Suggested next 5 things to ship (in order)
+
+1. **Resolve the 4 open PRs** (or reimplement their features). Highest-value pieces, in priority order:
+   - `wt/exporters` real PDF + ZIP (PPTX is tier 2 and can wait)
+   - `wt/reliability` error boundaries + AbortController + retry
+   - `wt/i18n` zh-CN end-to-end (most users will want this)
+   - `wt/preview-ux` settings overlay + command palette + theme toggle
+2. **Streaming generation** (Tier 2 of `packages/core`) — currently `core.generate()` blocks until the full response arrives. Switch to `streamArtifacts()` so tokens appear as they arrive and the UI can show ≤200 ms feedback. See `docs/research/05-pi-ai-boundary.md` and `docs/research/07-first-5-minutes.md`.
+3. **Inline comment loop** — click an element in the preview, write a comment, AI rewrites that region. Mechanism is decided in `docs/research/02-inline-comment-and-sliders.md`. Estimated 3-5 days.
+4. **AI-generated custom sliders** — model emits `design_params` JSON; frontend renders sliders bound to CSS variables; drag mutates CSS without re-running the model. Same research report.
+5. **UIUX iteration v2** — push 7.5/10 → 9/10. Focus areas: chat history list, generation-in-progress states (skeleton, streaming token highlight), settings drawer. The first iteration is in commits `49985a9` ... `a11f416`.
+
+---
+
+## 4. Workflow expectations
+
+- **Branch naming**: `feat/<slug>` for features, `fix/<slug>` for bugfixes, `wt/<slug>` for worktree-isolated agent work.
+- **DCO sign-off** required (`git commit -s -m "..."`). CI's `DCO check` step blocks otherwise.
+- **Conventional Commits** (commitlint enforces this).
+- **Squash-merge** to main as soon as CI is green. Pre-alpha solo workflow does not require external review; switch back to PR review when we go public.
+- **No new prod deps** without justification (size + license + alternatives) in the PR body.
+- **Run before push**: `pnpm install && pnpm -r typecheck && pnpm lint && pnpm -r test`
+- **All visible UI** uses `var(--color-*)` / `var(--text-*)` / `var(--space-*)` tokens. Never hardcode hex / px / fonts.
+
+---
+
+## 5. Things I would have done if I had another hour
+
+- Properly resolve the 4 open PRs into main (the file boundaries are fine, the merge effort is real).
+- Add `OPENAI_API_KEY` + `OPENAI_BASE_URL` repo secrets and set `vars.CODEX_BOT_ENABLED=true` so the Codex bot starts reviewing PRs.
+- Wire the bundle-size CI gate (`size-limit` step in `.github/workflows/ci.yml`) before any release.
+- Write integration tests for the onboarding flow (Playwright against the built app).
+- Acquire a real exported HTML sample from Claude Design Pro and reverse-engineer it — the artifact schema in `packages/shared` is still tentative.
+
+---
+
+## 6. Things to be careful about
+
+These have bitten me already:
+
+- **Preload path** is `out/preload/index.mjs` (NOT `.js`). Electron 33+ supports it natively but the main process must reference `.mjs`. Already fixed in `46e8c8d`.
+- **electron-vite + lockfile drift**: after a fresh `pnpm install`, you sometimes need `pnpm install` AGAIN if you switched between worktrees. The Re-optimizing dependencies message in the dev log is the signal.
+- **Squash-merge can leave conflict markers** if a rebase was partially completed. Always grep for `<<<<<<<` after a squash-merge: `grep -rn "<<<<<<<" apps/ packages/`.
+- **Tailwind v4 length tokens**: `text-[var(--text-xl)]` is silently treated as ambiguous. Use `text-[length:var(--text-xl)]` or register tokens via `@theme`.
+- **Biome `useLiteralKeys` is OFF** because it conflicts with TS `noPropertyAccessFromIndexSignature`. Use bracket notation for env / record / config access (`process.env['FOO']`, not `process.env.FOO`).
+- **pi-ai is single-maintainer** (`badlogic/pi-mono`, ~36k stars, bus-factor 1). Pin the version. Don't fork. Wrap missing features in `packages/providers`.
+- **Electron 41.x is excluded** in `renovate.json` due to a cross-origin isolation regression. Don't bypass.
+
+---
+
+## 7. Pilot demo verification checklist
+
+After any non-trivial change, walk this list to confirm nothing regressed:
+
+- [ ] `pnpm install && pnpm -r typecheck && pnpm lint && pnpm -r test` all green
+- [ ] `pnpm --filter @open-codesign/desktop dev` opens an Electron window without errors in `/tmp/codesign-dev.log`
+- [ ] First launch shows the Welcome step of the onboarding wizard
+- [ ] Pasting a real `sk-ant-...` key auto-detects Anthropic and validates within 500 ms
+- [ ] Expanding "Advanced — custom base URL" and pasting a proxy URL also validates against the proxy
+- [ ] After completing onboarding, the chat shell with 4 starter chips appears
+- [ ] Clicking any chip + Send produces an HTML artifact in the right pane within ~30 s
+- [ ] Click Export ▾ → HTML → save → opens correctly in the browser
+- [ ] PDF / PPTX / ZIP show "Coming in Phase 2" until #7 lands
+- [ ] Restart the app — onboarding is skipped and the chat shell loads with the saved provider
+
+---
+
+## 8. How to reach me
+
+- GitHub @hqhq1025 — open an Issue, tag me on a PR, or comment on a Discussion
+- For architecture / direction questions, open a GitHub Discussion first; don't change the locked decisions in `docs/VISION.md` without that
+
+Happy hacking. Build the simplest thing that works, then iterate. Do not skip the research-first step — every locked decision in this repo has a report under `docs/research/` explaining why.