mirror of https://github.com/got-feedBack/feedBack.git synced 2026-07-21 20:31:21 +00:00

refactor(ui)!: remove the classic v2 shell — v3 is the only UI (R3a) (#871 )

* 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>

2026-07-11 16:33:03 +02:00

5.5 KiB

Raw Blame History

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 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`

{
  "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):

/** 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:

@tailwind utilities;

Build script build-tailwind.sh (run at your plugin's release time — the output is committed; end users never build):

#!/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 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.

5.5 KiB Raw Blame History

Plugin styling — the styles capability

1. Declare it in plugin.json

2. Build the stylesheet — utilities only, preflight: false