@ycodium-ai/plugin-api 0.1.0 → 0.2.0

package/README.md

@@ -12,7 +12,15 @@ own state across restarts.
 npm install --save-dev @ycodium-ai/plugin-api
 ```
 
-This package is types only at build time — nothing of it ends up in your bundle.
+Types are erased at build time. Runtime exports such as `definePlugin` come from the
+Ycodium host's shared copy; keep this package external when bundling your plugin.
+
+The CSS subpath `@ycodium-ai/plugin-api/ui.css` is the public Tailwind preset for
+plugin pages: control-axis utilities, semantic colors, status animations, and
+`surface-glass`. It does not reset browser defaults. Host `index.css` and first-party plugin
+stylesheets import this same file. It does not reset browser defaults. Token _values_ still come from the host
+document (`:root` and `applyTheme`). Chart series colors are host CSS variables
+`--provider-*`, not a second copy of the palette.
 
 ## A plugin is an npm package
 
@@ -37,11 +45,11 @@ Declare the entry file under `ycodium.plugin`:
 And export the definition:
 
 ```ts
-import { definePlugin, PLUGIN_API_VERSION } from "@ycodium-ai/plugin-api";
+import { definePlugin } from "@ycodium-ai/plugin-api";
 
 export default definePlugin({
   id: "my-plugin",
-  apiVersion: PLUGIN_API_VERSION,
+  apiVersion: 2,
   activate: (ctx) => {
     ctx.log.info("hello");
 
@@ -69,12 +77,45 @@ ycodium plugin add my-ycodium-plugin
 
 ## Bundle your entry file
 
-The host loads your entry by absolute path, from a directory inside the user's Ycodium home
-— not inside your package's dependency tree. A bare `import` at runtime will not resolve
-there.
+Bundle your own code and private dependencies into an ESM entry. Keep
+`@ycodium-ai/plugin-api` and its subpaths external. For esbuild:
+
+```js
+external: ["@ycodium-ai/plugin-api", "@ycodium-ai/plugin-api/*"];
+```
+
+The host resolves these imports to its shared API module, including for bundled official
+plugins, npm installations, local directories, and temporary plugins. Plugins do not need
+to copy the API into their package or depend on a particular installation directory.
+
+Browser bundles use the same rule. Map runtime API imports to the host's module table,
+`window.__ycodiumPluginHost.modules`, as you map React to the host's React instance.
+For example, an alias module for a UI helper can re-export the host value:
+
+```js
+const api = window.__ycodiumPluginHost.modules?.["@ycodium-ai/plugin-api/ui"];
+if (!api) throw new Error("This plugin needs a newer Ycodium app. Update the app.");
+export const { pluginUiHostHasCapability } = api;
+```
+
+The table also exposes `@ycodium-ai/plugin-api`. Keep API implementations out of page bundles;
+type-only imports need no alias. Web and embedded plugin pages provide the same module table.
+
+## Embedded views and host controls
+
+`register(bridge)` can return an optional `views` map alongside `pages` and `panels`.
+A view has no navigation entry. Its caller supplies the agreed props; the host loads it
+from the same machine-scoped bundle and translation context as the full page. This lets
+an embedded detail and its full page share one implementation. Missing or unloaded views
+show an unavailable state.
 
-**Bundle your entry into one ESM file with no runtime imports.** Types from this package are
-compile-time only and erase during bundling, so importing it for types is fine.
+The host UI surface includes `InputGroup`, `InputGroupAddon`, `InputGroupInput`,
+`DocumentPanel`, and `MasterDetail`. `DocumentPanel` accepts `PluginUiDocumentTab` descriptors,
+an active id, close/activate callbacks, and a `widthStorageKey`; the host supplies its tab
+strip, menus, resize handle, and stored width. `MasterDetail` takes the list as children,
+a `detail`, an `onBack` callback, and `onMasterVisibilityChange`. Stop hidden list observers
+when that callback reports `false`. The list stays mounted to retain its scroll position.
+`useLinkContextMenu` supplies the host's copy/open menu for a link.
 
 ## Permissions
 
@@ -96,7 +137,9 @@ shows up there without anyone registering it.
 
 ## THERE WILL BE COMPATIBILITY-BREAKING CHANGES
 
-`PLUGIN_API_VERSION` is checked for **exact equality**. The current API is 2. Plugins targeting
+The definition's `apiVersion` is checked for **exact equality**. Declare the version your
+plugin targets as a literal; do not read the host's `PLUGIN_API_VERSION` to make the declaration
+automatically match. The current API is 2. Plugins targeting
 API 1 are refused before activation. API 2 replaces the Teams-specific host methods with generic
 execution ownership, command receipts, notifications, and plugin contributions. Update plugins
 against the current types and republish; there is no compatibility layer.

package/css/ui.css

@@ -0,0 +1,180 @@
+/* 宿主与插件共用工具类注册；令牌值由宿主主题提供，不重置浏览器默认样式。
+   插件在自己的 @scope 下生成工具类，不依赖宿主恰好产出的同名类。 */
+
+@theme inline {
+  --spacing-control-1: var(--control-h-1);
+  --spacing-control-2: var(--control-h-2);
+  --spacing-control-3: var(--control-h-3);
+  --spacing-control-4: var(--control-h-4);
+  --spacing-control-5: var(--control-h-5);
+  --spacing-nested-1: var(--control-h-nested-1);
+  --spacing-nested-2: var(--control-h-nested-2);
+  --spacing-nested-3: var(--control-h-nested-3);
+  --spacing-nested-4: var(--control-h-nested-4);
+  --spacing-nested-5: var(--control-h-nested-5);
+  --spacing-icon-1: var(--control-icon-1);
+  --spacing-icon-2: var(--control-icon-2);
+  --spacing-icon-3: var(--control-icon-3);
+  --spacing-icon-4: var(--control-icon-4);
+  --spacing-icon-5: var(--control-icon-5);
+  --radius-control-1: var(--control-radius-1);
+  --radius-control-2: var(--control-radius-2);
+  --radius-control-3: var(--control-radius-3);
+  --radius-control-4: var(--control-radius-4);
+  --radius-control-5: var(--control-radius-5);
+  --text-control-1: var(--control-text-1);
+  --text-control-1--line-height: var(--control-leading-1);
+  --text-control-2: var(--control-text-2);
+  --text-control-2--line-height: var(--control-leading-2);
+  --text-control-3: var(--control-text-3);
+  --text-control-3--line-height: var(--control-leading-3);
+  --text-control-4: var(--control-text-4);
+  --text-control-4--line-height: var(--control-leading-4);
+  --text-control-5: var(--control-text-5);
+  --text-control-5--line-height: var(--control-leading-5);
+
+  --animate-skeleton: skeleton 2s infinite linear;
+  /* Duty-cycled indicator animations: long holds with stepped ramps, so the
+     compositor updates discrete frames instead of every vsync. */
+  --animate-status-pulse: status-pulse 2s infinite;
+  --animate-ghost-pulse: ghost-pulse 2.4s infinite;
+  --animate-status-ping: status-ping 2s infinite;
+  --animate-status-spin: status-spin 0.9s infinite steps(3);
+  --animate-tab-run-breathe: tab-run-breathe 1.8s ease-in-out infinite;
+
+  --color-warning-foreground: var(--warning-foreground);
+  --color-warning: var(--warning);
+  --color-warning-surface: var(--warning-surface);
+  --color-error-foreground: var(--error-foreground);
+  --color-error: var(--error);
+  --color-error-surface: var(--error-surface);
+  --color-update-foreground: var(--update-foreground);
+  --color-update: var(--update);
+  --color-update-surface: var(--update-surface);
+  --color-success-foreground: var(--success-foreground);
+  --color-success: var(--success);
+  --color-info-foreground: var(--info-foreground);
+  --color-info: var(--info);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-ring: var(--ring);
+  --color-input: var(--contrast-input);
+  --color-border: var(--contrast-border);
+  --color-destructive: var(--destructive);
+  --color-accent-foreground: var(--contrast-accent-foreground);
+  --color-accent: var(--accent);
+  --color-accent-pressed: var(--accent-pressed);
+  --color-muted-foreground: var(--contrast-muted-foreground);
+  --color-muted: var(--muted);
+  --color-placeholder: var(--contrast-placeholder);
+  --color-secondary-label: var(--contrast-secondary-label);
+  --color-icon-muted: var(--contrast-icon-muted);
+  --color-secondary-foreground: var(--contrast-secondary-foreground);
+  --color-secondary: var(--secondary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-primary: var(--primary);
+  --color-popover-foreground: var(--contrast-popover-foreground);
+  --color-popover: var(--popover);
+  --color-card-foreground: var(--contrast-card-foreground);
+  --color-card: var(--card);
+  --color-foreground: var(--contrast-foreground);
+  --color-background: var(--background);
+
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --radius-2xl: calc(var(--radius) + 8px);
+  --radius-3xl: calc(var(--radius) + 12px);
+  --radius-4xl: calc(var(--radius) + 16px);
+
+  @keyframes skeleton {
+    /* Transform-only so the highlight sweep stays on the compositor, then a
+       long hold with the band parked off-screen instead of a constant shimmer. */
+    0% {
+      transform: translateX(-100%);
+    }
+    60%,
+    100% {
+      transform: translateX(100%);
+    }
+  }
+  @keyframes ghost-pulse {
+    /* The loading ghosts' breath. Stepped like the status indicators, so however many bars a
+       ghost holds, the compositor draws a handful of discrete frames per cycle rather than one
+       per vsync — which on a 120Hz display is the difference between ~14 and ~288 updates. */
+    0%,
+    42% {
+      opacity: 1;
+      animation-timing-function: steps(4);
+    }
+    50%,
+    92% {
+      opacity: 0.55;
+      animation-timing-function: steps(4);
+    }
+    100% {
+      opacity: 1;
+    }
+  }
+  @keyframes status-pulse {
+    0%,
+    40% {
+      opacity: 1;
+      animation-timing-function: steps(6);
+    }
+    50%,
+    90% {
+      opacity: 0.5;
+      animation-timing-function: steps(6);
+    }
+    100% {
+      opacity: 1;
+    }
+  }
+  /* 只转 45° 就回到起点:消费者是 8 段等距的虚线圈,转满一格跟自己完全重合,
+     所以循环点无缝,不必真的转满 360°。steps(3) 让一圈只有三帧——分步是这里的
+     全部意义,连续旋转会在高刷屏上每 vsync 重绘一次。 */
+  @keyframes status-spin {
+    to {
+      transform: rotate(45deg);
+    }
+  }
+  /* 会话运行点的呼吸。**只动 opacity**，别加 `transform: scale`——实测在 DPR 1.5
+     的屏幕上 Blink 不把 transform 动画交给合成器，每帧回主线程做一次全局样式
+     重算：5 秒 810 次（无动画时 27 次）。rotate 与 scale 都一样，跟元素大小无关，
+     4px 的点加了 scale 照样 810 次。只淡入淡出是 80 次。 */
+  @keyframes tab-run-breathe {
+    0%,
+    100% {
+      opacity: 1;
+    }
+    50% {
+      opacity: 0.35;
+    }
+  }
+  @keyframes status-ping {
+    /* Burst first (immediate feedback for click ripples), then hold
+       invisible for the rest of the cycle. Mirrors animate-ping's
+       75%-scale start. */
+    0% {
+      opacity: 0.9;
+      scale: 0.75;
+      animation-timing-function: steps(8);
+    }
+    40%,
+    100% {
+      opacity: 0;
+      scale: 2;
+    }
+  }
+}
+
+@utility surface-glass {
+  background: color-mix(in srgb, var(--background) var(--glass-opacity), transparent);
+  -webkit-backdrop-filter: blur(var(--glass-blur)) saturate(var(--glass-saturation));
+  backdrop-filter: blur(var(--glass-blur)) saturate(var(--glass-saturation));
+
+  @supports not ((-webkit-backdrop-filter: blur(1px)) or (backdrop-filter: blur(1px))) {
+    background: var(--background) !important;
+  }
+}