@bloodhound-rs/playground 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Justinidlerz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,140 @@
-# Temporary Holding Version
+# @bloodhound-rs/playground
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React 18/19 components for Manifest v2. The viewer and resource selector are independent exports. Neither depends on the scanner's native binary or an application router.
+
+| Export               | Responsibility                                                                             |
+| -------------------- | ------------------------------------------------------------------------------------------ |
+| `ManifestViewer`     | Render an already loaded manifest, filter records, inspect dependencies and preview source |
+| `ManifestSelector`   | Read a local JSON file or manifest URL and call `onChange`                                 |
+| `ManifestPlayground` | Ready-to-use selector and viewer composition                                               |
+| `ManifestComponents` | UI component slots, including an optional replacement for the source viewer                |
+
+## Install and use
+
+```sh
+pnpm add @bloodhound-rs/playground
+```
+
+React 18 or 19 is supplied by the host application. JavaScript, TypeScript declarations and CSS are included in the package.
+
+```tsx
+import { ManifestPlayground } from '@bloodhound-rs/playground';
+import '@bloodhound-rs/playground/styles.css';
+
+<ManifestPlayground components={components} loadText={loadText} />;
+```
+
+`initialResource` preloads a parsed report when mounting. `onChange(resource)` receives resource selections. `selectorProps` forwards `loadManifest`, `parse` and `maxBytes` to the selector. The remaining props go to `ManifestViewer`. Hosts that already manage the selected build use `ManifestViewer` directly.
+
+Headless parsing is available without importing React components:
+
+```ts
+import { parseManifest, ManifestIndex } from '@bloodhound-rs/playground/manifest';
+
+const { manifest } = parseManifest(jsonText);
+const index = new ManifestIndex(manifest);
+```
+
+## Ant Design example
+
+Install `antd` in the host application and pass its components with adapters for input events and table data. The host loads the manifest; this example renders the report without a resource selector.
+
+```tsx
+import { Button, Input, Select, Table, Tag } from 'antd';
+import { ManifestViewer, type Manifest, type ManifestComponents } from '@bloodhound-rs/playground';
+import '@bloodhound-rs/playground/styles.css';
+
+const components: Partial<ManifestComponents> = {
+  Button: (props) => <Button {...props} />,
+  Select,
+  Tag,
+  Input: ({ onChange, ...props }) => (
+    <Input {...props} onChange={(event) => onChange(event.target.value)} />
+  ),
+  Table: ({ data, ...props }) => <Table {...props} dataSource={data} />,
+};
+
+export function ScanReport({ manifest }: { manifest: Manifest }) {
+  return <ManifestViewer manifest={manifest} components={components} />;
+}
+```
+
+Ant Design's `Input.onChange` receives an event, while the viewer expects a string. Its `Table` uses `dataSource`, while the viewer supplies `data`. The adapters above translate these props. Define the component map outside rendering to keep component identities stable.
+
+Bloodhound does not depend on a UI library or inject a theme provider. Its CSS only styles the viewer's layout, default table and code excerpt, under `bh-` classes. Existing providers and component themes remain owned by the host.
+
+Components with different props use a small adapter. `Input.onChange` and `Select.onChange` receive a string. `Table` receives `data`, `columns`, `rowKey="id"` and `pagination={false}`. Missing slots use native HTML controls.
+
+## Source loading
+
+`manifestUrl` resolves relative map URLs. `loadText` routes generated code, source maps and original files through the host's resource service. The callback returns text and its absolute resource URL after redirects. No fetched code is executed.
+
+```tsx
+import { ManifestViewer, type TextLoader } from '@bloodhound-rs/playground';
+
+// Defined outside rendering; bind the selected build's ID in the host's service layer.
+const loadText: TextLoader = async (url, request) => {
+  return resourceService.readText({
+    url,
+    file: request.file,
+    kind: request.kind,
+    maxBytes: request.limit,
+  });
+};
+
+<ManifestViewer
+  manifest={manifest}
+  manifestUrl={manifestUrl}
+  components={components}
+  loadText={loadText}
+/>;
+```
+
+`resourceService` above is the host's implementation. `request.file` carries the project-relative path recorded by the plugin, when available. `request.kind` is `source` or `sourcemap`. A copied build artifact can therefore be resolved by build ID and path even when the public URL has changed. The custom loader owns authentication and enforces `request.limit`.
+
+With no loader, public HTTP(S) resources are fetched without credentials. The local Playground passes `workspace={{ projectRoot, fileEndpoint }}` to read files through its project endpoint. Original source is loaded only after opening a preview: project/host file first, then `sourcesContent`, then a resolvable source URL. A missing map association hides the original-source preview; users can explicitly link a map URL or, with a workspace/custom loader, a project path. Links last for the current report session.
+
+To use the platform's Monaco wrapper, supply `components.SourceCode`. Its props are `{ text, path?, location? }`; `location` uses 1-based lines and 0-based UTF-16 columns. Convert columns to Monaco's 1-based convention. The slot controls readonly rendering, highlighting and scrolling.
+
+## Compose the selector and viewer
+
+```tsx
+import { useState } from 'react';
+import { ManifestSelector, ManifestViewer, type ManifestResource } from '@bloodhound-rs/playground';
+import '@bloodhound-rs/playground/styles.css';
+
+export function Playground() {
+  const [resource, setResource] = useState<ManifestResource>();
+  return (
+    <>
+      <ManifestSelector onChange={setResource} />
+      {resource ? (
+        <ManifestViewer
+          manifest={resource.manifest}
+          manifestUrl={resource.url}
+          notices={resource.notices}
+        />
+      ) : null}
+    </>
+  );
+}
+```
+
+`ManifestSelector.loadManifest(url)` replaces URL fetching. `parse(text)` accepts a synchronous or asynchronous parser, including a host-managed worker. `maxBytes` defaults to 64 MiB. Local files remain in the browser; URL resources follow the browser's CORS rules unless the host supplies a loader.
+
+`ManifestViewer` additionally accepts `pageSize` (default 50), `className`, and `onSelect(row)`. Its four record categories are findings, sources, dependencies and gaps. Keep `manifest`, `workspace` and `loadText` references stable while displaying the same build. Replacing any resource context resets selection, filters, map links and pending preview state. Independent viewer instances do not share state.
+
+## Local development
+
+```sh
+pnpm build:playground-package
+pnpm playground --manifest /path/to/bloodhound.manifest.json --project /path/to/project
+```
+
+Open the printed **React components** URL (`/react.html`). It composes these exact exports. The classic Playground uses the same `@bloodhound-rs/manifest` parser and source resolver.
+
+## Changesets and release artifacts
+
+This public workspace package participates in the repository's existing Changesets release flow. Changesets versions `@bloodhound-rs/playground` and its shared manifest dependency. The release workflow builds workspace packages, packs their `dist` output and publishes dependencies before consumers. PR releases use the workflow's beta suffix and tag; main-branch releases use the stable version and latest tag.
+
+`pnpm build:playground-package` builds the component package. `pnpm build:playground` produces the repository's standalone preview site. The npm package exports components, styles and parsing utilities; it does not start a server or mount itself into the host page.

