@immediately-run/sdk 0.15.0 → 0.17.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/debug.cjs

@@ -0,0 +1,168 @@
+"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 debug_exports = {};
+__export(debug_exports, {
+  debug: () => debug,
+  isDebugEnabled: () => isDebugEnabled,
+  log: () => log,
+  useDebugEnabled: () => useDebugEnabled
+});
+module.exports = __toCommonJS(debug_exports);
+var import_pushChannel = require("./pushChannel");
+var import_sandboxUtils = require("./sandboxUtils");
+const enabledChannel = (0, import_pushChannel.createPushChannel)({
+  pushType: "debug-enabled",
+  requestType: "request-debug-enabled",
+  initial: false,
+  parse: (msg) => typeof msg.enabled === "boolean" ? msg.enabled : void 0
+});
+const isDebugEnabled = () => enabledChannel.get();
+const useDebugEnabled = () => enabledChannel.use();
+const MAX_DATA_BYTES = 16 * 1024;
+function safeData(data) {
+  if (data === void 0) return void 0;
+  try {
+    const json = JSON.stringify(data);
+    if (json === void 0) return "[unserializable]";
+    if (json.length > MAX_DATA_BYTES) return `[truncated ${json.length}B]`;
+    return JSON.parse(json);
+  } catch {
+    return "[unserializable]";
+  }
+}
+function log(level, message, data) {
+  if (!enabledChannel.get()) return;
+  try {
+    (0, import_sandboxUtils.sendMessage)("debug-log", { level, message: String(message), data: safeData(data) });
+  } catch {
+  }
+}
+const ATTR_ALLOW = /* @__PURE__ */ new Set(["role", "aria-hidden", "data-theme", "data-active", "href", "type", "hidden"]);
+const MAX_NODES = 2e3;
+const MAX_DEPTH = 25;
+const MAX_TEXT = 200;
+function round(n) {
+  return Math.round(n);
+}
+function snapshotDom(params) {
+  if (typeof document === "undefined") return null;
+  const root = params.selector ? document.querySelector(params.selector) : document.body;
+  if (!root) return null;
+  const maxDepth = Math.min(params.maxDepth ?? MAX_DEPTH, MAX_DEPTH);
+  const maxNodes = Math.min(params.maxNodes ?? MAX_NODES, MAX_NODES);
+  let budget = maxNodes;
+  const walk = (el, depth) => {
+    budget--;
+    const r = el.getBoundingClientRect();
+    const classes = el.classList.length ? [...el.classList] : void 0;
+    const attrs = {};
+    for (const name of el.getAttributeNames()) {
+      if (ATTR_ALLOW.has(name)) attrs[name] = el.getAttribute(name) ?? "";
+    }
+    const ownText = [...el.childNodes].filter((n) => n.nodeType === 3).map((n) => (n.textContent ?? "").trim()).join(" ").trim();
+    const node = {
+      tag: el.tagName.toLowerCase(),
+      ...el.id ? { id: el.id } : {},
+      ...classes ? { classes } : {},
+      ...Object.keys(attrs).length ? { attrs } : {},
+      rect: { x: round(r.x), y: round(r.y), w: round(r.width), h: round(r.height) },
+      ...ownText ? { text: ownText.slice(0, MAX_TEXT) } : {}
+    };
+    if (depth < maxDepth && el.children.length && budget > 0) {
+      const children = [];
+      for (const child of el.children) {
+        if (budget <= 0) {
+          node.truncated = true;
+          break;
+        }
+        children.push(walk(child, depth + 1));
+      }
+      if (children.length) node.children = children;
+    } else if (el.children.length) {
+      node.truncated = true;
+    }
+    return node;
+  };
+  return walk(root, 0);
+}
+function computedStyle(params) {
+  if (typeof document === "undefined") return null;
+  const el = document.querySelector(params.selector);
+  if (!el) return null;
+  const cs = getComputedStyle(el);
+  const out = {};
+  for (const p of params.props.slice(0, 50)) out[p] = cs.getPropertyValue(p) || cs[p]?.toString?.() || "";
+  return out;
+}
+function rects(params) {
+  if (typeof document === "undefined") return [];
+  return [...document.querySelectorAll(params.selector)].slice(0, 200).map((el) => {
+    const r = el.getBoundingClientRect();
+    return { x: round(r.x), y: round(r.y), w: round(r.width), h: round(r.height) };
+  });
+}
+let responderStarted = false;
+function startResponder() {
+  if (responderStarted || typeof window === "undefined") return;
+  responderStarted = true;
+  (0, import_sandboxUtils.addListener)("debug-query", (msg) => {
+    if (!enabledChannel.get()) return;
+    const id = msg.id;
+    const method = msg.method;
+    const params = msg.params ?? {};
+    let ok = true;
+    let result = null;
+    let error;
+    try {
+      switch (method) {
+        case "snapshotDom":
+          result = snapshotDom(params);
+          break;
+        case "computedStyle":
+          result = computedStyle(params);
+          break;
+        case "rect":
+          result = rects(params);
+          break;
+        default:
+          ok = false;
+          error = `unknown debug method: ${String(method)}`;
+      }
+    } catch (e) {
+      ok = false;
+      error = e instanceof Error ? e.message : String(e);
+    }
+    try {
+      (0, import_sandboxUtils.sendMessage)("debug-query-result", { id, ok, result, error });
+    } catch {
+    }
+  });
+}
+enabledChannel.onChange((enabled) => {
+  if (enabled) startResponder();
+});
+const debug = { log, isEnabled: isDebugEnabled };
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  debug,
+  isDebugEnabled,
+  log,
+  useDebugEnabled
+});
+//# sourceMappingURL=debug.cjs.map

