wyuc 7cb129183d
chore(packages): publish the @openmaic/* SDK family to npm (#778) (#780)
* chore(packages): publish the @openmaic/* SDK family to npm (#778)

Prepares the @openmaic/{dsl,renderer,importer} family for its first npm
publish, and moves the SDK packages onto the @openmaic scope.

Why the scope move: the @maic org name is unavailable on npm (an unscoped
`maic` package already holds the name), so @maic/* is not claimable. @openmaic
matches the project name, the scope is free, and the repo already ships an
@openmaic/docs package — so the SDK family now lines up with that convention.

- rename @maic/{dsl,renderer,importer} -> @openmaic/* across packages, the
  workspace glob, the package dir, and all import sites; lockfile regenerated
- renderer: add publishConfig (public, registry.npmjs.org) — was missing, so
  a scoped publish would default to the wrong registry / restricted access
- importer: add a files allowlist (dist, README, LICENSE) and drop the
  fragile .npmignore blacklist that shipped src; add an exports map so ESM
  consumers resolve dist/index.js instead of falling back to the .cjs main
- all three: add a prepublishOnly build (+ test/typecheck) guard so a publish
  can never ship a stale or empty dist
- add a tag-triggered publish workflow with npm provenance, pinned by name to
  the three @openmaic packages so the vendored forks (mathml2omml, pptxgenjs)
  are never published

Refs #778, #720 (Phase 1).

* fix(packages): address cross-review on the @openmaic publish prep

Cross-review (Claude /code-review + codex) on this PR surfaced:

- renderer's advertised CJS entry was broken: it keeps @openmaic/dsl external
  and imports a runtime enum from it, but dsl is ESM-only (no `require`
  condition), so `require('@openmaic/renderer')` would throw
  ERR_PACKAGE_PATH_NOT_EXPORTED. Make renderer ESM-only: drop the `.cjs`
  rollup output, `main` now points at the ESM build, and the `require`
  conditions are removed from `exports`. (importer is unaffected — it bundles
  dsl, so its CJS build still works.)
- prepublishOnly re-ran the test suite during `pnpm -r publish`, so a flaky
  test after dsl had already published gave a non-atomic partial release.
  Reduce prepublishOnly to a build-only guard (never ship stale/empty dist)
  and move the real test/typecheck gate into the workflow, before any publish.
- document that an @openmaic/* tag publishes the whole family via `pnpm -r`
  (pnpm skips already-published versions); the tag is a release marker, not a
  per-package gate.

Verified: dsl + renderer + importer build; renderer emits ESM only (0 .cjs),
all exports entries resolve; `npm pack` ships dist + README + LICENSE with no
src leak; frozen-lockfile passes.

Refs #778.

* style: reflow @openmaic/dsl type imports past print-width after rename

The @maic -> @openmaic rename lengthened two single-line type imports past
prettier's 100-col width; prettier --check flagged them. Pure formatting.

Refs #778.

* docs(importer): mark @openmaic/importer browser-only (cr-loop accepted limitation)

codex cross-review flagged that the published @openmaic/importer throws
`XMLHttpRequest is not a constructor` when loaded in a pure Node process —
its rollup build is browser-targeted (`nodeResolve({browser:true})` + a
browser pdf.js build). The app only consumes it client-side ('use client'),
so this is by design. Document it as an accepted limitation: prominent
browser-only note in the README and a `browser` field in the manifest.

Refs #778.
2026-06-24 15:12:23 +08:00

8.6 KiB
Raw Blame History

maic-renderer 设计稿(v1:只读画布)

配套计划:docs/superpowers/plans/2026-05-28-maic-renderer-package.md 原始 spec:docs/superpowers/specs/2026-05-28-maic-renderer-package-design.md

1. 目标

把 OpenMAIC 主仓 components/maic-renderer/ 中的只读画布部分抽成独立 workspace 包,让任意 React + Tailwind 4 项目都能"装包 → 传 Slide → 直接渲染"。

v1 范围限定为只读画布(对应主仓 Editor/ScreenCanvas.tsx 子树)。编辑能力(Editor/Canvas/*、Operate/*、ProseMirror live editor)留给 v2。

理由:

  1. 闭环最小可用,跟 pptxtojson-pro 形成「产 Slide → 渲 Slide」对子。
  2. 编辑器接口面(选中态、命令、撤销、剪贴板、协作)定型后难改,第一版强行定下来大概率返工。
  3. 只读包本身有独立价值(嵌课件、报告、回放、PDF 导出预览等)。

2. 设计决策

# 决策点 选择 理由
D1 范围 分两步:v1 只读 + v2 编辑 闭环最小,风险可控
D2 数据 API 纯 Props 主;同时导出可选 Provider 上手最快,进阶用户也照顾到
D3 样式 要求消费者使用 Tailwind 4 工作量最小,跟主仓工程实践一致
D4 特效层 包含,4 个全做成可选 props,默认关 还原"OpenMAIC 同款画布"必备,但默认零负担
D5 业务耦合元素 暴露 renderImage / renderVideo 插槽,包内默认渲原生标签 包不感知业务,消费者按需注入
D6 i18n 包不带文案 UI 文案下放给消费者
D7 ProseMirror v1 不依赖 只读用 dangerouslySetInnerHTML 就够,体积大幅缩小
D8 包发布 workspace 包,未来可发 npm;当前名 maic-renderer(同 pptxtojson-pro 风格) 一致性

3. 对外 API

3.1 主入口

import { SlideCanvas, type SlideCanvasProps } from 'maic-renderer';

interface SlideCanvasProps {
  /** 单页幻灯片数据(PPTist 风格) */
  slide: Slide;
  /** 画布缩放,默认 1 */
  scale?: number;
  /** 可选:覆盖 slide.background */
  background?: SlideBackground;
  /** 可选:4 个播放特效,默认全关 */
  effects?: {
    laser?:     { elementId: string; color?: string; duration?: number };
    spotlight?: { elementId: string };
    highlight?: { elementId: string };
    zoom?:      { elementId: string; scale: number };
  };
  /** 可选:图片渲染插槽,消费者可注入 placeholder/retry 逻辑 */
  renderImage?: (el: PPTImageElement, resolvedSrc: string) => React.ReactNode;
  /** 可选:视频渲染插槽 */
  renderVideo?: (el: PPTVideoElement) => React.ReactNode;
  /** 可选:元素点击 */
  onElementClick?: (el: PPTElement, event: React.MouseEvent) => void;
  /** 透传外层 */
  className?: string;
  style?: React.CSSProperties;
}