package/dist/ManifestPlayground.d.ts

@@ -0,0 +1,9 @@
+import { type ManifestResource, type ManifestSelectorProps } from './ManifestSelector.js';
+import { type ManifestViewerProps } from './ManifestViewer.js';
+export interface ManifestPlaygroundProps extends Omit<ManifestViewerProps, 'manifest' | 'manifestUrl' | 'notices'> {
+    initialResource?: ManifestResource;
+    onChange?: (resource: ManifestResource) => void;
+    selectorProps?: Pick<ManifestSelectorProps, 'loadManifest' | 'parse' | 'maxBytes'>;
+}
+/** Ready-to-use composition. Hosts with their own resource selection can use ManifestViewer alone. */
+export declare function ManifestPlayground({ initialResource, onChange, selectorProps, ...viewerProps }: ManifestPlaygroundProps): import("react").JSX.Element;

package/dist/ManifestPlayground.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { ManifestSelector, } from './ManifestSelector.js';
+import { ManifestViewer } from './ManifestViewer.js';
+/** Ready-to-use composition. Hosts with their own resource selection can use ManifestViewer alone. */
+export function ManifestPlayground({ initialResource, onChange, selectorProps, ...viewerProps }) {
+    const [resource, setResource] = useState(initialResource);
+    return (_jsxs(_Fragment, { children: [_jsx(ManifestSelector, { ...selectorProps, components: viewerProps.components, onChange: (resource) => {
+                    setResource(resource);
+                    onChange?.(resource);
+                } }), resource ? (_jsx(ManifestViewer, { ...viewerProps, manifest: resource.manifest, manifestUrl: resource.url, notices: resource.notices })) : null] }));
+}

