@lemoncloud/chatic-apps-sdk 0.1.0 → 0.3.0

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.
@@ -0,0 +1,263 @@
1
+ ---
2
+ name: chatic-mini-app
3
+ description: DoU 앱 안에서 열리는 페이지인 Chatic 미니앱을 웹 페이지를 만들어 본 적 없는 사람과 함께 만든다 — 아이디어를 묻고, SDK의 mock 위에서 만들고, 검증하고 zip으로 묶는다.
4
+ ---
5
+
6
+ > English: [SKILL.md](./SKILL.md) — 영어판이 정본입니다. 두 판이 다르면 영어판을 따르세요.
7
+
8
+ # Chatic 미니앱을 차근차근 만들기
9
+
10
+ `@lemoncloud/chatic-apps-sdk` 0.3.0과 `@lemoncloud/chatic-apps-devtools` 0.1.0 기준으로 쓴 것이다.
11
+
12
+ 이 문서는 누군가 Chatic 미니앱 — DoU 앱 안에서 열리는 웹 페이지 — 을 만들도록 돕는 AI 어시스턴트가 따르는
13
+ 절차다. 그 사람은 웹 페이지를 한 번도 만들어 본 적이 없을 수 있다. 질문을 주고받으며 세 단계 — 아이디어, 초기 구축,
14
+ 배포 준비 — 를 차례로 이끌고, 검증기를 통과한 zip으로 끝낸다. 바로 코드로 뛰어들지 않는다.
15
+
16
+ 이 절차가 다시 적지 않는 것은 같은 패키지의 문서 셋에 있다. 그것에 기대는 코드를 쓰기 전에 필요한 부분을 읽는다.
17
+
18
+ - `AGENTS.ko.md`(정본은 영어판 `AGENTS.md`) — 모든 페이지가 지키는 규칙. 이 절차는 가리키기만 한다.
19
+ - `README.ko.md`(영어판 `README.md`) — 모든 호출과 인자 · 한도 · 오류 코드, 권한마다 열리는 것.
20
+ - `GUIDE.ko.md`(영어판 `GUIDE.md`) — 프로젝트를 꾸리는 법, 번들, 화면과 뒤로 가기, 클라우드의 데이터, 서버.
21
+
22
+ ## 해도 되는 것
23
+
24
+ - **프로젝트 폴더 안의 파일만 고친다.** 그 밖은 건드리지 않는다.
25
+ - **설치는 한 번**, 2단계에서만 한다: 아래 시작 `package.json`에 적힌 패키지와 버전 그대로. 설치하기 전에 무엇을
26
+ 설치하는지 말하고 묻는다. 그 밖의 것은 절대 설치하지 않는다.
27
+ - **프로젝트의 스크립트만 돌린다**: 페이지를 보여 주는 `npm run dev`, `npm run build`, `npm run verify`,
28
+ `npm run bundle`.
29
+ - 스스로 네트워크 요청을 하지 않고, 프로젝트 밖의 경로를 읽거나 쓰지 않으며, 무엇도 업로드 · 제출 · 배포하지 않는다.
30
+
31
+ ## 지금 어디쯤인가
32
+
33
+ 이 절차를 시작할 때마다 먼저 한다.
34
+
35
+ 1. **프로젝트 맨 위의 `MINIAPP.md`가 있으면 읽는다.** 계획이자 상태다. 어느 단계에 있고 무엇이 남았는지 말하고
36
+ 거기서 이어 간다. 이 파일이 이미 답한 것은 다시 묻지 않는다.
37
+ 2. **SDK 버전을 확인한다.** `node_modules/@lemoncloud/chatic-apps-sdk/package.json`이 있고 그 `version`이 이 문서
38
+ 맨 위의 것과 다르면 알린다: 이 절차의 사본이 오래됐을 수 있고, 새 사본은 설치된 패키지에 들어 있다(`GUIDE.ko.md`의
39
+ "프로젝트의 AI 어시스턴트를 위해").
40
+ 3. **아니면 1단계부터** 시작하되, 그 사람이 이미 말한 것을 바탕으로 한다.
41
+
42
+ ## 묻는 법
43
+
44
+ - **한 번에 하나씩**, 그 사람이 쓰는 말로, 쉬운 말로 묻는다.
45
+ - **고를 것이 있으면 보기 2 ~ 4개**를 주고, 무엇을 추천하는지와 그 이유를 한 줄로 말한다. 그 사람은 언제든 자기
46
+ 말로 답해도 된다.
47
+ - **용어는 처음 나올 때 한 줄로 푼다**: *권한*은 페이지가 매니페스트에서 앱에 요청하는 것, *매니페스트*는 페이지의
48
+ 이름과 권한 목록을 적는 작은 파일, *mock*은 브라우저에서 앱 대신 도는 대역이다.
49
+ - **이미 말한 것은 다시 묻지 않는다.** 처음에 많이 말했으면 빈 것만 묻는다. "그냥 만들어"라고 하면 1단계를 요약
50
+ 확인 한 번으로 줄인다.
51
+ - **단계마다 끝에서** 짧게 정리해 보여 주고 "다음 단계로 갈까요?"라고 묻는다.
52
+
53
+ ## 1단계 — 아이디어
54
+
55
+ 아직 모르는 것을 대략 이 순서로 묻는다. 줄마다 질문, 그리고 추천이다.
56
+
57
+ 1. 미니앱이 무엇을 하는지 몇 문장으로 말해 주세요. — 추천할 것 없이 그 사람이 설명하게 한다.
58
+ 2. 누가, 언제 쓰나요? — 클라우드의 한 플레이스 멤버들이 DoU 안에 있을 때.
59
+ 3. 화면은 무엇이 있고 화면마다 무엇이 있나요? — 둘이나 셋으로 시작한다: 첫 화면과 거기서 가는 화면.
60
+ 4. 닫힐 때 결과를 돌려주나요? — 아니요. 결과를 받으려고 연 곳이 있을 때만.
61
+ 5. 클라우드의 대화방 · 메시지 · 멤버를 읽거나, 메시지를 보내거나, 메시지에 반응하나요? — 아이디어에 필요할 때만. 하나하나가 사용자가 허락하는 권한이고,
62
+ 받은 것으로 무엇을 하는지는 페이지 작성자가 책임진다.
63
+ 6. 공유 · 복사 · 바깥 링크 열기가 필요한가요? — 아이디어에 필요한 것만. 이것도 하나하나 권한이다.
64
+ 7. 게임처럼 화면 전체가 필요한가요? — 아니요. 보통 화면이면 앱의 닫기 버튼과 휴대폰의 안전 영역을 알아서 맞춰 준다.
65
+ 8. 사용자가 잃으면 안 되는 것 — 진행 상황, 작성 중인 글 — 이 있나요? — 바뀔 때마다 기기에 저장한다.
66
+ 9. 직접 운영하는 서버를 부르나요? — 서버가 없는 것이 가장 단순하다. 있다면 `GUIDE.ko.md`의 "직접 운영하는 서버"를
67
+ 함께 읽는다.
68
+
69
+ 그다음 프로젝트 맨 위에 `MINIAPP.md`를 그 사람의 말로 쓰고 보여 준다.
70
+
71
+ ```markdown
72
+ # <name of the mini-app>
73
+
74
+ Stage: 1 idea — done · 2 first build — next · 3 release prep — not started
75
+
76
+ ## What it does
77
+
78
+ <a few sentences>
79
+
80
+ ## Screens
81
+
82
+ 1. <first screen>: <what is on it>
83
+ 2. <screen>: <what is on it, how it is reached, how back returns>
84
+
85
+ ## What it asks the app for
86
+
87
+ - Permissions: <none, or each one with the reason>
88
+ - Display: clean · Orientation: portrait
89
+ - Result when it closes: <none, or what>
90
+ - Saved on the device: <none, or what>
91
+ - Own server: <none, or its address and what it receives>
92
+
93
+ ## Progress
94
+
95
+ - [ ] Starting files and first install
96
+ - [ ] <one line per screen>
97
+ - [ ] Verify passes
98
+ - [ ] Zip built
99
+ ```
100
+
101
+ ## 2단계 — 초기 구축
102
+
103
+ 1. **도구를 묻는다.** 이미 쓰는 프레임워크가 있나? 추천은 없음: Vite와 그냥 TypeScript다.
104
+ React · Vue · Svelte라고 하면 `GUIDE.ko.md`의 "도구 고르기"를 따르고, 아래의 나머지는 그대로 둔다.
105
+ 2. **시작 파일을 깐다.** 그 사람에게 이미 시작점으로 쓸 미니앱이 있으면 그것을 복사한다.
106
+ 없으면 아래 시작 파일을 만든다. 매니페스트는 `MINIAPP.md`에서 채운다: 이름, 그리고 거기 적힌 권한만.
107
+ 3. **묻고 설치한다.** 이렇게 말한다: "이 폴더에 @lemoncloud/chatic-apps-sdk 0.3.0, @lemoncloud/chatic-apps-devtools
108
+ 0.1.0, Vite 7.3.0, TypeScript 5.9.3을 `npm install`로 설치할게요. 진행할까요?" 그렇다고 할 때만 `npm install`을
109
+ 돌린다.
110
+ 4. **화면은 하나씩 만든다.** 화면을 쓰고, `npm run dev`를 돌리고, 출력된 주소를 브라우저에서 열어 보라고 한다: 거기서는
111
+ mock이 앱 대신 페이지에 답한다. 무엇을 바꿀지 묻고, 바꾸고, `MINIAPP.md`에서 그 화면에 표시한다. 만드는 동안
112
+ `AGENTS.ko.md`의 규칙을 지킨다 — 화면은 메모리 안의 목록과 `apps.onBack`으로, 테마는 앱의 것, 저장은
113
+ `apps.storage`, 분기는 메시지가 아니라 코드로.
114
+ 5. **mock에는 지어낸 데이터를 준다**(`src/mockData.ts`): 페이지가 읽는 것에 대해 지어낸 id와 이름만, 실제 클라우드의
115
+ 것은 쓰지 않는다.
116
+ 6. **화면이 둘 이상이 되면** `chatic-apps.scenarios.ts`에 화면을 적어 검증기에게 알려 준다. 그래야 화면마다 뒤로 가기와
117
+ 정리를 시험한다.
118
+ 7. `MINIAPP.md`의 단계 줄을 고치고, 정리해 보여 주고, 다음으로 갈지 묻는다.
119
+
120
+ ### 시작 파일
121
+
122
+ `package.json` — 버전은 이대로, 그 밖의 것은 설치하지 않는다.
123
+
124
+ ```json
125
+ {
126
+ "name": "my-mini-app",
127
+ "private": true,
128
+ "type": "module",
129
+ "scripts": {
130
+ "dev": "vite",
131
+ "build": "tsc --noEmit && vite build",
132
+ "verify": "chatic-apps verify",
133
+ "bundle": "chatic-apps bundle"
134
+ },
135
+ "dependencies": {
136
+ "@lemoncloud/chatic-apps-sdk": "0.3.0"
137
+ },
138
+ "devDependencies": {
139
+ "@lemoncloud/chatic-apps-devtools": "0.1.0",
140
+ "typescript": "5.9.3",
141
+ "vite": "7.3.0"
142
+ }
143
+ }
144
+ ```
145
+
146
+ `tsconfig.json`:
147
+
148
+ ```json
149
+ {
150
+ "compilerOptions": {
151
+ "target": "ES2022",
152
+ "module": "ESNext",
153
+ "moduleResolution": "bundler",
154
+ "lib": ["ES2022", "DOM"],
155
+ "types": ["vite/client"],
156
+ "strict": true,
157
+ "resolveJsonModule": true,
158
+ "isolatedModules": true,
159
+ "skipLibCheck": true,
160
+ "noEmit": true
161
+ },
162
+ "include": ["src", "public/.well-known/chatic-app.json", "chatic-apps.scenarios.ts"]
163
+ }
164
+ ```
165
+
166
+ `index.html`:
167
+
168
+ ```html
169
+ <!doctype html>
170
+ <html lang="en">
171
+ <head>
172
+ <meta charset="UTF-8" />
173
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
174
+ <title>My mini-app</title>
175
+ </head>
176
+ <body>
177
+ <main id="app"></main>
178
+ <script type="module" src="/src/main.ts"></script>
179
+ </body>
180
+ </html>
181
+ ```
182
+
183
+ `public/.well-known/chatic-app.json` — 매니페스트. `MINIAPP.md`에 적힌 권한만 넣는다.
184
+
185
+ ```json
186
+ {
187
+ "manifestVersion": 1,
188
+ "name": "My mini-app",
189
+ "permissions": [],
190
+ "display": "clean",
191
+ "orientation": "portrait"
192
+ }
193
+ ```
194
+
195
+ `src/main.ts` — 연결하고, mock은 개발 중에만 쓴다.
196
+
197
+ ```ts
198
+ import { ChaticAppsError, connect, type ChaticApps } from '@lemoncloud/chatic-apps-sdk';
199
+ import { installChaticAppsMock, type MockPermission } from '@lemoncloud/chatic-apps-sdk/mock';
200
+
201
+ import manifest from '../public/.well-known/chatic-app.json';
202
+ import { mockData } from './mockData';
203
+
204
+ const root = document.getElementById('app') as HTMLElement;
205
+
206
+ function start(apps: ChaticApps) {
207
+ document.documentElement.dataset.theme = apps.context?.theme ?? 'light';
208
+ apps.onContextChange(context => (document.documentElement.dataset.theme = context.theme));
209
+ root.textContent = 'Hello from my mini-app';
210
+ }
211
+
212
+ async function main() {
213
+ // The stand-in for the app, in the browser during development only: a production build drops it.
214
+ if (import.meta.env.DEV) {
215
+ installChaticAppsMock({ permissions: manifest.permissions as MockPermission[], data: mockData });
216
+ }
217
+ try {
218
+ start(await connect());
219
+ } catch (error) {
220
+ const needsUpdate = error instanceof ChaticAppsError && error.code === 'UNSUPPORTED_PROTOCOL';
221
+ root.textContent = needsUpdate ? 'This page needs an update.' : 'This page could not start.';
222
+ }
223
+ }
224
+
225
+ void main();
226
+ ```
227
+
228
+ `src/mockData.ts` — 페이지가 클라우드를 읽을 때 mock이 답하는 것. 브라우저와 `verify` 둘 다 이것을 쓴다. 페이지가
229
+ 무언가를 읽기 전까지는 비어 있다.
230
+
231
+ ```ts
232
+ import type { MockData } from '@lemoncloud/chatic-apps-sdk/mock';
233
+
234
+ // Made-up data only: invented ids and names, never a real cloud's.
235
+ export const mockData: MockData = {};
236
+ ```
237
+
238
+ `chatic-apps.scenarios.ts` — 화면이 생기면 쓴다. `open`마다 첫 화면에서 그 화면까지 누르는 순서를 적는다.
239
+
240
+ ```ts
241
+ import { mockData } from './src/mockData';
242
+
243
+ export default {
244
+ data: mockData,
245
+ ready: '[data-action="start"]',
246
+ screens: [{ name: 'question', open: ['[data-action="start"]'] }],
247
+ actions: [],
248
+ };
249
+ ```
250
+
251
+ ## 3단계 — 배포 준비
252
+
253
+ 1. **검증한다.** `npm run build` 다음에 `npm run verify`를 돌린다. 매니페스트 · 코드 · 빌드를 점검하고, mock 위에서
254
+ 페이지를 시험한다: 뒤로 가기, 닫기, 테마, 숨김, 거절.
255
+ 2. **출력된 줄을 하나씩** 다룬다: 무엇이 문제이고 무엇을 바꿀지 쉬운 말로 말하고, 바꾸기 전에 묻는다. 고친 뒤 다시
256
+ 빌드하고 검증한다. verify가 "넘길 준비가 됐습니다"로 끝나기 전에는 끝났다고 말하지 않는다.
257
+ 3. **앱에서 직접 볼지 묻는다.** 휴대폰에서 보고 싶다고 하면 `GUIDE.ko.md`의 "앱 안에서 시험하기"를 따르고, 시작하기 전에
258
+ 그 한계를 말한다.
259
+ 4. **묶는다.** `npm run bundle`을 돌린다: 빌드를 zip으로 쓰고, 맨 위에 `index.html`과 매니페스트가 있다. zip이 어디
260
+ 있는지 알려 준다.
261
+ 5. **`GUIDE.ko.md`의 "넘겨주기 전에"를** 그 사람과 한 항목씩 짚는다.
262
+ 6. **거기서 멈춘다.** zip을 어디에도 올리거나 제출하지 않는다. 이렇게 말한다: "미니앱과 zip이 준비됐어요. DoU에
263
+ 제출하는 창구는 아직 준비 중이에요." `MINIAPP.md`에서 3단계를 끝남으로 표시한다.
package/skill/SKILL.md ADDED
@@ -0,0 +1,275 @@
1
+ ---
2
+ name: chatic-mini-app
3
+ description: Build a Chatic mini-app, a page that opens inside the DoU app, with someone who may never have built a web page — ask about the idea, build it against the SDK's mock, verify it and pack the zip.
4
+ ---
5
+
6
+ > Korean: [SKILL.ko.md](./SKILL.ko.md). This English version is the canonical one.
7
+
8
+ # Building a Chatic mini-app, step by step
9
+
10
+ Written for `@lemoncloud/chatic-apps-sdk` 0.3.0 and `@lemoncloud/chatic-apps-devtools` 0.1.0.
11
+
12
+ This is a procedure for an AI assistant helping someone build a Chatic mini-app: a web page that opens
13
+ inside the DoU app. The person may never have built a web page. Lead them through three stages by
14
+ asking questions — the idea, the first build, the release prep — and end with a zip that passes the
15
+ verifier. Do not jump to code.
16
+
17
+ Three documents in the same package hold what this procedure does not repeat. Read the part you need
18
+ before you write code that depends on it:
19
+
20
+ - `AGENTS.md` — the rules every page keeps. It is the authority; this procedure only points at it.
21
+ - `README.md` — every call, its arguments, limits and error codes, and what each permission opens.
22
+ - `GUIDE.md` — how a project is set up, the bundle, screens and back, the cloud's data, servers.
23
+
24
+ ## What you may do
25
+
26
+ - **Edit files inside the project folder**, and nothing outside it.
27
+ - **Install once**, in stage 2: exactly the packages and versions in the starting `package.json` below.
28
+ Before installing, say what will be installed and ask. Install nothing else, ever.
29
+ - **Run the project's own scripts**: `npm run dev` to show the page, `npm run build`, `npm run verify` and
30
+ `npm run bundle`.
31
+ - Make no network requests of your own, read or write no path outside the project, and never upload,
32
+ submit or deploy anything.
33
+
34
+ ## Where are we?
35
+
36
+ Do this first, every time this procedure starts:
37
+
38
+ 1. **Read `MINIAPP.md`** at the project's top if it exists. It is the plan and the state: say which stage
39
+ it records and what is left, and carry on from there. Do not ask again what it already answers.
40
+ 2. **Check the SDK version.** If `node_modules/@lemoncloud/chatic-apps-sdk/package.json` exists and its
41
+ `version` is not the one at the top of this file, say so: this copy of the procedure may be out of
42
+ date, and a fresh copy comes with the installed package (see `GUIDE.md`, "For an AI assistant in your
43
+ project").
44
+ 3. **Otherwise start at stage 1** with whatever the person already said.
45
+
46
+ ## How to ask
47
+
48
+ - **One question at a time**, in the language the person writes in, in plain words.
49
+ - **Offer 2 to 4 choices** when there is something to pick, and say which one you recommend and why, in
50
+ one line. The person can always answer in their own words.
51
+ - **Explain a term the first time it comes up**, in one line: a _permission_ is what the page asks the
52
+ app for in its manifest; the _manifest_ is a small file that names the page and lists its permissions;
53
+ the _mock_ is a stand-in for the app that runs in a browser.
54
+ - **Never ask again** what the person already said. If they gave a lot at the start, ask only for what
55
+ is missing. If they say "just build it", turn stage 1 into one summary to confirm.
56
+ - **End each stage** with a short summary and "Shall we go on to the next stage?".
57
+
58
+ ## Stage 1 — the idea
59
+
60
+ Ask what is still unknown, in roughly this order. Each line is the question, then what you recommend.
61
+
62
+ 1. What does the mini-app do, in a few sentences? — Nothing to recommend; let them describe it.
63
+ 2. Who uses it, and when? — Members of one place in a cloud, while they are in DoU.
64
+ 3. Which screens does it have, and what is on each? — Start with two or three: a first screen and what
65
+ it leads to.
66
+ 4. When it closes, does it hand a result back? — No, unless something opened it to get one.
67
+ 5. Does it read the cloud's rooms, messages or members, send a message, or react to one? — Only if the idea needs them; each one is a
68
+ permission the user is asked to allow, and the page's author answers for what it does with it.
69
+ 6. Does it share, copy or open links outside? — Only what the idea needs; each is a permission too.
70
+ 7. Does it need the whole screen, like a game? — No: the normal display keeps the app's close button
71
+ and the phone's safe area handled for you.
72
+ 8. Is there anything the user must not lose, like progress or a draft? — Save it on the device as it
73
+ changes.
74
+ 9. Does it call a server of your own? — No server is simplest. If yes, read `GUIDE.md`, "Your own
75
+ server", with them.
76
+
77
+ Then write `MINIAPP.md` at the project's top, in the person's language, and show it:
78
+
79
+ ```markdown
80
+ # <name of the mini-app>
81
+
82
+ Stage: 1 idea — done · 2 first build — next · 3 release prep — not started
83
+
84
+ ## What it does
85
+
86
+ <a few sentences>
87
+
88
+ ## Screens
89
+
90
+ 1. <first screen>: <what is on it>
91
+ 2. <screen>: <what is on it, how it is reached, how back returns>
92
+
93
+ ## What it asks the app for
94
+
95
+ - Permissions: <none, or each one with the reason>
96
+ - Display: clean · Orientation: portrait
97
+ - Result when it closes: <none, or what>
98
+ - Saved on the device: <none, or what>
99
+ - Own server: <none, or its address and what it receives>
100
+
101
+ ## Progress
102
+
103
+ - [ ] Starting files and first install
104
+ - [ ] <one line per screen>
105
+ - [ ] Verify passes
106
+ - [ ] Zip built
107
+ ```
108
+
109
+ ## Stage 2 — the first build
110
+
111
+ 1. **Ask about the toolchain.** Does the person already use a framework? Recommend none: plain
112
+ TypeScript with Vite. If they name React, Vue or Svelte, follow
113
+ `GUIDE.md`, "Choose a toolchain", and keep everything else below the same.
114
+ 2. **Lay down the starting files.** If the person already has a working mini-app to start from,
115
+ copy it. Otherwise create the starting files below. Fill the
116
+ manifest from `MINIAPP.md`: its name, and only the permissions it lists.
117
+ 3. **Install, after asking.** Say: "I will install @lemoncloud/chatic-apps-sdk 0.3.0,
118
+ @lemoncloud/chatic-apps-devtools 0.1.0, Vite 7.3.0 and TypeScript 5.9.3 into this folder with
119
+ `npm install`. Shall I?" Run `npm install` only on a yes.
120
+ 4. **Build one screen at a time.** Write it, start `npm run dev`, and ask the person to open the address
121
+ it prints in their browser: the page runs there with the mock standing in for the app. Ask what to
122
+ change, change it, and tick the screen in `MINIAPP.md`. Keep the rules in `AGENTS.md` as you go —
123
+ screens in an in-memory stack with `apps.onBack`, the app's theme, `apps.storage`, codes not messages.
124
+ 5. **Give the mock made-up data** for what the page reads (`src/mockData.ts`): invented ids and names,
125
+ never a real cloud's.
126
+ 6. **Describe the screens to the verifier** in `chatic-apps.scenarios.ts` once there is more than one
127
+ screen, so it can try each screen's back and clean-up.
128
+ 7. Update `MINIAPP.md`'s stage line, summarise, and ask to go on.
129
+
130
+ ### Starting files
131
+
132
+ `package.json` — the exact versions; nothing else is installed:
133
+
134
+ ```json
135
+ {
136
+ "name": "my-mini-app",
137
+ "private": true,
138
+ "type": "module",
139
+ "scripts": {
140
+ "dev": "vite",
141
+ "build": "tsc --noEmit && vite build",
142
+ "verify": "chatic-apps verify",
143
+ "bundle": "chatic-apps bundle"
144
+ },
145
+ "dependencies": {
146
+ "@lemoncloud/chatic-apps-sdk": "0.3.0"
147
+ },
148
+ "devDependencies": {
149
+ "@lemoncloud/chatic-apps-devtools": "0.1.0",
150
+ "typescript": "5.9.3",
151
+ "vite": "7.3.0"
152
+ }
153
+ }
154
+ ```
155
+
156
+ `tsconfig.json`:
157
+
158
+ ```json
159
+ {
160
+ "compilerOptions": {
161
+ "target": "ES2022",
162
+ "module": "ESNext",
163
+ "moduleResolution": "bundler",
164
+ "lib": ["ES2022", "DOM"],
165
+ "types": ["vite/client"],
166
+ "strict": true,
167
+ "resolveJsonModule": true,
168
+ "isolatedModules": true,
169
+ "skipLibCheck": true,
170
+ "noEmit": true
171
+ },
172
+ "include": ["src", "public/.well-known/chatic-app.json", "chatic-apps.scenarios.ts"]
173
+ }
174
+ ```
175
+
176
+ `index.html`:
177
+
178
+ ```html
179
+ <!doctype html>
180
+ <html lang="en">
181
+ <head>
182
+ <meta charset="UTF-8" />
183
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
184
+ <title>My mini-app</title>
185
+ </head>
186
+ <body>
187
+ <main id="app"></main>
188
+ <script type="module" src="/src/main.ts"></script>
189
+ </body>
190
+ </html>
191
+ ```
192
+
193
+ `public/.well-known/chatic-app.json` — the manifest; list only the permissions `MINIAPP.md` names:
194
+
195
+ ```json
196
+ {
197
+ "manifestVersion": 1,
198
+ "name": "My mini-app",
199
+ "permissions": [],
200
+ "display": "clean",
201
+ "orientation": "portrait"
202
+ }
203
+ ```
204
+
205
+ `src/main.ts` — connects, with the mock in development only:
206
+
207
+ ```ts
208
+ import { ChaticAppsError, connect, type ChaticApps } from '@lemoncloud/chatic-apps-sdk';
209
+ import { installChaticAppsMock, type MockPermission } from '@lemoncloud/chatic-apps-sdk/mock';
210
+
211
+ import manifest from '../public/.well-known/chatic-app.json';
212
+ import { mockData } from './mockData';
213
+
214
+ const root = document.getElementById('app') as HTMLElement;
215
+
216
+ function start(apps: ChaticApps) {
217
+ document.documentElement.dataset.theme = apps.context?.theme ?? 'light';
218
+ apps.onContextChange(context => (document.documentElement.dataset.theme = context.theme));
219
+ root.textContent = 'Hello from my mini-app';
220
+ }
221
+
222
+ async function main() {
223
+ // The stand-in for the app, in the browser during development only: a production build drops it.
224
+ if (import.meta.env.DEV) {
225
+ installChaticAppsMock({ permissions: manifest.permissions as MockPermission[], data: mockData });
226
+ }
227
+ try {
228
+ start(await connect());
229
+ } catch (error) {
230
+ const needsUpdate = error instanceof ChaticAppsError && error.code === 'UNSUPPORTED_PROTOCOL';
231
+ root.textContent = needsUpdate ? 'This page needs an update.' : 'This page could not start.';
232
+ }
233
+ }
234
+
235
+ void main();
236
+ ```
237
+
238
+ `src/mockData.ts` — what the mock answers when the page reads the cloud, in the browser and in `verify`;
239
+ empty until the page reads something:
240
+
241
+ ```ts
242
+ import type { MockData } from '@lemoncloud/chatic-apps-sdk/mock';
243
+
244
+ // Made-up data only: invented ids and names, never a real cloud's.
245
+ export const mockData: MockData = {};
246
+ ```
247
+
248
+ `chatic-apps.scenarios.ts` — written once there are screens; each `open` lists the clicks from the first
249
+ screen that reach one:
250
+
251
+ ```ts
252
+ import { mockData } from './src/mockData';
253
+
254
+ export default {
255
+ data: mockData,
256
+ ready: '[data-action="start"]',
257
+ screens: [{ name: 'question', open: ['[data-action="start"]'] }],
258
+ actions: [],
259
+ };
260
+ ```
261
+
262
+ ## Stage 3 — the release prep
263
+
264
+ 1. **Verify.** Run `npm run build`, then `npm run verify`. It checks the manifest, the code and the
265
+ build, and tries the page against the mock: back, closing, the theme, hiding, refusals.
266
+ 2. **Go through each line it prints**, one at a time: say in plain words what is wrong and what you
267
+ would change, and ask before changing it. After the fixes, build and verify again. The page is not
268
+ done until verify ends with "Ready to hand over" — never say it is before then.
269
+ 3. **Offer to try it in the app.** If the person wants to see it on their phone, follow `GUIDE.md`,
270
+ "Trying it in the app", and say its limits before they start.
271
+ 4. **Pack it.** Run `npm run bundle`: it writes the zip of the build, with `index.html` and the manifest
272
+ at its top. Tell the person where the zip is.
273
+ 5. **Go through `GUIDE.md`, "Before you hand it over"**, with them, item by item.
274
+ 6. **Stop there.** Do not upload or submit the zip anywhere. Say: "The mini-app is ready, and so is the
275
+ zip. The way to submit it to DoU is still being prepared." Mark stage 3 done in `MINIAPP.md`.