From 0d9d1242373da9a7362f23d8964a7f7433fa56f4 Mon Sep 17 00:00:00 2001
From: Federico Jaramillo Martinez <federicojaramillom@gmail.com>
Date: Fri, 5 Jun 2026 14:26:35 +0200
Subject: [PATCH] fix(plugins): preserve deprecated panel terminal alias

---
 .changeset/remove-panel-open-terminal.md | 2 +-
 docs/plugins.md                          | 8 +++++---
 src/client/src/components/PiWebApp.ts    | 1 +
 src/client/src/plugins/types.ts          | 5 +++++
 src/plugin-api.ts                        | 1 -
 5 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/.changeset/remove-panel-open-terminal.md b/.changeset/remove-panel-open-terminal.md
index f989483..00a8f80 100644
--- a/.changeset/remove-panel-open-terminal.md
+++ b/.changeset/remove-panel-open-terminal.md
@@ -2,4 +2,4 @@
 "@jmfederico/pi-web": patch
 ---
 
-Clean up the workspace panel plugin context by removing the legacy `openTerminal` alias and moving render invalidation to `context.host.requestRender()`.
+Clean up the workspace panel plugin context by moving render invalidation to `context.host.requestRender()` and deprecating the legacy runtime-only `openTerminal` alias in favor of `context.terminal.open()`.
diff --git a/docs/plugins.md b/docs/plugins.md
index 66570fd..2e8ab53 100644
--- a/docs/plugins.md
+++ b/docs/plugins.md
@@ -182,7 +182,7 @@ Built-in plugins can be managed from **Settings → Plugins** or with the top-le
 
 ### Updates
 
-**Plugin id:** `updates`  
+**Plugin id:** `updates`
 **What it does:** adds a conditional **Updates** workspace tab with PI WEB update, restart, and installed-service guidance.
 
 Updates is enabled by default. To hide it, disable `updates` in **Settings → Plugins** or set:
@@ -197,8 +197,8 @@ Updates is enabled by default. To hide it, disable `updates` in **Settings → P
 
 ### Workspace Tasks
 
-**Plugin id:** `workspace-tasks`  
-**Config file:** `.pi-web/tasks.json`  
+**Plugin id:** `workspace-tasks`
+**Config file:** `.pi-web/tasks.json`
 **What it does:** adds a **Tasks** workspace tab for running configured shell commands in dedicated PI WEB terminals.
 
 Workspace Tasks is enabled by default. To hide it, disable `workspace-tasks` in **Settings → Plugins** or set:
@@ -534,6 +534,8 @@ interface WorkspacePanelContext {
 
 `machine`, `workspace`, `files`, `terminal`, and `host` are documented as stable for panel callbacks. Use `terminal.open()` to switch to the built-in terminal panel; pass `{ terminalId }` to deep-link to a specific terminal. Call `host.requestRender()` when async plugin-owned state changes should make PI WEB re-evaluate panel callbacks such as `badge`, `visible`, or `render`.
 
+For compatibility, PI WEB still provides the old `context.openTerminal()` workspace-panel helper at runtime. It is deprecated, intentionally omitted from the public TypeScript declarations, and planned for removal in v2. Existing JavaScript plugins keep working, while typed plugins should migrate to `context.terminal.open()`.
+
 Useful workspace and machine shapes:
 
 ```ts
diff --git a/src/client/src/components/PiWebApp.ts b/src/client/src/components/PiWebApp.ts
index 5e6c925..4bc238c 100644
--- a/src/client/src/components/PiWebApp.ts
+++ b/src/client/src/components/PiWebApp.ts
@@ -943,6 +943,7 @@ export class PiWebApp extends LitElement {
           open: (options) => { void this.openRuntimeTerminal(machineId, workspace, options); },
           runCommand: (input) => terminalCommandRuns.runCommand({ ...input, workspace }),
         },
+        openTerminal: (options) => { void this.openRuntimeTerminal(machineId, workspace, options); },
         host: this.createWorkspaceHost(),
         piWebUnstable: { terminalCommandRuns },
         fileTree: this.state.fileTree,
diff --git a/src/client/src/plugins/types.ts b/src/client/src/plugins/types.ts
index 4290865..23cde24 100644
--- a/src/client/src/plugins/types.ts
+++ b/src/client/src/plugins/types.ts
@@ -131,6 +131,11 @@ export interface QualifiedPluginAction extends AppAction {
 
 export interface WorkspacePanelContext extends WorkspaceContext {
   terminal: WorkspacePanelTerminal;
+  /**
+   * @deprecated Runtime-only compatibility alias for pre-v2 plugins. Use `terminal.open()` instead.
+   * This is intentionally not part of the public `@jmfederico/pi-web/plugin-api` declarations.
+   */
+  openTerminal?: (options?: { terminalId?: string | undefined }) => void;
   piWebUnstable?: Pick<PiWebUnstableRuntimeContext, "terminalCommandRuns">;
   fileTree: FileTreeEntry[];
   expandedDirs: Record<string, FileTreeEntry[]>;
diff --git a/src/plugin-api.ts b/src/plugin-api.ts
index d7285a5..971e46c 100644
--- a/src/plugin-api.ts
+++ b/src/plugin-api.ts
@@ -212,4 +212,3 @@ export interface ThemePairContribution {
   light: LocalContributionId;
   dark: LocalContributionId;
 }
-