package/dist/ManifestSelector.d.ts

@@ -0,0 +1,23 @@
+import { parseManifest, type Manifest } from '@bloodhound-rs/manifest';
+import { type ManifestComponents } from './components.js';
+export interface ManifestResource {
+    manifest: Manifest;
+    name: string;
+    url?: string;
+    notices: string[];
+}
+export interface ManifestSelectorProps {
+    onChange: (resource: ManifestResource) => void;
+    components?: Partial<ManifestComponents>;
+    /** Host-controlled URL fetch, including authentication when needed. */
+    loadManifest?: (url: string) => Promise<{
+        text: string;
+        url: string;
+    }>;
+    /** Supply a worker-backed parser for large reports. */
+    parse?: (text: string) => ReturnType<typeof parseManifest> | Promise<ReturnType<typeof parseManifest>>;
+    maxBytes?: number;
+    className?: string;
+}
+/** Resource input only. It does not render a report or load any source code. */
+export declare function ManifestSelector({ onChange, components, loadManifest, parse, maxBytes, className, }: ManifestSelectorProps): import("react").JSX.Element;

package/dist/ManifestSelector.js

@@ -0,0 +1,51 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { fetchText, parseManifest, safeUrl } from '@bloodhound-rs/manifest';
+import { defaultComponents } from './components.js';
+const defaultLoadManifest = (url) => fetchText(url, 64 * 1024 * 1024);
+/** Resource input only. It does not render a report or load any source code. */
+export function ManifestSelector({ onChange, components, loadManifest = defaultLoadManifest, parse = parseManifest, maxBytes = 64 * 1024 * 1024, className = '', }) {
+    const { Button, Input } = { ...defaultComponents, ...components };
+    const [url, setUrl] = useState('');
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState('');
+    const fileInput = useRef(null);
+    const request = useRef(0);
+    useEffect(() => () => {
+        request.current++;
+    }, []);
+    async function open(file) {
+        const id = ++request.current;
+        setLoading(true);
+        setError('');
+        try {
+            if (file && file.size > maxBytes)
+                throw new Error('Manifest exceeds the size limit.');
+            const address = file ? undefined : safeUrl(url.trim());
+            if (!file && !address)
+                throw new Error('Enter an HTTP(S) manifest URL.');
+            const data = file
+                ? { text: await file.text(), url: undefined }
+                : await loadManifest(address);
+            if (new TextEncoder().encode(data.text).length > maxBytes)
+                throw new Error('Manifest exceeds the size limit.');
+            const parsed = await parse(data.text);
+            if (id === request.current)
+                onChange({ ...parsed, name: file?.name ?? address, url: data.url });
+        }
+        catch (error) {
+            if (id === request.current)
+                setError(error instanceof Error ? error.message : String(error));
+        }
+        finally {
+            if (id === request.current)
+                setLoading(false);
+        }
+    }
+    return (_jsxs("section", { className: `bh-selector ${className}`, "aria-label": "Select manifest", "aria-busy": loading, children: [_jsxs("div", { className: "bh-controls", children: [_jsx("input", { ref: fileInput, type: "file", accept: ".json,application/json", hidden: true, onChange: (event) => {
+                            const file = event.currentTarget.files?.[0];
+                            event.currentTarget.value = '';
+                            if (file)
+                                void open(file);
+                        } }), _jsx(Button, { onClick: () => fileInput.current?.click(), children: "Open manifest file" }), _jsx(Input, { value: url, onChange: setUrl, placeholder: "https://\u2026/bloodhound.manifest.json", "aria-label": "Manifest URL" }), _jsx(Button, { disabled: !url.trim(), onClick: () => void open(), children: "Load URL" })] }), loading ? _jsx("p", { role: "status", children: "Loading manifest\u2026" }) : null, error ? _jsx("p", { role: "alert", children: error }) : null] }));
+}

package/dist/ManifestViewer.d.ts

@@ -0,0 +1,17 @@
+import { type Manifest, type ProjectWorkspace, type RecordRow, type TextLoader } from '@bloodhound-rs/manifest';
+import { type ManifestComponents } from './components.js';
+export interface ManifestViewerProps {
+    /** Already parsed report; replace this object when the build changes. */
+    manifest: Manifest;
+    components?: Partial<ManifestComponents>;
+    /** Base URL for relative source map references. */
+    manifestUrl?: string;
+    workspace?: ProjectWorkspace;
+    loadText?: TextLoader;
+    notices?: readonly string[];
+    pageSize?: number;
+    className?: string;
+    onSelect?: (row: RecordRow) => void;
+}
+/** Display only: no file picker, manifest request, router or application provider. */
+export declare function ManifestViewer(props: ManifestViewerProps): import("react").JSX.Element;

