@blksails/pi-web-canvas-ui 0.2.0

package/src/client-image-ops.ts

@@ -0,0 +1,50 @@
+/**
+ * @deprecated 转发兼容层(canvas-kit-m1 · Req 5.3/5.4/7.1)——保留**一个大版本**。
+ *
+ * client-image-ops 已整体迁入 `@blksails/pi-web-canvas-kit`(bitmap-io + 类型 canonical 家),
+ * 本模块只做**显式子集转发**:原模块曾有的 31 项导出(19 值 + 12 类型)逐一对应,
+ * 深路径 import(`.../src/canvas/client-image-ops.js`)与 ui 包入口 `export *` 链双兼容。
+ *
+ * - 新代码请直接 `import ... from "@blksails/pi-web-canvas-kit"`;
+ * - 刻意用显式 `export {...} from` 而非 `export *`:canvas-kit 出口另含
+ *   WorkLayer/LoadedImage/CanvasOp 等新家类型,不得经本兼容层泄漏成 ui 的既成公开面。
+ */
+
+// ── 值导出(19)──────────────────────────────────────────────────────────────
+export {
+  clampRect,
+  rotatedSize,
+  cropImage,
+  rotateImage,
+  createMask,
+  hasExpand,
+  expandedSize,
+  outpaintImage,
+  outpaintMask,
+  flattenLayers,
+  hasMaskContent,
+  strokesToMask,
+  ANNOTATION_COLOR,
+  ANNOTATION_PALETTE,
+  drawAnnotations,
+  annotationsToImage,
+  compositeByMask,
+  parseDataUri,
+  uploadDataUri,
+} from "@blksails/pi-web-canvas-kit";
+
+// ── 类型导出(12)────────────────────────────────────────────────────────────
+export type {
+  Ctx2DLike,
+  CanvasLike,
+  CanvasFactory,
+  Rect,
+  ImageSourceLike,
+  ClientImageOpsDeps,
+  ExpandEdges,
+  FlattenLayer,
+  MaskStroke,
+  Annotation,
+  UploadFn,
+  UploadDataUriInput,
+} from "@blksails/pi-web-canvas-kit";

package/src/generate-actions.ts

