@immediately-run/sdk 0.1.5 → 0.2.0

package/dist/contribute.cjs

@@ -0,0 +1,32 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var contribute_exports = {};
+__export(contribute_exports, {
+  contribute: () => contribute
+});
+module.exports = __toCommonJS(contribute_exports);
+var import_protocolStream = require("./protocolStream");
+function contribute(opts) {
+  return (0, import_protocolStream.protocolStream)("protocol-contribute", "run", [opts]);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  contribute
+});
+//# sourceMappingURL=contribute.cjs.map

package/dist/contribute.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/contribute.ts"],"sourcesContent":["// Contribute — stream a save (PR or direct commit) from app code\n// (UI_AS_APPS_SPEC §5.1, CONTRIBUTE_SPEC). The host runs the *existing*\n// contribution orchestrator and streams its stages back; this is the typed\n// front door over `protocolStream`.\n//\n// The OAuth token never reaches here — it stays on the host. The app passes a\n// commit message + save mode and watches stages go by; the host owns the token,\n// the GitHub API calls, and the user-facing consent.\nimport { protocolStream } from './protocolStream';\n\n/** The save strategy. `direct` requires the first-party `contribute:direct`\n *  capability and a scarier consent line — a `contribute:any` app asking for it\n *  is REJECTED (`forbidden`), never silently downgraded to a PR (threat T11). */\nexport type ContributeMode = 'pr' | 'direct';\n\n/** A stage emitted as the contribution runs. Mirrors the host orchestrator's\n *  event union; carries progress metadata only — never the token or file blobs. */\nexport type ContributionEvent =\n  | { stage: 'auth-check' }\n  | { stage: 'diff-compute' }\n  | { stage: 'permission-check' }\n  | { stage: 'install-required'; targetOwner: string; targetRepo: string; installUrl: string }\n  | { stage: 'conflict-check' }\n  | { stage: 'fork-prepare'; forkOwner: string; alreadyExists: boolean }\n  | { stage: 'upload-blob'; path: string; index: number; total: number }\n  | { stage: 'create-tree' }\n  | { stage: 'create-commit' }\n  | { stage: 'create-branch'; branchName: string }\n  | { stage: 'create-pr' }\n  | { stage: 'pr-updated'; prNumber: number; prUrl: string; commitSha: string }\n  | { stage: 'commit-pushed'; ref: string; commitSha: string }\n  | { stage: 'switch-branch'; provider: 'github'; pushOwner: string; repository: string; branchName: string }\n  | { stage: 'done'; prUrl?: string; prNumber?: number; commitSha: string }\n  | { stage: 'warning'; message: string; details?: unknown }\n  | { stage: 'error'; message: string; recoverable: boolean };\n\n/** The settled outcome (the stream's return value). */\nexport interface ContributionResult {\n  prUrl?: string;\n  prNumber?: number;\n  commitSha: string;\n  treeSha: string;\n  branchName: string;\n  mode: 'direct-commit' | 'new-branch-pr' | 'extend-existing';\n}\n\nexport interface ContributeOptions {\n  /** The commit message / PR title. */\n  commitMessage: string;\n  /** `'pr'` (default) opens a PR; `'direct'` commits to the branch and needs\n   *  the first-party `contribute:direct` capability. */\n  mode?: ContributeMode;\n  /** Override the generated branch name (PR mode). */\n  branchName?: string;\n}\n\n/**\n * Save the current working tree, streaming each stage.\n *\n * ```ts\n * for await (const ev of contribute({ commitMessage: 'Edit post' })) {\n *   if (ev.stage === 'done') console.log(ev.prUrl);\n * }\n * ```\n *\n * Yields {@link ContributionEvent}s and returns a {@link ContributionResult}.\n * Throws a `StreamError` (`.code`) if the host rejects the request — notably\n * `forbidden` when a `contribute:any` app asks for `mode: 'direct'` (T11).\n */\nexport function contribute(\n  opts: ContributeOptions\n): AsyncGenerator<ContributionEvent, ContributionResult, void> {\n  return protocolStream<ContributionEvent, ContributionResult>('protocol-contribute', 'run', [opts]);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAQA,4BAA+B;AA6DxB,SAAS,WACd,MAC6D;AAC7D,aAAO,sCAAsD,uBAAuB,OAAO,CAAC,IAAI,CAAC;AACnG;","names":[]}

package/dist/contribute.d.cts

