# Myzard 카드에 넣을 웹 도구 만들기 (AI에게 주는 안내문)

이 글은 사용자가 AI에게 그대로 붙여 넣는 안내문입니다. AI는 아래 규칙을 지켜서, 사용자가 이어서 설명하는 도구를 만들어 주세요.

규격 번호: 1 (2026-11)

## 무엇을 만드나

- Myzard는 크롬의 새 탭을 카드로 꾸미는 확장 프로그램입니다. 「웹사이트」 카드에 주소를 넣으면 그 페이지가 카드 안에 뜹니다(iframe).
- 만들 것은 **그 카드 안에서 쓰는 작은 웹 페이지 하나**입니다. 계산기, 현황판, 체크리스트, 개인 대시보드 같은 것입니다.
- Myzard 자체를 고치거나 확장 프로그램을 만드는 일이 아닙니다.

## 결과물

- **파일 하나**(`index.html`)에 HTML, CSS, JavaScript를 모두 넣습니다. 빌드 없이 그대로 열리는 정적 페이지여야 합니다.
- `https` 주소로 열려야 합니다(만드는 동안에는 `http://localhost`도 됩니다). GitHub Pages, Vercel, Netlify, Cloudflare Pages 같은 정적 호스팅이면 됩니다.
- 사용자가 개발자가 아닐 수 있습니다. 파일을 올려 주소를 얻는 방법을 단계별로 알려 주세요.

## 꼭 지킬 것

1. **다른 페이지 안에 표시될 수 있어야 합니다.** `X-Frame-Options` 헤더나 `Content-Security-Policy: frame-ancestors`로 막지 마세요. 정적 호스팅의 기본 설정은 대개 괜찮습니다.
2. **작은 화면에서 써야 합니다.** 카드 크기는 사용자가 정합니다. 폭 280px, 높이 200px에서도 쓸 수 있게 하고, 폭과 높이를 100% 쓰는 반응형으로 만드세요. 가로 스크롤이 생기면 안 됩니다. 바깥 여백은 12~16px이 알맞습니다.
3. **밝게·어둡게를 둘 다 지원합니다.** 주소의 `mode` 값(`light` 또는 `dark`)이 있으면 그것을 따르고, 없으면 `prefers-color-scheme`을 따르세요.
4. **로그인 없이 동작해야 합니다.** 카드 안의 페이지는 쿠키와 저장소가 막히거나 따로 나뉠 수 있어서 로그인 상태가 유지되지 않습니다.
5. **비밀 키를 페이지에 넣지 마세요.** 페이지의 코드는 누구나 볼 수 있습니다.
6. **저장은 실패해도 돌아가게 합니다.** `localStorage`를 써도 되지만 `try/catch`로 감싸고, 막혀 있으면 저장 없이 동작하게 하세요. 카드 안에서 저장한 것은 같은 페이지를 새 탭에서 직접 열었을 때의 저장과 따로일 수 있고, Myzard의 백업에는 들어가지 않습니다.

## Myzard가 주소로 넘겨 주는 값

사용자가 카드에 주소를 넣을 때 자리표시를 적으면 Myzard가 채워서 엽니다.

```
https://내-도구.example/?lang={lang}&mode={mode}
→ https://내-도구.example/?lang=ko&mode=dark
```

| 자리표시 | 값 | 뜻 |
|---|---|---|
| `{lang}` | `ko` 또는 `en` | Myzard의 화면 언어 |
| `{mode}` | `light` 또는 `dark` | Myzard의 밝게·어둡게 |

- 값이 없을 때(페이지를 직접 열었을 때)도 동작해야 합니다. 기본값을 두세요.
- 사용자가 테마를 바꾸면 페이지가 새 값으로 다시 열립니다.
- 넘겨 주는 것은 이 둘뿐입니다. 사용자 이름, 식별자, Myzard 안의 자료는 넘겨 주지 않습니다.

```js
const params = new URLSearchParams(location.search);
const lang = params.get('lang') === 'en' ? 'en' : 'ko';
const mode = params.get('mode') || (matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
document.documentElement.lang = lang;
document.documentElement.dataset.mode = mode; // CSS 에서 [data-mode="dark"] 로 색을 바꾼다
```

## 수신함에 소식 남기기 (선택)

사용자가 놓치면 안 되는 일이 생겼을 때, 페이지가 Myzard의 수신함에 소식 한 건을 남길 수 있습니다. 소식이 오면 그 카드가 있는 탭에 숫자가 붙고 화면에 알림이 뜹니다.

```js
function notifyMyzard(title, message, level, key) {
  if (window.parent === window) return; // Myzard 밖에서 직접 연 경우
  window.parent.postMessage({ myzard: 1, type: 'event', title, message, level, key }, '*');
}

notifyMyzard('재고 부족', 'A-102가 3개 남았습니다', 'warn', 'stock:A-102');
```

