@immediately-run/sdk 0.5.0 → 0.7.0

package/dist/editor.cjs

@@ -18,20 +18,36 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var editor_exports = {};
 __export(editor_exports, {
-  openInEditor: () => openInEditor
+  createFile: () => createFile,
+  createFolder: () => createFolder,
+  deleteEntry: () => deleteEntry,
+  openInEditor: () => openInEditor,
+  renameEntry: () => renameEntry,
+  uploadFile: () => uploadFile
 });
 module.exports = __toCommonJS(editor_exports);
 var import_sandboxUtils = require("./sandboxUtils");
-const openInEditor = async (path) => {
-  const res = await (0, import_sandboxUtils.protocolRequest)("editor", "open", [{ path }]);
+const editorRequest = async (method, arg) => {
+  const res = await (0, import_sandboxUtils.protocolRequest)("editor", method, [arg]);
   if (!res || res.ok !== true) {
-    const err = new Error(res?.message ?? "open failed");
+    const err = new Error(res?.message ?? `editor ${method} failed`);
     err.code = res?.code ?? "unknown";
     throw err;
   }
 };
+const openInEditor = (path) => editorRequest("open", { path });
+const createFile = (path) => editorRequest("createFile", { path });
+const createFolder = (path) => editorRequest("createFolder", { path });
+const deleteEntry = (path) => editorRequest("deleteEntry", { path });
+const renameEntry = (from, to) => editorRequest("rename", { from, to });
+const uploadFile = (path, bytes) => editorRequest("upload", { path, bytes });
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  openInEditor
+  createFile,
+  createFolder,
+  deleteEntry,
+  openInEditor,
+  renameEntry,
+  uploadFile
 });
 //# sourceMappingURL=editor.cjs.map

