@immediately-run/sdk 0.15.0 → 0.17.0

package/dist/hooks.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/hooks.ts"],"sourcesContent":["import { use, useEffect, useMemo, useState } from 'react';\nimport { TinkerableContext } from './TinkerableContext';\nimport { FilesMetadata, Metadata, MetadataQueryFunction, MetadataQueryResult } from './sandboxTypes';\n\nconst evaluateQueryFunction = (filesMetadata:FilesMetadata, queryFunction: MetadataQueryFunction):MetadataQueryResult => {\n  try {\n    return {result: queryFunction(filesMetadata)}\n  } catch (e) {\n    return {error: e}\n  }\n}\n\nconst arraysEqual = <T>(a: T[], b:T[]):boolean => {\n  if (a.length !== b.length) {\n    return false;\n  }\n  for (let i = 0; i < a.length; i++) {\n    if (a[i] !== b[i]) {\n      return false;\n    }\n  }\n  return true;\n}\n\nexport const useMetadataQuery = (queryFunction:MetadataQueryFunction) => {\n  const {filesMetadata} = use(TinkerableContext);\n  // we don't care if the metadata reference has changed, we only care about the output of queryFunction()\n  const [queryResult, setQueryResult] = useState<MetadataQueryResult | null>(null);\n  // any time the metadata object changes,\n  // recalculate the query result and update the state if necessary\n  useEffect(() => {\n    setQueryResult(prevResult => {\n      const newResult = evaluateQueryFunction(filesMetadata, queryFunction);\n      if (!prevResult) {\n        return newResult;\n      }\n      if (!('result' in newResult)) {\n        return newResult;\n      }\n      if (!('result' in prevResult)) {\n        return newResult;\n      }\n      return arraysEqual(prevResult.result, newResult.result) ? prevResult : newResult;\n    })\n  }, [filesMetadata, setQueryResult, queryFunction])\n  return queryResult;\n}\n\nexport const useFileMetadata = (path: string): Metadata|null => {\n  const {filesMetadata} = use(TinkerableContext);\n  const result = useMemo(() => filesMetadata[path], [path, filesMetadata]);\n  return result;\n}\n"],"mappings":"AAAA,SAAS,KAAK,WAAW,SAAS,gBAAgB;AAClD,SAAS,yBAAyB;AAGlC,MAAM,wBAAwB,CAAC,eAA6B,kBAA6D;AACvH,MAAI;AACF,WAAO,EAAC,QAAQ,cAAc,aAAa,EAAC;AAAA,EAC9C,SAAS,GAAG;AACV,WAAO,EAAC,OAAO,EAAC;AAAA,EAClB;AACF;AAEA,MAAM,cAAc,CAAI,GAAQ,MAAkB;AAChD,MAAI,EAAE,WAAW,EAAE,QAAQ;AACzB,WAAO;AAAA,EACT;AACA,WAAS,IAAI,GAAG,IAAI,EAAE,QAAQ,KAAK;AACjC,QAAI,EAAE,CAAC,MAAM,EAAE,CAAC,GAAG;AACjB,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO;AACT;AAEO,MAAM,mBAAmB,CAAC,kBAAwC;AACvE,QAAM,EAAC,cAAa,IAAI,IAAI,iBAAiB;AAE7C,QAAM,CAAC,aAAa,cAAc,IAAI,SAAqC,IAAI;AAG/E,YAAU,MAAM;AACd,mBAAe,gBAAc;AAC3B,YAAM,YAAY,sBAAsB,eAAe,aAAa;AACpE,UAAI,CAAC,YAAY;AACf,eAAO;AAAA,MACT;AACA,UAAI,EAAE,YAAY,YAAY;AAC5B,eAAO;AAAA,MACT;AACA,UAAI,EAAE,YAAY,aAAa;AAC7B,eAAO;AAAA,MACT;AACA,aAAO,YAAY,WAAW,QAAQ,UAAU,MAAM,IAAI,aAAa;AAAA,IACzE,CAAC;AAAA,EACH,GAAG,CAAC,eAAe,gBAAgB,aAAa,CAAC;AACjD,SAAO;AACT;AAEO,MAAM,kBAAkB,CAAC,SAAgC;AAC9D,QAAM,EAAC,cAAa,IAAI,IAAI,iBAAiB;AAC7C,QAAM,SAAS,QAAQ,MAAM,cAAc,IAAI,GAAG,CAAC,MAAM,aAAa,CAAC;AACvE,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../src/hooks.ts"],"sourcesContent":["import { use, useMemo, useRef } from 'react';\nimport { TinkerableContext } from './TinkerableContext';\nimport {\n  FilesMetadata,\n  Metadata,\n  MetadataQueryEntry,\n  MetadataQueryFunction,\n  MetadataQueryResult,\n} from './sandboxTypes';\n\nconst entriesEqual = <T>(a: MetadataQueryEntry<T>[], b: MetadataQueryEntry<T>[]): boolean => {\n  if (a.length !== b.length) {\n    return false;\n  }\n  for (let i = 0; i < a.length; i++) {\n    // Unchanged frontmatter keeps its object identity across `metadata-update`\n    // merges, so an identity check on `meta` is a sound \"did this match change?\".\n    if (a[i].path !== b[i].path || a[i].meta !== b[i].meta) {\n      return false;\n    }\n  }\n  return true;\n};\n\n/**\n * Query the file metadata store (MDX frontmatter) with a plain JS function.\n *\n * The query receives every file's frontmatter keyed by path and returns the paths\n * that match; the hook resolves each path back to its frontmatter and returns an\n * array of `{ path, meta }` entries — so a single call gives you everything you\n * filtered on, with no second lookup. A throwing query is reported as `{ error }`\n * rather than crashing the render.\n *\n * The query runs synchronously during render (no empty first frame), and the\n * returned array keeps its identity while the matches are unchanged, so it is safe\n * to use directly in downstream `useMemo`/`useEffect` dependency arrays.\n *\n * Pass a type parameter to get typed frontmatter throughout:\n * ```ts\n * interface PostMeta { title: string; date: string; draft?: boolean }\n * const posts = useMetadataQuery<PostMeta>((files) =>\n *   Object.entries(files)\n *     .filter(([, m]) => !m.draft)\n *     .sort(([, a], [, b]) => b.date.localeCompare(a.date))\n *     .map(([path]) => path),\n * );\n * ```\n */\nexport const useMetadataQuery = <T = Metadata>(\n  queryFunction: MetadataQueryFunction<T>,\n): MetadataQueryResult<T> => {\n  const { filesMetadata } = use(TinkerableContext);\n  const previous = useRef<MetadataQueryEntry<T>[]>([]);\n  return useMemo<MetadataQueryResult<T>>(() => {\n    const files = (filesMetadata ?? {}) as FilesMetadata<T>;\n    let entries: MetadataQueryEntry<T>[];\n    try {\n      entries = queryFunction(files).map((path) => ({ path, meta: files[path] }));\n    } catch (error) {\n      return { error };\n    }\n    // Preserve the prior array reference when nothing matched differently.\n    if (entriesEqual(entries, previous.current)) {\n      return previous.current;\n    }\n    previous.current = entries;\n    return entries;\n  }, [filesMetadata, queryFunction]);\n};\n\n/**\n * Read one file's metadata (MDX frontmatter) by repo-relative path. Returns\n * `undefined` when the path has no metadata. Pass a type parameter for typed\n * field access.\n */\nexport const useFileMetadata = <T = Metadata>(path: string): T | undefined => {\n  const { filesMetadata } = use(TinkerableContext);\n  return useMemo(\n    () => (filesMetadata ?? {})[path] as T | undefined,\n    [path, filesMetadata],\n  );\n};\n\n/**\n * The raw, reactive metadata store: a map from file path to frontmatter. The\n * escape hatch for apps that want to render their own index rather than express it\n * as a path-returning query. Pass a type parameter for typed frontmatter values.\n */\nexport const useAllMetadata = <T = Metadata>(): FilesMetadata<T> => {\n  const { filesMetadata } = use(TinkerableContext);\n  return (filesMetadata ?? {}) as FilesMetadata<T>;\n};\n"],"mappings":"AAAA,SAAS,KAAK,SAAS,cAAc;AACrC,SAAS,yBAAyB;AASlC,MAAM,eAAe,CAAI,GAA4B,MAAwC;AAC3F,MAAI,EAAE,WAAW,EAAE,QAAQ;AACzB,WAAO;AAAA,EACT;AACA,WAAS,IAAI,GAAG,IAAI,EAAE,QAAQ,KAAK;AAGjC,QAAI,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM;AACtD,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO;AACT;AA0BO,MAAM,mBAAmB,CAC9B,kBAC2B;AAC3B,QAAM,EAAE,cAAc,IAAI,IAAI,iBAAiB;AAC/C,QAAM,WAAW,OAAgC,CAAC,CAAC;AACnD,SAAO,QAAgC,MAAM;AAC3C,UAAM,QAAS,iBAAiB,CAAC;AACjC,QAAI;AACJ,QAAI;AACF,gBAAU,cAAc,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,MAAM,MAAM,IAAI,EAAE,EAAE;AAAA,IAC5E,SAAS,OAAO;AACd,aAAO,EAAE,MAAM;AAAA,IACjB;AAEA,QAAI,aAAa,SAAS,SAAS,OAAO,GAAG;AAC3C,aAAO,SAAS;AAAA,IAClB;AACA,aAAS,UAAU;AACnB,WAAO;AAAA,EACT,GAAG,CAAC,eAAe,aAAa,CAAC;AACnC;AAOO,MAAM,kBAAkB,CAAe,SAAgC;AAC5E,QAAM,EAAE,cAAc,IAAI,IAAI,iBAAiB;AAC/C,SAAO;AAAA,IACL,OAAO,iBAAiB,CAAC,GAAG,IAAI;AAAA,IAChC,CAAC,MAAM,aAAa;AAAA,EACtB;AACF;AAOO,MAAM,iBAAiB,MAAsC;AAClE,QAAM,EAAE,cAAc,IAAI,IAAI,iBAAiB;AAC/C,SAAQ,iBAAiB,CAAC;AAC5B;","names":[]}

package/dist/index.cjs

@@ -20,6 +20,7 @@ __reExport(index_exports, require("./routing"), module.exports);
 __reExport(index_exports, require("./boot"), module.exports);
 __reExport(index_exports, require("./components/Include"), module.exports);
 __reExport(index_exports, require("./components/MDXComponents"), module.exports);
+__reExport(index_exports, require("./components/Routes"), module.exports);
 __reExport(index_exports, require("./hooks"), module.exports);
 __reExport(index_exports, require("./auth"), module.exports);
 __reExport(index_exports, require("./theme"), module.exports);
@@ -37,10 +38,12 @@ __reExport(index_exports, require("./secrets"), module.exports);
 __reExport(index_exports, require("./llm"), module.exports);
 __reExport(index_exports, require("./diagnostics"), module.exports);
 __reExport(index_exports, require("./onFsChange"), module.exports);
+__reExport(index_exports, require("./debug"), module.exports);
 __reExport(index_exports, require("./tasks"), module.exports);
 __reExport(index_exports, require("./runtime"), module.exports);
 __reExport(index_exports, require("./irMarkers"), module.exports);
 __reExport(index_exports, require("./ready"), module.exports);
+__reExport(index_exports, require("./loading"), 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:
@@ -50,6 +53,7 @@ __reExport(index_exports, require("./sandboxTypes"), module.exports);
   ...require("./boot"),
   ...require("./components/Include"),
   ...require("./components/MDXComponents"),
+  ...require("./components/Routes"),
   ...require("./hooks"),
   ...require("./auth"),
   ...require("./theme"),
@@ -67,10 +71,12 @@ __reExport(index_exports, require("./sandboxTypes"), module.exports);
   ...require("./llm"),
   ...require("./diagnostics"),
   ...require("./onFsChange"),
+  ...require("./debug"),
   ...require("./tasks"),
   ...require("./runtime"),
   ...require("./irMarkers"),
   ...require("./ready"),
+  ...require("./loading"),
   ...require("./protocolStream"),
   ...require("./sandboxTypes")
 });

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 './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './region';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './secrets';\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './onFsChange';\nexport * from './tasks';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\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,qBATd;AAUA,0BAAc,yBAVd;AAWA,0BAAc,qBAXd;AAYA,0BAAc,qBAZd;AAaA,0BAAc,yBAbd;AAcA,0BAAc,sBAdd;AAeA,0BAAc,kBAfd;AAgBA,0BAAc,kBAhBd;AAiBA,0BAAc,uBAjBd;AAkBA,0BAAc,sBAlBd;AAmBA,0BAAc,kBAnBd;AAoBA,0BAAc,0BApBd;AAqBA,0BAAc,yBArBd;AAsBA,0BAAc,oBAtBd;AAuBA,0BAAc,sBAvBd;AAwBA,0BAAc,wBAxBd;AAyBA,0BAAc,oBAzBd;AA0BA,0BAAc,6BA1Bd;AA2BA,0BAAc,2BA3Bd;","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 './components/Routes';\nexport * from './hooks'\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './region';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './secrets';\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './onFsChange';\nexport * from './debug';\nexport * from './tasks';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\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,gCALd;AAMA,0BAAc,oBANd;AAOA,0BAAc,mBAPd;AAQA,0BAAc,oBARd;AASA,0BAAc,4BATd;AAUA,0BAAc,qBAVd;AAWA,0BAAc,yBAXd;AAYA,0BAAc,qBAZd;AAaA,0BAAc,qBAbd;AAcA,0BAAc,yBAdd;AAeA,0BAAc,sBAfd;AAgBA,0BAAc,kBAhBd;AAiBA,0BAAc,kBAjBd;AAkBA,0BAAc,uBAlBd;AAmBA,0BAAc,sBAnBd;AAoBA,0BAAc,kBApBd;AAqBA,0BAAc,0BArBd;AAsBA,0BAAc,yBAtBd;AAuBA,0BAAc,oBAvBd;AAwBA,0BAAc,oBAxBd;AAyBA,0BAAc,sBAzBd;AA0BA,0BAAc,wBA1Bd;AA2BA,0BAAc,oBA3Bd;AA4BA,0BAAc,sBA5Bd;AA6BA,0BAAc,6BA7Bd;AA8BA,0BAAc,2BA9Bd;","names":[]}

