Code reference detail
onboarding-state.ts
packages/extension/src/extension/onboarding-state.ts
| Idea | Status | Tags | Summary | Katz |
|---|---|---|---|---|
| persistence_tiers | done | Three persistence tiers — pick the shallowest that matches lifetime: 1. `acquireVsCodeApi().getState` / `setState` — ephemeral webview session ( pane expand / heights, active tab ). 2. `ExtensionContext.workspaceState` — durable UI prefs shared across reloads ( graph / table UI keys under `reqlan.ideasSummary.*`, optionally per-base ). Normalize + default on read ( `normalizeGraphUiState` / table defaults ); never trust raw JSON shape. 3. `ExtensionContext.globalState` — install / user-level flags ( e. g. onboarding ), not pane view-models. Debounce persist posts ( ~ 200 – 250 ms ) when UI controls churn. Related: [webview_app_state]. | 0.050 | |
| scope | TypeScript package standards for `packages/extension` ( npm `reqlan-extension` ), especially UI state. Complements [development_core.rust_mindset] and [extension_architecture.state_machine_mindset]. Webview inventory: [webview_doc.webview]. Package role: [core_architecture.extension_package]. | 0.040 | ||
| activation | VS Code loads the extension host entry at ["../../../packages/extension/src/extension/main.ts"] when an activation event in ["../../../packages/extension/package.json"] matches. The exported `activate(context)` function is the single activation entry point for [scope.vscode_extension]. Install-time and first-run sequencing across extension vs base layers: ["./installation.rq".installation_sequencing]. Startup failure diagnosis, first-paint sequencing, bundle splitting, and development-host lessons: ["./startup-performance.rq"]. | 0.064 | ||
| onboarding_check | Post-install onboarding is checked on every activation, not via a dedicated install event. ["./onboarding/page-thanks-for-installing.rq".installation_event_trigger] is satisfied because `activate` always schedules ["../../../packages/extension/src/extension/open-thanks-for-installing.ts"] after the activity-bar paint gate or 400 ms ( ["./startup-performance.rq".webview_claim_race] ). The check reads global state key `onboarding` via ["../../../packages/extension/src/extension/onboarding-state.ts"]: - `onboardingMessageShown` — when false, open the onboarding webview panel via ["../../../packages/extension/src/extension/onboarding-panel.ts"]. - `lastVersion` — updated each activation after the message has been shown so future releases can detect extension updates. The call is fire-and-forget; errors are logged and do not fail activation. Command-palette Show Onboarding remains immediate. | 0.087 | ||
| installation_event | done | On installation of the extension a webview should be opened showing: - A welcome message - Resolved links to site, github, docs etc. ( not template placeholders ) - A syntax-highlighted example `.rq` with real URLs ( clickable ) from ["../../../../packages/extension/templates/thanks-for-installing.template.rq"] after placeholder substitution - A control to open that example as an untitled `.rq` editor beside the webview - Short tips for the activity bar and `@reqlan` chat - A thanks to sponsors Place in overall install sequencing: ["../installation.rq".welcome_webview_install] / ["../installation.rq".extension_installation]. Implemented as a Svelte webview under ["../../../../packages/extension/webviews/onboarding"] bundled to ["../../../../packages/extension/media/webviews/onboarding"] and opened once on first activation by ["../../../../packages/extension/src/extension/open-thanks-for-installing.ts"] via ["../../../../packages/extension/src/extension/onboarding-panel.ts"]. Resource links and template values are resolved at runtime from [phonebook_reqs.phonebook] through ["../../../../packages/extension/src/shared/phonebook.ts"] and posted to the webview; the example block imports ["../../../../packages/extension/templates/thanks-for-installing.template.rq"] via Vite `?raw` and substitutes `{{…}}` placeholders before display. Highlighting uses the onboarding tokenizer in ["../../../../packages/extension/webviews/onboarding/lib/rq-highlight.ts"]. The source template still uses placeholders such as { { SITE_URL } }; those matching braces are body prose per ["../../../language/syntax-edge-cases.rq".nested_curly_braces] and must parse without errors. Activation state is stored in extension global state key `onboarding` with `onboardingMessageShown` and `lastVersion` per ["../../../../packages/extension/src/extension/onboarding-state.ts"]. VS Code persists `globalState` in the extension global storage directory ( `globalStorage/reqlan.reqlan-extension/state.vscdb` under the editor user data folder ). | 0.141 | |
| onboarding_state | Onboarding persistence uses VS Code `ExtensionContext.globalState` under key `onboarding` in ["../../../../packages/extension/src/extension/onboarding-state.ts"]. Fields: `onboardingMessageShown`, `lastVersion`. | 0.057 |
Reference labels
"../../../../packages/extension/src/extension/onboarding-state.ts", "../../../packages/extension/src/extension/onboarding-state.ts", "../../packages/extension/src/extension/onboarding-state.ts", ../../../../packages/extension/src/extension/onboarding-state.ts, ../../../packages/extension/src/extension/onboarding-state.ts, ../../packages/extension/src/extension/onboarding-state.ts