@@ -0,0 +1,100 @@
+/** The save strategy. `direct` requires the first-party `contribute:direct`
+ *  capability and a scarier consent line — a `contribute:any` app asking for it
+ *  is REJECTED (`forbidden`), never silently downgraded to a PR (threat T11). */
+type ContributeMode = 'pr' | 'direct';
+/** A stage emitted as the contribution runs. Mirrors the host orchestrator's
+ *  event union; carries progress metadata only — never the token or file blobs. */
+type ContributionEvent = {
+    stage: 'auth-check';
+} | {
+    stage: 'diff-compute';
+} | {
+    stage: 'permission-check';
+} | {
+    stage: 'install-required';
+    targetOwner: string;
+    targetRepo: string;
+    installUrl: string;
+} | {
+    stage: 'conflict-check';
+} | {
+    stage: 'fork-prepare';
+    forkOwner: string;
+    alreadyExists: boolean;
+} | {
+    stage: 'upload-blob';
+    path: string;
+    index: number;
+    total: number;
+} | {
+    stage: 'create-tree';
+} | {
+    stage: 'create-commit';
+} | {
+    stage: 'create-branch';
+    branchName: string;
+} | {
+    stage: 'create-pr';
+} | {
+    stage: 'pr-updated';
+    prNumber: number;
+    prUrl: string;
+    commitSha: string;
+} | {
+    stage: 'commit-pushed';
+    ref: string;
+    commitSha: string;
+} | {
+    stage: 'switch-branch';
+    provider: 'github';
+    pushOwner: string;
+    repository: string;
+    branchName: string;
+} | {
+    stage: 'done';
+    prUrl?: string;
+    prNumber?: number;
+    commitSha: string;
+} | {
+    stage: 'warning';
+    message: string;
+    details?: unknown;
+} | {
+    stage: 'error';
+    message: string;
+    recoverable: boolean;
+};
+/** The settled outcome (the stream's return value). */
+interface ContributionResult {
+    prUrl?: string;
+    prNumber?: number;
+    commitSha: string;
+    treeSha: string;
+    branchName: string;
+    mode: 'direct-commit' | 'new-branch-pr' | 'extend-existing';
+}
+interface ContributeOptions {
+    /** The commit message / PR title. */
+    commitMessage: string;
+    /** `'pr'` (default) opens a PR; `'direct'` commits to the branch and needs
+     *  the first-party `contribute:direct` capability. */
+    mode?: ContributeMode;
+    /** Override the generated branch name (PR mode). */
+    branchName?: string;
+}
+/**
+ * Save the current working tree, streaming each stage.
+ *
+ * ```ts
+ * for await (const ev of contribute({ commitMessage: 'Edit post' })) {
+ *   if (ev.stage === 'done') console.log(ev.prUrl);
+ * }
+ * ```
+ *
+ * Yields {@link ContributionEvent}s and returns a {@link ContributionResult}.
+ * Throws a `StreamError` (`.code`) if the host rejects the request — notably
+ * `forbidden` when a `contribute:any` app asks for `mode: 'direct'` (T11).
+ */
+declare function contribute(opts: ContributeOptions): AsyncGenerator<ContributionEvent, ContributionResult, void>;
+
+export { type ContributeMode, type ContributeOptions, type ContributionEvent, type ContributionResult, contribute };

package/dist/contribute.d.ts

@@ -0,0 +1,100 @@
+/** The save strategy. `direct` requires the first-party `contribute:direct`
+ *  capability and a scarier consent line — a `contribute:any` app asking for it
+ *  is REJECTED (`forbidden`), never silently downgraded to a PR (threat T11). */
+type ContributeMode = 'pr' | 'direct';
+/** A stage emitted as the contribution runs. Mirrors the host orchestrator's
+ *  event union; carries progress metadata only — never the token or file blobs. */
+type ContributionEvent = {
+    stage: 'auth-check';
+} | {
+    stage: 'diff-compute';
+} | {
+    stage: 'permission-check';
+} | {
+    stage: 'install-required';
+    targetOwner: string;
+    targetRepo: string;
+    installUrl: string;
+} | {
+    stage: 'conflict-check';
+} | {
+    stage: 'fork-prepare';
+    forkOwner: string;
+    alreadyExists: boolean;
+} | {
+    stage: 'upload-blob';
+    path: string;
+    index: number;
+    total: number;
+} | {
+    stage: 'create-tree';
+} | {
+    stage: 'create-commit';
+} | {
+    stage: 'create-branch';
+    branchName: string;
+} | {
+    stage: 'create-pr';
+} | {
+    stage: 'pr-updated';
+    prNumber: number;
+    prUrl: string;
+    commitSha: string;
+} | {
+    stage: 'commit-pushed';
+    ref: string;
+    commitSha: string;
+} | {
+    stage: 'switch-branch';
+    provider: 'github';
+    pushOwner: string;
+    repository: string;
+    branchName: string;
+} | {
+    stage: 'done';
+    prUrl?: string;
+    prNumber?: number;
+    commitSha: string;
+} | {
+    stage: 'warning';
+    message: string;
+    details?: unknown;
+} | {
+    stage: 'error';
+    message: string;
+    recoverable: boolean;
+};
+/** The settled outcome (the stream's return value). */
+interface ContributionResult {
+    prUrl?: string;
+    prNumber?: number;
+    commitSha: string;
+    treeSha: string;
+    branchName: string;
+    mode: 'direct-commit' | 'new-branch-pr' | 'extend-existing';
+}
+interface ContributeOptions {
+    /** The commit message / PR title. */
+    commitMessage: string;
+    /** `'pr'` (default) opens a PR; `'direct'` commits to the branch and needs
+     *  the first-party `contribute:direct` capability. */
+    mode?: ContributeMode;
+    /** Override the generated branch name (PR mode). */
+    branchName?: string;
+}
+/**
+ * Save the current working tree, streaming each stage.
+ *
+ * ```ts
+ * for await (const ev of contribute({ commitMessage: 'Edit post' })) {
+ *   if (ev.stage === 'done') console.log(ev.prUrl);
+ * }
+ * ```
+ *
+ * Yields {@link ContributionEvent}s and returns a {@link ContributionResult}.
+ * Throws a `StreamError` (`.code`) if the host rejects the request — notably
+ * `forbidden` when a `contribute:any` app asks for `mode: 'direct'` (T11).
+ */
+declare function contribute(opts: ContributeOptions): AsyncGenerator<ContributionEvent, ContributionResult, void>;
+
+export { type ContributeMode, type ContributeOptions, type ContributionEvent, type ContributionResult, contribute };

