@restregular/dsh-notepad 0.1.0 → 0.3.0

package/index.js

@@ -3,19 +3,27 @@
  *
  * Stores one plain-text note per workspace in `<workspace>/.dsh/notepad.json`
  * and exposes it to the same-origin browser overlay through the loopback route
- * `/dsh-notepad/api/note`.
+ * `/dsh-notepad/api/note`. Pasted images are written to the plugin-owned
+ * directory `<workspace>/.dsh/notepad/images/` through `/dsh-notepad/api/image`.
  *
  * Security:
  *   - only loopback requests with a same-origin (or absent) Origin are served;
  *   - the resolved root must be a registered workspace or the exact cwd of the
  *     requesting session;
- *   - the file path itself is fixed (`.dsh/notepad.json`), so the route cannot
- *     be used to read or write arbitrary workspace files.
+ *   - the file paths themselves are fixed (`.dsh/notepad.json` and the image
+ *     directory), so the route cannot be used to read or write arbitrary
+ *     workspace files. Image uploads must be a supported raster format whose
+ *     bytes match the declared MIME type.
  *
  * @module dsh-notepad
  */
 
 import path from 'node:path';
+import {
+  IMAGE_TYPES,
+  MAX_IMAGE_BYTES,
+  saveClipboardImage,
+} from './lib/image-store.js';
 import {
   DEFAULT_MAX_BYTES,
   NOTE_VERSION,
@@ -28,11 +36,14 @@ import {
 const ROUTE = '/dsh-notepad/api';
 
 /** Plugin version mirrored in package.json. */
-const VERSION = '0.1.0';
+const VERSION = '0.3.0';
 
-/** Request body cap. */
+/** Request body cap for note writes. */
 const BODY_LIMIT = 1024 * 1024;
 
+/** Request body cap for base64 image uploads (decoded cap + base64 overhead). */
+const IMAGE_BODY_LIMIT = Math.ceil((MAX_IMAGE_BYTES * 4) / 3) + 64 * 1024;
+
 // ---------------------------------------------------------------------------
 // HTTP helpers
 // ---------------------------------------------------------------------------
@@ -56,16 +67,22 @@ function readJsonBody(req, limit = BODY_LIMIT) {
   return new Promise((resolve, reject) => {
     const chunks = [];
     let total = 0;
+    let tooLarge = false;
     req.on('data', (chunk) => {
+      if (tooLarge) return;
       total += chunk.length;
       if (total > limit) {
+        tooLarge = true;
+        chunks.length = 0;
         reject(new NoteStoreError('too-large', 'Request body is too large.'));
-        req.destroy();
+        // Drain the rest so the 413 response can still be delivered.
+        req.resume();
         return;
       }
       chunks.push(chunk);
     });
     req.on('end', () => {
+      if (tooLarge) return;
       try {
         const text = Buffer.concat(chunks).toString('utf8');
         const value = text === '' ? {} : JSON.parse(text);
@@ -172,7 +189,10 @@ export async function handleRequest(ctx, req, res) {
     await dispatchRequest(ctx, req, res);
   } catch (error) {
     if (error instanceof NoteStoreError) {
-      const status = error.code === 'unknown-workspace' || error.code === 'bad-root' ? 403 : 400;
+      let status = 400;
+      if (error.code === 'unknown-workspace' || error.code === 'bad-root') status = 403;
+      else if (error.code === 'too-large') status = 413;
+      else if (error.code === 'unsupported-type') status = 415;
       sendJson(res, { ok: false, code: error.code, error: error.message }, status);
       return;
     }
@@ -199,7 +219,29 @@ async function dispatchRequest(ctx, req, res) {
   }
   const action = url.pathname.slice(ROUTE.length).replace(/^\/+|\/+$/gu, '');
   if (action === 'ping') {
-    sendJson(res, { ok: true, plugin: 'dsh-notepad', version: VERSION, noteVersion: NOTE_VERSION });
+    sendJson(res, {
+      ok: true,
+      plugin: 'dsh-notepad',
+      version: VERSION,
+      noteVersion: NOTE_VERSION,
+      imageTypes: Object.keys(IMAGE_TYPES),
+      maxImageBytes: MAX_IMAGE_BYTES,
+    });
+    return;
+  }
+  if (action === 'image') {
+    if (req.method !== 'POST') {
+      sendJson(res, { ok: false, code: 'method', error: 'Use POST.' }, 405);
+      return;
+    }
+    const body = await readJsonBody(req, IMAGE_BODY_LIMIT);
+    const root = await resolveRequestRoot(ctx, body);
+    const image = await saveClipboardImage(root, {
+      name: body.name,
+      mime: body.mime,
+      data: body.data,
+    });
+    sendJson(res, { ok: true, root, ...image });
     return;
   }
   if (action !== 'note') {
@@ -218,7 +260,9 @@ async function dispatchRequest(ctx, req, res) {
   if (req.method === 'PUT') {
     const body = await readJsonBody(req);
     const root = await resolveRequestRoot(ctx, body);
-    const note = await writeNote(root, body.text, { maxBytes: DEFAULT_MAX_BYTES });
+    const note = await writeNote(root, Array.isArray(body.segments) ? body.segments : body.text, {
+      maxBytes: DEFAULT_MAX_BYTES,
+    });
     sendJson(res, { ok: true, root, ...note });
     return;
   }

package/lib/image-store.js

@@ -0,0 +1,176 @@
+/**
+ * dsh-notepad — workspace image storage.
+ *
+ * Images pasted into the notepad have no host path in the browser, so their
+ * base64 payload is written under the plugin directory:
+ *
+ *   <workspace>/.dsh/notepad/images/<unique>-<name>.<ext>
+ *
+ * The returned path is workspace-relative, which keeps the note file portable
+ * inside one workspace. Selected images keep their original path and never
+ * reach this module unless the browser could not expose that path.
+ *
+ * Only PNG, JPEG, WebP and GIF are accepted, and the payload must actually
+ * start with the matching file signature: this route is loopback-only, but it
+ * must not be usable as an arbitrary file writer.
+ *
+ * @module dsh-notepad/lib/image-store
+ */
+
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { NoteStoreError } from './note-store.js';
+
+/** Plugin-owned directory under the workspace root (POSIX spelling). */
+export const IMAGE_DIR = '.dsh/notepad/images';
+
+/** Maximum decoded image size accepted from the browser. */
+export const MAX_IMAGE_BYTES = 20 * 1024 * 1024;
+
+/** Maximum display name kept for one image. */
+export const MAX_IMAGE_NAME_CHARS = 160;
+
+/** MIME type to canonical file extension. */
+export const IMAGE_TYPES = Object.freeze({
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/webp': 'webp',
+  'image/gif': 'gif',
+});
+
+/**
+ * Validate a declared MIME type.
+ * @param {unknown} mime
+ * @returns {string | null} canonical MIME type
+ */
+export function canonicalImageType(mime) {
+  if (typeof mime !== 'string') return null;
+  const value = mime.trim().toLowerCase();
+  return Object.prototype.hasOwnProperty.call(IMAGE_TYPES, value) ? value : null;
+}
+
+/**
+ * Read a supported image signature.
+ * @param {Buffer} bytes
+ * @returns {string | null} canonical MIME type
+ */
+export function sniffImageType(bytes) {
+  if (bytes.length >= 8
+    && bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47
+    && bytes[4] === 0x0d && bytes[5] === 0x0a && bytes[6] === 0x1a && bytes[7] === 0x0a) {
+    return 'image/png';
+  }
+  if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
+    return 'image/jpeg';
+  }
+  if (bytes.length >= 6) {
+    const gif = bytes.subarray(0, 6).toString('latin1');
+    if (gif === 'GIF87a' || gif === 'GIF89a') return 'image/gif';
+  }
+  if (bytes.length >= 12
+    && bytes.subarray(0, 4).toString('latin1') === 'RIFF'
+    && bytes.subarray(8, 12).toString('latin1') === 'WEBP') {
+    return 'image/webp';
+  }
+  return null;
+}
+
+/**
+ * Strictly decode canonical base64 (no whitespace, no data-URL prefix).
+ * @param {unknown} value
+ * @returns {Buffer}
+ */
+export function decodeBase64(value) {
+  if (typeof value !== 'string' || value === '') {
+    throw new NoteStoreError('bad-input', 'Image data is required.');
+  }
+  if (value.length % 4 !== 0 || !/^[A-Za-z0-9+/]+={0,2}$/u.test(value)) {
+    throw new NoteStoreError('bad-input', 'Image data is not canonical base64.');
+  }
+  const bytes = Buffer.from(value, 'base64');
+  // Re-encoding catches non-canonical trailing bits that Buffer accepts.
+  if (bytes.toString('base64') !== value) {
+    throw new NoteStoreError('bad-input', 'Image data is not canonical base64.');
+  }
+  return bytes;
+}
+
+/**
+ * Build a safe file stem from a display name.
+ * @param {unknown} name
+ * @returns {string}
+ */
+function fileStem(name) {
+  const raw = typeof name === 'string' ? name : '';
+  let stem = raw
+    .replace(/[\\/:*?"<>|\u0000-\u001f\u007f]+/gu, '-')
+    .replace(/^[.\s]+|[.\s]+$/gu, '')
+    .replace(/\.(?:png|jpe?g|webp|gif)$/iu, '')
+    .slice(0, 80);
+  if (stem === '') stem = 'image';
+  stem = stem.replace(/-+/gu, '-').replace(/^-|-$/gu, '');
+  return stem === '' ? 'image' : stem;
+}
+
+/**
+ * Keep a human-readable name; fall back to the stored file name.
+ * @param {unknown} name
+ * @returns {string}
+ */
+function displayName(name) {
+  const raw = typeof name === 'string' ? name : '';
+  const cleaned = raw
+    .replace(/[\\/\u0000-\u001f\u007f]+/gu, ' ')
+    .replace(/\s+/gu, ' ')
+    .trim()
+    .slice(0, MAX_IMAGE_NAME_CHARS);
+  return cleaned === '' ? 'image' : cleaned;
+}
+
+/**
+ * Save one pasted image under the plugin directory.
+ *
+ * @param {string} root workspace root
+ * @param {{ name?: unknown, mime?: unknown, data?: unknown }} input
+ * @returns {Promise<{path: string, name: string, mime: string, size: number}>}
+ */
+export async function saveClipboardImage(root, input) {
+  const declared = canonicalImageType(input?.mime);
+  if (declared === null) {
+    throw new NoteStoreError('unsupported-type', 'Only PNG, JPEG, WebP and GIF images are supported.');
+  }
+  const bytes = decodeBase64(input?.data);
+  if (bytes.byteLength === 0) {
+    throw new NoteStoreError('bad-input', 'Image data is empty.');
+  }
+  if (bytes.byteLength > MAX_IMAGE_BYTES) {
+    throw new NoteStoreError('too-large', `Image is too large (limit ${MAX_IMAGE_BYTES} bytes).`);
+  }
+  const sniffed = sniffImageType(bytes);
+  if (sniffed === null || sniffed !== declared) {
+    throw new NoteStoreError('unsupported-type', 'The image bytes do not match the declared type.');
+  }
+  const extension = IMAGE_TYPES[declared];
+  const name = displayName(input?.name);
+  const stem = fileStem(name);
+  const dir = path.join(root, ...IMAGE_DIR.split('/'));
+  await fs.mkdir(dir, { recursive: true });
+  const fileName = `${Date.now().toString(36)}-${randomBytes(4).toString('hex')}-${stem}.${extension}`;
+  const file = path.join(dir, fileName);
+  try {
+    await fs.writeFile(file, bytes, { flag: 'wx' });
+  } catch (error) {
+    if (error?.code === 'EEXIST') {
+      throw new NoteStoreError('internal', 'Could not allocate a unique image file name.');
+    }
+    throw error;
+  }
+  return {
+    path: `${IMAGE_DIR}/${fileName}`,
+    name,
+    mime: declared,
+    size: bytes.byteLength,
+  };
+}

package/lib/note-store.js

@@ -1,11 +1,14 @@
 /**
  * dsh-notepad — workspace note storage.
  *
- * One plain-text note per workspace, kept at `<workspace>/.dsh/notepad.json`.
- * The JSON envelope lets the file carry its own `updatedAt` while still
- * degrading gracefully: if the file is not JSON (a user or another tool
- * edited it by hand), the raw bytes are returned as the note text instead of
- * losing the content.
+ * One note per workspace, kept at `<workspace>/.dsh/notepad.json`. A note is an
+ * ordered list of text segments; each segment may be archived after it was
+ * sent, and only archived segments can be deleted by the client.
+ *
+ * Version 2 stores the segment list under `segments` and repeats the merged
+ * body under `text` so the file stays human readable and older builds can
+ * still read the content. Version 1 files (a single `text`) and hand-edited
+ * plain-text files are migrated on read as one segment.
  *
  * @module dsh-notepad/lib/note-store
  */
@@ -20,11 +23,26 @@ export const NOTE_DIR = '.dsh';
 /** File name inside {@link NOTE_DIR}. */
 export const NOTE_FILE = 'notepad.json';
 
-/** Default maximum note size (UTF-8 bytes). */
+/** Default maximum note file size (UTF-8 bytes). */
 export const DEFAULT_MAX_BYTES = 512 * 1024;
 
+/** Maximum number of segments accepted from the client. */
+export const MAX_SEGMENTS = 200;
+
+/** Maximum characters in one segment. */
+export const MAX_SEGMENT_CHARS = 160_000;
+
 /** Storage envelope version. */
-export const NOTE_VERSION = 1;
+export const NOTE_VERSION = 3;
+
+/** Maximum image references accepted on one segment. */
+export const MAX_IMAGES_PER_SEGMENT = 20;
+
+/** Maximum characters kept for one image path. */
+export const MAX_IMAGE_PATH_CHARS = 1024;
+
+/** Maximum characters kept for one image display name. */
+export const MAX_IMAGE_NAME_CHARS = 160;
 
 /** A note-store failure with a stable machine-readable code. */
 export class NoteStoreError extends Error {
@@ -47,25 +65,257 @@ export function notePath(root) {
   return path.join(root, NOTE_DIR, NOTE_FILE);
 }
 
+/**
+ * Final non-empty segment of a path, in either separator spelling.
+ * @param {string} value
+ */
+function baseNameOf(value) {
+  const trimmed = String(value ?? '').replace(/[/\\]+$/u, '');
+  const separator = Math.max(trimmed.lastIndexOf('/'), trimmed.lastIndexOf('\\'));
+  return trimmed.slice(separator + 1);
+}
+
+/**
+ * Normalize one stored image reference. Reading and writing share this shape;
+ * reading drops invalid entries, writing rejects them.
+ * @param {unknown} value
+ * @returns {{path: string, name: string} | null}
+ */
+function readImage(value) {
+  if (typeof value === 'string') value = { path: value };
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return null;
+  if (typeof value.path !== 'string') return null;
+  const filePath = value.path.trim().replace(/\\/gu, '/');
+  if (filePath === '' || filePath.length > MAX_IMAGE_PATH_CHARS) return null;
+  const name = typeof value.name === 'string' && value.name.trim() !== ''
+    ? value.name.trim().replace(/\s+/gu, ' ').slice(0, MAX_IMAGE_NAME_CHARS)
+    : baseNameOf(filePath);
+  return { path: filePath, name: name === '' ? 'image' : name };
+}
+
+/**
+ * Normalize every surviving image reference for one segment.
+ * @param {unknown} value
+ * @returns {Array<{path: string, name: string}>}
+ */
+function readImages(value) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  for (const item of value) {
+    if (out.length >= MAX_IMAGES_PER_SEGMENT) break;
+    const image = readImage(item);
+    if (image !== null) out.push(image);
+  }
+  return out;
+}
+
+/**
+ * Strict per-segment image normalization for writes.
+ * @param {unknown} value
+ * @param {number} index
+ * @returns {Array<{path: string, name: string}>}
+ */
+function normalizeWriteImages(value, index) {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) {
+    throw new NoteStoreError('bad-input', `Segment ${index + 1} images is not an array.`);
+  }
+  if (value.length > MAX_IMAGES_PER_SEGMENT) {
+    throw new NoteStoreError(
+      'too-many',
+      `Segment ${index + 1} has too many images (${value.length}; limit ${MAX_IMAGES_PER_SEGMENT}).`,
+    );
+  }
+  return value.map((item, imageIndex) => {
+    const image = readImage(item);
+    if (image === null) {
+      throw new NoteStoreError('bad-input', `Segment ${index + 1} image ${imageIndex + 1} is invalid.`);
+    }
+    return image;
+  });
+}
+
+/**
+ * Render one image as Markdown for the note body and composer transfers.
+ * Paths are URL-escaped so the DSH Markdown renderer can resolve them.
+ * @param {{path?: string, name?: string}} image
+ * @returns {string}
+ */
+export function imageMarkdown(image) {
+  const file = typeof image?.path === 'string' ? image.path.replace(/\\/gu, '/') : '';
+  if (file === '') return '';
+  const label = (typeof image?.name === 'string' ? image.name : '')
+    .replace(/[\r\n]+/gu, ' ')
+    .replace(/[[\]]/gu, ' ')
+    .trim() || baseNameOf(file) || 'image';
+  let target;
+  try {
+    target = encodeURI(file);
+  } catch {
+    target = file;
+  }
+  target = target
+    .replace(/#/gu, '%23')
+    .replace(/\?/gu, '%3F')
+    .replace(/\(/gu, '%28')
+    .replace(/\)/gu, '%29');
+  return `![${label}](${target})`;
+}
+
+/**
+ * One segment rendered as text plus one Markdown line per image.
+ * @param {{text?: string, images?: Array<{path: string, name: string}>}} segment
+ */
+export function segmentBody(segment) {
+  const text = typeof segment?.text === 'string' ? segment.text : '';
+  const images = Array.isArray(segment?.images) ? segment.images : [];
+  const parts = [];
+  if (text.trim() !== '') parts.push(text);
+  for (const image of images) {
+    const markdown = imageMarkdown(image);
+    if (markdown !== '') parts.push(markdown);
+  }
+  return parts.join('\n');
+}
+
+/**
+ * Normalize one segment read from disk. Reading is forgiving: a malformed
+ * entry is skipped instead of making the whole note unreadable.
+ * @param {unknown} value
+ * @param {number} index
+ * @param {Set<string>} seen
+ * @returns {{id: string, text: string, images: Array<{path: string, name: string}>, archived: boolean, archivedAt: string | null} | null}
+ */
+function readSegment(value, index, seen) {
+  if (typeof value === 'string') value = { text: value };
+  if (value === null || typeof value !== 'object') return null;
+  const images = readImages(value.images);
+  if (typeof value.text !== 'string' && images.length === 0) return null;
+  const text = typeof value.text === 'string' ? value.text : '';
+  let id = typeof value.id === 'string' && value.id !== '' ? value.id.slice(0, 128) : `seg-${index + 1}`;
+  let suffix = 1;
+  while (seen.has(id)) {
+    id = `${id}-${suffix}`;
+    suffix += 1;
+  }
+  seen.add(id);
+  const archived = value.archived === true;
+  const archivedAt = archived && typeof value.archivedAt === 'string' && value.archivedAt !== ''
+    ? value.archivedAt
+    : null;
+  return { id, text, images, archived, archivedAt };
+}
+
+/**
+ * Normalize a segment list for a write. Unlike {@link readSegment}, malformed
+ * entries are an input error here: the route must not silently drop content.
+ *
+ * Accepts the modern `segments` array, a single legacy text string, or
+ * `{ text }`.
+ *
+ * @param {unknown} input
+ * @returns {Array<{id: string, text: string, archived: boolean, archivedAt: string | null}>}
+ */
+export function normalizeSegments(input) {
+  if (typeof input === 'string') {
+    if (input === '') return [];
+    return [{ id: 'seg-1', text: input, images: [], archived: false, archivedAt: null }];
+  }
+  if (input !== null && typeof input === 'object' && !Array.isArray(input)) {
+    if (Array.isArray(input.segments)) return normalizeSegments(input.segments);
+    if (typeof input.text === 'string') return normalizeSegments(input.text);
+    throw new NoteStoreError('bad-input', 'Note must be a string or a segments array.');
+  }
+  if (!Array.isArray(input)) {
+    throw new NoteStoreError('bad-input', 'Note must be a string or a segments array.');
+  }
+  if (input.length > MAX_SEGMENTS) {
+    throw new NoteStoreError('too-many', `Too many segments (${input.length}; limit ${MAX_SEGMENTS}).`);
+  }
+  const seen = new Set();
+  return input.map((value, index) => {
+    const segment = normalizeWriteSegment(value, index, seen);
+    return segment;
+  });
+}
+
+/**
+ * Strict per-segment normalization for writes.
+ * @param {unknown} value
+ * @param {number} index
+ * @param {Set<string>} seen
+ */
+function normalizeWriteSegment(value, index, seen) {
+  if (typeof value === 'string') value = { text: value };
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new NoteStoreError('bad-input', `Segment ${index + 1} is not an object.`);
+  }
+  if (typeof value.text !== 'string') {
+    throw new NoteStoreError('bad-input', `Segment ${index + 1} has no text field.`);
+  }
+  if (value.text.length > MAX_SEGMENT_CHARS) {
+    throw new NoteStoreError(
+      'too-large',
+      `Segment ${index + 1} is too large (${value.text.length} characters; limit ${MAX_SEGMENT_CHARS}).`,
+    );
+  }
+  const images = normalizeWriteImages(value.images, index);
+  let id = typeof value.id === 'string' && value.id !== '' ? value.id.slice(0, 128) : `seg-${index + 1}`;
+  let suffix = 1;
+  while (seen.has(id)) {
+    id = `${id}-${suffix}`;
+    suffix += 1;
+  }
+  seen.add(id);
+  const archived = value.archived === true;
+  const archivedAt = archived && typeof value.archivedAt === 'string' && value.archivedAt !== ''
+    ? value.archivedAt
+    : null;
+  return { id, text: value.text, images, archived, archivedAt };
+}
+
+/**
+ * Merge segments into the plain body stored next to the list.
+ * @param {Array<{text: string, images?: Array<{path: string, name: string}>}>} segments
+ */
+export function mergeSegments(segments) {
+  return segments
+    .map((segment) => segmentBody(segment))
+    .filter((body) => body.trim() !== '')
+    .join('\n\n');
+}
+
 /**
  * Decode a stored note file.
  * @param {string} raw file contents
  * @param {number | undefined} mtimeMs
  */
 export function parseNote(raw, mtimeMs) {
-  let text = raw;
+  let segmentsInput;
   let updatedAt;
   try {
     const parsed = JSON.parse(raw);
-    if (parsed !== null && typeof parsed === 'object' && typeof parsed.text === 'string') {
-      text = parsed.text;
+    if (parsed !== null && typeof parsed === 'object') {
+      if (Array.isArray(parsed.segments)) segmentsInput = parsed.segments;
+      else if (typeof parsed.text === 'string') segmentsInput = parsed.text;
       if (typeof parsed.updatedAt === 'string') updatedAt = parsed.updatedAt;
     }
   } catch {
     /* Not our envelope: keep the raw text. */
   }
+  if (segmentsInput === undefined) segmentsInput = raw;
+  const seen = new Set();
+  const segments = [];
+  const values = typeof segmentsInput === 'string'
+    ? (segmentsInput === '' ? [] : [segmentsInput])
+    : Array.isArray(segmentsInput) ? segmentsInput : [];
+  for (const value of values) {
+    const segment = readSegment(value, segments.length, seen);
+    if (segment !== null) segments.push(segment);
+  }
   return {
-    text,
+    segments,
+    text: mergeSegments(segments),
     updatedAt: updatedAt ?? (typeof mtimeMs === 'number' ? new Date(mtimeMs).toISOString() : null),
     mtimeMs: typeof mtimeMs === 'number' ? mtimeMs : null,
     exists: true,
@@ -76,7 +326,7 @@ export function parseNote(raw, mtimeMs) {
 /**
  * Read one workspace note. A missing file is an empty note, not an error.
  * @param {string} root workspace root
- * @returns {Promise<{text: string, updatedAt: string | null, mtimeMs: number | null, exists: boolean, size: number}>}
+ * @returns {Promise<{segments: Array<{id: string, text: string, archived: boolean, archivedAt: string | null}>, text: string, updatedAt: string | null, mtimeMs: number | null, exists: boolean, size: number}>}
  */
 export async function readNote(root) {
   const file = notePath(root);
@@ -85,7 +335,7 @@ export async function readNote(root) {
     raw = await fs.readFile(file, 'utf8');
   } catch (error) {
     if (error?.code === 'ENOENT') {
-      return { text: '', updatedAt: null, mtimeMs: null, exists: false, size: 0 };
+      return { segments: [], text: '', updatedAt: null, mtimeMs: null, exists: false, size: 0 };
     }
     throw error;
   }
@@ -100,25 +350,37 @@ export async function readNote(root) {
 }
 
 /**
- * Replace one workspace note atomically.
+ * Replace one workspace note atomically. Accepts either a segment array or a
+ * legacy plain-text string.
  * @param {string} root workspace root
- * @param {string} text note body
+ * @param {unknown} note segments array or legacy text
  * @param {{ maxBytes?: number }} [options]
  */
-export async function writeNote(root, text, options = {}) {
-  if (typeof text !== 'string') {
-    throw new NoteStoreError('bad-input', 'Note text must be a string.');
-  }
+export async function writeNote(root, note, options = {}) {
+  const segments = normalizeSegments(note);
   const maxBytes = Number.isFinite(options.maxBytes) ? options.maxBytes : DEFAULT_MAX_BYTES;
-  const size = Buffer.byteLength(text, 'utf8');
+  const dir = path.join(root, NOTE_DIR);
+  const file = path.join(dir, NOTE_FILE);
+  const updatedAt = new Date().toISOString();
+  const payload = `${JSON.stringify({
+    version: NOTE_VERSION,
+    segments: segments.map((segment) => ({
+      id: segment.id,
+      text: segment.text,
+      ...(segment.images.length > 0
+        ? { images: segment.images.map((image) => ({ path: image.path, name: image.name })) }
+        : {}),
+      ...(segment.archived ? { archived: true } : {}),
+      ...(segment.archivedAt ? { archivedAt: segment.archivedAt } : {}),
+    })),
+    text: mergeSegments(segments),
+    updatedAt,
+  }, null, 2)}\n`;
+  const size = Buffer.byteLength(payload, 'utf8');
   if (size > maxBytes) {
     throw new NoteStoreError('too-large', `Note is too large (${size} bytes; limit ${maxBytes} bytes).`);
   }
-  const dir = path.join(root, NOTE_DIR);
-  const file = path.join(dir, NOTE_FILE);
   await fs.mkdir(dir, { recursive: true });
-  const updatedAt = new Date().toISOString();
-  const payload = `${JSON.stringify({ version: NOTE_VERSION, text, updatedAt }, null, 2)}\n`;
   const tmp = path.join(dir, `.${NOTE_FILE}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`);
   await fs.writeFile(tmp, payload, 'utf8');
   try {
@@ -129,7 +391,8 @@ export async function writeNote(root, text, options = {}) {
   }
   const stat = await fs.stat(file);
   return {
-    text,
+    segments,
+    text: mergeSegments(segments),
     updatedAt,
     mtimeMs: stat.mtimeMs,
     exists: true,