package/dist/ManifestViewer.js

@@ -0,0 +1,90 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useDeferredValue, useMemo, useState } from 'react';
+import { ManifestIndex, OriginalSources, sourceName, } from '@bloodhound-rs/manifest';
+import { defaultComponents } from './components.js';
+import { SourcePreview } from './SourcePreview.js';
+/** Display only: no file picker, manifest request, router or application provider. */
+export function ManifestViewer(props) {
+    const { manifest, manifestUrl, workspace, loadText } = props;
+    const [session, setSession] = useState({
+        manifest,
+        manifestUrl,
+        workspace,
+        loadText,
+        version: 0,
+    });
+    // Reset all selection, filters and source requests together when the host changes reports.
+    if (session.manifest !== manifest ||
+        session.manifestUrl !== manifestUrl ||
+        session.workspace !== workspace ||
+        session.loadText !== loadText) {
+        setSession({ manifest, manifestUrl, workspace, loadText, version: session.version + 1 });
+    }
+    return _jsx(ViewerSession, { ...props }, session.version);
+}
+const views = ['findings', 'sources', 'dependencies', 'gaps'];
+const groupings = ['type', 'source', 'folder', 'entry'];
+const initialFilters = {
+    view: 'findings',
+    query: '',
+    severity: '',
+    confidence: '',
+    grouping: 'type',
+    group: null,
+    includeDependencies: false,
+};
+function ViewerSession({ manifest, components, manifestUrl, workspace, loadText, notices, pageSize = 50, className = '', onSelect, }) {
+    const ui = { ...defaultComponents, ...components };
+    const { Button, Input, Select, Table, Tag } = ui;
+    const index = useMemo(() => new ManifestIndex(manifest), [manifest]);
+    const originals = useMemo(() => new OriginalSources(manifestUrl, workspace, loadText), [manifestUrl, workspace, loadText]);
+    const [filters, setFilters] = useState(initialFilters);
+    const [selected, setSelected] = useState();
+    const [page, setPage] = useState(0);
+    const query = useDeferredValue(filters.query);
+    const baseRows = useMemo(() => index.baseRows({ ...filters, query }), [index, filters.view, query, filters.severity, filters.confidence]);
+    const groups = useMemo(() => index.groups(baseRows, filters.grouping), [index, baseRows, filters.grouping]);
+    const rows = useMemo(() => index.filter(baseRows, filters), [index, baseRows, filters.group, filters.grouping, filters.includeDependencies]);
+    const size = Math.max(1, Math.floor(pageSize));
+    const pages = Math.max(1, Math.ceil(rows.length / size));
+    const activePage = Math.min(page, pages - 1);
+    const row = selected ? index.byId.get(selected) : undefined;
+    function filter(patch) {
+        setFilters((value) => ({ ...value, ...patch }));
+        setPage(0);
+        setSelected(undefined);
+    }
+    function select(row) {
+        setSelected(row.id);
+        onSelect?.(row);
+    }
+    function selectSource(id) {
+        const row = index.rows.sources.find((row) => row.source === id);
+        if (row)
+            select(row);
+    }
+    const columns = [
+        {
+            title: 'Record',
+            dataIndex: 'title',
+            render: (_, row) => _jsx(Button, { onClick: () => select(row), children: row.title }),
+        },
+        { title: 'Type', dataIndex: 'type', render: (_, row) => row.type },
+        { title: 'Status', dataIndex: 'status', render: (_, row) => _jsx(Tag, { children: row.status }) },
+        {
+            title: 'Source',
+            dataIndex: 'source',
+            render: (_, row) => (row.source ? sourceName(index.sources.get(row.source)) : 'Scan-wide'),
+        },
+    ];
+    const source = row?.source ? index.sources.get(row.source) : undefined;
+    const statusOptions = [...new Set(index.rows[filters.view].map((row) => row.status))];
+    return (_jsxs("section", { className: `bh-viewer ${className}`, "aria-label": "Bloodhound manifest report", children: [_jsxs("header", { className: "bh-heading", children: [_jsx("strong", { children: "Manifest report" }), _jsx(Tag, { children: manifest.status }), _jsxs("span", { children: ["Scanner ", manifest.scannerVersion, " \u00B7 ", manifest.dependencyMode] })] }), _jsx("p", { className: "bh-muted", children: "Static findings are candidates. Unresolved references and coverage gaps describe code the scan could not fully analyze." }), notices?.map((notice) => (_jsx("p", { role: "status", children: notice }, notice))), _jsx("nav", { className: "bh-controls", "aria-label": "Record categories", children: views.map((view) => (_jsxs(Button, { disabled: filters.view === view, onClick: () => filter({ ...initialFilters, view }), children: [view, " (", index.rows[view].length, ")"] }, view))) }), _jsxs("div", { className: "bh-controls", children: [_jsx(Input, { value: filters.query, onChange: (query) => filter({ query }), placeholder: "Search records, paths or code", "aria-label": "Search records" }), _jsx(Select, { value: filters.severity, onChange: (severity) => filter({ severity, group: null }), "aria-label": "Status", options: [
+                            { label: 'All statuses', value: '' },
+                            ...statusOptions.map((value) => ({ label: value, value })),
+                        ] }), filters.view === 'findings' ? (_jsx(Select, { value: filters.confidence, onChange: (confidence) => filter({ confidence, group: null }), "aria-label": "Confidence", options: [
+                            { label: 'All confidence levels', value: '' },
+                            { label: 'High', value: 'high' },
+                            { label: 'Medium', value: 'medium' },
+                        ] })) : null, _jsx(Select, { value: filters.grouping, onChange: (value) => filter({ grouping: value, group: null }), "aria-label": "Group by", options: groupings.map((value) => ({ label: `By ${value}`, value })) })] }), _jsxs("div", { className: "bh-layout", children: [_jsxs("aside", { className: "bh-groups", "aria-label": "Record groups", children: [_jsxs(Button, { disabled: filters.group === null, onClick: () => filter({ group: null }), children: ["All (", baseRows.length, ")"] }), groups.map((group) => (_jsxs(Button, { disabled: filters.group === group.id, onClick: () => filter({ group: group.id }), children: [group.name, " (", group.count, ")"] }, group.id))), filters.grouping === 'source' ? (_jsx(Button, { onClick: () => filter({ includeDependencies: !filters.includeDependencies }), children: filters.includeDependencies ? 'Exclude dependencies' : 'Include dependencies' })) : null] }), _jsxs("div", { className: "bh-results", children: [_jsx("div", { className: "bh-table-scroll", children: _jsx(Table, { columns: columns, data: rows.slice(activePage * size, (activePage + 1) * size), rowKey: "id", pagination: false }) }), rows.length === 0 ? _jsx("p", { role: "status", children: "No matching records." }) : null, _jsxs("div", { className: "bh-controls", "aria-label": "Pagination", children: [_jsx(Button, { disabled: activePage === 0, onClick: () => setPage(activePage - 1), children: "Previous" }), _jsxs("span", { children: [activePage + 1, " / ", pages, " \u00B7 ", rows.length, " records"] }), _jsx(Button, { disabled: activePage + 1 >= pages, onClick: () => setPage(activePage + 1), children: "Next" })] }), row ? (_jsxs("section", { className: "bh-detail", "aria-label": "Record details", children: [_jsxs("div", { className: "bh-heading", children: [_jsx("strong", { children: row.title }), _jsx(Button, { onClick: () => setSelected(undefined), children: "Close details" })] }), _jsxs("p", { children: [row.type, " \u00B7 ", row.status, row.confidence ? ` · ${row.confidence} confidence` : ''] }), source ? _jsx("p", { className: "bh-path", children: source.file ?? source.url ?? source.id }) : null, 'location' in row.data && row.data.location ? (_jsxs("p", { children: ["Line ", row.data.location.line, ", column ", row.data.location.column] })) : null, 'detail' in row.data && row.data.detail ? _jsx("p", { children: row.data.detail }) : null, 'snippet' in row.data ? _jsx("pre", { className: "bh-snippet", children: row.data.snippet }) : null, source && source.chain.length > 0 ? (_jsxs("div", { className: "bh-controls", "aria-label": "Entry chain", children: ["Entry chain:", ' ', source.chain.map((id) => (_jsx(Button, { onClick: () => selectSource(id), children: sourceName(index.sources.get(id)) }, id)))] })) : null, source ? (_jsxs("div", { className: "bh-controls", "aria-label": "Dependencies", children: ["Dependencies:", ' ', [...(index.children.get(source.id) ?? [])].map((id) => (_jsx(Button, { onClick: () => selectSource(id), children: sourceName(index.sources.get(id)) }, id)))] })) : null, _jsx(SourcePreview, { index: index, row: row, originals: originals, components: ui, customLoader: Boolean(loadText) }, row.id), _jsxs("details", { children: [_jsx("summary", { children: "Record JSON" }), _jsx("pre", { className: "bh-snippet", children: JSON.stringify(row.data, null, 2) })] })] })) : null] })] })] }));
+}

