@qingwu-ui/ai-editor 0.9.0-beta

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (146) hide show
  1. package/LICENSE +159 -0
  2. package/README.en.md +327 -0
  3. package/README.md +460 -0
  4. package/dist/clipper.cjs +1 -0
  5. package/dist/clipper.d.ts +12 -0
  6. package/dist/clipper.js +73 -0
  7. package/dist/components/ai-settings-dialog.d.ts +8 -0
  8. package/dist/components/ai-settings-dialog.d.ts.map +1 -0
  9. package/dist/components/export-dialog.d.ts +10 -0
  10. package/dist/components/export-dialog.d.ts.map +1 -0
  11. package/dist/components/image-upload-dialog.d.ts +11 -0
  12. package/dist/components/image-upload-dialog.d.ts.map +1 -0
  13. package/dist/components/md-import-dialog.d.ts +11 -0
  14. package/dist/components/md-import-dialog.d.ts.map +1 -0
  15. package/dist/components/search-bar.d.ts +21 -0
  16. package/dist/components/search-bar.d.ts.map +1 -0
  17. package/dist/components/storage-settings-dialog.d.ts +8 -0
  18. package/dist/components/storage-settings-dialog.d.ts.map +1 -0
  19. package/dist/components/toast.d.ts +22 -0
  20. package/dist/components/toast.d.ts.map +1 -0
  21. package/dist/components/toc.d.ts +18 -0
  22. package/dist/components/toc.d.ts.map +1 -0
  23. package/dist/components/video-embed-dialog.d.ts +9 -0
  24. package/dist/components/video-embed-dialog.d.ts.map +1 -0
  25. package/dist/editor/ai/components/ai-selector.d.ts +8 -0
  26. package/dist/editor/ai/components/ai-selector.d.ts.map +1 -0
  27. package/dist/editor/ai/index.d.ts +42 -0
  28. package/dist/editor/ai/index.d.ts.map +1 -0
  29. package/dist/editor/ai/pending-removal.d.ts +20 -0
  30. package/dist/editor/ai/pending-removal.d.ts.map +1 -0
  31. package/dist/editor/ai/providers/deepseek.d.ts +12 -0
  32. package/dist/editor/ai/providers/deepseek.d.ts.map +1 -0
  33. package/dist/editor/ai/providers/openai-compat.d.ts +14 -0
  34. package/dist/editor/ai/providers/openai-compat.d.ts.map +1 -0
  35. package/dist/editor/ai/providers/openai.d.ts +10 -0
  36. package/dist/editor/ai/providers/openai.d.ts.map +1 -0
  37. package/dist/editor/ai/providers/qwen.d.ts +14 -0
  38. package/dist/editor/ai/providers/qwen.d.ts.map +1 -0
  39. package/dist/editor/ai-editor.d.ts +57 -0
  40. package/dist/editor/ai-editor.d.ts.map +1 -0
  41. package/dist/editor/attachment-limits.d.ts +32 -0
  42. package/dist/editor/attachment-limits.d.ts.map +1 -0
  43. package/dist/editor/clipper/receiver-browser.d.ts +16 -0
  44. package/dist/editor/clipper/receiver-browser.d.ts.map +1 -0
  45. package/dist/editor/clipper/receiver-node.d.ts +43 -0
  46. package/dist/editor/clipper/receiver-node.d.ts.map +1 -0
  47. package/dist/editor/clipper/receiver.d.ts +10 -0
  48. package/dist/editor/clipper/receiver.d.ts.map +1 -0
  49. package/dist/editor/clipper/types.d.ts +47 -0
  50. package/dist/editor/clipper/types.d.ts.map +1 -0
  51. package/dist/editor/embeds/attachment-view.d.ts +2 -0
  52. package/dist/editor/embeds/attachment-view.d.ts.map +1 -0
  53. package/dist/editor/embeds/attachment.d.ts +4 -0
  54. package/dist/editor/embeds/attachment.d.ts.map +1 -0
  55. package/dist/editor/embeds/audio-view.d.ts +2 -0
  56. package/dist/editor/embeds/audio-view.d.ts.map +1 -0
  57. package/dist/editor/embeds/audio.d.ts +4 -0
  58. package/dist/editor/embeds/audio.d.ts.map +1 -0
  59. package/dist/editor/embeds/video-view.d.ts +2 -0
  60. package/dist/editor/embeds/video-view.d.ts.map +1 -0
  61. package/dist/editor/embeds/video.d.ts +4 -0
  62. package/dist/editor/embeds/video.d.ts.map +1 -0
  63. package/dist/editor/extensions/bubble-menu.d.ts +23 -0
  64. package/dist/editor/extensions/bubble-menu.d.ts.map +1 -0
  65. package/dist/editor/extensions/code-block-view.d.ts +2 -0
  66. package/dist/editor/extensions/code-block-view.d.ts.map +1 -0
  67. package/dist/editor/extensions/code-block.d.ts +6 -0
  68. package/dist/editor/extensions/code-block.d.ts.map +1 -0
  69. package/dist/editor/extensions/image-upload.d.ts +12 -0
  70. package/dist/editor/extensions/image-upload.d.ts.map +1 -0
  71. package/dist/editor/extensions/image-view.d.ts +2 -0
  72. package/dist/editor/extensions/image-view.d.ts.map +1 -0
  73. package/dist/editor/extensions/index.d.ts +27 -0
  74. package/dist/editor/extensions/index.d.ts.map +1 -0
  75. package/dist/editor/extensions/obsidian-markdown.d.ts +9 -0
  76. package/dist/editor/extensions/obsidian-markdown.d.ts.map +1 -0
  77. package/dist/editor/extensions/qingwu-ui.d.ts +28 -0
  78. package/dist/editor/extensions/qingwu-ui.d.ts.map +1 -0
  79. package/dist/editor/extensions/relative-media.d.ts +28 -0
  80. package/dist/editor/extensions/relative-media.d.ts.map +1 -0
  81. package/dist/editor/extensions/search-highlight.d.ts +34 -0
  82. package/dist/editor/extensions/search-highlight.d.ts.map +1 -0
  83. package/dist/editor/extensions/slash-command.d.ts +28 -0
  84. package/dist/editor/extensions/slash-command.d.ts.map +1 -0
  85. package/dist/editor/extensions/table-toolbar.d.ts +7 -0
  86. package/dist/editor/extensions/table-toolbar.d.ts.map +1 -0
  87. package/dist/editor/i18n/en-US.d.ts +197 -0
  88. package/dist/editor/i18n/en-US.d.ts.map +1 -0
  89. package/dist/editor/i18n/index.d.ts +7 -0
  90. package/dist/editor/i18n/index.d.ts.map +1 -0
  91. package/dist/editor/i18n/zh-CN.d.ts +197 -0
  92. package/dist/editor/i18n/zh-CN.d.ts.map +1 -0
  93. package/dist/editor/icons.d.ts +15 -0
  94. package/dist/editor/icons.d.ts.map +1 -0
  95. package/dist/editor/index.d.ts +40 -0
  96. package/dist/editor/index.d.ts.map +1 -0
  97. package/dist/editor/storage/index.d.ts +67 -0
  98. package/dist/editor/storage/index.d.ts.map +1 -0
  99. package/dist/editor/storage/providers/cos.d.ts +32 -0
  100. package/dist/editor/storage/providers/cos.d.ts.map +1 -0
  101. package/dist/editor/storage/providers/local.d.ts +3 -0
  102. package/dist/editor/storage/providers/local.d.ts.map +1 -0
  103. package/dist/editor/storage/providers/oss.d.ts +29 -0
  104. package/dist/editor/storage/providers/oss.d.ts.map +1 -0
  105. package/dist/editor/storage/providers/s3.d.ts +24 -0
  106. package/dist/editor/storage/providers/s3.d.ts.map +1 -0
  107. package/dist/editor/storage/remove-resource.d.ts +3 -0
  108. package/dist/editor/storage/remove-resource.d.ts.map +1 -0
  109. package/dist/editor/storage/signed-fetch.d.ts +25 -0
  110. package/dist/editor/storage/signed-fetch.d.ts.map +1 -0
  111. package/dist/editor/utils/delete-confirm-dialog.d.ts +18 -0
  112. package/dist/editor/utils/delete-confirm-dialog.d.ts.map +1 -0
  113. package/dist/editor/utils/delete-confirm.d.ts +13 -0
  114. package/dist/editor/utils/delete-confirm.d.ts.map +1 -0
  115. package/dist/editor/utils/import-choice-dialog.d.ts +10 -0
  116. package/dist/editor/utils/import-choice-dialog.d.ts.map +1 -0
  117. package/dist/editor/utils/local-media.d.ts +119 -0
  118. package/dist/editor/utils/local-media.d.ts.map +1 -0
  119. package/dist/editor/utils/render-probe.d.ts +6 -0
  120. package/dist/editor/utils/render-probe.d.ts.map +1 -0
  121. package/dist/editor/utils/resolve-local-media.d.ts +71 -0
  122. package/dist/editor/utils/resolve-local-media.d.ts.map +1 -0
  123. package/dist/editor/utils/sanitize.d.ts +24 -0
  124. package/dist/editor/utils/sanitize.d.ts.map +1 -0
  125. package/dist/export-dialog-DLCACwRK.js +162 -0
  126. package/dist/export-dialog-JUHUKqo-.cjs +13 -0
  127. package/dist/index.cjs +9 -0
  128. package/dist/index.d.ts +4 -0
  129. package/dist/index.js +7069 -0
  130. package/dist/local-B20eAPCo.js +93 -0
  131. package/dist/local-D4481lUa.cjs +3 -0
  132. package/dist/md-import-dialog-Cf3ZOwA_.js +129 -0
  133. package/dist/md-import-dialog-CnstzrIK.cjs +1 -0
  134. package/dist/sanitize-BLVk_EcE.cjs +1 -0
  135. package/dist/sanitize-OUn05c7P.js +451 -0
  136. package/dist/signed-fetch-CPPWCUUS.js +102 -0
  137. package/dist/signed-fetch-D8Rk6R5t.cjs +5 -0
  138. package/dist/storage-B6LsdlnG.js +37 -0
  139. package/dist/storage-raz9BRoZ.cjs +2 -0
  140. package/dist/storage-settings-dialog-BA8QlSw7.js +385 -0
  141. package/dist/storage-settings-dialog-Dojhp-Uo.cjs +1 -0
  142. package/dist/styles.css +3 -0
  143. package/dist/video-embed-dialog-AeGcMb4X.js +269 -0
  144. package/dist/video-embed-dialog-BbVHq51W.cjs +1 -0
  145. package/package.json +206 -0
  146. package/styles.d.ts +1 -0