package/dist/contribute.js

@@ -0,0 +1,8 @@
+import { protocolStream } from "./protocolStream";
+function contribute(opts) {
+  return protocolStream("protocol-contribute", "run", [opts]);
+}
+export {
+  contribute
+};
+//# sourceMappingURL=contribute.js.map

package/dist/contribute.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/contribute.ts"],"sourcesContent":["// Contribute — stream a save (PR or direct commit) from app code\n// (UI_AS_APPS_SPEC §5.1, CONTRIBUTE_SPEC). The host runs the *existing*\n// contribution orchestrator and streams its stages back; this is the typed\n// front door over `protocolStream`.\n//\n// The OAuth token never reaches here — it stays on the host. The app passes a\n// commit message + save mode and watches stages go by; the host owns the token,\n// the GitHub API calls, and the user-facing consent.\nimport { protocolStream } from './protocolStream';\n\n/** The save strategy. `direct` requires the first-party `contribute:direct`\n *  capability and a scarier consent line — a `contribute:any` app asking for it\n *  is REJECTED (`forbidden`), never silently downgraded to a PR (threat T11). */\nexport type ContributeMode = 'pr' | 'direct';\n\n/** A stage emitted as the contribution runs. Mirrors the host orchestrator's\n *  event union; carries progress metadata only — never the token or file blobs. */\nexport type ContributionEvent =\n  | { stage: 'auth-check' }\n  | { stage: 'diff-compute' }\n  | { stage: 'permission-check' }\n  | { stage: 'install-required'; targetOwner: string; targetRepo: string; installUrl: string }\n  | { stage: 'conflict-check' }\n  | { stage: 'fork-prepare'; forkOwner: string; alreadyExists: boolean }\n  | { stage: 'upload-blob'; path: string; index: number; total: number }\n  | { stage: 'create-tree' }\n  | { stage: 'create-commit' }\n  | { stage: 'create-branch'; branchName: string }\n  | { stage: 'create-pr' }\n  | { stage: 'pr-updated'; prNumber: number; prUrl: string; commitSha: string }\n  | { stage: 'commit-pushed'; ref: string; commitSha: string }\n  | { stage: 'switch-branch'; provider: 'github'; pushOwner: string; repository: string; branchName: string }\n  | { stage: 'done'; prUrl?: string; prNumber?: number; commitSha: string }\n  | { stage: 'warning'; message: string; details?: unknown }\n  | { stage: 'error'; message: string; recoverable: boolean };\n\n/** The settled outcome (the stream's return value). */\nexport interface ContributionResult {\n  prUrl?: string;\n  prNumber?: number;\n  commitSha: string;\n  treeSha: string;\n  branchName: string;\n  mode: 'direct-commit' | 'new-branch-pr' | 'extend-existing';\n}\n\nexport interface ContributeOptions {\n  /** The commit message / PR title. */\n  commitMessage: string;\n  /** `'pr'` (default) opens a PR; `'direct'` commits to the branch and needs\n   *  the first-party `contribute:direct` capability. */\n  mode?: ContributeMode;\n  /** Override the generated branch name (PR mode). */\n  branchName?: string;\n}\n\n/**\n * Save the current working tree, streaming each stage.\n *\n * ```ts\n * for await (const ev of contribute({ commitMessage: 'Edit post' })) {\n *   if (ev.stage === 'done') console.log(ev.prUrl);\n * }\n * ```\n *\n * Yields {@link ContributionEvent}s and returns a {@link ContributionResult}.\n * Throws a `StreamError` (`.code`) if the host rejects the request — notably\n * `forbidden` when a `contribute:any` app asks for `mode: 'direct'` (T11).\n */\nexport function contribute(\n  opts: ContributeOptions\n): AsyncGenerator<ContributionEvent, ContributionResult, void> {\n  return protocolStream<ContributionEvent, ContributionResult>('protocol-contribute', 'run', [opts]);\n}\n"],"mappings":"AAQA,SAAS,sBAAsB;AA6DxB,SAAS,WACd,MAC6D;AAC7D,SAAO,eAAsD,uBAAuB,OAAO,CAAC,IAAI,CAAC;AACnG;","names":[]}

package/dist/editorContext.cjs

