Update docs

This commit is contained in:
raucao committed 2026-10-08 18:32:16 +02:00
1 parent 9009a349f3
commit e8a8adf846
2 files changed
+22 -9

No files matched your search

+14 -2
View File
@@ -2,7 +2,7 @@
## Overview
**Dashtab** is a client-side new-tab dashboard built with Ember.js, Vite, and Tailwind CSS. It features widgets (clock, greeting), customizable wallpapers, and third-party integrations (e.g., Discourse).
**Dashtab** is a client-side new-tab dashboard distributed as a Manifest V3 browser extension and built with Ember.js, Vite, and Tailwind CSS. It features widgets (clock, greeting), customizable wallpapers, and third-party integrations (e.g., Discourse).
## Tech Stack
@@ -12,6 +12,7 @@
- **Storage**: `localforage` (IndexedDB / LocalStorage)
- **Cryptography**: Web Crypto API & `node-forge`
- **Testing**: QUnit, `@ember/test-helpers`, `qunit-dom`, `testem`
- **Distribution**: Manifest V3 browser extension (Chrome/Firefox); the web build is dev-only
- **Package Manager**: `pnpm`
## Code Layout
@@ -21,14 +22,25 @@
- `app/routes/` & `app/templates/`: Route definitions and `.gjs` templates.
- `app/styles/`: Application styles and Tailwind entry points.
- `doc/`: Protocol notes and integration specifications.
- `extension/`: Chrome/Firefox MV3 manifests; `extension/build/` is generated output.
- `tests/`: QUnit tests (`tests/integration/` for `.gjs` components, `tests/unit/` for services).
## Commands
- `pnpm start`: Start local development server (`http://localhost:4200`).
- `pnpm start`: Run the app in the browser for development only (`http://localhost:4200`).
- `pnpm test`: Build and run the test suite via Testem.
- `pnpm lint`: Run all linters (ESLint, Prettier, stylelint, template-lint).
- `pnpm lint:fix`: Auto-fix linting and formatting issues.
- `pnpm ext:dev`: Watch-build the Firefox extension and launch it via `web-ext`.
- `pnpm ext:build:chrome` / `pnpm ext:build:firefox`: Package the extension.
- `pnpm ext:lint`: Lint the packaged extension with `web-ext`.
## Browser Extension
Dashtab is a Manifest V3 browser extension that overrides the new tab. It can also run as a plain web app via `pnpm start`, but that path exists only for development convenience. `vite.config.mjs` switches to relative asset paths and copies the target manifest into `extension/build/` when `DASHTAB_EXT=1`, with `DASHTAB_EXT_TARGET` selecting `chrome` or `firefox`. Never edit `extension/build/` by hand.
- **Manifests**: `extension/manifest.chrome.json` and `extension/manifest.firefox.json`. Extension ids are pinned (Chrome `key`, Firefox `browser_specific_settings.gecko.id`) so `identity.getRedirectURL()` stays stable.
- **Auth transport**: `app/auth/transport.js` feature-detects the identity API (`app/utils/extension.js`). The extension uses `identity.launchWebAuthFlow` + `getRedirectURL`; the dev-server build (no identity API) falls back to a full-page redirect to the provider callback. See `doc/extension_auth.md`.
## Key Conventions
+8 -7
View File
@@ -1,4 +1,4 @@
# Integration authorization: web vs. extension
# Integration authorization: extension vs. dev server
Dashtab connects to integrations through a small authorization layer
(`app/auth/`):
@@ -9,14 +9,15 @@ Dashtab connects to integrations through a small authorization layer
without touching the transport.
- **Transport** (`app/auth/transport.js`) decides how the browser gets to the
provider:
- **Web app** → full-page redirect to `${origin}${provider.webCallbackPath}`
(e.g. `/auth/discourse/callback`).
- **Browser extension** → `identity.getRedirectURL(providerId)` plus
`identity.launchWebAuthFlow`, which opens a browser-managed auth window and
intercepts the redirect to a browser-owned domain.
- **Development server** (no identity API) → full-page redirect to
`${origin}${provider.webCallbackPath}` (e.g. `/auth/discourse/callback`).
The choice is made at runtime by feature-detecting the identity API, so the same
build works as a normal site and as an extension.
Dashtab ships as a browser extension; the dev-server path exists only for
development convenience. The choice is made at runtime by feature-detecting the
identity API, so the same build works in both contexts.
## Forum configuration
@@ -25,8 +26,8 @@ Discourse only accepts a redirect that matches the
`https://api.discourse.org/api/auth_redirect|discourse://auth_redirect`, so an
admin must add the redirects Dashtab uses:
- **Web app** — the deployed origin plus callback path, e.g.
`https://dashtab.example.com/auth/discourse/callback`.
- **Development server** — the dev origin plus callback path, e.g.
`http://localhost:4200/auth/discourse/callback`.
- **Chrome / Chromium extension** — `https://<extension-id>.chromiumapp.org/discourse`,
or the wildcard `https://*.chromiumapp.org/*`.
- **Firefox extension** — `https://<host>.extensions.allizom.org/discourse`