elowen-plugin-ui-kit 0.7.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: 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;
@@ -187,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. */
@@ -202,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.
@@ -229,6 +306,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.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;
@@ -112,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;