carouselbot 0.2.0 → 0.3.0

package/README.md

@@ -1,11 +1,14 @@
 # CarouselBot MCP
 
-Local-first MCP companion for the hosted [CarouselBot editor](https://carousel.bot). It exposes project, slide, text, image, layer, history, rendering, and export controls to any stdio MCP client while the editor remains in the browser.
+Local-first MCP companion for the hosted [CarouselBot editor](https://carousel.bot). It exposes project, folder, slide, text, image, layer, history, rendering, and export controls to any stdio MCP client while the editor remains in the browser.
 
 ```bash
 npx carouselbot@latest setup
 ```
 
+Setup pins that exact package version in the generated MCP configuration. Rerun
+the command when you intentionally want to update.
+
 For non-interactive agent setup, select the current client explicitly:
 
 ```bash
@@ -22,17 +25,33 @@ The same validated tool surface is available through the package CLI when a runn
 npx -y carouselbot@latest call get_design_guidance
 npx -y carouselbot@latest call list_editors
 npx -y carouselbot@latest call begin_edit_session --json '{"editorId":"EDITOR_ID","purpose":"Build my deck"}'
-npx -y carouselbot@latest call create_project --json '{"editSessionId":"SESSION_ID","name":"My presentation"}'
+npx -y carouselbot@latest call create_project --json '{"editSessionId":"SESSION_ID","name":"My presentation","folderPath":"/campaigns"}'
 ```
 
 Every MCP tool name and JSON argument shape works with `call`. The CLI-only `list_tools` helper lists names compactly or returns selected schemas. `render_slide` writes image output to a temporary `previewPath` instead of dumping base64 into the terminal.
 
+Folders use exact canonical slash paths such as `/campaigns` and are derived from project membership. Pass `folderPath` to `create_project` to create a project in a folder. Use `move_project` with another slash path to move it between folders, or with `folderPath: null` to move it back to the dashboard root. Embedded slashes are part of the virtual path and do not create a nested UI hierarchy. Because folders are implicit, moving the last project out removes the empty folder card automatically. `inspect_editor` returns each project's current folder path.
+
 Always use `list_editors` to check the browser connection. Do not open CarouselBot or click **Connect AI** through a sandboxed, remote, or agent-controlled browser: that is a different browser session and may not reach the local companion.
 
 Browser reconnection is automatic. Retry transient disconnects; use `restart` only for an explicit protocol mismatch or failed daemon health check. Hermes can refresh native tools with `/reload-mcp` and `/reload-skills`. Claude may need a new session to register a newly added server, but the CLI fallback works immediately.
 
 The companion binds only to `127.0.0.1`. There is no hosted relay: projects remain in browser IndexedDB and local images remain on the user's computer.
 
+## Installed fonts
+
+CarouselBot can use fonts installed on the same Mac as the companion. Open a text layer's font control once and choose **Allow local fonts**. The permission is stored in that browser; until it is granted, agent calls return `FONT_PERMISSION_REQUIRED`.
+
+Agents use project-scoped IDs rather than CSS family guesses:
+
+```text
+list_local_fonts({ query: "Didot" })
+import_font({ editSessionId, projectId, localFontId })
+add_text({ editSessionId, projectId, slideId, text, fontId })
+```
+
+`list_project_fonts` reports faces already embedded in a project. `add_text` and `update_text` accept the returned `fontId`, plus optional `fontWeight`, `fontStyle`, and variable-axis settings. The companion returns opaque local font IDs and never exposes font paths. A selected face is transferred over the authenticated loopback connection, persisted only in the browser's local IndexedDB project, and loaded before fitting or rendering. If the exact bytes are missing or invalid, rendering reports `FONT_UNAVAILABLE` instead of silently using a fallback.
+
 Any MCP client can launch it with:
 
 ```bash

package/guidance/design.md

@@ -20,6 +20,7 @@ Read this before creating or editing slides. Use it as a compact quality bar, th
 - Align related text layers consistently. Center is a safe default; use left alignment for editorial layouts.
 - Use rotation sparingly. Small intentional angles can add energy; arbitrary angles make carousels feel inconsistent.
 - Reuse a small palette and consistent type scale across the project.
+- For an installed Mac font, select an exact face with `list_local_fonts`, import its opaque ID with `import_font`, and apply only the returned project `fontId`. Reuse project faces through `list_project_fonts`; never guess family strings.
 
 ## Working method
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carouselbot",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Local-first MCP companion for the hosted CarouselBot editor",
   "type": "module",
   "license": "MIT",
@@ -28,6 +28,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/server": "2.0.0",
+    "fontkit": "^2.0.4",
     "zod": "^4.4.3"
   },
   "publishConfig": {

package/skill/carouselbot/SKILL.md

@@ -23,8 +23,8 @@ If the native MCP tools are not registered in the current session, do not stop o
 ```bash
 npx -y carouselbot@latest call get_design_guidance
 npx -y carouselbot@latest call list_editors
-npx -y carouselbot@latest call list_tools --json '{"names":["add_slide","add_text"]}'
-npx -y carouselbot@latest call create_project --json '{"name":"My presentation"}'
+npx -y carouselbot@latest call list_tools --json '{"names":["create_project","move_project","add_slide","add_text"]}'
+npx -y carouselbot@latest call create_project --json '{"name":"My presentation","folderPath":"/campaigns"}'
 ```
 
 Every tool accepts the same JSON arguments as MCP. Use `list_tools` without arguments for compact discovery or pass `{"names":[...]}` to retrieve selected schemas. Prefer `apply_operations` for batches. `render_slide` writes its returned image to a temporary local `previewPath`; inspect that file and remove the temporary directory after the review. Hermes can load the native tools in place with `/reload-mcp` and refresh this skill with `/reload-skills`.
@@ -46,6 +46,17 @@ With only one agent and one editor, the server can create an implicit session fo
 
 Inspect the assigned editor before editing and keep the returned IDs and revision. Work on the assigned project and slide. Pass `expectedRevision` for sensitive mutations. If `STALE_PROJECT` is returned, the browser has reloaded the canonical IndexedDB copy; inspect again and retry with current IDs. Prefer `apply_operations` for compact related changes while preserving logical order.
 
+When the user asks for a font installed on their Mac, use the deterministic two-ID flow:
+
+1. Call `list_local_fonts` with a family/style query and choose an exact face from its metadata. Never guess a CSS family or construct a `localFontId`.
+2. Call `import_font` with that opaque `localFontId`. Keep the returned project-scoped `fontId`.
+3. Pass the returned `fontId` to `add_text` or `update_text`. Import and application are separate calls for a newly selected face; do not invent a batch placeholder.
+4. Render and inspect the result. Use `list_project_fonts` to reuse faces already embedded in the project.
+
+If listing returns `FONT_PERMISSION_REQUIRED`, ask the user to open the real CarouselBot tab and choose **Allow local fonts** from the text font control, then retry. Do not bypass this with browser automation. Font paths and bytes are intentionally unavailable to agents. If rendering reports `FONT_UNAVAILABLE`, preserve the editable text, report the missing face, and ask the user to replace or re-import it rather than accepting fallback pixels.
+
+Dashboard folders are implicit and use exact canonical slash paths such as `/campaigns`. Set `folderPath` when calling `create_project` to create the project inside a folder. Call `move_project` with another slash path to move it between folders, or with `folderPath: null` to move it back to the dashboard root. Embedded slashes remain part of one virtual path rather than creating a nested UI hierarchy. Moving the final project out of a folder removes that empty folder automatically. Use `inspect_editor` to read each project's current `folderPath`.
+
 Use readable role-based type ranges: title `92–124`, subtitle `68–84`, body `54–68`, caption `44–52`. Do not solve dense copy by dropping below the body range; shorten it or split it across slides. `add_text` and `update_text` automatically preserve width and fit height around every wrapped line with safe padding. For highlighted text, prefer `style: "boxed"` with `backgroundShape: "lines"`. Use `backgroundShape: "full"` only for a deliberate card. Call `fit_text_boxes` with `mode: "both"` only when you intentionally want the width to shrink too.
 
 After each meaningful composition or after a short batch, call `render_slide` and inspect the returned image. Fix clipping, spacing, contrast, unsafe overlay placement, and weak hierarchy before claiming the slide is finished. Use `export_slide` or `export_project` only when local files are requested; do not overwrite existing files unless authorized.

package/src/daemon.mjs

@@ -2,17 +2,21 @@
 import { createServer } from "node:http";
 import { randomBytes, randomUUID } from "node:crypto";
 import { appendFile, mkdir, open, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
-import { basename, extname } from "node:path";
+import { basename, delimiter, extname } from "node:path";
 import {
   ALLOWED_ORIGINS, AUDIT_LOG_PATH, BRIDGE_HOST, BRIDGE_PORT, BRIDGE_URL, DAEMON_LOCK_PATH,
   DAEMON_STATE_PATH, PACKAGE_NAME, PACKAGE_VERSION, PROTOCOL_VERSION, STATE_DIRECTORY,
 } from "./config.mjs";
+import { createLocalFontService } from "./local-fonts.mjs";
 
 const MAX_JSON_BYTES = 40 * 1024 * 1024;
 const MAX_MEDIA_BYTES = 25 * 1024 * 1024;
 const EDITOR_TTL_MS = Number(process.env.CAROUSELBOT_EDITOR_TTL_MS || process.env.SLIDE_STUDIO_EDITOR_TTL_MS) || 60_000;
 const CLIENT_TTL_MS = 45_000;
 const MEDIA_TTL_MS = 5 * 60_000;
+const FONT_MEDIA_TTL_MS = 5 * 60_000;
+const MAX_FONT_MEDIA_ITEMS = 32;
+const MAX_FONT_MEDIA_BYTES = 256 * 1024 * 1024;
 const COMMAND_TIMEOUT_MS = 90_000;
 const EDIT_SESSION_TTL_MS = Number(process.env.CAROUSELBOT_EDIT_SESSION_TTL_MS || process.env.SLIDE_STUDIO_EDIT_SESSION_TTL_MS) || 5 * 60_000;
 const MAX_AUDIT_EVENTS = 500;
@@ -24,8 +28,17 @@ const editors = new Map();
 const clients = new Map();
 const inflight = new Map();
 const media = new Map();
+const fontMedia = new Map();
 const editSessions = new Map();
 const auditEvents = [];
+const configuredFontDirectories = String(process.env.CAROUSELBOT_FONT_DIRS || process.env.SLIDE_STUDIO_FONT_DIRS || "")
+  .split(delimiter)
+  .map((value) => value.trim())
+  .filter(Boolean);
+const localFonts = createLocalFontService({
+  cacheDirectory: STATE_DIRECTORY,
+  ...(configuredFontDirectories.length ? { directories: configuredFontDirectories } : {}),
+});
 let focusedEditorId = null;
 let lockHandle = null;
 let idleSince = null;
@@ -189,7 +202,7 @@ function browserCors(origin) {
     "Access-Control-Allow-Origin": origin,
     "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
     "Access-Control-Allow-Headers": "Authorization, Content-Type",
-    "Access-Control-Expose-Headers": "X-CarouselBot-Filename, X-Slide-Studio-Filename",
+    "Access-Control-Expose-Headers": "X-CarouselBot-Filename, X-Slide-Studio-Filename, X-CarouselBot-Local-Font-Id",
     "Access-Control-Allow-Private-Network": "true",
     "Access-Control-Max-Age": "600",
     "Cache-Control": "no-store",
@@ -203,6 +216,18 @@ function sendJson(response, statusCode, value, headers = {}) {
   response.end(body);
 }
 
+function sendLocalFont(response, item, headers = {}) {
+  response.writeHead(200, {
+    ...headers,
+    "Content-Type": item.mimeType,
+    "Content-Length": item.buffer.length,
+    "X-CarouselBot-Filename": encodeURIComponent(item.filename),
+    "X-Slide-Studio-Filename": encodeURIComponent(item.filename),
+    "X-CarouselBot-Local-Font-Id": encodeURIComponent(item.font.localFontId),
+  });
+  response.end(item.buffer);
+}
+
 function readJson(request) {
   return new Promise((resolve, reject) => {
     const chunks = [];
@@ -269,6 +294,7 @@ function disconnectEditor(editorId, message = "Browser editor disconnected.") {
   endEditorPoll(editor);
   for (const session of editSessions.values()) if (session.editorId === editorId) releaseEditSession(session.id, "editor disconnected");
   editors.delete(editorId);
+  for (const [id, item] of fontMedia) if (item.editorId === editorId) fontMedia.delete(id);
   if (focusedEditorId === editorId) focusedEditorId = null;
   for (const [requestId, pending] of inflight) {
     if (pending.editorId !== editorId) continue;
@@ -305,6 +331,22 @@ function selectEditor(clientId) {
   throw new Error("Multiple editors are connected and none is selected. Call list_editors, then select_editor.");
 }
 
+function requireLocalFontPermission(editor) {
+  if (editor?.localFontsEnabled) return editor;
+  throw codedError("FONT_PERMISSION_REQUIRED", "Open CarouselBot and enable local fonts.");
+}
+
+function selectLocalFontEditor(clientId) {
+  return requireLocalFontPermission(selectEditor(clientId));
+}
+
+function localFontEditorForCall(clientId, editSessionId) {
+  if (!editSessionId) return selectLocalFontEditor(clientId);
+  const session = requireEditSession(editSessionId);
+  session.lastClientId = clientId;
+  return requireLocalFontPermission(editors.get(session.editorId));
+}
+
 function resolveBrowserTarget(clientId, { editSessionId, mutating, projectId }) {
   const client = clients.get(clientId) || { id: clientId, name: "MCP agent" };
   if (editSessionId) {
@@ -348,10 +390,21 @@ function callBrowser(clientId, toolName, operation, label, { editSessionId = nul
   return new Promise((resolve, reject) => {
     const timer = setTimeout(() => {
       inflight.delete(requestId);
+      if (operation?.fontMediaId) fontMedia.delete(operation.fontMediaId);
       recordAudit({ action: "tool.result", client, session, editorId: editor.id, projectId, toolName, status: "error", message: "Browser timeout" });
       reject(codedError("BROWSER_TIMEOUT", "The browser did not answer within 90 seconds."));
     }, COMMAND_TIMEOUT_MS);
-    inflight.set(requestId, { resolve, reject, timer, editorId: editor.id, client, session, projectId, toolName });
+    inflight.set(requestId, {
+      resolve,
+      reject,
+      timer,
+      editorId: editor.id,
+      client,
+      session,
+      projectId,
+      toolName,
+      fontMediaId: operation?.fontMediaId || null,
+    });
     queueEditorEvent(editor, { kind: "command", requestId, toolName, operation, label, editSessionId: session?.id || null, agent: publicClient(client) });
   });
 }
@@ -382,6 +435,51 @@ async function prepareMedia(filePath) {
   return { mediaId: id, filename: basename(filePath), mimeType, size: buffer.length };
 }
 
+function localFontFilename(font, mimeType) {
+  const extension = ({
+    "font/ttf": "ttf",
+    "font/otf": "otf",
+    "font/woff": "woff",
+    "font/woff2": "woff2",
+  })[mimeType] || "font";
+  const stem = String(font?.postscriptName || font?.localFontId || "local-font")
+    .replace(/[^a-z0-9._-]+/gi, "-")
+    .replace(/^-+|-+$/g, "") || "local-font";
+  return `${stem}.${extension}`;
+}
+
+async function readLocalFontFace(localFontId) {
+  if (!localFontId || typeof localFontId !== "string") throw codedError("FONT_NOT_FOUND", "A valid localFontId is required.");
+  const prepared = await localFonts.readFace(localFontId);
+  if (!prepared?.font || !prepared?.buffer) throw codedError("FONT_NOT_FOUND", `Local font is unavailable: ${localFontId}`);
+  const buffer = Buffer.isBuffer(prepared.buffer) ? prepared.buffer : Buffer.from(prepared.buffer);
+  const mimeType = prepared.mimeType || "application/octet-stream";
+  return { font: prepared.font, buffer, mimeType, filename: localFontFilename(prepared.font, mimeType) };
+}
+
+async function prepareFont(clientId, localFontId, editSessionId) {
+  const editor = localFontEditorForCall(clientId, editSessionId);
+  const prepared = await readLocalFontFace(localFontId);
+  const now = Date.now();
+  let retainedBytes = 0;
+  for (const [id, item] of fontMedia) {
+    if (item.expiresAt < now) fontMedia.delete(id);
+    else retainedBytes += item.buffer.length;
+  }
+  if (fontMedia.size >= MAX_FONT_MEDIA_ITEMS || retainedBytes + prepared.buffer.length > MAX_FONT_MEDIA_BYTES) {
+    throw codedError("FONT_TRANSFER_LIMIT", "Too many local fonts are waiting to be transferred. Finish the pending imports and retry.");
+  }
+  const fontMediaId = randomUUID();
+  fontMedia.set(fontMediaId, {
+    ...prepared,
+    id: fontMediaId,
+    editorId: editor.id,
+    localFontId: prepared.font.localFontId,
+    expiresAt: now + FONT_MEDIA_TTL_MS,
+  });
+  return { font: prepared.font, fontMediaId };
+}
+
 async function writeExport(filePath, data, overwrite) {
   const buffer = Buffer.from(data, "base64");
   const handle = await open(filePath, overwrite ? "w" : "wx", 0o600).catch((error) => {
@@ -430,6 +528,11 @@ async function handleInternalCall(body) {
     const events = auditEvents.filter((event) => (!body.projectId || event.projectId === body.projectId) && (!body.status || event.status === body.status));
     return { events: events.slice(-limit).reverse(), localLogPath: AUDIT_LOG_PATH };
   }
+  if (body.action === "list_local_fonts") {
+    localFontEditorForCall(body.clientId, body.editSessionId);
+    return localFonts.list({ query: body.query, limit: body.limit, cursor: body.cursor, sort: body.sort });
+  }
+  if (body.action === "prepare_font") return prepareFont(body.clientId, body.localFontId, body.editSessionId);
   if (body.action === "prepare_media") return prepareMedia(body.path);
   if (body.action === "write_export") return writeExport(body.path, body.data, Boolean(body.overwrite));
   if (body.action === "notify") {
@@ -518,12 +621,14 @@ const server = createServer(async (request, response) => {
       }
       const editor = {
         id: body.editorId, queue: [], poll: null, pageUrl: body.pageUrl,
-        pollTimer: null, state: body.state, lastSeen: Date.now(), cors, sessionToken: randomBytes(32).toString("base64url"),
+        pollTimer: null, state: body.state, lastSeen: Date.now(), cors,
+        localFontsEnabled: body.localFontsEnabled === true,
+        sessionToken: randomBytes(32).toString("base64url"),
       };
       editors.set(editor.id, editor);
       if (body.hasFocus && body.visibilityState === "visible") focusedEditorId = editor.id;
       log(`Editor connected (${editor.id.slice(0, 8)})`);
-      return sendJson(response, 200, { ok: true, editorId: editor.id, sessionToken: editor.sessionToken, protocolVersion: PROTOCOL_VERSION, version: PACKAGE_VERSION, agents: activeClients().map(publicClient), editSessions: activeEditSessions().map(publicSession) }, cors);
+      return sendJson(response, 200, { ok: true, editorId: editor.id, sessionToken: editor.sessionToken, protocolVersion: PROTOCOL_VERSION, version: PACKAGE_VERSION, localFontsEnabled: editor.localFontsEnabled, agents: activeClients().map(publicClient), editSessions: activeEditSessions().map(publicSession) }, cors);
     }
     if (url.pathname === "/activate" && request.method === "POST") {
       const body = await readJson(request);
@@ -545,6 +650,55 @@ const server = createServer(async (request, response) => {
       disconnectEditor(editor.id);
       return sendJson(response, 200, { ok: true, editorId: editor.id }, cors);
     }
+    if (url.pathname === "/fonts/enable" && request.method === "POST") {
+      const body = await readJson(request);
+      const editor = requireEditor(request, response, body.editorId, cors);
+      if (!editor) return;
+      editor.localFontsEnabled = true;
+      return sendJson(response, 200, { enabled: true }, cors);
+    }
+    if (url.pathname === "/fonts" && request.method === "GET") {
+      const editor = requireEditor(request, response, url.searchParams.get("editorId"), cors);
+      if (!editor) return;
+      requireLocalFontPermission(editor);
+      const result = await localFonts.list({
+        query: url.searchParams.get("query") || "",
+        limit: url.searchParams.has("limit") ? Number(url.searchParams.get("limit")) : undefined,
+        cursor: url.searchParams.get("cursor") || null,
+        sort: url.searchParams.get("sort") || undefined,
+      });
+      return sendJson(response, 200, result, cors);
+    }
+    if (url.pathname === "/fonts/use" && request.method === "POST") {
+      const body = await readJson(request);
+      const editor = requireEditor(request, response, body.editorId, cors);
+      if (!editor) return;
+      requireLocalFontPermission(editor);
+      const font = await localFonts.markUsed(body.localFontId);
+      if (!font) throw codedError("FONT_NOT_FOUND", `Local font is unavailable: ${body.localFontId}`);
+      return sendJson(response, 200, { font }, cors);
+    }
+    if (url.pathname.startsWith("/fonts/") && request.method === "GET") {
+      const editor = requireEditor(request, response, url.searchParams.get("editorId"), cors);
+      if (!editor) return;
+      requireLocalFontPermission(editor);
+      const localFontId = decodeURIComponent(url.pathname.slice("/fonts/".length));
+      return sendLocalFont(response, await readLocalFontFace(localFontId), cors);
+    }
+    if (url.pathname.startsWith("/font-media/") && request.method === "GET") {
+      const editor = requireEditor(request, response, url.searchParams.get("editorId"), cors);
+      if (!editor) return;
+      requireLocalFontPermission(editor);
+      const id = decodeURIComponent(url.pathname.slice("/font-media/".length));
+      const item = fontMedia.get(id);
+      if (!item || item.expiresAt < Date.now()) {
+        fontMedia.delete(id);
+        throw codedError("FONT_MEDIA_UNAVAILABLE", "Local font transfer is missing or expired.");
+      }
+      if (item.editorId !== editor.id) throw codedError("FONT_MEDIA_UNAVAILABLE", "Local font transfer is missing or expired.");
+      fontMedia.delete(id);
+      return sendLocalFont(response, item, cors);
+    }
     if (url.pathname === "/events" && request.method === "GET") {
       const editor = requireEditor(request, response, url.searchParams.get("editorId"), cors);
       if (!editor) return;
@@ -580,6 +734,7 @@ const server = createServer(async (request, response) => {
       if (!pending || pending.editorId !== editor.id) return sendJson(response, 404, { error: "Unknown request." }, cors);
       inflight.delete(body.requestId);
       clearTimeout(pending.timer);
+      if (pending.fontMediaId) fontMedia.delete(pending.fontMediaId);
       if (body.state) editor.state = body.state;
       if (body.ok) {
         try {
@@ -612,7 +767,11 @@ const server = createServer(async (request, response) => {
     return sendJson(response, 404, { error: "Not found." }, cors);
   } catch (error) {
     const headers = cors || {};
-    const statusCode = error.code === "ENOENT" ? 404 : error.code === "EACCES" ? 403 : 400;
+    const statusCode = ["ENOENT", "FONT_NOT_FOUND", "FONT_MEDIA_UNAVAILABLE"].includes(error.code)
+      ? 404
+      : ["EACCES", "FONT_PERMISSION_REQUIRED"].includes(error.code)
+        ? 403
+        : error.code === "FONT_TRANSFER_LIMIT" ? 429 : 400;
     return sendJson(response, statusCode, { error: error.message }, headers);
   }
 });
@@ -661,6 +820,7 @@ async function cleanup() {
 setInterval(() => {
   const now = Date.now();
   for (const [id, item] of media) if (item.expiresAt < now) media.delete(id);
+  for (const [id, item] of fontMedia) if (item.expiresAt < now) fontMedia.delete(id);
   for (const session of editSessions.values()) if (session.lastSeen < now - EDIT_SESSION_TTL_MS) releaseEditSession(session.id, "lease expired");
   let clientsChanged = false;
   for (const [id, client] of clients) if (client.lastSeen < now - CLIENT_TTL_MS) {

package/src/local-fonts.mjs

@@ -0,0 +1,574 @@
+import { createHash } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import {
+  chmod,
+  mkdir,
+  open,
+  readFile,
+  readdir,
+  realpath,
+  rename,
+  stat,
+  unlink,
+  writeFile,
+} from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import { dirname, extname, join } from "node:path";
+import * as fontkit from "fontkit";
+
+const INDEX_VERSION = 1;
+const CURSOR_VERSION = 1;
+const DEFAULT_REFRESH_INTERVAL_MS = 30_000;
+const MAX_FONT_FILE_BYTES = 256 * 1024 * 1024;
+const MAX_EXTRACTED_FONT_BYTES = 128 * 1024 * 1024;
+const MAX_DISCOVERED_FILES = 20_000;
+const MAX_COLLECTION_FACES = 512;
+const MAX_SFNT_TABLES = 4_096;
+const PUBLIC_FONT_KEYS = [
+  "localFontId",
+  "family",
+  "fullName",
+  "postscriptName",
+  "subfamily",
+  "weight",
+  "italic",
+  "lastUsedAt",
+  "variableAxes",
+];
+const FONT_EXTENSIONS = new Set([".ttf", ".otf", ".ttc", ".woff", ".woff2"]);
+const STYLE_WEIGHTS = [
+  [/\b(?:thin|hairline)\b/i, 100],
+  [/\b(?:extra[ -]?light|ultra[ -]?light)\b/i, 200],
+  [/\blight\b/i, 300],
+  [/\b(?:medium)\b/i, 500],
+  [/\b(?:semi[ -]?bold|demi[ -]?bold)\b/i, 600],
+  [/\b(?:extra[ -]?bold|ultra[ -]?bold)\b/i, 800],
+  [/\b(?:black|heavy)\b/i, 900],
+  [/\bbold\b/i, 700],
+];
+const STYLE_ORDER = [
+  /\bregular\b/i,
+  /\bbook\b/i,
+  /\bmedium\b/i,
+  /\b(?:semi[ -]?bold|demi[ -]?bold)\b/i,
+  /\bbold\b/i,
+];
+
+export function defaultMacFontDirectories() {
+  if (platform() !== "darwin") return [];
+  return [
+    join(homedir(), "Library", "Fonts"),
+    "/Library/Fonts",
+    "/System/Library/Fonts",
+    "/System/Library/Fonts/Supplemental",
+  ];
+}
+
+function codedError(code, message) {
+  const error = new Error(`[${code}] ${message}`);
+  error.code = code;
+  return error;
+}
+
+function sha256(value, encoding = "hex") {
+  return createHash("sha256").update(value).digest(encoding);
+}
+
+function usageGenerationFor(usage) {
+  return sha256(JSON.stringify([...usage.entries()].sort(([left], [right]) => left.localeCompare(right))), "base64url").slice(0, 24);
+}
+
+function stableFontId(pathInternal, faceIndex, size, mtimeMs) {
+  const identity = `${pathInternal}\0${faceIndex}\0${size}\0${mtimeMs}`;
+  return `font_${sha256(identity, "base64url").slice(0, 24)}`;
+}
+
+function cleanString(value, fallback = "") {
+  const normalized = String(value ?? "")
+    .replace(/[\u0000-\u001f\u007f]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 240);
+  return normalized || fallback;
+}
+
+function inferredWeight(font, subfamily) {
+  const os2Weight = Number(font?.["OS/2"]?.usWeightClass);
+  if (Number.isFinite(os2Weight) && os2Weight >= 1 && os2Weight <= 1_000) return Math.round(os2Weight);
+  const variationWeight = Number(font?.variationAxes?.wght?.default);
+  if (Number.isFinite(variationWeight) && variationWeight >= 1 && variationWeight <= 1_000) return Math.round(variationWeight);
+  const match = STYLE_WEIGHTS.find(([pattern]) => pattern.test(subfamily));
+  return match?.[1] || 400;
+}
+
+function variableAxes(font) {
+  return Object.entries(font?.variationAxes || {}).flatMap(([rawTag, value]) => {
+    const tag = cleanString(rawTag).slice(0, 4);
+    const min = Number(value?.min);
+    const max = Number(value?.max);
+    const defaultValue = Number(value?.default);
+    if (!/^[\x20-\x7e]{4}$/.test(tag) || ![min, max, defaultValue].every(Number.isFinite) || min > max) return [];
+    return [{
+      tag,
+      name: cleanString(value?.name, tag),
+      min,
+      max,
+      default: Math.min(max, Math.max(min, defaultValue)),
+    }];
+  }).sort((left, right) => left.tag.localeCompare(right.tag, "en"));
+}
+
+function metadataForFont(font, source, faceIndex) {
+  const postscriptName = cleanString(font?.postscriptName);
+  const fullName = cleanString(font?.fullName, postscriptName);
+  const family = cleanString(font?.familyName, fullName || postscriptName || "Unknown font");
+  const subfamily = cleanString(font?.subfamilyName, "Regular");
+  const fsSelection = font?.["OS/2"]?.fsSelection || {};
+  const italic = Boolean(fsSelection.italic || fsSelection.oblique || Number(font?.italicAngle));
+  const localFontId = stableFontId(source.pathInternal, faceIndex, source.size, source.mtimeMs);
+  return {
+    localFontId,
+    family,
+    fullName: fullName || family,
+    postscriptName: postscriptName || fullName || family,
+    sourcePostscriptName: postscriptName || null,
+    subfamily,
+    weight: inferredWeight(font, subfamily),
+    italic,
+    variableAxes: variableAxes(font),
+    pathInternal: source.pathInternal,
+    faceIndex,
+    size: source.size,
+    mtimeMs: source.mtimeMs,
+    fileFingerprint: source.fileFingerprint,
+    fingerprint: sha256(`${source.fileFingerprint}\0${faceIndex}\0${postscriptName}`),
+    extension: source.extension,
+  };
+}
+
+function publicFont(font, usage) {
+  const value = {
+    localFontId: font.localFontId,
+    family: font.family,
+    fullName: font.fullName,
+    postscriptName: font.postscriptName,
+    subfamily: font.subfamily,
+    weight: font.weight,
+    italic: Boolean(font.italic),
+    lastUsedAt: usage.get(font.localFontId) || null,
+    variableAxes: Array.isArray(font.variableAxes) ? font.variableAxes.map((axis) => ({ ...axis })) : [],
+  };
+  return Object.fromEntries(PUBLIC_FONT_KEYS.map((key) => [key, value[key]]));
+}
+
+function styleRank(font) {
+  const style = `${font.subfamily} ${font.italic ? "Italic" : ""}`;
+  const base = STYLE_ORDER.findIndex((pattern) => pattern.test(style));
+  return (font.italic ? 100 : 0) + (base < 0 ? 5 : base);
+}
+
+const collator = new Intl.Collator("en", { sensitivity: "base", numeric: true });
+
+function alphabetical(left, right) {
+  return collator.compare(left.family, right.family)
+    || styleRank(left) - styleRank(right)
+    || collator.compare(left.subfamily, right.subfamily)
+    || collator.compare(left.fullName, right.fullName)
+    || left.localFontId.localeCompare(right.localFontId);
+}
+
+function normalizedQuery(value) {
+  return cleanString(value).normalize("NFKC").toLocaleLowerCase("en-US").slice(0, 240);
+}
+
+function cursorValue(value) {
+  try {
+    if (typeof value !== "string" || !value || value.length > 2_048) throw new Error("invalid");
+    const decoded = JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+    if (decoded?.v !== CURSOR_VERSION || !Number.isInteger(decoded.offset) || decoded.offset < 0) throw new Error("invalid");
+    return decoded;
+  } catch {
+    throw codedError("INVALID_FONT_CURSOR", "The local-font cursor is invalid or expired. Start listing again without a cursor.");
+  }
+}
+
+function encodeCursor(value) {
+  return Buffer.from(JSON.stringify({ v: CURSOR_VERSION, ...value })).toString("base64url");
+}
+
+async function readJson(path) {
+  if (!path) return null;
+  try { return JSON.parse(await readFile(path, "utf8")); }
+  catch { return null; }
+}
+
+async function writePrivateJson(path, value) {
+  if (!path) return;
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(value)}\n`, { mode: 0o600 });
+    await rename(temporary, path);
+    await chmod(path, 0o600).catch(() => {});
+  } finally {
+    await unlink(temporary).catch(() => {});
+  }
+}
+
+async function fontPaths(directories) {
+  const roots = [];
+  for (const candidate of directories) {
+    try { roots.push(await realpath(candidate)); }
+    catch { /* Missing font roots are normal. */ }
+  }
+  roots.sort();
+  const discovered = new Map();
+  const pending = [...new Set(roots)];
+  while (pending.length) {
+    const directory = pending.shift();
+    let entries;
+    try { entries = await readdir(directory, { withFileTypes: true }); }
+    catch { continue; }
+    entries.sort((left, right) => left.name.localeCompare(right.name, "en"));
+    for (const entry of entries) {
+      const path = join(directory, entry.name);
+      if (entry.isDirectory()) {
+        pending.push(path);
+        continue;
+      }
+      if (!entry.isFile() || !FONT_EXTENSIONS.has(extname(entry.name).toLowerCase())) continue;
+      let canonical;
+      let metadata;
+      try {
+        canonical = await realpath(path);
+        metadata = await stat(canonical);
+      } catch { continue; }
+      if (!metadata.isFile() || metadata.size <= 0 || metadata.size > MAX_FONT_FILE_BYTES) continue;
+      discovered.set(canonical, {
+        pathInternal: canonical,
+        size: metadata.size,
+        mtimeMs: Number(metadata.mtimeMs),
+        extension: extname(canonical).toLowerCase(),
+      });
+      if (discovered.size > MAX_DISCOVERED_FILES) {
+        throw codedError("FONT_INDEX_TOO_LARGE", "Too many local font files were found to index safely.");
+      }
+    }
+  }
+  return [...discovered.values()].sort((left, right) => left.pathInternal.localeCompare(right.pathInternal));
+}
+
+async function readFileSafely(pathInternal) {
+  const flags = fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW || 0);
+  const handle = await open(pathInternal, flags);
+  try {
+    const metadata = await handle.stat();
+    if (!metadata.isFile() || metadata.size <= 0 || metadata.size > MAX_FONT_FILE_BYTES) {
+      throw codedError("FONT_UNAVAILABLE", "The selected local font is unavailable or too large.");
+    }
+    return { buffer: await handle.readFile(), metadata };
+  } finally {
+    await handle.close();
+  }
+}
+
+function mimeTypeFor(buffer, extension = "") {
+  const signature = buffer.subarray(0, 4).toString("latin1");
+  if (signature === "wOF2") return "font/woff2";
+  if (signature === "wOFF") return "font/woff";
+  if (signature === "OTTO") return "font/otf";
+  if (["\u0000\u0001\u0000\u0000", "true", "typ1"].includes(signature)) return "font/ttf";
+  if (extension === ".woff2") return "font/woff2";
+  if (extension === ".woff") return "font/woff";
+  if (extension === ".otf") return "font/otf";
+  return "font/ttf";
+}
+
+function checksum(buffer) {
+  let sum = 0;
+  for (let offset = 0; offset < buffer.length; offset += 4) {
+    let word = 0;
+    for (let index = 0; index < 4; index += 1) word = ((word << 8) | (buffer[offset + index] || 0)) >>> 0;
+    sum = (sum + word) >>> 0;
+  }
+  return sum;
+}
+
+function checkedRange(buffer, offset, length, label) {
+  if (!Number.isSafeInteger(offset) || !Number.isSafeInteger(length) || offset < 0 || length < 0 || offset + length > buffer.length) {
+    throw codedError("INVALID_FONT_COLLECTION", `The selected collection has an invalid ${label}.`);
+  }
+}
+
+function align4(value) {
+  return Math.ceil(value / 4) * 4;
+}
+
+/** Repack one TTC/OTC face as a standalone, browser-loadable SFNT font. */
+export function extractTtcFace(value, faceIndex) {
+  const source = Buffer.isBuffer(value) ? value : Buffer.from(value);
+  checkedRange(source, 0, 12, "header");
+  if (source.subarray(0, 4).toString("ascii") !== "ttcf") {
+    throw codedError("INVALID_FONT_COLLECTION", "The selected font is not a TrueType/OpenType collection.");
+  }
+  const faceCount = source.readUInt32BE(8);
+  if (!faceCount || faceCount > MAX_COLLECTION_FACES) throw codedError("INVALID_FONT_COLLECTION", "The collection has an invalid face count.");
+  if (!Number.isInteger(faceIndex) || faceIndex < 0 || faceIndex >= faceCount) {
+    throw codedError("FONT_FACE_NOT_FOUND", `Font face ${faceIndex} does not exist in this collection.`);
+  }
+  checkedRange(source, 12, faceCount * 4, "face directory");
+  const faceOffset = source.readUInt32BE(12 + faceIndex * 4);
+  checkedRange(source, faceOffset, 12, "face header");
+  const sfntVersion = source.subarray(faceOffset, faceOffset + 4);
+  const signature = sfntVersion.toString("latin1");
+  if (!["\u0000\u0001\u0000\u0000", "true", "typ1", "OTTO"].includes(signature)) {
+    throw codedError("INVALID_FONT_COLLECTION", "The selected collection face is not an SFNT font.");
+  }
+  const tableCount = source.readUInt16BE(faceOffset + 4);
+  if (!tableCount || tableCount > MAX_SFNT_TABLES) throw codedError("INVALID_FONT_COLLECTION", "The collection face has an invalid table count.");
+  checkedRange(source, faceOffset + 12, tableCount * 16, "table directory");
+  const records = [];
+  const tags = new Set();
+  for (let index = 0; index < tableCount; index += 1) {
+    const recordOffset = faceOffset + 12 + index * 16;
+    const tagBytes = source.subarray(recordOffset, recordOffset + 4);
+    const tag = tagBytes.toString("latin1");
+    const offset = source.readUInt32BE(recordOffset + 8);
+    const length = source.readUInt32BE(recordOffset + 12);
+    checkedRange(source, offset, length, `table ${JSON.stringify(tag)}`);
+    if (tags.has(tag)) throw codedError("INVALID_FONT_COLLECTION", "The collection face contains duplicate table tags.");
+    tags.add(tag);
+    if (tag !== "DSIG") records.push({ tag, tagBytes: Buffer.from(tagBytes), offset, length });
+  }
+  const head = records.find((record) => record.tag === "head");
+  if (!head || head.length < 12) throw codedError("INVALID_FONT_COLLECTION", "The collection face has no valid head table.");
+
+  let outputLength = 12 + records.length * 16;
+  for (const record of records) {
+    outputLength = align4(outputLength);
+    record.outputOffset = outputLength;
+    outputLength += align4(record.length);
+    if (outputLength > MAX_EXTRACTED_FONT_BYTES) throw codedError("FONT_TOO_LARGE", "The selected font face is too large to transfer safely.");
+  }
+  const output = Buffer.alloc(outputLength);
+  sfntVersion.copy(output, 0);
+  output.writeUInt16BE(records.length, 4);
+  const highestPowerOfTwo = 2 ** Math.floor(Math.log2(records.length));
+  output.writeUInt16BE(highestPowerOfTwo * 16, 6);
+  output.writeUInt16BE(Math.log2(highestPowerOfTwo), 8);
+  output.writeUInt16BE(records.length * 16 - highestPowerOfTwo * 16, 10);
+
+  for (let index = 0; index < records.length; index += 1) {
+    const record = records[index];
+    source.copy(output, record.outputOffset, record.offset, record.offset + record.length);
+    if (record.tag === "head") output.writeUInt32BE(0, record.outputOffset + 8);
+    const directoryOffset = 12 + index * 16;
+    record.tagBytes.copy(output, directoryOffset);
+    output.writeUInt32BE(checksum(output.subarray(record.outputOffset, record.outputOffset + record.length)), directoryOffset + 4);
+    output.writeUInt32BE(record.outputOffset, directoryOffset + 8);
+    output.writeUInt32BE(record.length, directoryOffset + 12);
+  }
+  const adjustment = (0xb1b0afba - checksum(output)) >>> 0;
+  output.writeUInt32BE(adjustment, head.outputOffset + 8);
+  if (checksum(output) !== 0xb1b0afba) throw codedError("INVALID_FONT_COLLECTION", "The extracted font checksum could not be repaired.");
+  return output;
+}
+
+function safeFilename(font, mimeType) {
+  const extension = mimeType === "font/woff2" ? ".woff2" : mimeType === "font/woff" ? ".woff" : mimeType === "font/otf" ? ".otf" : ".ttf";
+  const stem = cleanString(font.postscriptName || font.fullName || "local-font", "local-font")
+    .replace(/[^a-z0-9._-]+/gi, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 120) || "local-font";
+  return `${stem}${extension}`;
+}
+
+export function createLocalFontService({
+  directories = defaultMacFontDirectories(),
+  cacheDirectory = null,
+  cachePath = cacheDirectory ? join(cacheDirectory, "local-font-index-v1.json") : null,
+  usagePath = cacheDirectory ? join(cacheDirectory, "local-font-usage-v1.json") : null,
+  refreshIntervalMs = DEFAULT_REFRESH_INTERVAL_MS,
+  now = () => Date.now(),
+} = {}) {
+  let records = new Map();
+  let files = [];
+  let generation = "empty";
+  let initialized = false;
+  let lastRefreshAt = -Infinity;
+  let refreshPromise = null;
+  let usagePromise = null;
+  let usage = new Map();
+  let usageGeneration = usageGenerationFor(usage);
+  let usageWrite = Promise.resolve();
+
+  async function loadUsage() {
+    if (usagePromise) return usagePromise;
+    usagePromise = (async () => {
+      const cached = await readJson(usagePath);
+      usage = new Map(Object.entries(cached?.usage || {}).flatMap(([id, timestamp]) => (
+        /^font_[A-Za-z0-9_-]{8,}$/.test(id) && Number.isFinite(Number(timestamp)) && Number(timestamp) > 0
+          ? [[id, Number(timestamp)]]
+          : []
+      )));
+      usageGeneration = usageGenerationFor(usage);
+      return usage;
+    })();
+    return usagePromise;
+  }
+
+  async function buildIndex() {
+    const candidates = await fontPaths(directories);
+    const cached = await readJson(cachePath);
+    const cachedFiles = new Map((cached?.version === INDEX_VERSION && Array.isArray(cached.files) ? cached.files : [])
+      .map((file) => [file.pathInternal, file]));
+    const nextFiles = [];
+    const seenFingerprints = new Set();
+    const nextRecords = new Map();
+    for (const candidate of candidates) {
+      const previous = cachedFiles.get(candidate.pathInternal);
+      let indexed;
+      if (previous && previous.size === candidate.size && previous.mtimeMs === candidate.mtimeMs && previous.extension === candidate.extension) {
+        indexed = previous;
+      } else {
+        try {
+          const { buffer } = await readFileSafely(candidate.pathInternal);
+          const fileFingerprint = sha256(buffer);
+          const parsed = fontkit.create(buffer);
+          const parsedFaces = Array.isArray(parsed?.fonts) ? parsed.fonts : [parsed];
+          if (!parsedFaces.length || parsedFaces.length > MAX_COLLECTION_FACES) throw new Error("Invalid face count");
+          const source = { ...candidate, fileFingerprint };
+          indexed = {
+            ...candidate,
+            fileFingerprint,
+            faces: parsedFaces.map((font, faceIndex) => metadataForFont(font, source, faceIndex)),
+          };
+        } catch {
+          indexed = { ...candidate, fileFingerprint: null, faces: [], invalid: true };
+        }
+      }
+      nextFiles.push(indexed);
+      if (!indexed.fileFingerprint || seenFingerprints.has(indexed.fileFingerprint)) continue;
+      seenFingerprints.add(indexed.fileFingerprint);
+      for (const face of indexed.faces || []) nextRecords.set(face.localFontId, face);
+    }
+    files = nextFiles;
+    records = nextRecords;
+    generation = sha256([...records.keys()].sort().join("\0"), "base64url").slice(0, 24);
+    lastRefreshAt = now();
+    initialized = true;
+    await writePrivateJson(cachePath, { version: INDEX_VERSION, generatedAt: lastRefreshAt, files });
+    return records;
+  }
+
+  async function refresh({ force = false } = {}) {
+    if (!force && initialized && now() - lastRefreshAt < refreshIntervalMs) return records;
+    if (!refreshPromise) refreshPromise = buildIndex().finally(() => { refreshPromise = null; });
+    return refreshPromise;
+  }
+
+  async function list({ query = "", limit = 50, cursor = null, sort = "recent_then_alphabetical" } = {}) {
+    await Promise.all([refresh(), loadUsage()]);
+    const safeQuery = normalizedQuery(query);
+    const safeSort = sort === "alphabetical" ? "alphabetical" : "recent_then_alphabetical";
+    const safeLimit = Math.max(1, Math.min(200, Number.isFinite(Number(limit)) ? Math.trunc(Number(limit)) : 50));
+    let offset = 0;
+    if (cursor) {
+      const decoded = cursorValue(cursor);
+      if (
+        decoded.generation !== generation
+        || decoded.query !== safeQuery
+        || decoded.sort !== safeSort
+        || (safeSort === "recent_then_alphabetical" && decoded.usageGeneration !== usageGeneration)
+      ) {
+        throw codedError("INVALID_FONT_CURSOR", "The local-font cursor is invalid or expired. Start listing again without a cursor.");
+      }
+      offset = decoded.offset;
+    }
+    let matches = [...records.values()].filter((font) => {
+      if (!safeQuery) return true;
+      return [font.family, font.fullName, font.postscriptName, font.subfamily]
+        .some((value) => normalizedQuery(value).includes(safeQuery));
+    });
+    if (safeSort === "alphabetical") matches.sort(alphabetical);
+    else {
+      const recent = matches
+        .filter((font) => usage.has(font.localFontId))
+        .sort((left, right) => usage.get(right.localFontId) - usage.get(left.localFontId) || alphabetical(left, right))
+        .slice(0, 8);
+      const recentIds = new Set(recent.map((font) => font.localFontId));
+      matches = [...recent, ...matches.filter((font) => !recentIds.has(font.localFontId)).sort(alphabetical)];
+    }
+    const page = matches.slice(offset, offset + safeLimit);
+    const nextOffset = offset + page.length;
+    return {
+      fonts: page.map((font) => publicFont(font, usage)),
+      nextCursor: nextOffset < matches.length
+        ? encodeCursor({
+          generation,
+          query: safeQuery,
+          sort: safeSort,
+          offset: nextOffset,
+          ...(safeSort === "recent_then_alphabetical" ? { usageGeneration } : {}),
+        })
+        : null,
+    };
+  }
+
+  async function resolve(localFontId) {
+    await Promise.all([refresh(), loadUsage()]);
+    const font = records.get(String(localFontId || ""));
+    return font ? { ...font, lastUsedAt: usage.get(font.localFontId) || null } : null;
+  }
+
+  async function readFace(localFontId) {
+    let font = await resolve(localFontId);
+    if (!font) return null;
+    let read;
+    try { read = await readFileSafely(font.pathInternal); }
+    catch {
+      await refresh({ force: true });
+      throw codedError("FONT_UNAVAILABLE", `${font.fullName} is not available on this device.`);
+    }
+    const currentMtime = Number(read.metadata.mtimeMs);
+    const currentFingerprint = sha256(read.buffer);
+    if (read.metadata.size !== font.size || currentMtime !== font.mtimeMs || currentFingerprint !== font.fileFingerprint) {
+      await refresh({ force: true });
+      throw codedError("FONT_UNAVAILABLE", `${font.fullName} changed on this device. List local fonts again and use its new ID.`);
+    }
+    let buffer = read.buffer;
+    if (buffer.subarray(0, 4).toString("ascii") === "ttcf") buffer = extractTtcFace(buffer, font.faceIndex);
+    const mimeType = mimeTypeFor(buffer, font.extension);
+    try {
+      const parsed = fontkit.create(buffer);
+      if (Array.isArray(parsed?.fonts) || (font.sourcePostscriptName && cleanString(parsed?.postscriptName) !== font.sourcePostscriptName)) {
+        throw new Error("Extracted face mismatch");
+      }
+    } catch {
+      throw codedError("FONT_UNAVAILABLE", `${font.fullName} could not be prepared for the browser.`);
+    }
+    return {
+      font: publicFont(font, usage),
+      buffer,
+      mimeType,
+      filename: safeFilename(font, mimeType),
+    };
+  }
+
+  async function markUsed(localFontId, at = now()) {
+    await Promise.all([refresh(), loadUsage()]);
+    const font = records.get(String(localFontId || ""));
+    if (!font) return null;
+    const timestamp = Number.isFinite(Number(at)) && Number(at) > 0 ? Number(at) : now();
+    usage.set(font.localFontId, timestamp);
+    usageGeneration = usageGenerationFor(usage);
+    usageWrite = usageWrite.then(() => writePrivateJson(usagePath, {
+      version: INDEX_VERSION,
+      usage: Object.fromEntries([...usage.entries()].sort(([left], [right]) => left.localeCompare(right))),
+    }));
+    await usageWrite;
+    return publicFont(font, usage);
+  }
+
+  return { list, resolve, readFace, markUsed, refresh };
+}