package/dist/SourcePreview.d.ts

@@ -0,0 +1,11 @@
+import { type ManifestIndex, type OriginalSources, type RecordRow } from '@bloodhound-rs/manifest';
+import type { ManifestComponents } from './components.js';
+interface Props {
+    index: ManifestIndex;
+    row: RecordRow;
+    originals: OriginalSources;
+    components: ManifestComponents;
+    customLoader: boolean;
+}
+export declare function SourcePreview({ index, row, originals, components, customLoader }: Props): import("react").JSX.Element;
+export {};

package/dist/SourcePreview.js

@@ -0,0 +1,81 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { viewerTarget, } from '@bloodhound-rs/manifest';
+function Preview({ load, components, }) {
+    const [result, setResult] = useState({ status: 'loading' });
+    const [attempt, setAttempt] = useState(0);
+    const { Button, SourceCode } = components;
+    useEffect(() => {
+        let active = true;
+        setResult({ status: 'loading' });
+        void load(attempt > 0).then((value) => {
+            if (active)
+                setResult(value);
+        }, (error) => {
+            if (active)
+                setResult({
+                    status: 'error',
+                    error: error instanceof Error ? error.message : String(error),
+                });
+        });
+        return () => {
+            active = false;
+        };
+    }, [load, attempt]);
+    if (result.status === 'loading')
+        return _jsx("p", { role: "status", children: "Loading source\u2026" });
+    if (result.status === 'error')
+        return (_jsxs("div", { role: "alert", children: [_jsx("p", { children: result.error }), _jsx(Button, { onClick: () => setAttempt((value) => value + 1), children: "Retry" })] }));
+    return (_jsxs("section", { "aria-label": "Source preview", children: [_jsxs("p", { className: "bh-path", children: [result.path, result.location ? `:${result.location.line}:${result.location.column}` : '', result.origin ? ` · ${result.origin}` : ''] }), _jsx(SourceCode, { text: result.text, path: result.path, location: result.location })] }));
+}
+export function SourcePreview({ index, row, originals, components, customLoader }) {
+    const { Button, Input } = components;
+    const source = row.source ? index.sources.get(row.source) : undefined;
+    const location = 'location' in row.data ? row.data.location : undefined;
+    const target = viewerTarget(index, row, originals.workspace, customLoader);
+    const [link, setLink] = useState('');
+    const [error, setError] = useState('');
+    const [load, setLoad] = useState();
+    const [reference, setReference] = useState(() => source && originals.reference(source));
+    const hasPosition = source && location;
+    function showOriginal() {
+        if (!source || !location)
+            return;
+        setLoad(() => async (retry) => {
+            await originals.preview(row.id, source, location, retry);
+            return originals.previews.get(row.id);
+        });
+    }
+    function associate() {
+        if (!source)
+            return;
+        try {
+            originals.link(source, link);
+            setReference(originals.reference(source));
+            setError('');
+            showOriginal();
+        }
+        catch (error) {
+            setError(error instanceof Error ? error.message : String(error));
+        }
+    }
+    return (_jsxs("div", { className: "bh-source-preview", children: [_jsxs("div", { className: "bh-controls", children: [target ? (_jsx(Button, { onClick: () => setLoad(() => async () => {
+                            const data = await originals.loadText(target.url, {
+                                kind: 'source',
+                                file: target.source.file,
+                                limit: 8 * 1024 * 1024,
+                            });
+                            return {
+                                status: 'ready',
+                                text: data.text,
+                                path: target.source.file ?? data.url,
+                                location: target.location,
+                            };
+                        }), children: "Preview generated code" })) : null, reference && hasPosition ? (_jsx(Button, { onClick: showOriginal, children: "Preview original source" })) : null] }), hasPosition ? (_jsxs("details", { children: [_jsx("summary", { children: "Source map association" }), reference ? (_jsx("p", { className: "bh-path", children: reference.file ?? reference.url })) : (_jsx("p", { children: "No source map linked." })), _jsxs("div", { className: "bh-controls", children: [_jsx(Input, { value: link, onChange: setLink, placeholder: "Source map URL or project path", "aria-label": "Source map URL or project path" }), _jsx(Button, { onClick: associate, disabled: !link.trim(), children: "Link source map" }), reference ? (_jsx(Button, { onClick: () => {
+                                    originals.unlink(source);
+                                    setReference(undefined);
+                                    setLoad(undefined);
+                                    setError('');
+                                    setLink('');
+                                }, children: "Unlink" })) : null] }), error ? _jsx("p", { role: "alert", children: error }) : null] })) : null, load ? _jsx(Preview, { load: load, components: components }) : null] }));
+}

