@gang-of-beads/pi-web-plugin-api 0.1.0-alpha.2 → 0.1.0-alpha.3

package/README.md

@@ -28,7 +28,7 @@ Bundle runtime imports into each plugin half: PI WEB loads plugin modules as the
 
 ## Compatibility
 
-`0.1.0-alpha.2` contains the declarations shipped by PI WEB `2.202610.11`, with the shape and typography tokens (`--pi-font-*`, `--pi-radius-*`) accepted in `ThemeTokens`. Browser plugins declare `apiVersion: 2`; server plugins declare `apiVersion: 1`. The existing `@gang-of-beads/pi-web/plugin-api` and `@gang-of-beads/pi-web/server-plugin-api` entry points remain available.
+`0.1.0-alpha.3` contains the declarations shipped by PI WEB `2.202610.12`: `ThemeTokens` accepts the shape and typography tokens (`--pi-font-*`, `--pi-radius-*`) and the message colour tokens (`--pi-msg-*`), a theme contribution can name the theme that replaces it (`replacedBy`), and the config types carry the shared theme. Browser plugins declare `apiVersion: 2`; server plugins declare `apiVersion: 1`. The existing `@gang-of-beads/pi-web/plugin-api` and `@gang-of-beads/pi-web/server-plugin-api` entry points remain available.
 
 This is an alpha release. Host-internal members marked unstable are not a supported third-party contract.
 

package/dist/plugin-api.d.ts

@@ -1,5 +1,5 @@
 import type { CSSResultGroup, TemplateResult } from "lit";
-import type { FileSuggestion, ForegroundToken, PluginListModel, PluginReadFailure, LegacyThemeToken, SemanticSurfaceToken, ShapeTypographyToken, TerminalCommandRun, TerminalInfo, DeleteWorkspaceFileResponse, FileContentResponse, FileTreeResponse, JsonValue, MachineKind, MoveWorkspaceFileOptions, MoveWorkspaceFileResponse, PiWebStatusResponse, TerminalCommandRunHandle, WorkspaceProviderMetadata, WorkspaceRemovalPresentation, WorkspaceUploadBatchProgress, WorkspaceUploadCancelHandle, WriteWorkspaceFileOptions, WriteWorkspaceFileResponse, MachineConnection } from "./shared/pluginApiTypes.js";
+import type { FileSuggestion, ForegroundToken, MessageRoleToken, PluginListModel, PluginReadFailure, LegacyThemeToken, SemanticSurfaceToken, ShapeTypographyToken, TerminalCommandRun, TerminalInfo, DeleteWorkspaceFileResponse, FileContentResponse, FileTreeResponse, JsonValue, MachineKind, MoveWorkspaceFileOptions, MoveWorkspaceFileResponse, PiWebStatusResponse, TerminalCommandRunHandle, WorkspaceProviderMetadata, WorkspaceRemovalPresentation, WorkspaceUploadBatchProgress, WorkspaceUploadCancelHandle, WriteWorkspaceFileOptions, WriteWorkspaceFileResponse, MachineConnection } from "./shared/pluginApiTypes.js";
 export type { ThemeToken } from "./shared/pluginApiTypes.js";
 export type { FileSuggestion, LegacyThemeToken, SemanticSurfaceToken, TerminalInfo, FileContentMediaType, FileContentResponse, FileTreeEntry, FileTreeResponse, JsonObject, JsonPrimitive, JsonValue, MachineConnection, MachineKind, PiWebComponentStatus, PiWebDockerMode, PluginListAction, PluginListGroup, PluginListModel, PluginListRead, PluginListRow, PluginListStatus, PluginListTone, PluginListWords, PluginReadFailure, PiWebInstallationInfo, PiWebInstallationKind, PiWebPackageManager, PiWebReleaseStatus, PiWebServiceComponent, PiWebStatusMessage, PiWebStatusResponse, PiWebStatusSeverity, PiWebVersionResponse, TerminalCommandRun, TerminalCommandRunHandle, TerminalCommandRunStatus, WorkspaceProviderCapabilities, WorkspaceProviderMetadata, WorkspaceRemovalPresentation, WorkspaceFileUploadProgress, WorkspaceUploadBatchFileProgress, WorkspaceUploadBatchProgress, WorkspaceUploadCancelHandle, WriteWorkspaceFileOptions, WriteWorkspaceFileResponse, DeleteWorkspaceFileResponse, MoveWorkspaceFileOptions, MoveWorkspaceFileResponse, } from "./shared/pluginApiTypes.js";
 export { CORE_STATUS_FLAGS } from "./shared/machineStatus.js";