| 값 | 필수 | 규칙 |
|---|---|---|
| `myzard` | 예 | 숫자 `1` |
| `type` | 예 | `'event'` |
| `title` | 예 | 80자까지. 무슨 일인지 한 줄로 |
| `message` | 아니오 | 300자까지 |
| `level` | 아니오 | `'info'`(기본) 또는 `'warn'` |
| `key` | 아니오 | 64자까지. 같은 일을 가리키는 이름. 같은 `key`는 1분 안에 한 번만 쌓입니다 |

- **사용자가 켜야 받습니다.** 카드 설정의 「이 사이트의 소식 받기」가 꺼져 있으면(기본값) 아무 일도 일어나지 않습니다. 소식을 쓰는 도구를 만들었다면 사용자에게 이 설정을 켜라고 알려 주세요.
- **한 방향입니다.** Myzard는 답을 보내지 않습니다. 도착했는지 확인할 수 없으니 페이지 안에도 같은 내용을 보여 주세요.
- **글자만 보냅니다.** HTML이나 링크는 글자 그대로 보입니다.
- **한도가 있습니다.** 카드마다 10초에 한 건, 한 시간에 20건까지 받고 넘는 것은 버려집니다.
- **카드가 떠 있을 때만 됩니다.** 새 탭이 닫혀 있으면 페이지도 돌지 않습니다. 새 탭이 다른 탭 뒤에 가려져 있을 때는 전달되고, 사용자가 Myzard의 시스템 알림을 켜 두었다면 화면 구석에 알림도 뜹니다.
- **가려진 탭에서는 타이머가 늦게 돕니다.** 브라우저는 가려진 탭의 `setInterval`·`setTimeout`을 1초에 한 번, 오래 가려져 있으면 1분에 한 번으로 늦추고 `requestAnimationFrame`은 멈춥니다. 시간을 재는 도구는 남은 시간을 조금씩 빼지 말고 **끝나는 시각을 저장해 두고 `Date.now()`와 비교**하세요. `visibilitychange`에서도 한 번 확인하면 탭으로 돌아왔을 때 바로 맞춰집니다. 그래도 가려진 동안의 소식은 최대 1분쯤 늦을 수 있습니다.
- **아껴서 씁니다.** 사용자가 방금 누른 단추의 결과("저장됨")에는 쓰지 마세요. 자리를 비운 사이에 생긴 일, 기준을 넘은 값처럼 나중에라도 알아야 하는 일에만 씁니다.

## 카드 안에서 안 되는 것

| 안 되는 것 | 대신 |
|---|---|
| `alert`, `confirm`, `prompt` (아무 일도 일어나지 않음) | 페이지 안에 직접 그린 안내와 확인 단추 |
| 파일 내려받기 | 결과를 화면에 보여 주고 사용자가 선택해 복사하게 하기 |
| 클립보드에 쓰기(막힐 수 있음) | 실패하면 글을 선택할 수 있게 보여 주기 |
| 화면 전체를 다른 주소로 보내기 | 링크는 `target="_blank"`로 새 탭에서 열기 |
| 알림·카메라·마이크·위치 권한 요청 | 쓰지 않기. 알릴 일은 위의 소식으로 |
| 전체 화면, 소리 자동 재생 | 쓰지 않기 |
| Myzard의 자료 읽기, 다른 카드 조작 | 불가능합니다. 필요한 값은 사용자가 페이지에 직접 입력하게 하기 |
| 로그인이 필요한 화면 | 로그인 없는 도구로 만들기 |

- 다른 서버의 자료를 불러올 때는 그 서버가 브라우저에서의 호출(CORS)을 허용해야 합니다.
- 자료를 주기적으로 다시 불러온다면 30초보다 짧게 잡지 마세요. 페이지 전체를 다시 여는 것은 카드의 「자동 새로 고침」 설정이 합니다.

## 다 만든 뒤 사용자에게 알려 줄 것

1. 파일을 올려 `https` 주소를 얻는 방법
2. Myzard에서 넣는 방법: 오른쪽 위 「앱 추가」 → 「웹사이트」 → 주소 붙여넣기. 주소 끝에 `?lang={lang}&mode={mode}`를 붙이라고 알려 주세요.
3. 소식을 보내는 도구라면: 카드 설정에서 「이 사이트의 소식 받기」 켜기
4. 화면이 비어 보이면: 호스팅이 다른 페이지 안에 표시되는 것을 막고 있는지 확인하기

## 내놓기 전에 스스로 확인할 것

- [ ] 파일 하나로 열리고, 빌드가 필요 없다
- [ ] 폭 280px에서 가로 스크롤 없이 쓸 수 있다
- [ ] `?mode=dark`와 `?mode=light`에서 모두 읽기 좋다
- [ ] `lang`과 `mode`가 없어도 동작한다
- [ ] `alert`·`confirm`·내려받기·권한 요청을 쓰지 않았다
- [ ] 저장소가 막혀도 오류 없이 동작한다
- [ ] 비밀 키가 없다
- [ ] 소식은 꼭 필요한 일에만 보내고, 같은 내용을 페이지 안에도 보여 준다
