@elastic/isomer-studio 0.0.0 → 0.4.0

package/dist/chrome/primitive_search.js

@@ -0,0 +1,93 @@
+import { jsx as _jsx } from "@emotion/react/jsx-runtime";
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+import { useEffect, useMemo, useRef } from 'react';
+import { EuiSelectableTemplateSitewide } from '@elastic/eui';
+import { css } from '@emotion/react';
+import { HOME } from '../home/tokens.js';
+import { useStudio } from '../studio_context.js';
+/** Every primitive by name, purpose and guidance, with ⌘K / Ctrl+K focusing the field. */
+export const PrimitiveSearch = ({ onSelectPrimitive, size = 'compressed', placeholder = 'Search names and descriptions', }) => {
+    const { docs: { primitives }, } = useStudio();
+    const input = useRef(null);
+    useEffect(() => {
+        const onKeyDown = (event) => {
+            // Editors claim Cmd/Ctrl+K chords by preventing the default.
+            if (!event.defaultPrevented &&
+                (event.metaKey || event.ctrlKey) &&
+                event.key.toLowerCase() === 'k') {
+                event.preventDefault();
+                input.current?.focus();
+            }
+        };
+        window.addEventListener('keydown', onKeyDown);
+        return () => window.removeEventListener('keydown', onKeyDown);
+    }, []);
+    const options = useMemo(() => primitives.map(({ type, label, group, purpose, useWhen, avoidWhen }) => ({
+        key: type,
+        label,
+        searchableLabel: [type, label, purpose, ...useWhen, ...avoidWhen].join(' '),
+        meta: [{ text: group, type: 'application' }, { text: purpose }],
+    })), [primitives]);
+    const large = size === 'large';
+    return (_jsx(EuiSelectableTemplateSitewide, { options: options, onChange: (updated) => {
+            const selected = updated.find(({ checked }) => checked === 'on');
+            if (selected?.key) {
+                onSelectPrimitive(selected.key);
+            }
+        }, searchProps: {
+            placeholder,
+            append: '⌘K',
+            compressed: !large,
+            fullWidth: large,
+            inputRef: (element) => {
+                input.current = element;
+            },
+            'aria-label': 'Search primitives',
+        }, popoverProps: { width: large ? 620 : 420 }, css: large
+            ? css `
+              width: 100%;
+              .euiFormControlLayout,
+              .euiFieldSearch {
+                block-size: 52px;
+              }
+              .euiFormControlLayout {
+                background-color: ${HOME.field};
+              }
+              .euiFormControlLayout:not(:focus-within)::after {
+                border-color: ${HOME.line3};
+              }
+              .euiFieldSearch {
+                background-color: transparent;
+                color: ${HOME.fg};
+              }
+              .euiFieldSearch::placeholder {
+                color: ${HOME.fg3};
+              }
+              .euiFormControlLayoutIcons,
+              .euiFormControlLayout__append {
+                color: ${HOME.fg2};
+              }
+              .euiFormControlLayoutIcons {
+                max-block-size: none;
+              }
+              .euiFieldSearch {
+                font-size: 15px;
+              }
+            `
+            : css `
+              flex: 0 1 280px;
+              width: 280px;
+              min-width: 72px;
+              @media (max-width: 480px) {
+                .euiFormControlLayout__append {
+                  display: none;
+                }
+              }
+            ` }));
+};
+//# sourceMappingURL=primitive_search.js.map