@@ -0,0 +1,46 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var editorContext_exports = {};
+__export(editorContext_exports, {
+  getEditorContext: () => getEditorContext,
+  onEditorContextChange: () => onEditorContextChange,
+  useEditorContext: () => useEditorContext
+});
+module.exports = __toCommonJS(editorContext_exports);
+var import_react = require("react");
+const editorContextService = () => {
+  return module.evaluation.module.bundler.editorContext;
+};
+const getEditorContext = () => editorContextService().getContext();
+const onEditorContextChange = (listener) => {
+  const disposable = editorContextService().onChange(listener);
+  return () => disposable.dispose();
+};
+const useEditorContext = () => {
+  const [context, setContext] = (0, import_react.useState)(getEditorContext);
+  (0, import_react.useEffect)(() => onEditorContextChange(setContext), []);
+  return context;
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getEditorContext,
+  onEditorContextChange,
+  useEditorContext
+});
+//# sourceMappingURL=editorContext.cjs.map

package/dist/editorContext.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/editorContext.ts"],"sourcesContent":["import { useEffect, useState } from 'react';\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\ninterface EditorContextService {\n  getContext(): EditorContext;\n  onChange(listener: (context: EditorContext) => void): { dispose(): void };\n}\n\n// `module.evaluation.module.bundler.editorContext` is the sandbox bundler service\n// injected into the evaluation context (same path the other SDK helpers use).\nconst editorContextService = (): EditorContextService => {\n  // @ts-ignore - injected by the sandbox runtime\n  return module.evaluation.module.bundler.editorContext;\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 => editorContextService().getContext();\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 = (\n  listener: (context: EditorContext) => void,\n): (() => void) => {\n  const disposable = editorContextService().onChange(listener);\n  return () => disposable.dispose();\n};\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 => {\n  const [context, setContext] = useState<EditorContext>(getEditorContext);\n  useEffect(() => onEditorContextChange(setContext), []);\n  return context;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mBAAoC;AAwBpC,MAAM,uBAAuB,MAA4B;AAEvD,SAAO,OAAO,WAAW,OAAO,QAAQ;AAC1C;AAMO,MAAM,mBAAmB,MAAqB,qBAAqB,EAAE,WAAW;AAMhF,MAAM,wBAAwB,CACnC,aACiB;AACjB,QAAM,aAAa,qBAAqB,EAAE,SAAS,QAAQ;AAC3D,SAAO,MAAM,WAAW,QAAQ;AAClC;AAOO,MAAM,mBAAmB,MAAqB;AACnD,QAAM,CAAC,SAAS,UAAU,QAAI,uBAAwB,gBAAgB;AACtE,8BAAU,MAAM,sBAAsB,UAAU,GAAG,CAAC,CAAC;AACrD,SAAO;AACT;","names":[]}

package/dist/editorContext.d.cts

@@ -0,0 +1,32 @@
+/**
+ * The editor "dirty set" mirrored from the immediately.run host into the sandbox
+ * (UI_AS_APPS_SPEC §5.3): which files the user has changed but not yet saved.
+ *
+ * This is the ELEVATED `editor:read` capability — only a system app whose binding
+ * grants it (e.g. the contribute dialog) receives it. The active file and ref are
+ * already available to every app via routing (`useNavigationState`), so this
+ * channel carries only the genuine delta: the unsaved paths. An app without
+ * `editor:read` simply sees an empty dirty set.
+ */
+interface EditorContext {
+    /** Repo-relative paths the user has modified but not yet saved. */
+    dirtyPaths: string[];
+}
+/**
+ * Returns the current editor context (dirty set). Poll this for a one-off read;
+ * use {@link onEditorContextChange} or {@link useEditorContext} to react.
+ */
+declare const getEditorContext: () => EditorContext;
+/**
+ * Subscribe to editor-context changes. The listener is invoked immediately with
+ * the current context, then again on every change. Returns an unsubscribe fn.
+ */
+declare const onEditorContextChange: (listener: (context: EditorContext) => void) => (() => void);
+/**
+ * React hook returning the current editor context (dirty set), re-rendering when
+ * it changes. Handy for a contribute dialog: `const { dirtyPaths } =
+ * useEditorContext()` to show "you'll save N files" before calling `contribute()`.
+ */
+declare const useEditorContext: () => EditorContext;
+
+export { type EditorContext, getEditorContext, onEditorContextChange, useEditorContext };

package/dist/editorContext.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The editor "dirty set" mirrored from the immediately.run host into the sandbox
+ * (UI_AS_APPS_SPEC §5.3): which files the user has changed but not yet saved.
+ *
+ * This is the ELEVATED `editor:read` capability — only a system app whose binding
+ * grants it (e.g. the contribute dialog) receives it. The active file and ref are
+ * already available to every app via routing (`useNavigationState`), so this
+ * channel carries only the genuine delta: the unsaved paths. An app without
+ * `editor:read` simply sees an empty dirty set.
+ */
+interface EditorContext {
+    /** Repo-relative paths the user has modified but not yet saved. */
+    dirtyPaths: string[];
+}
+/**
+ * Returns the current editor context (dirty set). Poll this for a one-off read;
+ * use {@link onEditorContextChange} or {@link useEditorContext} to react.
+ */
+declare const getEditorContext: () => EditorContext;
+/**
+ * Subscribe to editor-context changes. The listener is invoked immediately with
+ * the current context, then again on every change. Returns an unsubscribe fn.
+ */
+declare const onEditorContextChange: (listener: (context: EditorContext) => void) => (() => void);
+/**
+ * React hook returning the current editor context (dirty set), re-rendering when
+ * it changes. Handy for a contribute dialog: `const { dirtyPaths } =
+ * useEditorContext()` to show "you'll save N files" before calling `contribute()`.
+ */
+declare const useEditorContext: () => EditorContext;
+
+export { type EditorContext, getEditorContext, onEditorContextChange, useEditorContext };