@@ -0,0 +1,155 @@
+/**
+ * generate-actions — 六内置生成动作插件(task 3.1,Req 2.1/2.2/2.3/2.6)。
+ *
+ * design.md「canvas-ui · generate-actions.ts(六内置动作)」:把 canvas-workbench 内封闭的
+ * `decideGenerate` if 链自举迁移为评分制动作插件(defineCanvasAction<SurfaceOp>)。评分与
+ * buildArgs 逐分支复刻黄金基准(HEAD 的 decideGenerate 本体);execution 全为对话流通道
+ * (via:"prompt"),buildOp 内部走既有 buildSurfaceOp(golden 锁定)。内置六动作 = 行为回归线。
+ *
+ * 依赖方向(design Allowed Dependencies):本模块单向引 canvas-workbench 的**类型 GenerateDecision**
+ * 与**值 buildSurfaceOp**(3.2 才反向让 workbench 引本文件,本任务先单向,零循环);动作契约与
+ * SurfaceOp 载荷类型自 canvas-kit / web-kit。
+ *
+ * mask 透传约定(buildOp 签名保持 (args, input)):调用方(workbench)在掩码上传后把 `att_` 掩码
+ * id 经 `args.mask`(string)透传;buildOp 将其取作 buildSurfaceOp 的 opts.maskId 并从传给
+ * buildSurfaceOp 的 decision.args 中剔除 —— 保证与现 workbench 调用
+ * `buildSurfaceOp(decision, { maskId })`(decision.args 本不含 mask)逐字节等价。
+ */
+import { defineCanvasAction, type ActionInput, type CanvasRegistry } from "@blksails/pi-web-canvas-kit";
+import type { SurfaceOp } from "@blksails/pi-web-kit";
+import { buildSurfaceOp, type GenerateDecision } from "./canvas-workbench.js";
+
+/** 内置动作 id(`builtin:` 前缀)→ GenerateDecision 动作(union 字面量保持)。 */
+const ACTION_BY_ID = {
+  "builtin:outpaint": "outpaint",
+  "builtin:inpaint": "inpaint",
+  "builtin:reference": "reference",
+  "builtin:variants": "variants",
+  "builtin:reframe": "reframe",
+  "builtin:edit": "edit",
+} satisfies Record<string, GenerateDecision["action"]>;
+
+/**
+ * 内置插件 id → {@link GenerateDecision}(action + args 透传;args 同引用不复制)。
+ * 未知 id 防御性回退 edit(内置六动作恒命中映射表,回退仅为类型完备)。
+ */
+export function toGenerateDecision(
+  pluginId: string,
+  args: Record<string, unknown>,
+): GenerateDecision {
+  const action = (ACTION_BY_ID as Record<string, GenerateDecision["action"]>)[pluginId] ?? "edit";
+  return { action, args };
+}
+
+/** 公共 base 参数(image + prompt + 非空才带 model/size);逐字复刻 decideGenerate 本体。 */
+function baseArgs(input: ActionInput): Record<string, unknown> {
+  const base: Record<string, unknown> = { image: input.imageId, prompt: input.prompt };
+  if (input.model !== "") base.model = input.model;
+  if (input.size !== "") base.size = input.size;
+  return base;
+}
+
+/**
+ * prompt 通道 buildOp 工厂:mask 经 args.mask 透传约定剔除后转 opts.maskId,其余 args 原样
+ * 组装为 {@link GenerateDecision} 交 buildSurfaceOp(golden 锁定的参数渲染)。
+ */
+function makeBuildOp(id: string): (args: Record<string, unknown>) => SurfaceOp {
+  return (args) => {
+    const { mask, ...rest } = args;
+    const maskId = typeof mask === "string" ? mask : undefined;
+    return buildSurfaceOp(toGenerateDecision(id, rest), { maskId });
+  };
+}
+
+// ── 六内置动作插件(评分制;buildArgs 逐分支复刻 decideGenerate)──────────────────
+
+/** 扩图(hasExpand===true;删 size,image 由调用方替换为大画布合成图,mask 同步补充)。 */
+const outpaintAction = defineCanvasAction<SurfaceOp>({
+  id: "builtin:outpaint",
+  label: "扩图",
+  match: (input) => (input.hasExpand === true ? 100 : false),
+  buildArgs: (input) => {
+    const { size: _drop, ...rest } = baseArgs(input);
+    void _drop;
+    return rest;
+  },
+  execution: { via: "prompt", buildOp: makeBuildOp("builtin:outpaint") },
+});
+
+/** 局部重绘(hasMask;mask 由调用方在上传后经 args.mask 补充)。 */
+const inpaintAction = defineCanvasAction<SurfaceOp>({
+  id: "builtin:inpaint",
+  label: "局部重绘",
+  match: (input) => (input.hasMask ? 90 : false),
+  buildArgs: (input) => baseArgs(input),
+  execution: { via: "prompt", buildOp: makeBuildOp("builtin:inpaint") },
+});
+
+/** 融合生成(referenceIds 非空;附 reference_images,variants>=2 才附 n)。 */
+const referenceAction = defineCanvasAction<SurfaceOp>({
+  id: "builtin:reference",
+  label: "融合生成",
+  match: (input) => (input.referenceIds.length > 0 ? 80 : false),
+  buildArgs: (input) => {
+    const args: Record<string, unknown> = {
+      ...baseArgs(input),
+      reference_images: [...input.referenceIds],
+    };
+    if (input.variants >= 2) args.n = input.variants;
+    return args;
+  },
+  execution: { via: "prompt", buildOp: makeBuildOp("builtin:reference") },
+});
+
+/** 生成变体(variants>=2;附 n)。 */
+const variantsAction = defineCanvasAction<SurfaceOp>({
+  id: "builtin:variants",
+  label: "生成变体",
+  match: (input) => (input.variants >= 2 ? 70 : false),
+  buildArgs: (input) => ({ ...baseArgs(input), n: input.variants }),
+  execution: { via: "prompt", buildOp: makeBuildOp("builtin:variants") },
+});
+
+/** 重构比例(prompt 空 && size 非空;base 原样,reframe 默认提示词由 buildSurfaceOp 补)。 */
+const reframeAction = defineCanvasAction<SurfaceOp>({
+  id: "builtin:reframe",
+  label: "重构比例",
+  match: (input) => (input.prompt.trim() === "" && input.size !== "" ? 60 : false),
+  buildArgs: (input) => baseArgs(input),
+  execution: { via: "prompt", buildOp: makeBuildOp("builtin:reframe") },
+});
+
+/** 整图编辑(恒适用兜底)。 */
+const editAction = defineCanvasAction<SurfaceOp>({
+  id: "builtin:edit",
+  label: "生成",
+  match: () => 10,
+  buildArgs: (input) => baseArgs(input),
+  execution: { via: "prompt", buildOp: makeBuildOp("builtin:edit") },
+});
+
+/**
+ * 六内置生成动作(注册序 = 评分降序,便于阅读;resolveAction 按分排序,注册序仅决定同分先者
+ * 与 registry.actions 枚举序)。decideGenerate 优先级链的自举复刻。
+ */
+export const BUILTIN_GENERATE_ACTIONS: readonly CanvasActionPluginOp[] = [
+  outpaintAction,
+  inpaintAction,
+  referenceAction,
+  variantsAction,
+  reframeAction,
+  editAction,
+];
+
+// 载荷类型别名(六插件的 TOp 恒为 SurfaceOp)。
+type CanvasActionPluginOp = ReturnType<typeof defineCanvasAction<SurfaceOp>>;
+
+/**
+ * 六内置动作按序注册进 per-instance 注册表(registerBuiltinTools 同构);返回聚合退订。
+ */
+export function registerBuiltinGenerateActions(reg: CanvasRegistry): () => void {
+  const unregisters = BUILTIN_GENERATE_ACTIONS.map((a) => reg.registerAction(a));
+  return () => {
+    for (const off of unregisters) off();
+  };
+}

