# Soft Hours Diary CDN — Complete AI Integration Context

This is the canonical machine-readable reference for developers and AI coding assistants integrating the Soft Hours Diary emoji and flag CDN. Read it before generating code. Follow exact path patterns, quality values and casing rules. Never invent endpoints.

## Canonical service details

- CDN base URL: https://softhoursdiary-emojis.pages.dev/
- Main brand site / CORS-approved website origin: https://softhoursdiary.pages.dev
- Public JavaScript UMD helper: https://softhoursdiary-emojis.pages.dev/soft-hours-diary.js
- ESM helper: https://softhoursdiary-emojis.pages.dev/soft-hours-diary.esm.mjs
- TypeScript declarations: https://softhoursdiary-emojis.pages.dev/index.d.ts
- API documentation home: https://softhoursdiary-emojis.pages.dev/api/
- Interactive playground: https://softhoursdiary-emojis.pages.dev/api/playground/
- Downloadable complete AI context: https://softhoursdiary-emojis.pages.dev/api/soft-hours-diary-ai-context.md

## What the service is

This is a public static image CDN, not a dynamic JSON REST API. It serves emoji and flag files from fixed paths. Ordinary img elements and CSS backgrounds need no API key, SDK token, authentication header or backend proxy. There is no dynamic search API in this service. A JavaScript helper builds and validates URLs synchronously; it does not request the file and does not guarantee that a filename exists.

## Asset families and exact URL patterns

### 1. Emoji

- type: `emoji` (alias `emojis`)
- quality: `svg` (default) or `png`
- SVG path: `/emojis/svg/{unicode}.svg`
- PNG path: `/emojis/72x72/{unicode}.png`
- ID format: lowercase hexadecimal Unicode code point(s). Multi-code-point sequences are joined with hyphens.
- Literal Unicode strings are accepted by the helper and normalised to lowercase hexadecimal code points.
- Example SVG: https://softhoursdiary-emojis.pages.dev/emojis/svg/1f632.svg
- Example PNG: https://softhoursdiary-emojis.pages.dev/emojis/72x72/1f632.png

### 2. Country / region flag SVG

- type: `flag`
- quality: `s`, `m`, `l` (default `m`)
- path: `/flag/{quality}/{CODE}.svg`
- ID casing: uppercase country or region code
- Example: https://softhoursdiary-emojis.pages.dev/flag/l/IN.svg

### 3. Flag icons

- type: `flags` (aliases `flag-icon`, `flagicon`)
- quality: `1x1` or `4x3` (default `4x3`)
- path: `/flags/{quality}/{code}.svg`
- ID casing: lowercase country or region code
- Example: https://softhoursdiary-emojis.pages.dev/flags/4x3/in.svg

## JavaScript helper

Version: 1.0.0

### Browser install

```html
<script defer src="https://softhoursdiary-emojis.pages.dev/soft-hours-diary.js"></script>
```

Global object: `window.SoftHoursDiary`.

### ESM install

Download `soft-hours-diary.js` and `soft-hours-diary.esm.mjs` into the project. Keep them next to each other because the ESM entry imports the UMD file using a relative import.

```js
import SoftHoursDiary, {
  emojiUrl, flagUrl, flagIconUrl
} from "./soft-hours-diary.esm.mjs";
```

Do not use an HTTP URL import in a Next.js Server Component. Download and import the ESM files locally, or load the UMD helper client-side using the framework's script loader.

### API signatures

- `getUrl({ type, quality, id, baseUrl? })` → absolute asset URL string
- `emojiUrl(id, { quality?, format?, baseUrl? }?)` → emoji URL (SVG default)
- `flagUrl(id, { quality?, baseUrl? }?)` → flag SVG URL (medium default)
- `flagIconUrl(id, { quality?, baseUrl? }?)` → flag icon URL (4x3 default)
- `createImage(options)` → HTMLImageElement (browser only)
- `mount(target, options)` → updates an existing img or appends an image to an element
- `scan(scope?)` → processes DOM nodes with data-shd-type and data-shd-id attributes, returning the count processed
- `createReactComponents(React)` → `{ Emoji, Flag, FlagIcon, Asset }` React component functions
- `registerElements()` → registers custom elements if not already registered

### Examples

```js
const SHD = window.SoftHoursDiary;

SHD.getUrl({ type: "emoji", quality: "svg", id: "1f632" });
// https://softhoursdiary-emojis.pages.dev/emojis/svg/1f632.svg

SHD.getUrl({ type: "flag", quality: "l", id: "IN" });
// https://softhoursdiary-emojis.pages.dev/flag/l/IN.svg

SHD.getUrl({ type: "flags", quality: "4x3", id: "IN" });
// https://softhoursdiary-emojis.pages.dev/flags/4x3/in.svg

SHD.emojiUrl("1f632", { quality: "png" });
SHD.flagUrl("IN", { quality: "s" });
SHD.flagIconUrl("IN", { quality: "1x1" });
```

## Browser custom elements

The browser helper registers these custom elements when supported:

```html
<shd-asset type="emoji" asset-id="1f632" quality="svg" alt="Surprised face"></shd-asset>
<shd-emoji asset-id="1f632" quality="svg" alt="Surprised face"></shd-emoji>
<shd-flag asset-id="IN" quality="l" alt="Flag of India"></shd-flag>
<shd-flag-icon asset-id="IN" quality="4x3" alt="India flag icon"></shd-flag-icon>
```