3.2 Provider 高阶模式(可选)

import { SlideRendererProvider, useSlideContext } from 'maic-renderer';

<SlideRendererProvider slide={slide} scale={0.9}>
  <SlideCanvas />
  <MyCustomOverlay />  {/* 子组件 useSlideContext() 拿数据 */}
</SlideRendererProvider>

3.3 元素子组件(细粒度复用)

import {
  BaseTextElement, BaseShapeElement, BaseImageElement,
  BaseLineElement, BaseChartElement, BaseLatexElement,
  BaseTableElement, BaseVideoElement, BaseCodeElement,
} from 'maic-renderer/elements';

3.4 类型

import type {
  Slide, PPTElement, SlideBackground, SlideTheme,
  PPTTextElement, PPTShapeElement, PPTImageElement,
  PPTLineElement, PPTChartElement, PPTLatexElement,
  PPTTableElement, PPTVideoElement, PPTCodeElement,
  ImageElementClip, ImageElementFilters,
  Gradient, GradientType, PPTElementOutline, PPTElementShadow,
} from 'maic-renderer/types';

4. 包结构

packages/maic-renderer/
├── package.json
├── README.md
├── DESIGN.md
├── tsconfig.json
├── rollup.config.js
└── src/
    ├── index.ts                  # 主入口
    ├── SlideCanvas.tsx           # 替代 ScreenCanvas(props 驱动)
    ├── SlideElement.tsx          # 替代 ScreenElement
    ├── context.tsx               # Provider + useSlideContext
    ├── effects/
    │   ├── index.ts
    │   ├── HighlightOverlay.tsx
    │   ├── SpotlightOverlay.tsx
    │   ├── LaserOverlay.tsx
    │   └── ZoomWrapper.tsx
    ├── elements/
    │   ├── index.ts
    │   ├── text/BaseTextElement.tsx
    │   ├── shape/
    │   │   ├── BaseShapeElement.tsx
    │   │   ├── GradientDefs.tsx
    │   │   └── PatternDefs.tsx
    │   ├── image/
    │   │   ├── BaseImageElement.tsx
    │   │   ├── ImageOutline.tsx
    │   │   ├── useClipImage.ts
    │   │   └── useFilter.ts
    │   ├── line/BaseLineElement.tsx
    │   ├── chart/
    │   │   ├── BaseChartElement.tsx
    │   │   └── Chart.tsx
    │   ├── latex/BaseLatexElement.tsx
    │   ├── table/BaseTableElement.tsx
    │   ├── video/BaseVideoElement.tsx
    │   ├── code/BaseCodeElement.tsx
    │   └── shared/
    │       ├── ElementOutline.tsx
    │       ├── useElementFill.ts
    │       ├── useElementOutline.ts
    │       ├── useElementShadow.ts
    │       └── useElementFlip.ts
    ├── hooks/
    │   ├── useSlideBackgroundStyle.ts
    │   └── useViewportSize.ts
    ├── utils/
    │   ├── cn.ts
    │   ├── geometry.ts
    │   └── element.ts
    └── types/
        ├── slides.ts             # 从 lib/types/slides 拷贝
        ├── effects.ts            # 新增
        └── index.ts

