elowen-plugin-ui-kit 0.7.0 → 0.11.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: 12;
+/** 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,13 @@ 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;
@@ -45,7 +53,7 @@ export interface PluginConfigField {
   display?: { control?: 'input' | 'slider'; unit?: string; divisor?: number };
   browse?: 'directory';
   default?: string | number | boolean | string[];
-  providerType?: string;
+  providerType?: string | string[];
   options?: { value: string; label: string }[];
   language?: string;
   help?: string;
@@ -120,6 +128,52 @@ export interface ConfirmDialogProps {
   onClose: () => void;
 }
 
+/** The durable operation row a progress window renders, as the daemon publishes it. List projections
+ *  omit `logTail`; the single-operation read and the live `environment-operation` frame carry it.
+ *  The status union is the daemon's own (`EnvironmentOperation` in the wire contract): an environment
+ *  operation is never cancelled, and a status this side invents is one a bundle would render as "still
+ *  preparing" forever. */
+export interface EnvironmentOperationView {
+  id: string;
+  projectId: number;
+  generation: number;
+  action: { kind: string };
+  status: 'pending' | 'running' | 'succeeded' | 'failed';
+  error: string | null;
+  /** The declared step list, in order. Each entry is a stable id the host localizes. */
+  steps: string[];
+  stepIndex: number;
+  stepTotal: number;
+  stepLabel: string | null;
+  percent: number | null;
+  logTail?: string[];
+}
+
+/** Public props of `ElowenUiRuntime.components.OperationProgressDialog`: one installer-style window over
+ *  a durable environment operation, rendered as `Modal` content by the host.
+ *
+ *  Dismissing it while the work runs HIDES it — the operation outlives the tab that started it — so
+ *  `onClose` reports whether it was still running and the call site decides whether to keep following. */
+export interface OperationProgressDialogProps {
+  open: boolean;
+  /** What the person asked for, in their words. The dialog adds the step, never the intent. */
+  title: string;
+  operation: EnvironmentOperationView | null;
+  logTail?: string[];
+  /** A transport failure of the read that follows the operation, distinct from a failed operation. */
+  loadError?: string | null;
+  /** Run the same intent again. Omitted, the retry action is not offered. */
+  onRetry?: () => void;
+  /** The stale-environment repair. Offered only while `recreatable` holds. */
+  onRecreate?: () => void;
+  recreatable?: boolean;
+  onClose: (info: { running: boolean }) => void;
+  /** Fired once when a succeeded operation closes itself. */
+  onSettled?: () => void;
+  /** How long a success stays on screen before it closes itself. */
+  successDelayMs?: number;
+}
+
 /** 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 {
@@ -187,6 +241,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. */
@@ -202,6 +323,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.
@@ -229,6 +352,7 @@ export interface ElowenUiRuntime {
   jsxRuntime: typeof JsxRuntime;
   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

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 = 12;
+ *  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.7.0",
+  "version": "0.11.0",
   "description": "Contract types and esbuild toolchain for building Elowen plugin browser-UI bundles.",
   "license": "MIT",
   "type": "module",

package/theme.css

@@ -40,6 +40,62 @@
      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);
