elowen-plugin-ui-kit 0.1.0 → 0.5.0

package/build.d.ts

@@ -12,3 +12,15 @@ export interface BuildPluginUiBundleOptions {
 
 /** Bundle `entry` into the ESM file at `outfile`. Throws on any build error. */
 export declare function buildPluginUiBundle(options: BuildPluginUiBundleOptions): Promise<void>;
+
+export interface BuildPluginUiCssOptions {
+  /** The FINISHED bundle to scan for utility classes (the output of `buildPluginUiBundle`). */
+  bundle: string;
+  /** Where to write the compiled stylesheet (the plugin manifest's `web.css`). */
+  outfile: string;
+}
+
+/** Compile the plugin's own stylesheet from its built bundle. Utilities only, no preflight, no prefix,
+ *  and the host's design tokens are referenced (`var(--token, fallback)`) rather than inlined, so the
+ *  plugin follows the host's skin. Resolves to the emitted CSS. */
+export declare function buildPluginUiCss(options: BuildPluginUiCssOptions): Promise<string>;

package/build.js

@@ -3,10 +3,16 @@
  *  emits a plain `index.js`). React imports are aliased to shims that read the HOST's instance from
  *  `window.ElowenUiRuntime`, so a bundle can never ship a second React (two copies break hooks). */
 import { build } from 'esbuild';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const shim = (name) => fileURLToPath(new URL(`./shims/${name}.cjs`, import.meta.url));
 