package/dist/debug.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/debug.ts"],"sourcesContent":["// System-app devtools — the app-facing surface (plan: docs/plans/system-app-devtools.md).\n//\n// Two opt-in, DEV-ONLY instruments for debugging a sandboxed UI-as-app region:\n//   1. `debug.log(...)` — an app→host one-way log surfaced in the host dev panel\n//      / CLI `/debug` stream (instead of hand-fishing console output out of a\n//      cross-origin iframe's devtools).\n//   2. a READ-ONLY DOM/layout responder the host can query from outside — the\n//      thing a cross-origin screenshot can't reliably give you (a blank capture\n//      is ambiguous between a real 0-height collapse and a paint artifact).\n//\n// SECURITY (the gating constraint — see the plan's §0):\n//   - Both are inert unless the HOST signals dev mode via the `debug-enabled`\n//     channel. The host only sets it for a dev/override session (the `ir-dev-*`\n//     deep link) or an explicit operator developer-mode. A published app served\n//     to a normal user gets `enabled:false` → `debug.log` is a no-op and the\n//     responder never answers. Production isolation is therefore unchanged.\n//   - The responder is READ-ONLY with a fixed vocabulary (snapshotDom /\n//     computedStyle / rect). There is deliberately NO eval bridge — that would\n//     turn a debug aid into remote code execution into the sandbox.\n//   - The responder reads only its OWN `document` (it lives in its own opaque\n//     iframe and cannot reach a sibling app), so there is no app↔app leak even\n//     in dev.\n//   - Output is bounded (node/depth/text caps) so a query can't exfiltrate an\n//     unbounded payload or wedge the app.\n//\n// Apps that want the strongest guarantee can additionally guard their own usage\n// behind `import.meta.env.DEV` so the calls are tree-shaken from prod bundles;\n// the runtime gate here is the backstop that holds regardless.\n\nimport { createPushChannel } from './pushChannel';\nimport { sendMessage, addListener } from './sandboxUtils';\n\n/** Severity of a {@link debug.log} entry. */\nexport type DebugLevel = 'debug' | 'info' | 'warn' | 'error';\n\n// ── Dev gate ────────────────────────────────────────────────────────────────\n// The host pushes `debug-enabled:true` only for a dev/override session. Until\n// then (and always in production) it stays false and every instrument is inert.\nconst enabledChannel = createPushChannel<boolean>({\n  pushType: 'debug-enabled',\n  requestType: 'request-debug-enabled',\n  initial: false,\n  parse: (msg) => (typeof msg.enabled === 'boolean' ? msg.enabled : undefined),\n});\n\n/** Is the host dev-debug surface active for this session? `false` in production. */\nexport const isDebugEnabled = (): boolean => enabledChannel.get();\n\n/** React hook: whether the host dev-debug surface is active (re-renders on change).\n *  Handy for showing a debug affordance only when it would do something. */\nexport const useDebugEnabled = (): boolean => enabledChannel.use();\n\n// ── 1. App→host debug log ─────────────────────────────────────────────────────\n// Best-effort: a value that can't be structured-cloned is replaced with a marker\n// rather than throwing — `debug.log` must never break the app.\nconst MAX_DATA_BYTES = 16 * 1024;\n\nfunction safeData(data: unknown): unknown {\n  if (data === undefined) return undefined;\n  try {\n    const json = JSON.stringify(data);\n    if (json === undefined) return '[unserializable]';\n    if (json.length > MAX_DATA_BYTES) return `[truncated ${json.length}B]`;\n    return JSON.parse(json);\n  } catch {\n    return '[unserializable]';\n  }\n}\n\n/**\n * Emit a structured debug entry to the host dev surface. A NO-OP unless the host\n * has enabled the dev-debug session ({@link isDebugEnabled}); in production it\n * does nothing and sends nothing.\n *\n *   debug.log('info', 'mounted', { activeFile });\n */\nexport function log(level: DebugLevel, message: string, data?: unknown): void {\n  if (!enabledChannel.get()) return; // inert in prod / non-dev sessions\n  try {\n    sendMessage('debug-log', { level, message: String(message), data: safeData(data) });\n  } catch {\n    /* transport not ready — drop silently; logging must never throw */\n  }\n}\n\n// ── 2. Read-only DOM / layout responder ───────────────────────────────────────\n// The host sends `debug-query` { id, method, params }; we reply with\n// `debug-query-result` { id, ok, result | error }. Only ever active while the dev\n// gate is enabled. Vocabulary is fixed and read-only.\n\ninterface DomNode {\n  tag: string;\n  id?: string;\n  classes?: string[];\n  attrs?: Record<string, string>;\n  rect?: { x: number; y: number; w: number; h: number };\n  text?: string;\n  children?: DomNode[];\n  truncated?: true;\n}\n\nconst ATTR_ALLOW = new Set(['role', 'aria-hidden', 'data-theme', 'data-active', 'href', 'type', 'hidden']);\nconst MAX_NODES = 2000;\nconst MAX_DEPTH = 25;\nconst MAX_TEXT = 200;\n\nfunction round(n: number): number {\n  return Math.round(n);\n}\n\nfunction snapshotDom(params: { selector?: string; maxDepth?: number; maxNodes?: number }): DomNode | null {\n  if (typeof document === 'undefined') return null;\n  const root = params.selector ? document.querySelector(params.selector) : document.body;\n  if (!root) return null;\n  const maxDepth = Math.min(params.maxDepth ?? MAX_DEPTH, MAX_DEPTH);\n  const maxNodes = Math.min(params.maxNodes ?? MAX_NODES, MAX_NODES);\n  let budget = maxNodes;\n\n  const walk = (el: Element, depth: number): DomNode => {\n    budget--;\n    const r = el.getBoundingClientRect();\n    const classes = el.classList.length ? [...el.classList] : undefined;\n    const attrs: Record<string, string> = {};\n    for (const name of el.getAttributeNames()) {\n      if (ATTR_ALLOW.has(name)) attrs[name] = el.getAttribute(name) ?? '';\n    }\n    // Direct text (not descendants') so a leaf's label is visible without dumping\n    // the whole subtree's text.\n    const ownText = [...el.childNodes]\n      .filter((n) => n.nodeType === 3)\n      .map((n) => (n.textContent ?? '').trim())\n      .join(' ')\n      .trim();\n    const node: DomNode = {\n      tag: el.tagName.toLowerCase(),\n      ...(el.id ? { id: el.id } : {}),\n      ...(classes ? { classes } : {}),\n      ...(Object.keys(attrs).length ? { attrs } : {}),\n      rect: { x: round(r.x), y: round(r.y), w: round(r.width), h: round(r.height) },\n      ...(ownText ? { text: ownText.slice(0, MAX_TEXT) } : {}),\n    };\n    if (depth < maxDepth && el.children.length && budget > 0) {\n      const children: DomNode[] = [];\n      for (const child of el.children) {\n        if (budget <= 0) {\n          node.truncated = true;\n          break;\n        }\n        children.push(walk(child, depth + 1));\n      }\n      if (children.length) node.children = children;\n    } else if (el.children.length) {\n      node.truncated = true;\n    }\n    return node;\n  };\n\n  return walk(root, 0);\n}\n\nfunction computedStyle(params: { selector: string; props: string[] }): Record<string, string> | null {\n  if (typeof document === 'undefined') return null;\n  const el = document.querySelector(params.selector);\n  if (!el) return null;\n  const cs = getComputedStyle(el);\n  const out: Record<string, string> = {};\n  for (const p of params.props.slice(0, 50)) out[p] = cs.getPropertyValue(p) || cs[p as keyof CSSStyleDeclaration]?.toString?.() || '';\n  return out;\n}\n\nfunction rects(params: { selector: string }): Array<{ x: number; y: number; w: number; h: number }> {\n  if (typeof document === 'undefined') return [];\n  return [...document.querySelectorAll(params.selector)].slice(0, 200).map((el) => {\n    const r = el.getBoundingClientRect();\n    return { x: round(r.x), y: round(r.y), w: round(r.width), h: round(r.height) };\n  });\n}\n\nlet responderStarted = false;\n\n/** Wire the read-only DOM/layout responder. Idempotent; called lazily once the\n *  dev gate turns on. No effect when `document` is absent (non-browser realm). */\nfunction startResponder(): void {\n  if (responderStarted || typeof window === 'undefined') return;\n  responderStarted = true;\n  addListener('debug-query', (msg: { id?: unknown; method?: unknown; params?: unknown }) => {\n    if (!enabledChannel.get()) return; // gate: ignore unless dev-enabled\n    const id = msg.id;\n    const method = msg.method;\n    const params = (msg.params ?? {}) as Record<string, unknown>;\n    let ok = true;\n    let result: unknown = null;\n    let error: string | undefined;\n    try {\n      switch (method) {\n        case 'snapshotDom':\n          result = snapshotDom(params as never);\n          break;\n        case 'computedStyle':\n          result = computedStyle(params as never);\n          break;\n        case 'rect':\n          result = rects(params as never);\n          break;\n        default:\n          ok = false;\n          error = `unknown debug method: ${String(method)}`;\n      }\n    } catch (e) {\n      ok = false;\n      error = e instanceof Error ? e.message : String(e);\n    }\n    try {\n      sendMessage('debug-query-result', { id, ok, result, error });\n    } catch {\n      /* transport gone — nothing to do */\n    }\n  });\n}\n\n// Start the responder as soon as the gate flips on (and not before).\nenabledChannel.onChange((enabled) => {\n  if (enabled) startResponder();\n});\n\n/** The dev-only debug surface. Inert unless the host enables it ({@link isDebugEnabled}). */\nexport const debug = { log, isEnabled: isDebugEnabled } as const;\n"],"mappings":"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","names":[]}