+  /* NOT a shadcn token. The rule down the column's OUTER edge, and it now ALIASES
+     --color-sidebar-border rather than holding a colour of its own: the frame the top bar draws across
+     the window turns the corner and runs the full height of the column, so the vertical line and the
+     horizontal one have to resolve to one value or the frame changes colour where they meet. Owner
+     decision, 6 Sep 2026, overriding the transparent outer edge of 5 Sep — the column is framed on its
+     right the way the page is framed on top. The name stays because the two edges are still separate
+     DECISIONS: a design that wants its column to melt into the canvas sets this one token to
+     `transparent` and keeps the internal hairlines (header, footer, search field). */
+  --color-sidebar-rule: var(--color-sidebar-border);
+
+  /* The column's GEOMETRY, as measured off the Cloudflare dashboard (plans/cloudflare-sidebar-spec.md).
+     Separate tokens from the colours above because they are a different kind of decision: a skin
+     repaints the sidebar constantly and moves these almost never, and the primitive's collapsed rail
+     has to agree with the shell's flex basis or the fold animates to the wrong width.
+     `--sidebar-width-icon` is read by `components/ui/shadcn/sidebar.tsx`, which upstream injects as an
+     inline style — it is declared here so a skin can still override it. Its value is the reference's
+     measured 57px and it is stated ONCE, here: both Studio skins used to restate the same number, which
+     is two sources of truth for one measurement and a drift nothing would have caught. */
+  --sidebar-width: 16.25rem;        /* 260px, the expanded column */
+  --sidebar-width-icon: 3.5625rem;  /* 57px, the collapsed rail */
+  --sidebar-width-mobile: 18rem;    /* the off-canvas presentation, wider than the desktop column */
+  --sidebar-row-height: 2.125rem;   /* 34px, `min-h-8.5` in the reference */
+  --sidebar-row-radius: 0.5rem;     /* 8px, `rounded-lg` in the reference's own scale */
+  --sidebar-row-inset: 0.75rem;     /* 12px horizontal padding inside a row */
+  --sidebar-sub-indent: 1.75rem;    /* 28px, `pl-7` per nesting level */
+  --sidebar-text: 0.8125rem;        /* 13px, every row and group label */
+  --sidebar-header-height: 3.625rem; /* 58px, the switcher row above the header hairline */
+  --sidebar-switcher-height: 2.5rem; /* 40px, the switcher itself, centred inside that header */
+  /* The page's top bar is the SAME height as the sidebar header, because the hairline under each is ONE
+     line across the whole window: the column's header and the page's bar are two halves of one frame,
+     and 58px beside a 50px bar is what left a visible step where the two met. Stated as an ALIAS rather
+     than as a second 58px — they are one measurement, so a design that retunes the frame moves both by
+     moving the sidebar header. */
+  --topbar-height: var(--sidebar-header-height);
+  --sidebar-footer-height: 3rem;    /* 48px, the fold's row below the footer hairline */
+  --sidebar-search-height: 2rem;    /* 32px, the command palette's field under the header */
+  /* The disclosure caret's own duration. Not `--motion-base`: the Studio skins retune that to 150ms for
+     navigation, and the reference turns this caret in 200ms regardless of how fast the rest of the
+     column moves. A rotation is the one motion in the menu the eye follows to its end. */
+  --sidebar-caret-motion: 200ms;
+
   --color-border: #242424;
   /* NOT a shadcn token: the heavier rule, for a scrollbar thumb and a focused edge. */
   --color-border-strong: #363636;
@@ -74,6 +130,25 @@
   --color-warning: #edae49;
   --color-info: #62a8ea;
 
