elowen-plugin-ui-kit 0.6.0 → 0.10.0

package/index.d.ts

@@ -7,10 +7,11 @@ import type * as ReactDom from 'react-dom';
 import type * as JsxRuntime from 'react/jsx-runtime';
 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: 11;
+/** See index.js — bump whenever a released bundle requires a newly published runtime contract.
+ *  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: 16;
 
 /** Public props of `ElowenUiRuntime.components.Slider`. */
 export interface SliderProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'value' | 'onChange' | 'min' | 'max' | 'step' | 'type'> {
@@ -29,6 +30,83 @@ export interface DirectoryPickerProps {
   onClose: () => void;
 }
 
+/** Public props of the API 16 `ElowenUiRuntime.components.ProjectIcon`. */
+export interface ProjectIconProps {
+  project: { id: number; icon?: string };
+  size?: number;
+  className?: string;
+}
+
+export interface PluginConfigField {
+  key: string;
+  label: string;
+  type:
+    | 'string' | 'secret' | 'boolean' | 'number' | 'textarea' | 'rolePolicies' | 'model' | 'provider'
+    | 'section' | 'enum' | 'multiSelect' | 'code' | 'prompt' | 'json' | 'embeddingModel' | 'mcpServers'
+    | 'destination' | 'projects' | 'plugins' | 'tools' | 'models' | 'timezone' | 'tokenList';
+  hint?: string;
+  required?: boolean;
+  min?: number;
+  max?: number;
+  step?: number;
+  placeholder?: string;
+  display?: { control?: 'input' | 'slider'; unit?: string; divisor?: number };
+  browse?: 'directory';
+  default?: string | number | boolean | string[];
+  providerType?: string;
+  options?: { value: string; label: string }[];
+  language?: string;
+  help?: string;
+  risk?: 'low' | 'medium' | 'high';
+  advanced?: boolean;
+  fullWidth?: boolean;
+  visibleWhen?: { key: string; equals: string | number | boolean };
+}
+
+export type SaveStatus = 'idle' | 'saving' | 'saved' | 'pending' | 'error';
+
+export interface AutoSaveStatusProps {
+  status: SaveStatus;
+  onRetry?: () => void | Promise<void>;
+}
+
+export interface UseAutoSaveStatusOptions {
+  ready?: boolean;
+  savable?: boolean;
+  delay?: number;
+}
+
+export interface UseAutoSaveStatusResult {
+  status: SaveStatus;
+  retry: () => Promise<void>;
+  flush: () => Promise<SaveStatus>;
+}
+
+export type UseAutoSaveStatus = (
+  deps: readonly unknown[],
+  save: () => unknown | Promise<unknown>,
+  options?: UseAutoSaveStatusOptions,
+) => UseAutoSaveStatusResult;
+
+export type PluginConfigErrorKind = 'validation' | 'conflict' | 'transport';
+
+export interface PluginConfigDraft {
+  values: Record<string, unknown>;
+  setValue: (key: string, value: unknown) => void;
+  commitValue: (key: string, value: unknown) => Promise<{ pending: boolean }>;
+  status: SaveStatus;
+  errorKind: PluginConfigErrorKind | null;
+  retry: () => Promise<void>;
+  flush: () => Promise<SaveStatus>;
+  ready: boolean;
+}
+
+export type UsePluginConfigDraft = (
+  name: string,
+  detail: { config: Record<string, unknown>; configSchema: readonly PluginConfigField[]; revision?: number },
+  options?: { save?: (value: { name: string; values: Record<string, unknown>; expectedRevision?: number }) => Promise<unknown> },
+) => PluginConfigDraft;
+
 export type ConfirmDialogButtonVariant = 'default' | 'accent' | 'ghost' | 'danger' | 'ghost-danger' | 'outline' | 'outline-danger';
 
 /** Public props of the API 11 async-safe `ElowenUiRuntime.components.ConfirmDialog`. */
@@ -97,7 +175,7 @@ export interface PluginPageProps {
    *  inside a group header can ignore it; a section declaring `layout: 'orbital'` cannot — the orbital
    *  group is a field of pods with no header to hold one, so this channel is the only place its user
    *  ever learns that a save failed. */
-  onSaveState?: (status: 'idle' | 'saving' | 'saved' | 'error', retry?: () => void) => void;
+  onSaveState?: (status: SaveStatus, retry?: () => void | Promise<void>) => void;
 }
 
 /** Props for a contextual Project panel. It is never a standalone route: the selected Project and panel
@@ -117,6 +195,73 @@ export interface PluginUserPanelProps {
   surface: 'user';
 }
 
+/** JSON payload published with a plugin-owned inline chat artifact. */
+export type PluginChatArtifactData = null | boolean | number | string | PluginChatArtifactData[] | { [key: string]: PluginChatArtifactData };
+
+/** An optional authenticated same-plugin SSE source the artifact component may consume. */
+export interface PluginChatArtifactLiveMedia {
+  transport: 'sse';
+  path: string;
+}
+
+/** The normalized open artifact snapshot handed to a registered chat artifact component. */
+export interface PluginChatArtifact {
+  id: string;
+  plugin: string;
+  sessionId: string;
+  toolCallId: string;
+  view: string;
+  fallback: string;
+  data?: PluginChatArtifactData;
+  media?: PluginChatArtifactLiveMedia;
+  expiresAt: string;
+  status: 'open';
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** A prompt the host is waiting on, offered to an artifact that covers it (API 15).
+ *
+ *  It carries no content at all — not the question, not its options, not an id. A surface that hides the
+ *  host's question card only needs to say that one is waiting and to hand the reader back to it, and both
+ *  of those are host-owned: `label` is the app's own translated line, `reveal` brings the real card into
+ *  view and focuses it. Everything about answering — the options, validation, the request — stays where it
+ *  already is, so nothing an artifact renders can drift from what the user is actually being asked. */
+export interface PluginChatPendingInput {
+  /** The host's own user-visible line, already translated. Render it as-is. */
+  label: string;
+  /** Bring the host's prompt into view and focus it. A covering surface should close itself first. */
+  reveal: () => void;
+}
+
+/** Props for a plugin component rendered inline after its artifact's matching tool segment. */
+export interface PluginChatArtifactProps {
+  plugin: string;
+  artifact: PluginChatArtifact;
+  /** API 15. Set while the host is waiting on an answer from the user, `null` when it is not.
+   *
+   *  Same reason as `narration`: an artifact whose surface covers the dock covers the question card with
+   *  it, and a reader who cannot see that they are being asked something will sit and wait for an agent
+   *  that is waiting for them. Show that a prompt is waiting, then call `reveal` — after closing your own
+   *  surface — to put the reader in front of the real card.
+   *
+   *  It clears the moment the prompt is answered, discarded or the conversation is switched. Hosts older
+   *  than API 15 pass nothing, so read it as optional. */
+  pendingInput?: PluginChatPendingInput | null;
+  /** API 14. The assistant prose the transcript is rendering RIGHT NOW, for an artifact that draws a
+   *  surface over the dock and therefore hides the conversation it belongs to.
+   *
+   *  It is the host's own visible text, projected — the newest assistant turn's latest text segment,
+   *  whitespace-collapsed and capped at 240 characters — and deliberately nothing else: no tool payloads,
+   *  no hidden reasoning, no system content, no history, and empty (`''`) as soon as the newest turn is
+   *  the user's or carries no prose. A bundle renders it as PLAIN TEXT; the transcript owns markdown, and
+   *  a second composition of it would be a second source of truth for what the user was told.
+   *
+   *  It updates as the reply streams, so treat it as a live value: bound how much of it you draw, and do
+   *  not accumulate it. Hosts older than API 14 pass nothing, so read it as optional. */
+  narration?: string;
+}
+
 /** What a bundle hands to window.__elowenRegisterPluginUi. Routes are `/`-joined segment patterns
  *  (`''` = 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. */
@@ -132,6 +277,8 @@ export interface PluginUiRegistration {
   accountChip?: Record<string, ComponentType<PluginPageProps>>;
   user?: Record<string, ComponentType<PluginUserPanelProps>>;
   project?: Record<string, ComponentType<PluginProjectPanelProps>>;
+  /** Inline chat views keyed by the artifact `view` selected by the publishing plugin. */
+  chatArtifacts?: Record<string, ComponentType<PluginChatArtifactProps>>;
   settings?: Record<string, ComponentType<PluginPageProps>>;
   /** Ids of `settings` sections that draw their OWN page frame — the shell, the masthead and the save
    *  indicator — and therefore want none from the host.
@@ -157,11 +304,17 @@ export interface ElowenUiRuntime {
   react: typeof React;
   reactDom: typeof ReactDom;
   jsxRuntime: typeof JsxRuntime;
-  components: Record<string, ComponentType<never>>;
+  components: Record<string, ComponentType<never>> & {
+    AutoSaveStatus: ComponentType<AutoSaveStatusProps>;
+    ProjectIcon: ComponentType<ProjectIconProps>;
+  };
   /** Curated React hooks (i18n, toasts, the app's react-query data hooks). Safe across the boundary:
    *  the bundle runs on the HOST's React instance, so the rules of hooks hold. A bundle narrows each
    *  entry to the signature it expects; an absent name means the host predates the bundle. */
-  hooks: Record<string, unknown>;
+  hooks: Record<string, unknown> & {
+    useAutoSaveStatus: UseAutoSaveStatus;
+    usePluginConfigDraft: UsePluginConfigDraft;
+  };
   /** Curated pure helpers (formatting, session/task mapping, error shaping) shared with bundles. */
   utils: Record<string, unknown>;
   api: (path: string, init?: RequestInit) => Promise<unknown>;

package/index.js

@@ -1,5 +1,5 @@
 /** The single source of truth for the plugin browser-UI contract version. The web app installs
  *  `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 = 11;
+ *  renders a placeholder instead of executing against a contract it was not built for. Bump whenever
+ *  a released bundle requires a newly published `ElowenUiRuntime` contract (see index.d.ts). */
+export const PLUGIN_UI_API_VERSION = 16;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elowen-plugin-ui-kit",
-  "version": "0.6.0",
+  "version": "0.10.0",
   "description": "Contract types and esbuild toolchain for building Elowen plugin browser-UI bundles.",
   "license": "MIT",
   "type": "module",

package/theme.css

@@ -40,6 +40,22 @@
      cannot see, inherits a correct sticky colour without declaring one. */
   --color-sticky: color-mix(in srgb, var(--color-document) 94%, var(--color-foreground) 6%);
 
+  /* The primary navigation column's own surfaces — shadcn's `sidebar` namespace, which the adopted
+     `components/ui/shadcn/sidebar.tsx` compiles its `bg-sidebar` / `bg-sidebar-accent` utilities from.
+     A sidebar is a chrome region rather than a document surface: it sits one step quieter than the
+     content it insets from, its rows take a fill of their own that is not `--color-muted` (a CONTENT
+     step that moves with the cards), and its rules are drawn against its own ground.
+     A design with no opinion inherits the aliases below and looks exactly as it did, so this costs
+     nothing to a skin that does not want the distinction. They live in `@theme` rather than `:root`
+     because Tailwind only emits a `bg-sidebar` utility for a token it can see here; the plugin-ui-kit
+     mirror carries them for that reason alone — a plugin bundle still has no sidebar to paint. */
+  --color-sidebar: var(--color-background);
+  --color-sidebar-foreground: var(--color-muted-foreground);
+  --color-sidebar-accent: var(--color-muted);
+  --color-sidebar-accent-foreground: var(--color-foreground);
+  --color-sidebar-border: var(--color-border);
+  --color-sidebar-ring: var(--color-ring);
+
   --color-border: #242424;
   /* NOT a shadcn token: the heavier rule, for a scrollbar thumb and a focused edge. */
   --color-border-strong: #363636;
@@ -67,6 +83,10 @@
      three states, and borrowing `primary` or `chart-*` for them would say something they do not mean. */
   --color-success: #32c986;
   --color-success-foreground: var(--color-primary-foreground);
+  /* Toasts are outcome banners, not tiny status marks. GitHub's Primer success green gives them the
+     saturated diff/merge signal Filip expects while keeping white body text above AA contrast. */
+  --color-toast-success: #1f883d;
+  --color-toast-success-foreground: #ffffff;
   --color-warning: #edae49;
   --color-info: #62a8ea;
 
@@ -108,6 +128,35 @@
   --glow-soft: 0 0 44px rgb(var(--primary-rgb) / 0.1);
   --hairline: 1px solid rgb(255 255 255 / 0.075);
 
+  /* ---- Depth ----------------------------------------------------------------------------------
+     NOT shadcn tokens. shadcn's depth vocabulary is Tailwind's shadow scale, which is a set of fixed
+     black shadows — on a true-black canvas every one of them is a no-op, and on a near-white one they
+     are all too heavy. These four name the depth EFFECTS the app actually composes, so each design
+     states its own version of them once instead of every card guessing.
+
+     `--shadow-lift` is the hover step above `--shadow-card`: a card that rises under the pointer. It is
+     a peer of `--shadow-card`, not a replacement — a resting card keeps the quieter one.
+
+     `--glow-accent` is the accent halo a FOCUSED or ACTIVE surface takes: the composer under the caret,
+     the navigation row you are standing on. Distinct from `--glow-active`, which is the loud ember ring
+     the spatial design paints on its orbit nodes; this one has to stay usable behind body text.
+
+     `--glass-surface` + `--glass-blur` are the translucent working surface (the composer). The fill is a
+     MIX of a surface token rather than a fixed alpha white, so a design that has no light to scatter can
+     turn the effect off by mixing to 100% and setting the blur to 0 without touching a component. */
+  --shadow-lift: 0 1px 0 rgb(255 255 255 / 0.05), 0 24px 60px rgb(0 0 0 / 0.34);
+  --glow-accent: 0 0 0 1px rgb(var(--primary-rgb) / 0.28), 0 0 30px rgb(var(--primary-rgb) / 0.18);
+  --glass-surface: color-mix(in srgb, var(--color-card) 62%, transparent);
+  --glass-border: color-mix(in srgb, var(--color-foreground) 10%, transparent);
+  --glass-blur: 18px;
+
+  /* The accent atmosphere behind a hero. Two off-centre radial stops rather than one centred wash: a
+     single centred glow reads as a vignette bug, two offset ones read as light entering the page. It is
+     an IMAGE, so it composes over whatever canvas the design owns and needs no surface of its own. */
+  --mesh-accent:
+    radial-gradient(62% 78% at 16% -8%, rgb(var(--primary-rgb) / 0.16), transparent 68%),
+    radial-gradient(52% 68% at 86% 4%, rgb(var(--primary-rgb) / 0.1), transparent 70%);
+
   --motion-instant: 80ms;
   --motion-fast: 140ms;
   --motion-base: 240ms;