package/dist/index.d.cts

@@ -1,9 +1,10 @@
 export { MDXProvider, useMDXComponents } from './MDXProvider.cjs';
-export { AppliedRoutingRule, Router, applyRoutingRule, navigate, useTinkerableLink } from './routing.cjs';
-export { BootProps, DEFAULT_ROUTING_SPEC, TinkerableApp, boot } from './boot.cjs';
+export { AppliedRoutingRule, Router, applyRoutingRule, navigate, renderRoute, useRoute, useRouteParams, useTinkerableLink } from './routing.cjs';
+export { BootProps, CATCH_ALL_ROUTING_SPEC, DEFAULT_ROUTING_SPEC, TinkerableApp, boot } from './boot.cjs';
 export { Include, RenderExportedComponent, RenderExportedComponentContext, RenderFileContextType } from './components/Include.cjs';
 export { DEFAULT_MDX_COMPONENTS, InternalLink, Link } from './components/MDXComponents.cjs';
-export { useFileMetadata, useMetadataQuery } from './hooks.cjs';
+export { Route, RouteProps, Routes } from './components/Routes.cjs';
+export { useAllMetadata, 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';
@@ -20,12 +21,14 @@ export { SecretError, SecretGrant, SecretHints, SecretQuery, SecretType, SecretV
 export { ChatDelta, ChatFeatures, ChatMessage, ChatProviderInfo, ChatRequest, ChatResult, ChatRole, ChatStopReason, ContentPart, ToolDef, chat, describeChat, onChatProviderChange, useChatProvider } from './llm.cjs';
 export { BuildError, ConsoleEntry, ConsoleLevel, Diagnostics, DiagnosticsProvenance, getDiagnostics, onDiagnosticsChange, useDiagnostics } from './diagnostics.cjs';
 export { FsChange, getFsChange, onFsChange, useFsChange } from './onFsChange.cjs';
+export { DebugLevel, debug, isDebugEnabled, log, useDebugEnabled } from './debug.cjs';
 export { DirCap, FileCap, TaskInput, cancelTask, capDir, capFile, completeTask, getTaskInput, invokeTask, useTaskInput } from './tasks.cjs';
 export { SDK_PROTOCOL_VERSION, SdkHandshake, announceHandshake, sdkHandshake } from './runtime.cjs';
 export { ForwardedMarker, IR_MARKERS, IrMarkerName, isAllowedMarkerName, isIrMarkerName, resolveInteractive, validateMarker } from './irMarkers.cjs';
 export { ReadyState, __resetReady, __setReadyDeps, getReadyState, onReady, reportReady } from './ready.cjs';
+export { LOADING_TIMINGS, LoadingRegion, Skeleton, SkeletonArchetype, SkeletonRow, Spinner } from './loading.cjs';
 export { StreamError, StreamFrame, StreamTransport, consumeStream, protocolStream } from './protocolStream.cjs';
-export { EvaluationContext, FileQueryResult, FilesMetadata, Metadata, MetadataQueryFunction, MetadataQueryResult, ModuleExports } from './sandboxTypes.cjs';
+export { EvaluationContext, FileQueryResult, FilesMetadata, Metadata, MetadataQueryEntry, MetadataQueryFunction, MetadataQueryResult, ModuleExports } from './sandboxTypes.cjs';
 export { ImmediatelyRunGlobal, getHostRuntime } from './hostRuntime.cjs';
 export { SDK_VERSION } from './version.cjs';
 import 'react';

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 export { MDXProvider, useMDXComponents } from './MDXProvider.js';
-export { AppliedRoutingRule, Router, applyRoutingRule, navigate, useTinkerableLink } from './routing.js';
-export { BootProps, DEFAULT_ROUTING_SPEC, TinkerableApp, boot } from './boot.js';
+export { AppliedRoutingRule, Router, applyRoutingRule, navigate, renderRoute, useRoute, useRouteParams, useTinkerableLink } from './routing.js';
+export { BootProps, CATCH_ALL_ROUTING_SPEC, DEFAULT_ROUTING_SPEC, TinkerableApp, boot } from './boot.js';
 export { Include, RenderExportedComponent, RenderExportedComponentContext, RenderFileContextType } from './components/Include.js';
 export { DEFAULT_MDX_COMPONENTS, InternalLink, Link } from './components/MDXComponents.js';
-export { useFileMetadata, useMetadataQuery } from './hooks.js';
+export { Route, RouteProps, Routes } from './components/Routes.js';
+export { useAllMetadata, 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';
@@ -20,12 +21,14 @@ export { SecretError, SecretGrant, SecretHints, SecretQuery, SecretType, SecretV
 export { ChatDelta, ChatFeatures, ChatMessage, ChatProviderInfo, ChatRequest, ChatResult, ChatRole, ChatStopReason, ContentPart, ToolDef, chat, describeChat, onChatProviderChange, useChatProvider } from './llm.js';
 export { BuildError, ConsoleEntry, ConsoleLevel, Diagnostics, DiagnosticsProvenance, getDiagnostics, onDiagnosticsChange, useDiagnostics } from './diagnostics.js';
 export { FsChange, getFsChange, onFsChange, useFsChange } from './onFsChange.js';
+export { DebugLevel, debug, isDebugEnabled, log, useDebugEnabled } from './debug.js';
 export { DirCap, FileCap, TaskInput, cancelTask, capDir, capFile, completeTask, getTaskInput, invokeTask, useTaskInput } from './tasks.js';
 export { SDK_PROTOCOL_VERSION, SdkHandshake, announceHandshake, sdkHandshake } from './runtime.js';
 export { ForwardedMarker, IR_MARKERS, IrMarkerName, isAllowedMarkerName, isIrMarkerName, resolveInteractive, validateMarker } from './irMarkers.js';
 export { ReadyState, __resetReady, __setReadyDeps, getReadyState, onReady, reportReady } from './ready.js';
+export { LOADING_TIMINGS, LoadingRegion, Skeleton, SkeletonArchetype, SkeletonRow, Spinner } from './loading.js';
 export { StreamError, StreamFrame, StreamTransport, consumeStream, protocolStream } from './protocolStream.js';
-export { EvaluationContext, FileQueryResult, FilesMetadata, Metadata, MetadataQueryFunction, MetadataQueryResult, ModuleExports } from './sandboxTypes.js';
+export { EvaluationContext, FileQueryResult, FilesMetadata, Metadata, MetadataQueryEntry, MetadataQueryFunction, MetadataQueryResult, ModuleExports } from './sandboxTypes.js';
 export { ImmediatelyRunGlobal, getHostRuntime } from './hostRuntime.js';
 export { SDK_VERSION } from './version.js';
 import 'react';

package/dist/index.js

@@ -3,6 +3,7 @@ export * from "./routing";
 export * from "./boot";
 export * from "./components/Include";
 export * from "./components/MDXComponents";
+export * from "./components/Routes";
 export * from "./hooks";
 export * from "./auth";
 export * from "./theme";
@@ -20,10 +21,12 @@ export * from "./secrets";
 export * from "./llm";
 export * from "./diagnostics";
 export * from "./onFsChange";
+export * from "./debug";
 export * from "./tasks";
 export * from "./runtime";
 export * from "./irMarkers";
 export * from "./ready";
+export * from "./loading";
 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 './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './region';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './secrets';\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './onFsChange';\nexport * from './tasks';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\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;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;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 './components/Routes';\nexport * from './hooks'\nexport * from './auth';\nexport * from './theme';\nexport * from './editorContext';\nexport * from './editor';\nexport * from './formFactor';\nexport * from './region';\nexport * from './mounts';\nexport * from './contribute';\nexport * from './catalog';\nexport * from './ipc';\nexport * from './dnd';\nexport * from './netFetch';\nexport * from './secrets';\nexport * from './llm';\nexport * from './diagnostics';\nexport * from './onFsChange';\nexport * from './debug';\nexport * from './tasks';\nexport * from './runtime';\nexport * from './irMarkers';\nexport * from './ready';\nexport * from './loading';\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;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;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;","names":[]}

package/dist/irMarkers.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/irMarkers.ts"],"sourcesContent":["// The `ir.*` load-profiling marker vocabulary + the host-side allowlist + the\n// `ir.interactive` precedence rule (LOAD_PROFILING_SPEC §3/§3.1, R3-46).\n//\n// This module is PURE and dependency-free on purpose: the spec (§3.1) requires the\n// host's vocabulary allowlist to be MIRRORED from this same definition (\"additions\n// to the vocabulary are spec amendments, mirrored in the host allowlist in the same\n// change\"). Keeping the table + validator here, with no transport/React imports,\n// lets the sandbox side (this SDK) and the host (site-main, its own mirrored copy)\n// share an identical contract that is unit-tested in both places.\n\n/**\n * Each `ir.*` marker name → the attribute keys its payload may carry (the §3\n * table). A forwarded marker is accepted only if BOTH its name is defined here AND\n * every attribute key it carries is in that marker's allowed set (LP-5). An empty\n * array means \"no attributes\" (a bare mark).\n */\nexport const IR_MARKERS = {\n  \"ir.open\": [\"url\", \"provider\", \"ns\", \"repo\", \"ref\", \"refKind\"],\n  \"ir.fetch\": [\"source\", \"bytes\", \"requestCount\", \"cacheHit\", \"httpStatus\"],\n  \"ir.mount\": [\"phantomCount\", \"writablePrimed\"],\n  \"ir.sandbox.boot\": [],\n  \"ir.transpile\": [\"moduleCount\", \"cacheHit\", \"bytesIn\", \"bytesOut\"],\n  \"ir.deps\": [\"depCount\", \"bytes\", \"requestCount\", \"cacheHit\", \"cdn\"],\n  \"ir.eval\": [\"moduleCount\"],\n  \"ir.fmp\": [],\n  \"ir.interactive\": [\"cold\"],\n  \"ir.verify\": [\"result\", \"blocking\"],\n  \"ir.refresh\": [\"bytes\"],\n} as const;\n\nexport type IrMarkerName = keyof typeof IR_MARKERS;\n\n// Per-module / per-dep sub-marks (§3): a defined aggregate plus a `[…]` selector,\n// e.g. `ir.transpile.mod[/src/App.tsx]` or `ir.deps.pkg[react@18.2.0]`. A sub-mark\n// inherits its aggregate's attribute schema.\nconst SUBMARK_RE = /^(ir\\.transpile\\.mod|ir\\.deps\\.pkg)\\[[^\\]]+\\]$/;\nconst submarkAggregate = (name: string): IrMarkerName | null =>\n  name.startsWith(\"ir.transpile.mod\") ? \"ir.transpile\" : name.startsWith(\"ir.deps.pkg\") ? \"ir.deps\" : null;\n\n/** Is `name` a defined top-level `ir.*` marker (not a sub-mark)? */\nexport const isIrMarkerName = (name: string): name is IrMarkerName =>\n  Object.prototype.hasOwnProperty.call(IR_MARKERS, name);\n\n/** Is `name` an accepted marker name — a defined top-level marker OR a recognized\n *  per-module/per-dep sub-mark? */\nexport const isAllowedMarkerName = (name: string): boolean =>\n  isIrMarkerName(name) || SUBMARK_RE.test(name);\n\n/** A marker forwarded across the origin boundary (§3.2): a name, the sandbox-side\n *  `performance.now()` timestamp, and the optional attribute payload. */\nexport interface ForwardedMarker {\n  name: string;\n  /** Sandbox-relative timestamp (`performance.now()`) at emission (§3.2). */\n  at: number;\n  attrs?: Record<string, unknown>;\n}\n\n/**\n * The LP-5 vocabulary allowlist (pure). Accept a forwarded marker ONLY if its name\n * is in the vocabulary AND every attribute key is in that marker's schema. An\n * unknown name — or a defined name carrying an out-of-schema attribute key — is\n * DROPPED (returns `null`), never recorded. This is the gate against an untrusted\n * sandbox minting arbitrary names/values into the host timeline (an injection\n * surface for dashboards / the deferred RUM endpoint). Sub-marks inherit their\n * aggregate's schema.\n */\nexport function validateMarker(m: ForwardedMarker | null | undefined): ForwardedMarker | null {\n  if (!m || typeof m.name !== \"string\") return null;\n  if (typeof m.at !== \"number\" || !Number.isFinite(m.at)) return null;\n  if (!isAllowedMarkerName(m.name)) return null;\n  const base: IrMarkerName = isIrMarkerName(m.name) ? m.name : submarkAggregate(m.name)!;\n  const allowed: readonly string[] = IR_MARKERS[base];\n  const attrs = m.attrs;\n  if (attrs !== undefined) {\n    if (typeof attrs !== \"object\" || attrs === null) return null;\n    for (const key of Object.keys(attrs)) {\n      if (!allowed.includes(key)) return null; // out-of-schema attribute → drop the whole marker\n    }\n  }\n  return { name: m.name, at: m.at, ...(attrs !== undefined ? { attrs } : {}) };\n}\n\n/**\n * `ir.interactive = max(rootRenderCommit, reportReady)` (LP2-3). An app-called\n * `reportReady()` may only DELAY interactive — never advance it before the root\n * render commits. A `reportReady()` that fires early is recorded but takes effect\n * at the commit; if the app never reports, the commit alone stands. Budgets bind to\n * the later of the two, so an app can't game its budget by declaring itself ready\n * before it has rendered anything. PURE.\n */\nexport function resolveInteractive(rootRenderCommitAt: number, reportReadyAt?: number): number {\n  if (reportReadyAt === undefined) return rootRenderCommitAt;\n  return Math.max(rootRenderCommitAt, reportReadyAt);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgBO,MAAM,aAAa;AAAA,EACxB,WAAW,CAAC,OAAO,YAAY,MAAM,QAAQ,OAAO,SAAS;AAAA,EAC7D,YAAY,CAAC,UAAU,SAAS,gBAAgB,YAAY,YAAY;AAAA,EACxE,YAAY,CAAC,gBAAgB,gBAAgB;AAAA,EAC7C,mBAAmB,CAAC;AAAA,EACpB,gBAAgB,CAAC,eAAe,YAAY,WAAW,UAAU;AAAA,EACjE,WAAW,CAAC,YAAY,SAAS,gBAAgB,YAAY,KAAK;AAAA,EAClE,WAAW,CAAC,aAAa;AAAA,EACzB,UAAU,CAAC;AAAA,EACX,kBAAkB,CAAC,MAAM;AAAA,EACzB,aAAa,CAAC,UAAU,UAAU;AAAA,EAClC,cAAc,CAAC,OAAO;AACxB;AAOA,MAAM,aAAa;AACnB,MAAM,mBAAmB,CAAC,SACxB,KAAK,WAAW,kBAAkB,IAAI,iBAAiB,KAAK,WAAW,aAAa,IAAI,YAAY;AAG/F,MAAM,iBAAiB,CAAC,SAC7B,OAAO,UAAU,eAAe,KAAK,YAAY,IAAI;AAIhD,MAAM,sBAAsB,CAAC,SAClC,eAAe,IAAI,KAAK,WAAW,KAAK,IAAI;AAoBvC,SAAS,eAAe,GAA+D;AAC5F,MAAI,CAAC,KAAK,OAAO,EAAE,SAAS,SAAU,QAAO;AAC7C,MAAI,OAAO,EAAE,OAAO,YAAY,CAAC,OAAO,SAAS,EAAE,EAAE,EAAG,QAAO;AAC/D,MAAI,CAAC,oBAAoB,EAAE,IAAI,EAAG,QAAO;AACzC,QAAM,OAAqB,eAAe,EAAE,IAAI,IAAI,EAAE,OAAO,iBAAiB,EAAE,IAAI;AACpF,QAAM,UAA6B,WAAW,IAAI;AAClD,QAAM,QAAQ,EAAE;AAChB,MAAI,UAAU,QAAW;AACvB,QAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AACxD,eAAW,OAAO,OAAO,KAAK,KAAK,GAAG;AACpC,UAAI,CAAC,QAAQ,SAAS,GAAG,EAAG,QAAO;AAAA,IACrC;AAAA,EACF;AACA,SAAO,EAAE,MAAM,EAAE,MAAM,IAAI,EAAE,IAAI,GAAI,UAAU,SAAY,EAAE,MAAM,IAAI,CAAC,EAAG;AAC7E;AAUO,SAAS,mBAAmB,oBAA4B,eAAgC;AAC7F,MAAI,kBAAkB,OAAW,QAAO;AACxC,SAAO,KAAK,IAAI,oBAAoB,aAAa;AACnD;","names":[]}
+{"version":3,"sources":["../src/irMarkers.ts"],"sourcesContent":["// The `ir.*` load-profiling marker vocabulary + the host-side allowlist + the\n// `ir.interactive` precedence rule (LOAD_PROFILING_SPEC §3/§3.1, R3-46).\n//\n// This module is PURE and dependency-free on purpose: the spec (§3.1) requires the\n// host's vocabulary allowlist to be MIRRORED from this same definition (\"additions\n// to the vocabulary are spec amendments, mirrored in the host allowlist in the same\n// change\"). Keeping the table + validator here, with no transport/React imports,\n// lets the sandbox side (this SDK) and the host (site-main, its own mirrored copy)\n// share an identical contract that is unit-tested in both places.\n\n/**\n * Each `ir.*` marker name → the attribute keys its payload may carry (the §3\n * table). A forwarded marker is accepted only if BOTH its name is defined here AND\n * every attribute key it carries is in that marker's allowed set (LP-5). An empty\n * array means \"no attributes\" (a bare mark).\n */\nexport const IR_MARKERS = {\n  \"ir.open\": [\"url\", \"provider\", \"ns\", \"repo\", \"ref\", \"refKind\"],\n  \"ir.fetch\": [\"source\", \"bytes\", \"requestCount\", \"cacheHit\", \"httpStatus\"],\n  \"ir.mount\": [\"phantomCount\", \"writablePrimed\"],\n  \"ir.sandbox.boot\": [],\n  \"ir.transpile\": [\"moduleCount\", \"cacheHit\", \"bytesIn\", \"bytesOut\"],\n  \"ir.deps\": [\"depCount\", \"bytes\", \"requestCount\", \"cacheHit\", \"cdn\"],\n  \"ir.eval\": [\"moduleCount\"],\n  \"ir.fmp\": [],\n  \"ir.interactive\": [\"cold\"],\n  \"ir.verify\": [\"result\", \"blocking\"],\n  \"ir.refresh\": [\"bytes\"],\n} as const;\n\n/** A canonical `ir.*` load-profiling marker name (a key of {@link IR_MARKERS}). */\nexport type IrMarkerName = keyof typeof IR_MARKERS;\n\n// Per-module / per-dep sub-marks (§3): a defined aggregate plus a `[…]` selector,\n// e.g. `ir.transpile.mod[/src/App.tsx]` or `ir.deps.pkg[react@18.2.0]`. A sub-mark\n// inherits its aggregate's attribute schema.\nconst SUBMARK_RE = /^(ir\\.transpile\\.mod|ir\\.deps\\.pkg)\\[[^\\]]+\\]$/;\nconst submarkAggregate = (name: string): IrMarkerName | null =>\n  name.startsWith(\"ir.transpile.mod\") ? \"ir.transpile\" : name.startsWith(\"ir.deps.pkg\") ? \"ir.deps\" : null;\n\n/** Is `name` a defined top-level `ir.*` marker (not a sub-mark)? */\nexport const isIrMarkerName = (name: string): name is IrMarkerName =>\n  Object.prototype.hasOwnProperty.call(IR_MARKERS, name);\n\n/** Is `name` an accepted marker name — a defined top-level marker OR a recognized\n *  per-module/per-dep sub-mark? */\nexport const isAllowedMarkerName = (name: string): boolean =>\n  isIrMarkerName(name) || SUBMARK_RE.test(name);\n\n/** A marker forwarded across the origin boundary (§3.2): a name, the sandbox-side\n *  `performance.now()` timestamp, and the optional attribute payload. */\nexport interface ForwardedMarker {\n  name: string;\n  /** Sandbox-relative timestamp (`performance.now()`) at emission (§3.2). */\n  at: number;\n  attrs?: Record<string, unknown>;\n}\n\n/**\n * The LP-5 vocabulary allowlist (pure). Accept a forwarded marker ONLY if its name\n * is in the vocabulary AND every attribute key is in that marker's schema. An\n * unknown name — or a defined name carrying an out-of-schema attribute key — is\n * DROPPED (returns `null`), never recorded. This is the gate against an untrusted\n * sandbox minting arbitrary names/values into the host timeline (an injection\n * surface for dashboards / the deferred RUM endpoint). Sub-marks inherit their\n * aggregate's schema.\n */\nexport function validateMarker(m: ForwardedMarker | null | undefined): ForwardedMarker | null {\n  if (!m || typeof m.name !== \"string\") return null;\n  if (typeof m.at !== \"number\" || !Number.isFinite(m.at)) return null;\n  if (!isAllowedMarkerName(m.name)) return null;\n  const base: IrMarkerName = isIrMarkerName(m.name) ? m.name : submarkAggregate(m.name)!;\n  const allowed: readonly string[] = IR_MARKERS[base];\n  const attrs = m.attrs;\n  if (attrs !== undefined) {\n    if (typeof attrs !== \"object\" || attrs === null) return null;\n    for (const key of Object.keys(attrs)) {\n      if (!allowed.includes(key)) return null; // out-of-schema attribute → drop the whole marker\n    }\n  }\n  return { name: m.name, at: m.at, ...(attrs !== undefined ? { attrs } : {}) };\n}\n\n/**\n * `ir.interactive = max(rootRenderCommit, reportReady)` (LP2-3). An app-called\n * `reportReady()` may only DELAY interactive — never advance it before the root\n * render commits. A `reportReady()` that fires early is recorded but takes effect\n * at the commit; if the app never reports, the commit alone stands. Budgets bind to\n * the later of the two, so an app can't game its budget by declaring itself ready\n * before it has rendered anything. PURE.\n */\nexport function resolveInteractive(rootRenderCommitAt: number, reportReadyAt?: number): number {\n  if (reportReadyAt === undefined) return rootRenderCommitAt;\n  return Math.max(rootRenderCommitAt, reportReadyAt);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgBO,MAAM,aAAa;AAAA,EACxB,WAAW,CAAC,OAAO,YAAY,MAAM,QAAQ,OAAO,SAAS;AAAA,EAC7D,YAAY,CAAC,UAAU,SAAS,gBAAgB,YAAY,YAAY;AAAA,EACxE,YAAY,CAAC,gBAAgB,gBAAgB;AAAA,EAC7C,mBAAmB,CAAC;AAAA,EACpB,gBAAgB,CAAC,eAAe,YAAY,WAAW,UAAU;AAAA,EACjE,WAAW,CAAC,YAAY,SAAS,gBAAgB,YAAY,KAAK;AAAA,EAClE,WAAW,CAAC,aAAa;AAAA,EACzB,UAAU,CAAC;AAAA,EACX,kBAAkB,CAAC,MAAM;AAAA,EACzB,aAAa,CAAC,UAAU,UAAU;AAAA,EAClC,cAAc,CAAC,OAAO;AACxB;AAQA,MAAM,aAAa;AACnB,MAAM,mBAAmB,CAAC,SACxB,KAAK,WAAW,kBAAkB,IAAI,iBAAiB,KAAK,WAAW,aAAa,IAAI,YAAY;AAG/F,MAAM,iBAAiB,CAAC,SAC7B,OAAO,UAAU,eAAe,KAAK,YAAY,IAAI;AAIhD,MAAM,sBAAsB,CAAC,SAClC,eAAe,IAAI,KAAK,WAAW,KAAK,IAAI;AAoBvC,SAAS,eAAe,GAA+D;AAC5F,MAAI,CAAC,KAAK,OAAO,EAAE,SAAS,SAAU,QAAO;AAC7C,MAAI,OAAO,EAAE,OAAO,YAAY,CAAC,OAAO,SAAS,EAAE,EAAE,EAAG,QAAO;AAC/D,MAAI,CAAC,oBAAoB,EAAE,IAAI,EAAG,QAAO;AACzC,QAAM,OAAqB,eAAe,EAAE,IAAI,IAAI,EAAE,OAAO,iBAAiB,EAAE,IAAI;AACpF,QAAM,UAA6B,WAAW,IAAI;AAClD,QAAM,QAAQ,EAAE;AAChB,MAAI,UAAU,QAAW;AACvB,QAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AACxD,eAAW,OAAO,OAAO,KAAK,KAAK,GAAG;AACpC,UAAI,CAAC,QAAQ,SAAS,GAAG,EAAG,QAAO;AAAA,IACrC;AAAA,EACF;AACA,SAAO,EAAE,MAAM,EAAE,MAAM,IAAI,EAAE,IAAI,GAAI,UAAU,SAAY,EAAE,MAAM,IAAI,CAAC,EAAG;AAC7E;AAUO,SAAS,mBAAmB,oBAA4B,eAAgC;AAC7F,MAAI,kBAAkB,OAAW,QAAO;AACxC,SAAO,KAAK,IAAI,oBAAoB,aAAa;AACnD;","names":[]}

package/dist/irMarkers.d.cts

@@ -17,6 +17,7 @@ declare const IR_MARKERS: {
     readonly "ir.verify": readonly ["result", "blocking"];
     readonly "ir.refresh": readonly ["bytes"];
 };
+/** A canonical `ir.*` load-profiling marker name (a key of {@link IR_MARKERS}). */
 type IrMarkerName = keyof typeof IR_MARKERS;
 /** Is `name` a defined top-level `ir.*` marker (not a sub-mark)? */
 declare const isIrMarkerName: (name: string) => name is IrMarkerName;

package/dist/irMarkers.d.ts

@@ -17,6 +17,7 @@ declare const IR_MARKERS: {
     readonly "ir.verify": readonly ["result", "blocking"];
     readonly "ir.refresh": readonly ["bytes"];
 };
+/** A canonical `ir.*` load-profiling marker name (a key of {@link IR_MARKERS}). */
 type IrMarkerName = keyof typeof IR_MARKERS;
 /** Is `name` a defined top-level `ir.*` marker (not a sub-mark)? */
 declare const isIrMarkerName: (name: string) => name is IrMarkerName;

package/dist/irMarkers.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/irMarkers.ts"],"sourcesContent":["// The `ir.*` load-profiling marker vocabulary + the host-side allowlist + the\n// `ir.interactive` precedence rule (LOAD_PROFILING_SPEC §3/§3.1, R3-46).\n//\n// This module is PURE and dependency-free on purpose: the spec (§3.1) requires the\n// host's vocabulary allowlist to be MIRRORED from this same definition (\"additions\n// to the vocabulary are spec amendments, mirrored in the host allowlist in the same\n// change\"). Keeping the table + validator here, with no transport/React imports,\n// lets the sandbox side (this SDK) and the host (site-main, its own mirrored copy)\n// share an identical contract that is unit-tested in both places.\n\n/**\n * Each `ir.*` marker name → the attribute keys its payload may carry (the §3\n * table). A forwarded marker is accepted only if BOTH its name is defined here AND\n * every attribute key it carries is in that marker's allowed set (LP-5). An empty\n * array means \"no attributes\" (a bare mark).\n */\nexport const IR_MARKERS = {\n  \"ir.open\": [\"url\", \"provider\", \"ns\", \"repo\", \"ref\", \"refKind\"],\n  \"ir.fetch\": [\"source\", \"bytes\", \"requestCount\", \"cacheHit\", \"httpStatus\"],\n  \"ir.mount\": [\"phantomCount\", \"writablePrimed\"],\n  \"ir.sandbox.boot\": [],\n  \"ir.transpile\": [\"moduleCount\", \"cacheHit\", \"bytesIn\", \"bytesOut\"],\n  \"ir.deps\": [\"depCount\", \"bytes\", \"requestCount\", \"cacheHit\", \"cdn\"],\n  \"ir.eval\": [\"moduleCount\"],\n  \"ir.fmp\": [],\n  \"ir.interactive\": [\"cold\"],\n  \"ir.verify\": [\"result\", \"blocking\"],\n  \"ir.refresh\": [\"bytes\"],\n} as const;\n\nexport type IrMarkerName = keyof typeof IR_MARKERS;\n\n// Per-module / per-dep sub-marks (§3): a defined aggregate plus a `[…]` selector,\n// e.g. `ir.transpile.mod[/src/App.tsx]` or `ir.deps.pkg[react@18.2.0]`. A sub-mark\n// inherits its aggregate's attribute schema.\nconst SUBMARK_RE = /^(ir\\.transpile\\.mod|ir\\.deps\\.pkg)\\[[^\\]]+\\]$/;\nconst submarkAggregate = (name: string): IrMarkerName | null =>\n  name.startsWith(\"ir.transpile.mod\") ? \"ir.transpile\" : name.startsWith(\"ir.deps.pkg\") ? \"ir.deps\" : null;\n\n/** Is `name` a defined top-level `ir.*` marker (not a sub-mark)? */\nexport const isIrMarkerName = (name: string): name is IrMarkerName =>\n  Object.prototype.hasOwnProperty.call(IR_MARKERS, name);\n\n/** Is `name` an accepted marker name — a defined top-level marker OR a recognized\n *  per-module/per-dep sub-mark? */\nexport const isAllowedMarkerName = (name: string): boolean =>\n  isIrMarkerName(name) || SUBMARK_RE.test(name);\n\n/** A marker forwarded across the origin boundary (§3.2): a name, the sandbox-side\n *  `performance.now()` timestamp, and the optional attribute payload. */\nexport interface ForwardedMarker {\n  name: string;\n  /** Sandbox-relative timestamp (`performance.now()`) at emission (§3.2). */\n  at: number;\n  attrs?: Record<string, unknown>;\n}\n\n/**\n * The LP-5 vocabulary allowlist (pure). Accept a forwarded marker ONLY if its name\n * is in the vocabulary AND every attribute key is in that marker's schema. An\n * unknown name — or a defined name carrying an out-of-schema attribute key — is\n * DROPPED (returns `null`), never recorded. This is the gate against an untrusted\n * sandbox minting arbitrary names/values into the host timeline (an injection\n * surface for dashboards / the deferred RUM endpoint). Sub-marks inherit their\n * aggregate's schema.\n */\nexport function validateMarker(m: ForwardedMarker | null | undefined): ForwardedMarker | null {\n  if (!m || typeof m.name !== \"string\") return null;\n  if (typeof m.at !== \"number\" || !Number.isFinite(m.at)) return null;\n  if (!isAllowedMarkerName(m.name)) return null;\n  const base: IrMarkerName = isIrMarkerName(m.name) ? m.name : submarkAggregate(m.name)!;\n  const allowed: readonly string[] = IR_MARKERS[base];\n  const attrs = m.attrs;\n  if (attrs !== undefined) {\n    if (typeof attrs !== \"object\" || attrs === null) return null;\n    for (const key of Object.keys(attrs)) {\n      if (!allowed.includes(key)) return null; // out-of-schema attribute → drop the whole marker\n    }\n  }\n  return { name: m.name, at: m.at, ...(attrs !== undefined ? { attrs } : {}) };\n}\n\n/**\n * `ir.interactive = max(rootRenderCommit, reportReady)` (LP2-3). An app-called\n * `reportReady()` may only DELAY interactive — never advance it before the root\n * render commits. A `reportReady()` that fires early is recorded but takes effect\n * at the commit; if the app never reports, the commit alone stands. Budgets bind to\n * the later of the two, so an app can't game its budget by declaring itself ready\n * before it has rendered anything. PURE.\n */\nexport function resolveInteractive(rootRenderCommitAt: number, reportReadyAt?: number): number {\n  if (reportReadyAt === undefined) return rootRenderCommitAt;\n  return Math.max(rootRenderCommitAt, reportReadyAt);\n}\n"],"mappings":"AAgBO,MAAM,aAAa;AAAA,EACxB,WAAW,CAAC,OAAO,YAAY,MAAM,QAAQ,OAAO,SAAS;AAAA,EAC7D,YAAY,CAAC,UAAU,SAAS,gBAAgB,YAAY,YAAY;AAAA,EACxE,YAAY,CAAC,gBAAgB,gBAAgB;AAAA,EAC7C,mBAAmB,CAAC;AAAA,EACpB,gBAAgB,CAAC,eAAe,YAAY,WAAW,UAAU;AAAA,EACjE,WAAW,CAAC,YAAY,SAAS,gBAAgB,YAAY,KAAK;AAAA,EAClE,WAAW,CAAC,aAAa;AAAA,EACzB,UAAU,CAAC;AAAA,EACX,kBAAkB,CAAC,MAAM;AAAA,EACzB,aAAa,CAAC,UAAU,UAAU;AAAA,EAClC,cAAc,CAAC,OAAO;AACxB;AAOA,MAAM,aAAa;AACnB,MAAM,mBAAmB,CAAC,SACxB,KAAK,WAAW,kBAAkB,IAAI,iBAAiB,KAAK,WAAW,aAAa,IAAI,YAAY;AAG/F,MAAM,iBAAiB,CAAC,SAC7B,OAAO,UAAU,eAAe,KAAK,YAAY,IAAI;AAIhD,MAAM,sBAAsB,CAAC,SAClC,eAAe,IAAI,KAAK,WAAW,KAAK,IAAI;AAoBvC,SAAS,eAAe,GAA+D;AAC5F,MAAI,CAAC,KAAK,OAAO,EAAE,SAAS,SAAU,QAAO;AAC7C,MAAI,OAAO,EAAE,OAAO,YAAY,CAAC,OAAO,SAAS,EAAE,EAAE,EAAG,QAAO;AAC/D,MAAI,CAAC,oBAAoB,EAAE,IAAI,EAAG,QAAO;AACzC,QAAM,OAAqB,eAAe,EAAE,IAAI,IAAI,EAAE,OAAO,iBAAiB,EAAE,IAAI;AACpF,QAAM,UAA6B,WAAW,IAAI;AAClD,QAAM,QAAQ,EAAE;AAChB,MAAI,UAAU,QAAW;AACvB,QAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AACxD,eAAW,OAAO,OAAO,KAAK,KAAK,GAAG;AACpC,UAAI,CAAC,QAAQ,SAAS,GAAG,EAAG,QAAO;AAAA,IACrC;AAAA,EACF;AACA,SAAO,EAAE,MAAM,EAAE,MAAM,IAAI,EAAE,IAAI,GAAI,UAAU,SAAY,EAAE,MAAM,IAAI,CAAC,EAAG;AAC7E;AAUO,SAAS,mBAAmB,oBAA4B,eAAgC;AAC7F,MAAI,kBAAkB,OAAW,QAAO;AACxC,SAAO,KAAK,IAAI,oBAAoB,aAAa;AACnD;","names":[]}
+{"version":3,"sources":["../src/irMarkers.ts"],"sourcesContent":["// The `ir.*` load-profiling marker vocabulary + the host-side allowlist + the\n// `ir.interactive` precedence rule (LOAD_PROFILING_SPEC §3/§3.1, R3-46).\n//\n// This module is PURE and dependency-free on purpose: the spec (§3.1) requires the\n// host's vocabulary allowlist to be MIRRORED from this same definition (\"additions\n// to the vocabulary are spec amendments, mirrored in the host allowlist in the same\n// change\"). Keeping the table + validator here, with no transport/React imports,\n// lets the sandbox side (this SDK) and the host (site-main, its own mirrored copy)\n// share an identical contract that is unit-tested in both places.\n\n/**\n * Each `ir.*` marker name → the attribute keys its payload may carry (the §3\n * table). A forwarded marker is accepted only if BOTH its name is defined here AND\n * every attribute key it carries is in that marker's allowed set (LP-5). An empty\n * array means \"no attributes\" (a bare mark).\n */\nexport const IR_MARKERS = {\n  \"ir.open\": [\"url\", \"provider\", \"ns\", \"repo\", \"ref\", \"refKind\"],\n  \"ir.fetch\": [\"source\", \"bytes\", \"requestCount\", \"cacheHit\", \"httpStatus\"],\n  \"ir.mount\": [\"phantomCount\", \"writablePrimed\"],\n  \"ir.sandbox.boot\": [],\n  \"ir.transpile\": [\"moduleCount\", \"cacheHit\", \"bytesIn\", \"bytesOut\"],\n  \"ir.deps\": [\"depCount\", \"bytes\", \"requestCount\", \"cacheHit\", \"cdn\"],\n  \"ir.eval\": [\"moduleCount\"],\n  \"ir.fmp\": [],\n  \"ir.interactive\": [\"cold\"],\n  \"ir.verify\": [\"result\", \"blocking\"],\n  \"ir.refresh\": [\"bytes\"],\n} as const;\n\n/** A canonical `ir.*` load-profiling marker name (a key of {@link IR_MARKERS}). */\nexport type IrMarkerName = keyof typeof IR_MARKERS;\n\n// Per-module / per-dep sub-marks (§3): a defined aggregate plus a `[…]` selector,\n// e.g. `ir.transpile.mod[/src/App.tsx]` or `ir.deps.pkg[react@18.2.0]`. A sub-mark\n// inherits its aggregate's attribute schema.\nconst SUBMARK_RE = /^(ir\\.transpile\\.mod|ir\\.deps\\.pkg)\\[[^\\]]+\\]$/;\nconst submarkAggregate = (name: string): IrMarkerName | null =>\n  name.startsWith(\"ir.transpile.mod\") ? \"ir.transpile\" : name.startsWith(\"ir.deps.pkg\") ? \"ir.deps\" : null;\n\n/** Is `name` a defined top-level `ir.*` marker (not a sub-mark)? */\nexport const isIrMarkerName = (name: string): name is IrMarkerName =>\n  Object.prototype.hasOwnProperty.call(IR_MARKERS, name);\n\n/** Is `name` an accepted marker name — a defined top-level marker OR a recognized\n *  per-module/per-dep sub-mark? */\nexport const isAllowedMarkerName = (name: string): boolean =>\n  isIrMarkerName(name) || SUBMARK_RE.test(name);\n\n/** A marker forwarded across the origin boundary (§3.2): a name, the sandbox-side\n *  `performance.now()` timestamp, and the optional attribute payload. */\nexport interface ForwardedMarker {\n  name: string;\n  /** Sandbox-relative timestamp (`performance.now()`) at emission (§3.2). */\n  at: number;\n  attrs?: Record<string, unknown>;\n}\n\n/**\n * The LP-5 vocabulary allowlist (pure). Accept a forwarded marker ONLY if its name\n * is in the vocabulary AND every attribute key is in that marker's schema. An\n * unknown name — or a defined name carrying an out-of-schema attribute key — is\n * DROPPED (returns `null`), never recorded. This is the gate against an untrusted\n * sandbox minting arbitrary names/values into the host timeline (an injection\n * surface for dashboards / the deferred RUM endpoint). Sub-marks inherit their\n * aggregate's schema.\n */\nexport function validateMarker(m: ForwardedMarker | null | undefined): ForwardedMarker | null {\n  if (!m || typeof m.name !== \"string\") return null;\n  if (typeof m.at !== \"number\" || !Number.isFinite(m.at)) return null;\n  if (!isAllowedMarkerName(m.name)) return null;\n  const base: IrMarkerName = isIrMarkerName(m.name) ? m.name : submarkAggregate(m.name)!;\n  const allowed: readonly string[] = IR_MARKERS[base];\n  const attrs = m.attrs;\n  if (attrs !== undefined) {\n    if (typeof attrs !== \"object\" || attrs === null) return null;\n    for (const key of Object.keys(attrs)) {\n      if (!allowed.includes(key)) return null; // out-of-schema attribute → drop the whole marker\n    }\n  }\n  return { name: m.name, at: m.at, ...(attrs !== undefined ? { attrs } : {}) };\n}\n\n/**\n * `ir.interactive = max(rootRenderCommit, reportReady)` (LP2-3). An app-called\n * `reportReady()` may only DELAY interactive — never advance it before the root\n * render commits. A `reportReady()` that fires early is recorded but takes effect\n * at the commit; if the app never reports, the commit alone stands. Budgets bind to\n * the later of the two, so an app can't game its budget by declaring itself ready\n * before it has rendered anything. PURE.\n */\nexport function resolveInteractive(rootRenderCommitAt: number, reportReadyAt?: number): number {\n  if (reportReadyAt === undefined) return rootRenderCommitAt;\n  return Math.max(rootRenderCommitAt, reportReadyAt);\n}\n"],"mappings":"AAgBO,MAAM,aAAa;AAAA,EACxB,WAAW,CAAC,OAAO,YAAY,MAAM,QAAQ,OAAO,SAAS;AAAA,EAC7D,YAAY,CAAC,UAAU,SAAS,gBAAgB,YAAY,YAAY;AAAA,EACxE,YAAY,CAAC,gBAAgB,gBAAgB;AAAA,EAC7C,mBAAmB,CAAC;AAAA,EACpB,gBAAgB,CAAC,eAAe,YAAY,WAAW,UAAU;AAAA,EACjE,WAAW,CAAC,YAAY,SAAS,gBAAgB,YAAY,KAAK;AAAA,EAClE,WAAW,CAAC,aAAa;AAAA,EACzB,UAAU,CAAC;AAAA,EACX,kBAAkB,CAAC,MAAM;AAAA,EACzB,aAAa,CAAC,UAAU,UAAU;AAAA,EAClC,cAAc,CAAC,OAAO;AACxB;AAQA,MAAM,aAAa;AACnB,MAAM,mBAAmB,CAAC,SACxB,KAAK,WAAW,kBAAkB,IAAI,iBAAiB,KAAK,WAAW,aAAa,IAAI,YAAY;AAG/F,MAAM,iBAAiB,CAAC,SAC7B,OAAO,UAAU,eAAe,KAAK,YAAY,IAAI;AAIhD,MAAM,sBAAsB,CAAC,SAClC,eAAe,IAAI,KAAK,WAAW,KAAK,IAAI;AAoBvC,SAAS,eAAe,GAA+D;AAC5F,MAAI,CAAC,KAAK,OAAO,EAAE,SAAS,SAAU,QAAO;AAC7C,MAAI,OAAO,EAAE,OAAO,YAAY,CAAC,OAAO,SAAS,EAAE,EAAE,EAAG,QAAO;AAC/D,MAAI,CAAC,oBAAoB,EAAE,IAAI,EAAG,QAAO;AACzC,QAAM,OAAqB,eAAe,EAAE,IAAI,IAAI,EAAE,OAAO,iBAAiB,EAAE,IAAI;AACpF,QAAM,UAA6B,WAAW,IAAI;AAClD,QAAM,QAAQ,EAAE;AAChB,MAAI,UAAU,QAAW;AACvB,QAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AACxD,eAAW,OAAO,OAAO,KAAK,KAAK,GAAG;AACpC,UAAI,CAAC,QAAQ,SAAS,GAAG,EAAG,QAAO;AAAA,IACrC;AAAA,EACF;AACA,SAAO,EAAE,MAAM,EAAE,MAAM,IAAI,EAAE,IAAI,GAAI,UAAU,SAAY,EAAE,MAAM,IAAI,CAAC,EAAG;AAC7E;AAUO,SAAS,mBAAmB,oBAA4B,eAAgC;AAC7F,MAAI,kBAAkB,OAAW,QAAO;AACxC,SAAO,KAAK,IAAI,oBAAoB,aAAa;AACnD;","names":[]}

package/dist/llm.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/llm.ts"],"sourcesContent":["// Provider-agnostic LLM chat — the `llm.chat@1` slot (SERVICE_PROVIDERS_SPEC;\n// LLM_AND_AGENTS_SPEC §8 D5).\n//\n// An app calls ONE chat slot and never worries about which provider the user has a\n// key for: the HOST resolves which vendor answers from the key the user holds\n// (`SecretView.boundOrigin`) plus their `preferredImplementation` choice, normalizes\n// the wire format, injects the key host-side at the §6 net:fetch point (the\n// look-at-nothing proxy), and streams normalized deltas back. The app never names a\n// vendor, never sees the key, and needs NO `net:fetch`/`secrets` grant of its own —\n// only the `llm:chat` capability (elevated, app-scoped: a fork earns it by consent).\n//\n// Inert until the host implements `protocol-llm` (the `chat` stream) + the\n// `llm-provider` describe channel; the contract ships here so apps (the file-explorer\n// summarize fork) can be written against it — exactly how `secrets.ts` shipped ahead\n// of `protocol-secrets`.\nimport { invokeStream } from './catalog';\nimport { createPushChannel } from './pushChannel';\n\nexport type ChatRole = 'system' | 'user' | 'assistant' | 'tool';\n\n/** A part of a message. `image` is only honored when the resolved provider\n *  advertises `features.vision` (§2.5) — branch on {@link describeChat} first. */\nexport type ContentPart =\n  | { type: 'text'; text: string }\n  | { type: 'image'; mimeType: string; data: string }; // data: base64, no data: URL prefix\n\nexport interface ChatMessage {\n  role: ChatRole;\n  content: ContentPart[];\n}\n\n/** A tool the model may call — honored only when `features.tools`. */\nexport interface ToolDef {\n  name: string;\n  description?: string;\n  /** JSON-Schema for the tool's arguments. */\n  inputSchema: Record<string, unknown>;\n}\n\nexport interface ChatRequest {\n  messages: ChatMessage[];\n  /** Honored only when the resolved provider advertises `features.tools`. */\n  tools?: ToolDef[];\n  /** `'json'` honored only when `features.jsonMode`. Defaults to `'text'`. */\n  responseFormat?: 'text' | 'json';\n  maxTokens?: number;\n  /** An ABSTRACT tier hint, never a vendor model id — the host maps it to a concrete\n   *  model on the resolved provider. Omit to take the provider's default. */\n  modelHint?: 'fast' | 'smart';\n}\n\n/** One streamed chunk. Consumers typically accumulate `text-delta`s. */\nexport type ChatDelta =\n  | { type: 'text-delta'; text: string }\n  | { type: 'tool-call'; id: string; name: string; input: unknown }\n  | { type: 'usage'; inputTokens: number; outputTokens: number };\n\nexport type ChatStopReason = 'end' | 'length' | 'tool' | 'filtered';\n\n/** The terminal value of the {@link chat} stream. */\nexport interface ChatResult {\n  stopReason: ChatStopReason;\n}\n\n/**\n * Stream a chat completion from whichever provider the user has configured.\n *\n * ```ts\n * let summary = '';\n * for await (const d of chat({ messages: [{ role: 'user', content: [{ type: 'text', text }] }] })) {\n *   if (d.type === 'text-delta') summary += d.text;\n * }\n * ```\n *\n * Requires the `llm:chat` capability. If no provider is bound the host fails the\n * stream into the SP-7 connect-me prompt (the user adds a key) — the generator\n * throws with `code: 'auth-required'`; an un-granted call throws `forbidden`.\n */\nexport function chat(req: ChatRequest): AsyncGenerator<ChatDelta, ChatResult, void> {\n  return invokeStream<ChatDelta, ChatResult>('llm:chat', req as unknown as Record<string, unknown>);\n}\n\n/** The resolved provider's advertised abilities (SERVICE_PROVIDERS_SPEC §2.5) — read\n *  to branch/degrade (offer image upload only when `vision`). */\nexport interface ChatFeatures {\n  vision: boolean;\n  tools: boolean;\n  jsonMode: boolean;\n  maxContextTokens: number;\n}\n\n/** Info about the provider the host resolved for this app. `null` when no provider\n *  is bound (SP-7: prompt the user to add a key before calling {@link chat}). */\nexport interface ChatProviderInfo {\n  /** Opaque provider id, e.g. `llm.chat.anthropic` — never a vendor secret or model id. */\n  providerId: string;\n  /** True for Host-proxied providers (host-vouched, SP-9); false for app-level ones,\n   *  whose `features` are an untrusted claim. */\n  hostVouched: boolean;\n  features: ChatFeatures;\n}\n\n// The `llm-provider` describe channel (Recipe A): the host pushes the resolved\n// provider info on change and replays it on register-frame, gated by `llm:chat`.\n// A message with no `provider` key is ignored; an explicit `null` means \"no provider\n// bound\" (distinct from \"not yet answered\", which keeps the `initial` null).\nconst channel = createPushChannel<ChatProviderInfo | null>({\n  pushType: 'llm-provider',\n  requestType: 'request-llm-provider',\n  initial: null,\n  parse: (msg) =>\n    'provider' in msg ? (msg.provider as ChatProviderInfo | null) : undefined,\n});\n\n/** The provider the host resolved for this app (or `null` if none bound). Poll for a\n *  one-off read; use {@link onChatProviderChange}/{@link useChatProvider} to react. */\nexport const describeChat = (): ChatProviderInfo | null => channel.get();\n\n/** Subscribe to provider changes (key added/revoked, preference changed). Invoked\n *  immediately with the current value, then on every change. Returns unsubscribe. */\nexport const onChatProviderChange = (\n  listener: (provider: ChatProviderInfo | null) => void,\n): (() => void) => channel.onChange(listener);\n\n/** React hook returning the resolved chat provider (or `null`), re-rendering on\n *  change — gate the summarize affordance on `provider !== null`. */\nexport const useChatProvider = (): ChatProviderInfo | null => channel.use();\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAeA,qBAA6B;AAC7B,yBAAkC;AA8D3B,SAAS,KAAK,KAA+D;AAClF,aAAO,6BAAoC,YAAY,GAAyC;AAClG;AA0BA,MAAM,cAAU,sCAA2C;AAAA,EACzD,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QACN,cAAc,MAAO,IAAI,WAAuC;AACpE,CAAC;AAIM,MAAM,eAAe,MAA+B,QAAQ,IAAI;AAIhE,MAAM,uBAAuB,CAClC,aACiB,QAAQ,SAAS,QAAQ;AAIrC,MAAM,kBAAkB,MAA+B,QAAQ,IAAI;","names":[]}
+{"version":3,"sources":["../src/llm.ts"],"sourcesContent":["// Provider-agnostic LLM chat — the `llm.chat@1` slot (SERVICE_PROVIDERS_SPEC;\n// LLM_AND_AGENTS_SPEC §8 D5).\n//\n// An app calls ONE chat slot and never worries about which provider the user has a\n// key for: the HOST resolves which vendor answers from the key the user holds\n// (`SecretView.boundOrigin`) plus their `preferredImplementation` choice, normalizes\n// the wire format, injects the key host-side at the §6 net:fetch point (the\n// look-at-nothing proxy), and streams normalized deltas back. The app never names a\n// vendor, never sees the key, and needs NO `net:fetch`/`secrets` grant of its own —\n// only the `llm:chat` capability (elevated, app-scoped: a fork earns it by consent).\n//\n// Inert until the host implements `protocol-llm` (the `chat` stream) + the\n// `llm-provider` describe channel; the contract ships here so apps (the file-explorer\n// summarize fork) can be written against it — exactly how `secrets.ts` shipped ahead\n// of `protocol-secrets`.\nimport { invokeStream } from './catalog';\nimport { createPushChannel } from './pushChannel';\n\n/** Who authored a {@link ChatMessage}. */\nexport type ChatRole = 'system' | 'user' | 'assistant' | 'tool';\n\n/** A part of a message. `image` is only honored when the resolved provider\n *  advertises `features.vision` (§2.5) — branch on {@link describeChat} first. */\nexport type ContentPart =\n  | { type: 'text'; text: string }\n  | { type: 'image'; mimeType: string; data: string }; // data: base64, no data: URL prefix\n\n/** One message in a {@link ChatRequest}: a role plus its content parts. */\nexport interface ChatMessage {\n  role: ChatRole;\n  content: ContentPart[];\n}\n\n/** A tool the model may call — honored only when `features.tools`. */\nexport interface ToolDef {\n  name: string;\n  description?: string;\n  /** JSON-Schema for the tool's arguments. */\n  inputSchema: Record<string, unknown>;\n}\n\n/** A host-brokered chat completion request: the messages plus optional tools,\n *  response format, and model hint (each honored per the provider's features). */\nexport interface ChatRequest {\n  messages: ChatMessage[];\n  /** Honored only when the resolved provider advertises `features.tools`. */\n  tools?: ToolDef[];\n  /** `'json'` honored only when `features.jsonMode`. Defaults to `'text'`. */\n  responseFormat?: 'text' | 'json';\n  maxTokens?: number;\n  /** An ABSTRACT tier hint, never a vendor model id — the host maps it to a concrete\n   *  model on the resolved provider. Omit to take the provider's default. */\n  modelHint?: 'fast' | 'smart';\n}\n\n/** One streamed chunk. Consumers typically accumulate `text-delta`s. */\nexport type ChatDelta =\n  | { type: 'text-delta'; text: string }\n  | { type: 'tool-call'; id: string; name: string; input: unknown }\n  | { type: 'usage'; inputTokens: number; outputTokens: number };\n\n/** Why generation stopped: natural `end`, `length` cap, a `tool` call, or content `filtered`. */\nexport type ChatStopReason = 'end' | 'length' | 'tool' | 'filtered';\n\n/** The terminal value of the {@link chat} stream. */\nexport interface ChatResult {\n  stopReason: ChatStopReason;\n}\n\n/**\n * Stream a chat completion from whichever provider the user has configured.\n *\n * ```ts\n * let summary = '';\n * for await (const d of chat({ messages: [{ role: 'user', content: [{ type: 'text', text }] }] })) {\n *   if (d.type === 'text-delta') summary += d.text;\n * }\n * ```\n *\n * Requires the `llm:chat` capability. If no provider is bound the host fails the\n * stream into the SP-7 connect-me prompt (the user adds a key) — the generator\n * throws with `code: 'auth-required'`; an un-granted call throws `forbidden`.\n */\nexport function chat(req: ChatRequest): AsyncGenerator<ChatDelta, ChatResult, void> {\n  return invokeStream<ChatDelta, ChatResult>('llm:chat', req as unknown as Record<string, unknown>);\n}\n\n/** The resolved provider's advertised abilities (SERVICE_PROVIDERS_SPEC §2.5) — read\n *  to branch/degrade (offer image upload only when `vision`). */\nexport interface ChatFeatures {\n  vision: boolean;\n  tools: boolean;\n  jsonMode: boolean;\n  maxContextTokens: number;\n}\n\n/** Info about the provider the host resolved for this app. `null` when no provider\n *  is bound (SP-7: prompt the user to add a key before calling {@link chat}). */\nexport interface ChatProviderInfo {\n  /** Opaque provider id, e.g. `llm.chat.anthropic` — never a vendor secret or model id. */\n  providerId: string;\n  /** True for Host-proxied providers (host-vouched, SP-9); false for app-level ones,\n   *  whose `features` are an untrusted claim. */\n  hostVouched: boolean;\n  features: ChatFeatures;\n}\n\n// The `llm-provider` describe channel (Recipe A): the host pushes the resolved\n// provider info on change and replays it on register-frame, gated by `llm:chat`.\n// A message with no `provider` key is ignored; an explicit `null` means \"no provider\n// bound\" (distinct from \"not yet answered\", which keeps the `initial` null).\nconst channel = createPushChannel<ChatProviderInfo | null>({\n  pushType: 'llm-provider',\n  requestType: 'request-llm-provider',\n  initial: null,\n  parse: (msg) =>\n    'provider' in msg ? (msg.provider as ChatProviderInfo | null) : undefined,\n});\n\n/** The provider the host resolved for this app (or `null` if none bound). Poll for a\n *  one-off read; use {@link onChatProviderChange}/{@link useChatProvider} to react. */\nexport const describeChat = (): ChatProviderInfo | null => channel.get();\n\n/** Subscribe to provider changes (key added/revoked, preference changed). Invoked\n *  immediately with the current value, then on every change. Returns unsubscribe. */\nexport const onChatProviderChange = (\n  listener: (provider: ChatProviderInfo | null) => void,\n): (() => void) => channel.onChange(listener);\n\n/** React hook returning the resolved chat provider (or `null`), re-rendering on\n *  change — gate the summarize affordance on `provider !== null`. */\nexport const useChatProvider = (): ChatProviderInfo | null => channel.use();\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAeA,qBAA6B;AAC7B,yBAAkC;AAmE3B,SAAS,KAAK,KAA+D;AAClF,aAAO,6BAAoC,YAAY,GAAyC;AAClG;AA0BA,MAAM,cAAU,sCAA2C;AAAA,EACzD,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QACN,cAAc,MAAO,IAAI,WAAuC;AACpE,CAAC;AAIM,MAAM,eAAe,MAA+B,QAAQ,IAAI;AAIhE,MAAM,uBAAuB,CAClC,aACiB,QAAQ,SAAS,QAAQ;AAIrC,MAAM,kBAAkB,MAA+B,QAAQ,IAAI;","names":[]}

package/dist/llm.d.cts

@@ -1,3 +1,4 @@
+/** Who authored a {@link ChatMessage}. */
 type ChatRole = 'system' | 'user' | 'assistant' | 'tool';
 /** A part of a message. `image` is only honored when the resolved provider
  *  advertises `features.vision` (§2.5) — branch on {@link describeChat} first. */
@@ -9,6 +10,7 @@ type ContentPart = {
     mimeType: string;
     data: string;
 };
+/** One message in a {@link ChatRequest}: a role plus its content parts. */
 interface ChatMessage {
     role: ChatRole;
     content: ContentPart[];
@@ -20,6 +22,8 @@ interface ToolDef {
     /** JSON-Schema for the tool's arguments. */
     inputSchema: Record<string, unknown>;
 }
+/** A host-brokered chat completion request: the messages plus optional tools,
+ *  response format, and model hint (each honored per the provider's features). */
 interface ChatRequest {
     messages: ChatMessage[];
     /** Honored only when the resolved provider advertises `features.tools`. */
@@ -45,6 +49,7 @@ type ChatDelta = {
     inputTokens: number;
     outputTokens: number;
 };
+/** Why generation stopped: natural `end`, `length` cap, a `tool` call, or content `filtered`. */
 type ChatStopReason = 'end' | 'length' | 'tool' | 'filtered';
 /** The terminal value of the {@link chat} stream. */
 interface ChatResult {

package/dist/llm.d.ts

@@ -1,3 +1,4 @@
+/** Who authored a {@link ChatMessage}. */
 type ChatRole = 'system' | 'user' | 'assistant' | 'tool';
 /** A part of a message. `image` is only honored when the resolved provider
  *  advertises `features.vision` (§2.5) — branch on {@link describeChat} first. */
@@ -9,6 +10,7 @@ type ContentPart = {
     mimeType: string;
     data: string;
 };
+/** One message in a {@link ChatRequest}: a role plus its content parts. */
 interface ChatMessage {
     role: ChatRole;
     content: ContentPart[];
@@ -20,6 +22,8 @@ interface ToolDef {
     /** JSON-Schema for the tool's arguments. */
     inputSchema: Record<string, unknown>;
 }
+/** A host-brokered chat completion request: the messages plus optional tools,
+ *  response format, and model hint (each honored per the provider's features). */
 interface ChatRequest {
     messages: ChatMessage[];
     /** Honored only when the resolved provider advertises `features.tools`. */
@@ -45,6 +49,7 @@ type ChatDelta = {
     inputTokens: number;
     outputTokens: number;
 };
+/** Why generation stopped: natural `end`, `length` cap, a `tool` call, or content `filtered`. */
 type ChatStopReason = 'end' | 'length' | 'tool' | 'filtered';
 /** The terminal value of the {@link chat} stream. */
 interface ChatResult {

package/dist/llm.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/llm.ts"],"sourcesContent":["// Provider-agnostic LLM chat — the `llm.chat@1` slot (SERVICE_PROVIDERS_SPEC;\n// LLM_AND_AGENTS_SPEC §8 D5).\n//\n// An app calls ONE chat slot and never worries about which provider the user has a\n// key for: the HOST resolves which vendor answers from the key the user holds\n// (`SecretView.boundOrigin`) plus their `preferredImplementation` choice, normalizes\n// the wire format, injects the key host-side at the §6 net:fetch point (the\n// look-at-nothing proxy), and streams normalized deltas back. The app never names a\n// vendor, never sees the key, and needs NO `net:fetch`/`secrets` grant of its own —\n// only the `llm:chat` capability (elevated, app-scoped: a fork earns it by consent).\n//\n// Inert until the host implements `protocol-llm` (the `chat` stream) + the\n// `llm-provider` describe channel; the contract ships here so apps (the file-explorer\n// summarize fork) can be written against it — exactly how `secrets.ts` shipped ahead\n// of `protocol-secrets`.\nimport { invokeStream } from './catalog';\nimport { createPushChannel } from './pushChannel';\n\nexport type ChatRole = 'system' | 'user' | 'assistant' | 'tool';\n\n/** A part of a message. `image` is only honored when the resolved provider\n *  advertises `features.vision` (§2.5) — branch on {@link describeChat} first. */\nexport type ContentPart =\n  | { type: 'text'; text: string }\n  | { type: 'image'; mimeType: string; data: string }; // data: base64, no data: URL prefix\n\nexport interface ChatMessage {\n  role: ChatRole;\n  content: ContentPart[];\n}\n\n/** A tool the model may call — honored only when `features.tools`. */\nexport interface ToolDef {\n  name: string;\n  description?: string;\n  /** JSON-Schema for the tool's arguments. */\n  inputSchema: Record<string, unknown>;\n}\n\nexport interface ChatRequest {\n  messages: ChatMessage[];\n  /** Honored only when the resolved provider advertises `features.tools`. */\n  tools?: ToolDef[];\n  /** `'json'` honored only when `features.jsonMode`. Defaults to `'text'`. */\n  responseFormat?: 'text' | 'json';\n  maxTokens?: number;\n  /** An ABSTRACT tier hint, never a vendor model id — the host maps it to a concrete\n   *  model on the resolved provider. Omit to take the provider's default. */\n  modelHint?: 'fast' | 'smart';\n}\n\n/** One streamed chunk. Consumers typically accumulate `text-delta`s. */\nexport type ChatDelta =\n  | { type: 'text-delta'; text: string }\n  | { type: 'tool-call'; id: string; name: string; input: unknown }\n  | { type: 'usage'; inputTokens: number; outputTokens: number };\n\nexport type ChatStopReason = 'end' | 'length' | 'tool' | 'filtered';\n\n/** The terminal value of the {@link chat} stream. */\nexport interface ChatResult {\n  stopReason: ChatStopReason;\n}\n\n/**\n * Stream a chat completion from whichever provider the user has configured.\n *\n * ```ts\n * let summary = '';\n * for await (const d of chat({ messages: [{ role: 'user', content: [{ type: 'text', text }] }] })) {\n *   if (d.type === 'text-delta') summary += d.text;\n * }\n * ```\n *\n * Requires the `llm:chat` capability. If no provider is bound the host fails the\n * stream into the SP-7 connect-me prompt (the user adds a key) — the generator\n * throws with `code: 'auth-required'`; an un-granted call throws `forbidden`.\n */\nexport function chat(req: ChatRequest): AsyncGenerator<ChatDelta, ChatResult, void> {\n  return invokeStream<ChatDelta, ChatResult>('llm:chat', req as unknown as Record<string, unknown>);\n}\n\n/** The resolved provider's advertised abilities (SERVICE_PROVIDERS_SPEC §2.5) — read\n *  to branch/degrade (offer image upload only when `vision`). */\nexport interface ChatFeatures {\n  vision: boolean;\n  tools: boolean;\n  jsonMode: boolean;\n  maxContextTokens: number;\n}\n\n/** Info about the provider the host resolved for this app. `null` when no provider\n *  is bound (SP-7: prompt the user to add a key before calling {@link chat}). */\nexport interface ChatProviderInfo {\n  /** Opaque provider id, e.g. `llm.chat.anthropic` — never a vendor secret or model id. */\n  providerId: string;\n  /** True for Host-proxied providers (host-vouched, SP-9); false for app-level ones,\n   *  whose `features` are an untrusted claim. */\n  hostVouched: boolean;\n  features: ChatFeatures;\n}\n\n// The `llm-provider` describe channel (Recipe A): the host pushes the resolved\n// provider info on change and replays it on register-frame, gated by `llm:chat`.\n// A message with no `provider` key is ignored; an explicit `null` means \"no provider\n// bound\" (distinct from \"not yet answered\", which keeps the `initial` null).\nconst channel = createPushChannel<ChatProviderInfo | null>({\n  pushType: 'llm-provider',\n  requestType: 'request-llm-provider',\n  initial: null,\n  parse: (msg) =>\n    'provider' in msg ? (msg.provider as ChatProviderInfo | null) : undefined,\n});\n\n/** The provider the host resolved for this app (or `null` if none bound). Poll for a\n *  one-off read; use {@link onChatProviderChange}/{@link useChatProvider} to react. */\nexport const describeChat = (): ChatProviderInfo | null => channel.get();\n\n/** Subscribe to provider changes (key added/revoked, preference changed). Invoked\n *  immediately with the current value, then on every change. Returns unsubscribe. */\nexport const onChatProviderChange = (\n  listener: (provider: ChatProviderInfo | null) => void,\n): (() => void) => channel.onChange(listener);\n\n/** React hook returning the resolved chat provider (or `null`), re-rendering on\n *  change — gate the summarize affordance on `provider !== null`. */\nexport const useChatProvider = (): ChatProviderInfo | null => channel.use();\n"],"mappings":"AAeA,SAAS,oBAAoB;AAC7B,SAAS,yBAAyB;AA8D3B,SAAS,KAAK,KAA+D;AAClF,SAAO,aAAoC,YAAY,GAAyC;AAClG;AA0BA,MAAM,UAAU,kBAA2C;AAAA,EACzD,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QACN,cAAc,MAAO,IAAI,WAAuC;AACpE,CAAC;AAIM,MAAM,eAAe,MAA+B,QAAQ,IAAI;AAIhE,MAAM,uBAAuB,CAClC,aACiB,QAAQ,SAAS,QAAQ;AAIrC,MAAM,kBAAkB,MAA+B,QAAQ,IAAI;","names":[]}
+{"version":3,"sources":["../src/llm.ts"],"sourcesContent":["// Provider-agnostic LLM chat — the `llm.chat@1` slot (SERVICE_PROVIDERS_SPEC;\n// LLM_AND_AGENTS_SPEC §8 D5).\n//\n// An app calls ONE chat slot and never worries about which provider the user has a\n// key for: the HOST resolves which vendor answers from the key the user holds\n// (`SecretView.boundOrigin`) plus their `preferredImplementation` choice, normalizes\n// the wire format, injects the key host-side at the §6 net:fetch point (the\n// look-at-nothing proxy), and streams normalized deltas back. The app never names a\n// vendor, never sees the key, and needs NO `net:fetch`/`secrets` grant of its own —\n// only the `llm:chat` capability (elevated, app-scoped: a fork earns it by consent).\n//\n// Inert until the host implements `protocol-llm` (the `chat` stream) + the\n// `llm-provider` describe channel; the contract ships here so apps (the file-explorer\n// summarize fork) can be written against it — exactly how `secrets.ts` shipped ahead\n// of `protocol-secrets`.\nimport { invokeStream } from './catalog';\nimport { createPushChannel } from './pushChannel';\n\n/** Who authored a {@link ChatMessage}. */\nexport type ChatRole = 'system' | 'user' | 'assistant' | 'tool';\n\n/** A part of a message. `image` is only honored when the resolved provider\n *  advertises `features.vision` (§2.5) — branch on {@link describeChat} first. */\nexport type ContentPart =\n  | { type: 'text'; text: string }\n  | { type: 'image'; mimeType: string; data: string }; // data: base64, no data: URL prefix\n\n/** One message in a {@link ChatRequest}: a role plus its content parts. */\nexport interface ChatMessage {\n  role: ChatRole;\n  content: ContentPart[];\n}\n\n/** A tool the model may call — honored only when `features.tools`. */\nexport interface ToolDef {\n  name: string;\n  description?: string;\n  /** JSON-Schema for the tool's arguments. */\n  inputSchema: Record<string, unknown>;\n}\n\n/** A host-brokered chat completion request: the messages plus optional tools,\n *  response format, and model hint (each honored per the provider's features). */\nexport interface ChatRequest {\n  messages: ChatMessage[];\n  /** Honored only when the resolved provider advertises `features.tools`. */\n  tools?: ToolDef[];\n  /** `'json'` honored only when `features.jsonMode`. Defaults to `'text'`. */\n  responseFormat?: 'text' | 'json';\n  maxTokens?: number;\n  /** An ABSTRACT tier hint, never a vendor model id — the host maps it to a concrete\n   *  model on the resolved provider. Omit to take the provider's default. */\n  modelHint?: 'fast' | 'smart';\n}\n\n/** One streamed chunk. Consumers typically accumulate `text-delta`s. */\nexport type ChatDelta =\n  | { type: 'text-delta'; text: string }\n  | { type: 'tool-call'; id: string; name: string; input: unknown }\n  | { type: 'usage'; inputTokens: number; outputTokens: number };\n\n/** Why generation stopped: natural `end`, `length` cap, a `tool` call, or content `filtered`. */\nexport type ChatStopReason = 'end' | 'length' | 'tool' | 'filtered';\n\n/** The terminal value of the {@link chat} stream. */\nexport interface ChatResult {\n  stopReason: ChatStopReason;\n}\n\n/**\n * Stream a chat completion from whichever provider the user has configured.\n *\n * ```ts\n * let summary = '';\n * for await (const d of chat({ messages: [{ role: 'user', content: [{ type: 'text', text }] }] })) {\n *   if (d.type === 'text-delta') summary += d.text;\n * }\n * ```\n *\n * Requires the `llm:chat` capability. If no provider is bound the host fails the\n * stream into the SP-7 connect-me prompt (the user adds a key) — the generator\n * throws with `code: 'auth-required'`; an un-granted call throws `forbidden`.\n */\nexport function chat(req: ChatRequest): AsyncGenerator<ChatDelta, ChatResult, void> {\n  return invokeStream<ChatDelta, ChatResult>('llm:chat', req as unknown as Record<string, unknown>);\n}\n\n/** The resolved provider's advertised abilities (SERVICE_PROVIDERS_SPEC §2.5) — read\n *  to branch/degrade (offer image upload only when `vision`). */\nexport interface ChatFeatures {\n  vision: boolean;\n  tools: boolean;\n  jsonMode: boolean;\n  maxContextTokens: number;\n}\n\n/** Info about the provider the host resolved for this app. `null` when no provider\n *  is bound (SP-7: prompt the user to add a key before calling {@link chat}). */\nexport interface ChatProviderInfo {\n  /** Opaque provider id, e.g. `llm.chat.anthropic` — never a vendor secret or model id. */\n  providerId: string;\n  /** True for Host-proxied providers (host-vouched, SP-9); false for app-level ones,\n   *  whose `features` are an untrusted claim. */\n  hostVouched: boolean;\n  features: ChatFeatures;\n}\n\n// The `llm-provider` describe channel (Recipe A): the host pushes the resolved\n// provider info on change and replays it on register-frame, gated by `llm:chat`.\n// A message with no `provider` key is ignored; an explicit `null` means \"no provider\n// bound\" (distinct from \"not yet answered\", which keeps the `initial` null).\nconst channel = createPushChannel<ChatProviderInfo | null>({\n  pushType: 'llm-provider',\n  requestType: 'request-llm-provider',\n  initial: null,\n  parse: (msg) =>\n    'provider' in msg ? (msg.provider as ChatProviderInfo | null) : undefined,\n});\n\n/** The provider the host resolved for this app (or `null` if none bound). Poll for a\n *  one-off read; use {@link onChatProviderChange}/{@link useChatProvider} to react. */\nexport const describeChat = (): ChatProviderInfo | null => channel.get();\n\n/** Subscribe to provider changes (key added/revoked, preference changed). Invoked\n *  immediately with the current value, then on every change. Returns unsubscribe. */\nexport const onChatProviderChange = (\n  listener: (provider: ChatProviderInfo | null) => void,\n): (() => void) => channel.onChange(listener);\n\n/** React hook returning the resolved chat provider (or `null`), re-rendering on\n *  change — gate the summarize affordance on `provider !== null`. */\nexport const useChatProvider = (): ChatProviderInfo | null => channel.use();\n"],"mappings":"AAeA,SAAS,oBAAoB;AAC7B,SAAS,yBAAyB;AAmE3B,SAAS,KAAK,KAA+D;AAClF,SAAO,aAAoC,YAAY,GAAyC;AAClG;AA0BA,MAAM,UAAU,kBAA2C;AAAA,EACzD,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QACN,cAAc,MAAO,IAAI,WAAuC;AACpE,CAAC;AAIM,MAAM,eAAe,MAA+B,QAAQ,IAAI;AAIhE,MAAM,uBAAuB,CAClC,aACiB,QAAQ,SAAS,QAAQ;AAIrC,MAAM,kBAAkB,MAA+B,QAAQ,IAAI;","names":[]}

package/dist/loading.cjs

@@ -0,0 +1,186 @@
+"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 loading_exports = {};
+__export(loading_exports, {
+  LOADING_TIMINGS: () => LOADING_TIMINGS,
+  LoadingRegion: () => LoadingRegion,
+  Skeleton: () => Skeleton,
+  SkeletonRow: () => SkeletonRow,
+  Spinner: () => Spinner
+});
+module.exports = __toCommonJS(loading_exports);
+var import_jsx_runtime = require("react/jsx-runtime");
+var import_react = require("react");
+const LOADING_TIMINGS = {
+  /** Below this, NO spinner appears — a fast wait never flashes one (§6.2 floor). */
+  spinThresholdMs: 150,
+  /** The reveal cross-fade duration the host uses. */
+  fadeMs: 150,
+  /** One slow shimmer sweep across a placeholder. */
+  shimmerMs: 1900
+};
+const STYLE_ID = "ir-sdk-loading-styles";
+const STYLE_TEXT = `
+@keyframes ir-sdk-sweep{0%{transform:translateX(-130%)}60%,100%{transform:translateX(130%)}}
+@keyframes ir-sdk-spin{to{transform:rotate(360deg)}}
+.ir-sdk-shim{position:relative;overflow:hidden}
+.ir-sdk-shim::after{content:"";position:absolute;inset:0;background:linear-gradient(100deg,transparent 28%,rgba(127,127,127,.18) 50%,transparent 72%);transform:translateX(-130%);animation:ir-sdk-sweep ${LOADING_TIMINGS.shimmerMs}ms ease-in-out infinite}
+.ir-sdk-spin{animation:ir-sdk-spin .8s linear infinite}
+@media (prefers-reduced-motion:reduce){.ir-sdk-shim::after{display:none}.ir-sdk-spin{animation:none}}
+`;
+function ensureLoadingStyles() {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(STYLE_ID)) return;
+  const el = document.createElement("style");
+  el.id = STYLE_ID;
+  el.textContent = STYLE_TEXT;
+  document.head.appendChild(el);
+}
+function useLoadingStyles() {
+  (0, import_react.useLayoutEffect)(() => {
+    ensureLoadingStyles();
+  }, []);
+}
+const PLACEHOLDER = {
+  background: "rgba(127,127,127,0.20)",
+  borderRadius: 6
+};
+function SkeletonRow({
+  width = "100%",
+  height = 12,
+  style
+}) {
+  useLoadingStyles();
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    "div",
+    {
+      className: "ir-sdk-shim",
+      "aria-hidden": "true",
+      style: { ...PLACEHOLDER, width, height, ...style }
+    }
+  );
+}
+function rows(specs) {
+  return specs.map(({ key, ...s }) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "ir-sdk-shim", "aria-hidden": "true", style: { ...PLACEHOLDER, ...s } }, key));
+}
+function Skeleton({
+  archetype = "generic",
+  style
+}) {
+  useLoadingStyles();
+  const wrap = {
+    display: "flex",
+    flexDirection: "column",
+    gap: 10,
+    padding: 12,
+    width: "100%",
+    boxSizing: "border-box",
+    ...style
+  };
+  let body;
+  switch (archetype) {
+    case "panel.list":
+      body = rows([0, 1, 2, 3, 4].map((key) => ({ key, height: 14 })));
+      break;
+    case "panel.tree":
+      body = rows([0, 1, 2, 3, 4].map((key) => ({ key, height: 14, marginLeft: key % 3 * 16 })));
+      break;
+    case "panel.editor":
+      body = rows([62, 88, 73, 41, 80].map((w, key) => ({ key, height: 11, width: `${w}%` })));
+      break;
+    case "panel.conversation":
+      body = rows(
+        [0, 1, 2, 3].map((key) => ({
+          key,
+          height: 40,
+          width: "70%",
+          borderRadius: 12,
+          alignSelf: key % 2 ? "flex-end" : "flex-start"
+        }))
+      );
+      break;
+    case "generic":
+    default:
+      body = /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "ir-sdk-shim", "aria-hidden": "true", style: { ...PLACEHOLDER, height: 16, width: "45%", borderRadius: 4 } }),
+        rows([0, 1].map((key) => ({ key, height: 56, borderRadius: 8 })))
+      ] });
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { "aria-hidden": "true", style: wrap, children: body });
+}
+function useDelayedFlag(ms) {
+  const [on, setOn] = (0, import_react.useState)(false);
+  (0, import_react.useEffect)(() => {
+    const t = setTimeout(() => setOn(true), ms);
+    return () => clearTimeout(t);
+  }, [ms]);
+  return on;
+}
+function Spinner({
+  size = 18,
+  thresholdMs = LOADING_TIMINGS.spinThresholdMs,
+  label = "Loading"
+}) {
+  useLoadingStyles();
+  const show = useDelayedFlag(thresholdMs);
+  if (!show) return null;
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    "span",
+    {
+      className: "ir-sdk-spin",
+      role: "status",
+      "aria-label": label,
+      style: {
+        display: "inline-block",
+        width: size,
+        height: size,
+        border: "2px solid rgba(127,127,127,0.3)",
+        borderTopColor: "currentColor",
+        borderRadius: "50%",
+        boxSizing: "border-box"
+      }
+    }
+  );
+}
+function LoadingRegion({
+  loading,
+  fallback,
+  label = "Loading",
+  children
+}) {
+  useLoadingStyles();
+  if (!loading) return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children });
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    "div",
+    {
+      "aria-busy": "true",
+      style: { display: "flex", alignItems: "center", justifyContent: "center", width: "100%", height: "100%", minHeight: 48 },
+      children: fallback ?? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Spinner, { label })
+    }
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  LOADING_TIMINGS,
+  LoadingRegion,
+  Skeleton,
+  SkeletonRow,
+  Spinner
+});
+//# sourceMappingURL=loading.cjs.map