package/dist/debug.d.cts

@@ -0,0 +1,22 @@
+/** Severity of a {@link debug.log} entry. */
+type DebugLevel = 'debug' | 'info' | 'warn' | 'error';
+/** Is the host dev-debug surface active for this session? `false` in production. */
+declare const isDebugEnabled: () => boolean;
+/** React hook: whether the host dev-debug surface is active (re-renders on change).
+ *  Handy for showing a debug affordance only when it would do something. */
+declare const useDebugEnabled: () => boolean;
+/**
+ * Emit a structured debug entry to the host dev surface. A NO-OP unless the host
+ * has enabled the dev-debug session ({@link isDebugEnabled}); in production it
+ * does nothing and sends nothing.
+ *
+ *   debug.log('info', 'mounted', { activeFile });
+ */
+declare function log(level: DebugLevel, message: string, data?: unknown): void;
+/** The dev-only debug surface. Inert unless the host enables it ({@link isDebugEnabled}). */
+declare const debug: {
+    readonly log: typeof log;
+    readonly isEnabled: () => boolean;
+};
+
+export { type DebugLevel, debug, isDebugEnabled, log, useDebugEnabled };

package/dist/debug.d.ts

@@ -0,0 +1,22 @@
+/** Severity of a {@link debug.log} entry. */
+type DebugLevel = 'debug' | 'info' | 'warn' | 'error';
+/** Is the host dev-debug surface active for this session? `false` in production. */
+declare const isDebugEnabled: () => boolean;
+/** React hook: whether the host dev-debug surface is active (re-renders on change).
+ *  Handy for showing a debug affordance only when it would do something. */
+declare const useDebugEnabled: () => boolean;
+/**
+ * Emit a structured debug entry to the host dev surface. A NO-OP unless the host
+ * has enabled the dev-debug session ({@link isDebugEnabled}); in production it
+ * does nothing and sends nothing.
+ *
+ *   debug.log('info', 'mounted', { activeFile });
+ */
+declare function log(level: DebugLevel, message: string, data?: unknown): void;
+/** The dev-only debug surface. Inert unless the host enables it ({@link isDebugEnabled}). */
+declare const debug: {
+    readonly log: typeof log;
+    readonly isEnabled: () => boolean;
+};
+
+export { type DebugLevel, debug, isDebugEnabled, log, useDebugEnabled };