stikfix 1.2.0

package/dist/host/src/server.js

@@ -0,0 +1,451 @@
+/**
+ * HTTP server factory for stikfix-host.
+ * D-05/HOST-10: CORS echo-Origin + Access-Control-Allow-Private-Network on every response
+ * D-06/HOST-04: GET /status no-token, no secrets
+ * D-05/HOST-05: POST /annotation token-gated via checkToken
+ * D-04/HOST-11: readBody 12 MB cap -> 413; JSON.parse -> 400
+ * D-03/HOST-06: withSerialLock(getNextSerial + writeNote) for atomic serial assignment
+ * Pitfall 6: setCorsHeaders called at top of handler — before any response write
+ */
+import * as http from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { join, basename } from 'node:path';
+import { VERSION, ensureNotesDir } from './config.js';
+import { checkToken, readBody, isInsideDir } from './security.js';
+import { withSerialLock, getNextSerial } from './serial.js';
+import { writeNote } from './write-note.js';
+import { listAnnotations, editNote, deleteNote } from './read-note.js';
+import { validateChosenFolder } from './validate-folder.js';
+// ---------------------------------------------------------------------------
+// Per-request notes-dir resolution (D-04 — targetDir support)
+// ---------------------------------------------------------------------------
+/**
+ * Marker error mapped to HTTP 400 by every handler. Thrown by resolveNotesDir
+ * when a supplied targetDir fails validation — so an invalid/system targetDir
+ * NEVER results in a write outside the validated folder (T-09-14b).
+ */
+class InvalidTargetDirError extends Error {
+    statusCode = 400;
+    constructor() {
+        super('Invalid target folder');
+        this.name = 'InvalidTargetDirError';
+    }
+}
+/**
+ * Resolve the notes directory for a single request (D-04).
+ *
+ * Security (T-09-14b): every targetDir is RE-VALIDATED here, server-side, on
+ * EVERY request via the shared validateChosenFolder (absolute + exists +
+ * isDirectory + system-dir deny-list). A valid targetDir confines the write to
+ * <validated>/notes (created on demand). This extends the Phase 8 "confined
+ * writes" invariant from a single --root to any user-chosen, validated folder.
+ *
+ * Back-compat: when targetDir is absent/empty, returns cfg.notesDir UNCHANGED —
+ * the existing --root flow is byte-for-byte identical to today (no regression).
+ *
+ * @throws InvalidTargetDirError (→ HTTP 400) when a non-empty targetDir is invalid.
+ */
+function resolveNotesDir(cfg, targetDir) {
+    if (typeof targetDir === 'string' && targetDir.length > 0) {
+        const valid = validateChosenFolder(targetDir);
+        if (!valid)
+            throw new InvalidTargetDirError();
+        const dir = join(valid, 'notes');
+        ensureNotesDir(dir);
+        return dir;
+    }
+    // No targetDir → identical behavior to today (back-compat / --root default).
+    return cfg.notesDir;
+}
+// ---------------------------------------------------------------------------
+// CORS helpers (Pattern 4)
+// ---------------------------------------------------------------------------
+/**
+ * Set base CORS headers on every response — echoes the request Origin.
+ * Must be called FIRST in every route handler, before any writeHead/end (Pitfall 6).
+ */
+function setCorsHeaders(req, res) {
+    const origin = req.headers.origin ?? '*';
+    res.setHeader('Access-Control-Allow-Origin', origin);
+    res.setHeader('Access-Control-Allow-Private-Network', 'true');
+}
+/**
+ * Add OPTIONS preflight-specific headers (called after setCorsHeaders for OPTIONS requests).
+ */
+function setPreflightHeaders(req, res) {
+    setCorsHeaders(req, res);
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type, X-Stikfix-Token');
+    res.setHeader('Access-Control-Max-Age', '86400');
+}
+// ---------------------------------------------------------------------------
+// Route handlers
+// ---------------------------------------------------------------------------
+function handleStatus(req, res, cfg) {
+    setCorsHeaders(req, res);
+    const body = JSON.stringify({
+        app: 'stikfix',
+        version: VERSION,
+        name: cfg.name,
+        root: cfg.root,
+        notesDir: cfg.notesDir,
+        origins: cfg.origins,
+    });
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(body);
+}
+function handleOptions(req, res) {
+    setPreflightHeaders(req, res);
+    res.writeHead(204);
+    res.end();
+}
+async function handleAnnotation(req, res, cfg) {
+    // 1. CORS on every response path (Pitfall 6)
+    setCorsHeaders(req, res);
+    // 2. Token auth (HOST-05)
+    if (!checkToken(req, cfg.token)) {
+        res.writeHead(401, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: 'unauthorized' }));
+        return;
+    }
+    // 3. Read body with size cap (HOST-11)
+    let raw;
+    try {
+        raw = await readBody(req);
+    }
+    catch (e) {
+        const err = e;
+        const status = err.statusCode === 413 ? 413 : 400;
+        res.writeHead(status, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: err.message ?? 'read error' }));
+        return;
+    }
+    // 4. Parse JSON (D-04)
+    let payload;
+    try {
+        payload = JSON.parse(raw);
+    }
+    catch {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: 'invalid JSON' }));
+        return;
+    }
+    // 4b. WR-02: Runtime payload shape guard before reaching the disk-write path.
+    // buildFrontmatter/buildNoteBody dereference page.url, viewport.width, etc.
+    // unconditionally — a missing field causes a TypeError (500). Validate first.
+    if ((payload.mode !== 'free' && payload.mode !== 'element') ||
+        typeof payload.comment !== 'string' ||
+        !payload.page || typeof payload.page.url !== 'string' || typeof payload.page.title !== 'string' ||
+        !payload.viewport ||
+        typeof payload.viewport.width !== 'number' ||
+        typeof payload.viewport.height !== 'number' ||
+        typeof payload.viewport.devicePixelRatio !== 'number') {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: 'invalid payload' }));
+        return;
+    }
+    // 5. Resolve the per-request notes dir (D-04). An invalid/system targetDir
+    //    throws InvalidTargetDirError → 400 BEFORE any serial is burned or file
+    //    is written. Absent targetDir → cfg.notesDir (back-compat, no regression).
+    let notesDir;
+    try {
+        notesDir = resolveNotesDir(cfg, payload.targetDir);
+    }
+    catch (e) {
+        const err = e;
+        const status = err.statusCode === 400 ? 400 : 500;
+        res.writeHead(status, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: err.message ?? 'invalid target folder' }));
+        return;
+    }
+    // 6. Write under serial lock (D-03 / Pitfall 3).
+    //    Writes are confined to <notesDir> (= cfg.notesDir OR <validated targetDir>/notes).
+    //    targetDir is NOT persisted into the note frontmatter (routing-only field).
+    try {
+        const { file, serial } = await withSerialLock(async () => {
+            const serialNum = getNextSerial(notesDir);
+            return writeNote(notesDir, payload, serialNum);
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true, file, serial }));
+    }
+    catch (e) {
+        // CR-02: propagate statusCode from write-phase errors (e.g. bad screenshot → 400)
+        const err = e;
+        const status = (typeof err.statusCode === 'number' && err.statusCode >= 400 && err.statusCode < 600)
+            ? err.statusCode
+            : 500;
+        res.writeHead(status, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: err.message ?? 'internal error' }));
+    }
+}
+// ---------------------------------------------------------------------------
+// Phase 6 handlers: GET /annotations, PUT /annotation/<serial>, DELETE /annotation/<serial>
+// HOST-14/15/16
+// ---------------------------------------------------------------------------
+/**
+ * GET /annotations?url=<page-url>
+ * Returns all notes whose URL path matches the given page URL (D-02).
+ * Token-gated (T-06-04). CORS headers first (Pitfall 6).
+ */
+async function handleListAnnotations(req, res, cfg) {
+    setCorsHeaders(req, res);
+    if (!checkToken(req, cfg.token)) {
+        res.writeHead(401, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: 'unauthorized' }));
+        return;
+    }
+    try {
+        // Parse ?url= and ?targetDir= query parameters (path already stripped of query)
+        const params = new URL(req.url ?? '/', 'http://x').searchParams;
+        const pageUrl = params.get('url') ?? '';
+        // D-04: re-validate targetDir per request; absent → cfg.notesDir (back-compat)
+        const notesDir = resolveNotesDir(cfg, params.get('targetDir') ?? undefined);
+        // ?done=1 → include archived (*.read.md / status:read) notes (panel-only opt-in)
+        const includeDone = params.get('done') === '1';
+        // ?scope=all → project-wide listing (notes from every page, not just pageUrl)
+        const pins = params.get('scope') === 'all'
+            ? listAnnotations(notesDir, pageUrl, { allUrls: true, includeDone })
+            : listAnnotations(notesDir, pageUrl, { includeDone });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true, pins }));
+    }
+    catch (e) {
+        const err = e;
+        const status = (typeof err.statusCode === 'number' && err.statusCode >= 400 && err.statusCode < 600)
+            ? err.statusCode : 500;
+        res.writeHead(status, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: err.message ?? 'internal error' }));
+    }
+}
+/**
+ * PUT /annotation/<serial>
+ * Overwrites the note body in place; preserves frontmatter + screenshots; re-marks status:unread.
+ * Reads body via existing readBody (12 MB cap → 413, HOST-11 reuse).
+ * Token-gated (T-06-01). path-confined via editNote (T-06-02).
+ */
+async function handleEditAnnotation(req, res, cfg, serial) {
+    setCorsHeaders(req, res);
+    if (!checkToken(req, cfg.token)) {
+        res.writeHead(401, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: 'unauthorized' }));
+        return;
+    }
+    // Read body with 12 MB cap (HOST-11 invariant reuse, T-06-03)
+    let raw;
+    try {
+        raw = await readBody(req);
+    }
+    catch (e) {
+        const err = e;
+        const status = err.statusCode === 413 ? 413 : 400;
+        res.writeHead(status, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: err.message ?? 'read error' }));
+        return;
+    }
+    try {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ ok: false, error: 'invalid JSON' }));
+            return;
+        }
+        const comment = parsed.comment ?? '';
+        // D-04: re-validate targetDir per request; absent → cfg.notesDir (back-compat)
+        const targetDir = new URL(req.url ?? '/', 'http://x').searchParams.get('targetDir') ?? undefined;
+        const notesDir = resolveNotesDir(cfg, targetDir);
+        await editNote(notesDir, serial, comment);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true }));
+    }
+    catch (e) {
+        const err = e;
+        const status = (typeof err.statusCode === 'number' && err.statusCode >= 400 && err.statusCode < 600)
+            ? err.statusCode : 500;
+        res.writeHead(status, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: err.message ?? 'internal error' }));
+    }
+}
+/**
+ * DELETE /annotation/<serial>
+ * Removes the .md file and its +N.png screenshots (D-05/D-06).
+ * Token-gated (T-06-01). path-confined via deleteNote (T-06-02).
+ */
+async function handleDeleteAnnotation(req, res, cfg, serial) {
+    setCorsHeaders(req, res);
+    if (!checkToken(req, cfg.token)) {
+        res.writeHead(401, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: 'unauthorized' }));
+        return;
+    }
+    try {
+        // D-04: re-validate targetDir per request; absent → cfg.notesDir (back-compat)
+        const targetDir = new URL(req.url ?? '/', 'http://x').searchParams.get('targetDir') ?? undefined;
+        const notesDir = resolveNotesDir(cfg, targetDir);
+        await deleteNote(notesDir, serial);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true }));
+    }
+    catch (e) {
+        const err = e;
+        const status = (typeof err.statusCode === 'number' && err.statusCode >= 400 && err.statusCode < 600)
+            ? err.statusCode : 500;
+        res.writeHead(status, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: err.message ?? 'internal error' }));
+    }
+}
+/**
+ * GET /screenshot?serial=<serial>&file=<basename.png>
+ * Serves a screenshot PNG file from notesDir as image/png bytes.
+ *
+ * Security model:
+ *  - Token-gated via checkToken (same as all other read verbs) — prevents
+ *    info-disclosure from unauthenticated callers (T-06-04 class).
+ *  - Path-traversal guard (T-06-02 class): `file` param must be a plain
+ *    basename (no `/`, `\`, or `..`), MUST start with `<serial>` (ties the
+ *    file to the note being requested), MUST end with `.png`.
+ *    The resolved absolute path is then verified via isInsideDir before read.
+ *  - No directory listing: only a single named file is ever returned.
+ *  - SW is the sole HTTP client — this endpoint is not called from page context.
+ */
+async function handleGetScreenshot(req, res, cfg) {
+    // CORS first (Pitfall 6)
+    setCorsHeaders(req, res);
+    // Token gate (T-06-04)
+    if (!checkToken(req, cfg.token)) {
+        res.writeHead(401, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: 'unauthorized' }));
+        return;
+    }
+    const params = new URL(req.url ?? '/', 'http://x').searchParams;
+    const serial = params.get('serial') ?? '';
+    const file = params.get('file') ?? '';
+    // Basename guard: reject any path separator or traversal component (T-06-02)
+    if (!serial ||
+        !file ||
+        file.includes('/') ||
+        file.includes('\\') ||
+        file.includes('..') ||
+        !file.startsWith(serial) || // ties file to the specific note serial
+        !file.endsWith('.png')) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: 'invalid file parameter' }));
+        return;
+    }
+    // D-04: re-validate targetDir per request; absent → cfg.notesDir (back-compat).
+    // An invalid/system targetDir → 400 (no file served outside the validated dir).
+    let notesDir;
+    try {
+        notesDir = resolveNotesDir(cfg, params.get('targetDir') ?? undefined);
+    }
+    catch (e) {
+        const err = e;
+        const status = err.statusCode === 400 ? 400 : 500;
+        res.writeHead(status, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: err.message ?? 'invalid target folder' }));
+        return;
+    }
+    // Reconstruct absolute path and verify confinement against the RESOLVED dir (T-06-02)
+    const resolved = join(notesDir, basename(file));
+    if (!isInsideDir(notesDir, resolved)) {
+        res.writeHead(403, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: 'forbidden' }));
+        return;
+    }
+    let bytes;
+    try {
+        bytes = await readFile(resolved);
+    }
+    catch {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: 'not found' }));
+        return;
+    }
+    res.writeHead(200, { 'Content-Type': 'image/png', 'Content-Length': String(bytes.length) });
+    res.end(bytes);
+}
+// ---------------------------------------------------------------------------
+// Server factory (D-01: createHostServer — does NOT call listen)
+// ---------------------------------------------------------------------------
+/**
+ * Create a configured http.Server with /status, OPTIONS, POST /annotation routing.
+ * Does NOT call server.listen — index.ts owns port binding (Pattern 1).
+ */
+export function createHostServer(cfg) {
+    const server = http.createServer((req, res) => {
+        const method = req.method ?? 'GET';
+        // WR-01: match on the path only — strip query string so /status?x=1 still routes correctly
+        const path = (req.url ?? '/').split('?', 1)[0];
+        if (method === 'OPTIONS') {
+            handleOptions(req, res);
+            return;
+        }
+        if (method === 'GET' && path === '/status') {
+            handleStatus(req, res, cfg);
+            return;
+        }
+        if (method === 'POST' && path === '/annotation') {
+            handleAnnotation(req, res, cfg).catch((e) => {
+                // Last-resort: if handler itself threw unexpectedly and response not started
+                if (!res.headersSent) {
+                    setCorsHeaders(req, res);
+                    res.writeHead(500, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, error: String(e) }));
+                }
+            });
+            return;
+        }
+        // Phase 6 routes: GET /annotations, PUT/DELETE /annotation/<serial>
+        if (method === 'GET' && path === '/annotations') {
+            handleListAnnotations(req, res, cfg).catch((e) => {
+                if (!res.headersSent) {
+                    setCorsHeaders(req, res);
+                    res.writeHead(500, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, error: String(e) }));
+                }
+            });
+            return;
+        }
+        if (method === 'PUT' && path.startsWith('/annotation/')) {
+            const serial = path.slice('/annotation/'.length);
+            handleEditAnnotation(req, res, cfg, serial).catch((e) => {
+                if (!res.headersSent) {
+                    setCorsHeaders(req, res);
+                    res.writeHead(500, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, error: String(e) }));
+                }
+            });
+            return;
+        }
+        if (method === 'DELETE' && path.startsWith('/annotation/')) {
+            const serial = path.slice('/annotation/'.length);
+            handleDeleteAnnotation(req, res, cfg, serial).catch((e) => {
+                if (!res.headersSent) {
+                    setCorsHeaders(req, res);
+                    res.writeHead(500, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, error: String(e) }));
+                }
+            });
+            return;
+        }
+        // GET /screenshot?serial=&file= — token-gated PNG file serve (FIX-1 UAT)
+        if (method === 'GET' && path === '/screenshot') {
+            handleGetScreenshot(req, res, cfg).catch((e) => {
+                if (!res.headersSent) {
+                    setCorsHeaders(req, res);
+                    res.writeHead(500, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, error: String(e) }));
+                }
+            });
+            return;
+        }
+        // 404 for all other routes (CORS headers still required — Pitfall 6)
+        setCorsHeaders(req, res);
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: 'not found' }));
+    });
+    return server;
+}

