minecodex 0.1.4 → 0.1.5

package/features/images/codex-feature.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "id": "images",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "label": {
     "en": "Images",
     "zh-CN": "图片"

package/features/images/src/http-server.mjs

@@ -5,6 +5,7 @@ import path from "node:path";
 import { saveImageAs } from "./save-as.mjs";
 
 const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+const CODEX_EMBED_ORIGIN = "app://-";
 const DEFAULT_PAGE_LIMIT = 36;
 const MAX_PAGE_LIMIT = 72;
 const MAX_PAGE_OFFSET = Number.MAX_SAFE_INTEGER;
@@ -69,6 +70,16 @@ function mutationError(message, code) {
   return Object.assign(new Error(message), { status: 403, code });
 }
 
+function applyCodexEmbedCors(request, response) {
+  if (request.headers.origin !== CODEX_EMBED_ORIGIN) return false;
+  response.setHeader("Access-Control-Allow-Origin", CODEX_EMBED_ORIGIN);
+  response.setHeader("Access-Control-Allow-Methods", "GET, HEAD, POST, OPTIONS");
+  response.setHeader("Access-Control-Allow-Headers", "Content-Type");
+  response.setHeader("Access-Control-Allow-Private-Network", "true");
+  response.setHeader("Vary", "Origin");
+  return true;
+}
+
 function parseIntegerQuery(searchParams, name, { defaultValue, min, max }) {
   const values = searchParams.getAll(name);
   if (values.length === 0) return defaultValue;
@@ -115,6 +126,7 @@ function validateMutationOrigin(request, address, host) {
   if (!origin) {
     throw mutationError("Mutation requests require the exact bound loopback Origin", "ORIGIN_NOT_ALLOWED");
   }
+  if (origin === CODEX_EMBED_ORIGIN) return;
   let parsed;
   try {
     parsed = new URL(origin);
@@ -137,13 +149,20 @@ export async function createHttpServer({
   if (!LOOPBACK_HOSTS.has(host)) throw new Error("Images only supports loopback hosts");
   const server = createNodeServer(async (request, response) => {
     try {
+      applyCodexEmbedCors(request, response);
       const address = server.address();
       const boundOrigin = address && typeof address !== "string"
         ? `http://${formatHost(host)}:${address.port}`
         : `http://${formatHost(host)}:${port}`;
       const url = new URL(request.url ?? "/", boundOrigin);
 
-      if (!["GET", "HEAD", "OPTIONS"].includes(request.method)) {
+      if (request.method === "OPTIONS") {
+        response.writeHead(204, { "Cache-Control": "no-store" });
+        response.end();
+        return;
+      }
+
+      if (!["GET", "HEAD"].includes(request.method)) {
         validateMutationOrigin(request, address, host);
       }
 

package/features/model-slider/codex-feature.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "id": "model-slider",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "label": {
     "en": "Model Slider",
     "zh-CN": "模型滑条"

package/features/notes/codex-feature.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "id": "notes",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "label": {
     "en": "Notes",
     "zh-CN": "笔记"

package/features/notes/src/http-server.mjs

@@ -15,6 +15,7 @@ const LUCIDE_ICON_ROOT = path.resolve(DEFAULT_WEB_ROOT, "../assets/icons");
 const MAX_BODY_BYTES = 1024 * 1024;
 const MAX_PREVIEW_BYTES = 64 * 1024 * 1024;
 const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+const CODEX_EMBED_ORIGIN = "app://-";
 const LUCIDE_ICON_NAMES = [
   "circle",
   "ellipsis",
@@ -233,6 +234,16 @@ function formatHost(host) {
   return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
 }
 
+function applyCodexEmbedCors(request, response) {
+  if (request.headers.origin !== CODEX_EMBED_ORIGIN) return false;
+  response.setHeader("Access-Control-Allow-Origin", CODEX_EMBED_ORIGIN);
+  response.setHeader("Access-Control-Allow-Methods", "GET, HEAD, POST, PATCH, DELETE, OPTIONS");
+  response.setHeader("Access-Control-Allow-Headers", "Content-Type");
+  response.setHeader("Access-Control-Allow-Private-Network", "true");
+  response.setHeader("Vary", "Origin");
+  return true;
+}
+
 function validateMutationOrigin(request, address, host) {
   const expectedHost = formatHost(host);
   const expectedOrigin = `http://${expectedHost}:${address.port}`;
@@ -246,6 +257,7 @@ function validateMutationOrigin(request, address, host) {
 
   const origin = request.headers.origin;
   if (!origin) return;
+  if (origin === CODEX_EMBED_ORIGIN) return;
   let parsed;
   try {
     parsed = new URL(origin);
@@ -285,6 +297,7 @@ export function createCodexNotesServer({
 
   const server = createServer(async (request, response) => {
     try {
+      applyCodexEmbedCors(request, response);
       const url = new URL(request.url ?? "/", `http://${formatHost(host)}:${port}`);
       const { pathname } = url;
       const method = request.method ?? "GET";
@@ -293,12 +306,7 @@ export function createCodexNotesServer({
       }
 
       if (method === "OPTIONS") {
-        response.writeHead(204, {
-          "Access-Control-Allow-Origin": request.headers.origin ?? "null",
-          "Access-Control-Allow-Headers": "Content-Type",
-          "Access-Control-Allow-Methods": "GET, POST, PATCH, DELETE, OPTIONS",
-          "Access-Control-Max-Age": "600",
-        });
+        response.writeHead(204, { "Access-Control-Max-Age": "600" });
         response.end();
         return;
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minecodex",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Lightweight, local-first plugins for the Codex desktop app.",
   "license": "MIT",
   "type": "module",

package/packages/runtime-host/README.md

@@ -141,8 +141,10 @@ Host 会再次发送当前状态。功能页面可据此暂停隐藏状态下的
 
 - 只在 top frame 安装 Runtime，绝不向业务 iframe 注入 binding token。
 - Watch / refresh 串行；已连接 Renderer 不重复连接，关闭 target 会清理状态。
-- 本地 Surface 注入前先启用 CSP bypass，并为后续 document 注册 document-start 脚本；
-  当前 Codex document 始终直接注入或替换 Runtime，绝不通过 CDP reload Codex 页面。
+- 当前 Codex document 始终直接注入或替换 Runtime，绝不通过 CDP reload Codex 页面。
+  本地 Surface 不直接导航到 loopback URL：Host 先创建 `about:blank` iframe，再校验
+  manifest URL、health service/protocol/instance，抓取 HTML 并用 `Page.setDocumentContent`
+  写入目标 frame。Images/Notes 只向精确的 `app://-` Origin 开放 CORS。
 - 入口由 Renderer 内的 MutationObserver 幂等挂载，React 重绘不会产生重复入口。
 - Summary 根据对话主区域宽度连续派生 `overlay / shift / gutter`：小于 1096px
   使用临时 Popover；1096–1535px 预留 316px 并把对话内容左移 158px；更宽时
@@ -154,9 +156,9 @@ Host 会再次发送当前状态。功能页面可据此暂停隐藏状态下的
   border、dropdown background 和 elevation tokens 发送给 Surface。
 - 新客户端会话默认关闭；Thread 切换关闭 Pinned Summary 并清除旧 Composer Range。
 - Detail Tab 使用 Codex 当前 `local-thread` scope，因此标签状态跟随 Task；React panel
-  中的 iframe 继续注册同一套 Surface origin、`contentWindow`、Theme 与 Host-action bridge。
+  中的 iframe 继续注册同一套可信 Host origin、`contentWindow`、Theme 与 Host-action bridge。
 - Surface 以 `ready` handshake 标记可用。若第一次加载发生在服务离线期间，下一次
-  打开只重载这个未 ready 的 iframe；已经 ready 的 Surface 不重载、不打断草稿。
+  打开只重新请求 Host 加载这个未 ready 的 frame；已经 ready 的 Surface 不重载、不打断草稿。
 
 ## 当前接口分类
 

package/packages/runtime-host/src/codex-runtime.mjs

@@ -7,6 +7,10 @@ const RUNTIME_VERSION = 99;
 const HOST_BINDING_NAME = "__codexPersonalHostAction";
 const CSP_BOOTSTRAP_VERSION = 1;
 const CSP_BOOTSTRAP_KEY = "__mineCodexCspBootstrapVersion";
+const CODEX_APP_ORIGIN = "app://-";
+const SURFACE_LOAD_ACTION = "load-surface";
+const SURFACE_FRAME_PREFIX = "minecodex-surface-";
+const LOOPBACK_SURFACE_HOSTS = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
 
 export const RESPONSIVE_SUMMARY_LAYOUT = Object.freeze({
   contentBaseWidth: 736,
@@ -38,6 +42,48 @@ export function responsiveSummaryContentShift({ displayMode, isPinned }, layout
     : 0;
 }
 
+function declaredSurfaceUrls(feature) {
+  return new Set([
+    feature.surfaceUrl,
+    feature.pinnedSummary?.surfaceUrl,
+    ...(feature.detailTabs ?? []).map((detail) => detail.surfaceUrl),
+  ].filter(Boolean));
+}
+
+function requireDeclaredLoopbackSurface(feature, value) {
+  if (typeof value !== "string" || !declaredSurfaceUrls(feature).has(value)) {
+    throw Object.assign(new Error("Surface URL is not declared by this feature"), {
+      code: "SURFACE_URL_NOT_ALLOWED",
+    });
+  }
+  const url = new URL(value);
+  if (url.protocol !== "http:" || !LOOPBACK_SURFACE_HOSTS.has(url.hostname)) {
+    throw Object.assign(new Error("Surface URL must use an exact loopback HTTP origin"), {
+      code: "SURFACE_URL_NOT_ALLOWED",
+    });
+  }
+  return url;
+}
+
+function findFrameByName(frameTree, frameName) {
+  if (frameTree.frame?.name === frameName) return frameTree.frame;
+  for (const child of frameTree.childFrames ?? []) {
+    const match = findFrameByName(child, frameName);
+    if (match) return match;
+  }
+  return null;
+}
+
+function documentWithBase(html, surfaceUrl) {
+  const head = /<head(?:\s[^>]*)?>/i;
+  if (!head.test(html)) {
+    throw Object.assign(new Error("Surface document has no head element"), {
+      code: "SURFACE_DOCUMENT_INVALID",
+    });
+  }
+  return html.replace(head, (match) => `${match}<base href=${JSON.stringify(surfaceUrl)}>`);
+}
+
 export function createInjectionSource(features, {
   bindingName = HOST_BINDING_NAME,
   bindingToken = "test-binding-token",
@@ -1785,6 +1831,32 @@ export function createInjectionSource(features, {
       return `${featureId}:${kind}:${detailId}`;
     }
 
+    function surfaceFrameName(featureId) {
+      const nonce = crypto.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+      return `minecodex-surface-${config.sessionId}-${featureId}-${nonce}`;
+    }
+
+    function requestSurfaceLoad(record) {
+      if (!record || record.loading || typeof globalThis[config.bindingName] !== "function") return false;
+      const requestId = crypto.randomUUID?.()
+        ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+      record.loading = true;
+      record.ready = false;
+      record.loadError = null;
+      pendingHostActions.set(requestId, { recordKey: record.key, kind: "surface-load" });
+      globalThis[config.bindingName](JSON.stringify({
+        token: config.bindingToken,
+        featureId: record.featureId,
+        requestId,
+        action: "load-surface",
+        payload: {
+          frameName: record.frame.name,
+          surfaceUrl: record.surfaceUrl,
+        },
+      }));
+      return true;
+    }
+
     function postSurfaceActive(record, active) {
       if (!record || record.kind !== "page") return;
       record.frame.contentWindow?.postMessage({
@@ -1799,10 +1871,13 @@ export function createInjectionSource(features, {
         featureId: feature.id,
         kind,
         detailId,
-        origin: new URL(surfaceUrl).origin,
+        origin: window.location.origin,
+        surfaceUrl,
         element,
         frame,
         ready: false,
+        loading: false,
+        loadError: null,
         preferredHeight: null,
       };
       surfaceRecords.set(key, record);
@@ -1810,14 +1885,14 @@ export function createInjectionSource(features, {
         queueTheme();
         postSurfaceActive(record, activePageFeatureId === record.featureId && !record.element.hidden);
       });
+      requestSurfaceLoad(record);
       return record;
     }
 
     function reloadSurfaceIfUnready(key, surfaceUrl) {
       const record = surfaceRecords.get(key);
-      if (!record || record.ready) return false;
-      record.frame.src = surfaceUrl;
-      return true;
+      if (!record || record.ready || record.surfaceUrl !== surfaceUrl) return false;
+      return requestSurfaceLoad(record);
     }
 
     function removeSurfaceRecord(key) {
@@ -2056,9 +2131,10 @@ export function createInjectionSource(features, {
       }
     }
 
-    function createFrame(surfaceUrl, title) {
+    function createFrame(featureId, title) {
       const frame = document.createElement("iframe");
-      frame.src = surfaceUrl;
+      frame.name = surfaceFrameName(featureId);
+      frame.src = "about:blank";
       frame.title = title;
       frame.allow = "clipboard-write";
       frame.style.cssText = "width:100%;height:100%;border:0;display:block;background:transparent";
@@ -2076,7 +2152,7 @@ export function createInjectionSource(features, {
         "z-index:40",
         "background:transparent",
       ].join(";");
-      const frame = createFrame(feature.surfaceUrl, feature.label);
+      const frame = createFrame(feature.id, feature.label);
       surface.append(frame);
       document.body.append(surface);
       pageSurfaces.set(feature.id, surface);
@@ -2311,7 +2387,7 @@ export function createInjectionSource(features, {
         "pointer-events:none",
         "will-change:transform,opacity",
       ].join(";");
-      const frame = createFrame(definition.surfaceUrl, definition.label ?? feature.label);
+      const frame = createFrame(feature.id, definition.label ?? feature.label);
       surface.append(frame);
       document.body.append(surface);
       pinnedSurfaces.set(feature.id, surface);
@@ -2505,7 +2581,7 @@ export function createInjectionSource(features, {
         "outline:none",
       ].join(";");
 
-      const frame = createFrame(editorUrl.href, `${payload.id ? "Edit" : "Add"} ${kind}`);
+      const frame = createFrame(feature.id, `${payload.id ? "Edit" : "Add"} ${kind}`);
       dialog.append(frame);
       document.body.append(overlay, dialog);
       const key = surfaceKey(feature.id, "modal");
@@ -2751,6 +2827,8 @@ export function createInjectionSource(features, {
         const elementRef = React.useRef(null);
         const frameRef = React.useRef(null);
         const recordKeyRef = React.useRef(null);
+        const frameNameRef = React.useRef(null);
+        frameNameRef.current ??= surfaceFrameName(feature.id);
         React.useLayoutEffect(() => {
           const element = elementRef.current;
           const frame = frameRef.current;
@@ -2785,7 +2863,8 @@ export function createInjectionSource(features, {
           },
           children: jsx.jsx("iframe", {
             ref: frameRef,
-            src: detail.surfaceUrl,
+            name: frameNameRef.current,
+            src: "about:blank",
             title: detail.label,
             allow: "clipboard-write",
             style: {
@@ -3027,7 +3106,7 @@ export function createInjectionSource(features, {
       panel.setAttribute("data-app-shell-tab-panel-controller", "right");
       panel.setAttribute("data-tab-id", stableId);
       panel.style.cssText = "position:absolute;inset:0;min-height:0;background:var(--color-token-main-surface-primary)";
-      const frame = createFrame(detail.surfaceUrl, detail.label);
+      const frame = createFrame(feature.id, detail.label);
       panel.append(frame);
       strip.append(tab);
       panels.append(panel);
@@ -3337,6 +3416,11 @@ export function createInjectionSource(features, {
       pendingHostActions.delete(requestId);
       const record = surfaceRecords.get(pending.recordKey);
       if (!record) return false;
+      if (pending.kind === "surface-load") {
+        record.loading = false;
+        record.loadError = response.ok ? null : response.error;
+        return response.ok;
+      }
       respondToSurface(record, requestId, response);
       return true;
     }
@@ -3735,6 +3819,9 @@ export class CodexRuntime {
     availabilityTimeoutMs = 20_000,
     availabilityPollMs = 500,
     monitorIntervalMs = 2_000,
+    surfaceLoadTimeoutMs = 5_000,
+    surfaceFramePollMs = 25,
+    featureInstanceId = null,
     runtimeSessionId = randomBytes(16).toString("hex"),
     onStatusChange = null,
     onManagedCodexPidChange = null,
@@ -3751,6 +3838,9 @@ export class CodexRuntime {
     this.availabilityTimeoutMs = availabilityTimeoutMs;
     this.availabilityPollMs = availabilityPollMs;
     this.monitorIntervalMs = monitorIntervalMs;
+    this.surfaceLoadTimeoutMs = surfaceLoadTimeoutMs;
+    this.surfaceFramePollMs = surfaceFramePollMs;
+    this.featureInstanceId = featureInstanceId;
     this.runtimeSessionId = runtimeSessionId;
     this.onStatusChange = onStatusChange;
     this.onManagedCodexPidChange = onManagedCodexPidChange;
@@ -4099,6 +4189,106 @@ export class CodexRuntime {
     }
   }
 
+  async fetchSurfaceResource(url, label) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.surfaceLoadTimeoutMs);
+    try {
+      return await this.fetchImpl(url, {
+        cache: "no-store",
+        headers: { origin: CODEX_APP_ORIGIN },
+        signal: controller.signal,
+      });
+    } catch (error) {
+      if (controller.signal.aborted) {
+        throw Object.assign(new Error(`${label} timed out`), { code: "SURFACE_LOAD_TIMEOUT" });
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  async verifiedSurfaceDocument(feature, surfaceUrl) {
+    requireDeclaredLoopbackSurface(feature, surfaceUrl);
+    if (!this.featureInstanceId || !feature.healthUrl) {
+      throw Object.assign(new Error("Surface service identity is unavailable"), {
+        code: "SURFACE_IDENTITY_UNAVAILABLE",
+      });
+    }
+    const healthResponse = await this.fetchSurfaceResource(feature.healthUrl, "Surface health check");
+    if (!healthResponse?.ok) {
+      throw Object.assign(new Error(`Surface health returned HTTP ${healthResponse?.status ?? "error"}`), {
+        code: "SURFACE_HEALTH_FAILED",
+      });
+    }
+    let health;
+    try {
+      health = await healthResponse.json();
+    } catch {
+      throw Object.assign(new Error("Surface health returned invalid JSON"), {
+        code: "SURFACE_HEALTH_FAILED",
+      });
+    }
+    if (
+      health?.ok !== true
+      || health.service !== feature.id
+      || health.protocolVersion !== 1
+      || health.instanceId !== this.featureInstanceId
+    ) {
+      throw Object.assign(new Error("Surface service identity does not match this RuntimeHost"), {
+        code: "SURFACE_IDENTITY_MISMATCH",
+      });
+    }
+
+    const response = await this.fetchSurfaceResource(surfaceUrl, "Surface document request");
+    if (!response?.ok) {
+      throw Object.assign(new Error(`Surface document returned HTTP ${response?.status ?? "error"}`), {
+        code: "SURFACE_DOCUMENT_FAILED",
+      });
+    }
+    const contentType = String(response.headers?.get?.("content-type") ?? "").toLowerCase();
+    if (!contentType.startsWith("text/html")) {
+      throw Object.assign(new Error("Surface document must be HTML"), {
+        code: "SURFACE_DOCUMENT_INVALID",
+      });
+    }
+    return documentWithBase(await response.text(), surfaceUrl);
+  }
+
+  async loadSurfaceIntoFrame(client, feature, payload = {}) {
+    const frameName = payload.frameName;
+    if (
+      typeof frameName !== "string"
+      || !frameName.startsWith(SURFACE_FRAME_PREFIX)
+      || frameName.length > 256
+    ) {
+      throw Object.assign(new Error("Surface frame identity is invalid"), {
+        code: "SURFACE_FRAME_INVALID",
+      });
+    }
+    const surfaceUrl = payload.surfaceUrl;
+    const html = await this.verifiedSurfaceDocument(feature, surfaceUrl);
+    const deadline = Date.now() + this.surfaceLoadTimeoutMs;
+    let frame = null;
+    while (!frame && Date.now() < deadline) {
+      const { frameTree } = await client.send("Page.getFrameTree");
+      frame = findFrameByName(frameTree, frameName);
+      if (!frame) await this.sleep(this.surfaceFramePollMs);
+    }
+    if (!frame) {
+      throw Object.assign(new Error("Surface frame was not discovered"), {
+        code: "SURFACE_FRAME_NOT_FOUND",
+      });
+    }
+    if (frame.url !== "about:blank") {
+      throw Object.assign(new Error("Surface frame must remain at about:blank before loading"), {
+        code: "SURFACE_FRAME_INVALID",
+      });
+    }
+    await client.send("Page.setDocumentContent", { frameId: frame.id, html });
+    return { loaded: true };
+  }
+
   async handleBindingCalled(targetId, client, params) {
     if (params.name !== HOST_BINDING_NAME) return;
     let request;
@@ -4109,6 +4299,18 @@ export class CodexRuntime {
     }
     if (request.token !== this.bindingTokens.get(targetId) || typeof request.requestId !== "string") return;
     const feature = this.features.find((candidate) => candidate.id === request.featureId);
+    if (feature && request.action === SURFACE_LOAD_ACTION) {
+      try {
+        const result = await this.loadSurfaceIntoFrame(client, feature, request.payload);
+        await this.resolveHostAction(client, request.requestId, { ok: true, result });
+      } catch (error) {
+        await this.resolveHostAction(client, request.requestId, {
+          ok: false,
+          error: { code: error.code ?? "SURFACE_LOAD_FAILED", message: error.message },
+        });
+      }
+      return;
+    }
     if (!feature?.hostActions?.includes(request.action)) {
       await this.resolveHostAction(client, request.requestId, {
         ok: false,

package/packages/runtime-host/src/main.mjs

@@ -63,6 +63,7 @@ featureProcesses = await startFeatureProcesses(features, {
 
 runtime = new CodexRuntime({
   features,
+  featureInstanceId,
   profileDir,
   cdpPort,
   appPath: process.env.MINECODEX_CODEX_EXECUTABLE || undefined,