@blksails/pi-web-canvas-ui 0.2.0

package/src/canvas-gallery.tsx

@@ -0,0 +1,292 @@
+/**
+ * CanvasGallery — 画廊镜像视图(aigc-canvas · Req 3.x / 8.2 / 9.x)。
+ *
+ * 经宿主注入的 `surface`(`WebExtSurfaceAccess`,slot 侧等价 `useSurface("canvas")`)镜像
+ * `surface:canvas` 快照:
+ *  - `available === true`(source 注册了 `surface:canvas` 探针)→ 9 宫格默认 + 密度切换
+ *    (概览 / 瀑布流 / 聚焦)+ 客户端分页 + 血缘 / 时间分组;缩略用签名 `displayUrl`(二进制旁路);
+ *    轮末 idle 边沿(`syncSignal` 变化)→ `run("sync")` reconcile。
+ *  - `available === false`(非 AIGC source)→ 退化只读图库(来源 = 宿主注入的消息历史图片 `historyImages`),
+ *    A 档禁用、不发命令、不报错(B 档在工作台侧仍本地可用)。
+ *
+ * slot 组件是独立 bundle,经 prop 注入 surface(领域无关搬运);domain 对宿主不透明。
+ */
+import * as React from "react";
+import { Loader2 } from "lucide-react";
+import type { WebExtSurfaceAccess } from "@blksails/pi-web-kit";
+import { useConversationBridge } from "@blksails/pi-web-react";
+import type { GalleryAsset, GalleryState } from "@blksails/pi-web-tool-kit/aigc-canvas-schema";
+import {
+  useCanvasView,
+  CANVAS_PAGE_SIZE,
+  type CanvasDensity,
+} from "./use-canvas-view.js";
+
+const DOMAIN = "canvas";
+const STATE_KEY = `surface:${DOMAIN}`;
+const PROBE = `surface:${DOMAIN}`;
+
+const DENSITY_LABEL: Record<CanvasDensity, string> = {
+  overview: "概览",
+  waterfall: "瀑布流",
+  focus: "聚焦",
+};
+
+export interface CanvasGalleryProps {
+  /** 宿主注入的权威 surface 接入(panelRight slot);缺失 / 探针缺失 → 退化。 */
+  readonly surface?: WebExtSurfaceAccess;
+  /** 退化态图库来源:当前消息历史中的图片附件(宿主已有,无 surface)。 */
+  readonly historyImages?: readonly GalleryAsset[];
+  /** 轮末 idle 边沿信号:值变化时触发 `run("sync")`(宿主在 onTurnEnd bump)。 */
+  readonly syncSignal?: unknown;
+  /** 点击格子:展开工作台(由父面板处理)。 */
+  readonly onOpenAsset?: (assetId: string) => void;
+  /** 宿主转发的当前轮流式图像预览(由糊变清);配合 surface `livePreview` 显示渐进图。 */
+  readonly livePreviewImage?: string;
+}
+
+/** 时间分组 KEY(YYYY-MM-DD;locale 无关,保证分组稳定)。 */
+function dayOf(iso: string): string {
+  return iso.slice(0, 10);
+}
+
+/** 分组标签**显示**格式(经 Intl.DateTimeFormat 本地化;运行时 locale)。 */
+const DAY_LABEL_FMT = new Intl.DateTimeFormat(undefined, {
+  year: "numeric",
+  month: "long",
+  day: "numeric",
+});
+function formatDayLabel(ymd: string): string {
+  const d = new Date(`${ymd}T00:00:00`);
+  return Number.isNaN(d.getTime()) ? ymd : DAY_LABEL_FMT.format(d);
+}
+
+/** 血缘分组标签(root att_ = 无 derivedFrom 的祖先;此处以直接 derivedFrom 归组,UI 本地派生)。 */
+function lineageGroupOf(a: GalleryAsset): string {
+  return a.derivedFrom ?? a.attachmentId;
+}
+
+export function CanvasGallery({
+  surface,
+  historyImages,
+  syncSignal,
+  onOpenAsset,
+  livePreviewImage,
+}: CanvasGalleryProps): React.JSX.Element {
+  const view = useCanvasView();
+  const available = surface !== undefined && surface.hasCommand(PROBE);
+  // 对话桥门面(契约 §4.5):轮末 idle 边沿经 bridge.onTurnEnd 订阅(封装 syncSignal 首见不触发、
+  // 仅变化触发的边沿语义);画廊只用 onTurnEnd 一维,无提交/别名。
+  const bridge = useConversationBridge({
+    ...(surface !== undefined ? { surface } : {}),
+    syncSignal,
+    domain: DOMAIN,
+  });
+
+  // 镜像快照(available 时);退化时用 historyImages。
+  const [snap, setSnap] = React.useState<GalleryState | undefined>(() =>
+    surface?.getState<GalleryState>(STATE_KEY),
+  );
+  React.useEffect(() => {
+    if (surface === undefined) return;
+    setSnap(surface.getState<GalleryState>(STATE_KEY));
+    return surface.subscribe(STATE_KEY, (v) => setSnap(v as GalleryState | undefined));
+  }, [surface]);
+
+  // 轮末 idle 边沿 → run("sync")(仅 available;bridge.onTurnEnd 封装 syncSignal 边沿)。
+  React.useEffect(
+    () =>
+      bridge.onTurnEnd(() => {
+        if (available && surface !== undefined) {
+          void surface.run(DOMAIN, "sync");
+        }
+      }),
+    [bridge, available, surface],
+  );
+
+  const assets: readonly GalleryAsset[] = available
+    ? (snap?.assets ?? [])
+    : (historyImages ?? []);
+
+  // 客户端分页(over 轻量快照列表)。
+  const pageSize = CANVAS_PAGE_SIZE[view.density];
+  const pageCount = Math.max(1, Math.ceil(assets.length / pageSize));
+  const page = Math.min(view.page, pageCount - 1);
+  const pageAssets = assets.slice(page * pageSize, page * pageSize + pageSize);
+
+  // 分组(UI 本地派生;不发命令)。
+  const groups = React.useMemo(() => {
+    if (view.group === "none") return [{ key: "", items: pageAssets }];
+    const map = new Map<string, GalleryAsset[]>();
+    for (const a of pageAssets) {
+      const key = view.group === "time" ? dayOf(a.createdAt) : lineageGroupOf(a);
+      const arr = map.get(key);
+      if (arr === undefined) map.set(key, [a]);
+      else arr.push(a);
+    }
+    return Array.from(map.entries()).map(([key, items]) => ({ key, items }));
+  }, [pageAssets, view.group]);
+
+  const gridClass =
+    view.density === "overview"
+      ? "grid grid-cols-[repeat(auto-fill,minmax(160px,1fr))] gap-2"
+      : view.density === "waterfall"
+        ? "columns-[160px] gap-2 [&>*]:mb-2"
+        : "mx-auto grid w-full max-w-2xl grid-cols-1 gap-2";
+
+  return (
+    <div
+      data-canvas-gallery
+      data-canvas-available={String(available)}
+      data-canvas-density={view.density}
+      data-canvas-page={String(page)}
+      className="flex flex-col gap-2 p-3"
+    >
+      {/* 密度切换 + 分组(UI 本地)。 */}
+      <div className="flex items-center gap-1 text-xs">
+        {(Object.keys(DENSITY_LABEL) as CanvasDensity[]).map((d) => (
+          <button
+            key={d}
+            type="button"
+            data-canvas-density-btn={d}
+            aria-pressed={view.density === d}
+            onClick={() => view.setDensity(d)}
+            className={`rounded px-1.5 py-0.5 transition-colors ${
+              view.density === d
+                ? "bg-[hsl(var(--accent))] font-medium"
+                : "text-[hsl(var(--muted-foreground))]"
+            }`}
+          >
+            {DENSITY_LABEL[d]}
+          </button>
+        ))}
+        <span className="mx-1 opacity-30">·</span>
+        {(["time", "lineage", "none"] as const).map((g) => (
+          <button
+            key={g}
+            type="button"
+            data-canvas-group-btn={g}
+            aria-pressed={view.group === g}
+            onClick={() => view.setGroup(g)}
+            className={`rounded px-1.5 py-0.5 transition-colors ${
+              view.group === g
+                ? "bg-[hsl(var(--accent))] font-medium"
+                : "text-[hsl(var(--muted-foreground))]"
+            }`}
+          >
+            {g === "time" ? "时间" : g === "lineage" ? "血缘" : "全部"}
+          </button>
+        ))}
+      </div>
+
+      {!available ? (
+        <div
+          data-canvas-degraded
+          className="rounded bg-[hsl(var(--muted)/0.4)] px-2 py-1 text-xs text-[hsl(var(--muted-foreground))]"
+        >
+          只读图库(该 source 未提供 canvas surface;A 档禁用)
+        </div>
+      ) : null}
+
+      {/* 流式渐进预览指示(由糊变清):生成中在画廊顶部显示;有小预览显图,否则显占位指示。
+          完整渐进图由对话流工具卡承载(4:6 布局下与 Canvas 并列可见);出终图即清。 */}
+      {snap?.livePreview != null ? (
+        <div
+          data-canvas-live-preview
+          data-canvas-live-preview-stage={snap.livePreview.stage}
+          className="relative flex aspect-square w-full max-w-[200px] items-center justify-center gap-2 overflow-hidden rounded-md border border-dashed border-[hsl(var(--primary))] bg-[hsl(var(--muted)/0.3)]"
+        >
+          {(livePreviewImage ?? snap.livePreview.displayUrl) !== undefined ? (
+            // eslint-disable-next-line @next/next/no-img-element
+            <img
+              src={livePreviewImage ?? snap.livePreview.displayUrl}
+              alt="生成中预览"
+              className="absolute inset-0 h-full w-full object-cover"
+            />
+          ) : (
+            <Loader2 className="h-6 w-6 animate-spin text-[hsl(var(--primary))]" aria-hidden="true" />
+          )}
+          <div
+            role="status"
+            aria-live="polite"
+            className="pointer-events-none absolute bottom-1 left-1/2 flex -translate-x-1/2 items-center gap-1 rounded-full bg-[hsl(var(--background))]/90 px-2 py-0.5 text-[10px] text-[hsl(var(--muted-foreground))] shadow"
+          >
+            <Loader2 className="h-3 w-3 animate-spin" aria-hidden="true" />
+            {snap.livePreview.stage === "finalizing" ? "正在保存…" : "生成中 · 由糊变清"}
+          </div>
+        </div>
+      ) : null}
+
+      {assets.length === 0 && snap?.livePreview == null ? (
+        <div data-canvas-empty className="px-2 py-6 text-center text-xs text-[hsl(var(--muted-foreground))]">
+          暂无图片
+        </div>
+      ) : (
+        groups.map((group) => (
+          <div key={group.key || "_"} data-canvas-group={group.key}>
+            {view.group !== "none" && group.key !== "" ? (
+              <div className="mb-1 text-[11px] font-medium text-[hsl(var(--muted-foreground))]">
+                {view.group === "time" ? formatDayLabel(group.key) : group.key}
+              </div>
+            ) : null}
+            <div className={gridClass}>
+              {group.items.map((a) => (
+                <button
+                  key={a.attachmentId}
+                  type="button"
+                  data-canvas-cell
+                  data-att-id={a.attachmentId}
+                  onClick={() => onOpenAsset?.(a.attachmentId)}
+                  className="group relative block animate-in fade-in-0 overflow-hidden rounded-md transition-opacity duration-300 hover:opacity-90 focus:outline-none focus:ring-2 focus:ring-[hsl(var(--ring))]"
+                >
+                  {/* eslint-disable-next-line @next/next/no-img-element */}
+                  <img
+                    src={a.displayUrl}
+                    alt={a.name}
+                    className="aspect-square w-full object-cover"
+                    loading="lazy"
+                  />
+                  {a.derivedFrom !== undefined ? (
+                    <span
+                      data-canvas-cell-derived
+                      className="absolute left-1 top-1 rounded bg-black/50 px-1 text-[9px] text-white"
+                    >
+                      派生
+                    </span>
+                  ) : null}
+                </button>
+              ))}
+            </div>
+          </div>
+        ))
+      )}
+
+      {/* 客户端分页。 */}
+      {pageCount > 1 ? (
+        <div data-canvas-pager className="flex items-center justify-center gap-2 text-xs">
+          <button
+            type="button"
+            data-canvas-prev
+            disabled={page <= 0}
+            onClick={() => view.setPage(page - 1)}
+            className="rounded px-2 py-0.5 disabled:opacity-40"
+          >
+            上一页
+          </button>
+          <span data-canvas-page-indicator>
+            {page + 1} / {pageCount}
+          </span>
+          <button
+            type="button"
+            data-canvas-next
+            disabled={page >= pageCount - 1}
+            onClick={() => view.setPage(page + 1)}
+            className="rounded px-2 py-0.5 disabled:opacity-40"
+          >
+            下一页
+          </button>
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/canvas-launcher.tsx

@@ -0,0 +1,218 @@
+/**
+ * CanvasLauncher / CanvasPanel — 入口 + 面板挂载(aigc-canvas · Req 10.x)。
+ *
+ * **由 source 声明驱动,免全局门控**:agent source 在 `.pi/web` 把这两个组件挂到
+ * launcherRail / panelRight 槽,即视为"要用 Canvas"——组件被挂载即显示(`enabled` 默认 true)。
+ * 非 AIGC source 不声明这些槽 → 自然不挂载(独立性由声明缺席保证,而非 env 开关)。
+ *
+ * - **CanvasLauncher**(launcherRail 具名槽):渲染入口按钮,点击经跨 slot 共享的
+ *   `canvasOpenStore` 开合画廊面板(激活/关闭回收视图)。
+ * - **CanvasPanel**(panelRight 具名槽):宿主经 prop 注入 `surface`(launcherRail slot 拿不到 surface,
+ *   故交互画廊 / 工作台落在有 surface 的 panelRight 区);读 `canvasOpen` 开合,展开 CanvasGallery,
+ *   点格子展开 CanvasWorkbench,关闭回画廊。
+ *
+ * 两个 slot 是不同子树,经 module-level `canvasOpenStore` 联动(同一 app bundle 内共享)。
+ */
+import * as React from "react";
+import type { WebExtSurfaceAccess, ConversationAccess, WebExtension } from "@blksails/pi-web-kit";
+import type { GalleryAsset, GalleryState } from "@blksails/pi-web-tool-kit/aigc-canvas-schema";
+import { CanvasGallery } from "./canvas-gallery.js";
+import { CanvasWorkbench } from "./canvas-workbench.js";
+import { fetchVisionModels, type VisionModelOption } from "./vision-op.js";
+import { collectCanvasPluginBundles } from "./plugin-aggregation.js";
+import { useCanvasOpen } from "./use-canvas-view.js";
+import type { UploadFn } from "@blksails/pi-web-canvas-kit";
+
+const DOMAIN = "canvas";
+const STATE_KEY = `surface:${DOMAIN}`;
+
+/**
+ * @deprecated Canvas 显示已改为 source 声明驱动(挂 slot 即显示),不再依赖此 env 门控。
+ * 保留仅为向后兼容 / 可选的强制覆盖读取:`NEXT_PUBLIC_PI_WEB_CANVAS === "true" || "1"`。
+ */
+export function isCanvasEnabled(): boolean {
+  if (typeof process === "undefined") return false;
+  const v = process.env?.NEXT_PUBLIC_PI_WEB_CANVAS;
+  return v === "true" || v === "1";
+}
+
+export interface CanvasLauncherProps {
+  readonly extId?: string;
+  readonly surface?: WebExtSurfaceAccess;
+  /** 测试 / 强制覆盖门控(缺省读 env)。 */
+  readonly enabled?: boolean;
+}
+
+/** launcherRail 入口按钮(被 source 声明挂载即显示;`enabled` 显式传可覆盖,如强制关)。 */
+export function CanvasLauncher({ enabled }: CanvasLauncherProps): React.JSX.Element | null {
+  const on = enabled ?? true;
+  const { open, toggle } = useCanvasOpen();
+  if (!on) return null;
+  return (
+    <button
+      type="button"
+      data-canvas-launcher
+      aria-expanded={open}
+      onClick={toggle}
+      className="flex w-full items-center gap-2 rounded-lg px-2 py-1.5 text-left text-sm font-medium transition-colors hover:bg-[hsl(var(--accent))]"
+    >
+      <span aria-hidden>🖼️</span>
+      <span>Canvas 画廊</span>
+    </button>
+  );
+}
+
+/**
+ * 拉取可用视觉模型清单(spec canvas-vision-readout,Req 3.1/3.6)。
+ *
+ * 面板打开时拉一次,不轮询。**任何失败(网络 / 非 2xx / 解析)都记为空清单**,
+ * 既不抛也不阻断解读 —— 空清单时解读载荷不带 model,由 `image_vision` 工具弹层兜底。
+ *
+ * `override` 供测试与宿主直接注入,注入时跳过 fetch。
+ */
+function useVisionModels(
+  baseUrl: string | undefined,
+  override?: readonly VisionModelOption[],
+): readonly VisionModelOption[] {
+  const [models, setModels] = React.useState<readonly VisionModelOption[]>([]);
+
+  React.useEffect(() => {
+    if (override !== undefined) return;
+    let cancelled = false;
+    void fetchVisionModels(baseUrl).then((list) => {
+      // fetchVisionModels 内部已把一切失败折成空数组 —— 此处不需要 catch。
+      if (!cancelled && list.length > 0) setModels(list);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [baseUrl, override]);
+
+  return override ?? models;
+}
+
+export interface CanvasPanelProps {
+  readonly extId?: string;
+  readonly surface?: WebExtSurfaceAccess;
+  readonly enabled?: boolean;
+  /** 轮末 idle 边沿信号(透传 CanvasGallery → run("sync"))。 */
+  readonly syncSignal?: unknown;
+  /** 退化态图库来源(消息历史图片)。 */
+  readonly historyImages?: readonly GalleryAsset[];
+  /** 带入对话(Prompt 注入 att_id)。 */
+  readonly onBringToConversation?: (attachmentId: string) => void;
+  // ── B 档上传接缝(可注入)────────────────────────────────────────────────────
+  readonly upload?: UploadFn;
+  readonly baseUrl?: string;
+  /** 视觉模型清单覆盖(测试 / 宿主直注);缺省时经 `GET {baseUrl}/vision/models` 拉取。 */
+  readonly visionModelOptions?: readonly VisionModelOption[];
+  readonly sessionId?: string;
+  /** 会话能力对象(契约 §4.2;canvas 生成走对话流经此提交,取代 onSubmitPrompt)。 */
+  readonly conversation?: ConversationAccess;
+  /**
+   * 经宿主 Prompt 通道发用户消息(canvas 生成走对话流,LLM 调工具执行)。
+   * @deprecated 使用 `conversation`(过渡别名,行为等价)。
+   */
+  readonly onSubmitPrompt?: (text: string) => void;
+  /** 宿主转发的当前轮流式图像预览(由糊变清);配合 surface `livePreview.stage` 显示渐进图。 */
+  readonly livePreviewImage?: string;
+  /**
+   * 宿主中立注入的全部已装载扩展描述符(SlotHost 领域中立搬运;task 3.1,Req 4.1/4.2/5.1)。
+   * CanvasPanel 经 collectCanvasPluginBundles 领域聚合出 canvas 插件捆(附 manifestId 命名空间)
+   * 透传工作台。缺省/无声明 canvasPlugins → 零插件路径,行为与现状逐点一致(Req 4.3/5.3)。
+   */
+  readonly extensions?: readonly WebExtension[];
+}
+
+/** panelRight 画廊 / 工作台面板(门控关或未开 → null)。 */
+export function CanvasPanel({
+  surface,
+  enabled,
+  syncSignal,
+  historyImages,
+  onBringToConversation,
+  upload,
+  baseUrl,
+  visionModelOptions,
+  sessionId,
+  conversation,
+  onSubmitPrompt,
+  livePreviewImage,
+  extensions,
+}: CanvasPanelProps): React.JSX.Element | null {
+  const on = enabled ?? true;
+  const { open, setOpen } = useCanvasOpen();
+  const [openId, setOpenId] = React.useState<string | null>(null);
+  // 领域聚合:已装载扩展 → canvas 插件捆(附 manifestId 命名空间)。useMemo 稳定引用,使
+  // 下游工作台 kernel 装配(registerPluginBundles)不因每次渲染的新数组重建(per-mount 契约)。
+  const plugins = React.useMemo(() => collectCanvasPluginBundles(extensions), [extensions]);
+  // 视觉模型清单(canvas-vision-readout):失败/未就绪 → 空数组,解读仍可用。
+  // ⚠ 必须在下方 `if (!on || !open) return null` **之前**调用 —— hooks 不得置于 early return 之后
+  // (面板开合会改变 hook 数量,React 报「Rendered more hooks than during the previous render」)。
+  const visionModels = useVisionModels(baseUrl, visionModelOptions);
+
+  // 「点 chat 生成图 → 进 Canvas 编辑」:对话流工具卡的图带通用 `data-att-id`(见 pi-tool-part),
+  // 这里挂 document 级**委托监听**——命中即开面板并把工作台切到该 att_id(此时面板可能仍关闭,故
+  // 监听须在早返回之前、恒常挂载)。asset 生成后经 idle 边沿 sync 已进画廊 `assets`;openId 具粘性,
+  // 万一点击早于 sync,待 asset 到达即自动展开工作台。canvas 关闭态(!on)不接管。
+  React.useEffect(() => {
+    if (!on) return undefined;
+    const onDocClick = (e: MouseEvent): void => {
+      const target = e.target as HTMLElement | null;
+      const img = target?.closest?.("img[data-att-id]") as HTMLElement | null;
+      if (img === null || img === undefined) return;
+      if (img.closest("[data-pi-tool-images]") === null) return; // 仅工具卡图片
+      const id = img.getAttribute("data-att-id");
+      if (id === null || id === "") return;
+      setOpenId(id);
+      setOpen(true);
+    };
+    document.addEventListener("click", onDocClick);
+    // canvas 活跃期给 body 打标记 → 工具图悬浮态显「可点」affordance(见 styles.css)。
+    document.body.setAttribute("data-canvas-tool-image-clickable", "true");
+    return () => {
+      document.removeEventListener("click", onDocClick);
+      document.body.removeAttribute("data-canvas-tool-image-clickable");
+    };
+  }, [on, setOpen]);
+
+  if (!on || !open) return null;
+
+  const snap = surface?.getState<GalleryState>(STATE_KEY);
+  const assets: readonly GalleryAsset[] = snap?.assets ?? historyImages ?? [];
+  const workbenchAsset = openId !== null ? assets.find((a) => a.attachmentId === openId) : undefined;
+
+  return (
+    <div
+      data-canvas-panel
+      className="pi-scrollbar-ghost flex h-full min-h-0 flex-col overflow-y-auto animate-in fade-in-0 duration-200"
+    >
+      {workbenchAsset !== undefined ? (
+        <CanvasWorkbench
+          {...(surface !== undefined ? { surface } : {})}
+          asset={workbenchAsset}
+          assets={assets}
+          onClose={() => setOpenId(null)}
+          {...(onBringToConversation !== undefined ? { onBringToConversation } : {})}
+          {...(upload !== undefined ? { upload } : {})}
+          {...(baseUrl !== undefined ? { baseUrl } : {})}
+          {...(sessionId !== undefined ? { sessionId } : {})}
+          {...(conversation !== undefined ? { conversation } : {})}
+          {...(onSubmitPrompt !== undefined ? { onSubmitPrompt } : {})}
+          {...(livePreviewImage !== undefined ? { livePreviewImage } : {})}
+          {...(syncSignal !== undefined ? { syncSignal } : {})}
+          {...(plugins.length > 0 ? { plugins } : {})}
+          visionModelOptions={visionModels}
+        />
+      ) : (
+        <CanvasGallery
+          {...(surface !== undefined ? { surface } : {})}
+          {...(historyImages !== undefined ? { historyImages } : {})}
+          {...(syncSignal !== undefined ? { syncSignal } : {})}
+          {...(livePreviewImage !== undefined ? { livePreviewImage } : {})}
+          onOpenAsset={(id) => setOpenId(id)}
+        />
+      )}
+    </div>
+  );
+}