mirror of
https://github.com/got-feedBack/feedBack.git
synced 2026-07-21 20:31:21 +00:00
9d0bf95716
* refactor(ui)!: remove the classic v2 shell — v3 is the only UI (R3a)
Deletes `static/index.html`, the `/v2` route, and the `FEEDBACK_UI` v2/legacy
opt-out. `/` and `/v3` both serve `static/v3/index.html`, which has been the
default since 0.3.0.
This is step 0 of the core-frontend ES-module migration (R3a). Both shells load
the same `static/app.js`, so every later step of that migration — exposing the
window contract, the `defer` ordering fix, the `type="module"` flips — would
otherwise have to be made and verified twice. Removing the fallback now halves
that surface before any of it is touched.
Incidentally fixes a latent bug in `index()`: its guard read
`if getenv_compat("FEEDBACK_UI") or getenv_compat("FEEDBACK_UI") in ("v2", "legacy")`,
whose left operand is truthy for *any* non-empty value — so `FEEDBACK_UI=v3`
actually served the **v2** shell.
- `static/tailwind.min.css` regenerated: the content globs scanned the deleted
file, so v2-only utility classes are now purged (CI's tailwind-fresh job
rebuilds and diffs it).
- Constitution amended to 1.3.0 — Principle II's frontend file list now names
`static/v3/index.html`.
- Tests: 4 suites read the v2 shell (3 via a constructed `path.join` that a
literal grep misses). Their v2 halves are paired duplicates of v3 tests that
stay, so they are dropped; `alpha_warning_banner` and the capability-registry
script-order test retarget to `static/v3/index.html`.
BREAKING CHANGE: `FEEDBACK_UI=v2` / `=legacy` and the `/v2` route are gone.
Unset the variable and use `/`. No chart, settings, or plugin data changes, and
no plugin API changes — v3 reuses the same engine.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs: drop the stale '/ is v2' plugin-verification guidance (CodeRabbit)
The v3-only rewrite updated the intro paragraphs but left three lines that
still instructed plugin authors to verify in 'both / (v2) and /v3' — now the
same shell. Historical 'in v2 it was X' contrasts are kept: they still orient
authors whose plugins also ship to users on older cores.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
143 lines
5.5 KiB
Markdown
143 lines
5.5 KiB
Markdown
# Plugin styling — the `styles` capability
|
|
|
|
> The **v3 UI** is the only UI — it uses `fb-*` design tokens and a restructured
|
|
> player chrome with a dedicated plugin-control slot. See
|
|
> **[plugin-v3-ui.md](plugin-v3-ui.md)** for the player-chrome contract plugins
|
|
> must follow.
|
|
|
|
FeedBack serves Tailwind as a **prebuilt** stylesheet
|
|
(`static/tailwind.min.css`), never the runtime Play CDN. The CDN's on-the-fly
|
|
JIT rescanned the DOM on the main thread and dropped ~26% of frames with the 3D
|
|
highway running (feedBack-desktop#110). See **constitution Principle II**.
|
|
|
|
A prebuilt stylesheet only contains the classes the build scanner saw in **core
|
|
source at core build time**. That has a consequence for plugins:
|
|
|
|
- Core's build scans bundled plugins on disk, but **a plugin installed at
|
|
runtime** (community / NAS) was never scanned. Its classes — especially
|
|
arbitrary values like `text-[11px]`, `grid-cols-[1fr_auto]`,
|
|
`shadow-[0_0_8px_rgba(0,0,0,.5)]` — are **absent** from the served CSS, so its
|
|
UI renders unstyled.
|
|
|
|
The `styles` capability fixes this: your plugin ships its **own** compiled
|
|
stylesheet and declares it in the manifest. The frontend injects one versioned
|
|
`<link rel="stylesheet">` into `<head>` when your plugin activates, covering both
|
|
your screen and your settings panel.
|
|
|
|
> You only need this if you use Tailwind classes that aren't guaranteed in core —
|
|
> in practice, **any arbitrary-value class** (`w-[37px]`), or a custom class core
|
|
> doesn't ship. If you use only common core utilities (`flex`, `p-4`,
|
|
> `text-gray-300`, `bg-dark-600`), you can omit `styles` and rely on core's CSS.
|
|
|
|
## 1. Declare it in `plugin.json`
|
|
|
|
```json
|
|
{
|
|
"id": "my_plugin",
|
|
"name": "My Plugin",
|
|
"version": "1.2.0",
|
|
"screen": "screen.html",
|
|
"script": "screen.js",
|
|
"styles": "assets/plugin.css"
|
|
}
|
|
```
|
|
|
|
`styles` is a **plugin-root-relative path that must live under `assets/`** (like
|
|
`screen`/`script`/`routes` are root-relative). It serves through the sandboxed
|
|
`/api/plugins/<id>/assets/...` route, so the file must be at
|
|
`<plugin>/assets/plugin.css`. The injected `<link>` is cache-busted with
|
|
`?v=<version>`, so **bump your manifest `version`** whenever you rebuild the CSS,
|
|
or browsers may serve a stale copy within a session.
|
|
|
|
## 2. Build the stylesheet — utilities only, `preflight: false`
|
|
|
|
Core already ships Tailwind's base reset (preflight) once. Your plugin must
|
|
**not** re-apply it, or it would double the reset and fight core's styles. Build
|
|
with `corePlugins: { preflight: false }` so your sheet emits **only the utility
|
|
classes your files use**.
|
|
|
|
`tailwind.config.js` (in your plugin repo):
|
|
|
|
```js
|
|
/** Plugin stylesheet build — utilities only, scanned from this plugin's files.
|
|
* Regenerate assets/plugin.css with: bash build-tailwind.sh */
|
|
module.exports = {
|
|
corePlugins: { preflight: false }, // core owns the single base reset
|
|
content: [
|
|
'./screen.js',
|
|
'./settings.html',
|
|
'./screen.html',
|
|
// add any other file that carries Tailwind classes (e.g. './tour.json')
|
|
],
|
|
theme: {
|
|
extend: {
|
|
// Re-declare any core theme tokens you reference so they compile here.
|
|
colors: {
|
|
dark: { 900: '#050508', 800: '#0a0a12', 700: '#10101e', 600: '#181830', 500: '#1e1e3a' },
|
|
accent: { DEFAULT: '#4080e0', light: '#60a0ff', dark: '#2060b0' },
|
|
gold: '#e8c040',
|
|
},
|
|
fontFamily: { display: ['"Inter"', 'system-ui', 'sans-serif'] },
|
|
},
|
|
},
|
|
// Mirror only the dynamically-built classes your code generates at runtime
|
|
// (Tailwind can't see them textually). Drop this if you have none.
|
|
safelist: [
|
|
{ pattern: /^(bg|text|border)-(dark|accent)(-.+)?$/ },
|
|
],
|
|
plugins: [],
|
|
};
|
|
```
|
|
|
|
Input CSS — **`@tailwind utilities;` only** (no `@tailwind base`, that's the
|
|
preflight you're disabling):
|
|
|
|
`_plugin.src.css`:
|
|
|
|
```css
|
|
@tailwind utilities;
|
|
```
|
|
|
|
Build script `build-tailwind.sh` (run at your plugin's release time — the output
|
|
is committed; end users never build):
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
set -euo pipefail
|
|
cd "$(dirname "$0")"
|
|
# Pin the same Tailwind 3.x core uses so output stays diff-stable.
|
|
exec npx -y tailwindcss@3.4.19 \
|
|
-c tailwind.config.js \
|
|
-i _plugin.src.css \
|
|
-o assets/plugin.css \
|
|
--minify
|
|
```
|
|
|
|
```bash
|
|
bash build-tailwind.sh # writes assets/plugin.css — commit it
|
|
```
|
|
|
|
## 3. Rules (inherited from the constitution)
|
|
|
|
- **No Play CDN, no runtime CSS JIT** — anywhere, ever. Same rule that binds core.
|
|
- **`preflight: false`** — utilities only; core ships the one base reset.
|
|
- **`styles` under `assets/`** — it serves through the sandboxed asset route;
|
|
`..`, absolute paths, and NUL bytes are rejected by `safe_join`.
|
|
- **Bump `version` on every CSS rebuild** so the `?v=` cache-buster fetches fresh.
|
|
- Plugins without `styles` are unaffected and inject no `<link>`.
|
|
|
|
## How it works (for reference)
|
|
|
|
- The loader derives a manifest-only `has_styles` boolean and passes the `styles`
|
|
path through to `/api/plugins` — no plugin code is imported
|
|
(`plugins/__init__.py::_nav_entry`).
|
|
- The frontend (`static/app.js::_injectPluginStyles`) injects one
|
|
`<link rel="stylesheet" data-plugin-id data-plugin-version
|
|
href="/api/plugins/<id>/assets/plugin.css?v=<version>">` (the `styles` value —
|
|
e.g. `assets/plugin.css` — appended to `/api/plugins/<id>/`) into `<head>`, **before** the
|
|
screen markup so styles are present on first paint. It's deduped by version: a
|
|
plugin upgrade swaps the old `<link>` for the new one; re-activation never piles
|
|
up duplicates.
|
|
- The stylesheet is served by the existing
|
|
`/api/plugins/<id>/assets/<path>` route as `text/css`.
|