package/src/index.ts

@@ -0,0 +1,122 @@
+/**
+ * @blksails/pi-web-canvas-ui — canvas 领域组件 canonical 家唯一出口(出口纪律)。
+ *
+ * 纪律(Req 2.1/2.2,canvas-ui-m15 design「Boundary Commitments」):
+ * - 出口面 = 自 packages/ui/src/canvas/ 迁入的 8 文件 **HEAD 导出全集的去重并集**
+ *   (严格超集于迁移前 ui index 的 canvas 兼容导出块:深路径 named import 与
+ *   设置面板消费——aigc-model-meta 三导出、workbench 的 decideGenerate/
+ *   buildSurfaceOp/buildToolPrompt、use-canvas-view 的 canvasViewStore 等——
+ *   均须从包入口可达);
+ * - 组件语义/DOM/data-* 锚点与迁移前逐一致(原样迁入,仅 import 来源改线);
+ * - 依赖方向:ui 经转发层消费本包,反向禁止(本包零 @blksails/pi-web-ui 依赖);
+ *   canvas-kit 消费只走主入口,禁深路径;
+ * - 此出口是 semver 承诺面:任何导出的增删改按 semver 语义对待;
+ *   显式清单 re-export,禁 export *(防内部件经链泄漏成既成公开面);
+ * - client-image-ops 显式清单刻意排除 LoadedImage(canvas-workbench 单点
+ *   re-export),8 文件无跨文件重名。
+ */
+
+// aigc-model-meta — provider 元数据(设置面板 aigc-model-toggles-field 跨包消费)。
+export { PROVIDER_META, displayNameOf, ProviderBadge } from "./aigc-model-meta.js";
+
+// aigc-quick-settings — 输入区工具排 AIGC 快捷设置(模型/尺寸偏好;promptToolbar 槽挂载)。
+export { AigcQuickSettings } from "./aigc-quick-settings.js";
+export type { AigcQuickSettingsProps } from "./aigc-quick-settings.js";
+
+// canvas-gallery — 画廊(domain="canvas" AAS 投影)。
+export { CanvasGallery } from "./canvas-gallery.js";
+export type { CanvasGalleryProps } from "./canvas-gallery.js";
+
+// canvas-launcher — 门控(NEXT_PUBLIC_PI_WEB_CANVAS)+ 画布面板装配。
+export { CanvasLauncher, CanvasPanel, isCanvasEnabled } from "./canvas-launcher.js";
+export type { CanvasLauncherProps, CanvasPanelProps } from "./canvas-launcher.js";
+
+// canvas-workbench — 二创工作台(编辑器 + 生成决策纯函数 + inpaint 回合成)。
+export {
+  CanvasWorkbench,
+  decideGenerate,
+  buildSurfaceOp,
+  buildToolPrompt,
+  composeInpaintBack,
+  resolveToolRailTitle,
+} from "./canvas-workbench.js";
+export type {
+  CanvasWorkbenchProps,
+  GenerateDecision,
+  GenerateDecisionInput,
+  ImageLoader,
+  LoadedImage,
+} from "./canvas-workbench.js";
+
+// generate-actions — 六内置生成动作插件(评分制决策链;canvas-kit resolveAction 消费,
+// workbench 装配期注册进 per-instance 注册表)。
+export {
+  BUILTIN_GENERATE_ACTIONS,
+  registerBuiltinGenerateActions,
+} from "./generate-actions.js";
+
+// plugin-aggregation — 宿主中立扩展描述符 → canvas 插件捆聚合纯函数(task 3.1;
+// CanvasPanel extensions → workbench plugins 的领域聚合点)。
+export { collectCanvasPluginBundles } from "./plugin-aggregation.js";
+export type { NamespacedPluginBundles } from "./plugin-aggregation.js";
+
+// lineage-view — 血缘树视图。
+export { LineageView, buildLineageTree } from "./lineage-view.js";
+export type { LineageViewProps, LineageNode } from "./lineage-view.js";
+
+// use-canvas-view — 画布视图状态(open/density/group 外部 store + hooks)。
+export {
+  useCanvasView,
+  useCanvasOpen,
+  canvasOpenStore,
+  canvasViewStore,
+  CANVAS_PAGE_SIZE,
+} from "./use-canvas-view.js";
+export type {
+  CanvasDensity,
+  CanvasGroupMode,
+  CanvasViewState,
+  UseCanvasViewResult,
+} from "./use-canvas-view.js";
+
+// client-image-ops — @deprecated 转发兼容层(canvas-kit canonical 家的显式子集
+// 转发:19 值 + 12 类型;刻意不含 LoadedImage/WorkLayer/CanvasOp 等新家类型)。
+export {
+  clampRect,
+  rotatedSize,
+  cropImage,
+  rotateImage,
+  createMask,
+  hasExpand,
+  expandedSize,
+  outpaintImage,
+  outpaintMask,
+  flattenLayers,
+  hasMaskContent,
+  strokesToMask,
+  ANNOTATION_COLOR,
+  ANNOTATION_PALETTE,
+  drawAnnotations,
+  annotationsToImage,
+  compositeByMask,
+  parseDataUri,
+  uploadDataUri,
+} from "./client-image-ops.js";
+export type {
+  Ctx2DLike,
+  CanvasLike,
+  CanvasFactory,
+  Rect,
+  ImageSourceLike,
+  ClientImageOpsDeps,
+  ExpandEdges,
+  FlattenLayer,
+  MaskStroke,
+  Annotation,
+  UploadFn,
+  UploadDataUriInput,
+} from "./client-image-ops.js";
+
+// ── vision readout(spec canvas-vision-readout):解读载荷构造器 + 模型选项类型 ──────
+export { buildVisionOp, DEFAULT_READOUT_QUESTION } from "./vision-op.js";
+export type { BuildVisionOpInput, VisionModelOption } from "./vision-op.js";