package/dist/loading.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/loading.tsx"],"sourcesContent":["// In-app loading primitives (LOADING_UX_SPEC §9, Surface E; design brief 19).\n//\n// Opt-in, presentational components an app author drops in for IN-APP waits (a\n// React.lazy chunk, a slow fetch, a pending action) so they match the platform's\n// loading language for free. Per product_values §3 this is convenience — a plain\n// app that ignores it still works.\n//\n// TRUST BOUNDARY (read brief 19): these render INSIDE the app's iframe, under the\n// app's principal — presentational only, NO capability, NO host round-trip. They\n// share the token VOCABULARY (radii, the shimmer sweep, soft placeholder fills)\n// with the host skeletons, but they are deliberately NOT the host's trusted chrome:\n// no reserved landmark, no wordmark, no \"platform is loading\" framing. They use\n// ordinary app a11y (`aria-hidden` for decorative skeletons, `role=\"status\"` for an\n// indeterminate indicator) — never the host's reserved landmark/accessible name\n// (that is the trusted-path control, reserved to the host). An in-app loader that\n// mimicked host chrome would be a spoofing vector.\n//\n// Self-contained: the SDK ships no CSS pipeline, so the keyframes are injected once\n// into the document and everything else is inline styles — zero config for the author.\nimport {\n  useEffect,\n  useLayoutEffect,\n  useState,\n  type CSSProperties,\n  type ReactNode,\n} from \"react\";\n\n/** Loading timing constants, matching the host (LOADING_UX_SPEC §3, the 2026-06-22\n *  design bundle). Exported so authors who hand-roll still match the platform. */\nexport const LOADING_TIMINGS = {\n  /** Below this, NO spinner appears — a fast wait never flashes one (§6.2 floor). */\n  spinThresholdMs: 150,\n  /** The reveal cross-fade duration the host uses. */\n  fadeMs: 150,\n  /** One slow shimmer sweep across a placeholder. */\n  shimmerMs: 1900,\n} as const;\n\n/** The in-app skeleton archetypes (the same shapes as the host §4.1 catalog). */\nexport type SkeletonArchetype =\n  | \"panel.list\"\n  | \"panel.tree\"\n  | \"panel.editor\"\n  | \"panel.conversation\"\n  | \"generic\";\n\nconst STYLE_ID = \"ir-sdk-loading-styles\";\nconst STYLE_TEXT = `\n@keyframes ir-sdk-sweep{0%{transform:translateX(-130%)}60%,100%{transform:translateX(130%)}}\n@keyframes ir-sdk-spin{to{transform:rotate(360deg)}}\n.ir-sdk-shim{position:relative;overflow:hidden}\n.ir-sdk-shim::after{content:\"\";position:absolute;inset:0;background:linear-gradient(100deg,transparent 28%,rgba(127,127,127,.18) 50%,transparent 72%);transform:translateX(-130%);animation:ir-sdk-sweep ${LOADING_TIMINGS.shimmerMs}ms ease-in-out infinite}\n.ir-sdk-spin{animation:ir-sdk-spin .8s linear infinite}\n@media (prefers-reduced-motion:reduce){.ir-sdk-shim::after{display:none}.ir-sdk-spin{animation:none}}\n`;\n\n/** Inject the shimmer/spin keyframes once (idempotent, browser-only). */\nfunction ensureLoadingStyles(): void {\n  if (typeof document === \"undefined\") return;\n  if (document.getElementById(STYLE_ID)) return;\n  const el = document.createElement(\"style\");\n  el.id = STYLE_ID;\n  el.textContent = STYLE_TEXT;\n  document.head.appendChild(el);\n}\n\n/** Ensure the loading keyframes exist before the component paints. */\nfunction useLoadingStyles(): void {\n  useLayoutEffect(() => {\n    ensureLoadingStyles();\n  }, []);\n}\n\n// A soft, low-contrast placeholder fill that reads on a light OR dark app surface.\nconst PLACEHOLDER: CSSProperties = {\n  background: \"rgba(127,127,127,0.20)\",\n  borderRadius: 6,\n};\n\n/** A single placeholder bar — compose these into a custom skeleton shape. */\nexport function SkeletonRow({\n  width = \"100%\",\n  height = 12,\n  style,\n}: {\n  width?: number | string;\n  height?: number | string;\n  style?: CSSProperties;\n}) {\n  useLoadingStyles();\n  return (\n    <div\n      className=\"ir-sdk-shim\"\n      aria-hidden=\"true\"\n      style={{ ...PLACEHOLDER, width, height, ...style }}\n    />\n  );\n}\n\nfunction rows(specs: Array<CSSProperties & { key: number }>): ReactNode {\n  return specs.map(({ key, ...s }) => (\n    <div key={key} className=\"ir-sdk-shim\" aria-hidden=\"true\" style={{ ...PLACEHOLDER, ...s }} />\n  ));\n}\n\n/** A shaped, in-app skeleton matching the host archetypes — for an app's own lazy\n *  region (e.g. `<Suspense fallback={<Skeleton archetype=\"panel.list\" />}>`).\n *  Decorative (`aria-hidden`); pair it with `aria-busy` on the region it stands in. */\nexport function Skeleton({\n  archetype = \"generic\",\n  style,\n}: {\n  archetype?: SkeletonArchetype;\n  style?: CSSProperties;\n}) {\n  useLoadingStyles();\n  const wrap: CSSProperties = {\n    display: \"flex\",\n    flexDirection: \"column\",\n    gap: 10,\n    padding: 12,\n    width: \"100%\",\n    boxSizing: \"border-box\",\n    ...style,\n  };\n  let body: ReactNode;\n  switch (archetype) {\n    case \"panel.list\":\n      body = rows([0, 1, 2, 3, 4].map((key) => ({ key, height: 14 })));\n      break;\n    case \"panel.tree\":\n      body = rows([0, 1, 2, 3, 4].map((key) => ({ key, height: 14, marginLeft: (key % 3) * 16 })));\n      break;\n    case \"panel.editor\":\n      body = rows([62, 88, 73, 41, 80].map((w, key) => ({ key, height: 11, width: `${w}%` })));\n      break;\n    case \"panel.conversation\":\n      body = rows(\n        [0, 1, 2, 3].map((key) => ({\n          key,\n          height: 40,\n          width: \"70%\",\n          borderRadius: 12,\n          alignSelf: key % 2 ? \"flex-end\" : \"flex-start\",\n        })),\n      );\n      break;\n    case \"generic\":\n    default:\n      body = (\n        <>\n          <div className=\"ir-sdk-shim\" aria-hidden=\"true\" style={{ ...PLACEHOLDER, height: 16, width: \"45%\", borderRadius: 4 }} />\n          {rows([0, 1].map((key) => ({ key, height: 56, borderRadius: 8 })))}\n        </>\n      );\n  }\n  return (\n    <div aria-hidden=\"true\" style={wrap}>\n      {body}\n    </div>\n  );\n}\n\n/** Become true after `ms`, so a fast wait never flashes an indicator (§6.2 floor). */\nfunction useDelayedFlag(ms: number): boolean {\n  const [on, setOn] = useState(false);\n  useEffect(() => {\n    const t = setTimeout(() => setOn(true), ms);\n    return () => clearTimeout(t);\n  }, [ms]);\n  return on;\n}\n\n/** An indeterminate spinner for waits where a shaped skeleton doesn't fit (a pending\n *  button, a small inline fetch). Wired to the host's ~150 ms-before-spin rule: it\n *  renders nothing until the threshold, so a fast wait shows no flash. Reduced motion\n *  stills the rotation (the ring stays as a static indicator). In-app a11y only. */\nexport function Spinner({\n  size = 18,\n  thresholdMs = LOADING_TIMINGS.spinThresholdMs,\n  label = \"Loading\",\n}: {\n  size?: number;\n  thresholdMs?: number;\n  label?: string;\n}) {\n  useLoadingStyles();\n  const show = useDelayedFlag(thresholdMs);\n  if (!show) return null;\n  return (\n    <span\n      className=\"ir-sdk-spin\"\n      role=\"status\"\n      aria-label={label}\n      style={{\n        display: \"inline-block\",\n        width: size,\n        height: size,\n        border: \"2px solid rgba(127,127,127,0.3)\",\n        borderTopColor: \"currentColor\",\n        borderRadius: \"50%\",\n        boxSizing: \"border-box\",\n      }}\n    />\n  );\n}\n\n/** Wrap an in-app region whose content is still loading: shows a centered spinner\n *  (past the 150 ms floor) with `aria-busy`, then reveals `children`. For a shaped\n *  wait, pass a `<Skeleton>` as `fallback` instead. App a11y only — not host chrome. */\nexport function LoadingRegion({\n  loading,\n  fallback,\n  label = \"Loading\",\n  children,\n}: {\n  loading: boolean;\n  fallback?: ReactNode;\n  label?: string;\n  children?: ReactNode;\n}) {\n  useLoadingStyles();\n  if (!loading) return <>{children}</>;\n  return (\n    <div\n      aria-busy=\"true\"\n      style={{ display: \"flex\", alignItems: \"center\", justifyContent: \"center\", width: \"100%\", height: \"100%\", minHeight: 48 }}\n    >\n      {fallback ?? <Spinner label={label} />}\n    </div>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA2FI;AAxEJ,mBAMO;AAIA,MAAM,kBAAkB;AAAA;AAAA,EAE7B,iBAAiB;AAAA;AAAA,EAEjB,QAAQ;AAAA;AAAA,EAER,WAAW;AACb;AAUA,MAAM,WAAW;AACjB,MAAM,aAAa;AAAA;AAAA;AAAA;AAAA,2MAIwL,gBAAgB,SAAS;AAAA;AAAA;AAAA;AAMpO,SAAS,sBAA4B;AACnC,MAAI,OAAO,aAAa,YAAa;AACrC,MAAI,SAAS,eAAe,QAAQ,EAAG;AACvC,QAAM,KAAK,SAAS,cAAc,OAAO;AACzC,KAAG,KAAK;AACR,KAAG,cAAc;AACjB,WAAS,KAAK,YAAY,EAAE;AAC9B;AAGA,SAAS,mBAAyB;AAChC,oCAAgB,MAAM;AACpB,wBAAoB;AAAA,EACtB,GAAG,CAAC,CAAC;AACP;AAGA,MAAM,cAA6B;AAAA,EACjC,YAAY;AAAA,EACZ,cAAc;AAChB;AAGO,SAAS,YAAY;AAAA,EAC1B,QAAQ;AAAA,EACR,SAAS;AAAA,EACT;AACF,GAIG;AACD,mBAAiB;AACjB,SACE;AAAA,IAAC;AAAA;AAAA,MACC,WAAU;AAAA,MACV,eAAY;AAAA,MACZ,OAAO,EAAE,GAAG,aAAa,OAAO,QAAQ,GAAG,MAAM;AAAA;AAAA,EACnD;AAEJ;AAEA,SAAS,KAAK,OAA0D;AACtE,SAAO,MAAM,IAAI,CAAC,EAAE,KAAK,GAAG,EAAE,MAC5B,4CAAC,SAAc,WAAU,eAAc,eAAY,QAAO,OAAO,EAAE,GAAG,aAAa,GAAG,EAAE,KAA9E,GAAiF,CAC5F;AACH;AAKO,SAAS,SAAS;AAAA,EACvB,YAAY;AAAA,EACZ;AACF,GAGG;AACD,mBAAiB;AACjB,QAAM,OAAsB;AAAA,IAC1B,SAAS;AAAA,IACT,eAAe;AAAA,IACf,KAAK;AAAA,IACL,SAAS;AAAA,IACT,OAAO;AAAA,IACP,WAAW;AAAA,IACX,GAAG;AAAA,EACL;AACA,MAAI;AACJ,UAAQ,WAAW;AAAA,IACjB,KAAK;AACH,aAAO,KAAK,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC,EAAE,IAAI,CAAC,SAAS,EAAE,KAAK,QAAQ,GAAG,EAAE,CAAC;AAC/D;AAAA,IACF,KAAK;AACH,aAAO,KAAK,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC,EAAE,IAAI,CAAC,SAAS,EAAE,KAAK,QAAQ,IAAI,YAAa,MAAM,IAAK,GAAG,EAAE,CAAC;AAC3F;AAAA,IACF,KAAK;AACH,aAAO,KAAK,CAAC,IAAI,IAAI,IAAI,IAAI,EAAE,EAAE,IAAI,CAAC,GAAG,SAAS,EAAE,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;AACvF;AAAA,IACF,KAAK;AACH,aAAO;AAAA,QACL,CAAC,GAAG,GAAG,GAAG,CAAC,EAAE,IAAI,CAAC,SAAS;AAAA,UACzB;AAAA,UACA,QAAQ;AAAA,UACR,OAAO;AAAA,UACP,cAAc;AAAA,UACd,WAAW,MAAM,IAAI,aAAa;AAAA,QACpC,EAAE;AAAA,MACJ;AACA;AAAA,IACF,KAAK;AAAA,IACL;AACE,aACE,4EACE;AAAA,oDAAC,SAAI,WAAU,eAAc,eAAY,QAAO,OAAO,EAAE,GAAG,aAAa,QAAQ,IAAI,OAAO,OAAO,cAAc,EAAE,GAAG;AAAA,QACrH,KAAK,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,SAAS,EAAE,KAAK,QAAQ,IAAI,cAAc,EAAE,EAAE,CAAC;AAAA,SACnE;AAAA,EAEN;AACA,SACE,4CAAC,SAAI,eAAY,QAAO,OAAO,MAC5B,gBACH;AAEJ;AAGA,SAAS,eAAe,IAAqB;AAC3C,QAAM,CAAC,IAAI,KAAK,QAAI,uBAAS,KAAK;AAClC,8BAAU,MAAM;AACd,UAAM,IAAI,WAAW,MAAM,MAAM,IAAI,GAAG,EAAE;AAC1C,WAAO,MAAM,aAAa,CAAC;AAAA,EAC7B,GAAG,CAAC,EAAE,CAAC;AACP,SAAO;AACT;AAMO,SAAS,QAAQ;AAAA,EACtB,OAAO;AAAA,EACP,cAAc,gBAAgB;AAAA,EAC9B,QAAQ;AACV,GAIG;AACD,mBAAiB;AACjB,QAAM,OAAO,eAAe,WAAW;AACvC,MAAI,CAAC,KAAM,QAAO;AAClB,SACE;AAAA,IAAC;AAAA;AAAA,MACC,WAAU;AAAA,MACV,MAAK;AAAA,MACL,cAAY;AAAA,MACZ,OAAO;AAAA,QACL,SAAS;AAAA,QACT,OAAO;AAAA,QACP,QAAQ;AAAA,QACR,QAAQ;AAAA,QACR,gBAAgB;AAAA,QAChB,cAAc;AAAA,QACd,WAAW;AAAA,MACb;AAAA;AAAA,EACF;AAEJ;AAKO,SAAS,cAAc;AAAA,EAC5B;AAAA,EACA;AAAA,EACA,QAAQ;AAAA,EACR;AACF,GAKG;AACD,mBAAiB;AACjB,MAAI,CAAC,QAAS,QAAO,2EAAG,UAAS;AACjC,SACE;AAAA,IAAC;AAAA;AAAA,MACC,aAAU;AAAA,MACV,OAAO,EAAE,SAAS,QAAQ,YAAY,UAAU,gBAAgB,UAAU,OAAO,QAAQ,QAAQ,QAAQ,WAAW,GAAG;AAAA,MAEtH,sBAAY,4CAAC,WAAQ,OAAc;AAAA;AAAA,EACtC;AAEJ;","names":[]}