package/dist/components.d.ts

@@ -0,0 +1,56 @@
+import type { JSXElementConstructor, CSSProperties, ReactNode } from 'react';
+import { type Location, type RecordRow } from '@bloodhound-rs/manifest';
+interface ControlProps {
+    className?: string;
+    style?: CSSProperties;
+    'aria-label'?: string;
+    disabled?: boolean;
+}
+export interface ButtonProps extends ControlProps {
+    children?: ReactNode;
+    onClick?: () => void;
+}
+export interface InputProps extends ControlProps {
+    value: string;
+    placeholder?: string;
+    onChange: (value: string) => void;
+}
+export interface SelectProps extends ControlProps {
+    value: string;
+    options: {
+        label: string;
+        value: string;
+    }[];
+    onChange: (value: string) => void;
+}
+export interface TagProps {
+    children?: ReactNode;
+}
+export interface TableColumn {
+    title: string;
+    dataIndex: string;
+    render: (value: unknown, record: RecordRow) => ReactNode;
+}
+export interface TableProps {
+    data: RecordRow[];
+    columns: TableColumn[];
+    rowKey: 'id';
+    pagination: false;
+}
+export interface SourceCodeProps {
+    text: string;
+    path?: string;
+    /** Lines are 1-based, columns are 0-based. */
+    location?: Location;
+}
+/** Pass compatible library exports directly; adapt only components with different props. */
+export interface ManifestComponents {
+    Button: JSXElementConstructor<ButtonProps>;
+    Input: JSXElementConstructor<InputProps>;
+    Select: JSXElementConstructor<SelectProps>;
+    Tag: JSXElementConstructor<TagProps>;
+    Table: JSXElementConstructor<TableProps>;
+    SourceCode: JSXElementConstructor<SourceCodeProps>;
+}
+export declare const defaultComponents: ManifestComponents;
+export {};

