@immediately-run/sdk 0.15.0 → 0.16.0

package/dist/components/Include.d.ts

@@ -4,14 +4,21 @@ import { EvaluationContext } from '../sandboxTypes.js';
 import { defaultLoadingComponent, defaultErrorComponent } from './defaults.js';
 import 'react-error-boundary';
 
+/** The value exposed on {@link RenderExportedComponentContext}: the evaluation
+ *  context of the module {@link Include} resolved. */
 type RenderFileContextType = {
     evaluationContext: EvaluationContext;
 };
+/** Context carrying the included module's {@link EvaluationContext} to its subtree. */
 declare const RenderExportedComponentContext: react.Context<RenderFileContextType | null>;
+/** Low-level: render one export of an already-resolving module evaluation. Most
+ *  code should use {@link Include}, which resolves the module and adds Suspense. */
 declare const RenderExportedComponent: ({ evaluationContextPromise, exportedSymbol, }: {
     evaluationContextPromise: Promise<EvaluationContext>;
     exportedSymbol: string;
 }) => react_jsx_runtime.JSX.Element;
+/** Render another repo file's exported component inline, resolving + evaluating it
+ *  through the module cache (with Suspense + an error boundary). */
 declare const Include: ({ filename, exportedSymbol, LoadingComponent, ErrorComponent, baseModule, }: {
     filename: string;
     exportedSymbol?: string;

package/dist/components/Include.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/Include.tsx"],"sourcesContent":["import { Suspense, createContext, use } from 'react';\nimport { ErrorBoundary } from 'react-error-boundary';\n\nimport { ModuleCacheContext } from '../moduleCache';\nimport { EvaluationContext } from '../sandboxTypes';\nimport { defaultErrorComponent, defaultLoadingComponent } from './defaults';\n\nexport type RenderFileContextType = {\n  evaluationContext: EvaluationContext;\n};\n\nexport const RenderExportedComponentContext = createContext<RenderFileContextType | null>(null);\n\nexport const RenderExportedComponent = ({\n  evaluationContextPromise,\n  exportedSymbol = 'default',\n}: {\n  evaluationContextPromise: Promise<EvaluationContext>;\n  exportedSymbol: string;\n}) => {\n  const evaluationContext = use(evaluationContextPromise);\n  // TODO: handle case where exported symbol not found.\n  const Component = exportedSymbol === '*' ? evaluationContext.exports : evaluationContext.exports[exportedSymbol];\n  return (\n    <RenderExportedComponentContext value={{ evaluationContext }}>\n      <Component />\n    </RenderExportedComponentContext>\n  );\n};\n\nexport const Include = ({\n  filename,\n  exportedSymbol = 'default',\n  LoadingComponent = defaultLoadingComponent,\n  ErrorComponent = defaultErrorComponent,\n  baseModule,\n}: {\n  filename: string;\n  exportedSymbol?: string;\n  LoadingComponent?: typeof defaultLoadingComponent;\n  ErrorComponent?: typeof defaultErrorComponent;\n  baseModule?: EvaluationContext;\n}) => {\n  const moduleCache = use(ModuleCacheContext);\n  // @ts-ignore\n  const evaluationContextPromise = moduleCache!.getEvaluationContext(filename, baseModule ?? module);\n  return (\n    <ErrorBoundary fallbackRender={ErrorComponent}>\n      <Suspense fallback={<LoadingComponent />}>\n        <RenderExportedComponent evaluationContextPromise={evaluationContextPromise} exportedSymbol={exportedSymbol} />\n      </Suspense>\n    </ErrorBoundary>\n  );\n};\n"],"mappings":"AAyBM;AAzBN,SAAS,UAAU,eAAe,WAAW;AAC7C,SAAS,qBAAqB;AAE9B,SAAS,0BAA0B;AAEnC,SAAS,uBAAuB,+BAA+B;AAMxD,MAAM,iCAAiC,cAA4C,IAAI;AAEvF,MAAM,0BAA0B,CAAC;AAAA,EACtC;AAAA,EACA,iBAAiB;AACnB,MAGM;AACJ,QAAM,oBAAoB,IAAI,wBAAwB;AAEtD,QAAM,YAAY,mBAAmB,MAAM,kBAAkB,UAAU,kBAAkB,QAAQ,cAAc;AAC/G,SACE,oBAAC,kCAA+B,OAAO,EAAE,kBAAkB,GACzD,8BAAC,aAAU,GACb;AAEJ;AAEO,MAAM,UAAU,CAAC;AAAA,EACtB;AAAA,EACA,iBAAiB;AAAA,EACjB,mBAAmB;AAAA,EACnB,iBAAiB;AAAA,EACjB;AACF,MAMM;AACJ,QAAM,cAAc,IAAI,kBAAkB;AAE1C,QAAM,2BAA2B,YAAa,qBAAqB,UAAU,cAAc,MAAM;AACjG,SACE,oBAAC,iBAAc,gBAAgB,gBAC7B,8BAAC,YAAS,UAAU,oBAAC,oBAAiB,GACpC,8BAAC,2BAAwB,0BAAoD,gBAAgC,GAC/G,GACF;AAEJ;","names":[]}
+{"version":3,"sources":["../../src/components/Include.tsx"],"sourcesContent":["import { Suspense, createContext, use } from 'react';\nimport { ErrorBoundary } from 'react-error-boundary';\n\nimport { ModuleCacheContext } from '../moduleCache';\nimport { EvaluationContext } from '../sandboxTypes';\nimport { defaultErrorComponent, defaultLoadingComponent } from './defaults';\n\n/** The value exposed on {@link RenderExportedComponentContext}: the evaluation\n *  context of the module {@link Include} resolved. */\nexport type RenderFileContextType = {\n  evaluationContext: EvaluationContext;\n};\n\n/** Context carrying the included module's {@link EvaluationContext} to its subtree. */\nexport const RenderExportedComponentContext = createContext<RenderFileContextType | null>(null);\n\n/** Low-level: render one export of an already-resolving module evaluation. Most\n *  code should use {@link Include}, which resolves the module and adds Suspense. */\nexport const RenderExportedComponent = ({\n  evaluationContextPromise,\n  exportedSymbol = 'default',\n}: {\n  evaluationContextPromise: Promise<EvaluationContext>;\n  exportedSymbol: string;\n}) => {\n  const evaluationContext = use(evaluationContextPromise);\n  // TODO: handle case where exported symbol not found.\n  const Component = exportedSymbol === '*' ? evaluationContext.exports : evaluationContext.exports[exportedSymbol];\n  return (\n    <RenderExportedComponentContext value={{ evaluationContext }}>\n      <Component />\n    </RenderExportedComponentContext>\n  );\n};\n\n/** Render another repo file's exported component inline, resolving + evaluating it\n *  through the module cache (with Suspense + an error boundary). */\nexport const Include = ({\n  filename,\n  exportedSymbol = 'default',\n  LoadingComponent = defaultLoadingComponent,\n  ErrorComponent = defaultErrorComponent,\n  baseModule,\n}: {\n  filename: string;\n  exportedSymbol?: string;\n  LoadingComponent?: typeof defaultLoadingComponent;\n  ErrorComponent?: typeof defaultErrorComponent;\n  baseModule?: EvaluationContext;\n}) => {\n  const moduleCache = use(ModuleCacheContext);\n  // @ts-ignore\n  const evaluationContextPromise = moduleCache!.getEvaluationContext(filename, baseModule ?? module);\n  return (\n    <ErrorBoundary fallbackRender={ErrorComponent}>\n      <Suspense fallback={<LoadingComponent />}>\n        <RenderExportedComponent evaluationContextPromise={evaluationContextPromise} exportedSymbol={exportedSymbol} />\n      </Suspense>\n    </ErrorBoundary>\n  );\n};\n"],"mappings":"AA8BM;AA9BN,SAAS,UAAU,eAAe,WAAW;AAC7C,SAAS,qBAAqB;AAE9B,SAAS,0BAA0B;AAEnC,SAAS,uBAAuB,+BAA+B;AASxD,MAAM,iCAAiC,cAA4C,IAAI;AAIvF,MAAM,0BAA0B,CAAC;AAAA,EACtC;AAAA,EACA,iBAAiB;AACnB,MAGM;AACJ,QAAM,oBAAoB,IAAI,wBAAwB;AAEtD,QAAM,YAAY,mBAAmB,MAAM,kBAAkB,UAAU,kBAAkB,QAAQ,cAAc;AAC/G,SACE,oBAAC,kCAA+B,OAAO,EAAE,kBAAkB,GACzD,8BAAC,aAAU,GACb;AAEJ;AAIO,MAAM,UAAU,CAAC;AAAA,EACtB;AAAA,EACA,iBAAiB;AAAA,EACjB,mBAAmB;AAAA,EACnB,iBAAiB;AAAA,EACjB;AACF,MAMM;AACJ,QAAM,cAAc,IAAI,kBAAkB;AAE1C,QAAM,2BAA2B,YAAa,qBAAqB,UAAU,cAAc,MAAM;AACjG,SACE,oBAAC,iBAAc,gBAAgB,gBAC7B,8BAAC,YAAS,UAAU,oBAAC,oBAAiB,GACpC,8BAAC,2BAAwB,0BAAoD,gBAAgC,GAC/G,GACF;AAEJ;","names":[]}

package/dist/components/MDXComponents.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/MDXComponents.tsx"],"sourcesContent":["import { ReactNode, use, useCallback } from 'react';\nimport { navigate } from '../routing';\nimport { TinkerableContext } from '../TinkerableContext';\nimport { constructOuterUrl, constructUrl, isInternalHref, repositoryPrefixURL } from '../urlUtils';\n\nexport const InternalLink = ({\n  href,\n  children,\n  ...props\n}: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>): ReactNode => {\n  const clickHandler = useCallback(\n    (e: any) => {\n      if (href) {\n        e.preventDefault();\n        navigate(href);\n      }\n    },\n    [href]\n  );\n  return (\n    <a href={href} onClick={clickHandler} {...props}>\n      {children}\n    </a>\n  );\n};\n\nexport const Link = ({\n  href,\n  children,\n  ...properties\n}: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>): ReactNode => {\n  const { outerHref, navigationState } = use(TinkerableContext);\n  if (href && isInternalHref(outerHref, href, navigationState)) {\n    const targetHref = constructOuterUrl(outerHref, href, navigationState);\n    return (\n      <InternalLink href={targetHref} {...properties}>\n        {children}\n      </InternalLink>\n    );\n  } else {\n    // create a regular link to external resource\n    return <a {...{ href, ...properties }}>{children}</a>;\n  }\n};\n\nexport const DEFAULT_MDX_COMPONENTS = {\n  a({\n    href,\n    children,\n    ...properties\n  }: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>) {\n    return (\n      <Link href={href} {...properties}>\n        {children}\n      </Link>\n    );\n  },\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAoBI;AApBJ,mBAA4C;AAC5C,qBAAyB;AACzB,+BAAkC;AAClC,sBAAqF;AAE9E,MAAM,eAAe,CAAC;AAAA,EAC3B;AAAA,EACA;AAAA,EACA,GAAG;AACL,MAA4G;AAC1G,QAAM,mBAAe;AAAA,IACnB,CAAC,MAAW;AACV,UAAI,MAAM;AACR,UAAE,eAAe;AACjB,qCAAS,IAAI;AAAA,MACf;AAAA,IACF;AAAA,IACA,CAAC,IAAI;AAAA,EACP;AACA,SACE,4CAAC,OAAE,MAAY,SAAS,cAAe,GAAG,OACvC,UACH;AAEJ;AAEO,MAAM,OAAO,CAAC;AAAA,EACnB;AAAA,EACA;AAAA,EACA,GAAG;AACL,MAA4G;AAC1G,QAAM,EAAE,WAAW,gBAAgB,QAAI,kBAAI,0CAAiB;AAC5D,MAAI,YAAQ,gCAAe,WAAW,MAAM,eAAe,GAAG;AAC5D,UAAM,iBAAa,mCAAkB,WAAW,MAAM,eAAe;AACrE,WACE,4CAAC,gBAAa,MAAM,YAAa,GAAG,YACjC,UACH;AAAA,EAEJ,OAAO;AAEL,WAAO,4CAAC,OAAG,GAAG,EAAE,MAAM,GAAG,WAAW,GAAI,UAAS;AAAA,EACnD;AACF;AAEO,MAAM,yBAAyB;AAAA,EACpC,EAAE;AAAA,IACA;AAAA,IACA;AAAA,IACA,GAAG;AAAA,EACL,GAA8F;AAC5F,WACE,4CAAC,QAAK,MAAa,GAAG,YACnB,UACH;AAAA,EAEJ;AACF;","names":[]}
+{"version":3,"sources":["../../src/components/MDXComponents.tsx"],"sourcesContent":["import { ReactNode, use, useCallback } from 'react';\nimport { navigate } from '../routing';\nimport { TinkerableContext } from '../TinkerableContext';\nimport { constructOuterUrl, constructUrl, isInternalHref, repositoryPrefixURL } from '../urlUtils';\n\n/** An `<a>` that performs in-sandbox navigation on click (prevents the default\n *  full-page load and routes via {@link navigate}). */\nexport const InternalLink = ({\n  href,\n  children,\n  ...props\n}: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>): ReactNode => {\n  const clickHandler = useCallback(\n    (e: any) => {\n      if (href) {\n        e.preventDefault();\n        navigate(href);\n      }\n    },\n    [href]\n  );\n  return (\n    <a href={href} onClick={clickHandler} {...props}>\n      {children}\n    </a>\n  );\n};\n\n/** A link that routes same-app hrefs through the sandbox router (as an\n *  {@link InternalLink}) and renders external hrefs as a plain `<a>`. */\nexport const Link = ({\n  href,\n  children,\n  ...properties\n}: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>): ReactNode => {\n  const { outerHref, navigationState } = use(TinkerableContext);\n  if (href && isInternalHref(outerHref, href, navigationState)) {\n    const targetHref = constructOuterUrl(outerHref, href, navigationState);\n    return (\n      <InternalLink href={targetHref} {...properties}>\n        {children}\n      </InternalLink>\n    );\n  } else {\n    // create a regular link to external resource\n    return <a {...{ href, ...properties }}>{children}</a>;\n  }\n};\n\n/** Default MDX component overrides: routes `<a>` through {@link Link} so links in\n *  MDX prose navigate within the app. Passed to {@link MDXProvider} by `boot`. */\nexport const DEFAULT_MDX_COMPONENTS = {\n  a({\n    href,\n    children,\n    ...properties\n  }: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>) {\n    return (\n      <Link href={href} {...properties}>\n        {children}\n      </Link>\n    );\n  },\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAsBI;AAtBJ,mBAA4C;AAC5C,qBAAyB;AACzB,+BAAkC;AAClC,sBAAqF;AAI9E,MAAM,eAAe,CAAC;AAAA,EAC3B;AAAA,EACA;AAAA,EACA,GAAG;AACL,MAA4G;AAC1G,QAAM,mBAAe;AAAA,IACnB,CAAC,MAAW;AACV,UAAI,MAAM;AACR,UAAE,eAAe;AACjB,qCAAS,IAAI;AAAA,MACf;AAAA,IACF;AAAA,IACA,CAAC,IAAI;AAAA,EACP;AACA,SACE,4CAAC,OAAE,MAAY,SAAS,cAAe,GAAG,OACvC,UACH;AAEJ;AAIO,MAAM,OAAO,CAAC;AAAA,EACnB;AAAA,EACA;AAAA,EACA,GAAG;AACL,MAA4G;AAC1G,QAAM,EAAE,WAAW,gBAAgB,QAAI,kBAAI,0CAAiB;AAC5D,MAAI,YAAQ,gCAAe,WAAW,MAAM,eAAe,GAAG;AAC5D,UAAM,iBAAa,mCAAkB,WAAW,MAAM,eAAe;AACrE,WACE,4CAAC,gBAAa,MAAM,YAAa,GAAG,YACjC,UACH;AAAA,EAEJ,OAAO;AAEL,WAAO,4CAAC,OAAG,GAAG,EAAE,MAAM,GAAG,WAAW,GAAI,UAAS;AAAA,EACnD;AACF;AAIO,MAAM,yBAAyB;AAAA,EACpC,EAAE;AAAA,IACA;AAAA,IACA;AAAA,IACA,GAAG;AAAA,EACL,GAA8F;AAC5F,WACE,4CAAC,QAAK,MAAa,GAAG,YACnB,UACH;AAAA,EAEJ;AACF;","names":[]}

package/dist/components/MDXComponents.d.cts

@@ -1,8 +1,14 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 
+/** An `<a>` that performs in-sandbox navigation on click (prevents the default
+ *  full-page load and routes via {@link navigate}). */
 declare const InternalLink: ({ href, children, ...props }: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>) => ReactNode;
+/** A link that routes same-app hrefs through the sandbox router (as an
+ *  {@link InternalLink}) and renders external hrefs as a plain `<a>`. */
 declare const Link: ({ href, children, ...properties }: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>) => ReactNode;
+/** Default MDX component overrides: routes `<a>` through {@link Link} so links in
+ *  MDX prose navigate within the app. Passed to {@link MDXProvider} by `boot`. */
 declare const DEFAULT_MDX_COMPONENTS: {
     a({ href, children, ...properties }: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>): react_jsx_runtime.JSX.Element;
 };

package/dist/components/MDXComponents.d.ts

@@ -1,8 +1,14 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 
+/** An `<a>` that performs in-sandbox navigation on click (prevents the default
+ *  full-page load and routes via {@link navigate}). */
 declare const InternalLink: ({ href, children, ...props }: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>) => ReactNode;
+/** A link that routes same-app hrefs through the sandbox router (as an
+ *  {@link InternalLink}) and renders external hrefs as a plain `<a>`. */
 declare const Link: ({ href, children, ...properties }: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>) => ReactNode;
+/** Default MDX component overrides: routes `<a>` through {@link Link} so links in
+ *  MDX prose navigate within the app. Passed to {@link MDXProvider} by `boot`. */
 declare const DEFAULT_MDX_COMPONENTS: {
     a({ href, children, ...properties }: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>): react_jsx_runtime.JSX.Element;
 };

package/dist/components/MDXComponents.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/MDXComponents.tsx"],"sourcesContent":["import { ReactNode, use, useCallback } from 'react';\nimport { navigate } from '../routing';\nimport { TinkerableContext } from '../TinkerableContext';\nimport { constructOuterUrl, constructUrl, isInternalHref, repositoryPrefixURL } from '../urlUtils';\n\nexport const InternalLink = ({\n  href,\n  children,\n  ...props\n}: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>): ReactNode => {\n  const clickHandler = useCallback(\n    (e: any) => {\n      if (href) {\n        e.preventDefault();\n        navigate(href);\n      }\n    },\n    [href]\n  );\n  return (\n    <a href={href} onClick={clickHandler} {...props}>\n      {children}\n    </a>\n  );\n};\n\nexport const Link = ({\n  href,\n  children,\n  ...properties\n}: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>): ReactNode => {\n  const { outerHref, navigationState } = use(TinkerableContext);\n  if (href && isInternalHref(outerHref, href, navigationState)) {\n    const targetHref = constructOuterUrl(outerHref, href, navigationState);\n    return (\n      <InternalLink href={targetHref} {...properties}>\n        {children}\n      </InternalLink>\n    );\n  } else {\n    // create a regular link to external resource\n    return <a {...{ href, ...properties }}>{children}</a>;\n  }\n};\n\nexport const DEFAULT_MDX_COMPONENTS = {\n  a({\n    href,\n    children,\n    ...properties\n  }: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>) {\n    return (\n      <Link href={href} {...properties}>\n        {children}\n      </Link>\n    );\n  },\n};\n"],"mappings":"AAoBI;AApBJ,SAAoB,KAAK,mBAAmB;AAC5C,SAAS,gBAAgB;AACzB,SAAS,yBAAyB;AAClC,SAAS,mBAAiC,sBAA2C;AAE9E,MAAM,eAAe,CAAC;AAAA,EAC3B;AAAA,EACA;AAAA,EACA,GAAG;AACL,MAA4G;AAC1G,QAAM,eAAe;AAAA,IACnB,CAAC,MAAW;AACV,UAAI,MAAM;AACR,UAAE,eAAe;AACjB,iBAAS,IAAI;AAAA,MACf;AAAA,IACF;AAAA,IACA,CAAC,IAAI;AAAA,EACP;AACA,SACE,oBAAC,OAAE,MAAY,SAAS,cAAe,GAAG,OACvC,UACH;AAEJ;AAEO,MAAM,OAAO,CAAC;AAAA,EACnB;AAAA,EACA;AAAA,EACA,GAAG;AACL,MAA4G;AAC1G,QAAM,EAAE,WAAW,gBAAgB,IAAI,IAAI,iBAAiB;AAC5D,MAAI,QAAQ,eAAe,WAAW,MAAM,eAAe,GAAG;AAC5D,UAAM,aAAa,kBAAkB,WAAW,MAAM,eAAe;AACrE,WACE,oBAAC,gBAAa,MAAM,YAAa,GAAG,YACjC,UACH;AAAA,EAEJ,OAAO;AAEL,WAAO,oBAAC,OAAG,GAAG,EAAE,MAAM,GAAG,WAAW,GAAI,UAAS;AAAA,EACnD;AACF;AAEO,MAAM,yBAAyB;AAAA,EACpC,EAAE;AAAA,IACA;AAAA,IACA;AAAA,IACA,GAAG;AAAA,EACL,GAA8F;AAC5F,WACE,oBAAC,QAAK,MAAa,GAAG,YACnB,UACH;AAAA,EAEJ;AACF;","names":[]}
+{"version":3,"sources":["../../src/components/MDXComponents.tsx"],"sourcesContent":["import { ReactNode, use, useCallback } from 'react';\nimport { navigate } from '../routing';\nimport { TinkerableContext } from '../TinkerableContext';\nimport { constructOuterUrl, constructUrl, isInternalHref, repositoryPrefixURL } from '../urlUtils';\n\n/** An `<a>` that performs in-sandbox navigation on click (prevents the default\n *  full-page load and routes via {@link navigate}). */\nexport const InternalLink = ({\n  href,\n  children,\n  ...props\n}: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>): ReactNode => {\n  const clickHandler = useCallback(\n    (e: any) => {\n      if (href) {\n        e.preventDefault();\n        navigate(href);\n      }\n    },\n    [href]\n  );\n  return (\n    <a href={href} onClick={clickHandler} {...props}>\n      {children}\n    </a>\n  );\n};\n\n/** A link that routes same-app hrefs through the sandbox router (as an\n *  {@link InternalLink}) and renders external hrefs as a plain `<a>`. */\nexport const Link = ({\n  href,\n  children,\n  ...properties\n}: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>): ReactNode => {\n  const { outerHref, navigationState } = use(TinkerableContext);\n  if (href && isInternalHref(outerHref, href, navigationState)) {\n    const targetHref = constructOuterUrl(outerHref, href, navigationState);\n    return (\n      <InternalLink href={targetHref} {...properties}>\n        {children}\n      </InternalLink>\n    );\n  } else {\n    // create a regular link to external resource\n    return <a {...{ href, ...properties }}>{children}</a>;\n  }\n};\n\n/** Default MDX component overrides: routes `<a>` through {@link Link} so links in\n *  MDX prose navigate within the app. Passed to {@link MDXProvider} by `boot`. */\nexport const DEFAULT_MDX_COMPONENTS = {\n  a({\n    href,\n    children,\n    ...properties\n  }: React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>) {\n    return (\n      <Link href={href} {...properties}>\n        {children}\n      </Link>\n    );\n  },\n};\n"],"mappings":"AAsBI;AAtBJ,SAAoB,KAAK,mBAAmB;AAC5C,SAAS,gBAAgB;AACzB,SAAS,yBAAyB;AAClC,SAAS,mBAAiC,sBAA2C;AAI9E,MAAM,eAAe,CAAC;AAAA,EAC3B;AAAA,EACA;AAAA,EACA,GAAG;AACL,MAA4G;AAC1G,QAAM,eAAe;AAAA,IACnB,CAAC,MAAW;AACV,UAAI,MAAM;AACR,UAAE,eAAe;AACjB,iBAAS,IAAI;AAAA,MACf;AAAA,IACF;AAAA,IACA,CAAC,IAAI;AAAA,EACP;AACA,SACE,oBAAC,OAAE,MAAY,SAAS,cAAe,GAAG,OACvC,UACH;AAEJ;AAIO,MAAM,OAAO,CAAC;AAAA,EACnB;AAAA,EACA;AAAA,EACA,GAAG;AACL,MAA4G;AAC1G,QAAM,EAAE,WAAW,gBAAgB,IAAI,IAAI,iBAAiB;AAC5D,MAAI,QAAQ,eAAe,WAAW,MAAM,eAAe,GAAG;AAC5D,UAAM,aAAa,kBAAkB,WAAW,MAAM,eAAe;AACrE,WACE,oBAAC,gBAAa,MAAM,YAAa,GAAG,YACjC,UACH;AAAA,EAEJ,OAAO;AAEL,WAAO,oBAAC,OAAG,GAAG,EAAE,MAAM,GAAG,WAAW,GAAI,UAAS;AAAA,EACnD;AACF;AAIO,MAAM,yBAAyB;AAAA,EACpC,EAAE;AAAA,IACA;AAAA,IACA;AAAA,IACA,GAAG;AAAA,EACL,GAA8F;AAC5F,WACE,oBAAC,QAAK,MAAa,GAAG,YACnB,UACH;AAAA,EAEJ;AACF;","names":[]}

package/dist/components/Routes.cjs

@@ -0,0 +1,59 @@
+"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 Routes_exports = {};
+__export(Routes_exports, {
+  Route: () => Route,
+  Routes: () => Routes
+});
+module.exports = __toCommonJS(Routes_exports);
+var import_jsx_runtime = require("react/jsx-runtime");
+var import_react = require("react");
+var import_TinkerableContext = require("../TinkerableContext");
+var import_routeMatch = require("../routeMatch");
+var import_routing = require("../routing");
+const Route = (_props) => null;
+const Routes = ({
+  children,
+  fallback = null
+}) => {
+  const context = (0, import_react.use)(import_TinkerableContext.TinkerableContext);
+  const { sandboxPath } = context.navigationState;
+  for (const child of import_react.Children.toArray(children)) {
+    if (!(0, import_react.isValidElement)(child) || child.type !== Route) {
+      continue;
+    }
+    const { path, element, component, name } = child.props;
+    const params = (0, import_routeMatch.matchRoute)(path, sandboxPath);
+    if (params) {
+      const routingRule = { name, pattern: path, element, component };
+      const scoped = {
+        ...context,
+        navigationState: { ...context.navigationState, routingRule, pathParameters: params }
+      };
+      return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_TinkerableContext.TinkerableContext, { value: scoped, children: (0, import_routing.renderRoute)(routingRule, params) });
+    }
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_jsx_runtime.Fragment, { children: fallback });
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Route,
+  Routes
+});
+//# sourceMappingURL=Routes.cjs.map

package/dist/components/Routes.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/Routes.tsx"],"sourcesContent":["import type { ReactNode } from 'react';\nimport { Children, isValidElement, use } from 'react';\n\nimport { TinkerableContext } from '../TinkerableContext';\nimport type { RouteComponent, RoutingRule } from '../RoutingSpec';\nimport { matchRoute } from '../routeMatch';\nimport { renderRoute } from '../routing';\n\n/** Props for a {@link Route} declared inside {@link Routes}. */\nexport type RouteProps = {\n  /** A path template (`/posts/:slug`, `/files/*`, `/`) or a raw RegExp. */\n  path: string | RegExp;\n  name?: string;\n  /** Element to render; reads params via `useRouteParams()`. */\n  element?: ReactNode;\n  /** Component to render; receives matched params as a prop. */\n  component?: RouteComponent;\n};\n\n/**\n * Declares a route. Rendered as a child of `<Routes>`, where it is read for its\n * props — it renders nothing on its own. Mounting a `<Route>` registers it;\n * unmounting (or conditionally not rendering it) removes it, which is how routes\n * become dynamic without a mutable registry.\n */\nexport const Route = (_props: RouteProps): null => null;\n\n/**\n * Resolves the active `sandboxPath` against its mounted `<Route>` children,\n * first-match-wins in render order, and renders the winner (or `fallback`). The\n * match scopes a nested context so `useRouteParams()` / `useRoute()` inside the\n * rendered route see this match. Use instead of (or nested within) a `boot`-time\n * `routingSpec`.\n */\nexport const Routes = ({\n  children,\n  fallback = null,\n}: {\n  children?: ReactNode;\n  fallback?: ReactNode;\n}) => {\n  const context = use(TinkerableContext);\n  const { sandboxPath } = context.navigationState;\n\n  for (const child of Children.toArray(children)) {\n    if (!isValidElement(child) || child.type !== Route) {\n      continue;\n    }\n    const { path, element, component, name } = child.props as RouteProps;\n    const params = matchRoute(path, sandboxPath);\n    if (params) {\n      const routingRule: RoutingRule = { name, pattern: path, element, component };\n      const scoped = {\n        ...context,\n        navigationState: { ...context.navigationState, routingRule, pathParameters: params },\n      };\n      return (\n        <TinkerableContext value={scoped}>\n          {renderRoute(routingRule, params)}\n        </TinkerableContext>\n      );\n    }\n  }\n\n  return <>{fallback}</>;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAyDQ;AAxDR,mBAA8C;AAE9C,+BAAkC;AAElC,wBAA2B;AAC3B,qBAA4B;AAmBrB,MAAM,QAAQ,CAAC,WAA6B;AAS5C,MAAM,SAAS,CAAC;AAAA,EACrB;AAAA,EACA,WAAW;AACb,MAGM;AACJ,QAAM,cAAU,kBAAI,0CAAiB;AACrC,QAAM,EAAE,YAAY,IAAI,QAAQ;AAEhC,aAAW,SAAS,sBAAS,QAAQ,QAAQ,GAAG;AAC9C,QAAI,KAAC,6BAAe,KAAK,KAAK,MAAM,SAAS,OAAO;AAClD;AAAA,IACF;AACA,UAAM,EAAE,MAAM,SAAS,WAAW,KAAK,IAAI,MAAM;AACjD,UAAM,aAAS,8BAAW,MAAM,WAAW;AAC3C,QAAI,QAAQ;AACV,YAAM,cAA2B,EAAE,MAAM,SAAS,MAAM,SAAS,UAAU;AAC3E,YAAM,SAAS;AAAA,QACb,GAAG;AAAA,QACH,iBAAiB,EAAE,GAAG,QAAQ,iBAAiB,aAAa,gBAAgB,OAAO;AAAA,MACrF;AACA,aACE,4CAAC,8CAAkB,OAAO,QACvB,0CAAY,aAAa,MAAM,GAClC;AAAA,IAEJ;AAAA,EACF;AAEA,SAAO,2EAAG,oBAAS;AACrB;","names":[]}

package/dist/components/Routes.d.cts

@@ -0,0 +1,34 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { RouteComponent } from '../RoutingSpec.cjs';
+
+/** Props for a {@link Route} declared inside {@link Routes}. */
+type RouteProps = {
+    /** A path template (`/posts/:slug`, `/files/*`, `/`) or a raw RegExp. */
+    path: string | RegExp;
+    name?: string;
+    /** Element to render; reads params via `useRouteParams()`. */
+    element?: ReactNode;
+    /** Component to render; receives matched params as a prop. */
+    component?: RouteComponent;
+};
+/**
+ * Declares a route. Rendered as a child of `<Routes>`, where it is read for its
+ * props — it renders nothing on its own. Mounting a `<Route>` registers it;
+ * unmounting (or conditionally not rendering it) removes it, which is how routes
+ * become dynamic without a mutable registry.
+ */
+declare const Route: (_props: RouteProps) => null;
+/**
+ * Resolves the active `sandboxPath` against its mounted `<Route>` children,
+ * first-match-wins in render order, and renders the winner (or `fallback`). The
+ * match scopes a nested context so `useRouteParams()` / `useRoute()` inside the
+ * rendered route see this match. Use instead of (or nested within) a `boot`-time
+ * `routingSpec`.
+ */
+declare const Routes: ({ children, fallback, }: {
+    children?: ReactNode;
+    fallback?: ReactNode;
+}) => react_jsx_runtime.JSX.Element;
+
+export { Route, type RouteProps, Routes };

package/dist/components/Routes.d.ts

@@ -0,0 +1,34 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { RouteComponent } from '../RoutingSpec.js';
+
+/** Props for a {@link Route} declared inside {@link Routes}. */
+type RouteProps = {
+    /** A path template (`/posts/:slug`, `/files/*`, `/`) or a raw RegExp. */
+    path: string | RegExp;
+    name?: string;
+    /** Element to render; reads params via `useRouteParams()`. */
+    element?: ReactNode;
+    /** Component to render; receives matched params as a prop. */
+    component?: RouteComponent;
+};
+/**
+ * Declares a route. Rendered as a child of `<Routes>`, where it is read for its
+ * props — it renders nothing on its own. Mounting a `<Route>` registers it;
+ * unmounting (or conditionally not rendering it) removes it, which is how routes
+ * become dynamic without a mutable registry.
+ */
+declare const Route: (_props: RouteProps) => null;
+/**
+ * Resolves the active `sandboxPath` against its mounted `<Route>` children,
+ * first-match-wins in render order, and renders the winner (or `fallback`). The
+ * match scopes a nested context so `useRouteParams()` / `useRoute()` inside the
+ * rendered route see this match. Use instead of (or nested within) a `boot`-time
+ * `routingSpec`.
+ */
+declare const Routes: ({ children, fallback, }: {
+    children?: ReactNode;
+    fallback?: ReactNode;
+}) => react_jsx_runtime.JSX.Element;
+
+export { Route, type RouteProps, Routes };

package/dist/components/Routes.js

@@ -0,0 +1,34 @@
+import { Fragment, jsx } from "react/jsx-runtime";
+import { Children, isValidElement, use } from "react";
+import { TinkerableContext } from "../TinkerableContext";
+import { matchRoute } from "../routeMatch";
+import { renderRoute } from "../routing";
+const Route = (_props) => null;
+const Routes = ({
+  children,
+  fallback = null
+}) => {
+  const context = use(TinkerableContext);
+  const { sandboxPath } = context.navigationState;
+  for (const child of Children.toArray(children)) {
+    if (!isValidElement(child) || child.type !== Route) {
+      continue;
+    }
+    const { path, element, component, name } = child.props;
+    const params = matchRoute(path, sandboxPath);
+    if (params) {
+      const routingRule = { name, pattern: path, element, component };
+      const scoped = {
+        ...context,
+        navigationState: { ...context.navigationState, routingRule, pathParameters: params }
+      };
+      return /* @__PURE__ */ jsx(TinkerableContext, { value: scoped, children: renderRoute(routingRule, params) });
+    }
+  }
+  return /* @__PURE__ */ jsx(Fragment, { children: fallback });
+};
+export {
+  Route,
+  Routes
+};
+//# sourceMappingURL=Routes.js.map

package/dist/components/Routes.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/Routes.tsx"],"sourcesContent":["import type { ReactNode } from 'react';\nimport { Children, isValidElement, use } from 'react';\n\nimport { TinkerableContext } from '../TinkerableContext';\nimport type { RouteComponent, RoutingRule } from '../RoutingSpec';\nimport { matchRoute } from '../routeMatch';\nimport { renderRoute } from '../routing';\n\n/** Props for a {@link Route} declared inside {@link Routes}. */\nexport type RouteProps = {\n  /** A path template (`/posts/:slug`, `/files/*`, `/`) or a raw RegExp. */\n  path: string | RegExp;\n  name?: string;\n  /** Element to render; reads params via `useRouteParams()`. */\n  element?: ReactNode;\n  /** Component to render; receives matched params as a prop. */\n  component?: RouteComponent;\n};\n\n/**\n * Declares a route. Rendered as a child of `<Routes>`, where it is read for its\n * props — it renders nothing on its own. Mounting a `<Route>` registers it;\n * unmounting (or conditionally not rendering it) removes it, which is how routes\n * become dynamic without a mutable registry.\n */\nexport const Route = (_props: RouteProps): null => null;\n\n/**\n * Resolves the active `sandboxPath` against its mounted `<Route>` children,\n * first-match-wins in render order, and renders the winner (or `fallback`). The\n * match scopes a nested context so `useRouteParams()` / `useRoute()` inside the\n * rendered route see this match. Use instead of (or nested within) a `boot`-time\n * `routingSpec`.\n */\nexport const Routes = ({\n  children,\n  fallback = null,\n}: {\n  children?: ReactNode;\n  fallback?: ReactNode;\n}) => {\n  const context = use(TinkerableContext);\n  const { sandboxPath } = context.navigationState;\n\n  for (const child of Children.toArray(children)) {\n    if (!isValidElement(child) || child.type !== Route) {\n      continue;\n    }\n    const { path, element, component, name } = child.props as RouteProps;\n    const params = matchRoute(path, sandboxPath);\n    if (params) {\n      const routingRule: RoutingRule = { name, pattern: path, element, component };\n      const scoped = {\n        ...context,\n        navigationState: { ...context.navigationState, routingRule, pathParameters: params },\n      };\n      return (\n        <TinkerableContext value={scoped}>\n          {renderRoute(routingRule, params)}\n        </TinkerableContext>\n      );\n    }\n  }\n\n  return <>{fallback}</>;\n};\n"],"mappings":"AAyDQ,SAOC,UAPD;AAxDR,SAAS,UAAU,gBAAgB,WAAW;AAE9C,SAAS,yBAAyB;AAElC,SAAS,kBAAkB;AAC3B,SAAS,mBAAmB;AAmBrB,MAAM,QAAQ,CAAC,WAA6B;AAS5C,MAAM,SAAS,CAAC;AAAA,EACrB;AAAA,EACA,WAAW;AACb,MAGM;AACJ,QAAM,UAAU,IAAI,iBAAiB;AACrC,QAAM,EAAE,YAAY,IAAI,QAAQ;AAEhC,aAAW,SAAS,SAAS,QAAQ,QAAQ,GAAG;AAC9C,QAAI,CAAC,eAAe,KAAK,KAAK,MAAM,SAAS,OAAO;AAClD;AAAA,IACF;AACA,UAAM,EAAE,MAAM,SAAS,WAAW,KAAK,IAAI,MAAM;AACjD,UAAM,SAAS,WAAW,MAAM,WAAW;AAC3C,QAAI,QAAQ;AACV,YAAM,cAA2B,EAAE,MAAM,SAAS,MAAM,SAAS,UAAU;AAC3E,YAAM,SAAS;AAAA,QACb,GAAG;AAAA,QACH,iBAAiB,EAAE,GAAG,QAAQ,iBAAiB,aAAa,gBAAgB,OAAO;AAAA,MACrF;AACA,aACE,oBAAC,qBAAkB,OAAO,QACvB,sBAAY,aAAa,MAAM,GAClC;AAAA,IAEJ;AAAA,EACF;AAEA,SAAO,gCAAG,oBAAS;AACrB;","names":[]}

package/dist/contribute.cjs.map

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

package/dist/contribute.d.cts

@@ -73,6 +73,8 @@ interface ContributionResult {
     branchName: string;
     mode: 'direct-commit' | 'new-branch-pr' | 'extend-existing';
 }
+/** Options for a contribution: the commit message, save {@link ContributeMode},
+ *  and (PR mode) an optional branch name. */
 interface ContributeOptions {
     /** The commit message / PR title. */
     commitMessage: string;

package/dist/contribute.d.ts

@@ -73,6 +73,8 @@ interface ContributionResult {
     branchName: string;
     mode: 'direct-commit' | 'new-branch-pr' | 'extend-existing';
 }
+/** Options for a contribution: the commit message, save {@link ContributeMode},
+ *  and (PR mode) an optional branch name. */
 interface ContributeOptions {
     /** The commit message / PR title. */
     commitMessage: string;

package/dist/contribute.js.map

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

package/dist/diagnostics.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/diagnostics.ts"],"sourcesContent":["// The `diagnostics:read` channel — app-facing surface (LLM_AND_AGENTS_SPEC §3.3/§4,\n// D4; roadmap R3-74 / P3-72).\n//\n// A *sibling* agent app (one holding `diagnostics:read`) observes the result of its\n// edits to the PREVIEWED app: the build/transpile errors from the sandbox bundler\n// and the previewed app's captured `console.*`. This is the in-browser analogue of\n// a local coding agent reading compiler/test output (P3-73's `get_diagnostics()`\n// tool). Read-only and scoped host-side to the paired previewed app's OWN\n// diagnostics — never another app's (the host channel projection enforces it; the\n// previewed app itself holds no `diagnostics:read`, so it is origin-excluded).\n//\n// Recipe-A push channel, identical get/onChange/use trio as `secrets`/`catalog`:\n// the host pushes `diagnostics` on change and answers a `request-diagnostics` poll,\n// gated per-frame by the read ACL. Inert until the host wires the channel\n// (site-main `channelBridge`); the contract ships here so the agent app (P3-73) can\n// be written against it.\nimport { createPushChannel } from './pushChannel';\n\n/** One build/transpile error from the sandbox bundler's compile of the previewed\n *  app. `path` is repo-relative (leading slash) when the error is file-located. */\nexport interface BuildError {\n  message: string;\n  path?: string;\n  line?: number;\n  column?: number;\n}\n\nexport type ConsoleLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';\n\n/** One captured `console.*` entry from the previewed app. The host renders the\n *  console arguments to text host-side — the agent never receives live object\n *  handles across the boundary. */\nexport interface ConsoleEntry {\n  level: ConsoleLevel;\n  text: string;\n  /** Host-side timestamp (ms) at capture. */\n  at: number;\n}\n\n/** Provenance (D4 / EDITOR_AS_APP_SPEC §12.3): WHICH previewed app + compile this\n *  snapshot describes, so a consumer can tell stale output from fresh and never\n *  conflates two apps' diagnostics. `null` until a first compile is observed. */\nexport interface DiagnosticsProvenance {\n  /** The previewed app's stable key (`provider/ns/repo`). */\n  appKey?: string;\n  /** Monotonic id of the compile that produced these build errors. */\n  compileId?: string;\n}\n\nexport interface Diagnostics {\n  buildErrors: BuildError[];\n  consoleEntries: ConsoleEntry[];\n  provenance: DiagnosticsProvenance | null;\n}\n\n/** Value before the host answers — also the value when the app may not read the\n *  channel (no `diagnostics:read`): an empty, provenance-less snapshot. */\nconst EMPTY: Diagnostics = { buildErrors: [], consoleEntries: [], provenance: null };\n\nconst channel = createPushChannel<Diagnostics>({\n  pushType: 'diagnostics',\n  requestType: 'request-diagnostics',\n  initial: EMPTY,\n  parse: (msg) => {\n    // Require both arrays; tolerate an absent/partial provenance. A malformed push\n    // is ignored (returns undefined) so the last good snapshot stands.\n    if (!Array.isArray(msg.buildErrors) || !Array.isArray(msg.consoleEntries)) return undefined;\n    const provenance =\n      msg.provenance && typeof msg.provenance === 'object'\n        ? (msg.provenance as DiagnosticsProvenance)\n        : null;\n    return {\n      buildErrors: msg.buildErrors as BuildError[],\n      consoleEntries: msg.consoleEntries as ConsoleEntry[],\n      provenance,\n    };\n  },\n});\n\n/** One-off read of the previewed app's current diagnostics. Returns the empty\n *  snapshot until the host answers (or if the app lacks `diagnostics:read`). Use\n *  {@link onDiagnosticsChange}/{@link useDiagnostics} to react to live updates. */\nexport const getDiagnostics = (): Diagnostics => channel.get();\n\n/** Subscribe to diagnostics. Invoked immediately with the current value, then on\n *  every host push. Returns an unsubscribe. */\nexport const onDiagnosticsChange = (listener: (d: Diagnostics) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook: the current diagnostics, re-rendering on every change. */\nexport const useDiagnostics = (): Diagnostics => channel.use();\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgBA,yBAAkC;AAyClC,MAAM,QAAqB,EAAE,aAAa,CAAC,GAAG,gBAAgB,CAAC,GAAG,YAAY,KAAK;AAEnF,MAAM,cAAU,sCAA+B;AAAA,EAC7C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAQ;AAGd,QAAI,CAAC,MAAM,QAAQ,IAAI,WAAW,KAAK,CAAC,MAAM,QAAQ,IAAI,cAAc,EAAG,QAAO;AAClF,UAAM,aACJ,IAAI,cAAc,OAAO,IAAI,eAAe,WACvC,IAAI,aACL;AACN,WAAO;AAAA,MACL,aAAa,IAAI;AAAA,MACjB,gBAAgB,IAAI;AAAA,MACpB;AAAA,IACF;AAAA,EACF;AACF,CAAC;AAKM,MAAM,iBAAiB,MAAmB,QAAQ,IAAI;AAItD,MAAM,sBAAsB,CAAC,aAClC,QAAQ,SAAS,QAAQ;AAGpB,MAAM,iBAAiB,MAAmB,QAAQ,IAAI;","names":[]}
+{"version":3,"sources":["../src/diagnostics.ts"],"sourcesContent":["// The `diagnostics:read` channel — app-facing surface (LLM_AND_AGENTS_SPEC §3.3/§4,\n// D4; roadmap R3-74 / P3-72).\n//\n// A *sibling* agent app (one holding `diagnostics:read`) observes the result of its\n// edits to the PREVIEWED app: the build/transpile errors from the sandbox bundler\n// and the previewed app's captured `console.*`. This is the in-browser analogue of\n// a local coding agent reading compiler/test output (P3-73's `get_diagnostics()`\n// tool). Read-only and scoped host-side to the paired previewed app's OWN\n// diagnostics — never another app's (the host channel projection enforces it; the\n// previewed app itself holds no `diagnostics:read`, so it is origin-excluded).\n//\n// Recipe-A push channel, identical get/onChange/use trio as `secrets`/`catalog`:\n// the host pushes `diagnostics` on change and answers a `request-diagnostics` poll,\n// gated per-frame by the read ACL. Inert until the host wires the channel\n// (site-main `channelBridge`); the contract ships here so the agent app (P3-73) can\n// be written against it.\nimport { createPushChannel } from './pushChannel';\n\n/** One build/transpile error from the sandbox bundler's compile of the previewed\n *  app. `path` is repo-relative (leading slash) when the error is file-located. */\nexport interface BuildError {\n  message: string;\n  path?: string;\n  line?: number;\n  column?: number;\n}\n\n/** The `console.*` method a captured entry came from. */\nexport type ConsoleLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';\n\n/** One captured `console.*` entry from the previewed app. The host renders the\n *  console arguments to text host-side — the agent never receives live object\n *  handles across the boundary. */\nexport interface ConsoleEntry {\n  level: ConsoleLevel;\n  text: string;\n  /** Host-side timestamp (ms) at capture. */\n  at: number;\n}\n\n/** Provenance (D4 / EDITOR_AS_APP_SPEC §12.3): WHICH previewed app + compile this\n *  snapshot describes, so a consumer can tell stale output from fresh and never\n *  conflates two apps' diagnostics. `null` until a first compile is observed. */\nexport interface DiagnosticsProvenance {\n  /** The previewed app's stable key (`provider/ns/repo`). */\n  appKey?: string;\n  /** Monotonic id of the compile that produced these build errors. */\n  compileId?: string;\n}\n\n/** A snapshot of the previewed app's diagnostics: its build errors, captured\n *  console output, and the {@link DiagnosticsProvenance} of the compile. */\nexport interface Diagnostics {\n  buildErrors: BuildError[];\n  consoleEntries: ConsoleEntry[];\n  provenance: DiagnosticsProvenance | null;\n}\n\n/** Value before the host answers — also the value when the app may not read the\n *  channel (no `diagnostics:read`): an empty, provenance-less snapshot. */\nconst EMPTY: Diagnostics = { buildErrors: [], consoleEntries: [], provenance: null };\n\nconst channel = createPushChannel<Diagnostics>({\n  pushType: 'diagnostics',\n  requestType: 'request-diagnostics',\n  initial: EMPTY,\n  parse: (msg) => {\n    // Require both arrays; tolerate an absent/partial provenance. A malformed push\n    // is ignored (returns undefined) so the last good snapshot stands.\n    if (!Array.isArray(msg.buildErrors) || !Array.isArray(msg.consoleEntries)) return undefined;\n    const provenance =\n      msg.provenance && typeof msg.provenance === 'object'\n        ? (msg.provenance as DiagnosticsProvenance)\n        : null;\n    return {\n      buildErrors: msg.buildErrors as BuildError[],\n      consoleEntries: msg.consoleEntries as ConsoleEntry[],\n      provenance,\n    };\n  },\n});\n\n/** One-off read of the previewed app's current diagnostics. Returns the empty\n *  snapshot until the host answers (or if the app lacks `diagnostics:read`). Use\n *  {@link onDiagnosticsChange}/{@link useDiagnostics} to react to live updates. */\nexport const getDiagnostics = (): Diagnostics => channel.get();\n\n/** Subscribe to diagnostics. Invoked immediately with the current value, then on\n *  every host push. Returns an unsubscribe. */\nexport const onDiagnosticsChange = (listener: (d: Diagnostics) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook: the current diagnostics, re-rendering on every change. */\nexport const useDiagnostics = (): Diagnostics => channel.use();\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgBA,yBAAkC;AA4ClC,MAAM,QAAqB,EAAE,aAAa,CAAC,GAAG,gBAAgB,CAAC,GAAG,YAAY,KAAK;AAEnF,MAAM,cAAU,sCAA+B;AAAA,EAC7C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAQ;AAGd,QAAI,CAAC,MAAM,QAAQ,IAAI,WAAW,KAAK,CAAC,MAAM,QAAQ,IAAI,cAAc,EAAG,QAAO;AAClF,UAAM,aACJ,IAAI,cAAc,OAAO,IAAI,eAAe,WACvC,IAAI,aACL;AACN,WAAO;AAAA,MACL,aAAa,IAAI;AAAA,MACjB,gBAAgB,IAAI;AAAA,MACpB;AAAA,IACF;AAAA,EACF;AACF,CAAC;AAKM,MAAM,iBAAiB,MAAmB,QAAQ,IAAI;AAItD,MAAM,sBAAsB,CAAC,aAClC,QAAQ,SAAS,QAAQ;AAGpB,MAAM,iBAAiB,MAAmB,QAAQ,IAAI;","names":[]}

package/dist/diagnostics.d.cts

@@ -6,6 +6,7 @@ interface BuildError {
     line?: number;
     column?: number;
 }
+/** The `console.*` method a captured entry came from. */
 type ConsoleLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
 /** One captured `console.*` entry from the previewed app. The host renders the
  *  console arguments to text host-side — the agent never receives live object
@@ -25,6 +26,8 @@ interface DiagnosticsProvenance {
     /** Monotonic id of the compile that produced these build errors. */
     compileId?: string;
 }
+/** A snapshot of the previewed app's diagnostics: its build errors, captured
+ *  console output, and the {@link DiagnosticsProvenance} of the compile. */
 interface Diagnostics {
     buildErrors: BuildError[];
     consoleEntries: ConsoleEntry[];

package/dist/diagnostics.d.ts

@@ -6,6 +6,7 @@ interface BuildError {
     line?: number;
     column?: number;
 }
+/** The `console.*` method a captured entry came from. */
 type ConsoleLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';
 /** One captured `console.*` entry from the previewed app. The host renders the
  *  console arguments to text host-side — the agent never receives live object
@@ -25,6 +26,8 @@ interface DiagnosticsProvenance {
     /** Monotonic id of the compile that produced these build errors. */
     compileId?: string;
 }
+/** A snapshot of the previewed app's diagnostics: its build errors, captured
+ *  console output, and the {@link DiagnosticsProvenance} of the compile. */
 interface Diagnostics {
     buildErrors: BuildError[];
     consoleEntries: ConsoleEntry[];

package/dist/diagnostics.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/diagnostics.ts"],"sourcesContent":["// The `diagnostics:read` channel — app-facing surface (LLM_AND_AGENTS_SPEC §3.3/§4,\n// D4; roadmap R3-74 / P3-72).\n//\n// A *sibling* agent app (one holding `diagnostics:read`) observes the result of its\n// edits to the PREVIEWED app: the build/transpile errors from the sandbox bundler\n// and the previewed app's captured `console.*`. This is the in-browser analogue of\n// a local coding agent reading compiler/test output (P3-73's `get_diagnostics()`\n// tool). Read-only and scoped host-side to the paired previewed app's OWN\n// diagnostics — never another app's (the host channel projection enforces it; the\n// previewed app itself holds no `diagnostics:read`, so it is origin-excluded).\n//\n// Recipe-A push channel, identical get/onChange/use trio as `secrets`/`catalog`:\n// the host pushes `diagnostics` on change and answers a `request-diagnostics` poll,\n// gated per-frame by the read ACL. Inert until the host wires the channel\n// (site-main `channelBridge`); the contract ships here so the agent app (P3-73) can\n// be written against it.\nimport { createPushChannel } from './pushChannel';\n\n/** One build/transpile error from the sandbox bundler's compile of the previewed\n *  app. `path` is repo-relative (leading slash) when the error is file-located. */\nexport interface BuildError {\n  message: string;\n  path?: string;\n  line?: number;\n  column?: number;\n}\n\nexport type ConsoleLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';\n\n/** One captured `console.*` entry from the previewed app. The host renders the\n *  console arguments to text host-side — the agent never receives live object\n *  handles across the boundary. */\nexport interface ConsoleEntry {\n  level: ConsoleLevel;\n  text: string;\n  /** Host-side timestamp (ms) at capture. */\n  at: number;\n}\n\n/** Provenance (D4 / EDITOR_AS_APP_SPEC §12.3): WHICH previewed app + compile this\n *  snapshot describes, so a consumer can tell stale output from fresh and never\n *  conflates two apps' diagnostics. `null` until a first compile is observed. */\nexport interface DiagnosticsProvenance {\n  /** The previewed app's stable key (`provider/ns/repo`). */\n  appKey?: string;\n  /** Monotonic id of the compile that produced these build errors. */\n  compileId?: string;\n}\n\nexport interface Diagnostics {\n  buildErrors: BuildError[];\n  consoleEntries: ConsoleEntry[];\n  provenance: DiagnosticsProvenance | null;\n}\n\n/** Value before the host answers — also the value when the app may not read the\n *  channel (no `diagnostics:read`): an empty, provenance-less snapshot. */\nconst EMPTY: Diagnostics = { buildErrors: [], consoleEntries: [], provenance: null };\n\nconst channel = createPushChannel<Diagnostics>({\n  pushType: 'diagnostics',\n  requestType: 'request-diagnostics',\n  initial: EMPTY,\n  parse: (msg) => {\n    // Require both arrays; tolerate an absent/partial provenance. A malformed push\n    // is ignored (returns undefined) so the last good snapshot stands.\n    if (!Array.isArray(msg.buildErrors) || !Array.isArray(msg.consoleEntries)) return undefined;\n    const provenance =\n      msg.provenance && typeof msg.provenance === 'object'\n        ? (msg.provenance as DiagnosticsProvenance)\n        : null;\n    return {\n      buildErrors: msg.buildErrors as BuildError[],\n      consoleEntries: msg.consoleEntries as ConsoleEntry[],\n      provenance,\n    };\n  },\n});\n\n/** One-off read of the previewed app's current diagnostics. Returns the empty\n *  snapshot until the host answers (or if the app lacks `diagnostics:read`). Use\n *  {@link onDiagnosticsChange}/{@link useDiagnostics} to react to live updates. */\nexport const getDiagnostics = (): Diagnostics => channel.get();\n\n/** Subscribe to diagnostics. Invoked immediately with the current value, then on\n *  every host push. Returns an unsubscribe. */\nexport const onDiagnosticsChange = (listener: (d: Diagnostics) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook: the current diagnostics, re-rendering on every change. */\nexport const useDiagnostics = (): Diagnostics => channel.use();\n"],"mappings":"AAgBA,SAAS,yBAAyB;AAyClC,MAAM,QAAqB,EAAE,aAAa,CAAC,GAAG,gBAAgB,CAAC,GAAG,YAAY,KAAK;AAEnF,MAAM,UAAU,kBAA+B;AAAA,EAC7C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAQ;AAGd,QAAI,CAAC,MAAM,QAAQ,IAAI,WAAW,KAAK,CAAC,MAAM,QAAQ,IAAI,cAAc,EAAG,QAAO;AAClF,UAAM,aACJ,IAAI,cAAc,OAAO,IAAI,eAAe,WACvC,IAAI,aACL;AACN,WAAO;AAAA,MACL,aAAa,IAAI;AAAA,MACjB,gBAAgB,IAAI;AAAA,MACpB;AAAA,IACF;AAAA,EACF;AACF,CAAC;AAKM,MAAM,iBAAiB,MAAmB,QAAQ,IAAI;AAItD,MAAM,sBAAsB,CAAC,aAClC,QAAQ,SAAS,QAAQ;AAGpB,MAAM,iBAAiB,MAAmB,QAAQ,IAAI;","names":[]}
+{"version":3,"sources":["../src/diagnostics.ts"],"sourcesContent":["// The `diagnostics:read` channel — app-facing surface (LLM_AND_AGENTS_SPEC §3.3/§4,\n// D4; roadmap R3-74 / P3-72).\n//\n// A *sibling* agent app (one holding `diagnostics:read`) observes the result of its\n// edits to the PREVIEWED app: the build/transpile errors from the sandbox bundler\n// and the previewed app's captured `console.*`. This is the in-browser analogue of\n// a local coding agent reading compiler/test output (P3-73's `get_diagnostics()`\n// tool). Read-only and scoped host-side to the paired previewed app's OWN\n// diagnostics — never another app's (the host channel projection enforces it; the\n// previewed app itself holds no `diagnostics:read`, so it is origin-excluded).\n//\n// Recipe-A push channel, identical get/onChange/use trio as `secrets`/`catalog`:\n// the host pushes `diagnostics` on change and answers a `request-diagnostics` poll,\n// gated per-frame by the read ACL. Inert until the host wires the channel\n// (site-main `channelBridge`); the contract ships here so the agent app (P3-73) can\n// be written against it.\nimport { createPushChannel } from './pushChannel';\n\n/** One build/transpile error from the sandbox bundler's compile of the previewed\n *  app. `path` is repo-relative (leading slash) when the error is file-located. */\nexport interface BuildError {\n  message: string;\n  path?: string;\n  line?: number;\n  column?: number;\n}\n\n/** The `console.*` method a captured entry came from. */\nexport type ConsoleLevel = 'log' | 'info' | 'warn' | 'error' | 'debug';\n\n/** One captured `console.*` entry from the previewed app. The host renders the\n *  console arguments to text host-side — the agent never receives live object\n *  handles across the boundary. */\nexport interface ConsoleEntry {\n  level: ConsoleLevel;\n  text: string;\n  /** Host-side timestamp (ms) at capture. */\n  at: number;\n}\n\n/** Provenance (D4 / EDITOR_AS_APP_SPEC §12.3): WHICH previewed app + compile this\n *  snapshot describes, so a consumer can tell stale output from fresh and never\n *  conflates two apps' diagnostics. `null` until a first compile is observed. */\nexport interface DiagnosticsProvenance {\n  /** The previewed app's stable key (`provider/ns/repo`). */\n  appKey?: string;\n  /** Monotonic id of the compile that produced these build errors. */\n  compileId?: string;\n}\n\n/** A snapshot of the previewed app's diagnostics: its build errors, captured\n *  console output, and the {@link DiagnosticsProvenance} of the compile. */\nexport interface Diagnostics {\n  buildErrors: BuildError[];\n  consoleEntries: ConsoleEntry[];\n  provenance: DiagnosticsProvenance | null;\n}\n\n/** Value before the host answers — also the value when the app may not read the\n *  channel (no `diagnostics:read`): an empty, provenance-less snapshot. */\nconst EMPTY: Diagnostics = { buildErrors: [], consoleEntries: [], provenance: null };\n\nconst channel = createPushChannel<Diagnostics>({\n  pushType: 'diagnostics',\n  requestType: 'request-diagnostics',\n  initial: EMPTY,\n  parse: (msg) => {\n    // Require both arrays; tolerate an absent/partial provenance. A malformed push\n    // is ignored (returns undefined) so the last good snapshot stands.\n    if (!Array.isArray(msg.buildErrors) || !Array.isArray(msg.consoleEntries)) return undefined;\n    const provenance =\n      msg.provenance && typeof msg.provenance === 'object'\n        ? (msg.provenance as DiagnosticsProvenance)\n        : null;\n    return {\n      buildErrors: msg.buildErrors as BuildError[],\n      consoleEntries: msg.consoleEntries as ConsoleEntry[],\n      provenance,\n    };\n  },\n});\n\n/** One-off read of the previewed app's current diagnostics. Returns the empty\n *  snapshot until the host answers (or if the app lacks `diagnostics:read`). Use\n *  {@link onDiagnosticsChange}/{@link useDiagnostics} to react to live updates. */\nexport const getDiagnostics = (): Diagnostics => channel.get();\n\n/** Subscribe to diagnostics. Invoked immediately with the current value, then on\n *  every host push. Returns an unsubscribe. */\nexport const onDiagnosticsChange = (listener: (d: Diagnostics) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook: the current diagnostics, re-rendering on every change. */\nexport const useDiagnostics = (): Diagnostics => channel.use();\n"],"mappings":"AAgBA,SAAS,yBAAyB;AA4ClC,MAAM,QAAqB,EAAE,aAAa,CAAC,GAAG,gBAAgB,CAAC,GAAG,YAAY,KAAK;AAEnF,MAAM,UAAU,kBAA+B;AAAA,EAC7C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAQ;AAGd,QAAI,CAAC,MAAM,QAAQ,IAAI,WAAW,KAAK,CAAC,MAAM,QAAQ,IAAI,cAAc,EAAG,QAAO;AAClF,UAAM,aACJ,IAAI,cAAc,OAAO,IAAI,eAAe,WACvC,IAAI,aACL;AACN,WAAO;AAAA,MACL,aAAa,IAAI;AAAA,MACjB,gBAAgB,IAAI;AAAA,MACpB;AAAA,IACF;AAAA,EACF;AACF,CAAC;AAKM,MAAM,iBAAiB,MAAmB,QAAQ,IAAI;AAItD,MAAM,sBAAsB,CAAC,aAClC,QAAQ,SAAS,QAAQ;AAGpB,MAAM,iBAAiB,MAAmB,QAAQ,IAAI;","names":[]}

package/dist/formFactor.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/formFactor.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\n\n/**\n * The form factor of the surface your app is rendered into, mirrored from the\n * immediately.run host (UI_AS_APPS_SPEC §5.4.1). Read this to lay out\n * responsively — a narrow chrome panel, a full preview, or a mobile carousel\n * pane all report their box here. The host is the source of truth (it owns the\n * region); you cannot reliably measure your own viewport across the sandbox\n * boundary.\n *\n * Baseline capability `formFactor:read` — every app may read it.\n */\nexport type FormFactorClass = 'mobile' | 'tablet' | 'desktop';\nexport type Orientation = 'portrait' | 'landscape';\n\nexport interface FormFactor {\n  class: FormFactorClass;\n  orientation: Orientation;\n  width: number;\n  height: number;\n}\n\n/** Assumed before the host reports — a reasonable desktop default. */\nconst DEFAULT_FORM_FACTOR: FormFactor = {\n  class: 'desktop',\n  orientation: 'landscape',\n  width: 1280,\n  height: 800,\n};\n\nconst isFormFactor = (v: unknown): v is FormFactor => {\n  const f = v as Partial<FormFactor> | null;\n  return (\n    !!f &&\n    (f.class === 'mobile' || f.class === 'tablet' || f.class === 'desktop') &&\n    (f.orientation === 'portrait' || f.orientation === 'landscape') &&\n    typeof f.width === 'number' &&\n    typeof f.height === 'number'\n  );\n};\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `form-factor`\n// and answers `request-form-factor` (wire format: site-main channelBridge.ts).\nconst channel = createPushChannel<FormFactor>({\n  pushType: 'form-factor',\n  requestType: 'request-form-factor',\n  initial: DEFAULT_FORM_FACTOR,\n  parse: (msg) => (isFormFactor(msg.formFactor) ? (msg.formFactor as FormFactor) : undefined),\n});\n\n/** Returns the current form factor. Poll for a one-off read. */\nexport const getFormFactor = (): FormFactor => channel.get();\n\n/**\n * Subscribe to form-factor changes. The listener is invoked immediately with\n * the current value, then again on every change. Returns an unsubscribe fn.\n */\nexport const onFormFactorChange = (listener: (formFactor: FormFactor) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook returning the current form factor, re-rendering on change. */\nexport const useFormFactor = (): FormFactor => channel.use();\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,yBAAkC;AAuBlC,MAAM,sBAAkC;AAAA,EACtC,OAAO;AAAA,EACP,aAAa;AAAA,EACb,OAAO;AAAA,EACP,QAAQ;AACV;AAEA,MAAM,eAAe,CAAC,MAAgC;AACpD,QAAM,IAAI;AACV,SACE,CAAC,CAAC,MACD,EAAE,UAAU,YAAY,EAAE,UAAU,YAAY,EAAE,UAAU,eAC5D,EAAE,gBAAgB,cAAc,EAAE,gBAAgB,gBACnD,OAAO,EAAE,UAAU,YACnB,OAAO,EAAE,WAAW;AAExB;AAIA,MAAM,cAAU,sCAA8B;AAAA,EAC5C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAS,aAAa,IAAI,UAAU,IAAK,IAAI,aAA4B;AACnF,CAAC;AAGM,MAAM,gBAAgB,MAAkB,QAAQ,IAAI;AAMpD,MAAM,qBAAqB,CAAC,aACjC,QAAQ,SAAS,QAAQ;AAGpB,MAAM,gBAAgB,MAAkB,QAAQ,IAAI;","names":[]}
+{"version":3,"sources":["../src/formFactor.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\n\n/**\n * The form factor of the surface your app is rendered into, mirrored from the\n * immediately.run host (UI_AS_APPS_SPEC §5.4.1). Read this to lay out\n * responsively — a narrow chrome panel, a full preview, or a mobile carousel\n * pane all report their box here. The host is the source of truth (it owns the\n * region); you cannot reliably measure your own viewport across the sandbox\n * boundary.\n *\n * Baseline capability `formFactor:read` — every app may read it.\n */\nexport type FormFactorClass = 'mobile' | 'tablet' | 'desktop';\n/** Whether the rendered surface is taller than wide (`portrait`) or wider (`landscape`). */\nexport type Orientation = 'portrait' | 'landscape';\n\n/** The host-reported size class, orientation, and pixel box of your app's surface. */\nexport interface FormFactor {\n  class: FormFactorClass;\n  orientation: Orientation;\n  width: number;\n  height: number;\n}\n\n/** Assumed before the host reports — a reasonable desktop default. */\nconst DEFAULT_FORM_FACTOR: FormFactor = {\n  class: 'desktop',\n  orientation: 'landscape',\n  width: 1280,\n  height: 800,\n};\n\nconst isFormFactor = (v: unknown): v is FormFactor => {\n  const f = v as Partial<FormFactor> | null;\n  return (\n    !!f &&\n    (f.class === 'mobile' || f.class === 'tablet' || f.class === 'desktop') &&\n    (f.orientation === 'portrait' || f.orientation === 'landscape') &&\n    typeof f.width === 'number' &&\n    typeof f.height === 'number'\n  );\n};\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `form-factor`\n// and answers `request-form-factor` (wire format: site-main channelBridge.ts).\nconst channel = createPushChannel<FormFactor>({\n  pushType: 'form-factor',\n  requestType: 'request-form-factor',\n  initial: DEFAULT_FORM_FACTOR,\n  parse: (msg) => (isFormFactor(msg.formFactor) ? (msg.formFactor as FormFactor) : undefined),\n});\n\n/** Returns the current form factor. Poll for a one-off read. */\nexport const getFormFactor = (): FormFactor => channel.get();\n\n/**\n * Subscribe to form-factor changes. The listener is invoked immediately with\n * the current value, then again on every change. Returns an unsubscribe fn.\n */\nexport const onFormFactorChange = (listener: (formFactor: FormFactor) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook returning the current form factor, re-rendering on change. */\nexport const useFormFactor = (): FormFactor => channel.use();\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,yBAAkC;AAyBlC,MAAM,sBAAkC;AAAA,EACtC,OAAO;AAAA,EACP,aAAa;AAAA,EACb,OAAO;AAAA,EACP,QAAQ;AACV;AAEA,MAAM,eAAe,CAAC,MAAgC;AACpD,QAAM,IAAI;AACV,SACE,CAAC,CAAC,MACD,EAAE,UAAU,YAAY,EAAE,UAAU,YAAY,EAAE,UAAU,eAC5D,EAAE,gBAAgB,cAAc,EAAE,gBAAgB,gBACnD,OAAO,EAAE,UAAU,YACnB,OAAO,EAAE,WAAW;AAExB;AAIA,MAAM,cAAU,sCAA8B;AAAA,EAC5C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAS,aAAa,IAAI,UAAU,IAAK,IAAI,aAA4B;AACnF,CAAC;AAGM,MAAM,gBAAgB,MAAkB,QAAQ,IAAI;AAMpD,MAAM,qBAAqB,CAAC,aACjC,QAAQ,SAAS,QAAQ;AAGpB,MAAM,gBAAgB,MAAkB,QAAQ,IAAI;","names":[]}

package/dist/formFactor.d.cts

@@ -9,7 +9,9 @@
  * Baseline capability `formFactor:read` — every app may read it.
  */
 type FormFactorClass = 'mobile' | 'tablet' | 'desktop';
+/** Whether the rendered surface is taller than wide (`portrait`) or wider (`landscape`). */
 type Orientation = 'portrait' | 'landscape';
+/** The host-reported size class, orientation, and pixel box of your app's surface. */
 interface FormFactor {
     class: FormFactorClass;
     orientation: Orientation;

package/dist/formFactor.d.ts

@@ -9,7 +9,9 @@
  * Baseline capability `formFactor:read` — every app may read it.
  */
 type FormFactorClass = 'mobile' | 'tablet' | 'desktop';
+/** Whether the rendered surface is taller than wide (`portrait`) or wider (`landscape`). */
 type Orientation = 'portrait' | 'landscape';
+/** The host-reported size class, orientation, and pixel box of your app's surface. */
 interface FormFactor {
     class: FormFactorClass;
     orientation: Orientation;

package/dist/formFactor.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/formFactor.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\n\n/**\n * The form factor of the surface your app is rendered into, mirrored from the\n * immediately.run host (UI_AS_APPS_SPEC §5.4.1). Read this to lay out\n * responsively — a narrow chrome panel, a full preview, or a mobile carousel\n * pane all report their box here. The host is the source of truth (it owns the\n * region); you cannot reliably measure your own viewport across the sandbox\n * boundary.\n *\n * Baseline capability `formFactor:read` — every app may read it.\n */\nexport type FormFactorClass = 'mobile' | 'tablet' | 'desktop';\nexport type Orientation = 'portrait' | 'landscape';\n\nexport interface FormFactor {\n  class: FormFactorClass;\n  orientation: Orientation;\n  width: number;\n  height: number;\n}\n\n/** Assumed before the host reports — a reasonable desktop default. */\nconst DEFAULT_FORM_FACTOR: FormFactor = {\n  class: 'desktop',\n  orientation: 'landscape',\n  width: 1280,\n  height: 800,\n};\n\nconst isFormFactor = (v: unknown): v is FormFactor => {\n  const f = v as Partial<FormFactor> | null;\n  return (\n    !!f &&\n    (f.class === 'mobile' || f.class === 'tablet' || f.class === 'desktop') &&\n    (f.orientation === 'portrait' || f.orientation === 'landscape') &&\n    typeof f.width === 'number' &&\n    typeof f.height === 'number'\n  );\n};\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `form-factor`\n// and answers `request-form-factor` (wire format: site-main channelBridge.ts).\nconst channel = createPushChannel<FormFactor>({\n  pushType: 'form-factor',\n  requestType: 'request-form-factor',\n  initial: DEFAULT_FORM_FACTOR,\n  parse: (msg) => (isFormFactor(msg.formFactor) ? (msg.formFactor as FormFactor) : undefined),\n});\n\n/** Returns the current form factor. Poll for a one-off read. */\nexport const getFormFactor = (): FormFactor => channel.get();\n\n/**\n * Subscribe to form-factor changes. The listener is invoked immediately with\n * the current value, then again on every change. Returns an unsubscribe fn.\n */\nexport const onFormFactorChange = (listener: (formFactor: FormFactor) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook returning the current form factor, re-rendering on change. */\nexport const useFormFactor = (): FormFactor => channel.use();\n"],"mappings":"AAAA,SAAS,yBAAyB;AAuBlC,MAAM,sBAAkC;AAAA,EACtC,OAAO;AAAA,EACP,aAAa;AAAA,EACb,OAAO;AAAA,EACP,QAAQ;AACV;AAEA,MAAM,eAAe,CAAC,MAAgC;AACpD,QAAM,IAAI;AACV,SACE,CAAC,CAAC,MACD,EAAE,UAAU,YAAY,EAAE,UAAU,YAAY,EAAE,UAAU,eAC5D,EAAE,gBAAgB,cAAc,EAAE,gBAAgB,gBACnD,OAAO,EAAE,UAAU,YACnB,OAAO,EAAE,WAAW;AAExB;AAIA,MAAM,UAAU,kBAA8B;AAAA,EAC5C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAS,aAAa,IAAI,UAAU,IAAK,IAAI,aAA4B;AACnF,CAAC;AAGM,MAAM,gBAAgB,MAAkB,QAAQ,IAAI;AAMpD,MAAM,qBAAqB,CAAC,aACjC,QAAQ,SAAS,QAAQ;AAGpB,MAAM,gBAAgB,MAAkB,QAAQ,IAAI;","names":[]}
+{"version":3,"sources":["../src/formFactor.ts"],"sourcesContent":["import { createPushChannel } from './pushChannel';\n\n/**\n * The form factor of the surface your app is rendered into, mirrored from the\n * immediately.run host (UI_AS_APPS_SPEC §5.4.1). Read this to lay out\n * responsively — a narrow chrome panel, a full preview, or a mobile carousel\n * pane all report their box here. The host is the source of truth (it owns the\n * region); you cannot reliably measure your own viewport across the sandbox\n * boundary.\n *\n * Baseline capability `formFactor:read` — every app may read it.\n */\nexport type FormFactorClass = 'mobile' | 'tablet' | 'desktop';\n/** Whether the rendered surface is taller than wide (`portrait`) or wider (`landscape`). */\nexport type Orientation = 'portrait' | 'landscape';\n\n/** The host-reported size class, orientation, and pixel box of your app's surface. */\nexport interface FormFactor {\n  class: FormFactorClass;\n  orientation: Orientation;\n  width: number;\n  height: number;\n}\n\n/** Assumed before the host reports — a reasonable desktop default. */\nconst DEFAULT_FORM_FACTOR: FormFactor = {\n  class: 'desktop',\n  orientation: 'landscape',\n  width: 1280,\n  height: 800,\n};\n\nconst isFormFactor = (v: unknown): v is FormFactor => {\n  const f = v as Partial<FormFactor> | null;\n  return (\n    !!f &&\n    (f.class === 'mobile' || f.class === 'tablet' || f.class === 'desktop') &&\n    (f.orientation === 'portrait' || f.orientation === 'landscape') &&\n    typeof f.width === 'number' &&\n    typeof f.height === 'number'\n  );\n};\n\n// Read over the transport (SDK_PACKAGING_SPEC §4): the host pushes `form-factor`\n// and answers `request-form-factor` (wire format: site-main channelBridge.ts).\nconst channel = createPushChannel<FormFactor>({\n  pushType: 'form-factor',\n  requestType: 'request-form-factor',\n  initial: DEFAULT_FORM_FACTOR,\n  parse: (msg) => (isFormFactor(msg.formFactor) ? (msg.formFactor as FormFactor) : undefined),\n});\n\n/** Returns the current form factor. Poll for a one-off read. */\nexport const getFormFactor = (): FormFactor => channel.get();\n\n/**\n * Subscribe to form-factor changes. The listener is invoked immediately with\n * the current value, then again on every change. Returns an unsubscribe fn.\n */\nexport const onFormFactorChange = (listener: (formFactor: FormFactor) => void): (() => void) =>\n  channel.onChange(listener);\n\n/** React hook returning the current form factor, re-rendering on change. */\nexport const useFormFactor = (): FormFactor => channel.use();\n"],"mappings":"AAAA,SAAS,yBAAyB;AAyBlC,MAAM,sBAAkC;AAAA,EACtC,OAAO;AAAA,EACP,aAAa;AAAA,EACb,OAAO;AAAA,EACP,QAAQ;AACV;AAEA,MAAM,eAAe,CAAC,MAAgC;AACpD,QAAM,IAAI;AACV,SACE,CAAC,CAAC,MACD,EAAE,UAAU,YAAY,EAAE,UAAU,YAAY,EAAE,UAAU,eAC5D,EAAE,gBAAgB,cAAc,EAAE,gBAAgB,gBACnD,OAAO,EAAE,UAAU,YACnB,OAAO,EAAE,WAAW;AAExB;AAIA,MAAM,UAAU,kBAA8B;AAAA,EAC5C,UAAU;AAAA,EACV,aAAa;AAAA,EACb,SAAS;AAAA,EACT,OAAO,CAAC,QAAS,aAAa,IAAI,UAAU,IAAK,IAAI,aAA4B;AACnF,CAAC;AAGM,MAAM,gBAAgB,MAAkB,QAAQ,IAAI;AAMpD,MAAM,qBAAqB,CAAC,aACjC,QAAQ,SAAS,QAAQ;AAGpB,MAAM,gBAAgB,MAAkB,QAAQ,IAAI;","names":[]}

package/dist/hooks.cjs

@@ -18,25 +18,19 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var hooks_exports = {};
 __export(hooks_exports, {
+  useAllMetadata: () => useAllMetadata,
   useFileMetadata: () => useFileMetadata,
   useMetadataQuery: () => useMetadataQuery
 });
 module.exports = __toCommonJS(hooks_exports);
 var import_react = require("react");
 var import_TinkerableContext = require("./TinkerableContext");
-const evaluateQueryFunction = (filesMetadata, queryFunction) => {
-  try {
-    return { result: queryFunction(filesMetadata) };
-  } catch (e) {
-    return { error: e };
-  }
-};
-const arraysEqual = (a, b) => {
+const entriesEqual = (a, b) => {
   if (a.length !== b.length) {
     return false;
   }
   for (let i = 0; i < a.length; i++) {
-    if (a[i] !== b[i]) {
+    if (a[i].path !== b[i].path || a[i].meta !== b[i].meta) {
       return false;
     }
   }
@@ -44,31 +38,36 @@ const arraysEqual = (a, b) => {
 };
 const useMetadataQuery = (queryFunction) => {
   const { filesMetadata } = (0, import_react.use)(import_TinkerableContext.TinkerableContext);
-  const [queryResult, setQueryResult] = (0, import_react.useState)(null);
-  (0, import_react.useEffect)(() => {
-    setQueryResult((prevResult) => {
-      const newResult = evaluateQueryFunction(filesMetadata, queryFunction);
-      if (!prevResult) {
-        return newResult;
-      }
-      if (!("result" in newResult)) {
-        return newResult;
-      }
-      if (!("result" in prevResult)) {
-        return newResult;
-      }
-      return arraysEqual(prevResult.result, newResult.result) ? prevResult : newResult;
-    });
-  }, [filesMetadata, setQueryResult, queryFunction]);
-  return queryResult;
+  const previous = (0, import_react.useRef)([]);
+  return (0, import_react.useMemo)(() => {
+    const files = filesMetadata ?? {};
+    let entries;
+    try {
+      entries = queryFunction(files).map((path) => ({ path, meta: files[path] }));
+    } catch (error) {
+      return { error };
+    }
+    if (entriesEqual(entries, previous.current)) {
+      return previous.current;
+    }
+    previous.current = entries;
+    return entries;
+  }, [filesMetadata, queryFunction]);
 };
 const useFileMetadata = (path) => {
   const { filesMetadata } = (0, import_react.use)(import_TinkerableContext.TinkerableContext);
-  const result = (0, import_react.useMemo)(() => filesMetadata[path], [path, filesMetadata]);
-  return result;
+  return (0, import_react.useMemo)(
+    () => (filesMetadata ?? {})[path],
+    [path, filesMetadata]
+  );
+};
+const useAllMetadata = () => {
+  const { filesMetadata } = (0, import_react.use)(import_TinkerableContext.TinkerableContext);
+  return filesMetadata ?? {};
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  useAllMetadata,
   useFileMetadata,
   useMetadataQuery
 });