package/dist/editor.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/editor.ts"],"sourcesContent":["import { protocolRequest } from './sandboxUtils';\n\n/**\n * Open a working-tree file in the immediately.run host editor (UI_AS_APPS_SPEC §4 —\n * the file explorer's click-to-open). This is an INTENT: the app asks, the HOST\n * validates the path and drives the CodeMirror editor — the editor itself stays\n * host-owned (§2 recursion boundary), so an app can never own or script it beyond\n * \"please show this file\".\n *\n * Requires the elevated `editor:open` capability — a previewed app does not hold it\n * (it must not move the host's focus), so only a system app whose binding grants it\n * (the file explorer) can call this; anyone else is refused at the gate.\n */\n\n/** An error from {@link openInEditor}, carrying a machine-readable `.code`. */\nexport interface EditorOpenError extends Error {\n  code:\n    | 'forbidden' // the frame lacks `editor:open`\n    | 'not-found' // no such file in the live working tree (the host never creates)\n    | 'invalid-params' // the path was empty / contained `..` / looked like a URI\n    | 'no-target' // there is no host editor session to open files in\n    | 'unknown';\n}\n\ntype EditorResult =\n  | { ok: true; data: unknown }\n  | { ok: false; code: string; message: string };\n\n/**\n * Ask the host to open `path` (a repo-relative working-tree path, e.g. `src/App.tsx`\n * or `/src/App.tsx`) in the editor. Resolves once the editor switches to it; rejects\n * with an {@link EditorOpenError} (`.code`) if the path is invalid, missing, or this\n * app may not open files.\n */\nexport const openInEditor = async (path: string): Promise<void> => {\n  const res = (await protocolRequest('editor', 'open', [{ path }])) as EditorResult;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'open failed') as EditorOpenError;\n    err.code = (res?.code as EditorOpenError['code']) ?? 'unknown';\n    throw err;\n  }\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,0BAAgC;AAkCzB,MAAM,eAAe,OAAO,SAAgC;AACjE,QAAM,MAAO,UAAM,qCAAgB,UAAU,QAAQ,CAAC,EAAE,KAAK,CAAC,CAAC;AAC/D,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,aAAa;AACnD,QAAI,OAAQ,KAAK,QAAoC;AACrD,UAAM;AAAA,EACR;AACF;","names":[]}
+{"version":3,"sources":["../src/editor.ts"],"sourcesContent":["import { protocolRequest } from './sandboxUtils';\n\n/**\n * Open a working-tree file in the immediately.run host editor (UI_AS_APPS_SPEC §4 —\n * the file explorer's click-to-open). This is an INTENT: the app asks, the HOST\n * validates the path and drives the CodeMirror editor — the editor itself stays\n * host-owned (§2 recursion boundary), so an app can never own or script it beyond\n * \"please show this file\".\n *\n * Requires the elevated `editor:open` capability — a previewed app does not hold it\n * (it must not move the host's focus), so only a system app whose binding grants it\n * (the file explorer) can call this; anyone else is refused at the gate.\n */\n\n/** An error from {@link openInEditor}, carrying a machine-readable `.code`. */\nexport interface EditorOpenError extends Error {\n  code:\n    | 'forbidden' // the frame lacks `editor:open`\n    | 'not-found' // no such file in the live working tree (the host never creates)\n    | 'invalid-params' // the path was empty / contained `..` / looked like a URI\n    | 'no-target' // there is no host editor session to open files in\n    | 'unknown';\n}\n\ntype EditorResult =\n  | { ok: true; data: unknown }\n  | { ok: false; code: string; message: string };\n\nconst editorRequest = async (\n  method: string,\n  arg: Record<string, unknown>,\n): Promise<void> => {\n  const res = (await protocolRequest('editor', method, [arg])) as EditorResult;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? `editor ${method} failed`) as EditorWriteError;\n    err.code = (res?.code as EditorWriteError['code']) ?? 'unknown';\n    throw err;\n  }\n};\n\n/**\n * Ask the host to open `path` (a repo-relative working-tree path, e.g. `src/App.tsx`\n * or `/src/App.tsx`) in the editor. Resolves once the editor switches to it; rejects\n * with an {@link EditorOpenError} (`.code`) if the path is invalid, missing, or this\n * app may not open files.\n */\nexport const openInEditor = (path: string): Promise<void> => editorRequest('open', { path });\n\n// ---------------------------------------------------------------------------\n// Working-tree mutation (UI_AS_APPS_SPEC §4 / EDITOR_AS_APP_SPEC §5.2). The file\n// explorer NAMES a working-tree path and the HOST performs the COW write (and\n// refreshes the preview) — the app holds no write port; it asks. Gated by the\n// first-party `editor:write` capability, so only a first-party chrome app (the\n// file explorer) can call these; anyone else is refused at the gate.\n// ---------------------------------------------------------------------------\n\n/** An error from a working-tree mutation, carrying a machine-readable `.code`. */\nexport interface EditorWriteError extends Error {\n  code:\n    | 'forbidden' // the frame lacks `editor:write` (first-party-only)\n    | 'not-found' // the target file/folder does not exist (delete/rename)\n    | 'exists' // the target already exists (create/rename would clobber)\n    | 'protected' // the host refuses to delete this file (e.g. package.json)\n    | 'too-large' // an upload exceeds the host's size limit\n    | 'invalid-params' // a path was empty / contained `..` / looked like a URI\n    | 'no-target' // there is no host editor session\n    | 'unknown';\n}\n\n/** Create an empty working-tree file at `path` and open it. Rejects `exists` if a\n *  file is already there. */\nexport const createFile = (path: string): Promise<void> => editorRequest('createFile', { path });\n\n/** Create a working-tree folder at `path` (materialised with a `.gitkeep`). */\nexport const createFolder = (path: string): Promise<void> =>\n  editorRequest('createFolder', { path });\n\n/** Delete a working-tree file, or a folder and everything under it. Rejects\n *  `protected` for files the host won't remove, `not-found` if absent. */\nexport const deleteEntry = (path: string): Promise<void> => editorRequest('deleteEntry', { path });\n\n/** Rename/move a working-tree file from `from` to `to`. Rejects `exists` if `to`\n *  is taken, `not-found` if `from` is absent. */\nexport const renameEntry = (from: string, to: string): Promise<void> =>\n  editorRequest('rename', { from, to });\n\n/** Upload binary/text `bytes` to a working-tree file at `path`. Rejects\n *  `too-large` past the host's size limit. The bytes are transferred (zero-copy). */\nexport const uploadFile = (path: string, bytes: Uint8Array): Promise<void> =>\n  editorRequest('upload', { path, bytes });\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,0BAAgC;AA4BhC,MAAM,gBAAgB,OACpB,QACA,QACkB;AAClB,QAAM,MAAO,UAAM,qCAAgB,UAAU,QAAQ,CAAC,GAAG,CAAC;AAC1D,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,UAAU,MAAM,SAAS;AAC/D,QAAI,OAAQ,KAAK,QAAqC;AACtD,UAAM;AAAA,EACR;AACF;AAQO,MAAM,eAAe,CAAC,SAAgC,cAAc,QAAQ,EAAE,KAAK,CAAC;AAyBpF,MAAM,aAAa,CAAC,SAAgC,cAAc,cAAc,EAAE,KAAK,CAAC;AAGxF,MAAM,eAAe,CAAC,SAC3B,cAAc,gBAAgB,EAAE,KAAK,CAAC;AAIjC,MAAM,cAAc,CAAC,SAAgC,cAAc,eAAe,EAAE,KAAK,CAAC;AAI1F,MAAM,cAAc,CAAC,MAAc,OACxC,cAAc,UAAU,EAAE,MAAM,GAAG,CAAC;AAI/B,MAAM,aAAa,CAAC,MAAc,UACvC,cAAc,UAAU,EAAE,MAAM,MAAM,CAAC;","names":[]}

package/dist/editor.d.cts

@@ -20,5 +20,23 @@ interface EditorOpenError extends Error {
  * app may not open files.
  */
 declare const openInEditor: (path: string) => Promise<void>;
+/** An error from a working-tree mutation, carrying a machine-readable `.code`. */
+interface EditorWriteError extends Error {
+    code: 'forbidden' | 'not-found' | 'exists' | 'protected' | 'too-large' | 'invalid-params' | 'no-target' | 'unknown';
+}
+/** Create an empty working-tree file at `path` and open it. Rejects `exists` if a
+ *  file is already there. */
+declare const createFile: (path: string) => Promise<void>;
+/** Create a working-tree folder at `path` (materialised with a `.gitkeep`). */
+declare const createFolder: (path: string) => Promise<void>;
+/** Delete a working-tree file, or a folder and everything under it. Rejects
+ *  `protected` for files the host won't remove, `not-found` if absent. */
+declare const deleteEntry: (path: string) => Promise<void>;
+/** Rename/move a working-tree file from `from` to `to`. Rejects `exists` if `to`
+ *  is taken, `not-found` if `from` is absent. */
+declare const renameEntry: (from: string, to: string) => Promise<void>;
+/** Upload binary/text `bytes` to a working-tree file at `path`. Rejects
+ *  `too-large` past the host's size limit. The bytes are transferred (zero-copy). */
+declare const uploadFile: (path: string, bytes: Uint8Array) => Promise<void>;
 
-export { type EditorOpenError, openInEditor };
+export { type EditorOpenError, type EditorWriteError, createFile, createFolder, deleteEntry, openInEditor, renameEntry, uploadFile };

package/dist/editor.d.ts

@@ -20,5 +20,23 @@ interface EditorOpenError extends Error {
  * app may not open files.
  */
 declare const openInEditor: (path: string) => Promise<void>;
+/** An error from a working-tree mutation, carrying a machine-readable `.code`. */
+interface EditorWriteError extends Error {
+    code: 'forbidden' | 'not-found' | 'exists' | 'protected' | 'too-large' | 'invalid-params' | 'no-target' | 'unknown';
+}
+/** Create an empty working-tree file at `path` and open it. Rejects `exists` if a
+ *  file is already there. */
+declare const createFile: (path: string) => Promise<void>;
+/** Create a working-tree folder at `path` (materialised with a `.gitkeep`). */
+declare const createFolder: (path: string) => Promise<void>;
+/** Delete a working-tree file, or a folder and everything under it. Rejects
+ *  `protected` for files the host won't remove, `not-found` if absent. */
+declare const deleteEntry: (path: string) => Promise<void>;
+/** Rename/move a working-tree file from `from` to `to`. Rejects `exists` if `to`
+ *  is taken, `not-found` if `from` is absent. */
+declare const renameEntry: (from: string, to: string) => Promise<void>;
+/** Upload binary/text `bytes` to a working-tree file at `path`. Rejects
+ *  `too-large` past the host's size limit. The bytes are transferred (zero-copy). */
+declare const uploadFile: (path: string, bytes: Uint8Array) => Promise<void>;
 
-export { type EditorOpenError, openInEditor };
+export { type EditorOpenError, type EditorWriteError, createFile, createFolder, deleteEntry, openInEditor, renameEntry, uploadFile };

package/dist/editor.js

@@ -1,13 +1,24 @@
 import { protocolRequest } from "./sandboxUtils";
-const openInEditor = async (path) => {
-  const res = await protocolRequest("editor", "open", [{ path }]);
+const editorRequest = async (method, arg) => {
+  const res = await protocolRequest("editor", method, [arg]);
   if (!res || res.ok !== true) {
-    const err = new Error(res?.message ?? "open failed");
+    const err = new Error(res?.message ?? `editor ${method} failed`);
     err.code = res?.code ?? "unknown";
     throw err;
   }
 };
+const openInEditor = (path) => editorRequest("open", { path });
+const createFile = (path) => editorRequest("createFile", { path });
+const createFolder = (path) => editorRequest("createFolder", { path });
+const deleteEntry = (path) => editorRequest("deleteEntry", { path });
+const renameEntry = (from, to) => editorRequest("rename", { from, to });
+const uploadFile = (path, bytes) => editorRequest("upload", { path, bytes });
 export {
-  openInEditor
+  createFile,
+  createFolder,
+  deleteEntry,
+  openInEditor,
+  renameEntry,
+  uploadFile
 };
 //# sourceMappingURL=editor.js.map

package/dist/editor.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/editor.ts"],"sourcesContent":["import { protocolRequest } from './sandboxUtils';\n\n/**\n * Open a working-tree file in the immediately.run host editor (UI_AS_APPS_SPEC §4 —\n * the file explorer's click-to-open). This is an INTENT: the app asks, the HOST\n * validates the path and drives the CodeMirror editor — the editor itself stays\n * host-owned (§2 recursion boundary), so an app can never own or script it beyond\n * \"please show this file\".\n *\n * Requires the elevated `editor:open` capability — a previewed app does not hold it\n * (it must not move the host's focus), so only a system app whose binding grants it\n * (the file explorer) can call this; anyone else is refused at the gate.\n */\n\n/** An error from {@link openInEditor}, carrying a machine-readable `.code`. */\nexport interface EditorOpenError extends Error {\n  code:\n    | 'forbidden' // the frame lacks `editor:open`\n    | 'not-found' // no such file in the live working tree (the host never creates)\n    | 'invalid-params' // the path was empty / contained `..` / looked like a URI\n    | 'no-target' // there is no host editor session to open files in\n    | 'unknown';\n}\n\ntype EditorResult =\n  | { ok: true; data: unknown }\n  | { ok: false; code: string; message: string };\n\n/**\n * Ask the host to open `path` (a repo-relative working-tree path, e.g. `src/App.tsx`\n * or `/src/App.tsx`) in the editor. Resolves once the editor switches to it; rejects\n * with an {@link EditorOpenError} (`.code`) if the path is invalid, missing, or this\n * app may not open files.\n */\nexport const openInEditor = async (path: string): Promise<void> => {\n  const res = (await protocolRequest('editor', 'open', [{ path }])) as EditorResult;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'open failed') as EditorOpenError;\n    err.code = (res?.code as EditorOpenError['code']) ?? 'unknown';\n    throw err;\n  }\n};\n"],"mappings":"AAAA,SAAS,uBAAuB;AAkCzB,MAAM,eAAe,OAAO,SAAgC;AACjE,QAAM,MAAO,MAAM,gBAAgB,UAAU,QAAQ,CAAC,EAAE,KAAK,CAAC,CAAC;AAC/D,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,aAAa;AACnD,QAAI,OAAQ,KAAK,QAAoC;AACrD,UAAM;AAAA,EACR;AACF;","names":[]}
+{"version":3,"sources":["../src/editor.ts"],"sourcesContent":["import { protocolRequest } from './sandboxUtils';\n\n/**\n * Open a working-tree file in the immediately.run host editor (UI_AS_APPS_SPEC §4 —\n * the file explorer's click-to-open). This is an INTENT: the app asks, the HOST\n * validates the path and drives the CodeMirror editor — the editor itself stays\n * host-owned (§2 recursion boundary), so an app can never own or script it beyond\n * \"please show this file\".\n *\n * Requires the elevated `editor:open` capability — a previewed app does not hold it\n * (it must not move the host's focus), so only a system app whose binding grants it\n * (the file explorer) can call this; anyone else is refused at the gate.\n */\n\n/** An error from {@link openInEditor}, carrying a machine-readable `.code`. */\nexport interface EditorOpenError extends Error {\n  code:\n    | 'forbidden' // the frame lacks `editor:open`\n    | 'not-found' // no such file in the live working tree (the host never creates)\n    | 'invalid-params' // the path was empty / contained `..` / looked like a URI\n    | 'no-target' // there is no host editor session to open files in\n    | 'unknown';\n}\n\ntype EditorResult =\n  | { ok: true; data: unknown }\n  | { ok: false; code: string; message: string };\n\nconst editorRequest = async (\n  method: string,\n  arg: Record<string, unknown>,\n): Promise<void> => {\n  const res = (await protocolRequest('editor', method, [arg])) as EditorResult;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? `editor ${method} failed`) as EditorWriteError;\n    err.code = (res?.code as EditorWriteError['code']) ?? 'unknown';\n    throw err;\n  }\n};\n\n/**\n * Ask the host to open `path` (a repo-relative working-tree path, e.g. `src/App.tsx`\n * or `/src/App.tsx`) in the editor. Resolves once the editor switches to it; rejects\n * with an {@link EditorOpenError} (`.code`) if the path is invalid, missing, or this\n * app may not open files.\n */\nexport const openInEditor = (path: string): Promise<void> => editorRequest('open', { path });\n\n// ---------------------------------------------------------------------------\n// Working-tree mutation (UI_AS_APPS_SPEC §4 / EDITOR_AS_APP_SPEC §5.2). The file\n// explorer NAMES a working-tree path and the HOST performs the COW write (and\n// refreshes the preview) — the app holds no write port; it asks. Gated by the\n// first-party `editor:write` capability, so only a first-party chrome app (the\n// file explorer) can call these; anyone else is refused at the gate.\n// ---------------------------------------------------------------------------\n\n/** An error from a working-tree mutation, carrying a machine-readable `.code`. */\nexport interface EditorWriteError extends Error {\n  code:\n    | 'forbidden' // the frame lacks `editor:write` (first-party-only)\n    | 'not-found' // the target file/folder does not exist (delete/rename)\n    | 'exists' // the target already exists (create/rename would clobber)\n    | 'protected' // the host refuses to delete this file (e.g. package.json)\n    | 'too-large' // an upload exceeds the host's size limit\n    | 'invalid-params' // a path was empty / contained `..` / looked like a URI\n    | 'no-target' // there is no host editor session\n    | 'unknown';\n}\n\n/** Create an empty working-tree file at `path` and open it. Rejects `exists` if a\n *  file is already there. */\nexport const createFile = (path: string): Promise<void> => editorRequest('createFile', { path });\n\n/** Create a working-tree folder at `path` (materialised with a `.gitkeep`). */\nexport const createFolder = (path: string): Promise<void> =>\n  editorRequest('createFolder', { path });\n\n/** Delete a working-tree file, or a folder and everything under it. Rejects\n *  `protected` for files the host won't remove, `not-found` if absent. */\nexport const deleteEntry = (path: string): Promise<void> => editorRequest('deleteEntry', { path });\n\n/** Rename/move a working-tree file from `from` to `to`. Rejects `exists` if `to`\n *  is taken, `not-found` if `from` is absent. */\nexport const renameEntry = (from: string, to: string): Promise<void> =>\n  editorRequest('rename', { from, to });\n\n/** Upload binary/text `bytes` to a working-tree file at `path`. Rejects\n *  `too-large` past the host's size limit. The bytes are transferred (zero-copy). */\nexport const uploadFile = (path: string, bytes: Uint8Array): Promise<void> =>\n  editorRequest('upload', { path, bytes });\n"],"mappings":"AAAA,SAAS,uBAAuB;AA4BhC,MAAM,gBAAgB,OACpB,QACA,QACkB;AAClB,QAAM,MAAO,MAAM,gBAAgB,UAAU,QAAQ,CAAC,GAAG,CAAC;AAC1D,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,UAAU,MAAM,SAAS;AAC/D,QAAI,OAAQ,KAAK,QAAqC;AACtD,UAAM;AAAA,EACR;AACF;AAQO,MAAM,eAAe,CAAC,SAAgC,cAAc,QAAQ,EAAE,KAAK,CAAC;AAyBpF,MAAM,aAAa,CAAC,SAAgC,cAAc,cAAc,EAAE,KAAK,CAAC;AAGxF,MAAM,eAAe,CAAC,SAC3B,cAAc,gBAAgB,EAAE,KAAK,CAAC;AAIjC,MAAM,cAAc,CAAC,SAAgC,cAAc,eAAe,EAAE,KAAK,CAAC;AAI1F,MAAM,cAAc,CAAC,MAAc,OACxC,cAAc,UAAU,EAAE,MAAM,GAAG,CAAC;AAI/B,MAAM,aAAa,CAAC,MAAc,UACvC,cAAc,UAAU,EAAE,MAAM,MAAM,CAAC;","names":[]}

package/dist/editorContext.cjs

@@ -24,11 +24,20 @@ __export(editorContext_exports, {
 });
 module.exports = __toCommonJS(editorContext_exports);
 var import_pushChannel = require("./pushChannel");
+const isStringArray = (v) => Array.isArray(v) && v.every((p) => typeof p === "string");
 const channel = (0, import_pushChannel.createPushChannel)({
   pushType: "editor-context",
   requestType: "request-editor-context",
-  initial: { dirtyPaths: [] },
-  parse: (msg) => Array.isArray(msg.dirtyPaths) && msg.dirtyPaths.every((p) => typeof p === "string") ? { dirtyPaths: msg.dirtyPaths } : void 0
+  initial: { dirtyPaths: [], openFiles: [], activeFile: null },
+  parse: (msg) => isStringArray(msg.dirtyPaths) ? {
+    dirtyPaths: msg.dirtyPaths,
+    // `openFiles` is newer than `dirtyPaths`; tolerate an older host that
+    // omits it (defensive SDK — defaults to empty rather than rejecting).
+    openFiles: isStringArray(msg.openFiles) ? msg.openFiles : [],
+    // `activeFile` is newer still; an older host that omits it (or sends a
+    // non-string) reads as `null` — no file highlighted, never a throw.
+    activeFile: typeof msg.activeFile === "string" ? msg.activeFile : null
+  } : void 0
 });
 const getEditorContext = () => channel.get();
 const onEditorContextChange = (listener) => channel.onChange(listener);

package/dist/editorContext.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/editorContext.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\n\n/**\n * The editor \"dirty set\" mirrored from the immediately.run host into the sandbox\n * (UI_AS_APPS_SPEC §5.3): which files the user has changed but not yet saved.\n *\n * This is the ELEVATED `editor:read` capability — only a system app whose binding\n * grants it (e.g. the contribute dialog) receives it. The active file and ref are\n * already available to every app via routing (`useNavigationState`), so this\n * channel carries only the genuine delta: the unsaved paths. An app without\n * `editor:read` simply sees an empty dirty set.\n */\nexport interface EditorContext {\n  /** Repo-relative paths the user has modified but not yet saved. */\n  dirtyPaths: string[];\n}\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `editor-context`\n// and answers `request-editor-context` — but only for a frame holding `editor:read`\n// (gated by the channel router). An app without it gets no reply, so the empty\n// default below stands. Wire format: site-main channelBridge.ts.\nconst channel = createPushChannel<EditorContext>({\n  pushType: 'editor-context',\n  requestType: 'request-editor-context',\n  initial: { dirtyPaths: [] },\n  parse: (msg) =>\n    Array.isArray(msg.dirtyPaths) && msg.dirtyPaths.every((p) => typeof p === 'string')\n      ? { dirtyPaths: msg.dirtyPaths as string[] }\n      : undefined,\n});\n\n/**\n * Returns the current editor context (dirty set). Poll this for a one-off read;\n * use {@link onEditorContextChange} or {@link useEditorContext} to react.\n */\nexport const getEditorContext = (): EditorContext => channel.get();\n\n/**\n * Subscribe to editor-context changes. The listener is invoked immediately with\n * the current context, then again on every change. Returns an unsubscribe fn.\n */\nexport const onEditorContextChange = (listener: (context: EditorContext) => void): (() => void) =>\n  channel.onChange(listener);\n\n/**\n * React hook returning the current editor context (dirty set), re-rendering when\n * it changes. Handy for a contribute dialog: `const { dirtyPaths } =\n * useEditorContext()` to show \"you'll save N files\" before calling `contribute()`.\n */\nexport const useEditorContext = (): EditorContext => channel.use();\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,yBAAkC;AAqBlC,MAAM,cAAU,sCAAiC;AAAA,EAC/C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,EAAE,YAAY,CAAC,EAAE;AAAA,EAC1B,OAAO,CAAC,QACN,MAAM,QAAQ,IAAI,UAAU,KAAK,IAAI,WAAW,MAAM,CAAC,MAAM,OAAO,MAAM,QAAQ,IAC9E,EAAE,YAAY,IAAI,WAAuB,IACzC;AACR,CAAC;AAMM,MAAM,mBAAmB,MAAqB,QAAQ,IAAI;AAM1D,MAAM,wBAAwB,CAAC,aACpC,QAAQ,SAAS,QAAQ;AAOpB,MAAM,mBAAmB,MAAqB,QAAQ,IAAI;","names":[]}
+{"version":3,"sources":["../src/editorContext.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\n\n/**\n * The editor \"dirty set\" mirrored from the immediately.run host into the sandbox\n * (UI_AS_APPS_SPEC §5.3): which files the user has changed but not yet saved.\n *\n * This is the ELEVATED `editor:read` capability — only a system app whose binding\n * grants it (e.g. the contribute dialog) receives it. The active file and ref are\n * already available to every app via routing (`useNavigationState`), so this\n * channel carries only the genuine delta: the unsaved paths. An app without\n * `editor:read` simply sees an empty dirty set.\n */\nexport interface EditorContext {\n  /** Repo-relative paths the user has modified but not yet saved. */\n  dirtyPaths: string[];\n  /** Repo-relative paths currently open as tabs in the host editor (§4.2). */\n  openFiles: string[];\n  /**\n   * The one file currently focused in the host editor (repo-relative, leading\n   * slash — e.g. `/src/index.ts`), or `null` when no file is open. Distinct from\n   * {@link dirtyPaths} (the unsaved SET) and {@link openFiles} (the open-tab set):\n   * this is the single ACTIVE file. A baseline app reads its own active file from\n   * the route, but a self-routed system panel (`drivesHostRoute=false`, e.g. the\n   * file explorer) does not see the host editor's route, so it receives the active\n   * file here instead (UI_AS_APPS_SPEC §5.3 self-routed-panel refinement).\n   */\n  activeFile: string | null;\n}\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `editor-context`\n// and answers `request-editor-context` — but only for a frame holding `editor:read`\n// (gated by the channel router). An app without it gets no reply, so the empty\n// default below stands. Wire format: site-main channelBridge.ts.\nconst isStringArray = (v: unknown): v is string[] =>\n  Array.isArray(v) && v.every((p) => typeof p === 'string');\n\nconst channel = createPushChannel<EditorContext>({\n  pushType: 'editor-context',\n  requestType: 'request-editor-context',\n  initial: { dirtyPaths: [], openFiles: [], activeFile: null },\n  parse: (msg) =>\n    isStringArray(msg.dirtyPaths)\n      ? {\n          dirtyPaths: msg.dirtyPaths,\n          // `openFiles` is newer than `dirtyPaths`; tolerate an older host that\n          // omits it (defensive SDK — defaults to empty rather than rejecting).\n          openFiles: isStringArray(msg.openFiles) ? msg.openFiles : [],\n          // `activeFile` is newer still; an older host that omits it (or sends a\n          // non-string) reads as `null` — no file highlighted, never a throw.\n          activeFile: typeof msg.activeFile === 'string' ? msg.activeFile : null,\n        }\n      : undefined,\n});\n\n/**\n * Returns the current editor context (dirty set). Poll this for a one-off read;\n * use {@link onEditorContextChange} or {@link useEditorContext} to react.\n */\nexport const getEditorContext = (): EditorContext => channel.get();\n\n/**\n * Subscribe to editor-context changes. The listener is invoked immediately with\n * the current context, then again on every change. Returns an unsubscribe fn.\n */\nexport const onEditorContextChange = (listener: (context: EditorContext) => void): (() => void) =>\n  channel.onChange(listener);\n\n/**\n * React hook returning the current editor context (dirty set), re-rendering when\n * it changes. Handy for a contribute dialog: `const { dirtyPaths } =\n * useEditorContext()` to show \"you'll save N files\" before calling `contribute()`.\n */\nexport const useEditorContext = (): EditorContext => channel.use();\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,yBAAkC;AAiClC,MAAM,gBAAgB,CAAC,MACrB,MAAM,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,OAAO,MAAM,QAAQ;AAE1D,MAAM,cAAU,sCAAiC;AAAA,EAC/C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,EAAE,YAAY,CAAC,GAAG,WAAW,CAAC,GAAG,YAAY,KAAK;AAAA,EAC3D,OAAO,CAAC,QACN,cAAc,IAAI,UAAU,IACxB;AAAA,IACE,YAAY,IAAI;AAAA;AAAA;AAAA,IAGhB,WAAW,cAAc,IAAI,SAAS,IAAI,IAAI,YAAY,CAAC;AAAA;AAAA;AAAA,IAG3D,YAAY,OAAO,IAAI,eAAe,WAAW,IAAI,aAAa;AAAA,EACpE,IACA;AACR,CAAC;AAMM,MAAM,mBAAmB,MAAqB,QAAQ,IAAI;AAM1D,MAAM,wBAAwB,CAAC,aACpC,QAAQ,SAAS,QAAQ;AAOpB,MAAM,mBAAmB,MAAqB,QAAQ,IAAI;","names":[]}

package/dist/editorContext.d.cts

@@ -11,6 +11,18 @@
 interface EditorContext {
     /** Repo-relative paths the user has modified but not yet saved. */
     dirtyPaths: string[];
+    /** Repo-relative paths currently open as tabs in the host editor (§4.2). */
+    openFiles: string[];
+    /**
+     * The one file currently focused in the host editor (repo-relative, leading
+     * slash — e.g. `/src/index.ts`), or `null` when no file is open. Distinct from
+     * {@link dirtyPaths} (the unsaved SET) and {@link openFiles} (the open-tab set):
+     * this is the single ACTIVE file. A baseline app reads its own active file from
+     * the route, but a self-routed system panel (`drivesHostRoute=false`, e.g. the
+     * file explorer) does not see the host editor's route, so it receives the active
+     * file here instead (UI_AS_APPS_SPEC §5.3 self-routed-panel refinement).
+     */
+    activeFile: string | null;
 }
 /**
  * Returns the current editor context (dirty set). Poll this for a one-off read;

package/dist/editorContext.d.ts

@@ -11,6 +11,18 @@
 interface EditorContext {
     /** Repo-relative paths the user has modified but not yet saved. */
     dirtyPaths: string[];
+    /** Repo-relative paths currently open as tabs in the host editor (§4.2). */
+    openFiles: string[];
+    /**
+     * The one file currently focused in the host editor (repo-relative, leading
+     * slash — e.g. `/src/index.ts`), or `null` when no file is open. Distinct from
+     * {@link dirtyPaths} (the unsaved SET) and {@link openFiles} (the open-tab set):
+     * this is the single ACTIVE file. A baseline app reads its own active file from
+     * the route, but a self-routed system panel (`drivesHostRoute=false`, e.g. the
+     * file explorer) does not see the host editor's route, so it receives the active
+     * file here instead (UI_AS_APPS_SPEC §5.3 self-routed-panel refinement).
+     */
+    activeFile: string | null;
 }
 /**
  * Returns the current editor context (dirty set). Poll this for a one-off read;

package/dist/editorContext.js

@@ -1,9 +1,18 @@
 import { createPushChannel } from "./pushChannel";
+const isStringArray = (v) => Array.isArray(v) && v.every((p) => typeof p === "string");
 const channel = createPushChannel({
   pushType: "editor-context",
   requestType: "request-editor-context",
-  initial: { dirtyPaths: [] },
-  parse: (msg) => Array.isArray(msg.dirtyPaths) && msg.dirtyPaths.every((p) => typeof p === "string") ? { dirtyPaths: msg.dirtyPaths } : void 0
+  initial: { dirtyPaths: [], openFiles: [], activeFile: null },
+  parse: (msg) => isStringArray(msg.dirtyPaths) ? {
+    dirtyPaths: msg.dirtyPaths,
+    // `openFiles` is newer than `dirtyPaths`; tolerate an older host that
+    // omits it (defensive SDK — defaults to empty rather than rejecting).
+    openFiles: isStringArray(msg.openFiles) ? msg.openFiles : [],
+    // `activeFile` is newer still; an older host that omits it (or sends a
+    // non-string) reads as `null` — no file highlighted, never a throw.
+    activeFile: typeof msg.activeFile === "string" ? msg.activeFile : null
+  } : void 0
 });
 const getEditorContext = () => channel.get();
 const onEditorContextChange = (listener) => channel.onChange(listener);

package/dist/editorContext.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/editorContext.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\n\n/**\n * The editor \"dirty set\" mirrored from the immediately.run host into the sandbox\n * (UI_AS_APPS_SPEC §5.3): which files the user has changed but not yet saved.\n *\n * This is the ELEVATED `editor:read` capability — only a system app whose binding\n * grants it (e.g. the contribute dialog) receives it. The active file and ref are\n * already available to every app via routing (`useNavigationState`), so this\n * channel carries only the genuine delta: the unsaved paths. An app without\n * `editor:read` simply sees an empty dirty set.\n */\nexport interface EditorContext {\n  /** Repo-relative paths the user has modified but not yet saved. */\n  dirtyPaths: string[];\n}\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `editor-context`\n// and answers `request-editor-context` — but only for a frame holding `editor:read`\n// (gated by the channel router). An app without it gets no reply, so the empty\n// default below stands. Wire format: site-main channelBridge.ts.\nconst channel = createPushChannel<EditorContext>({\n  pushType: 'editor-context',\n  requestType: 'request-editor-context',\n  initial: { dirtyPaths: [] },\n  parse: (msg) =>\n    Array.isArray(msg.dirtyPaths) && msg.dirtyPaths.every((p) => typeof p === 'string')\n      ? { dirtyPaths: msg.dirtyPaths as string[] }\n      : undefined,\n});\n\n/**\n * Returns the current editor context (dirty set). Poll this for a one-off read;\n * use {@link onEditorContextChange} or {@link useEditorContext} to react.\n */\nexport const getEditorContext = (): EditorContext => channel.get();\n\n/**\n * Subscribe to editor-context changes. The listener is invoked immediately with\n * the current context, then again on every change. Returns an unsubscribe fn.\n */\nexport const onEditorContextChange = (listener: (context: EditorContext) => void): (() => void) =>\n  channel.onChange(listener);\n\n/**\n * React hook returning the current editor context (dirty set), re-rendering when\n * it changes. Handy for a contribute dialog: `const { dirtyPaths } =\n * useEditorContext()` to show \"you'll save N files\" before calling `contribute()`.\n */\nexport const useEditorContext = (): EditorContext => channel.use();\n"],"mappings":"AAAA,SAAS,yBAAyB;AAqBlC,MAAM,UAAU,kBAAiC;AAAA,EAC/C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,EAAE,YAAY,CAAC,EAAE;AAAA,EAC1B,OAAO,CAAC,QACN,MAAM,QAAQ,IAAI,UAAU,KAAK,IAAI,WAAW,MAAM,CAAC,MAAM,OAAO,MAAM,QAAQ,IAC9E,EAAE,YAAY,IAAI,WAAuB,IACzC;AACR,CAAC;AAMM,MAAM,mBAAmB,MAAqB,QAAQ,IAAI;AAM1D,MAAM,wBAAwB,CAAC,aACpC,QAAQ,SAAS,QAAQ;AAOpB,MAAM,mBAAmB,MAAqB,QAAQ,IAAI;","names":[]}
+{"version":3,"sources":["../src/editorContext.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\n\n/**\n * The editor \"dirty set\" mirrored from the immediately.run host into the sandbox\n * (UI_AS_APPS_SPEC §5.3): which files the user has changed but not yet saved.\n *\n * This is the ELEVATED `editor:read` capability — only a system app whose binding\n * grants it (e.g. the contribute dialog) receives it. The active file and ref are\n * already available to every app via routing (`useNavigationState`), so this\n * channel carries only the genuine delta: the unsaved paths. An app without\n * `editor:read` simply sees an empty dirty set.\n */\nexport interface EditorContext {\n  /** Repo-relative paths the user has modified but not yet saved. */\n  dirtyPaths: string[];\n  /** Repo-relative paths currently open as tabs in the host editor (§4.2). */\n  openFiles: string[];\n  /**\n   * The one file currently focused in the host editor (repo-relative, leading\n   * slash — e.g. `/src/index.ts`), or `null` when no file is open. Distinct from\n   * {@link dirtyPaths} (the unsaved SET) and {@link openFiles} (the open-tab set):\n   * this is the single ACTIVE file. A baseline app reads its own active file from\n   * the route, but a self-routed system panel (`drivesHostRoute=false`, e.g. the\n   * file explorer) does not see the host editor's route, so it receives the active\n   * file here instead (UI_AS_APPS_SPEC §5.3 self-routed-panel refinement).\n   */\n  activeFile: string | null;\n}\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `editor-context`\n// and answers `request-editor-context` — but only for a frame holding `editor:read`\n// (gated by the channel router). An app without it gets no reply, so the empty\n// default below stands. Wire format: site-main channelBridge.ts.\nconst isStringArray = (v: unknown): v is string[] =>\n  Array.isArray(v) && v.every((p) => typeof p === 'string');\n\nconst channel = createPushChannel<EditorContext>({\n  pushType: 'editor-context',\n  requestType: 'request-editor-context',\n  initial: { dirtyPaths: [], openFiles: [], activeFile: null },\n  parse: (msg) =>\n    isStringArray(msg.dirtyPaths)\n      ? {\n          dirtyPaths: msg.dirtyPaths,\n          // `openFiles` is newer than `dirtyPaths`; tolerate an older host that\n          // omits it (defensive SDK — defaults to empty rather than rejecting).\n          openFiles: isStringArray(msg.openFiles) ? msg.openFiles : [],\n          // `activeFile` is newer still; an older host that omits it (or sends a\n          // non-string) reads as `null` — no file highlighted, never a throw.\n          activeFile: typeof msg.activeFile === 'string' ? msg.activeFile : null,\n        }\n      : undefined,\n});\n\n/**\n * Returns the current editor context (dirty set). Poll this for a one-off read;\n * use {@link onEditorContextChange} or {@link useEditorContext} to react.\n */\nexport const getEditorContext = (): EditorContext => channel.get();\n\n/**\n * Subscribe to editor-context changes. The listener is invoked immediately with\n * the current context, then again on every change. Returns an unsubscribe fn.\n */\nexport const onEditorContextChange = (listener: (context: EditorContext) => void): (() => void) =>\n  channel.onChange(listener);\n\n/**\n * React hook returning the current editor context (dirty set), re-rendering when\n * it changes. Handy for a contribute dialog: `const { dirtyPaths } =\n * useEditorContext()` to show \"you'll save N files\" before calling `contribute()`.\n */\nexport const useEditorContext = (): EditorContext => channel.use();\n"],"mappings":"AAAA,SAAS,yBAAyB;AAiClC,MAAM,gBAAgB,CAAC,MACrB,MAAM,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,OAAO,MAAM,QAAQ;AAE1D,MAAM,UAAU,kBAAiC;AAAA,EAC/C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS,EAAE,YAAY,CAAC,GAAG,WAAW,CAAC,GAAG,YAAY,KAAK;AAAA,EAC3D,OAAO,CAAC,QACN,cAAc,IAAI,UAAU,IACxB;AAAA,IACE,YAAY,IAAI;AAAA;AAAA;AAAA,IAGhB,WAAW,cAAc,IAAI,SAAS,IAAI,IAAI,YAAY,CAAC;AAAA;AAAA;AAAA,IAG3D,YAAY,OAAO,IAAI,eAAe,WAAW,IAAI,aAAa;AAAA,EACpE,IACA;AACR,CAAC;AAMM,MAAM,mBAAmB,MAAqB,QAAQ,IAAI;AAM1D,MAAM,wBAAwB,CAAC,aACpC,QAAQ,SAAS,QAAQ;AAOpB,MAAM,mBAAmB,MAAqB,QAAQ,IAAI;","names":[]}

package/dist/index.d.cts

@@ -7,7 +7,7 @@ export { useFileMetadata, useMetadataQuery } from './hooks.cjs';
 export { AuthState, AuthStatus, SandboxUser, getAuthState, onAuthChange, useAuth } from './auth.cjs';
 export { HostTheme, getHostTheme, onHostThemeChange, setHostTheme, useHostTheme } from './theme.cjs';
 export { EditorContext, getEditorContext, onEditorContextChange, useEditorContext } from './editorContext.cjs';
-export { EditorOpenError, openInEditor } from './editor.cjs';
+export { EditorOpenError, EditorWriteError, createFile, createFolder, deleteEntry, openInEditor, renameEntry, uploadFile } from './editor.cjs';
 export { FormFactor, FormFactorClass, Orientation, getFormFactor, onFormFactorChange, useFormFactor } from './formFactor.cjs';
 export { GrantRecord, Member, MountQuery, ResolvedUser, Role, SandboxMount, SpaceError, SpaceInfo, createSpace, findMount, getAppMountPath, getMounts, getSpaceMembers, listAllSpaces, listGrants, listSpaces, lookupUser, mount, mountSpace, onMountsChange, openAppSpace, requestMount, requestSpace, revokeGrant, setSpaceRole, shareSpace, unmountSpace, unshareSpace, useMounts, waitForMount } from './mounts.cjs';
 export { ContributeMode, ContributeOptions, ContributionEvent, ContributionResult, contribute } from './contribute.cjs';

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export { useFileMetadata, useMetadataQuery } from './hooks.js';
 export { AuthState, AuthStatus, SandboxUser, getAuthState, onAuthChange, useAuth } from './auth.js';
 export { HostTheme, getHostTheme, onHostThemeChange, setHostTheme, useHostTheme } from './theme.js';
 export { EditorContext, getEditorContext, onEditorContextChange, useEditorContext } from './editorContext.js';
-export { EditorOpenError, openInEditor } from './editor.js';
+export { EditorOpenError, EditorWriteError, createFile, createFolder, deleteEntry, openInEditor, renameEntry, uploadFile } from './editor.js';
 export { FormFactor, FormFactorClass, Orientation, getFormFactor, onFormFactorChange, useFormFactor } from './formFactor.js';
 export { GrantRecord, Member, MountQuery, ResolvedUser, Role, SandboxMount, SpaceError, SpaceInfo, createSpace, findMount, getAppMountPath, getMounts, getSpaceMembers, listAllSpaces, listGrants, listSpaces, lookupUser, mount, mountSpace, onMountsChange, openAppSpace, requestMount, requestSpace, revokeGrant, setSpaceRole, shareSpace, unmountSpace, unshareSpace, useMounts, waitForMount } from './mounts.js';
 export { ContributeMode, ContributeOptions, ContributionEvent, ContributionResult, contribute } from './contribute.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immediately-run/sdk",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Runtime SDK for code executing inside an immediately.run sandbox.",
   "license": "MIT",
   "repository": "github:immediately-run/immediately-run-sdk",