# Building a web tool for a Myzard card (guide for your AI)

This is a guide a person pastes to an AI as is. AI: follow the rules below and build the tool the person describes next.

Spec version: 1 (2026-11)

## What you are building

- Myzard is a Chrome extension that turns the new tab into a board of cards. Put an address into a "Website" card and that page is shown inside the card (in an iframe).
- You are building **one small web page that runs inside that card**: a calculator, a status board, a checklist, a personal dashboard and the like.
- You are not changing Myzard itself and you are not building a browser extension.

## Output

- **A single file** (`index.html`) holding all HTML, CSS and JavaScript. It must be a static page that opens as is, with no build step.
- It must be served over `https` (`http://localhost` is fine while building). Any static host works: GitHub Pages, Vercel, Netlify, Cloudflare Pages.
- The person may not be a developer. Explain step by step how to upload the file and get its address.

## Rules

1. **It must be allowed inside another page.** Do not block framing with an `X-Frame-Options` header or `Content-Security-Policy: frame-ancestors`. Default settings of static hosts are usually fine.
2. **It must work on a small surface.** The person decides the card size. Make it usable at 280px wide and 200px tall, responsive to 100% of the width and height, with no horizontal scrolling. An outer padding of 12–16px works well.
3. **Support both light and dark.** Follow the `mode` value in the address (`light` or `dark`) when present, otherwise follow `prefers-color-scheme`.
4. **It must work without signing in.** Cookies and storage can be blocked or partitioned for a page inside a card, so a signed-in state does not last.
5. **Never put a secret key in the page.** Anyone can read the page's code.
6. **Storage may fail, and the tool must still work.** You may use `localStorage`, but wrap it in `try/catch` and run without saving when it is blocked. Data saved inside the card can be separate from what the same page saves when opened directly in a tab, and it is not part of Myzard's backup.

## Values Myzard passes in the address

When the person writes placeholders in the card's address, Myzard fills them in before opening the page.

```
https://my-tool.example/?lang={lang}&mode={mode}
→ https://my-tool.example/?lang=en&mode=dark
```

| Placeholder | Value | Meaning |
|---|---|---|
| `{lang}` | `ko` or `en` | Myzard's interface language |
| `{mode}` | `light` or `dark` | Myzard's light or dark mode |

- The page must also work without them (when opened directly). Use defaults.
- When the person changes the theme, the page is opened again with the new value.
- These two are all that is passed. No user name, no identifier and none of the person's Myzard data.

```js
const params = new URLSearchParams(location.search);
const lang = params.get('lang') === 'ko' ? 'ko' : 'en';
const mode = params.get('mode') || (matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
document.documentElement.lang = lang;
document.documentElement.dataset.mode = mode; // switch colors in CSS with [data-mode="dark"]
```

## Leaving an event in the inbox (optional)

When something happens that the person should not miss, the page can leave one event in Myzard's inbox. The tab holding that card then shows a count and a notification appears on screen.

```js
function notifyMyzard(title, message, level, key) {
  if (window.parent === window) return; // opened directly, outside Myzard
  window.parent.postMessage({ myzard: 1, type: 'event', title, message, level, key }, '*');
}

notifyMyzard('Low stock', 'Only 3 of A-102 left', 'warn', 'stock:A-102');
```

| Field | Required | Rule |
|---|---|---|
| `myzard` | yes | the number `1` |
| `type` | yes | `'event'` |
| `title` | yes | up to 80 characters; what happened, in one line |
| `message` | no | up to 300 characters |
| `level` | no | `'info'` (default) or `'warn'` |
| `key` | no | up to 64 characters; a name for the same occurrence. The same `key` is kept only once per minute |

- **The person must turn it on.** Nothing happens while "Receive events from this site" in the card's settings is off, which is the default. If your tool sends events, tell the person to turn that setting on.
- **It is one way.** Myzard sends nothing back. You cannot tell whether it arrived, so show the same information inside the page too.
- **Text only.** HTML and links are shown as plain text.
- **There are limits.** One event per 10 seconds and 20 per hour for each card; anything beyond is dropped.
- **Only while the card is on screen.** When the new tab is closed, the page is not running. While the new tab is hidden behind another tab, events are still delivered, and if the person has turned on Myzard's desktop notifications, a notification appears too.
- **Timers run late in a hidden tab.** Browsers slow `setInterval` and `setTimeout` in hidden tabs to once per second, then once per minute after a while, and pause `requestAnimationFrame`. A tool that measures time must **store the end time and compare it with `Date.now()`** instead of subtracting a little on every tick. Check once more on `visibilitychange` so it catches up as soon as the tab is shown again. Even so, an event sent while hidden can be up to about a minute late.
- **Use it sparingly.** Not for the result of a button the person just pressed ("Saved"). Only for things they need to learn later: something that happened while they were away, a value that crossed a threshold.

## What does not work inside a card

| Does not work | Do this instead |
|---|---|
| `alert`, `confirm`, `prompt` (they do nothing) | Draw your own message and confirm buttons in the page |
| File downloads | Show the result on the page so the person can select and copy it |
| Writing to the clipboard (may be blocked) | If it fails, show the text so it can be selected |
| Sending the whole tab to another address | Open links in a new tab with `target="_blank"` |
| Asking for notification, camera, microphone or location permission | Do not use them. Use the inbox event above to notify |
| Fullscreen, autoplaying sound | Do not use them |
| Reading Myzard's data or touching other cards | Not possible. Let the person type the values the tool needs |
| Screens that need signing in | Build a tool that needs no sign-in |

- To load data from another server, that server must allow calls from a browser (CORS).
- If you reload data on a timer, do not go below 30 seconds. Reloading the whole page is what the card's "Auto reload" setting is for.

## What to tell the person when you are done

1. How to upload the file and get an `https` address
2. How to add it in Myzard: Add app at the top right → "Website" → paste the address. Tell them to end the address with `?lang={lang}&mode={mode}`.
3. If the tool sends events: turn on "Receive events from this site" in the card's settings
4. If the card looks blank: check whether the host blocks the page from being shown inside another page

## Check before you hand it over

- [ ] It opens from a single file with no build step
- [ ] It is usable at 280px wide with no horizontal scrolling
- [ ] It reads well with both `?mode=dark` and `?mode=light`
- [ ] It works without `lang` and `mode`
- [ ] It does not use `alert`, `confirm`, downloads or permission requests
- [ ] It runs without errors when storage is blocked
- [ ] It contains no secret key
- [ ] Events are sent only when truly needed, and the same information is shown in the page
