@groupviz/react 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rrCathy,LDK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# @groupviz/react
+
+GroupViz 群论可视化的 **React 视图组件**。与 [@groupviz/core](../core) 配套：core 出数据，react 出图。
+
+**包含**：10 个视图 Scene（`SetView` / `CycleView` / `CayleyView` / `TableView` / `CosetStripScene` /
+`ActionScene` / `HomomorphismScene` / `SublatticeScene` / `Cayley3DScene` / `SymmetryViewScene`）、
+窗口容器壳 `SceneWindow`、`I18nProvider`（内置中 / 英文语言包）、`theme.css`（深 / 浅色主题变量）。
+
+**安装**（npm 自动解析 peer：react 19 / three / @react-three/fiber / @react-three/drei / katex）
+
+```
+npm i @groupviz/core @groupviz/react
+```
+
+**快速开始**
+
+```tsx
+import { I18nProvider, SetView } from '@groupviz/react'
+import '@groupviz/react/theme.css'
+import { createGroupFromSymbol } from '@groupviz/core'
+
+const group = createGroupFromSymbol('C_{6}')
+
+export function App() {
+  return (
+    <I18nProvider>
+      <div style={{ width: 480, height: 360, background: '#0f1115' }}>
+        <SetView
+          group={group}
+          selectedElements={new Set()}
+          canvasTransform={{ x: 0, y: 0, scale: 1 }}
+          viewBoxSize={{ width: 480, height: 360 }}
+        />
+      </div>
+    </I18nProvider>
+  )
+}
+```
+
+```ts
+import '@groupviz/react/theme.css' // 主题样式（模块化工程可 import 到全局）
+```
+
+**交互约定**：Scene 是纯受控内核——标签显隐 / hover 气泡 / 选中高亮等由宿主通过 props
+（`showLabels` / `onHover` / `onSelect`）注入；更多组合示例见仓库 `examples/host-minimal/`。
+
+完整文档：[GroupViz 主仓库](https://github.com/rrCathy/GroupViz)（docs/VIEWS.md · docs/PRESENTATION.md）。
+MIT License。

package/components/Canvas/ActionScene.d.ts

@@ -0,0 +1,46 @@
+import type { Group, GroupActionArrow, GroupActionComputation, GroupActionKind, GroupElement, CanvasTransform } from '@groupviz/core';
+import { type CustomArrowError } from '@groupviz/core';
+export interface ActionSceneProps {
+    group: Group;
+    /** 作用来源；窗口范围 conjugation/regular/custom（sylow/coset 仅主画布壳会传） */
+    kind: GroupActionKind;
+    computation: GroupActionComputation | null;
+    /** custom 编辑模式（渲染 CustomActionEditor，不吃 canvasTransform） */
+    editing?: boolean;
+    /** 编辑模式 |X|（1..20） */
+    setSize?: number | null;
+    /** 编辑模式箭头列表 */
+    arrows?: GroupActionArrow[];
+    /** 编辑模式错误（画布内红字提示） */
+    error?: CustomArrowError | null;
+    onAddArrow?: (from: number, to: number, generatorId?: string | null) => void;
+    onBindArrow?: (from: number, to: number, generatorId: string) => void;
+    onRemoveArrow?: (from: number, generatorId?: string | null, to?: number) => void;
+    onReplaceGenArrows?: (generatorId: string | null, pairs: [number, number][]) => void;
+    /** 选中集合元素索引（OST 交互 + 底部 Stab box） */
+    selectedElement?: number | null;
+    onSelectedElementChange?: (x: number | null) => void;
+    /** 悬停群元素 id（金色箭头联动；主画布壳接 context） */
+    hoveredElement?: string | null;
+    onHoverElementChange?: (id: string | null) => void;
+    /** chips 群元素点击 → 主画布全局选中；窗口不传 */
+    onSetElementSelect?: (id: string) => void;
+    /** 节点常驻标签 + 顶部轨道 chips 区；缺省 true（主画布观感）。窗口传 false：
+     *  节点空圈 + chips 区隐藏 + conjugation/regular 节点悬停就地气泡 */
+    showLabels?: boolean;
+    /** 悬停就地气泡回调（窗口接 handleHover） */
+    onHover?: (el: GroupElement | null, anchor?: {
+        x: number;
+        y: number;
+    } | null) => void;
+    /** 内容平移缩放（主画布壳接 canvasTransform，窗口接窗口 ct）；编辑模式不吃 */
+    canvasTransform?: CanvasTransform;
+    /** 视口尺寸；fitVB 自适应时作为兜底 */
+    viewBoxSize?: {
+        width: number;
+        height: number;
+    };
+    /** sylow 作用的素数（banner 标题用）；窗口不传 */
+    prime?: number | null;
+}
+export declare function ActionScene({ group, kind, computation, editing, setSize, arrows, error, onAddArrow, onBindArrow, onRemoveArrow, onReplaceGenArrows, selectedElement, onSelectedElementChange, hoveredElement, onHoverElementChange, onSetElementSelect, showLabels, onHover, canvasTransform, viewBoxSize, prime, }: ActionSceneProps): import("react/jsx-runtime").JSX.Element;

package/components/Canvas/Cayley3DScene.d.ts

@@ -0,0 +1,35 @@
+import type { Group, MultiplyType, Layout3D } from '@groupviz/core';
+import type { CayleyActionParam } from '@groupviz/core';
+export interface Cayley3DSceneProps {
+    /** 群；null → .view-empty 占位 */
+    group: Group | null;
+    /** 选中元素集合（调用方自持会话态） */
+    selectedElements: Set<string>;
+    /** 节点点击选中回调；缺省 no-op */
+    onSelectElement?: (id: string, additive: boolean) => void;
+    /** 作用边元素集合；缺省 = 群生成元（normalizeCayleyActions 归一化） */
+    actions?: CayleyActionParam[];
+    /** 边的乘法方向；缺省 'right' */
+    multiplyType?: MultiplyType;
+    /** 3D 布局形状；缺省 getDefaultLayout3D(group) */
+    layout3D?: Layout3D;
+    /** 节点球缩放 0.5–2.0；缺省 1 */
+    nodeScale?: number;
+    /** 自动旋转；缺省 false。prop 优先，未设置时内部 ▶ 按钮本地态兜底 */
+    autoRotate?: boolean;
+    /** 是否显示 hover/选中 Html 标签；缺省 true */
+    showLabels?: boolean;
+    /** 锁定相机交互（轨道拖拽/滚轮缩放/右键平移）；保留点击选中与双击复位 */
+    locked?: boolean;
+    /** 子集高亮（元素 id → 颜色）；context subsets 的同构映射 */
+    subsetHighlights?: {
+        elementIds: string[];
+        color: string;
+    }[];
+    /** 渲染主题（canvas 背景 / label 阴影）。缺省回落到 ThemeContext（无 Provider 时 'dark'）；
+     *  主应用壳不传即保持现状（读全局主题），包消费端显式传以与容器主题解耦 */
+    theme?: 'dark' | 'light';
+}
+/** 受控 3D 凯莱图（props 驱动；ViewWindow 与测试用）。空群渲染占位，非空渲染 R3F 场景。 */
+export declare function Cayley3DScene(props: Cayley3DSceneProps): import("react/jsx-runtime").JSX.Element;
+/** 主应用入口（context 组装壳）：从全局 Provider 组装 Cayley3DScene 所需 props（保留原行为） */ 

package/components/Canvas/CayleyView.d.ts

@@ -0,0 +1,36 @@
+import type { CanvasTransform, CayleyShape2D, Group, GroupElement, MultiplyType } from '@groupviz/core';
+import type { CayleyActionParam } from '@groupviz/core';
+export interface CayleyViewProps {
+    group: Group | null;
+    selectedElements: Set<string>;
+    canvasTransform: CanvasTransform;
+    viewBoxSize: {
+        width: number;
+        height: number;
+    };
+    /** 缺省 getDefaultShape2D(group) */
+    shape2D?: CayleyShape2D;
+    /** 缺省 'right'（右乘 a·c） */
+    multiplyType?: MultiplyType;
+    /** 缺省 = 群生成元集合；条目缺省 enabled=true、color=COLOR_PALETTE 按序 */
+    actions?: CayleyActionParam[];
+    /** 缺省 28（与主视图非复合节点一致） */
+    nodeRadius?: number;
+    /** 缺省 true；>60 阶沿用主视图自适应规则（选中后仅选中节点显示标签）。嵌入小窗（ViewWindow）传 false 彻底不显示节点标签、读元素靠悬停就地气泡 */
+    showLabels?: boolean;
+    /** 缺省 false；true 时禁用节点拖拽（供 ViewWindow 锁定状态使用，点击选中仍保留） */
+    locked?: boolean;
+    onSelect?: (elId: string, additive: boolean) => void;
+    /**
+     * 悬停回调：第一个参数是元素，第二个是节点在 viewport 内的屏幕锚点
+     * （viewBox 坐标经 canvasTransform 映射，供上层渲染"就地气泡"tooltip）。
+     */
+    onHover?: (el: GroupElement | null, anchor?: {
+        x: number;
+        y: number;
+    } | null) => void;
+    /** 当前悬停元素 id；用于在该节点外圈绘制高亮环（让"悬停→信息"在视觉上立得住） */
+    hoveredElementId?: string | null;
+    noGroupText?: string;
+}
+export declare function CayleyView({ group, selectedElements, canvasTransform, viewBoxSize, shape2D: shapeProp, multiplyType: multiplyProp, actions: actionsProp, nodeRadius: nodeRadiusProp, showLabels: showLabelsProp, locked, onSelect, onHover, hoveredElementId, noGroupText, }: CayleyViewProps): import("react/jsx-runtime").JSX.Element;

package/components/Canvas/CosetStripScene.d.ts

@@ -0,0 +1,41 @@
+import type { Group, GroupElement } from '@groupviz/core';
+export interface CosetStripSceneProps {
+    group: Group | null;
+    selectedElements?: Set<string>;
+    canvasTransform?: {
+        x: number;
+        y: number;
+        scale: number;
+    };
+    viewBoxSize: {
+        width: number;
+        height: number;
+    };
+    /** 元素 → 陪集下标（与 SetView 同约定）。缺省空 Map 显示空态文案 */
+    cosetElementMap?: Map<string, number> | null;
+    /** 每条陪集的条带颜色 */
+    cosetColors?: string[];
+    /** 被高亮的陪集下标集合（点击选中元素 → 其所在陪集） */
+    cosetHighlightSet?: Set<number>;
+    /** 已保存子集（元素集合 + 颜色），命中元素描边用子集色 */
+    subsets?: Array<{
+        elementIds: string[];
+        color: string;
+    }>;
+    /** 节点常驻标签；缺省 true（主画布行为）；嵌入窗口默认关，读元素靠 hover */
+    showLabels?: boolean;
+    /** H 条带上方的 H-Cayley 小圈；缺省 true（主画布行为），嵌入窗口默认关省空间 */
+    showSubgroupCayley?: boolean;
+    /** 点击节点：缺省无操作（主画布壳接全局选中，窗口引擎自己维护会话态） */
+    onSelect?: (elId: string, additive: boolean) => void;
+    /** 悬停节点：主画布走全局 Hover，窗口经 anchor 就地气泡 */
+    onHover?: (el: GroupElement | null, anchor?: {
+        x: number;
+        y: number;
+    } | null) => void;
+    noGroupText?: string;
+    /** 有群但无陪集数据时的文案（缺省 i18n canvas.cosetStripNoCosets，主应用语境）；
+     *  窗口引擎可传自定义提示（如本地枚举上限） */
+    noCosetsText?: string;
+}
+export declare function CosetStripScene({ group, selectedElements, canvasTransform, viewBoxSize, cosetElementMap, cosetColors, cosetHighlightSet, subsets, showLabels, showSubgroupCayley, onSelect, onHover, noGroupText, noCosetsText, }: CosetStripSceneProps): import("react/jsx-runtime").JSX.Element;

package/components/Canvas/CycleView.d.ts

@@ -0,0 +1,40 @@
+import type { CanvasTransform, Group, GroupElement, NodePosition } from '@groupviz/core';
+export interface CycleViewProps {
+    group: Group | null;
+    selectedElements: Set<string>;
+    canvasTransform: CanvasTransform;
+    viewBoxSize: {
+        width: number;
+        height: number;
+    };
+    /** 缺省 false（显示全部循环子群）；true 时仅显示极大循环并启用 planar 布局 */
+    showMaximalCycles?: boolean;
+    /** 节点半径；缺省 24 */
+    nodeRadius?: number;
+    /** 是否显示节点标签；缺省 true（>60 阶自适应） */
+    showLabels?: boolean;
+    /** 是否显示每个循环的 ⟨g⟩ ≅ Z_n 标注；缺省 true */
+    showCycleLabels?: boolean;
+    /** 缺省 false；true 时禁用节点拖拽（供 ViewWindow 锁定状态使用，点击选中仍保留） */
+    locked?: boolean;
+    /** 子集着色（子集→元素映射）；缺省空 */
+    subsets?: Array<{
+        elementIds: string[];
+        color: string;
+    }>;
+    selfInverseElementId?: string | null;
+    cosetElementMap?: Map<string, number>;
+    cosetHighlightSet?: Set<number>;
+    cosetColors?: string[];
+    /** 外部持久化节点位置（主画布共享位置）；缺省使用本地拖拽态 */
+    getNodePosition?: (elId: string) => NodePosition | undefined;
+    /** 拖拽回写节点位置；缺省写入本地拖拽态 */
+    onNodePositionChange?: (elId: string, x: number, y: number) => void;
+    onSelect?: (elId: string, additive: boolean) => void;
+    onHover?: (el: GroupElement | null, anchor?: {
+        x: number;
+        y: number;
+    } | null) => void;
+    noGroupText?: string;
+}
+export declare function CycleView({ group, selectedElements, canvasTransform, viewBoxSize, showMaximalCycles, nodeRadius, showLabels, showCycleLabels, locked, subsets, selfInverseElementId, cosetElementMap, cosetHighlightSet, cosetColors, getNodePosition, onNodePositionChange, onSelect, onHover, noGroupText, }: CycleViewProps): import("react/jsx-runtime").JSX.Element;

package/components/Canvas/HomomorphismScene.d.ts

@@ -0,0 +1,24 @@
+import { type ReactNode } from 'react';
+import type { Group, GroupElement, HomomorphismResult } from '@groupviz/core';
+export interface HomomorphismSceneProps {
+    source: Group | null;
+    target: Group | null;
+    mapping: Map<string, string>;
+    /** 预计算结果（null=源/目标缺失或 mapping 为空）。缺省（undefined）由 Scene 内部 verifyHomomorphism 推导 */
+    result?: HomomorphismResult | null;
+    /** 映射显示名（TeX 或纯文本）；缺省 `${source.symbol} → ${target.symbol}` */
+    name?: string;
+    /** 定理模式（第一同构定理动画）；缺省 false。动画内容由 theoremAnimation 注入 */
+    theoremMode?: boolean;
+    onTheoremModeChange?: (v: boolean) => void;
+    /** 定理动画内容（主画布壳注入 <FirstIsomorphismAnimation>）；窗口不传 */
+    theoremAnimation?: ReactNode;
+    /** 节点常驻标签；缺省 true（主画布行为）；嵌入窗口默认关，读元素靠悬停就地气泡 */
+    showLabels?: boolean;
+    /** 悬停节点（源/目标元素 + 视口内屏幕锚点）；主画布壳不传（内部高亮即可），窗口接就地气泡 */
+    onHover?: (el: GroupElement | null, anchor?: {
+        x: number;
+        y: number;
+    } | null) => void;
+}
+export declare function HomomorphismScene({ source, target, mapping, result, name, theoremMode, onTheoremModeChange, theoremAnimation, showLabels, onHover, }: HomomorphismSceneProps): import("react/jsx-runtime").JSX.Element;

package/components/Canvas/SceneWindow.d.ts

@@ -0,0 +1,83 @@
+/**
+ * SceneWindow — @groupviz/react 通用窗口壳容器（FGVE「壳能力参数化」）。
+ *
+ * 定位：ViewWindow（主应用浮动窗壳）与「裸 Scene 直渲」之间的中间形态。壳只管
+ * 窗口 chrome，children 渲任意 packaged Scene（消费端自持 Scene props，本组件
+ * 零 Scene 耦合）。两个层次控制壳能力：
+ *
+ *   shell: 'none'   → 裸内容容器（等同 Frame 直嵌，不带任何 chrome）
+ *          'chrome' → 标题栏 + 能力按钮 + 拖拽/resize + ⚙ View Config 面板 + persist
+ *   capabilities:    chrome 形态下逐项露/藏内容；不传 = 全开，显式 false 关闭该项。
+ *
+ * 零 context / i18n / zod 依赖：主题用 theme prop（颜色自含 hex，不读 CSS 变量），
+ * 按钮图标 + 英文 title（与主应用 FloatingViewWindow 一致），持久化 minimal
+ * localStorage（try/catch 宽容，不引 utils/persistence 的 zod 校验链）。
+ *
+ * 约定：parent 需 position:relative；chrome 窗口 absolute 定位可拖可缩；shell:'none'
+ * 时返回普通块级容器（不脱离文档流）。
+ */
+import { type ReactNode } from 'react';
+import type { Group } from '@groupviz/core';
+export type SceneWindowTheme = 'dark' | 'light';
+/** 窗口级 config（行为开关；Scene 级参数由消费端以 Scene props 直传，不经此壳） */
+export interface SceneWindowConfig {
+    /** 📌 锁定窗口移动（拖拽禁用） */
+    locked?: boolean;
+    /** 标题栏 info 区显示群符号/阶/名 */
+    showInfo?: boolean;
+    /** 8 向 resize 手柄 */
+    resizable?: boolean;
+    /** 定位用 fixed（视口固定）而非 absolute */
+    viewportFixed?: boolean;
+    /** 标题栏整组隐藏（插图等专注阅读场景） */
+    showControls?: boolean;
+}
+/** chrome 内容裁剪位；缺省全开。false 关某项 */
+export interface SceneWindowCaps {
+    /** 标题栏本体（含 info 区） */
+    titlebar?: boolean;
+    /** 标题栏拖拽移动（需 titlebar 且 locked=false） */
+    drag?: boolean;
+    /** resize 手柄（8 向） */
+    resize?: boolean;
+    /** 📌 锁定移动按钮 */
+    lockMove?: boolean;
+    /** i 信息开关按钮 */
+    toggleInfo?: boolean;
+    /** ⚙ View Config 面板（窗口 config 编辑） */
+    params?: boolean;
+    /** × 关闭按钮（触发 onClose） */
+    close?: boolean;
+    /** storageKey 持久化（位置/尺寸/config） */
+    persist?: boolean;
+}
+interface SceneWindowProps {
+    /** 标题栏主文案；缺省回退 group.symbol */
+    title?: string;
+    /** 标题/信息兜底源 */
+    group?: Group | null;
+    /** 窗口主题（背景/边框/文字配色）；缺省 'dark' */
+    theme?: SceneWindowTheme;
+    /** 'chrome' 浮动窗壳（缺省）/ 'none' 裸内容容器 */
+    shell?: 'none' | 'chrome';
+    /** chrome 内容裁剪；不传全开 */
+    capabilities?: SceneWindowCaps;
+    /** 窗口 config（受控传入或非受控初值） */
+    config?: SceneWindowConfig;
+    onConfigChange?: (c: SceneWindowConfig) => void;
+    /** 持久化键（cap.persist 且给键才读写 localStorage，键空间 gv-sw-*） */
+    storageKey?: string;
+    defaultPosition?: {
+        x: number;
+        y: number;
+    };
+    defaultSize?: {
+        width: number;
+        height: number;
+    };
+    onClose?: () => void;
+    /** 任意 packaged Scene（或任意内容） */
+    children: ReactNode;
+}
+export declare function SceneWindow({ title, group, theme, shell, capabilities, config: configProp, onConfigChange, storageKey, defaultPosition, defaultSize, onClose, children, }: SceneWindowProps): import("react/jsx-runtime").JSX.Element;
+export type { SceneWindowProps };

package/components/Canvas/SetView.d.ts

@@ -0,0 +1,33 @@
+import type { Group } from '@groupviz/core';
+export interface SetViewProps {
+    group: Group | null;
+    selectedElements: Set<string>;
+    canvasTransform: {
+        x: number;
+        y: number;
+        scale: number;
+    };
+    viewBoxSize: {
+        width: number;
+        height: number;
+    };
+    subsets?: Array<{
+        elementIds: string[];
+        color: string;
+    }>;
+    selfInverseElementId?: string | null;
+    cosetElementMap?: Map<string, number>;
+    cosetHighlightSet?: Set<number>;
+    cosetColors?: string[];
+    onSelect?: (elId: string, additive: boolean) => void;
+    onHover?: (el: Group['elements'][number] | null, anchor?: {
+        x: number;
+        y: number;
+    } | null) => void;
+    noGroupText?: string;
+    nodeRadius?: number;
+    gap?: number;
+    columns?: number;
+    showLabels?: boolean;
+}
+export declare function SetView({ group, selectedElements, canvasTransform, viewBoxSize, subsets, selfInverseElementId, cosetElementMap, cosetHighlightSet, cosetColors, onSelect, onHover, noGroupText, nodeRadius: nodeRadiusOverride, gap: gapOverride, columns: columnsOverride, showLabels: showLabelsOverride, }: SetViewProps): import("react/jsx-runtime").JSX.Element;

package/components/Canvas/SublatticeScene.d.ts

@@ -0,0 +1,70 @@
+import { type SubgroupLatticeNode, type SubgroupLatticeEdge } from '@groupviz/core';
+import type { SeriesType, SeriesFactor } from '@groupviz/core';
+import type { CanvasTransform, Group, GroupElement, LatticeLabelDetail, Subset } from '@groupviz/core';
+export interface LatticeData {
+    nodes: SubgroupLatticeNode[];
+    edges: SubgroupLatticeEdge[];
+}
+/** 子群列（Series）状态：由宿主组装后传入，内核只负责高亮与面板呈现 */
+export interface SublatticeSeriesState {
+    type: SeriesType;
+    /** 系列项的元素集合；null 表示后端仍在计算 / 超过守卫 */
+    terms: GroupElement[][] | null;
+    factors?: SeriesFactor[] | null;
+    solvable?: boolean;
+    nilpotent?: boolean;
+    chainCount?: number;
+    truncated?: boolean;
+    loading?: boolean;
+}
+export interface SublatticeSceneProps {
+    group: Group | null;
+    /** 外部提供则优先（大群后端通路）；缺省内核对 order ≤ 60 自行枚举 */
+    lattice?: LatticeData | null;
+    canvasTransform?: CanvasTransform;
+    /** 宿主可用像素尺寸；缺省由 ResizeObserver 实测自身容器 */
+    availableSize?: {
+        width: number;
+        height: number;
+    };
+    /** 名片细节档，缺省 'auto'（按槽位屏幕宽度自动降级） */
+    labelDetail?: LatticeLabelDetail;
+    /** 共轭子群合并为轨道节点，缺省 false */
+    mergeConjugates?: boolean;
+    /** 名片与层距的世界单位乘子，缺省 1 */
+    nodeScale?: number;
+    /** 底部子群列面板，缺省 true */
+    showSeriesPanel?: boolean;
+    series?: SublatticeSeriesState | null;
+    /** 群中心元素 id 列表（宿主已算好时传入，省一次本地计算） */
+    centerIds?: string[];
+    subsets?: Subset[];
+    activeNodeIdx?: number | null;
+    onActivateNode?: (idx: number | null, node: SubgroupLatticeNode | null) => void;
+    noGroupText?: string;
+    /** 渲染主题（格取色 palette）。缺省回落到 ThemeContext（无 Provider 时 'dark'）；
+     *  主应用壳不传即保持现状（读全局主题），包消费端显式传以与容器主题解耦 */
+    theme?: 'dark' | 'light';
+}
+interface SeriesPanelProps {
+    group: Group;
+    series: SublatticeSeriesState;
+    color: string | null;
+    /** 渲染主题（徽标深浅色）。缺省回落到 ThemeContext */
+    theme?: 'dark' | 'light';
+}
+/** 子群列链式展示：N₀ ⊵ N₁ ⊵ … + 各级阶 + 因子 + 可解/幂零徽标（由原视图内联 JSX 迁出） */
+export declare function SeriesPanel({ group, series, color, theme: themeProp }: SeriesPanelProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * 子群格受控内核（FGVE 阶段 2 批次三）。
+ *
+ * 小窗口里的可读性靠三件事：
+ *  1. 布局世界坐标紧贴内容（`computeLatticeLayout`，无 1000×600 下限），适配缩放
+ *     钳 ≤ 1，故主画布不会被撑大、小窗也不会被 letterbox 到不可读；
+ *  2. 名片按"槽位屏幕宽度"自动降级 full → compact → dots；compact/dots 的几何按
+ *     `1/eff` 反算为屏幕恒定大小，同时被槽位宽封顶，所以在任何密度下都不重叠；
+ *  3. 省掉的文字不丢——底部 caption 行按 hover ?? 选中给出完整名片；密度真的高时
+ *     用 `mergeConjugates` 把共轭子群合成一个轨道节点（×n，n = |G : N_G(H)|）。
+ */
+export declare function SublatticeScene({ group, lattice, canvasTransform, availableSize, labelDetail, mergeConjugates, nodeScale, showSeriesPanel, series, centerIds, subsets, activeNodeIdx: activeNodeIdxProp, onActivateNode, noGroupText, theme: themeProp, }: SublatticeSceneProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/components/Canvas/SymmetryViewScene.d.ts

@@ -0,0 +1,34 @@
+import type { Group } from '@groupviz/core';
+import type { SymmetryType } from '@groupviz/core';
+export interface SymmetryViewSceneProps {
+    /** 展示群（null 由调用方自行占位，本组件要求非空） */
+    group: Group;
+    /** 对称类型；缺省按 getSymmetryType(group) 推导（unsupported 群渲染提示 overlay） */
+    symmetryType?: SymmetryType;
+    /** 深色场景配色（背景 + 顶部标注文字）；主画布传主主题，ViewWindow 传窗口主题（解耦） */
+    dark?: boolean;
+    /** 对偶多面体（cube↔octahedron / icosahedron↔dodecahedron）：受控形态（false=主形 / true=对偶形）。
+     *  切换入口由宿主提供（ViewWindow ⚙ 面板 / 主画布 ViewPanel 的 Shape 选项），场景内不再悬浮切换按钮 */
+    variant?: boolean;
+    /** 元素作用演示开关；缺省 false */
+    showAction?: boolean;
+    /** 演示元素 id（受控，toggle 语义：点活跃元素回到恒等姿态）；缺省 null */
+    actionElementId?: string | null;
+    /** 动画倍速 0.2–5；缺省 1 */
+    rotateSpeed?: number;
+    /** 顶部群名 + 几何描述标注；缺省 true（小窗可关） */
+    showFigureTitle?: boolean;
+    /** 锁定相机交互（拖拽旋转/平移/缩放）；演示动画期间本就禁用 */
+    locked?: boolean;
+    /** 演示状态提示回调（主画布接 hint bar，ViewWindow 显示为内容区底部唯一浮条）；缺省无 */
+    onHint?: (msg: string) => void;
+    /** 演示开启但当前元素无可旋转作用（恒等/未选）时，是否上抛 clickHint 引导；
+     *  主画布缺省 true（提示去其它视图点元素）；ViewWindow 传 false（引导文案写在参数面板，浮条只显示真实状态） */
+    hintOnIdle?: boolean;
+    /** 重放信号：宿主自增该值即对当前演示元素重播一次动画（姿态不改变目标，
+     *  解决同元素动画播完一次后无入口重看的缺口）；缺省 0 */
+    replaySignal?: number;
+}
+/** 对称性视图纯渲染核（props 化、主题解耦）：Canvas + 场景 + 顶部标注 + 演示动画。
+ *  主画布经 SymmetryView 适配器接入全局 context；ViewWindow（FGVE 引擎）受控直接使用。 */
+export declare function SymmetryViewScene({ group, symmetryType: symmetryTypeProp, dark, variant, showAction, actionElementId, rotateSpeed, showFigureTitle, locked, onHint, hintOnIdle, replaySignal, }: SymmetryViewSceneProps): import("react/jsx-runtime").JSX.Element;

package/components/Canvas/TableView.d.ts

@@ -0,0 +1,43 @@
+import type { CanvasTransform, Group, GroupElement, Subset } from '@groupviz/core';
+import type { CosetInfo } from '@groupviz/core';
+import type { TableStrategy } from '@groupviz/core';
+export declare const TABLE_PAD_W = 44;
+export declare const TABLE_PAD_H = 74;
+export interface TableViewProps {
+    group: Group | null;
+    selectedElements: Set<string>;
+    canvasTransform: CanvasTransform;
+    viewBoxSize: {
+        width: number;
+        height: number;
+    };
+    /** 子集（含子群标记），用于子群/非子群着色；缺省空 */
+    subsets?: Subset[];
+    cosetElementMap?: Map<string, number>;
+    cosetColors?: string[];
+    cosetData?: CosetInfo | null;
+    cosetType?: 'left' | 'right';
+    showAllCosets?: boolean;
+    /** 大群告警已解除（对应主画布 forceShowLargeGroupViews.has('table')）；缺省 false */
+    forceShowLargeGroup?: boolean;
+    /** 解除大群告警回调；缺省使用本地状态 */
+    onForceShowLargeGroup?: (allow: boolean) => void;
+    /** 大群（>16 阶）展示策略；缺省 'subgroup' */
+    strategy?: TableStrategy;
+    /** 单元格尺寸；缺省 50 */
+    cellSize?: number;
+    /** 热力图模式：只显示颜色，不显示元素和行/列表头；缺省 false */
+    showHeatmap?: boolean;
+    /** 策略被内部 UI 切换时回传（供外部 viewParams 同步） */
+    onStrategyChange?: (s: TableStrategy) => void;
+    /** 实际渲染的表格内容尺寸回传（行数×cellSize + 表头/页脚），用于 ViewWindow 设定最小窗口尺寸；
+     *  大群告警/全屏占位时回传 null（无表格可显示） */
+    onLayoutSize?: (size: {
+        width: number;
+        height: number;
+    } | null) => void;
+    onSelect?: (elId: string, additive: boolean) => void;
+    onHover?: (el: GroupElement | null) => void;
+    noGroupText?: string;
+}
+export declare function TableView({ group, selectedElements, viewBoxSize, canvasTransform, subsets: subsetsProp, cosetElementMap, cosetColors, cosetData: cosetDataProp, cosetType: cosetTypeProp, showAllCosets: showAllCosetsProp, forceShowLargeGroup, onForceShowLargeGroup, strategy: strategyProp, cellSize: cellSizeProp, showHeatmap, onStrategyChange, onLayoutSize, onSelect, onHover, noGroupText, }: TableViewProps): import("react/jsx-runtime").JSX.Element;

package/context/cayleyActions.d.ts

@@ -0,0 +1,20 @@
+import type { Group, ViewMode, CayleyAction, Layout3D } from '@groupviz/core';
+import { type CayleyShape2D } from '@groupviz/core';
+import type { CayleyActionParam } from '@groupviz/core';
+export declare function getInitialCayleyActions(group: Group): CayleyAction[];
+/**
+ * 归一化凯莱视图作用边参数：过滤群中不存在的 elementId，补全 enabled（默认 true）与
+ * color（默认 COLOR_PALETTE 按序）。actions 未提供时返回群生成元集合。
+ * ViewWindow 参数面板与 CayleyView 渲染共用，保证两边对「当前边集合」的判定一致。
+ */
+export declare function normalizeCayleyActions(group: Group, actions?: CayleyActionParam[]): CayleyAction[];
+export interface CayleyShapeConfig {
+    defaultShape3D: Layout3D;
+    availableShapes3D: Layout3D[];
+    defaultShape2D: CayleyShape2D;
+    availableShapes2D: CayleyShape2D[];
+}
+export declare function getCayleyShapeConfig(group: Group): CayleyShapeConfig;
+export declare function getSpecialCayleyActions(group: Group, shape: Layout3D): CayleyAction[] | null;
+export declare function toggleCayleyActionReducer(prev: CayleyAction[], elementId: string): CayleyAction[];
+export declare function addAllCayleyActionsHelper(group: Group, currentView: ViewMode, cayleyShape3D: Layout3D, existingActions: CayleyAction[]): CayleyAction[];

package/i18n/I18nContext.d.ts

@@ -0,0 +1,11 @@
+import { type ReactNode } from 'react';
+import { type Lang } from './translations.js';
+export interface I18nContextValue {
+    lang: Lang;
+    setLang: (lang: Lang) => void;
+    t: (key: string, params?: Record<string, string | number>) => string;
+}
+export declare const I18nContext: import("react").Context<I18nContextValue>;
+export declare function I18nProvider({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;

package/i18n/translations.d.ts

@@ -0,0 +1,5 @@
+export type Lang = 'zh' | 'en';
+type TranslationMap = Record<string, string>;
+export declare const translations: Record<Lang, TranslationMap>;
+export declare function getDefaultLang(): Lang;
+export {};

package/i18n/useTranslation.d.ts

@@ -0,0 +1 @@
+export declare function useTranslation(): import("./I18nContext").I18nContextValue;