package/src/mcp-server.mjs

@@ -6,6 +6,9 @@ import { EDITOR_URL, GUIDANCE_PATH, PACKAGE_NAME, PACKAGE_VERSION } from "./conf
 
 const id = z.string().min(1).max(160);
 const optionalId = id.optional();
+const folderPath = z.string().min(2).max(160)
+  .regex(/^\/(?!\/)\S(?:[\s\S]*\S)?$/, "Use a canonical folder path with one leading slash and no surrounding whitespace, for example /my-folder.")
+  .refine((value) => value !== "/." && value !== "/..", "Folder paths cannot use the reserved names /. or /..");
 const color = z.string().regex(/^#?[0-9a-f]{3}(?:[0-9a-f]{3})?$/i, "Use a 3- or 6-digit hex color.");
 const unit = z.number().min(-0.5).max(1.5);
 const positiveUnit = z.number().min(0.01).max(2.4);
@@ -13,12 +16,17 @@ const expectedRevision = z.number().int().min(0).optional().describe("Optional o
 const editSessionId = optionalId.describe("Edit session from begin_edit_session. Required for coordinated parallel editing.");
 const targetProject = { editSessionId, projectId: optionalId, expectedRevision };
 const targetSlide = { editSessionId, projectId: optionalId, slideId: optionalId, expectedRevision };
+const fontId = z.union([id, z.null()]).optional().describe("Project font ID returned by import_font. Use null to restore the built-in font.");
 const textFields = {
   text: z.string().max(4000).optional(), x: unit.optional(), y: unit.optional(), width: positiveUnit.optional(), height: positiveUnit.optional(),
   role: z.enum(["title", "subtitle", "body", "caption"]).optional().describe("Semantic size role. Recommended ranges: title 92-124, subtitle 68-84, body 54-68, caption 44-52."),
   size: z.number().min(20).max(180).optional(), style: z.enum(["plain", "outline", "boxed"]).optional(),
   outlineWidth: z.number().min(0).max(40).optional(), color: color.optional(), background: z.enum(["white", "black"]).optional(),
   backgroundShape: z.enum(["lines", "full"]).optional(), align: z.enum(["left", "center", "right"]).optional(),
+  fontId,
+  fontWeight: z.number().int().min(1).max(1000).optional(),
+  fontStyle: z.enum(["normal", "italic"]).optional(),
+  fontVariationSettings: z.record(z.string().regex(/^[A-Za-z0-9]{4}$/), z.number()).optional(),
   rotation: z.number().min(-720).max(720).optional(), z: z.number().optional(),
 };
 const imageFields = {
@@ -35,8 +43,11 @@ function textResult(value, summary = value) {
 }
 
 function compactMutation(value) {
-  const keys = ["id", "editSessionId", "editorId", "projectId", "slideId", "revision", "leaseExpiresAt", "purpose", "released", "opened", "createdSlideId", "createdTextId", "fittedTextBox", "createdImageId", "createdLayers", "assetId", "deletedAssetId", "deletedProjectId", "deletedSlideId", "deletedLayerIds", "updatedTextIds", "fittedTextBoxes", "updatedImageIds", "applied", "path", "bytes"];
-  return Object.fromEntries(keys.flatMap((key) => value?.[key] == null ? [] : [[key, value[key]]]));
+  const keys = ["id", "editSessionId", "editorId", "projectId", "folderPath", "slideId", "revision", "leaseExpiresAt", "purpose", "released", "opened", "createdSlideId", "createdTextId", "fittedTextBox", "createdImageId", "createdLayers", "assetId", "fontId", "localFontId", "existing", "repaired", "deletedAssetId", "deletedProjectId", "deletedSlideId", "deletedLayerIds", "updatedTextIds", "fittedTextBoxes", "updatedImageIds", "applied", "path", "bytes"];
+  return Object.fromEntries(keys.flatMap((key) => {
+    if (key === "folderPath" && Object.hasOwn(value || {}, key)) return [[key, value[key] ?? null]];
+    return value?.[key] == null ? [] : [[key, value[key]]];
+  }));
 }
 
 function clientIdentity(context, server) {
@@ -53,10 +64,10 @@ async function pathExists(value) {
 
 function operationLabel(toolName) {
   return ({
-    create_project: "Creating a project…", update_project: "Updating the project…", delete_project: "Deleting a project…",
+    create_project: "Creating a project…", update_project: "Updating the project…", move_project: "Moving the project…", delete_project: "Deleting a project…",
     open_project: "Opening a project…", add_slide: "Adding a slide…", update_slide: "Updating a slide…",
     duplicate_slide: "Duplicating a slide…", reorder_slides: "Reordering slides…", delete_slide: "Deleting a slide…",
-    add_text: "Adding text…", update_text: "Updating text…", fit_text_boxes: "Fitting text boxes…", import_asset: "Importing a local image…",
+    add_text: "Adding text…", update_text: "Updating text…", fit_text_boxes: "Fitting text boxes…", import_font: "Adding a local font…", import_asset: "Importing a local image…",
     update_asset: "Updating an image asset…", delete_asset: "Deleting an image asset…", add_image: "Placing an image…",
     update_image: "Updating an image…", delete_layers: "Deleting layers…", duplicate_layers: "Duplicating layers…",
     reorder_layers: "Reordering layers…", undo: "Undoing the last edit…", redo: "Redoing the last edit…",
@@ -67,11 +78,11 @@ function operationLabel(toolName) {
 async function browserOperation(companion, toolName, args) {
   const { editSessionId: sessionId, ...toolArgs } = args;
   const definition = definitions.get(toolName);
-  const operation = await prepareOperation(companion, toolName, toolArgs);
+  const operation = await prepareOperation(companion, toolName, toolArgs, sessionId);
   return companion.call("browser", { toolName, operation, label: operationLabel(toolName), editSessionId: sessionId, mutating: Boolean(definition?.mutating) });
 }
 
-async function prepareOperation(companion, toolName, args) {
+async function prepareOperation(companion, toolName, args, editSessionId = null) {
   const operation = { ...args };
   if (operation.backgroundPath) {
     const prepared = await companion.call("prepare_media", { path: absolutePath(operation.backgroundPath) });
@@ -83,10 +94,15 @@ async function prepareOperation(companion, toolName, args) {
     operation.mediaId = prepared.mediaId;
     delete operation.path;
   }
+  if (toolName === "import_font") {
+    const prepared = await companion.call("prepare_font", { localFontId: operation.localFontId, editSessionId });
+    operation.font = prepared.font;
+    operation.fontMediaId = prepared.fontMediaId;
+  }
   const type = ({
-    create_project: "project.create", open_project: "project.open", update_project: "project.update", delete_project: "project.delete",
+    create_project: "project.create", open_project: "project.open", update_project: "project.update", move_project: "project.move", delete_project: "project.delete",
     add_slide: "slide.add", update_slide: "slide.update", duplicate_slide: "slide.duplicate", reorder_slides: "slide.reorder", delete_slide: "slide.delete",
-    add_text: "text.add", update_text: "text.update", fit_text_boxes: "text.fit", import_asset: "asset.import", update_asset: "asset.update", delete_asset: "asset.delete",
+    add_text: "text.add", update_text: "text.update", fit_text_boxes: "text.fit", import_font: "font.import", list_project_fonts: "font.list", import_asset: "asset.import", update_asset: "asset.update", delete_asset: "asset.delete",
     add_image: "image.add", update_image: "image.update", delete_layers: "layer.delete", duplicate_layers: "layer.duplicate", reorder_layers: "layer.reorder",
     undo: "history.undo", redo: "history.redo", set_view: "view.update", render_slide: "slide.render", inspect_editor: "editor.inspect",
   })[toolName];
@@ -151,11 +167,14 @@ export async function createCarouselBotMcpServer(companion) {
   register("list_edit_sessions", "List active edit reservations, their owners, projects, and lease expirations.", z.object({}).strict(), () => companion.call("list_edit_sessions"), { readOnlyHint: true });
   register("list_recent_operations", "Read the local sanitized operation audit. Text, prompts, paths, and image bytes are never logged.", z.object({ limit: z.number().int().min(1).max(200).default(50), projectId: optionalId, status: z.enum(["started", "ok", "error", "blocked"]).optional() }).strict(), (args) => companion.call("list_recent_operations", args), { readOnlyHint: true });
   register("inspect_editor", "Inspect projects, slides, assets, and every text/image layer without returning image bytes.", z.object({ ...targetSlide, includeAllProjects: z.boolean().default(true) }).strict(), (args) => browserOperation(companion, "inspect_editor", args), { readOnlyHint: true });
+  register("list_local_fonts", "Search fonts installed on this computer. Returns opaque local font IDs and never filesystem paths. The user must enable local fonts in CarouselBot first.", z.object({ editSessionId, query: z.string().max(200).optional(), limit: z.number().int().min(1).max(200).default(80), cursor: z.string().max(2048).optional(), sort: z.enum(["recent_then_alphabetical", "alphabetical"]).default("recent_then_alphabetical") }).strict(), (args) => companion.call("list_local_fonts", args), { readOnlyHint: true });
+  register("list_project_fonts", "List fonts already imported into one project, including whether each face is currently available.", z.object({ ...targetProject, projectId: id }).strict(), (args) => browserOperation(companion, "list_project_fonts", args), { readOnlyHint: true });
   register("show_notification", "Show a short visual notification in a connected editor for status or marketing demos.", z.object({ editSessionId, message: z.string().min(1).max(240), tone: z.enum(["agent", "success", "info", "error"]).default("agent") }).strict(), ({ editSessionId, ...args }) => companion.call("notify", { ...args, editSessionId }), { destructiveHint: false, idempotentHint: false });
 
-  register("create_project", "Create an empty project without changing the user's current browser view. Its dashboard card appears live when the dashboard is open.", z.object({ editSessionId, name: z.string().min(1).max(160) }).strict(), (args) => browserOperation(companion, "create_project", args), { destructiveHint: false });
+  register("create_project", "Create an empty project without changing the user's current browser view. Pass a canonical folderPath such as /my-folder to create it inside that folder; omit it or use null for the dashboard root.", z.object({ editSessionId, name: z.string().min(1).max(160), folderPath: folderPath.nullable().optional() }).strict(), (args) => browserOperation(companion, "create_project", args), { destructiveHint: false });
   register("open_project", "Explicitly navigate the browser to a project and optionally a specific slide without changing content. Use only when the user asks to show it.", z.object({ editSessionId, projectId: id, slideId: optionalId }).strict(), (args) => browserOperation(companion, "open_project", args), { destructiveHint: false, idempotentHint: true });
   register("update_project", "Rename a project.", z.object({ ...targetProject, name: z.string().min(1).max(160) }).strict(), (args) => browserOperation(companion, "update_project", args), { destructiveHint: true });
+  register("move_project", "Move a project into a folder by canonical slash path, move it between folders, or move it back to the dashboard root with folderPath=null. Folder cards are derived from project membership, so empty folders disappear.", z.object({ ...targetProject, projectId: id, folderPath: folderPath.nullable() }).strict(), (args) => browserOperation(companion, "move_project", args), { destructiveHint: true });
   register("delete_project", "Delete a project from browser storage.", z.object({ ...targetProject, projectId: id }).strict(), (args) => browserOperation(companion, "delete_project", args), { destructiveHint: true });
 
   register("add_slide", "Add a slide using a solid color or local background image path. The browser follows it only when that project is already visible.", z.object({ ...targetProject, name: z.string().max(160).optional(), index: z.number().int().min(0).optional(), backgroundColor: color.optional(), backgroundPath: z.string().min(1).optional() }).strict(), (args) => browserOperation(companion, "add_slide", args), { destructiveHint: false });
@@ -167,6 +186,7 @@ export async function createCarouselBotMcpServer(companion) {
   register("add_text", "Add a text layer. Choose a semantic role and a size within its readable range. Width is preserved while height is fitted automatically with safe padding; boxed text defaults to the preferred per-line background.", z.object({ ...targetSlide, ...textFields, text: z.string().min(1).max(4000) }).strict(), (args) => browserOperation(companion, "add_text", args), { destructiveHint: false });
   register("update_text", "Update one or more text layers. Every updated layer automatically keeps its width and refits its height with safe padding, so a render-fit-render loop is unnecessary.", z.object({ ...targetSlide, updates: z.array(z.object({ id, ...textFields }).strict()).min(1).max(100) }).strict(), (args) => browserOperation(companion, "update_text", args), { destructiveHint: true });
   register("fit_text_boxes", "Explicitly resize text boxes to their rendered content. add_text and update_text already fit height automatically; use mode=both only when you also want to shrink width.", z.object({ ...targetSlide, textIds: z.array(id).min(1).max(100), mode: z.enum(["height", "both"]).default("both") }).strict(), (args) => browserOperation(companion, "fit_text_boxes", args), { destructiveHint: true });
+  register("import_font", "Add one installed font face to a project using a localFontId returned by list_local_fonts. Exact face bytes remain on this computer and duplicate imports are reused.", z.object({ ...targetProject, projectId: id, localFontId: id }).strict(), (args) => browserOperation(companion, "import_font", args), { destructiveHint: false });
 
   register("import_asset", "Import a local image file into the active project's reusable asset library. Image bytes stay local.", z.object({ ...targetSlide, path: z.string().min(1), name: z.string().max(160).optional() }).strict(), (args) => browserOperation(companion, "import_asset", args), { destructiveHint: false });
   register("update_asset", "Rename a reusable image asset.", z.object({ ...targetProject, assetId: id, name: z.string().min(1).max(160) }).strict(), (args) => browserOperation(companion, "update_asset", args), { destructiveHint: true });
@@ -220,7 +240,7 @@ export async function createCarouselBotMcpServer(companion) {
       if (!definition?.mutating) throw new Error(`Tool cannot be batched: ${item.tool}`);
       const args = definition.inputSchema.parse(item.arguments);
       const { editSessionId: _ignored, ...toolArgs } = args;
-      items.push({ toolName: item.tool, operation: await prepareOperation(companion, item.tool, toolArgs), label: operationLabel(item.tool) });
+      items.push({ toolName: item.tool, operation: await prepareOperation(companion, item.tool, toolArgs, sessionId), label: operationLabel(item.tool) });
     }
     return companion.call("batch", { items, editSessionId: sessionId });
   }, { destructiveHint: true });

package/src/setup.mjs

@@ -62,8 +62,7 @@ export async function runSetup(arguments_) {
   const clientArgument = arguments_.find((value) => value.startsWith("--client="))?.slice("--client=".length);
   const requested = clientArgument ? clientArgument.split(",").map((value) => value.trim().toLowerCase()) : supported.filter(commandExists);
   const clients = [...new Set(requested)].filter((client) => supported.includes(client));
-  const releaseTag = PACKAGE_VERSION.includes("-beta.") ? "beta" : "latest";
-  const specifier = `${PACKAGE_NAME}@${releaseTag}`;
+  const specifier = `${PACKAGE_NAME}@${PACKAGE_VERSION}`;
   const dryRun = flags.has("--dry-run");
   const assumeYes = flags.has("--yes") || flags.has("-y");
   if (!clients.length) throw new Error("No supported agent CLI was detected. Use --client=claude,codex,hermes,opencode,openclaw or copy the generic stdio config below.");