`shd-asset` takes a `type` attribute of `emoji`, `flag` or `flags`. Use `asset-id` for the CDN identifier, not the HTML `id` attribute. Supported attributes include type, asset-id, quality, alt, width, height, class, loading, decoding and base-url. The component renders an img inside a shadow root.

## React / Vite

```jsx
import React from "react";

const { Emoji, Flag, FlagIcon, Asset } =
  window.SoftHoursDiary.createReactComponents(React);

export function Reactions() {
  return (
    <div>
      <Emoji id="1f632" quality="svg" alt="Surprised face" width={36} height={36} />
      <Flag id="IN" quality="l" alt="Flag of India" width={48} height={32} />
      <FlagIcon id="IN" quality="4x3" alt="India flag" width={48} />
      <Asset type="emoji" id="1f632" quality="png" alt="Emoji PNG" />
    </div>
  );
}
```

The adapter renders ordinary img elements and accepts standard image attributes such as alt, width, height, loading, decoding and className. For SSR, do not access window on the server; use local ESM URL helpers.

## Next.js

Recommended: download both helper files to the project and import `emojiUrl` / `flagUrl` from the local ESM entry in Server Components. Render a normal img element if you do not need Next's image optimisation.

If using `next/image`, add this host to `images.remotePatterns`: `softhoursdiary-emojis.pages.dev` with protocol `https` and pathname `/**`.

For custom elements in a Client Component, load the UMD script with `next/script` and `strategy="afterInteractive"`. Do not HTTP-import the ESM URL into a Server Component.

## HTML and CSS

Direct image example:

```html
<img src="https://softhoursdiary-emojis.pages.dev/emojis/svg/1f632.svg"
  alt="Surprised face" width="36" height="36" loading="lazy" decoding="async">
```

Data attribute example:

```html
<img data-shd-type="emoji" data-shd-id="1f632"
  data-shd-quality="svg" alt="Surprised face">
<script>window.SoftHoursDiary.scan();</script>
```

CSS background example:

```css
.reaction {
  width: 32px;
  height: 32px;
  background: url("https://softhoursdiary-emojis.pages.dev/emojis/svg/1f632.svg") center / contain no-repeat;
}
```

## TypeScript

The repository includes `index.d.ts`. Copy it beside the local ESM files. Supported unions: EmojiQuality = `svg | png`; FlagQuality = `s | m | l`; FlagIconQuality = `1x1 | 4x3`. Runtime validation still applies, and a typed URL does not guarantee a file exists.

## CORS policy

The Cloudflare Pages `_headers` configuration sets `Access-Control-Allow-Origin: https://softhoursdiary.pages.dev` globally for static responses. Allowed methods are GET, HEAD and OPTIONS. Allowed request headers are Accept, Content-Type, Origin and Range. Other origins are not whitelisted. Normal img rendering does not need CORS-readable response access; JavaScript fetch() and canvas pixel access do.

The repository is a static Pages deployment. If Pages Functions are added, they must set the required CORS headers in their own responses; Pages `_headers` does not configure Function-generated responses.

## Crawler and indexing policy

`robots.txt` allows general search and named AI documentation crawlers to read `/api/` and asks them to skip `/emojis/`, `/flag/` and `/flags/`. The Pages `_headers` file additionally adds `X-Robots-Tag: noindex, nofollow, nosnippet` to raw asset directories. Documentation pages are indexable, carry canonical and structured metadata, and are included in the API docs sitemap.

Robots directives are advisory and are not authentication. Crawlers can ignore them; user-triggered fetchers may not apply them. The asset files remain public and direct HTTP requests remain possible. Strict blocking requires a WAF or application-layer control and careful testing to avoid breaking real image users.

## Performance and accessibility

- Add meaningful alt text to informative images; use empty alt text for decorative images.
- Specify width and height to reduce layout shift.
- Lazy-load below-the-fold images; the helper defaults to lazy loading and async decoding.
- Prefer direct img rendering over fetch() when the only requirement is to display an asset.
- Keep a text or native emoji fallback for important controls.

## Package publication status

Package metadata is prepared as `soft-hours-diary-cdn@1.0.0`, but npm publication is not complete. Do not claim that `npm install soft-hours-diary-cdn` works until the package is published. Until then, use the browser CDN script or local ESM files.

## Documentation index

- Overview: https://softhoursdiary-emojis.pages.dev/api/
- Quick start: https://softhoursdiary-emojis.pages.dev/api/getting-started/
- Installation: https://softhoursdiary-emojis.pages.dev/api/installation/
- JavaScript: https://softhoursdiary-emojis.pages.dev/api/javascript/
- React: https://softhoursdiary-emojis.pages.dev/api/react/
- Next.js: https://softhoursdiary-emojis.pages.dev/api/nextjs/
- HTML & CSS: https://softhoursdiary-emojis.pages.dev/api/html-css/
- TypeScript: https://softhoursdiary-emojis.pages.dev/api/typescript/
- Playground: https://softhoursdiary-emojis.pages.dev/api/playground/
- API reference: https://softhoursdiary-emojis.pages.dev/api/reference/
- Performance: https://softhoursdiary-emojis.pages.dev/api/performance/
- Troubleshooting: https://softhoursdiary-emojis.pages.dev/api/troubleshooting/
- CORS and crawlers: https://softhoursdiary-emojis.pages.dev/api/cors-and-crawlers/

## AI assistant response rules

When generating integration code, first use the user's known project stack. If it is unclear, ask which environment they use. Use only documented values and URL patterns. Never invent a REST endpoint. Never tell the user the npm package is published. Explain that helpers validate URL syntax but do not check file availability. Preserve image accessibility and image dimensions.