package/dist/chrome/primitive_search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitive_search.js","sourceRoot":"","sources":["../../src/chrome/primitive_search.tsx"],"names":[],"mappings":";AAAA;;;;;GAKG;AAEH,OAAc,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAE1D,OAAO,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AAErC,OAAO,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAS9C,0FAA0F;AAC1F,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,EAC9B,iBAAiB,EACjB,IAAI,GAAG,YAAY,EACnB,WAAW,GAAG,+BAA+B,GACxB,EAAE,EAAE;IACzB,MAAM,EACJ,IAAI,EAAE,EAAE,UAAU,EAAE,GACrB,GAAG,SAAS,EAAE,CAAC;IAChB,MAAM,KAAK,GAAG,MAAM,CAA0B,IAAI,CAAC,CAAC;IAEpD,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,SAAS,GAAG,CAAC,KAAoB,EAAE,EAAE;YACzC,6DAA6D;YAC7D,IACE,CAAC,KAAK,CAAC,gBAAgB;gBACvB,CAAC,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC;gBAChC,KAAK,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,GAAG,EAC/B,CAAC;gBACD,KAAK,CAAC,cAAc,EAAE,CAAC;gBACvB,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC;YACzB,CAAC;QACH,CAAC,CAAC;QACF,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;QAC9C,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IAChE,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,MAAM,OAAO,GAAG,OAAO,CACrB,GAA0C,EAAE,CAC1C,UAAU,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC;QACvE,GAAG,EAAE,IAAI;QACT,KAAK;QACL,eAAe,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,GAAG,SAAS,CAAC,CAAC,IAAI,CACpE,GAAG,CACJ;QACD,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;KAChE,CAAC,CAAC,EACL,CAAC,UAAU,CAAC,CACb,CAAC;IAEF,MAAM,KAAK,GAAG,IAAI,KAAK,OAAO,CAAC;IAE/B,OAAO,CACL,KAAC,6BAA6B,IAC5B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,CAAC,OAAO,EAAE,EAAE;YACpB,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC;YACjE,IAAI,QAAQ,EAAE,GAAG,EAAE,CAAC;gBAClB,iBAAiB,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YAClC,CAAC;QACH,CAAC,EACD,WAAW,EAAE;YACX,WAAW;YACX,MAAM,EAAE,IAAI;YACZ,UAAU,EAAE,CAAC,KAAK;YAClB,SAAS,EAAE,KAAK;YAChB,QAAQ,EAAE,CAAC,OAAgC,EAAE,EAAE;gBAC7C,KAAK,CAAC,OAAO,GAAG,OAAO,CAAC;YAC1B,CAAC;YACD,YAAY,EAAE,mBAAmB;SAClC,EACD,YAAY,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,EAC1C,GAAG,EACD,KAAK;YACH,CAAC,CAAC,GAAG,CAAA;;;;;;;oCAOqB,IAAI,CAAC,KAAK;;;gCAGd,IAAI,CAAC,KAAK;;;;yBAIjB,IAAI,CAAC,EAAE;;;yBAGP,IAAI,CAAC,GAAG;;;;yBAIR,IAAI,CAAC,GAAG;;;;;;;;aAQpB;YACH,CAAC,CAAC,GAAG,CAAA;;;;;;;;;aASF,GAEP,CACH,CAAC;AACJ,CAAC,CAAC","sourcesContent":["/*\n * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one\n * or more contributor license agreements. Licensed under the Elastic License\n * 2.0; you may not use this file except in compliance with the Elastic License\n * 2.0.\n */\n\nimport React, { useEffect, useMemo, useRef } from 'react';\nimport type { EuiSelectableTemplateSitewideOption } from '@elastic/eui';\nimport { EuiSelectableTemplateSitewide } from '@elastic/eui';\nimport { css } from '@emotion/react';\n\nimport { HOME } from '../home/tokens';\nimport { useStudio } from '../studio_context';\n\nexport interface PrimitiveSearchProps {\n  onSelectPrimitive: (type: string) => void;\n  /** `compressed` fits the header; `large` is the Home page's search. */\n  size?: 'compressed' | 'large' | undefined;\n  placeholder?: string | undefined;\n}\n\n/** Every primitive by name, purpose and guidance, with ⌘K / Ctrl+K focusing the field. */\nexport const PrimitiveSearch = ({\n  onSelectPrimitive,\n  size = 'compressed',\n  placeholder = 'Search names and descriptions',\n}: PrimitiveSearchProps) => {\n  const {\n    docs: { primitives },\n  } = useStudio();\n  const input = useRef<HTMLInputElement | null>(null);\n\n  useEffect(() => {\n    const onKeyDown = (event: KeyboardEvent) => {\n      // Editors claim Cmd/Ctrl+K chords by preventing the default.\n      if (\n        !event.defaultPrevented &&\n        (event.metaKey || event.ctrlKey) &&\n        event.key.toLowerCase() === 'k'\n      ) {\n        event.preventDefault();\n        input.current?.focus();\n      }\n    };\n    window.addEventListener('keydown', onKeyDown);\n    return () => window.removeEventListener('keydown', onKeyDown);\n  }, []);\n\n  const options = useMemo(\n    (): EuiSelectableTemplateSitewideOption[] =>\n      primitives.map(({ type, label, group, purpose, useWhen, avoidWhen }) => ({\n        key: type,\n        label,\n        searchableLabel: [type, label, purpose, ...useWhen, ...avoidWhen].join(\n          ' '\n        ),\n        meta: [{ text: group, type: 'application' }, { text: purpose }],\n      })),\n    [primitives]\n  );\n\n  const large = size === 'large';\n\n  return (\n    <EuiSelectableTemplateSitewide\n      options={options}\n      onChange={(updated) => {\n        const selected = updated.find(({ checked }) => checked === 'on');\n        if (selected?.key) {\n          onSelectPrimitive(selected.key);\n        }\n      }}\n      searchProps={{\n        placeholder,\n        append: '⌘K',\n        compressed: !large,\n        fullWidth: large,\n        inputRef: (element: HTMLInputElement | null) => {\n          input.current = element;\n        },\n        'aria-label': 'Search primitives',\n      }}\n      popoverProps={{ width: large ? 620 : 420 }}\n      css={\n        large\n          ? css`\n              width: 100%;\n              .euiFormControlLayout,\n              .euiFieldSearch {\n                block-size: 52px;\n              }\n              .euiFormControlLayout {\n                background-color: ${HOME.field};\n              }\n              .euiFormControlLayout:not(:focus-within)::after {\n                border-color: ${HOME.line3};\n              }\n              .euiFieldSearch {\n                background-color: transparent;\n                color: ${HOME.fg};\n              }\n              .euiFieldSearch::placeholder {\n                color: ${HOME.fg3};\n              }\n              .euiFormControlLayoutIcons,\n              .euiFormControlLayout__append {\n                color: ${HOME.fg2};\n              }\n              .euiFormControlLayoutIcons {\n                max-block-size: none;\n              }\n              .euiFieldSearch {\n                font-size: 15px;\n              }\n            `\n          : css`\n              flex: 0 1 280px;\n              width: 280px;\n              min-width: 72px;\n              @media (max-width: 480px) {\n                .euiFormControlLayout__append {\n                  display: none;\n                }\n              }\n            `\n      }\n    />\n  );\n};\n"]}

package/dist/chrome/route.d.ts

@@ -0,0 +1,48 @@
+import type { RuntimeDocs } from '../model/describe_runtime.js';
+export type StudioMode = 'dev' | 'docs';
+export interface StudioRoute {
+    mode: StudioMode;
+    /** A primitive `type`, or `gallery` in docs mode. */
+    page: string;
+    example: number;
+    /** A group title the gallery scrolls to, from `#/docs/gallery/<group>`. */
+    group?: string | undefined;
+}
+export interface AppRoute {
+    app: string;
+    /** Everything after `#/app/<id>/`, which may contain slashes. */
+    path: string;
+}
+/** The landing page, at `#/home`, which an empty or unknown hash also opens. */
+export interface HomeRoute {
+    home: true;
+}
+export type StudioLocation = StudioRoute | AppRoute | HomeRoute;
+export declare const GALLERY = "gallery";
+export declare const HOME: HomeRoute;
+export declare const isAppRoute: (location: StudioLocation) => location is AppRoute;
+export declare const isHomeRoute: (location: StudioLocation) => location is HomeRoute;
+export declare const isPrimitiveRoute: (location: StudioLocation) => location is StudioRoute;
+/** Reads `#/dev/callout/0`, `#/docs/statGroup`, `#/docs/gallery` or `#/docs/gallery/Text`, falling back to the first primitive. */
+export declare const parseRoute: (hash: string, { primitives, groups }: RuntimeDocs) => StudioRoute;
+/**
+ * {@link parseRoute} for `#/dev/...` and `#/docs/...`, `#/app/<id>/<path>` for an id in `appIds`, and
+ * {@link HOME} for an empty hash, `#/home`, an unknown app, or any other first segment.
+ */
+export declare const parseLocation: (hash: string, docs: RuntimeDocs, appIds: readonly string[]) => StudioLocation;
+export declare const formatRoute: ({ mode, page, example, group, }: StudioRoute) => string;
+export declare const formatLocation: (location: StudioLocation) => string;
+export interface StudioRouter {
+    location: StudioLocation;
+    /** The current primitive route, or the last one before an app or Home opened. */
+    route: StudioRoute;
+    /** Moves to a primitive route, merging `next` into {@link StudioRouter.route}. */
+    navigate: (next: Partial<StudioRoute>) => void;
+    /** `path` is percent-encoded in the hash, segment by segment, and decoded when read back. */
+    openApp: (id: string, path?: string) => void;
+    /** Opens `#/home`. */
+    goHome: () => void;
+}
+/** The location in the URL hash, re-checked whenever the primitives or apps change. */
+export declare const useStudioRoute: (docs: RuntimeDocs, appIds: readonly string[]) => StudioRouter;
+//# sourceMappingURL=route.d.ts.map

package/dist/chrome/route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/chrome/route.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,CAAC;AAExC,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,UAAU,CAAC;IACjB,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5B;AAED,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;CACd;AAED,gFAAgF;AAChF,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEhE,eAAO,MAAM,OAAO,YAAY,CAAC;AAKjC,eAAO,MAAM,IAAI,EAAE,SAA0B,CAAC;AAW9C,eAAO,MAAM,UAAU,GAAI,UAAU,cAAc,KAAG,QAAQ,IAAI,QAC/C,CAAC;AAEpB,eAAO,MAAM,WAAW,GAAI,UAAU,cAAc,KAAG,QAAQ,IAAI,SAC/C,CAAC;AAErB,eAAO,MAAM,gBAAgB,GAC3B,UAAU,cAAc,KACvB,QAAQ,IAAI,WAAiC,CAAC;AAEjD,mIAAmI;AACnI,eAAO,MAAM,UAAU,GACrB,MAAM,MAAM,EACZ,wBAAwB,WAAW,KAClC,WA6BF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,GACxB,MAAM,MAAM,EACZ,MAAM,WAAW,EACjB,QAAQ,SAAS,MAAM,EAAE,KACxB,cAWF,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,iCAKzB,WAAW,KAAG,MAKmB,CAAC;AAErC,eAAO,MAAM,cAAc,GAAI,UAAU,cAAc,KAAG,MAK7B,CAAC;AAE9B,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,cAAc,CAAC;IACzB,iFAAiF;IACjF,KAAK,EAAE,WAAW,CAAC;IACnB,kFAAkF;IAClF,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,WAAW,CAAC,KAAK,IAAI,CAAC;IAC/C,6FAA6F;IAC7F,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,sBAAsB;IACtB,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED,uFAAuF;AACvF,eAAO,MAAM,cAAc,GACzB,MAAM,WAAW,EACjB,QAAQ,SAAS,MAAM,EAAE,KACxB,YAsFF,CAAC"}

package/dist/chrome/route.js

@@ -0,0 +1,136 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+export const GALLERY = 'gallery';
+const APP_SEGMENT = 'app';
+const HOME_SEGMENT = 'home';
+export const HOME = { home: true };
+/** A segment as written, when it is not valid percent-encoding. */
+const decodeSegment = (segment) => {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch {
+        return segment;
+    }
+};
+export const isAppRoute = (location) => 'app' in location;
+export const isHomeRoute = (location) => 'home' in location;
+export const isPrimitiveRoute = (location) => 'mode' in location;
+/** Reads `#/dev/callout/0`, `#/docs/statGroup`, `#/docs/gallery` or `#/docs/gallery/Text`, falling back to the first primitive. */
+export const parseRoute = (hash, { primitives, groups }) => {
+    const [mode, page, example] = hash.replace(/^#\/?/, '').split('/');
+    const first = groups[0]?.types[0] ?? primitives[0]?.type ?? '';
+    const resolvedMode = mode === 'docs' ? 'docs' : 'dev';
+    const doc = primitives.find(({ type }) => type === page);
+    const index = Number(example);
+    if (!doc && resolvedMode === 'docs' && page === GALLERY) {
+        const title = example === undefined ? undefined : decodeSegment(example);
+        const group = groups.find((candidate) => candidate.title === title);
+        return {
+            mode: resolvedMode,
+            page: GALLERY,
+            example: 0,
+            ...(group ? { group: group.title } : {}),
+        };
+    }
+    return {
+        mode: resolvedMode,
+        page: doc ? doc.type : first,
+        example: doc &&
+            Number.isInteger(index) &&
+            index >= 0 &&
+            index < doc.examples.length
+            ? index
+            : 0,
+    };
+};
+/**
+ * {@link parseRoute} for `#/dev/...` and `#/docs/...`, `#/app/<id>/<path>` for an id in `appIds`, and
+ * {@link HOME} for an empty hash, `#/home`, an unknown app, or any other first segment.
+ */
+export const parseLocation = (hash, docs, appIds) => {
+    const [segment, id, ...rest] = hash.replace(/^#\/?/, '').split('/');
+    if (segment === APP_SEGMENT) {
+        return id !== undefined && appIds.includes(id)
+            ? { app: id, path: rest.map(decodeSegment).join('/') }
+            : HOME;
+    }
+    if (segment === 'dev' || segment === 'docs') {
+        return parseRoute(hash, docs);
+    }
+    return HOME;
+};
+export const formatRoute = ({ mode, page, example, group, }) => page === GALLERY
+    ? group === undefined
+        ? `#/${mode}/${GALLERY}`
+        : `#/${mode}/${GALLERY}/${encodeURIComponent(group)}`
+    : `#/${mode}/${page}/${example}`;
+export const formatLocation = (location) => isHomeRoute(location)
+    ? `#/${HOME_SEGMENT}`
+    : isAppRoute(location)
+        ? `#/${APP_SEGMENT}/${location.app}/${location.path.split('/').map(encodeURIComponent).join('/')}`
+        : formatRoute(location);
+/** The location in the URL hash, re-checked whenever the primitives or apps change. */
+export const useStudioRoute = (docs, appIds) => {
+    const appKey = appIds.join('/');
+    const ids = useRef(appIds);
+    ids.current = appIds;
+    const [location, setLocation] = useState(() => parseLocation(window.location.hash, docs, appIds));
+    const [route, setRoute] = useState(() => isPrimitiveRoute(location) ? location : parseRoute('', docs));
+    const current = useRef(route);
+    current.current = route;
+    const shown = useRef(location);
+    shown.current = location;
+    const show = useCallback((next) => {
+        setLocation(next);
+        if (isPrimitiveRoute(next)) {
+            setRoute(next);
+        }
+    }, []);
+    useEffect(() => {
+        const onHashChange = () => show(parseLocation(window.location.hash, docs, ids.current));
+        window.addEventListener('hashchange', onHashChange);
+        return () => window.removeEventListener('hashchange', onHashChange);
+    }, [docs, show]);
+    const checked = useRef({ docs, appKey });
+    useEffect(() => {
+        if (checked.current.docs === docs && checked.current.appKey === appKey) {
+            return;
+        }
+        checked.current = { docs, appKey };
+        const remembered = parseRoute(formatRoute(current.current), docs);
+        if (formatRoute(remembered) !== formatRoute(current.current)) {
+            setRoute(remembered);
+        }
+        const next = parseLocation(window.location.hash, docs, ids.current);
+        const hash = formatLocation(next);
+        if (hash === formatLocation(shown.current)) {
+            return;
+        }
+        window.history.replaceState(null, '', hash);
+        show(next);
+    }, [docs, appKey, show]);
+    const go = useCallback((next) => {
+        const hash = formatLocation(next);
+        if (window.location.hash !== hash) {
+            window.history.pushState(null, '', hash);
+        }
+        show(next);
+    }, [show]);
+    const navigate = useCallback((next) => {
+        const { mode, page, example } = current.current;
+        const merged = { mode, page, example, ...next };
+        go(parseRoute(formatRoute(merged.mode === 'dev' && merged.page === GALLERY
+            ? { ...merged, page: '' }
+            : merged), docs));
+    }, [docs, go]);
+    const openApp = useCallback((id, path = '') => go({ app: id, path }), [go]);
+    const goHome = useCallback(() => go(HOME), [go]);
+    return { location, route, navigate, openApp, goHome };
+};
+//# sourceMappingURL=route.js.map

package/dist/chrome/route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.js","sourceRoot":"","sources":["../../src/chrome/route.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one\n * or more contributor license agreements. Licensed under the Elastic License\n * 2.0; you may not use this file except in compliance with the Elastic License\n * 2.0.\n */\n\nimport { useCallback, useEffect, useRef, useState } from 'react';\n\nimport type { RuntimeDocs } from '../model/describe_runtime';\n\nexport type StudioMode = 'dev' | 'docs';\n\nexport interface StudioRoute {\n  mode: StudioMode;\n  /** A primitive `type`, or `gallery` in docs mode. */\n  page: string;\n  example: number;\n  /** A group title the gallery scrolls to, from `#/docs/gallery/<group>`. */\n  group?: string | undefined;\n}\n\nexport interface AppRoute {\n  app: string;\n  /** Everything after `#/app/<id>/`, which may contain slashes. */\n  path: string;\n}\n\n/** The landing page, at `#/home`, which an empty or unknown hash also opens. */\nexport interface HomeRoute {\n  home: true;\n}\n\nexport type StudioLocation = StudioRoute | AppRoute | HomeRoute;\n\nexport const GALLERY = 'gallery';\n\nconst APP_SEGMENT = 'app';\nconst HOME_SEGMENT = 'home';\n\nexport const HOME: HomeRoute = { home: true };\n\n/** A segment as written, when it is not valid percent-encoding. */\nconst decodeSegment = (segment: string): string => {\n  try {\n    return decodeURIComponent(segment);\n  } catch {\n    return segment;\n  }\n};\n\nexport const isAppRoute = (location: StudioLocation): location is AppRoute =>\n  'app' in location;\n\nexport const isHomeRoute = (location: StudioLocation): location is HomeRoute =>\n  'home' in location;\n\nexport const isPrimitiveRoute = (\n  location: StudioLocation\n): location is StudioRoute => 'mode' in location;\n\n/** Reads `#/dev/callout/0`, `#/docs/statGroup`, `#/docs/gallery` or `#/docs/gallery/Text`, falling back to the first primitive. */\nexport const parseRoute = (\n  hash: string,\n  { primitives, groups }: RuntimeDocs\n): StudioRoute => {\n  const [mode, page, example] = hash.replace(/^#\\/?/, '').split('/');\n  const first = groups[0]?.types[0] ?? primitives[0]?.type ?? '';\n  const resolvedMode: StudioMode = mode === 'docs' ? 'docs' : 'dev';\n  const doc = primitives.find(({ type }) => type === page);\n  const index = Number(example);\n\n  if (!doc && resolvedMode === 'docs' && page === GALLERY) {\n    const title = example === undefined ? undefined : decodeSegment(example);\n    const group = groups.find((candidate) => candidate.title === title);\n    return {\n      mode: resolvedMode,\n      page: GALLERY,\n      example: 0,\n      ...(group ? { group: group.title } : {}),\n    };\n  }\n\n  return {\n    mode: resolvedMode,\n    page: doc ? doc.type : first,\n    example:\n      doc &&\n      Number.isInteger(index) &&\n      index >= 0 &&\n      index < doc.examples.length\n        ? index\n        : 0,\n  };\n};\n\n/**\n * {@link parseRoute} for `#/dev/...` and `#/docs/...`, `#/app/<id>/<path>` for an id in `appIds`, and\n * {@link HOME} for an empty hash, `#/home`, an unknown app, or any other first segment.\n */\nexport const parseLocation = (\n  hash: string,\n  docs: RuntimeDocs,\n  appIds: readonly string[]\n): StudioLocation => {\n  const [segment, id, ...rest] = hash.replace(/^#\\/?/, '').split('/');\n  if (segment === APP_SEGMENT) {\n    return id !== undefined && appIds.includes(id)\n      ? { app: id, path: rest.map(decodeSegment).join('/') }\n      : HOME;\n  }\n  if (segment === 'dev' || segment === 'docs') {\n    return parseRoute(hash, docs);\n  }\n  return HOME;\n};\n\nexport const formatRoute = ({\n  mode,\n  page,\n  example,\n  group,\n}: StudioRoute): string =>\n  page === GALLERY\n    ? group === undefined\n      ? `#/${mode}/${GALLERY}`\n      : `#/${mode}/${GALLERY}/${encodeURIComponent(group)}`\n    : `#/${mode}/${page}/${example}`;\n\nexport const formatLocation = (location: StudioLocation): string =>\n  isHomeRoute(location)\n    ? `#/${HOME_SEGMENT}`\n    : isAppRoute(location)\n      ? `#/${APP_SEGMENT}/${location.app}/${location.path.split('/').map(encodeURIComponent).join('/')}`\n      : formatRoute(location);\n\nexport interface StudioRouter {\n  location: StudioLocation;\n  /** The current primitive route, or the last one before an app or Home opened. */\n  route: StudioRoute;\n  /** Moves to a primitive route, merging `next` into {@link StudioRouter.route}. */\n  navigate: (next: Partial<StudioRoute>) => void;\n  /** `path` is percent-encoded in the hash, segment by segment, and decoded when read back. */\n  openApp: (id: string, path?: string) => void;\n  /** Opens `#/home`. */\n  goHome: () => void;\n}\n\n/** The location in the URL hash, re-checked whenever the primitives or apps change. */\nexport const useStudioRoute = (\n  docs: RuntimeDocs,\n  appIds: readonly string[]\n): StudioRouter => {\n  const appKey = appIds.join('/');\n  const ids = useRef(appIds);\n  ids.current = appIds;\n\n  const [location, setLocation] = useState(() =>\n    parseLocation(window.location.hash, docs, appIds)\n  );\n  const [route, setRoute] = useState(() =>\n    isPrimitiveRoute(location) ? location : parseRoute('', docs)\n  );\n  const current = useRef(route);\n  current.current = route;\n  const shown = useRef(location);\n  shown.current = location;\n\n  const show = useCallback((next: StudioLocation) => {\n    setLocation(next);\n    if (isPrimitiveRoute(next)) {\n      setRoute(next);\n    }\n  }, []);\n\n  useEffect(() => {\n    const onHashChange = () =>\n      show(parseLocation(window.location.hash, docs, ids.current));\n    window.addEventListener('hashchange', onHashChange);\n    return () => window.removeEventListener('hashchange', onHashChange);\n  }, [docs, show]);\n\n  const checked = useRef({ docs, appKey });\n  useEffect(() => {\n    if (checked.current.docs === docs && checked.current.appKey === appKey) {\n      return;\n    }\n    checked.current = { docs, appKey };\n    const remembered = parseRoute(formatRoute(current.current), docs);\n    if (formatRoute(remembered) !== formatRoute(current.current)) {\n      setRoute(remembered);\n    }\n    const next = parseLocation(window.location.hash, docs, ids.current);\n    const hash = formatLocation(next);\n    if (hash === formatLocation(shown.current)) {\n      return;\n    }\n    window.history.replaceState(null, '', hash);\n    show(next);\n  }, [docs, appKey, show]);\n\n  const go = useCallback(\n    (next: StudioLocation) => {\n      const hash = formatLocation(next);\n      if (window.location.hash !== hash) {\n        window.history.pushState(null, '', hash);\n      }\n      show(next);\n    },\n    [show]\n  );\n\n  const navigate = useCallback(\n    (next: Partial<StudioRoute>) => {\n      const { mode, page, example } = current.current;\n      const merged = { mode, page, example, ...next };\n      go(\n        parseRoute(\n          formatRoute(\n            merged.mode === 'dev' && merged.page === GALLERY\n              ? { ...merged, page: '' }\n              : merged\n          ),\n          docs\n        )\n      );\n    },\n    [docs, go]\n  );\n\n  const openApp = useCallback(\n    (id: string, path = '') => go({ app: id, path }),\n    [go]\n  );\n\n  const goHome = useCallback(() => go(HOME), [go]);\n\n  return { location, route, navigate, openApp, goHome };\n};\n"]}

package/dist/cli/args.d.ts

@@ -0,0 +1,39 @@
+import type { StudioSurface } from '../model/describe_runtime.js';
+import type { ConfigLoader } from '../node/load_config.js';
+import type { ReportFormat } from '../node/report.js';
+export declare const DEFAULT_PORT = 5179;
+interface SharedArgs {
+    /** Absolute; `--config` and `--out` resolve against it. */
+    cwd: string;
+    config?: string | undefined;
+    loader: ConfigLoader;
+}
+export type CliArgs = {
+    command: 'help';
+} | (SharedArgs & {
+    command: 'init';
+}) | (SharedArgs & {
+    command: 'dev';
+    port: number;
+    open: boolean;
+}) | (SharedArgs & {
+    command: 'build';
+    out: string;
+    base: string;
+}) | (SharedArgs & {
+    command: 'check';
+    report?: string | undefined;
+    format: ReportFormat;
+    png: boolean;
+    surfaces?: StudioSurface[] | undefined;
+});
+export declare const USAGE = "Usage: isomer-studio [command] [options]\n\nCommands:\n  dev     Serve the Studio with live reload. The default.\n  build   Write the Studio as a static site.\n  check   Render every example on every surface, and exit 1 on a failure.\n  init    Write a config for the packs the project exports: isomer-studio.config.ts\n          beside a tsconfig.json, isomer-studio.config.js otherwise.\n\nOptions for every command:\n  --cwd <dir>            The project; resolves --config, --out and --report. Default: the current directory.\n  --loader tsx|none      How the config is imported in Node. Default: tsx.\n\ndev, build and check:\n  --config <file>        Default: isomer-studio.config.{ts,tsx,js} in --cwd.\n\ndev:\n  --port <number>        Default: 5179.\n  --open                 Open the Studio in a browser.\n\nbuild:\n  --out <dir>            Default: dist/studio.\n  --base <path>          The URL path the site is served from. Default: ./\n\ncheck:\n  --report <file>        Also write the report to a file.\n  --format json|junit    The report's format. Default: json.\n  --png                  Also rasterize every example.\n  --surfaces <list>      Comma-separated surfaces to render. Default: every surface the runtime has.\n";
+/** Bad command-line input. Identify it by `name`. */
+export declare class UsageError extends Error {
+    readonly name = "UsageError";
+}
+/** A trailing slash, so asset URLs resolve inside the base rather than beside it. */
+export declare const normalizeBase: (base: string) => string;
+export declare const parseCliArgs: (argv: readonly string[], processCwd?: string) => CliArgs;
+export {};
+//# sourceMappingURL=args.d.ts.map

package/dist/cli/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC,UAAU,UAAU;IAClB,2DAA2D;IAC3D,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,MAAM,MAAM,OAAO,GACf;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GACnB,CAAC,UAAU,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,GAClC,CAAC,UAAU,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,GAC9D,CAAC,UAAU,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GAC9D,CAAC,UAAU,GAAG;IACZ,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,MAAM,EAAE,YAAY,CAAC;IACrB,GAAG,EAAE,OAAO,CAAC;IACb,QAAQ,CAAC,EAAE,aAAa,EAAE,GAAG,SAAS,CAAC;CACxC,CAAC,CAAC;AAEP,eAAO,MAAM,KAAK,0tCA6BjB,CAAC;AAEF,qDAAqD;AACrD,qBAAa,UAAW,SAAQ,KAAK;IACnC,SAAkB,IAAI,gBAAgB;CACvC;AA0DD,qFAAqF;AACrF,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,KAAG,MACL,CAAC;AA6BzC,eAAO,MAAM,YAAY,GACvB,MAAM,SAAS,MAAM,EAAE,EACvB,aAAY,MAAsB,KACjC,OAoEF,CAAC"}

package/dist/cli/args.js

@@ -0,0 +1,171 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0; you may not use this file except in compliance with the Elastic License
+ * 2.0.
+ */
+import { resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { SURFACE_LABELS } from '../model/describe_runtime.js';
+export const DEFAULT_PORT = 5179;
+export const USAGE = `Usage: isomer-studio [command] [options]
+
+Commands:
+  dev     Serve the Studio with live reload. The default.
+  build   Write the Studio as a static site.
+  check   Render every example on every surface, and exit 1 on a failure.
+  init    Write a config for the packs the project exports: isomer-studio.config.ts
+          beside a tsconfig.json, isomer-studio.config.js otherwise.
+
+Options for every command:
+  --cwd <dir>            The project; resolves --config, --out and --report. Default: the current directory.
+  --loader tsx|none      How the config is imported in Node. Default: tsx.
+
+dev, build and check:
+  --config <file>        Default: isomer-studio.config.{ts,tsx,js} in --cwd.
+
+dev:
+  --port <number>        Default: ${DEFAULT_PORT}.
+  --open                 Open the Studio in a browser.
+
+build:
+  --out <dir>            Default: dist/studio.
+  --base <path>          The URL path the site is served from. Default: ./
+
+check:
+  --report <file>        Also write the report to a file.
+  --format json|junit    The report's format. Default: json.
+  --png                  Also rasterize every example.
+  --surfaces <list>      Comma-separated surfaces to render. Default: every surface the runtime has.
+`;
+/** Bad command-line input. Identify it by `name`. */
+export class UsageError extends Error {
+    name = 'UsageError';
+}
+const COMMANDS = ['dev', 'build', 'check', 'init'];
+const isCommand = (value) => COMMANDS.some((command) => command === value);
+const isSurface = (value) => Object.hasOwn(SURFACE_LABELS, value);
+const oneOf = (flag, value, allowed, fallback) => {
+    if (value === undefined) {
+        return fallback;
+    }
+    const match = allowed.find((candidate) => candidate === value);
+    if (match === undefined) {
+        throw new UsageError(`--${flag} must be one of ${allowed.join(', ')}; got ${value}.`);
+    }
+    return match;
+};
+const parsePort = (value) => {
+    if (value === undefined) {
+        return DEFAULT_PORT;
+    }
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+        throw new UsageError(`--port must be a port number; got ${value}.`);
+    }
+    return port;
+};
+const parseSurfaces = (value) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    const names = value
+        .split(',')
+        .map((name) => name.trim())
+        .filter(Boolean);
+    const unknown = names.filter((name) => !isSurface(name));
+    if (unknown.length) {
+        throw new UsageError(`--surfaces has unknown surfaces: ${unknown.join(', ')}. Known: ${Object.keys(SURFACE_LABELS).join(', ')}.`);
+    }
+    return names.filter(isSurface);
+};
+/** A trailing slash, so asset URLs resolve inside the base rather than beside it. */
+export const normalizeBase = (base) => base.endsWith('/') ? base : `${base}/`;
+const OPTIONS = {
+    config: { type: 'string' },
+    cwd: { type: 'string' },
+    loader: { type: 'string' },
+    port: { type: 'string' },
+    open: { type: 'boolean' },
+    out: { type: 'string' },
+    base: { type: 'string' },
+    report: { type: 'string' },
+    format: { type: 'string' },
+    png: { type: 'boolean' },
+    surfaces: { type: 'string' },
+    help: { type: 'boolean', short: 'h' },
+};
+const ONLY = {
+    config: ['dev', 'build', 'check'],
+    port: ['dev'],
+    open: ['dev'],
+    out: ['build'],
+    base: ['build'],
+    report: ['check'],
+    format: ['check'],
+    png: ['check'],
+    surfaces: ['check'],
+};
+export const parseCliArgs = (argv, processCwd = process.cwd()) => {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: [...argv],
+            options: OPTIONS,
+            allowPositionals: true,
+        });
+    }
+    catch (error) {
+        throw new UsageError(error instanceof Error ? error.message : String(error));
+    }
+    const { values, positionals } = parsed;
+    const [command = 'dev', ...extra] = positionals;
+    if (values.help || command === 'help') {
+        return { command: 'help' };
+    }
+    if (!isCommand(command)) {
+        throw new UsageError(`Unknown command: ${command}.`);
+    }
+    if (extra.length) {
+        throw new UsageError(`Unexpected arguments: ${extra.join(' ')}.`);
+    }
+    const misplaced = Object.keys(values).filter((flag) => ONLY[flag] !== undefined && !ONLY[flag].includes(command));
+    if (misplaced.length) {
+        throw new UsageError(`${misplaced.map((flag) => `--${flag}`).join(', ')} does not apply to ${command}.`);
+    }
+    const shared = {
+        cwd: resolve(processCwd, values.cwd ?? '.'),
+        config: values.config,
+        loader: oneOf('loader', values.loader, ['tsx', 'none'], 'tsx'),
+    };
+    switch (command) {
+        case 'init':
+            return { ...shared, command };
+        case 'dev':
+            return {
+                ...shared,
+                command,
+                port: parsePort(values.port),
+                open: values.open ?? false,
+            };
+        case 'build':
+            return {
+                ...shared,
+                command,
+                out: resolve(shared.cwd, values.out ?? 'dist/studio'),
+                base: normalizeBase(values.base ?? './'),
+            };
+        case 'check':
+            return {
+                ...shared,
+                command,
+                report: values.report === undefined
+                    ? undefined
+                    : resolve(shared.cwd, values.report),
+                format: oneOf('format', values.format, ['json', 'junit'], 'json'),
+                png: values.png ?? false,
+                surfaces: parseSurfaces(values.surfaces),
+            };
+    }
+};
+//# sourceMappingURL=args.js.map

package/dist/cli/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one\n * or more contributor license agreements. Licensed under the Elastic License\n * 2.0; you may not use this file except in compliance with the Elastic License\n * 2.0.\n */\n\nimport { resolve } from 'node:path';\nimport { parseArgs } from 'node:util';\n\nimport type { StudioSurface } from '../model/describe_runtime';\nimport { SURFACE_LABELS } from '../model/describe_runtime';\nimport type { ConfigLoader } from '../node/load_config';\nimport type { ReportFormat } from '../node/report';\n\nexport const DEFAULT_PORT = 5179;\n\ninterface SharedArgs {\n  /** Absolute; `--config` and `--out` resolve against it. */\n  cwd: string;\n  config?: string | undefined;\n  loader: ConfigLoader;\n}\n\nexport type CliArgs =\n  | { command: 'help' }\n  | (SharedArgs & { command: 'init' })\n  | (SharedArgs & { command: 'dev'; port: number; open: boolean })\n  | (SharedArgs & { command: 'build'; out: string; base: string })\n  | (SharedArgs & {\n      command: 'check';\n      report?: string | undefined;\n      format: ReportFormat;\n      png: boolean;\n      surfaces?: StudioSurface[] | undefined;\n    });\n\nexport const USAGE = `Usage: isomer-studio [command] [options]\n\nCommands:\n  dev     Serve the Studio with live reload. The default.\n  build   Write the Studio as a static site.\n  check   Render every example on every surface, and exit 1 on a failure.\n  init    Write a config for the packs the project exports: isomer-studio.config.ts\n          beside a tsconfig.json, isomer-studio.config.js otherwise.\n\nOptions for every command:\n  --cwd <dir>            The project; resolves --config, --out and --report. Default: the current directory.\n  --loader tsx|none      How the config is imported in Node. Default: tsx.\n\ndev, build and check:\n  --config <file>        Default: isomer-studio.config.{ts,tsx,js} in --cwd.\n\ndev:\n  --port <number>        Default: ${DEFAULT_PORT}.\n  --open                 Open the Studio in a browser.\n\nbuild:\n  --out <dir>            Default: dist/studio.\n  --base <path>          The URL path the site is served from. Default: ./\n\ncheck:\n  --report <file>        Also write the report to a file.\n  --format json|junit    The report's format. Default: json.\n  --png                  Also rasterize every example.\n  --surfaces <list>      Comma-separated surfaces to render. Default: every surface the runtime has.\n`;\n\n/** Bad command-line input. Identify it by `name`. */\nexport class UsageError extends Error {\n  override readonly name = 'UsageError';\n}\n\nconst COMMANDS = ['dev', 'build', 'check', 'init'] as const;\n\nconst isCommand = (value: string): value is (typeof COMMANDS)[number] =>\n  COMMANDS.some((command) => command === value);\n\nconst isSurface = (value: string): value is StudioSurface =>\n  Object.hasOwn(SURFACE_LABELS, value);\n\nconst oneOf = <T extends string>(\n  flag: string,\n  value: string | undefined,\n  allowed: readonly T[],\n  fallback: T\n): T => {\n  if (value === undefined) {\n    return fallback;\n  }\n  const match = allowed.find((candidate) => candidate === value);\n  if (match === undefined) {\n    throw new UsageError(\n      `--${flag} must be one of ${allowed.join(', ')}; got ${value}.`\n    );\n  }\n  return match;\n};\n\nconst parsePort = (value: string | undefined): number => {\n  if (value === undefined) {\n    return DEFAULT_PORT;\n  }\n  const port = Number(value);\n  if (!Number.isInteger(port) || port < 0 || port > 65_535) {\n    throw new UsageError(`--port must be a port number; got ${value}.`);\n  }\n  return port;\n};\n\nconst parseSurfaces = (\n  value: string | undefined\n): StudioSurface[] | undefined => {\n  if (value === undefined) {\n    return undefined;\n  }\n  const names = value\n    .split(',')\n    .map((name) => name.trim())\n    .filter(Boolean);\n  const unknown = names.filter((name) => !isSurface(name));\n  if (unknown.length) {\n    throw new UsageError(\n      `--surfaces has unknown surfaces: ${unknown.join(', ')}. Known: ${Object.keys(SURFACE_LABELS).join(', ')}.`\n    );\n  }\n  return names.filter(isSurface);\n};\n\n/** A trailing slash, so asset URLs resolve inside the base rather than beside it. */\nexport const normalizeBase = (base: string): string =>\n  base.endsWith('/') ? base : `${base}/`;\n\nconst OPTIONS = {\n  config: { type: 'string' },\n  cwd: { type: 'string' },\n  loader: { type: 'string' },\n  port: { type: 'string' },\n  open: { type: 'boolean' },\n  out: { type: 'string' },\n  base: { type: 'string' },\n  report: { type: 'string' },\n  format: { type: 'string' },\n  png: { type: 'boolean' },\n  surfaces: { type: 'string' },\n  help: { type: 'boolean', short: 'h' },\n} as const;\n\nconst ONLY: Readonly<Record<string, readonly string[]>> = {\n  config: ['dev', 'build', 'check'],\n  port: ['dev'],\n  open: ['dev'],\n  out: ['build'],\n  base: ['build'],\n  report: ['check'],\n  format: ['check'],\n  png: ['check'],\n  surfaces: ['check'],\n};\n\nexport const parseCliArgs = (\n  argv: readonly string[],\n  processCwd: string = process.cwd()\n): CliArgs => {\n  let parsed;\n  try {\n    parsed = parseArgs({\n      args: [...argv],\n      options: OPTIONS,\n      allowPositionals: true,\n    });\n  } catch (error) {\n    throw new UsageError(\n      error instanceof Error ? error.message : String(error)\n    );\n  }\n  const { values, positionals } = parsed;\n  const [command = 'dev', ...extra] = positionals;\n  if (values.help || command === 'help') {\n    return { command: 'help' };\n  }\n  if (!isCommand(command)) {\n    throw new UsageError(`Unknown command: ${command}.`);\n  }\n  if (extra.length) {\n    throw new UsageError(`Unexpected arguments: ${extra.join(' ')}.`);\n  }\n  const misplaced = Object.keys(values).filter(\n    (flag) => ONLY[flag] !== undefined && !ONLY[flag].includes(command)\n  );\n  if (misplaced.length) {\n    throw new UsageError(\n      `${misplaced.map((flag) => `--${flag}`).join(', ')} does not apply to ${command}.`\n    );\n  }\n\n  const shared: SharedArgs = {\n    cwd: resolve(processCwd, values.cwd ?? '.'),\n    config: values.config,\n    loader: oneOf('loader', values.loader, ['tsx', 'none'], 'tsx'),\n  };\n  switch (command) {\n    case 'init':\n      return { ...shared, command };\n    case 'dev':\n      return {\n        ...shared,\n        command,\n        port: parsePort(values.port),\n        open: values.open ?? false,\n      };\n    case 'build':\n      return {\n        ...shared,\n        command,\n        out: resolve(shared.cwd, values.out ?? 'dist/studio'),\n        base: normalizeBase(values.base ?? './'),\n      };\n    case 'check':\n      return {\n        ...shared,\n        command,\n        report:\n          values.report === undefined\n            ? undefined\n            : resolve(shared.cwd, values.report),\n        format: oneOf('format', values.format, ['json', 'junit'], 'json'),\n        png: values.png ?? false,\n        surfaces: parseSurfaces(values.surfaces),\n      };\n  }\n};\n"]}

package/dist/cli/run.d.ts

@@ -0,0 +1,15 @@
+import type { DevServer } from '../node/dev_server.js';
+export interface CliIo {
+    cwd: string;
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+    /** Called with the running dev server, which keeps the process alive until it closes. */
+    onDevServer?: ((server: DevServer) => void) | undefined;
+    /** Called with the config before it loads; the binary passes `registerProjectResolution`. */
+    onConfig?: ((configPath: string) => void) | undefined;
+}
+/** Opens `url` in the default browser, reporting a missing or failing opener to `onError`. */
+export declare const openBrowser: (url: string, onError: (error: Error) => void, command?: string) => void;
+/** Runs one CLI invocation and resolves its exit code: 0, 1 on a failure, 2 on bad usage. */
+export declare const runCli: (argv: readonly string[], io: CliIo) => Promise<number>;
+//# sourceMappingURL=run.d.ts.map

package/dist/cli/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/cli/run.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAepD,MAAM,WAAW,KAAK;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,yFAAyF;IACzF,WAAW,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IACxD,6FAA6F;IAC7F,QAAQ,CAAC,EAAE,CAAC,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CACvD;AAOD,8FAA8F;AAC9F,eAAO,MAAM,WAAW,GACtB,KAAK,MAAM,EACX,SAAS,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,EAC/B,gBAAiD,KAChD,IAIF,CAAC;AAqFF,6FAA6F;AAC7F,eAAO,MAAM,MAAM,GACjB,MAAM,SAAS,MAAM,EAAE,EACvB,IAAI,KAAK,KACR,OAAO,CAAC,MAAM,CAkBhB,CAAC"}