package/src/lineage-view.tsx

@@ -0,0 +1,170 @@
+/**
+ * LineageView — C 档灵感放大(aigc-canvas · Req 6.1 / 6.2 / 6.3 / 6.4)。
+ *
+ * 全部从快照派生(UI 本地,不发命令):
+ *  - **血缘树**:读 `derivedFrom` 建父子关系;
+ *  - **参数复用**:读选中资产 `genParams` 预填 A 档表单(经 `onReuseParams` 回调);
+ *  - **A-B 对比**:选两张图并排(读 `displayUrl`);
+ *  - **当前工作图链**:沿 `derivedFrom` 的一条 UI 本地路径,支持前进 / 回退。
+ */
+import * as React from "react";
+import type { GalleryAsset } from "@blksails/pi-web-tool-kit/aigc-canvas-schema";
+import { Button } from "@blksails/pi-web-primitives";
+import { Card } from "@blksails/pi-web-primitives";
+import { cn } from "@blksails/pi-web-primitives";
+
+export interface LineageNode {
+  asset: GalleryAsset;
+  children: LineageNode[];
+}
+
+/** 从扁平资产列表按 `derivedFrom` 建血缘树(纯函数;缺失父节点者作为根)。 */
+export function buildLineageTree(assets: readonly GalleryAsset[]): LineageNode[] {
+  const byId = new Map<string, LineageNode>();
+  for (const a of assets) byId.set(a.attachmentId, { asset: a, children: [] });
+  const roots: LineageNode[] = [];
+  for (const node of byId.values()) {
+    const parentId = node.asset.derivedFrom;
+    const parent = parentId !== undefined ? byId.get(parentId) : undefined;
+    if (parent !== undefined) parent.children.push(node);
+    else roots.push(node);
+  }
+  return roots;
+}
+
+function TreeNode({
+  node,
+  depth,
+  onReuseParams,
+  currentId,
+}: {
+  node: LineageNode;
+  depth: number;
+  onReuseParams?: (asset: GalleryAsset) => void;
+  currentId?: string;
+}): React.JSX.Element {
+  const a = node.asset;
+  const isCurrent = currentId !== undefined && a.attachmentId === currentId;
+  return (
+    <>
+      <Card
+        data-lineage-node
+        data-att-id={a.attachmentId}
+        data-depth={depth}
+        className={cn(
+          "group relative w-20 shrink-0 overflow-hidden p-0",
+          isCurrent && "ring-2 ring-[hsl(var(--ring))]",
+        )}
+      >
+        {/* eslint-disable-next-line @next/next/no-img-element */}
+        <img src={a.displayUrl} alt={a.name} width={80} height={80} className="h-20 w-20 object-cover" />
+        <div className="pointer-events-none absolute inset-x-0 top-0 truncate bg-gradient-to-b from-black/50 to-transparent px-1 py-0.5 text-[10px] text-white">
+          {a.name}
+        </div>
+        {a.genParams !== undefined ? (
+          <Button
+            variant="secondary"
+            size="sm"
+            data-lineage-reuse
+            data-att-id={a.attachmentId}
+            onClick={() => onReuseParams?.(a)}
+            className="absolute inset-x-0 bottom-0 hidden h-6 rounded-none px-1 text-[10px] group-hover:flex"
+          >
+            复用参数
+          </Button>
+        ) : null}
+      </Card>
+      {node.children.map((c) => (
+        <TreeNode
+          key={c.asset.attachmentId}
+          node={c}
+          depth={depth + 1}
+          {...(onReuseParams !== undefined ? { onReuseParams } : {})}
+          {...(currentId !== undefined ? { currentId } : {})}
+        />
+      ))}
+    </>
+  );
+}
+
+export interface LineageViewProps {
+  readonly assets: readonly GalleryAsset[];
+  /** A-B 对比:选中的两个 att_id(取前两项)。 */
+  readonly compareIds?: readonly string[];
+  /** 当前工作图链(att_id 序列)。 */
+  readonly chain?: readonly string[];
+  readonly onReuseParams?: (asset: GalleryAsset) => void;
+  readonly onChainStep?: (direction: "back" | "forward", id: string) => void;
+  /** 当前工作图 att_id(仅高亮,可选增强)。 */
+  readonly currentId?: string;
+}
+
+export function LineageView({
+  assets,
+  compareIds,
+  chain,
+  onReuseParams,
+  currentId,
+}: LineageViewProps): React.JSX.Element {
+  const tree = React.useMemo(() => buildLineageTree(assets), [assets]);
+  const byId = React.useMemo(() => {
+    const m = new Map<string, GalleryAsset>();
+    for (const a of assets) m.set(a.attachmentId, a);
+    return m;
+  }, [assets]);
+
+  const comparePair = (compareIds ?? [])
+    .slice(0, 2)
+    .map((id) => byId.get(id))
+    .filter((a): a is GalleryAsset => a !== undefined);
+
+  return (
+    <div data-lineage-view className="flex flex-col gap-2 text-xs">
+      {/* 血缘树(横向缩略条)。 */}
+      <div className="mb-0.5 font-medium text-[hsl(var(--muted-foreground))]">版本血缘</div>
+      <div
+        data-lineage-tree
+        className="pi-scrollbar-thin flex gap-2 overflow-x-auto pb-1"
+      >
+        {tree.map((n) => (
+          <TreeNode
+            key={n.asset.attachmentId}
+            node={n}
+            depth={0}
+            {...(onReuseParams !== undefined ? { onReuseParams } : {})}
+            {...(currentId !== undefined ? { currentId } : {})}
+          />
+        ))}
+      </div>
+
+      {/* A-B 对比。 */}
+      {comparePair.length === 2 ? (
+        <div data-lineage-compare className="grid grid-cols-2 gap-1">
+          {comparePair.map((a) => (
+            // eslint-disable-next-line @next/next/no-img-element
+            <img
+              key={a.attachmentId}
+              data-compare-img
+              data-att-id={a.attachmentId}
+              src={a.displayUrl}
+              alt={a.name}
+              className="w-full rounded object-contain"
+            />
+          ))}
+        </div>
+      ) : null}
+
+      {/* 当前工作图链。 */}
+      {chain !== undefined && chain.length > 0 ? (
+        <div data-lineage-chain className="flex flex-wrap items-center gap-1">
+          {chain.map((id, i) => (
+            <span key={id} data-chain-step data-att-id={id} className="opacity-70">
+              {byId.get(id)?.name ?? id}
+              {i < chain.length - 1 ? " → " : ""}
+            </span>
+          ))}
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/plugin-aggregation.ts

@@ -0,0 +1,51 @@
+/**
+ * plugin-aggregation — 宿主中立扩展描述符 → canvas 插件捆聚合(task 3.1,
+ * Req 4.1/4.2/4.3/5.1/5.2/5.3;design「宿主中立注入与聚合」)。
+ *
+ * 宿主(pi-chat)对 canvas 领域中立:只把全部已装载扩展描述符(readonly WebExtension[])
+ * 整体经 SlotHost 搬运进 CanvasPanel,不解析内容。真正的**领域聚合**发生在此:提取各扩展
+ * 声明的 `canvasPlugins` 捆,附来源命名空间(= manifestId),交由 CanvasWorkbench 的
+ * registerPluginBundles 施加 `<namespace>:` 前缀与拓扑校验。
+ *
+ * 类型收敛(design「Allowed Dependencies」):web-kit 的 CanvasPluginBundle 是**最小结构镜像**
+ * (组件位 unknown 宽型,便于宿主中立搬运);canonical 家在 canvas-kit(具体插件形状)。二者
+ * 无包依赖边,结构上 kit→web-kit 单向可赋值(窄→宽)。聚合是反向的 web-kit→kit **窄化**:
+ * 运行期安全(source 作者以 canvas-kit defineXxx 声明捆,transport 仅把组件位擦除为 unknown),
+ * 类型层以断言收窄(见 collectCanvasPluginBundles 的 `as`;双向可赋值防漂移断言在
+ * plugin-aggregation.test.ts,capability-type-sync M2 先例)。
+ */
+import type { WebExtension } from "@blksails/pi-web-kit";
+import type { CanvasPluginBundle } from "@blksails/pi-web-canvas-kit";
+
+/** 单个来源(扩展)贡献的 canvas 插件捆集合 + 其命名空间(= manifestId)。 */
+export interface NamespacedPluginBundles {
+  /** 来源命名空间(registerPluginBundles 据此前缀化捆内 id/type;= WebExtension.manifestId)。 */
+  readonly namespace: string;
+  /** 该来源声明的插件捆(canonical canvas-kit 型;已从 web-kit 镜像窄化)。 */
+  readonly bundles: readonly CanvasPluginBundle[];
+}
+
+/**
+ * 从已装载扩展描述符集提取各自的 canvas 插件捆,附来源命名空间(manifestId)。
+ *
+ * - 无 `canvasPlugins` 声明或空数组的扩展被**剔除**(不产生空条目 → 零影响,Req 4.3);
+ * - 验签失败的插件包根本不进 `extensions` 列表(装载链既有容错)→ 聚合天然不含、不崩(Req 5.3);
+ * - `undefined` 入参(宿主未注入)→ 空聚合(现状路径,Req 4.3);
+ * - 车道①(source 自带)与车道②(已装包 webext,同 defineWebExtension 形态)统一经此消费(Req 5.1/5.2)。
+ *
+ * 纯函数(无副作用;bundles 引用原样透传,仅类型收窄不拷贝/不 mutate 作者只读声明)。
+ */
+export function collectCanvasPluginBundles(
+  extensions?: readonly WebExtension[],
+): readonly NamespacedPluginBundles[] {
+  if (extensions === undefined) return [];
+  const out: NamespacedPluginBundles[] = [];
+  for (const ext of extensions) {
+    const plugins = ext.canvasPlugins;
+    if (plugins === undefined || plugins.length === 0) continue;
+    // web-kit 镜像型 → canvas-kit canonical 型窄化(结构上 kit 可赋给 web-kit,反向窄化断言;
+    // 运行期安全见模块头注)。整捆引用透传,前缀化留 registerPluginBundles(装配层)。
+    out.push({ namespace: ext.manifestId, bundles: plugins as readonly CanvasPluginBundle[] });
+  }
+  return out;
+}

package/src/styles.css

@@ -0,0 +1,24 @@
+/*
+ * @blksails/pi-web-canvas-ui — canvas 领域样式(自 packages/ui/src/styles.css 随迁,canvas-ui-m15 Req 2.4)。
+ * 两段原样迁入:工具图 affordance + 棋盘透明底;由 app 装配层 @import 引入。
+ */
+
+/* Canvas 活跃期:对话流工具卡里带 att_ 的生成图可点(→ 进 Canvas 工作台编辑)。悬浮示可点。 */
+[data-canvas-tool-image-clickable] [data-pi-tool-images] img[data-att-id] {
+  cursor: pointer;
+}
+[data-canvas-tool-image-clickable] [data-pi-tool-images] img[data-att-id]:hover {
+  outline: 2px solid hsl(var(--ring));
+  outline-offset: 1px;
+}
+
+/* 棋盘透明底:Canvas 舞台展示透明图区(16px 方格,主题 muted 半透)。 */
+.canvas-checkerboard {
+  background-image:
+    linear-gradient(45deg, hsl(var(--muted) / 0.4) 25%, transparent 25%),
+    linear-gradient(-45deg, hsl(var(--muted) / 0.4) 25%, transparent 25%),
+    linear-gradient(45deg, transparent 75%, hsl(var(--muted) / 0.4) 75%),
+    linear-gradient(-45deg, transparent 75%, hsl(var(--muted) / 0.4) 75%);
+  background-size: 16px 16px;
+  background-position: 0 0, 0 8px, 8px -8px, -8px 0;
+}