package/LICENSE ADDED
@@ -0,0 +1,159 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity.
18
+
19
+ "You" (or "Your") shall mean an individual or Legal Entity
20
+ exercising permissions granted by this License.
21
+
22
+ "Source" form shall mean the preferred form for making modifications,
23
+ including but not limited to software source code, documentation
24
+ source, and configuration files.
25
+
26
+ "Object" form shall mean any form resulting from mechanical
27
+ transformation or translation of a Source form, including but
28
+ not limited to compiled object code, generated documentation,
29
+ and conversions to other media types.
30
+
31
+ "Work" shall mean the work of authorship, whether in Source or
32
+ Object form, made available under the License, as indicated by a
33
+ copyright notice that is included in or attached to the work.
34
+
35
+ "Derivative Works" shall mean any work, whether in Source or Object
36
+ form, that is based on (or derived from) the Work and for which the
37
+ editorial revisions, annotations, elaborations, or other modifications
38
+ represent, as a whole, an original work of authorship.
39
+
40
+ "Contribution" shall mean any work of authorship, including
41
+ the original version of the Work and any modifications or additions
42
+ to that Work or Derivative Works thereof, that is intentionally
43
+ submitted to Licensor for inclusion in the Work by the copyright owner
44
+ or by an individual or Legal Entity authorized to submit on behalf of
45
+ the copyright owner.
46
+
47
+ "Contributor" shall mean Licensor and any individual or Legal Entity
48
+ on behalf of whom a Contribution has been received by Licensor and
49
+ subsequently incorporated within the Work.
50
+
51
+ 2. Grant of Copyright License. Subject to the terms and conditions of
52
+ this License, each Contributor hereby grants to You a perpetual,
53
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
54
+ copyright license to reproduce, prepare Derivative Works of,
55
+ publicly display, publicly perform, sublicense, and distribute the
56
+ Work and such Derivative Works in Source or Object form.
57
+
58
+ 3. Grant of Patent License. Subject to the terms and conditions of
59
+ this License, each Contributor hereby grants to You a perpetual,
60
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
61
+ (except as stated in this section) patent license to make, have made,
62
+ use, offer to sell, sell, import, and otherwise transfer the Work,
63
+ where such license applies only to those patent claims licensable
64
+ by such Contributor that are necessarily infringed by their
65
+ Contribution(s) alone or by combination of their Contribution(s)
66
+ with the Work to which such Contribution(s) was submitted.
67
+
68
+ 4. Redistribution. You may reproduce and distribute copies of the
69
+ Work or Derivative Works thereof in any medium, with or without
70
+ modifications, and in Source or Object form, provided that You
71
+ meet the following conditions:
72
+
73
+ (a) You must give any other recipients of the Work or
74
+ Derivative Works a copy of this License; and
75
+
76
+ (b) You must cause any modified files to carry prominent notices
77
+ stating that You changed the files; and
78
+
79
+ (c) You must retain, in the Source form of any Derivative Works
80
+ that You distribute, all copyright, patent, trademark, and
81
+ attribution notices from the Source form of the Work,
82
+ excluding those notices that do not pertain to any part of
83
+ the Derivative Works; and
84
+
85
+ (d) If the Work includes a "NOTICE" text file as part of its
86
+ distribution, then any Derivative Works that You distribute must
87
+ include a readable copy of the attribution notices contained
88
+ within such NOTICE file, excluding those notices that do not
89
+ pertain to any part of the Derivative Works, in at least one
90
+ of the following places: within a NOTICE text file distributed
91
+ as part of the Derivative Works; within the Source form or
92
+ documentation, if provided along with the Derivative Works; or,
93
+ within a display generated by the Derivative Works, if and
94
+ wherever such third-party notices normally appear.
95
+
96
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
97
+ any Contribution intentionally submitted for inclusion in the Work
98
+ by You to the Licensor shall be under the terms and conditions of
99
+ this License, without any additional terms or conditions.
100
+
101
+ 6. Trademarks. This License does not grant permission to use the trade
102
+ names, trademarks, service marks, or product names of the Licensor,
103
+ except as required for reasonable and customary use in describing the
104
+ origin of the Work and reproducing the content of the NOTICE file.
105
+
106
+ 7. Disclaimer of Warranty. Unless required by applicable law or
107
+ agreed to in writing, Licensor provides the Work (and each
108
+ Contributor provides its Contributions) on an "AS IS" BASIS,
109
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
110
+ implied, including, without limitation, any warranties or conditions
111
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
112
+ PARTICULAR PURPOSE. You are solely responsible for determining the
113
+ appropriateness of using or redistributing the Work and assume any
114
+ risks associated with Your exercise of permissions under this License.
115
+
116
+ 8. Limitation of Liability. In no event and under no legal theory,
117
+ whether in tort (including negligence), contract, or otherwise,
118
+ unless required by applicable law (such as deliberate and grossly
119
+ negligent acts) or agreed to in writing, shall any Contributor be
120
+ liable to You for damages, including any direct, indirect, special,
121
+ incidental, or consequential damages of any character arising as a
122
+ result of this License or out of the use or inability to use the
123
+ Work (including but not limited to damages for loss of goodwill,
124
+ work stoppage, computer failure or malfunction, or any and all
125
+ other commercial damages or losses), even if such Contributor
126
+ has been advised of the possibility of such damages.
127
+
128
+ 9. Accepting Warranty or Additional Liability. While redistributing
129
+ the Work or Derivative Works thereof, You may choose to offer,
130
+ and charge a fee for, acceptance of support, warranty, indemnity,
131
+ or other liability obligations and/or rights consistent with this
132
+ License. However, in accepting such obligations, You may act only
133
+ on Your own behalf and on Your sole responsibility, not on behalf
134
+ of any other Contributor, and only if You agree to indemnify,
135
+ defend, and hold each Contributor harmless for any liability
136
+ incurred by, or claims asserted against, such Contributor by reason
137
+ of your accepting any such warranty or additional liability.
138
+
139
+ END OF TERMS AND CONDITIONS
140
+
141
+ Copyright 2026 QingWu Contributors
142
+
143
+ Licensed under the Apache License, Version 2.0 (the "License");
144
+ you may not use this file except in compliance with the License.
145
+ You may obtain a copy of the License at
146
+
147
+ http://www.apache.org/licenses/LICENSE-2.0
148
+
149
+ Unless required by applicable law or agreed to in writing, software
150
+ distributed under the License is distributed on an "AS IS" BASIS,
151
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
152
+ See the License for the specific language governing permissions and
153
+ limitations under the License.
154
+
155
+ ---
156
+
157
+ 本项目编辑器核心基于 Tiptap (MIT License),致敬 Novel 项目 (Apache-2.0)。
158
+ This project's editor core is built on Tiptap (MIT License).
159
+ Tribute to Novel (steven-tey/novel, Apache-2.0) for the inspiration.
package/README.en.md ADDED
@@ -0,0 +1,327 @@
1
+ # 青梧 · QingWu Editor
2
+
3
+ > A smart rich-text editor for Chinese users, built on Tiptap + React, with DeepSeek, Qwen, OpenAI and other LLM integrations.
4
+
5
+ ---
6
+
7
+ ## Features
8
+
9
+ - **AI writing assistant** - continue, polish, condense, expand, fix, translate, custom prompts, via the unified Vercel AI SDK interface
10
+ - **Rich media embeds** - images, video (Bilibili / direct link / Xiaohongshu), audio, attachments (206+ formats online preview)
11
+ - **Markdown paste** - Obsidian-style `[[link]]` and `![[image]]` syntax
12
+ - **Multiple storage backends** - local / Alibaba Cloud OSS / Tencent Cloud COS / S3-compatible storage, with persisted config
13
+ - **Bilingual (ZH/EN)** - switchable at runtime, no reload
14
+ - **Slash commands** - `/` to insert headings, lists, images, video, etc.
15
+ - **Code highlighting** - 30+ languages via lowlight
16
+ - **Math formulas** - [KaTeX](https://katex.org/)
17
+ - **Video playback** - [xgplayer](https://h5player.bytedance.com/)
18
+ - **File preview** - based on @file-viewer/react-full, supports Office / PDF / CAD / archives and 206+ formats
19
+ - **Export** - HTML / Markdown / JSON / plain text / PDF
20
+ - **Editable** - readonly mode for pure display scenarios
21
+
22
+ ## Install
23
+
24
+ ```bash
25
+ npm install @qingwu-ui/ai-editor
26
+ ```
27
+
28
+ Or clone the repo (qingwu-ui monorepo, in `packages/ai-editor`):
29
+
30
+ ```bash
31
+ git clone https://github.com/apricotdream/qingwu-ui.git
32
+ cd qingwu-ui/packages/ai-editor
33
+ bun install
34
+ bun run dev
35
+ ```
36
+
37
+ ## Quick Start
38
+
39
+ ### Use as an npm dependency
40
+
41
+ ```tsx
42
+ import { QingWuAIEditor, t, setLocale } from "@qingwu-ui/ai-editor";
43
+
44
+ function App() {
45
+ return (
46
+ <QingWuAIEditor
47
+ placeholder="Start writing…"
48
+ onChange={(html, json) => console.log(html)}
49
+ // Attachment upload limits (required): 50MB per file, 100MB total
50
+ maxAttachmentSize={50 * 1024 * 1024}
51
+ maxTotalAttachmentSize={100 * 1024 * 1024}
52
+ />
53
+ );
54
+ }
55
+ ```
56
+
57
+ ### Configure the writing assistant
58
+
59
+ ```ts
60
+ import {
61
+ setAIProvider,
62
+ createAILanguageModelProvider,
63
+ } from "@qingwu-ui/ai-editor";
64
+
65
+ // Generic interface - supports any OpenAI-compatible API
66
+ const provider = await createAILanguageModelProvider({
67
+ apiKey: "sk-xxx",
68
+ baseURL: "https://api.deepseek.com/v1", // DeepSeek
69
+ model: "deepseek-v4-flash",
70
+ });
71
+ setAIProvider(provider);
72
+
73
+ // To switch to Qwen, just change baseURL and model:
74
+ // baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1"
75
+ // model: "qwen3.7-plus"
76
+ ```
77
+
78
+ ### Configure cloud storage
79
+
80
+ ```ts
81
+ import { setStorageProvider, createOSSStorage } from "@qingwu-ui/ai-editor";
82
+
83
+ setStorageProvider(
84
+ createOSSStorage({
85
+ region: "oss-cn-hangzhou",
86
+ bucket: "my-bucket",
87
+ accessKeyId: "xxx",
88
+ accessKeySecret: "xxx",
89
+ })
90
+ );
91
+ ```
92
+
93
+ ### Switch language
94
+
95
+ ```ts
96
+ import { setLocale } from "@qingwu-ui/ai-editor";
97
+
98
+ setLocale("en-US"); // switch to English
99
+ setLocale("zh-CN"); // switch to Chinese
100
+ ```
101
+
102
+ ## Browser extension (QingWu Web Clipper)
103
+
104
+ [QingWu Web Clipper](./extension) is the companion browser clipping extension. Clip web content into QingWu Editor with one click. Supports Chrome / Edge / Firefox.
105
+
106
+ ### Features
107
+
108
+ - **Multi-mode clipping** - full page / selection / link bookmark / image URL
109
+ - **AI summary & tags** - auto-generate summary and tags (requires AI config)
110
+ - **Template rendering** - custom Markdown templates with variables
111
+ - **History management** - local IndexedDB storage, with search / favorite / delete
112
+ - **Push to editor** - push clips to QingWu Editor via local receiver or browser channel
113
+ - **Multiple triggers** - floating ball, context menu, keyboard shortcuts
114
+
115
+ ### Install
116
+
117
+ ```bash
118
+ # One-click build for all browser extension packages (Windows / Linux / Mac)
119
+ cd extension
120
+ ./build-extension.bat # Windows
121
+ ./build-extension.sh # Linux / Mac
122
+ ```
123
+
124
+ Build artifacts are in `extension/dist/`:
125
+
126
+ - `qingwu-clipper-chrome-v*.zip` / `edge` / `firefox` - packaged for store upload
127
+ - `dist/chrome` / `edge` / `firefox` - load directly as "unpacked extension" for debugging
128
+
129
+ #### Load unpacked extension (dev debugging)
130
+
131
+ | Browser | Steps |
132
+ |--------|------|
133
+ | **Chrome** | Open `chrome://extensions` -> enable "Developer mode" -> "Load unpacked" -> select `extension/dist/chrome` |
134
+ | **Edge** | Open `edge://extensions` -> enable "Developer mode" -> "Load unpacked" -> select `extension/dist/edge` |
135
+ | **Firefox** | Open `about:debugging#/runtime/this-firefox` -> "Load Temporary Add-on" -> select `extension/dist/firefox/manifest.json` |
136
+
137
+ After loading, the QingWu extension icon appears in the browser toolbar.
138
+
139
+ ### Usage
140
+
141
+ #### Quick entry points
142
+
143
+ | Action | Entry |
144
+ |------|------|
145
+ | Clip current page | Shortcut `Alt+Shift+C` / context menu / floating ball |
146
+ | Clip selection | Select text, then context menu |
147
+ | Open sidebar | Shortcut `Alt+Shift+P` / click the extension icon |
148
+
149
+ #### First-use tutorial
150
+
151
+ 1. **Load the extension** - follow the "Load unpacked extension" steps above to load the build artifacts into the browser
152
+ 2. **Trigger a clip** - open any page, hover the right edge to show the floating ball (or press `Alt+Shift+C`); click it to auto-extract the main content
153
+ 3. **Edit the draft** - after clipping, content enters the sidebar draft; edit title / path / tags
154
+ 4. **Save & push** - click "Save", then "Push to editor" (receiver must be enabled in the editor) or "Download Markdown"
155
+
156
+ > Pushing to the editor requires enabling the "Receive clips" toggle on the editor side (homepage banner -> About the extension). The extension pushes via the local receiver `http://127.0.0.1:7321` or the browser channel.
157
+
158
+ ### Connect to the editor
159
+
160
+ Start a receiver on the editor side to accept clips pushed by the extension:
161
+
162
+ ```ts
163
+ import { startClipperReceiver } from "@qingwu-ui/ai-editor";
164
+
165
+ await startClipperReceiver({
166
+ port: 7321,
167
+ onClip: (clip) => {
168
+ editor.commands.setContent(clip.markdown);
169
+ },
170
+ });
171
+ ```
172
+
173
+ HTTP endpoint `POST http://127.0.0.1:7321/clip`, request body (`IncomingClip`):
174
+
175
+ | Field | Type | Required | Description |
176
+ |------|------|------|------|
177
+ | `markdown` | string | yes | Clipped Markdown body |
178
+ | `title` | string | yes | Title |
179
+ | `path` | string | no | Note path |
180
+ | `tags` | string[] | no | Tags |
181
+ | `sourceUrl` | string | no | Source URL |
182
+ | `capturedAt` | string | no | Capture time (ISO) |
183
+
184
+ **Unified response format** (eliminates legacy field redundancy / inconsistent error codes):
185
+
186
+ - Success: `{ ok: true, data?: { at: string } }`
187
+ - Failure: `{ ok: false, error: { code: ClipperErrorCode; message: string } }`
188
+
189
+ Error codes (stable, so the extension can handle them precisely):
190
+
191
+ | code | HTTP | Description |
192
+ |------|------|------|
193
+ | `UNAUTHORIZED` | 401 | token verification failed |
194
+ | `INVALID_JSON` | 400 | request body is not valid JSON |
195
+ | `MARKDOWN_REQUIRED` | 422 | missing `markdown` field |
196
+ | `NOT_FOUND` | 404 | route not found |
197
+ | `INTERNAL` | 500 | internal error |
198
+
199
+ For pure browser scenarios (no Node runtime), use `startBrowserClipperReceiver`, which receives via `window.postMessage` without HTTP:
200
+
201
+ ```ts
202
+ import { startBrowserClipperReceiver } from "@qingwu-ui/ai-editor";
203
+
204
+ startBrowserClipperReceiver({
205
+ onClip: (clip) => editor.commands.setContent(clip.markdown),
206
+ });
207
+ ```
208
+
209
+ ### Configuration
210
+
211
+ In the extension sidebar "Settings":
212
+
213
+ - **Push method** - HTTP (default, push to local receiver) / File (download Markdown to a specified directory)
214
+ - **HTTP endpoint** - default `http://127.0.0.1:7321/clip`
215
+ - **Editor page URL** - fallback editor URL when HTTP is unreachable (default `http://localhost:5173`)
216
+
217
+ ## API
218
+
219
+ ### `<QingWuAIEditor>` Props
220
+
221
+ | Prop | Type | Default | Description |
222
+ |------|------|--------|------|
223
+ | `initialContent` | `string` | `""` | Initial HTML content (auto-sanitized) |
224
+ | `onChange` | `(html: string, json: object) => void` | - | Content change callback |
225
+ | `placeholder` | `string` | `"Type '/' for menu…"` | Placeholder text |
226
+ | `mode` | `"edit" \| "view"` | `"edit"` | Editor mode; `"view"` for read-only |
227
+ | `readonly` | `boolean` | `false` | **Deprecated**, use `mode="view"` instead |
228
+ | `maxLength` | `number` | - | Max character limit |
229
+ | `maxAttachmentSize` | `number` | **required** | Max size of a single uploaded file (bytes); oversize files are blocked and reported via `onToast` |
230
+ | `maxTotalAttachmentSize` | `number` | **required** | Max total size of all attachments in the document (bytes); new uploads rejected when exceeded |
231
+ | `onToast` | `(message: string, type: `"success"` \| `"error"` \| `"info"`, options?) => void` | - | Global toast callback (attachment limit blocks / document oversize warnings). Wire it to your own toast component; third arg `options` passes display options (`persist`/`maxLines`/`duration`), old two-arg signature remains compatible |
232
+ | `className` | `string` | `""` | Custom class name |
233
+ | `style` | `React.CSSProperties` | - | Custom container style |
234
+ | `borderless` | `boolean` | `false` | Hide editor outer border |
235
+ | `showToolbar` | `boolean` | `true` | Show top toolbar (export) |
236
+ | `showToc` | `boolean` | `true` | Show TOC sidebar |
237
+ | `showSearch` | `boolean` | `true` | Enable full-text search (Ctrl+F) |
238
+ | `onEditorReady` | `(editor: Editor) => void` | - | Editor instance ready callback |
239
+
240
+ ### Writing assistant
241
+
242
+ ```ts
243
+ setAIProvider(provider: AIProvider): void
244
+ getAIProvider(): AIProvider
245
+ createAILanguageModelProvider(config: AILanguageModelConfig): Promise<AIProvider>
246
+ ```
247
+
248
+ ### Storage
249
+
250
+ ```ts
251
+ setStorageProvider(provider: StorageProvider, config?: StorageConfig): void
252
+ getStorageProvider(): StorageProvider
253
+ getStorageInfo(): { name, type, config } | null
254
+ loadStorageConfig(): StorageConfig | null
255
+
256
+ // Built-in providers
257
+ createLocalStorage(): StorageProvider
258
+ createOSSStorage(config: OSSStorageConfig): StorageProvider
259
+ createCOSStorage(config: COSStorageConfig): StorageProvider
260
+ createS3Storage(config: S3StorageOptions): StorageProvider
261
+ ```
262
+
263
+ ### i18n
264
+
265
+ ```ts
266
+ setLocale(locale: "zh-CN" | "en-US"): void
267
+ getLocale(): Locale
268
+ t(path: string): string
269
+ tf(path: string, ...args): string // named / positional placeholder interpolation
270
+ ```
271
+
272
+ ### Extension helpers
273
+
274
+ ```ts
275
+ getEditorExtensions(config?: EditorExtensionsConfig): Extension[]
276
+ createSlashCommandExtension(getItems: () => SlashCommandItem[]): Extension
277
+ getDefaultSlashCommands(t: (key: string) => string): SlashCommandItem[]
278
+ getBubbleMenuActions(t: (key: string) => string): BubbleMenuAction[]
279
+ setSearchEngine(template: string): void
280
+ getSearchEngine(): string
281
+ ```
282
+
283
+ ## Development
284
+
285
+ ```bash
286
+ # Install dependencies
287
+ npm install
288
+
289
+ # Start the dev server
290
+ npm run dev
291
+
292
+ # Type check
293
+ npm run typecheck
294
+
295
+ # Build
296
+ npm run build
297
+
298
+ # Test
299
+ npm test
300
+ ```
301
+
302
+ ## Tech stack
303
+
304
+ | Layer | Tech |
305
+ |------|------|
306
+ | Editor core | [Tiptap](https://tiptap.dev/) (ProseMirror) |
307
+ | UI framework | React 19 |
308
+ | Command palette | [cmdk](https://cmdk.paco.me/) |
309
+ | AI SDK | [Vercel AI SDK](https://sdk.vercel.ai/) |
310
+ | Code highlighting | [lowlight](https://github.com/wooorm/lowlight) |
311
+ | Math formulas | [KaTeX](https://katex.org/) |
312
+ | Video playback | [xgplayer](https://h5player.bytedance.com/) |
313
+ | File preview | [FileViewer](https://doc.file-viewer.app/) |
314
+ | Animation | [Framer Motion](https://www.framer.com/motion/) |
315
+ | Build | [Vite](https://vitejs.dev/) |
316
+ | Styling | [Tailwind CSS](https://tailwindcss.com/) |
317
+
318
+ ## License
319
+
320
+ [Apache-2.0](./LICENSE) © 2026 QingWu Contributors
321
+
322
+ ---
323
+
324
+ <p align="center">
325
+ <sub>Tribute to <a href="https://github.com/steven-tey/novel">Novel</a> (steven-tey/novel); QingWu Editor is built inspired by it.</sub>
326
+ </p>
327
+