Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 7 additions & 3 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ same domain as the backend (see `fmc_pocketbase/README.md`).
App: the store at the root, three shelves under one "Store" tab — watchfaces (`/`, with
`?mine` for the signed-in user's own shelf; `/my`
redirects there; `/market/[id]` — a face's showcase page), apps (`/apps`, `/apps/[id]` —
`.wp2app` packages published from cmf-tech-community/apps, built with the wp2-apps SDK) and firmware (`/firmware`,
`.wp2app` packages published from fmctools/apps, built with the wp2-apps SDK) and firmware (`/firmware`,
`/firmware/[id]` — OTA images), plus a Community section (`/community`, links out; the old
`/?community` redirects there); creator profiles (`/user/[id]`), watchface editor (`/editor`,
with a BLE connection to the CMF Watch Pro 2) and auth (`/login`, `/register`).
Expand Down Expand Up @@ -205,9 +205,9 @@ and `frames` sections; `PropsPanel.svelte` is the container and owns the shared
desktop, the swipeable sheet on the phone —
no portal/floating-ui deps. Button & co. don't forward arbitrary attrs; for `title`
tooltips wrap in a `<span title>` (see `tool-slot` in editor.svelte).
- Icons are Material Symbols Rounded, the whole set from Google Fonts (`app.html`). `name` IS
- Icons are Material Symbols Rounded, the full font bundled in `static/fonts/material-symbols.woff2`. `name` IS
the ligature — `<Icon name="storefront" />`, any name from fonts.google.com/icons works with
no map to edit and no build step. A name the font doesn't know renders as its own word, so
no map to edit and no build step. Keep the font local and preserve the load guard and fixed icon slot; do not reintroduce the external Google Fonts icon stylesheet. A name the font doesn't know is invalid, so
`tests/ui-icon.browser.test.ts` measures every name the app spells.
- Phone first for the store: the watchface grid is two dials across on a phone
(`watchface-list`), a detail page is one column with a single ink button (the action that
Expand Down Expand Up @@ -261,3 +261,7 @@ and `frames` sections; `PropsPanel.svelte` is the container and owns the shared
- **English everywhere in the repo and around it**: code, identifiers, comments, docs,
commit messages, PR titles and descriptions, issue text, CI/workflow files. Chat with the
user can be in any language — anything that lands in git or on GitHub is English.

## Watch identity and preview overrides

`docs/watch-identity.md` records the Nothing X model/color formats and browser limitations. Keep factory identity separate from preview overrides. Unknown SKU values stay unknown, advertisement observation is optional and bounded, and recovery skips the extra PID query. The preview selectors must never feed firmware or package compatibility checks. No physical-device claim follows from fixture tests.
14 changes: 12 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# FMC Watchfaces Frontend
# FMC Frontend

Watchface editor + marketplace for the CMF Watch Pro 2 / Pro 3. SvelteKit (Svelte 5) SPA,
Watch faces, apps, firmware and browser tools for CMF watches. SvelteKit (Svelte 5) SPA,
static build (`@sveltejs/adapter-static`). Backend — [`fmc_pocketbase`](../fmc_pocketbase)
(PocketBase), must be running for auth/marketplace to work.

Expand Down Expand Up @@ -52,3 +52,13 @@ pnpm test # round-trip test of the .bin parser/compiler against watchfaces/fi

[AGPL-3.0](LICENSE). The bundled Geist fonts are under the SIL Open Font License —
see [`static/fonts/OFL.txt`](static/fonts/OFL.txt).

Material Symbols Rounded is bundled locally under the [Apache 2.0 license](static/fonts/LICENSE-Material-Symbols.txt). Icons do not require Google Fonts requests.

## Branding assets

The original community logo is `static/branding/fmc-community.svg`. Navigation preserves the full artwork, including “by COMMUNITY”. Transparent SVG favicons adapt to the system light/dark preference. A stable 96px PNG and ICO provide non-themed fallbacks, with a contrasting edge for light and dark host surfaces. Installed-app icons keep a solid background for platform masking.

Run `pnpm brand-assets` to regenerate the icons and `pnpm og-card` to regenerate the default share card. These scripts use Playwright Chromium; set `PLAYWRIGHT_CHANNEL=msedge` to use an installed Edge instead. Keep device-specific support descriptions on their relevant pages.

Keep `/favicon.png` stable for crawlers; do not rotate favicon URLs on every build. Browser and third-party caches refresh independently. Search results may take days to weeks to recrawl, and favicon changes are not guaranteed to appear immediately.
116 changes: 116 additions & 0 deletions docs/watch-identity.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,116 @@
# Watch model and color identification

CMF watches identify their product model and factory color in Bluetooth
advertisements. Nothing X combines these values into a catalog key to select the
corresponding product artwork. A factory color identifies a product variant; it
does not describe replacement straps or bezels.

## Product identifiers

A product ID contains four bytes. Its catalog representation is eight hexadecimal
digits in the same byte order, with leading zeroes preserved.

| Product ID | Watch |
| ---------- | ----------- |
| `82D5BB72` | Watch Pro |
| `34F72851` | Watch Pro 2 |
| `335BBD62` | Watch 3 Pro |

The factory color is a separate byte, represented by two hexadecimal digits.
The catalog key is the product ID followed by the color code. For example,
`335BBD62` and `23` form `335BBD6223`, an orange Watch 3 Pro entry.
The catalog calls this combined key `fastPairId`; it is a product/SKU identifier,
not a unique identifier for an individual watch.

The [artwork reference](https://cmf.arnv.dev/reference/watch-artwork/) lists the known color codes.
Several codes can share the same image. Their individual regional or retail
meanings have not been established.

## Advertisement normalization

The field offsets below refer to the byte sequence reconstructed by Nothing X's
watch parser, not the complete Bluetooth advertising packet.

Android and Web Bluetooth expose manufacturer-specific data with the two-byte
company identifier separated from its payload. In Nothing X 3.10.0:

- Company ID `0x0CCB` (3275 decimal) uses the supplied payload unchanged.
- For other company IDs passed to the watch parser, `2C BE` is prepended to the
supplied payload before the fields are read.

This second rule describes the parser's normalization branch; it does not mean
that arbitrary manufacturers identify CMF watches. The parser also checks the
watch marker and validates the embedded address through its vendor-address check.

## Advertisement layouts

Nothing X uses a legacy layout for normalized data of at least 18 bytes, and a
compact layout for 14-17 bytes. Shorter data does not contain the complete fields.

| Field | Legacy layout | Compact layout |
| -------------------------- | -------------------- | --------------- |
| Embedded Bluetooth address | Bytes 0-5 | Bytes 0-5 |
| Watch marker | Bytes 6-11: `JX-IWD` | Bytes 6-7: `JX` |
| Product ID | Bytes 12-15 | Bytes 8-11 |
| Factory color code | Byte 16 | Byte 12 |
| State | Byte 17 | Byte 13 |

The address bytes are formatted in their existing order. The product and color
bytes are converted to uppercase hexadecimal without reversing them.
Nothing X exposes them as `PRODUCT_ID`, `COLOR_ID` and the combined
`PRODUCT_COLOR_ID` / `FAST_PAIRED_ID`.

The parser sets `IS_PAIRED` for state bytes `00`, `01` or `02`. This is the app's
interpretation of an advertising state; it does not establish an authenticated
GATT session. Advertised identity is not proof of device ownership.

## QR and shell identifiers

The stock onboarding QR uses product field `P` and color field `C`. The QR color
is decimal, whereas the catalog uses hexadecimal. For example, decimal `35`
corresponds to catalog color `23`. Comparing the strings without this conversion
can select the wrong SKU.

Watch Pro 2 and Watch 3 Pro firmware analysis identifies the `APP_PID` property and
the read-only `AT GETPID` query. Its response format is:

```text
GETPID:34F72851,OK
```

This query reports the product ID only. It does not report the factory color.
Shell-service availability and command support depend on the firmware; the query
is separate from the encrypted control-channel authentication protocol. A shell
reply may arrive over several Bluetooth notifications.

## Browser access

Web Bluetooth distinguishes access to GATT services from access to advertisements.
A successful connection alone does not provide the manufacturer-data color byte.
Where supported, `BluetoothDevice.watchAdvertisements()` delivers advertisements
for an authorized device. API support, permissions and the watch's advertising
state determine whether those bytes are available.

A missing advertisement or unknown color code leaves the factory color unknown.
An advertised device name can help identify a model, but does not establish a
factory color. A user-selected frame is a display preference, not detected hardware
metadata or evidence that a firmware package is compatible.

See the [Web Bluetooth specification](https://bluetooth.spec.whatwg.org/) and
[BluetoothDevice API reference](https://developer.mozilla.org/en-US/docs/Web/API/BluetoothDevice)
for the browser interfaces and availability.

## Evidence and scope

The advertisement layouts and state handling come from Nothing X 3.10.0's
`com.nothing.link.bluetooth.sdk.scan.parser.NothingWatchParser`, including
`getTotalManufacture()` and `parser()`. `NtBlePlugin` consumes the resulting
`PRODUCT_ID` and `COLOR_ID`; Flutter's
`BluetoothHelper.getDeviceInfoByBluetoothDevice` resolves them against the
`DeviceInfoTable` SKU catalog.

The QR and `APP_PID` findings come from stock Watch Pro 2 and Watch 3 Pro firmware
analysis. The artwork associations come from the Nothing X product catalog and
its recorded image URLs. These findings establish the documented formats and
known catalog mappings, not universal advertisement or shell-command availability
across every firmware and browser.
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@
"dev": "vite dev --host",
"build": "vite build && node scripts/seo.ts",
"og-card": "node scripts/og-card.ts",
"brand-assets": "node scripts/brand-assets.ts",
"preview": "vite preview",
"prepare": "svelte-kit sync || echo ''",
"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
Expand Down
67 changes: 67 additions & 0 deletions scripts/brand-assets.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
import { readFile, writeFile } from "node:fs/promises";
import { chromium } from "playwright";
const browser = await chromium.launch({ channel: process.env.PLAYWRIGHT_CHANNEL });
const page = await browser.newPage();
const mark = await readFile("static/branding/fmc-community.svg", "utf8");

await writeFile("static/icons/icon.svg", mark);
// Keep every part of the supplied mark; remove only its tile and tighten the surrounding canvas.
const transparentMark = mark.replace(/<rect\b[^>]*\/>/, "");
const freeMark = transparentMark.replace('viewBox="0 0 512 512"', 'viewBox="44 44 424 424"');

for (const [name, foreground] of [
["light", "#010101"],
["dark", "#FAFAFA"],
["neutral", "#202020"],
]) {
if (name !== "neutral")
await writeFile(
`static/branding/fmc-community-${name}.svg`,
transparentMark.replaceAll('fill="#FAFAFA"', 'fill="' + foreground + '"'),
);
let variant = freeMark.replaceAll('fill="#FAFAFA"', 'fill="' + foreground + '"');
// The non-themed fallback needs an edge that survives both light and dark host surfaces.
if (name === "neutral")
variant = variant.replace(
/(<svg\b[^>]*>)([\s\S]*)(<\/svg>)/,
'$1<g stroke="#FAFAFA" stroke-width="4">$2</g><g>$2</g>$3',
);
await writeFile(`static/icons/favicon-${name}.svg`, variant);
}

// Run from the repository root: node scripts/brand-assets.ts.
for (const [name, size, pad] of [
["icon-192.png", 192, 0],
["icon-512.png", 512, 0],
["icon-maskable-512.png", 512, 32],
["apple-touch-icon.png", 180, 0],
["favicon-32.png", 32, 0],
["favicon-96.png", 96, 0],
] as const) {
await page.setViewportSize({ width: size, height: size });
const artwork = name.startsWith("favicon-")
? await readFile("static/icons/favicon-neutral.svg", "utf8")
: mark;

await page.setContent(
`<style>*{box-sizing:border-box}body{margin:0;background:${pad ? "#010101" : "transparent"};padding:${pad}px}svg{display:block;width:100%;height:100%}</style>${artwork}`,
);
if (name === "favicon-32.png") {
const png = await page.screenshot({ omitBackground: true });
const header = Buffer.alloc(22);

header.writeUInt16LE(1, 2);
header.writeUInt16LE(1, 4);
header[6] = header[7] = 32;
header.writeUInt16LE(1, 10);
header.writeUInt16LE(32, 12);
header.writeUInt32LE(png.length, 14);
header.writeUInt32LE(22, 18);
await writeFile("static/favicon.ico", Buffer.concat([header, png]));
} else if (name === "favicon-96.png") {
await page.screenshot({ path: "static/favicon.png", omitBackground: true });
} else {
await page.screenshot({ path: `static/icons/${name}` });
}
}
await browser.close();
125 changes: 78 additions & 47 deletions scripts/og-card.ts
Original file line number Diff line number Diff line change
@@ -1,54 +1,85 @@
// Renders static/og-default.png — the 1200x630 card a link unfurls to when the page behind it
// isn't one watchface. Committed output; this only exists so it can be redrawn when the mark or
// the pitch changes: `pnpm run og-card`.
//
// The mark itself comes from static/icons/icon.svg, so the card can't drift from the app icon.
// Chromium is the one playwright already installs for the browser tests — no new dependency.
import { readFile, writeFile } from "node:fs/promises";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";
import { chromium } from "playwright";
import { DEVICE } from "../src/lib/shared/seo/copy.ts";

const STATIC = join(dirname(fileURLToPath(import.meta.url)), "..", "static");
const inline = async (path: string, mime: string) =>
`data:${mime};base64,${(await readFile(join(STATIC, path))).toString("base64")}`;
const source = (await readFile(join(STATIC, "branding/fmc-community.svg"), "utf8"))
.replace(/<rect\b[^>]*\/>/, "")
.replace(/\s(?:width|height)="512"/g, "");
const color = process.env.OG_WATCH_COLOR ?? "dark-grey";

// the dark-scheme pair from tokens.css, spelled out — a PNG can't read a custom property
const INK = "#131313";
const PAPER = "#f2f2f2";

const mark = await readFile(join(STATIC, "icons", "icon.svg"), "utf8");

const html = `<!doctype html>
<html><head><meta charset="utf-8">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Geist:wght@400..600&display=swap" rel="stylesheet">
<style>
* { box-sizing: border-box; margin: 0; }
html, body { width: 1200px; height: 630px; overflow: hidden; }
body {
background: ${INK}; color: ${PAPER};
font-family: Geist, system-ui, sans-serif;
display: flex; flex-direction: column; justify-content: center; gap: 36px; padding: 0 96px;
}
.mark { width: 124px; height: 124px; border-radius: 26px; overflow: hidden; }
.mark svg { display: block; width: 100%; height: 100%; }
/* both lines are sized to sit on one line at 1008px of usable width */
h1 { font-size: 46px; font-weight: 600; letter-spacing: -1px; }
p { font-size: 28px; font-weight: 400; color: oklch(from ${PAPER} l c h / 55%); }
</style></head>
<body>
<div class="mark">${mark}</div>
<h1>Watchfaces for the ${DEVICE}</h1>
<p>Browse, edit and install — straight from the browser, no phone app</p>
</body></html>`;

const browser = await chromium.launch();
const page = await browser.newPage({ viewport: { width: 1200, height: 630 } });

await page.setContent(html, { waitUntil: "load" });
await page.evaluate(() => document.fonts.ready);
const png = await page.screenshot({ type: "png" });

await browser.close();
await writeFile(join(STATIC, "og-default.png"), png);
console.log(`static/og-default.png — ${(png.length / 1024).toFixed(1)} kB`);
if (!["dark-grey", "orange", "green"].includes(color))
throw new Error("Unsupported OG watch color");
const output = process.env.OG_OUTPUT ?? join(STATIC, "og-default.png");
const browser = await chromium.launch({ channel: process.env.PLAYWRIGHT_CHANNEL });

try {
const page = await browser.newPage({
viewport: { width: 1200, height: 630 },
deviceScaleFactor: 1,
});

await page.setContent(source);
const bounds = await page.locator("svg").evaluate((svg) => {
const { x, y, width, height } = (svg as SVGSVGElement).getBBox();

return `${x - 2} ${y - 2} ${width + 4} ${height + 4}`;
});
const mark = source.replace(/viewBox="[^"]+"/, `viewBox="${bounds}"`);
const [font, watch] = await Promise.all([
inline("fonts/geist.woff2", "font/woff2"),
inline(`frames/watch-3-pro-${color}.webp`, "image/webp"),
]);

await page.setContent(
`<!doctype html><html lang="en"><head><meta charset="utf-8">
<style>
@font-face { font-family: Geist; src: url("${font}"); font-weight: 100 900; }
* { box-sizing: border-box; margin: 0; }
html, body { inline-size: 1200px; block-size: 630px; }
body { background: #000; color: #fafafa; font-family: Geist, sans-serif; }
main { position: relative; isolation: isolate; display: grid; grid-template-columns: 680px minmax(0, 1fr); block-size: 100%; padding-inline: 152px 72px; overflow: clip; }
.copy { position: relative; display: flex; flex-direction: column; justify-content: center; align-items: start; padding-block: 72px; z-index: 1; }
.mark { inline-size: 230px; }
.mark svg { display: block; inline-size: 100%; block-size: auto; }
h1 { margin-block-start: 44px; font-size: 60px; font-weight: 550; line-height: 1.12; letter-spacing: -2px; }
p { margin-block-start: 24px; color: #929292; font-size: 26px; line-height: 1.4; }
.art { position: absolute; inset: 0; z-index: 0; mask-image: linear-gradient(90deg, transparent 54%, #000 80%); }
.art img { display: block; position: absolute; inline-size: 1120px; block-size: 1120px; object-fit: contain; inset-inline-start: 565px; inset-block-start: -245px; opacity: .23; }
</style></head><body><main>
<section class="copy"><div class="mark">${mark}</div>
<h1>Watch faces.<br>Apps &amp; firmware.</h1>
<p>Explore, create and install.</p>
</section>
<div class="art" aria-hidden="true"><img src="${watch}" alt=""></div>
</main></body></html>`,
{ waitUntil: "load" },
);
await page.evaluate(async () => {
await document.fonts.ready;
await Promise.all([...document.images].map((image) => image.decode()));
});
await page.evaluate(
() =>
new Promise<void>((resolve) =>
requestAnimationFrame(() => requestAnimationFrame(() => resolve())),
),
);

const textFits = await page
.locator("h1")
.evaluate((element) => element.scrollWidth <= element.clientWidth);

if (!textFits) throw new Error("OG headline overflows its column");
const png = await page.screenshot({ type: "png" });

await writeFile(output, png);
console.log(
`static/og-default.png: 1200x630, ${(png.length / 1024).toFixed(1)} kB; local fonts and artwork only`,
);
} finally {
await browser.close();
}
3 changes: 1 addition & 2 deletions scripts/seo.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,6 @@ import { fileURLToPath } from "node:url";
import {
creatorDesc,
creatorTitle,
DEVICE,
faceDesc,
faceTitle,
siteDesc,
Expand All @@ -35,7 +34,7 @@ const SITE = (process.env.SITE_URL || "https://fmc.tools").replace(/\/$/, "");
const PB = (process.env.PB_URL || SITE).replace(/\/$/, "");

const DEFAULT_IMAGE = `${SITE}/og-default.png`;
const DEFAULT_ALT = `${SITE_NAME} — watchfaces for the ${DEVICE}`;
const DEFAULT_ALT = `${SITE_NAME} — watch faces, apps and firmware for CMF watches`;

// ---- the meta block ----

Expand Down
Loading
Loading