+/** This package's own directory — the resolution base for the Tailwind compile below, so
+ *  `tailwindcss/theme.css` resolves against the kit's dependencies rather than the plugin's. */
+const kitDir = fileURLToPath(new URL('.', import.meta.url));
+
 /** Bundle `entry` into the ESM file at `outfile`. Throws on any build error. */
 export async function buildPluginUiBundle({ entry, outfile, minify = false, nodePaths }) {
   await build({
@@ -32,3 +38,48 @@ export async function buildPluginUiBundle({ entry, outfile, minify = false, node
     },
   });
 }
+
+/** Compile the plugin's OWN stylesheet from the FINISHED bundle at `bundle` and write it to `outfile`.
+ *
+ *  Why this exists: Elowen ships a PREBUILT web app (`web-dist/` is in `package.json → files`), so on a
+ *  user's machine there is no Tailwind and no Next build — the host's CSS is frozen at publish time and
+ *  carries only the utilities the HOST itself uses. A plugin from the registry that reaches for any other
+ *  utility rendered unstyled there, with nothing the user could do about it. So the plugin brings its own.
+ *
+ *  Three scoping rules make that safe to drop into a running app, and each is load-bearing:
+ *  - everything lands in `@layer utilities`, so the host's own utilities (declared in the same layer, but
+ *    earlier in the cascade order the host establishes) are not globally outranked by a plugin's sheet;
+ *  - NO preflight — a plugin must never reset the host's elements;
+ *  - NO prefix — the plugin shares class names with the shared components it renders from
+ *    `window.ElowenUiRuntime`, which are styled by the host's sheet.
+ *
+ *  The theme is `@reference`d, never imported: referencing emits `var(--token, fallback)` instead of
+ *  inlining the value, so the plugin reads the HOST's live variables and follows a skin
+ *  (`web/skins/*` override the tokens on `:root[data-skin]`). Inlining them would freeze every plugin
+ *  on the default palette. Returns the emitted CSS. */
+export async function buildPluginUiCss({ bundle, outfile }) {
+  // Loaded lazily so `buildPluginUiBundle` — the far more common call — never pays for Tailwind's
+  // native scanner just to bundle JS.
+  const { compile } = await import('@tailwindcss/node');
+  const { Scanner } = await import('@tailwindcss/oxide');
+
+  const source = resolve(bundle);
+  const css = [
+    // Declare the layer order the host uses, so `utilities` sorts where the host puts it.
+    '@layer theme, base, components, utilities;',
+    // Reference-only: gives the compiler the design system (Tailwind's defaults + the host tokens)
+    // WITHOUT emitting a single variable or preflight rule of its own.
+    '@reference "tailwindcss/theme.css";',
+    `@reference ${JSON.stringify(resolve(kitDir, 'theme.css'))};`,
+    // The finished bundle is the only scan target: class names survive minification as plain string
+    // literals, so the built file is a complete and honest record of what the plugin actually uses.
+    `@source ${JSON.stringify(source)};`,
+    '@layer utilities { @tailwind utilities; }',
+  ].join('\n');
+
+  const compiler = await compile(css, { base: kitDir, onDependency: () => {} });
+  const out = compiler.build(new Scanner({ sources: compiler.sources }).scan());
+  await mkdir(dirname(resolve(outfile)), { recursive: true });
+  await writeFile(resolve(outfile), out, 'utf8');
+  return out;
+}

package/index.d.ts

@@ -10,7 +10,36 @@ import type { ComponentType } from 'react';
 /** See index.js — bump on incompatible changes to `ElowenUiRuntime`. Deliberately a LITERAL type:
  *  the web app re-declares the value and annotates it with `typeof PLUGIN_UI_API_VERSION`, so a kit
  *  bump that forgets the host fails the web typecheck instead of drifting silently. */
-export declare const PLUGIN_UI_API_VERSION: 1;
+export declare const PLUGIN_UI_API_VERSION: 6;
+
+/** Project metadata exposed to a contextual plugin panel. The Project remains core-owned; a panel uses
+ *  this identity to address only its own project-scoped API data. */
+export interface PluginUiProject {
+  id: number;
+  slug: string;
+  path: string;
+  notes: string;
+  icon?: string;
+}
+
+/** The selected core User DTO exposed only to administrator user-detail panels. Compatibility fields stay
+ * present because plugins receive the same object as the host Users screen, not a second partial identity. */
+export interface PluginUiUser {
+  id: number;
+  username: string;
+  created_at: string;
+  is_admin: boolean;
+  allowed_execs: string[];
+  disabled_tools: string[];
+  allowed_tools: string[];
+  granted_plugins: string[];
+  name: string;
+  email: string;
+  avatar: string;
+  default_exec: string;
+  advisor_exec: string;
+  advisor_autostart: boolean;
+}
 
 /** Props every plugin page/settings component receives. */
 export interface PluginPageProps {
@@ -33,12 +62,32 @@ export interface PluginPageProps {
   onSaveState?: (status: 'idle' | 'saving' | 'saved' | 'error', retry?: () => void) => void;
 }
 
+/** Props for a contextual Project panel. It is never a standalone route: the selected Project and panel
+ *  id come from the host's Project detail rail. */
+export interface PluginProjectPanelProps {
+  plugin: string;
+  panelId: string;
+  project: PluginUiProject;
+  surface: 'project';
+}
+
+/** Props for an administrator panel mounted for one selected core User. */
+export interface PluginUserPanelProps {
+  plugin: string;
+  panelId: string;
+  user: PluginUiUser;
+  surface: 'user';
+}
+
 /** What a bundle hands to window.__elowenRegisterPluginUi. Routes are `/`-joined segment patterns
- *  (`''` = the root page, `detail/:id` captures params). `settings` components are keyed by the
- *  manifest's `web.settings[].id` and render inside the Settings page's control deck. */
+ *  (`''` = the root page, `detail/:id` captures params). Contextual component maps are keyed by their
+ *  matching manifest panel ids and mount only in the corresponding host surface. */
 export interface PluginUiRegistration {
   requiresApiVersion: number;
   pages?: Record<string, ComponentType<PluginPageProps>>;
+  account?: Record<string, ComponentType<PluginPageProps>>;
+  user?: Record<string, ComponentType<PluginUserPanelProps>>;
+  project?: Record<string, ComponentType<PluginProjectPanelProps>>;
   settings?: Record<string, ComponentType<PluginPageProps>>;
 }
 

package/index.js

@@ -2,4 +2,4 @@
  *  `window.ElowenUiRuntime` stamped with this number; a bundle whose `requiresApiVersion` is NEWER
  *  renders a placeholder instead of executing against a contract it was not built for. Bump on
  *  incompatible changes to the `ElowenUiRuntime` surface (see index.d.ts). */
-export const PLUGIN_UI_API_VERSION = 1;
+export const PLUGIN_UI_API_VERSION = 5;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elowen-plugin-ui-kit",
-  "version": "0.1.0",
+  "version": "0.5.0",
   "description": "Contract types and esbuild toolchain for building Elowen plugin browser-UI bundles.",
   "license": "MIT",
   "type": "module",
@@ -25,11 +25,15 @@
     "build.d.ts",
     "bin.js",
     "shims/",
+    "theme.css",
     "README.md"
   ],
   "dependencies": {
+    "@tailwindcss/node": "^4.3.3",
+    "@tailwindcss/oxide": "^4.3.3",
     "@types/react": "^19.2.0",
     "@types/react-dom": "^19.2.0",
-    "esbuild": "^0.28.2"
+    "esbuild": "^0.28.2",
+    "tailwindcss": "^4.3.3"
   }
 }