5. 依赖

peerDependencies:

{
  "react": ">=18",
  "react-dom": ">=18",
  "motion": ">=11",
  "tailwindcss": ">=4"
}

dependencies(运行时必备):

  • katex — latex 渲染
  • tinycolor2 — 颜色工具
  • lucide-react — 图标
  • clsx、tailwind-merge — cn helper

chart 库:复用主仓现用方案,T10 实现阶段确认。开发阶段先 inline 进 dependencies,若体积过大改 peerDep。

ProseMirror 系列:v1 完全不依赖。

6. 构建

跟 pptxtojson-pro 完全一致:

pnpm build    # rollup -c && tsc --emitDeclarationOnly

产物:

dist/
├── index.{js,cjs,d.ts}
├── elements/index.{js,cjs,d.ts}
└── types/index.{js,cjs,d.ts}

7. 关键解耦点

7.1 ScreenCanvas → SlideCanvas

原 新
useCanvasStore.use.canvasScale() props.scale ?? 1
useSceneSelector(c => c.canvas.elements) props.slide.elements
useSceneSelector(c => c.canvas.background) props.background ?? props.slide.background
useCanvasStore.use.laserElementId/Options() props.effects?.laser
useCanvasStore.use.zoomTarget() props.effects?.zoom
findElementGeometry(...) 拷贝进 utils/geometry.ts

7.2 ScreenElement → SlideElement

theme.fontColor / theme.fontName 改成从 props.slide.theme 读取;useSceneSelector 移除。

7.3 BaseImageElement

包内退化成纯 <img> 版本(含 clip/filter/outline/shadow),所有 placeholder / retry / i18n 逻辑剥离。消费者通过 renderImage 注入业务版本。

7.4 BaseVideoElement

同上,纯 <video>。

7.5 其余 Base*Element

只有类型导入路径要改(@/lib/types/slides → ../../types/slides),无业务耦合。

8. 验收标准

  1. pnpm --filter maic-renderer build 通过,产出干净 dist
  2. 主仓 /maic-renderer-demo 路由用包渲染一份手写 Slide,目视与原 ScreenCanvas 一致
  3. v1 不替换主仓既有调用

9. v2 预告

  • Editor/Canvas/* 抽到包内 editing/
  • ProseMirror live editor
  • 选中/拖拽/resize/旋转/裁剪/对齐线/标尺
  • 撤销/重做/剪贴板
  • API:<SlideEditor slide editable onChange={...} />

10. 风险

风险 等级 缓解
Chart 库依赖不明,包体积可能膨胀 中 T10 阶段确认;若 >200KB gz 改 peerDep
Tailwind 4 强依赖筛掉很多消费者 中 README 显著说明;v3 再考虑编译 CSS
主仓 Slide 类型未来演进,包内拷贝版会漂移 低 后续可通过 pptxtojson-pro 已有的 openmaic/types/slides.ts 三方共享
BaseImageElement 砍业务后主仓现有页面会丢功能 无影响 本次任务不替换主仓调用,主仓继续用自己的 BaseImageElement