package/dist/components.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { codeWindow } from '@bloodhound-rs/manifest';
+function Button(props) {
+    return _jsx("button", { type: "button", ...props });
+}
+function Input({ onChange, ...props }) {
+    return _jsx("input", { ...props, onChange: (event) => onChange(event.target.value) });
+}
+function Select({ options, onChange, ...props }) {
+    return (_jsx("select", { ...props, onChange: (event) => onChange(event.target.value), children: options.map((option) => (_jsx("option", { value: option.value, children: option.label }, option.value))) }));
+}
+function Tag({ children }) {
+    return _jsx("span", { className: "bh-tag", children: children });
+}
+function Table({ columns, data }) {
+    return (_jsxs("table", { className: "bh-table", children: [_jsx("thead", { children: _jsx("tr", { children: columns.map((column) => (_jsx("th", { scope: "col", children: column.title }, column.dataIndex))) }) }), _jsx("tbody", { children: data.map((row) => (_jsx("tr", { children: columns.map((column) => (_jsx("td", { children: column.render(undefined, row) }, column.dataIndex))) }, row.id))) })] }));
+}
+function SourceCode({ text, location }) {
+    const view = codeWindow(text, location, 25);
+    return (_jsxs("div", { className: "bh-code", children: [_jsxs("small", { children: ["Lines ", view.from, "\u2013", view.to, " of ", view.total] }), _jsx("pre", { children: view.lines.map((line) => (_jsxs("div", { "data-highlight": line.inRange || undefined, children: [_jsx("span", { className: "bh-line-number", children: line.number }), line.cutBefore ? '…' : '', line.before, _jsx("mark", { children: line.hit }), line.after, line.cutAfter ? '…' : ''] }, line.number))) })] }));
+}
+export const defaultComponents = {
+    Button,
+    Input,
+    Select,
+    Tag,
+    Table,
+    SourceCode,
+};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { ManifestViewer, type ManifestViewerProps } from './ManifestViewer.js';
+export { ManifestPlayground, type ManifestPlaygroundProps } from './ManifestPlayground.js';
+export { ManifestSelector, type ManifestSelectorProps, type ManifestResource, } from './ManifestSelector.js';
+export { defaultComponents } from './components.js';
+export type { ManifestComponents, ButtonProps, InputProps, SelectProps, TableProps, TableColumn, TagProps, SourceCodeProps, } from './components.js';
+export type { Manifest, TextLoader, TextRequest, TextResource, ProjectWorkspace, RecordRow, } from '@bloodhound-rs/manifest';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { ManifestViewer } from './ManifestViewer.js';
+export { ManifestPlayground } from './ManifestPlayground.js';
+export { ManifestSelector, } from './ManifestSelector.js';
+export { defaultComponents } from './components.js';