package/dist/editorContext.js

@@ -0,0 +1,20 @@
+import { useEffect, useState } from "react";
+const editorContextService = () => {
+  return module.evaluation.module.bundler.editorContext;
+};
+const getEditorContext = () => editorContextService().getContext();
+const onEditorContextChange = (listener) => {
+  const disposable = editorContextService().onChange(listener);
+  return () => disposable.dispose();
+};
+const useEditorContext = () => {
+  const [context, setContext] = useState(getEditorContext);
+  useEffect(() => onEditorContextChange(setContext), []);
+  return context;
+};
+export {
+  getEditorContext,
+  onEditorContextChange,
+  useEditorContext
+};
+//# sourceMappingURL=editorContext.js.map

package/dist/editorContext.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/editorContext.ts"],"sourcesContent":["import { useEffect, useState } from 'react';\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\ninterface EditorContextService {\n  getContext(): EditorContext;\n  onChange(listener: (context: EditorContext) => void): { dispose(): void };\n}\n\n// `module.evaluation.module.bundler.editorContext` is the sandbox bundler service\n// injected into the evaluation context (same path the other SDK helpers use).\nconst editorContextService = (): EditorContextService => {\n  // @ts-ignore - injected by the sandbox runtime\n  return module.evaluation.module.bundler.editorContext;\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 => editorContextService().getContext();\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 = (\n  listener: (context: EditorContext) => void,\n): (() => void) => {\n  const disposable = editorContextService().onChange(listener);\n  return () => disposable.dispose();\n};\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 => {\n  const [context, setContext] = useState<EditorContext>(getEditorContext);\n  useEffect(() => onEditorContextChange(setContext), []);\n  return context;\n};\n"],"mappings":"AAAA,SAAS,WAAW,gBAAgB;AAwBpC,MAAM,uBAAuB,MAA4B;AAEvD,SAAO,OAAO,WAAW,OAAO,QAAQ;AAC1C;AAMO,MAAM,mBAAmB,MAAqB,qBAAqB,EAAE,WAAW;AAMhF,MAAM,wBAAwB,CACnC,aACiB;AACjB,QAAM,aAAa,qBAAqB,EAAE,SAAS,QAAQ;AAC3D,SAAO,MAAM,WAAW,QAAQ;AAClC;AAOO,MAAM,mBAAmB,MAAqB;AACnD,QAAM,CAAC,SAAS,UAAU,IAAI,SAAwB,gBAAgB;AACtE,YAAU,MAAM,sBAAsB,UAAU,GAAG,CAAC,CAAC;AACrD,SAAO;AACT;","names":[]}

package/dist/formFactor.cjs

@@ -0,0 +1,46 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var formFactor_exports = {};
+__export(formFactor_exports, {
+  getFormFactor: () => getFormFactor,
+  onFormFactorChange: () => onFormFactorChange,
+  useFormFactor: () => useFormFactor
+});
+module.exports = __toCommonJS(formFactor_exports);
+var import_react = require("react");
+const formFactorService = () => {
+  return module.evaluation.module.bundler.formFactor;
+};
+const getFormFactor = () => formFactorService().getFormFactor();
+const onFormFactorChange = (listener) => {
+  const disposable = formFactorService().onChange(listener);
+  return () => disposable.dispose();
+};
+const useFormFactor = () => {
+  const [ff, setFf] = (0, import_react.useState)(getFormFactor);
+  (0, import_react.useEffect)(() => onFormFactorChange(setFf), []);
+  return ff;
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getFormFactor,
+  onFormFactorChange,
+  useFormFactor
+});
+//# sourceMappingURL=formFactor.cjs.map