@@ -903,9 +903,11 @@ export interface WorkspaceLabelContribution {
     items: (context: WorkspaceLabelContext) => WorkspaceLabelItem[];
 }
 export type ThemeColorScheme = "dark" | "light";
-export type ThemeTokens = Record<LegacyThemeToken, string> & Partial<Record<SemanticSurfaceToken | ForegroundToken | ShapeTypographyToken, string>>;
+export type ThemeTokens = Record<LegacyThemeToken, string> & Partial<Record<SemanticSurfaceToken | ForegroundToken | ShapeTypographyToken | MessageRoleToken, string>>;
 export interface ThemeContribution {
     id: LocalContributionId;
+    /** Prefer this available concrete theme; tokens remain the fallback for other hosts. */
+    replacedBy?: QualifiedContributionId;
     name: string;
     description?: string;
     order?: number;

package/dist/shared/apiTypes.d.ts

@@ -100,6 +100,11 @@ export interface PiWebListTilesConfig {
     phone?: ListTilesPerRow;
     desktop?: ListTilesPerRow;
 }
+/** One theme choice, as a browser keeps it locally: a qualified theme id and whether it follows the system. */
+export interface PiWebSharedThemeConfig {
+    themeId: `${string}:${string}`;
+    auto: boolean;
+}
 export interface PiWebConfigValues {
     host?: string;
     port?: number;
@@ -122,6 +127,11 @@ export interface PiWebConfigValues {
     updateCommand?: string;
     /** Tiles per row in the Navigate lists, per layout; see PiWebListTilesConfig. */
     listTiles?: PiWebListTilesConfig;
+    /**
+     * The theme every browser of this PI WEB shares (owner, 2026-10-16); absent, each browser keeps
+     * its own. Written only through `PUT /api/config/theme`, so a general config save keeps it.
+     */
+    theme?: PiWebSharedThemeConfig;
     /**
      * When true, PI WEB appends environment facts to session system prompts:
      * the pi-web session nesting every session runs in, plus container facts in

package/dist/shared/pluginApiTypes.d.ts

@@ -214,13 +214,20 @@ export interface PiWebStatusResponse extends PiWebVersionResponse {
  */
 /**
  * Shape and typography stops a theme may pin. Optional by design: a theme
- * that omits them inherits the core's current shape - which since the pro
- * redesign is the flat mono TUI look, so a soft theme MUST set these to keep
- * its rounded sans rendering. Radii follow the published scale; there is no
+ * that omits them inherits the core's current shape - the rounded sans
+ * Material scale - so a flat or mono theme MUST set these to keep its look. Radii follow the published scale; there is no
  * density or border-width token yet.
  */
 export type ShapeTypographyToken = "--pi-font-ui" | "--pi-font-display" | "--pi-font-mono" | "--pi-radius-xs" | "--pi-radius-sm" | "--pi-radius-md" | "--pi-radius-lg" | "--pi-radius-xl";
-export type ThemeToken = LegacyThemeToken | SemanticSurfaceToken | ForegroundToken | ShapeTypographyToken;
+export type ThemeToken = LegacyThemeToken | SemanticSurfaceToken | ForegroundToken | ShapeTypographyToken | MessageRoleToken;
+/**
+ * Conversation message colours by who wrote the message. Optional: a theme that omits one gets it
+ * derived from its own tokens when it is applied (user from the selection colour and accent border,
+ * assistant from the surface, system from the purple family), so packs written before these tokens
+ * keep their user and assistant look and still get a system message that reads apart from the
+ * assistant's (owner, 2026-10-16).
+ */
+export type MessageRoleToken = "--pi-msg-user-bg" | "--pi-msg-user-border" | "--pi-msg-user-header-bg" | "--pi-msg-assistant-bg" | "--pi-msg-assistant-border" | "--pi-msg-assistant-header-bg" | "--pi-msg-system-bg" | "--pi-msg-system-border" | "--pi-msg-system-header-bg";
 /**
  * Foregrounds a theme may name for a filled surface it owns. Optional by
  * design: a theme that omits one keeps the previous fallback, which is why

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gang-of-beads/pi-web-plugin-api",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.3",
   "description": "Lightweight PI WEB browser and server plugin contracts, with TypeScript declarations and public runtime helpers.",
   "license": "MIT",
   "author": "Gang of Beads",