package/dist/manifest.d.ts

@@ -0,0 +1 @@
+export * from '@bloodhound-rs/manifest';

package/dist/manifest.js

@@ -0,0 +1 @@
+export * from '@bloodhound-rs/manifest';

package/dist/styles.css

@@ -0,0 +1,117 @@
+.bh-viewer,
+.bh-selector {
+  --bh-border: var(--color-border, #dce1e8);
+  --bh-muted: var(--color-text-3, #667085);
+  --bh-accent: var(--color-primary-light-1, #eef2ff);
+  color: inherit;
+  font: inherit;
+  line-height: 1.5;
+  min-width: 0;
+}
+.bh-controls,
+.bh-heading {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 8px;
+  margin-block: 12px;
+}
+.bh-selector input:not([type='file']),
+.bh-viewer input {
+  min-width: 220px;
+}
+.bh-layout {
+  display: grid;
+  grid-template-columns: minmax(160px, 230px) minmax(0, 1fr);
+  gap: 20px;
+}
+.bh-groups {
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+  gap: 6px;
+  overflow: auto;
+  max-height: 65vh;
+}
+.bh-groups > * {
+  text-align: left;
+  overflow-wrap: anywhere;
+  flex-shrink: 0;
+  white-space: normal;
+}
+.bh-results {
+  min-width: 0;
+}
+.bh-table-scroll {
+  overflow-x: auto;
+}
+.bh-table {
+  width: 100%;
+  border-collapse: collapse;
+  text-align: left;
+}
+.bh-table th,
+.bh-table td {
+  padding: 10px;
+  border-bottom: 1px solid var(--bh-border);
+  overflow-wrap: anywhere;
+}
+.bh-table td {
+  max-width: 400px;
+}
+.bh-tag {
+  display: inline-block;
+  padding: 2px 8px;
+  border: 1px solid var(--bh-border);
+  border-radius: 4px;
+}
+.bh-detail {
+  border-top: 1px solid var(--bh-border);
+  padding-top: 12px;
+}
+.bh-path {
+  overflow-wrap: anywhere;
+}
+.bh-muted,
+.bh-line-number {
+  color: var(--bh-muted);
+}
+.bh-code pre,
+.bh-snippet {
+  overflow: auto;
+  max-height: 500px;
+  padding: 12px;
+  border: 1px solid var(--bh-border);
+  border-radius: 4px;
+  font: 13px/1.6 monospace;
+}
+.bh-snippet {
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+}
+.bh-line-number {
+  display: inline-block;
+  min-width: 5ch;
+  margin-right: 16px;
+  user-select: none;
+  text-align: right;
+}
+.bh-code [data-highlight] {
+  background: var(--bh-accent);
+}
+.bh-code mark {
+  background: #fff1a8;
+  color: #1d2939;
+}
+.bh-viewer summary {
+  cursor: pointer;
+  margin-block: 12px;
+}
+@media (max-width: 700px) {
+  .bh-layout {
+    grid-template-columns: minmax(0, 1fr);
+  }
+  .bh-groups {
+    max-height: 200px;
+  }
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@bloodhound-rs/playground",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.0",
+  "description": "Embeddable Bloodhound Playground, manifest viewer and resource selector for React",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./manifest": {
+      "types": "./dist/manifest.d.ts",
+      "import": "./dist/manifest.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "dependencies": {
+    "@bloodhound-rs/manifest": "0.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "@types/react": "^18.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Justinidlerz/bloodhound.git",
+    "directory": "packages/playground"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node -e \"require('node:fs').copyFileSync('src/styles.css', 'dist/styles.css')\"",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
 }