+  /* Code and diff surfaces. Mirrored from the host so a plugin sheet compiled against this kit resolves
+     the same values; the app renders diffs itself, so a plugin bundle has none of its own to paint. */
+  --color-diff-canvas: #0d0d10;
+  --color-diff-add: color-mix(in srgb, #005f00 30%, var(--color-diff-canvas));
+  --color-diff-add-marker: #50c850;
+  --color-diff-del: color-mix(in srgb, #5f0000 30%, var(--color-diff-canvas));
+  --color-diff-del-marker: #dc5a5a;
+  --color-diff-del-foreground: #f8f8f2;
+  --color-diff-gutter: #7d7d88;
+
+  --color-code-plain: #f8f8f2;
+  --color-code-keyword: #f92672;
+  --color-code-string: #e6db74;
+  --color-code-number: #ae81ff;
+  --color-code-comment: #75715e;
+  --color-code-type: #66d9ef;
+  --color-code-function: #a6e22e;
+  --color-code-punct: #f8f8f2;
+
   /* The categorical series. Charts and legends read these and never a literal, so a repaint moves the
      whole set. 1–3 are the brand ramp; 4 and 5 are deliberately UNLIKE it, so a swatch stays
      distinguishable from its neighbours without borrowing `destructive` or `success` and implying a
@@ -95,8 +170,55 @@
   --radius-2xl: 1.25rem;
 
   --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);
+
+  /* Inter Variable is the app's ONE sans face, headings included. It is self-hosted
+     (`@fontsource-variable/inter`, imported in app/layout.tsx), so no rule here reaches Google Fonts.
+
+     `--font-geist-sans` is a COMPATIBILITY ALIAS, not a Geist reference: Geist Sans is no longer loaded,
+     but plugin stylesheets compiled against an older plugin-ui-kit still say `var(--font-geist-sans)`,
+     and an undefined variable inside a font-family list invalidates the whole declaration — the plugin
+     would fall back to the browser default rather than to Inter. Declaring it here keeps those bundles
+     rendering in the app's face. It is not a name new code should use; `--font-sans` is.
+
+     `--font-display` is `--font-sans` on purpose. It stays a separate token because a skin is entitled
+     to give headings a face of their own, but the built-in designs no longer do. */
+  --font-geist-sans: "Inter Variable", Inter, ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  --font-sans: var(--font-geist-sans);
+  --font-display: var(--font-sans);
+
+  /* Inter is drawn on a wider sidebearing than the reference design wants. The measured dashboard runs
+     -0.16px at 16px and -0.13px at 13px, which is the same optical correction expressed twice; as a
+     ratio it is -0.01em, so ONE token tracks both sizes and every other size in between. */
+  --tracking-ui: -0.01em;
+
+  /* ---- The type scale -------------------------------------------------------------------------
+     Five steps, measured off the reference dashboard (plans/cloudflare-sidebar-spec.md). Each one is a
+     Tailwind v4 TEXT token, which means it carries its line height, its weight and — where it differs
+     from the inherited ratio — its tracking with it. That is the property the app was missing: a
+     heading used to be assembled from a size here, a weight there and a letter-spacing somewhere else,
+     so every surface that wanted "a section title" wrote its own three-quarters of one, and no two
+     agreed. A rule now reads `var(--text-section-title)` and the rest of the step is one variable away.
+
+     `--text-page-title` is the ONE step that states its tracking absolutely. `--tracking-ui` above is a
+     RATIO, which is what makes the reference's -0.16px at 16px and -0.13px at 13px the same correction;
+     at 30px that ratio gives -0.3px, while the reference still runs -0.16px on its page title. A ratio
+     cannot express both, so the outlier says so here rather than in whichever stylesheet noticed. */
+  --text-page-title: 1.875rem;               /* 30px, the single <h1> a page has */
+  --text-page-title--line-height: 2.25rem;   /* 36px */
+  --text-page-title--font-weight: 600;
+  --text-page-title--letter-spacing: -0.16px;
+  --text-section-title: 1rem;                /* 16px, the heading of a section card */
+  --text-section-title--line-height: 1.5rem;
+  --text-section-title--font-weight: 600;
+  --text-card-title: 0.875rem;               /* 14px, the name of one record inside a card */
+  --text-card-title--line-height: 1.25rem;
+  --text-card-title--font-weight: 500;
+  --text-meta: 0.8125rem;                    /* 13px, the quiet line under a title */
+  --text-meta--line-height: 1.25rem;
+  --text-meta--font-weight: 400;
+  --text-body: 1rem;                         /* 16px/24px, the document's own step */
+  --text-body--line-height: 1.5rem;
+  --text-body--font-weight: 400;
 
   --text-display: clamp(2rem, 1.55rem + 1.5vw, 3.25rem);
   --text-caption: 0.6875rem;
@@ -112,6 +234,46 @@
   --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);
+
+  /* NOT a shadcn token. The resting depth of the ONE loud control on a page: a 1px ring in the brand
+     colour plus a short drop under it. The reference dashboard's primary button is not a flat rectangle
+     of blue — it has a defined edge and something beneath it, and that is most of why it reads as the
+     action rather than as a coloured label.
+
+     A separate token from `--glow-accent`, which is the FOCUS/ACTIVE halo and is therefore soft and
+     wide; this one is tight, opaque and always on. Composed from `--primary-rgb` so a white-label theme
+     retints it by moving that one variable, and each design states its own drop, because the value that
+     reads on a near-white page is a no-op on a true-black one. */
+  --shadow-primary: 0 0 0 1px rgb(var(--primary-rgb) / 0.9), 0 1px 2px rgb(0 0 0 / 0.4);
+  --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;