package/theme.css

@@ -0,0 +1,78 @@
+/* GENERATED MIRROR of web/app/styles/tokens.css @theme blocks — do not edit by hand.
+ * The host owns these tokens; this copy exists only so a plugin CSS build can `@reference` them and
+ * emit `var(--token, fallback)`. tests/contract/pluginUiKitTheme.test.ts fails the moment the two drift.
+ */
+@theme {
+  /* OLED Ember: true black canvas, warm near-black surfaces, one unmistakable Elowen accent. */
+  --color-bg: #000000;
+  --color-document: #030303;
+  --color-surface: #070707;
+  --color-elevated: #0d0d0d;
+  --color-overlay: #151515;
+  --color-border: #242424;
+  --color-border-strong: #363636;
+  --color-accent: #ff5236;
+  --color-accent-hot: #ff735c;
+  --color-ember: #ff9a62;
+  /* The pale end of the ember ramp — the far stop of a heat gradient, where the accent is the near one.
+     It is a token so a repaint moves the whole ramp; a literal in a chart would stay orange. */
+  --color-ember-bright: #ffd09a;
+
+  --color-text: #f7f3f0;
+  --color-text-muted: #9d948e;
+  --color-text-subtle: #6e6661;
+
+  --color-danger: #e94d42;
+  --color-success: #32c986;
+  --color-warning: #edae49;
+  --color-error: #e94d42;
+  --color-info: #62a8ea;
+  --color-approve: #32c986;
+  --color-cancelled: #756d68;
+
+  /* Organic but disciplined: compact controls, roomier panels, never pill-shaped by default. */
+  --radius-sm: 0.375rem;
+  --radius: 0.5rem;
+  --radius-md: 0.625rem;
+  --radius-lg: 0.75rem;
+  --radius-xl: 1rem;
+  --radius-2xl: 1.25rem;
+
+  --space-1: 0.25rem;
+  --space-2: 0.5rem;
+  --space-3: 0.75rem;
+  --space-4: 1rem;
+  --space-5: 1.25rem;
+  --space-6: 1.5rem;
+  --space-8: 2rem;
+  --space-10: 2.5rem;
+  --space-12: 3rem;
+
+  --font-mono: var(--font-geist-mono), ui-monospace, "SF Mono", monospace;
+  --font-sans: var(--font-geist-sans), -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  --font-display: var(--font-geist-sans), var(--font-sans);
+
+  --text-display: clamp(2rem, 1.55rem + 1.5vw, 3.25rem);
+  --text-caption: 0.6875rem;
+  --text-tiny: 0.5625rem;
+
+  /* The accent as a bare R G B triple, so shadow/glow tokens can compose alpha variants — and so a
+     white-label theme can retint them by overriding this ONE variable instead of every baked shadow. */
+  --accent-rgb: 255 82 54;
+  --shadow-card: 0 1px 0 rgb(255 255 255 / 0.025), 0 14px 40px rgb(0 0 0 / 0.2);
+  --shadow-raised: 0 1px 0 rgb(255 255 255 / 0.04), 0 22px 64px rgb(0 0 0 / 0.48);
+  --shadow-ember: 0 16px 48px rgb(var(--accent-rgb) / 0.14);
+  --glow-active: 0 0 0 1px rgb(var(--accent-rgb) / 0.3), 0 0 24px rgb(var(--accent-rgb) / 0.22), 0 0 64px rgb(var(--accent-rgb) / 0.12);
+  --glow-soft: 0 0 44px rgb(var(--accent-rgb) / 0.1);
+  --hairline: 1px solid rgb(255 255 255 / 0.075);
+
+  --motion-instant: 80ms;
+  --motion-fast: 140ms;
+  --motion-base: 240ms;
+  --motion-slow: 420ms;
+  --motion-ambient: 8s;
+  --motion-distance-md: 10px;
+  --ease-standard: cubic-bezier(0.2, 0, 0, 1);
+  --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
+  --ease-spring: cubic-bezier(0.34, 1.35, 0.64, 1);
+}