package/dist/formFactor.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/formFactor.ts"],"sourcesContent":["import { useEffect, useState } from 'react';\n\n/**\n * The form factor of the surface your app is rendered into, mirrored from the\n * immediately.run host (UI_AS_APPS_SPEC §5.4.1). Read this to lay out\n * responsively — a narrow chrome panel, a full preview, or a mobile carousel\n * pane all report their box here. The host is the source of truth (it owns the\n * region); you cannot reliably measure your own viewport across the sandbox\n * boundary.\n *\n * Baseline capability `formFactor:read` — every app may read it.\n */\nexport type FormFactorClass = 'mobile' | 'tablet' | 'desktop';\nexport type Orientation = 'portrait' | 'landscape';\n\nexport interface FormFactor {\n  class: FormFactorClass;\n  orientation: Orientation;\n  width: number;\n  height: number;\n}\n\ninterface FormFactorService {\n  getFormFactor(): FormFactor;\n  onChange(listener: (formFactor: FormFactor) => void): { dispose(): void };\n}\n\nconst formFactorService = (): FormFactorService => {\n  // @ts-ignore - injected by the sandbox runtime\n  return module.evaluation.module.bundler.formFactor;\n};\n\n/** Returns the current form factor. Poll for a one-off read. */\nexport const getFormFactor = (): FormFactor =>\n  formFactorService().getFormFactor();\n\n/**\n * Subscribe to form-factor changes. The listener is invoked immediately with\n * the current value, then again on every change. Returns an unsubscribe fn.\n */\nexport const onFormFactorChange = (\n  listener: (formFactor: FormFactor) => void,\n): (() => void) => {\n  const disposable = formFactorService().onChange(listener);\n  return () => disposable.dispose();\n};\n\n/** React hook returning the current form factor, re-rendering on change. */\nexport const useFormFactor = (): FormFactor => {\n  const [ff, setFf] = useState<FormFactor>(getFormFactor);\n  useEffect(() => onFormFactorChange(setFf), []);\n  return ff;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mBAAoC;AA2BpC,MAAM,oBAAoB,MAAyB;AAEjD,SAAO,OAAO,WAAW,OAAO,QAAQ;AAC1C;AAGO,MAAM,gBAAgB,MAC3B,kBAAkB,EAAE,cAAc;AAM7B,MAAM,qBAAqB,CAChC,aACiB;AACjB,QAAM,aAAa,kBAAkB,EAAE,SAAS,QAAQ;AACxD,SAAO,MAAM,WAAW,QAAQ;AAClC;AAGO,MAAM,gBAAgB,MAAkB;AAC7C,QAAM,CAAC,IAAI,KAAK,QAAI,uBAAqB,aAAa;AACtD,8BAAU,MAAM,mBAAmB,KAAK,GAAG,CAAC,CAAC;AAC7C,SAAO;AACT;","names":[]}

package/dist/formFactor.d.cts

@@ -0,0 +1,29 @@
+/**
+ * The form factor of the surface your app is rendered into, mirrored from the
+ * immediately.run host (UI_AS_APPS_SPEC §5.4.1). Read this to lay out
+ * responsively — a narrow chrome panel, a full preview, or a mobile carousel
+ * pane all report their box here. The host is the source of truth (it owns the
+ * region); you cannot reliably measure your own viewport across the sandbox
+ * boundary.
+ *
+ * Baseline capability `formFactor:read` — every app may read it.
+ */
+type FormFactorClass = 'mobile' | 'tablet' | 'desktop';
+type Orientation = 'portrait' | 'landscape';
+interface FormFactor {
+    class: FormFactorClass;
+    orientation: Orientation;
+    width: number;
+    height: number;
+}
+/** Returns the current form factor. Poll for a one-off read. */
+declare const getFormFactor: () => FormFactor;
+/**
+ * Subscribe to form-factor changes. The listener is invoked immediately with
+ * the current value, then again on every change. Returns an unsubscribe fn.
+ */
+declare const onFormFactorChange: (listener: (formFactor: FormFactor) => void) => (() => void);
+/** React hook returning the current form factor, re-rendering on change. */
+declare const useFormFactor: () => FormFactor;
+
+export { type FormFactor, type FormFactorClass, type Orientation, getFormFactor, onFormFactorChange, useFormFactor };

package/dist/formFactor.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The form factor of the surface your app is rendered into, mirrored from the
+ * immediately.run host (UI_AS_APPS_SPEC §5.4.1). Read this to lay out
+ * responsively — a narrow chrome panel, a full preview, or a mobile carousel
+ * pane all report their box here. The host is the source of truth (it owns the
+ * region); you cannot reliably measure your own viewport across the sandbox
+ * boundary.
+ *
+ * Baseline capability `formFactor:read` — every app may read it.
+ */
+type FormFactorClass = 'mobile' | 'tablet' | 'desktop';
+type Orientation = 'portrait' | 'landscape';
+interface FormFactor {
+    class: FormFactorClass;
+    orientation: Orientation;
+    width: number;
+    height: number;
+}
+/** Returns the current form factor. Poll for a one-off read. */
+declare const getFormFactor: () => FormFactor;
+/**
+ * Subscribe to form-factor changes. The listener is invoked immediately with
+ * the current value, then again on every change. Returns an unsubscribe fn.
+ */
+declare const onFormFactorChange: (listener: (formFactor: FormFactor) => void) => (() => void);
+/** React hook returning the current form factor, re-rendering on change. */
+declare const useFormFactor: () => FormFactor;
+
+export { type FormFactor, type FormFactorClass, type Orientation, getFormFactor, onFormFactorChange, useFormFactor };

package/dist/formFactor.js

@@ -0,0 +1,20 @@
+import { useEffect, useState } from "react";
+const formFactorService = () => {
+  return module.evaluation.module.bundler.formFactor;
+};
+const getFormFactor = () => formFactorService().getFormFactor();
+const onFormFactorChange = (listener) => {
+  const disposable = formFactorService().onChange(listener);
+  return () => disposable.dispose();
+};
+const useFormFactor = () => {
+  const [ff, setFf] = useState(getFormFactor);
+  useEffect(() => onFormFactorChange(setFf), []);
+  return ff;
+};
+export {
+  getFormFactor,
+  onFormFactorChange,
+  useFormFactor
+};
+//# sourceMappingURL=formFactor.js.map

package/dist/formFactor.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/formFactor.ts"],"sourcesContent":["import { useEffect, useState } from 'react';\n\n/**\n * The form factor of the surface your app is rendered into, mirrored from the\n * immediately.run host (UI_AS_APPS_SPEC §5.4.1). Read this to lay out\n * responsively — a narrow chrome panel, a full preview, or a mobile carousel\n * pane all report their box here. The host is the source of truth (it owns the\n * region); you cannot reliably measure your own viewport across the sandbox\n * boundary.\n *\n * Baseline capability `formFactor:read` — every app may read it.\n */\nexport type FormFactorClass = 'mobile' | 'tablet' | 'desktop';\nexport type Orientation = 'portrait' | 'landscape';\n\nexport interface FormFactor {\n  class: FormFactorClass;\n  orientation: Orientation;\n  width: number;\n  height: number;\n}\n\ninterface FormFactorService {\n  getFormFactor(): FormFactor;\n  onChange(listener: (formFactor: FormFactor) => void): { dispose(): void };\n}\n\nconst formFactorService = (): FormFactorService => {\n  // @ts-ignore - injected by the sandbox runtime\n  return module.evaluation.module.bundler.formFactor;\n};\n\n/** Returns the current form factor. Poll for a one-off read. */\nexport const getFormFactor = (): FormFactor =>\n  formFactorService().getFormFactor();\n\n/**\n * Subscribe to form-factor changes. The listener is invoked immediately with\n * the current value, then again on every change. Returns an unsubscribe fn.\n */\nexport const onFormFactorChange = (\n  listener: (formFactor: FormFactor) => void,\n): (() => void) => {\n  const disposable = formFactorService().onChange(listener);\n  return () => disposable.dispose();\n};\n\n/** React hook returning the current form factor, re-rendering on change. */\nexport const useFormFactor = (): FormFactor => {\n  const [ff, setFf] = useState<FormFactor>(getFormFactor);\n  useEffect(() => onFormFactorChange(setFf), []);\n  return ff;\n};\n"],"mappings":"AAAA,SAAS,WAAW,gBAAgB;AA2BpC,MAAM,oBAAoB,MAAyB;AAEjD,SAAO,OAAO,WAAW,OAAO,QAAQ;AAC1C;AAGO,MAAM,gBAAgB,MAC3B,kBAAkB,EAAE,cAAc;AAM7B,MAAM,qBAAqB,CAChC,aACiB;AACjB,QAAM,aAAa,kBAAkB,EAAE,SAAS,QAAQ;AACxD,SAAO,MAAM,WAAW,QAAQ;AAClC;AAGO,MAAM,gBAAgB,MAAkB;AAC7C,QAAM,CAAC,IAAI,KAAK,IAAI,SAAqB,aAAa;AACtD,YAAU,MAAM,mBAAmB,KAAK,GAAG,CAAC,CAAC;AAC7C,SAAO;AACT;","names":[]}

package/dist/index.cjs

@@ -22,7 +22,12 @@ __reExport(index_exports, require("./components/Include"), module.exports);
 __reExport(index_exports, require("./components/MDXComponents"), module.exports);
 __reExport(index_exports, require("./hooks"), module.exports);
 __reExport(index_exports, require("./auth"), module.exports);
+__reExport(index_exports, require("./theme"), module.exports);
+__reExport(index_exports, require("./editorContext"), module.exports);
+__reExport(index_exports, require("./formFactor"), module.exports);
 __reExport(index_exports, require("./mounts"), module.exports);
+__reExport(index_exports, require("./contribute"), module.exports);
+__reExport(index_exports, require("./protocolStream"), module.exports);
 __reExport(index_exports, require("./sandboxTypes"), module.exports);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
@@ -33,7 +38,12 @@ __reExport(index_exports, require("./sandboxTypes"), module.exports);
   ...require("./components/MDXComponents"),
   ...require("./hooks"),
   ...require("./auth"),
+  ...require("./theme"),
+  ...require("./editorContext"),
+  ...require("./formFactor"),
   ...require("./mounts"),
+  ...require("./contribute"),
+  ...require("./protocolStream"),
   ...require("./sandboxTypes")
 });
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\nexport * from './components/MDXComponents';\nexport * from './hooks'\nexport * from './auth';\nexport * from './mounts';\nexport * from './sandboxTypes';\n"],"mappings":";;;;;;;;;;;;;;;AAAA;AAAA;AAAA,0BAAc,0BAAd;AACA,0BAAc,sBADd;AAEA,0BAAc,mBAFd;AAGA,0BAAc,iCAHd;AAIA,0BAAc,uCAJd;AAKA,0BAAc,oBALd;AAMA,0BAAc,mBANd;AAOA,0BAAc,qBAPd;AAQA,0BAAc,2BARd;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\nexport * from './components/MDXComponents';\nexport * from './hooks'\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './formFactor';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './protocolStream';\nexport * from './sandboxTypes';\n"],"mappings":";;;;;;;;;;;;;;;AAAA;AAAA;AAAA,0BAAc,0BAAd;AACA,0BAAc,sBADd;AAEA,0BAAc,mBAFd;AAGA,0BAAc,iCAHd;AAIA,0BAAc,uCAJd;AAKA,0BAAc,oBALd;AAMA,0BAAc,mBANd;AAOA,0BAAc,oBAPd;AAQA,0BAAc,4BARd;AASA,0BAAc,yBATd;AAUA,0BAAc,qBAVd;AAWA,0BAAc,yBAXd;AAYA,0BAAc,6BAZd;AAaA,0BAAc,2BAbd;","names":[]}