package/dist/host/src/types.js

@@ -0,0 +1,5 @@
+/**
+ * Shared TypeScript interfaces for stikfix-host.
+ * Matches PRD §9.1 (annotation payload) and the resolved Config shape.
+ */
+export {};

package/dist/host/src/validate-folder.js

@@ -0,0 +1,68 @@
+/**
+ * Shared folder-picker / target-folder validation (T-09-14 / T-09-14b).
+ *
+ * Single source of truth used by BOTH:
+ *  - the native host (native-host.ts) when validating a freshly-picked folder, and
+ *  - the HTTP server (server.ts) when re-validating an optional per-request
+ *    targetDir before confining a note write to <targetDir>/notes.
+ *
+ * Node builtins only — no Chrome/WXT imports.
+ */
+import { existsSync, statSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+/**
+ * Sensitive system directories that must NEVER become a note-write root.
+ * Compared against a resolved, normalized chosen path (case-insensitive on
+ * win32). If the chosen folder equals one of these roots, the pick is rejected.
+ */
+const SYSTEM_DIRS_NIX = ['/', '/System', '/usr', '/etc'];
+const SYSTEM_DIRS_WIN = ['C:\\Windows', 'C:\\Program Files'];
+/**
+ * Validate a folder before it becomes a note root (T-09-14 / T-09-14b).
+ *
+ * IMPORTANT — why isInsideDir does NOT apply here:
+ * The chosen folder is a *brand-new* note root selected by the user, NOT a
+ * child of any pre-existing root. The `isInsideDir(root, target)` confinement
+ * guard asserts that `target` lives inside an already-established `root`; there
+ * is no such pre-existing root at folder-pick time. Do not "fix" this by adding
+ * an isInsideDir call against the wrong base — that would reject every valid
+ * pick. Instead we validate the path defensively on its own terms:
+ *   (1) absolute, (2) exists, (3) is a directory, (4) not a sensitive system dir.
+ *
+ * Server-side reuse (D-04): the server re-runs this on EVERY request that
+ * carries a targetDir, then confines the write to <returned>/notes. An invalid
+ * or system targetDir returns null → the server maps that to HTTP 400 and
+ * writes nothing.
+ *
+ * @returns the validated absolute directory, or null if any check fails.
+ */
+export function validateChosenFolder(folder, plat = process.platform) {
+    // User cancelled / dialog unavailable / empty target — no folder chosen.
+    if (folder === null || typeof folder !== 'string' || folder.length === 0) {
+        return null;
+    }
+    // (1) Must be absolute.
+    if (!isAbsolute(folder))
+        return null;
+    // (2) Must exist + (3) must be a directory.
+    try {
+        if (!existsSync(folder))
+            return null;
+        if (!statSync(folder).isDirectory())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    // (4) Reject sensitive system directories. Normalize via resolve() and, on
+    // win32, compare case-insensitively (the filesystem is case-insensitive).
+    const normalized = resolve(folder);
+    const denyList = plat === 'win32' ? SYSTEM_DIRS_WIN : SYSTEM_DIRS_NIX;
+    const cmp = plat === 'win32' ? normalized.toLowerCase() : normalized;
+    for (const sysDir of denyList) {
+        const sysCmp = plat === 'win32' ? resolve(sysDir).toLowerCase() : resolve(sysDir);
+        if (cmp === sysCmp)
+            return null;
+    }
+    return normalized;
+}

package/dist/host/src/write-note.js

@@ -0,0 +1,158 @@
+/**
+ * Note file writer for stikfix-host.
+ * D-09/HOST-07: writes <serial>-<YYYYMMDD-HHmmss>.md with YAML frontmatter
+ * D-09/HOST-08: decodes PNG data-URLs to <base>+<N>.png next to the .md
+ * D-11: PRD §9.2 note format — frontmatter + comment + element context + screenshots
+ */
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { stringify as yamlStringify } from 'yaml';
+const PNG_PREFIX = 'data:image/png;base64,';
+// ---------------------------------------------------------------------------
+// Public helpers (exported for unit tests)
+// ---------------------------------------------------------------------------
+/**
+ * Format local time as YYYYMMDD-HHmmss (Pattern 10).
+ * 15 characters including the dash.
+ */
+export function localTimestamp() {
+    const d = new Date();
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-` +
+        `${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+}
+// 8-byte PNG file signature (ISO 15948 §12.1)
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+/**
+ * Validate the data:image/png;base64, prefix, decode to a Buffer, and assert
+ * the 8-byte PNG magic signature (WR-04). Throws {statusCode:400} on any failure
+ * (wrong prefix, zero-length buffer, bad magic bytes).
+ */
+export function decodePngDataUrl(dataUrl) {
+    if (!dataUrl.startsWith(PNG_PREFIX)) {
+        throw Object.assign(new Error('Invalid screenshot mime: expected data:image/png;base64,'), { statusCode: 400 });
+    }
+    const buf = Buffer.from(dataUrl.slice(PNG_PREFIX.length), 'base64');
+    // WR-04: reject zero-length buffers and non-PNG magic bytes
+    if (buf.length < PNG_SIGNATURE.length) {
+        throw Object.assign(new Error('Invalid screenshot: decoded buffer is too small to be a PNG'), { statusCode: 400 });
+    }
+    if (!buf.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE)) {
+        throw Object.assign(new Error('Invalid screenshot: PNG magic bytes not found'), { statusCode: 400 });
+    }
+    return buf;
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Build the YAML frontmatter block per PRD §9.2 (Pattern 8).
+ * selector + react_component ONLY for element mode (D-11).
+ * IN-01: `base` parameter removed (was unused).
+ */
+export function buildFrontmatter(payload, serial, screenshotRelPaths) {
+    const { mode, page, viewport, element } = payload;
+    const fm = {
+        id: serial,
+        created: new Date().toISOString(),
+        mode,
+        url: page.url,
+        title: page.title,
+        viewport: {
+            width: viewport.width,
+            height: viewport.height,
+            dpr: viewport.devicePixelRatio,
+        },
+    };
+    if (mode === 'element' && element) {
+        if (element.selector)
+            fm['selector'] = element.selector;
+        if (element.reactComponent)
+            fm['react_component'] = element.reactComponent;
+        // D-03: persist page-absolute rect for orphaned pin fallback (PIN-03)
+        if (element.rect)
+            fm['rect'] = element.rect;
+    }
+    // D-03: persist free-note viewport coords for pin floating position (PIN-02)
+    // CANONICAL KEY: note_position — matches listAnnotations read key (D-03)
+    if (mode === 'free' && payload.notePosition) {
+        fm['note_position'] = payload.notePosition;
+    }
+    fm['screenshots'] = screenshotRelPaths;
+    fm['status'] = 'unread';
+    return '---\n' + yamlStringify(fm) + '---\n';
+}
+/**
+ * Build the Markdown body per PRD §9.2 RESEARCH "Note Body Building" example.
+ * Free notes: comment only + optional Screenshots section.
+ * Element notes: comment + ## Element context + computed styles table + outerHTML + Screenshots.
+ */
+export function buildNoteBody(base, payload) {
+    const { comment, element, screenshots } = payload;
+    const screenshotBasenames = (screenshots ?? []).map((_, i) => `${base}+${i + 1}.png`);
+    let body = `${comment ?? ''}\n`;
+    if (element) {
+        body += `\n## Element context\n\n`;
+        body += `- **Selector:** \`${element.selector}\`\n`;
+        if (element.reactComponent)
+            body += `- **React component:** \`${element.reactComponent}\`\n`;
+        body += `- **Tag / role:** \`${element.tag}\` / \`${element.role ?? element.tag}\``;
+        if (element.ariaLabel)
+            body += `  ·  **aria-label:** ${element.ariaLabel}`;
+        body += '\n';
+        if (element.text)
+            body += `- **Text:** ${element.text}\n`;
+        const r = element.rect;
+        if (r)
+            body += `- **Rect:** x=${r.x} y=${r.y} w=${r.width} h=${r.height}\n`;
+        if (element.computedStyles && Object.keys(element.computedStyles).length > 0) {
+            body += `\n### Computed styles (curated)\n| prop | value |\n|------|-------|\n`;
+            for (const [k, v] of Object.entries(element.computedStyles)) {
+                body += `| ${k} | ${v} |\n`;
+            }
+        }
+        if (element.outerHTML) {
+            body += `\n### outerHTML (truncated)\n\`\`\`html\n${element.outerHTML}\n\`\`\`\n`;
+        }
+    }
+    if (screenshotBasenames.length > 0) {
+        body += `\n### Screenshots\n`;
+        screenshotBasenames.forEach((p, i) => {
+            const kind = payload.screenshots?.[i]?.kind ?? `+${i + 1}`;
+            body += `![${kind}](${p})\n`;
+        });
+    }
+    return body;
+}
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+/**
+ * Write a note to `notesDir` using the provided serial (caller holds the lock).
+ * Returns { file, serial } where file is the absolute .md path.
+ *
+ * The caller (server.ts) must call this inside withSerialLock so that
+ * getNextSerial → writeNote is atomic (Pitfall 3 / D-03).
+ */
+export async function writeNote(notesDir, payload, serial) {
+    const ts = localTimestamp();
+    const padded = String(serial).padStart(4, '0');
+    const base = `${padded}-${ts}`;
+    const mdPath = join(notesDir, `${base}.md`);
+    // CR-02: Decode/validate ALL screenshots into buffers BEFORE touching disk.
+    // A bad dataUrl throws {statusCode:400} here — before any file is written —
+    // so there is no partial on-disk state (no orphaned .md, no burned serial).
+    const pngBuffers = (payload.screenshots ?? []).map(s => decodePngDataUrl(s.dataUrl));
+    // Collect relative screenshot filenames for frontmatter
+    const screenshotRelPaths = pngBuffers.map((_, i) => `${base}+${i + 1}.png`);
+    // Build and write the .md file
+    const frontmatter = buildFrontmatter(payload, serial, screenshotRelPaths);
+    const body = buildNoteBody(base, payload);
+    await writeFile(mdPath, frontmatter + body, 'utf8');
+    // Write each decoded PNG buffer next to the .md
+    for (let i = 0; i < pngBuffers.length; i++) {
+        const pngPath = join(notesDir, `${base}+${i + 1}.png`);
+        await writeFile(pngPath, pngBuffers[i]);
+    }
+    return { file: mdPath, serial: padded };
+}