package/dist/index.d.cts

@@ -5,7 +5,12 @@ export { Include, RenderExportedComponent, RenderExportedComponentContext, Rende
 export { DEFAULT_MDX_COMPONENTS, InternalLink, Link } from './components/MDXComponents.cjs';
 export { useFileMetadata, useMetadataQuery } from './hooks.cjs';
 export { AuthState, AuthStatus, SandboxUser, getAuthState, onAuthChange, useAuth } from './auth.cjs';
-export { MountQuery, SandboxMount, SpaceError, SpaceInfo, createSpace, findMount, getMounts, listSpaces, mountSpace, onMountsChange, openAppSpace, unmountSpace, useMounts, waitForMount } from './mounts.cjs';
+export { HostTheme, getHostTheme, onHostThemeChange, setHostTheme, useHostTheme } from './theme.cjs';
+export { EditorContext, getEditorContext, onEditorContextChange, useEditorContext } from './editorContext.cjs';
+export { FormFactor, FormFactorClass, Orientation, getFormFactor, onFormFactorChange, useFormFactor } from './formFactor.cjs';
+export { MountQuery, SandboxMount, SpaceError, SpaceInfo, createSpace, findMount, getMounts, listSpaces, mount, mountSpace, onMountsChange, openAppSpace, requestMount, requestSpace, unmountSpace, useMounts, waitForMount } from './mounts.cjs';
+export { ContributeMode, ContributeOptions, ContributionEvent, ContributionResult, contribute } from './contribute.cjs';
+export { StreamError, StreamFrame, StreamTransport, consumeStream, protocolStream } from './protocolStream.cjs';
 export { EvaluationContext, FileQueryResult, FilesMetadata, Metadata, MetadataQueryFunction, MetadataQueryResult, ModuleExports } from './sandboxTypes.cjs';
 import 'react';
 import './TinkerableContext.cjs';

package/dist/index.d.ts

@@ -5,7 +5,12 @@ export { Include, RenderExportedComponent, RenderExportedComponentContext, Rende
 export { DEFAULT_MDX_COMPONENTS, InternalLink, Link } from './components/MDXComponents.js';
 export { useFileMetadata, useMetadataQuery } from './hooks.js';
 export { AuthState, AuthStatus, SandboxUser, getAuthState, onAuthChange, useAuth } from './auth.js';
-export { MountQuery, SandboxMount, SpaceError, SpaceInfo, createSpace, findMount, getMounts, listSpaces, mountSpace, onMountsChange, openAppSpace, unmountSpace, useMounts, waitForMount } from './mounts.js';
+export { HostTheme, getHostTheme, onHostThemeChange, setHostTheme, useHostTheme } from './theme.js';
+export { EditorContext, getEditorContext, onEditorContextChange, useEditorContext } from './editorContext.js';
+export { FormFactor, FormFactorClass, Orientation, getFormFactor, onFormFactorChange, useFormFactor } from './formFactor.js';
+export { MountQuery, SandboxMount, SpaceError, SpaceInfo, createSpace, findMount, getMounts, listSpaces, mount, mountSpace, onMountsChange, openAppSpace, requestMount, requestSpace, unmountSpace, useMounts, waitForMount } from './mounts.js';
+export { ContributeMode, ContributeOptions, ContributionEvent, ContributionResult, contribute } from './contribute.js';
+export { StreamError, StreamFrame, StreamTransport, consumeStream, protocolStream } from './protocolStream.js';
 export { EvaluationContext, FileQueryResult, FilesMetadata, Metadata, MetadataQueryFunction, MetadataQueryResult, ModuleExports } from './sandboxTypes.js';
 import 'react';
 import './TinkerableContext.js';

package/dist/index.js

@@ -5,6 +5,11 @@ export * from "./components/Include";
 export * from "./components/MDXComponents";
 export * from "./hooks";
 export * from "./auth";
+export * from "./theme";
+export * from "./editorContext";
+export * from "./formFactor";
 export * from "./mounts";
+export * from "./contribute";
+export * from "./protocolStream";
 export * from "./sandboxTypes";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\nexport * from './components/MDXComponents';\nexport * from './hooks'\nexport * from './auth';\nexport * from './mounts';\nexport * from './sandboxTypes';\n"],"mappings":"AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export * from \"./MDXProvider\";\nexport * from \"./routing\";\nexport * from \"./boot\";\nexport * from './components/Include';\nexport * from './components/MDXComponents';\nexport * from './hooks'\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './formFactor';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './protocolStream';\nexport * from './sandboxTypes';\n"],"mappings":"AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;","names":[]}