@braidlabs/console 0.1.1

package/README.md

@@ -0,0 +1,131 @@
+# @braidlabs/console
+
+A read-only console for a [Braid](../braid-gateway) gateway's fragment registry. One package, two
+shapes: a mountable React component, and a standalone deployable app.
+
+**It needs nothing deployed.** It reads the `/__braid/registry` discovery endpoint the gateway
+already serves, so it works against a gateway whose manifests are defined in code — which is every
+gateway today. No snapshot store, no write API.
+
+## As a library
+
+For teams who already run an internal admin app and want this inside it rather than beside it:
+
+```tsx
+import { RegistryConsole } from '@braidlabs/console';
+
+<RegistryConsole api={{ baseUrl: '/api/gateway', headers: () => ({ Authorization: token }) }} />;
+```
+
+| Prop | Type | Notes |
+| --- | --- | --- |
+| `api` | `ConsoleApi` | base URL, discovery path, a `headers()` hook, or your own `fetch` |
+| `theme` | `'light' \| 'dark'` | omit to follow the viewer's OS setting |
+| `className` | `string` | for sizing and positioning |
+| `onLoaded` | `(listing) => void` | for hosts that want their own chrome |
+
+## As an app
+
+```bash
+nx build-app braid-console     # → dist/apps/braid-console
+nx serve-app braid-console     # dev server
+```
+
+A static bundle for object storage, nginx, or the gateway itself. Configuration comes from the DOM,
+not from a build-time constant, so **one artifact serves every environment**:
+
+```html
+<script type="application/json" id="braid-console-config">
+  { "baseUrl": "https://shell.example" }
+</script>
+```
+
+Omit it and the console reads the origin it was served from — which is what you want when the
+gateway serves the bundle, and the simplest deployment there is.
+
+## Being a library has consequences
+
+Mounting inside someone else's page is a real constraint, and these are cheaper to honor from the
+start than to retrofit:
+
+**No global styles.** Every rule is scoped under `.braid-console`. No resets, no bare element
+selectors, no `:root`. A library that styles `body` or `*` vandalizes its host, and the damage
+surfaces in a part of the app nobody connects to this component. There is a test that walks the
+parsed CSSOM and fails if any selector escapes the scope.
+
+**No router ownership.** The console cannot own the URL bar in someone else's app, so it holds its
+own state.
+
+**No session.** It takes an API base and a `headers()` hook and never performs a login — identity
+belongs to the host, exactly as it does for the gateway's own `principal` resolver.
+
+**Theming by variable, not by specificity.** Everything themable is a CSS custom property on the
+scope class. Dark mode follows `prefers-color-scheme`; `theme="dark"` forces it, and wins in both
+directions, because an admin shell may be dark inside a light OS.
+
+**Container queries, not media queries.** The console's width is its host's business, not the
+viewport's. In a 420px sidebar it stacks — on a 1280px screen.
+
+**Slim is a number.** 140 kB gzipped for the app bundle including React and the inlined
+stylesheet, enforced by `nx size braid-console`. Currently 61 kB. React is a peer dependency in
+library form, so a host never ships two copies.
+
+## Editing
+
+```tsx
+import { RegistryEditor } from '@braidlabs/console';
+
+<RegistryEditor api={{ apiPath: '/__braid/registry-api' }} onPublished={(o) => toast(o.snapshot.id)} />;
+```
+
+Needs [`@braidlabs/registry`](../braid-registry)'s write API mounted. The flow is **branch from
+what is pinned → edit → see what it changes → publish**, and publishing never mutates the snapshot
+being edited: it mints a new one and moves a pointer, so the previous configuration survives
+untouched and rollback is re-pinning it.
+
+Three things the editor does on purpose:
+
+**Validates as you type, and does not trust itself.** The same `validateRegistry` the server runs,
+run locally for the person typing. The server validates again, because a client check is advice and
+the server's is the decision — a 422 shows the server's findings, not the client's.
+
+**Marks gateway-owned fields.** `endpoint`, `pierce`, `access`, `fallback` carry a badge, and the
+pre-publish diff labels every change by owner. A changed `pierce` is a routing change with
+page-wide blast radius; a changed `title` is a label. An unlabelled list makes them look alike.
+
+**Clearing a field removes it.** An empty input means *unset*, not `""` — because an omitted field
+is what lets a fragment descriptor supply it later, and `title: ""` is not the same as no title.
+
+**Previews who loses access.** *Show access* renders a list/fetch matrix per named principal, with
+`✓ → ✗` transitions against what is pinned. Losses lead; the grid is context. The count surfaces in
+the publish bar whether or not the panel is open, because a finding hidden behind a toggle nobody
+pressed is not a finding. Every outcome carries a text label as well as a symbol, so the meaning
+does not depend on colour.
+
+Principals are what-ifs, not a directory — the gateway has none. Pass `principals` and
+`onPrincipalsChange` to hold them in the host; omit both and the editor keeps them for the session.
+
+Drafts live in the browser. Nothing is written until you publish, so closing the tab discards, and
+there is no draft state to reconcile between editors.
+
+## What it shows
+
+| Column | |
+| --- | --- |
+| Fragment | id, title, description, tags |
+| Adapter | `compat`, `custom-element`, … |
+| Pierces | the page URL patterns it is server-rendered into |
+| Mount | what `<fragment-slot name>` resolves to |
+| Access | `loadable` or `gated` |
+
+`gated` is not a broken row. Listing and loading are **separate rules**, so a fragment you may see
+but not load is a legitimate state — a launcher should render it, not hide it. And when a gateway
+is in development mode the listing skips access filtering entirely, which the console says out
+loud rather than letting you mistake a dev listing for a production one.
+
+## Related
+
+- [`@braidlabs/registry`](../braid-registry) — snapshots and analysis, for when the registry
+  becomes editable
+- [the plan](../../docs/plans/braid-registry-console-plan.md) — including why the console is
+  deliberately optional, and the line it must not cross

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@braidlabs/console",
+  "version": "0.1.1",
+  "description": "A read-only console for a Braid gateway's fragment registry. Mountable React library, or a standalone deployable app.",
+  "keywords": [
+    "braid",
+    "micro-frontends",
+    "registry",
+    "console",
+    "react"
+  ],
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "@braidlabs/gateway": "^0.1.1",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "@braidlabs/registry": "^0.1.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/braidjs/braid.git",
+    "directory": "libs/braid-console"
+  },
+  "homepage": "https://github.com/braidjs/braid#readme",
+  "bugs": {
+    "url": "https://github.com/braidjs/braid/issues"
+  },
+  "module": "./src/index.js"
+}

package/src/app/console-app.d.ts

@@ -0,0 +1,17 @@
+import type { ConsoleApi } from '../lib/client.js';
+/**
+ * The standalone deployment's shell.
+ *
+ * This lives in `app/`, not `lib/`, on purpose: it owns a page — a title, a tab strip, and the
+ * URL — and every one of those is something the library must *not* own when it mounts inside
+ * someone else's admin app. Keeping the page-level concerns here is what lets `RegistryConsole`
+ * stay embeddable.
+ *
+ * The view is in the URL hash rather than in state alone, so a topology someone is looking at is
+ * a link they can paste into a ticket. That is the difference between a console an operator uses
+ * and one they screenshot.
+ */
+export declare function ConsoleApp({ api, edit }: {
+    api: ConsoleApi;
+    edit: boolean;
+}): import("react").JSX.Element;

package/src/app/console-app.js

@@ -0,0 +1,48 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { RegistryConsole } from '../lib/registry-console.js';
+import { RegistryEditor } from '../lib/registry-editor.js';
+import { ensureStyles } from '../lib/styles.js';
+/**
+ * The standalone deployment's shell.
+ *
+ * This lives in `app/`, not `lib/`, on purpose: it owns a page — a title, a tab strip, and the
+ * URL — and every one of those is something the library must *not* own when it mounts inside
+ * someone else's admin app. Keeping the page-level concerns here is what lets `RegistryConsole`
+ * stay embeddable.
+ *
+ * The view is in the URL hash rather than in state alone, so a topology someone is looking at is
+ * a link they can paste into a ticket. That is the difference between a console an operator uses
+ * and one they screenshot.
+ */
+export function ConsoleApp({ api, edit }) {
+    const [view, setView] = useState(() => readView(edit));
+    useEffect(() => {
+        ensureStyles();
+    }, []);
+    // Back and forward should move between views, since the tabs put entries in history.
+    useEffect(() => {
+        const onHashChange = () => setView(readView(edit));
+        window.addEventListener('hashchange', onHashChange);
+        return () => window.removeEventListener('hashchange', onHashChange);
+    }, [edit]);
+    function go(next) {
+        window.location.hash = next;
+        setView(next);
+    }
+    const tabs = [
+        { id: 'fragments', label: 'Fragments' },
+        { id: 'topology', label: 'Topology' },
+        ...(edit ? [{ id: 'edit', label: 'Edit registry' }] : []),
+    ];
+    return (_jsxs("div", { className: "braid-console", children: [_jsxs("div", { className: "braid-console__shell", children: [_jsxs("div", { className: "braid-console__titlebar", children: [_jsx("h1", { className: "braid-console__producttitle", children: "Braid gateway" }), _jsxs("span", { className: "braid-console__breadcrumb", children: [_jsx("span", { "aria-hidden": "true", children: "\u00B7" }), _jsx("code", { children: api.baseUrl || window.location.host })] })] }), _jsx("div", { className: "braid-console__commandbar", children: _jsx("div", { className: "braid-console__tabs", role: "tablist", "aria-label": "Console views", children: tabs.map((entry) => (_jsx("button", { type: "button", role: "tab", className: "braid-console__tab", "aria-selected": view === entry.id, onClick: () => go(entry.id), children: entry.label }, entry.id))) }) })] }), view === 'edit' ? (_jsx(RegistryEditor, { api: api })) : (_jsx(RegistryConsole, { api: api, chrome: false, view: view }))] }));
+}
+function readView(edit) {
+    const hash = window.location.hash.replace('#', '');
+    if (hash === 'topology')
+        return 'topology';
+    if (hash === 'edit' && edit)
+        return 'edit';
+    return 'fragments';
+}
+//# sourceMappingURL=console-app.js.map

package/src/app/console-app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-app.js","sourceRoot":"","sources":["../../../../../libs/braid-console/src/app/console-app.tsx"],"names":[],"mappings":"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"}

package/src/app/main.d.ts

@@ -0,0 +1 @@
+export {};

package/src/app/main.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createRoot } from 'react-dom/client';
+import { ConsoleApp } from './console-app.js';
+/**
+ * Standalone entry — the deployable form.
+ *
+ * Configuration comes from the DOM rather than a build-time constant, so one bundle serves every
+ * environment: the same artifact staging tested is the artifact production runs, pointed
+ * elsewhere. Drop a `<script type="application/json" id="braid-console-config">` next to the mount
+ * point, or leave it out and the console reads the origin it was served from.
+ */
+const mount = document.getElementById('root');
+if (!mount)
+    throw new Error('braid-console: no #root element to mount into');
+const config = readConfig();
+// Read-only unless the deployment says otherwise. Editing needs a write API the gateway may not
+// have mounted, and defaulting to an editor that cannot save is a worse first impression than a
+// listing that works — so `edit` adds a tab rather than replacing the console with one.
+createRoot(mount).render(_jsx(ConsoleApp, { api: config, edit: config.edit === true }));
+function readConfig() {
+    const element = document.getElementById('braid-console-config');
+    if (!element?.textContent)
+        return {};
+    try {
+        return JSON.parse(element.textContent);
+    }
+    catch {
+        console.warn('braid-console: #braid-console-config is not valid JSON; using defaults');
+        return {};
+    }
+}
+//# sourceMappingURL=main.js.map

package/src/app/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../../../../libs/braid-console/src/app/main.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C;;;;;;;GAOG;AACH,MAAM,KAAK,GAAG,QAAQ,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;AAC9C,IAAI,CAAC,KAAK;IAAE,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;AAE7E,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;AAE5B,gGAAgG;AAChG,gGAAgG;AAChG,wFAAwF;AACxF,UAAU,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAC,UAAU,IAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,KAAK,IAAI,GAAI,CAAC,CAAC;AAElF,SAAS,UAAU;IACjB,MAAM,OAAO,GAAG,QAAQ,CAAC,cAAc,CAAC,sBAAsB,CAAC,CAAC;IAChE,IAAI,CAAC,OAAO,EAAE,WAAW;QAAE,OAAO,EAAE,CAAC;IACrC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,CAAoC,CAAC;IAC5E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,IAAI,CAAC,wEAAwE,CAAC,CAAC;QACvF,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC"}

package/src/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @braidlabs/console — a read-only view of a Braid gateway's fragment registry.
+ *
+ * Two ways to use it, from one package:
+ *
+ * ```tsx
+ * // as a library, inside an admin app you already run
+ * import { RegistryConsole } from '@braidlabs/console';
+ * <RegistryConsole api={{ baseUrl: '/api/gateway' }} />
+ * ```
+ *
+ * ```sh
+ * # as a deployable app — a static bundle pointed at a gateway by config
+ * nx build-app braid-console
+ * ```
+ *
+ * It reads the discovery endpoint the gateway already serves, so it needs no snapshot store and
+ * no write API — it works against a gateway whose manifests are defined in code.
+ */
+export { RegistryConsole, filterEntries } from './lib/registry-console.js';
+export { TopologyGraph, layoutTopology } from './lib/topology-graph.js';
+export { IntegrationPanel } from './lib/integration-panel.js';
+export type { IntegrationPanelProps } from './lib/integration-panel.js';
+export { integrationSnippet, allIntegrationSnippets, integrationWarnings, INTEGRATION_TARGETS } from './lib/integration.js';
+export type { IntegrationTarget, IntegrationSnippet } from './lib/integration.js';
+export type { TopologyGraphProps } from './lib/topology-graph.js';
+export { buildTopology, neighborhood, coTenants, edgeKey } from './lib/topology.js';
+export type { Topology, TopologyNode, TopologyEdge, TopologyNodeKind } from './lib/topology.js';
+export type { RegistryConsoleProps } from './lib/registry-console.js';
+export { RegistryEditor } from './lib/registry-editor.js';
+export type { RegistryEditorProps } from './lib/registry-editor.js';
+export { AccessPanel } from './lib/access-panel.js';
+export type { AccessPanelProps } from './lib/access-panel.js';
+export { createDraft, draftStatus, addFragment, removeFragment, updateFragment, resetDraft, parseList, formatList, } from './lib/draft.js';
+export type { Draft, DraftStatus } from './lib/draft.js';
+export { fetchRegistry, fetchHead, listSnapshots, publishSnapshot, pinSnapshot, RegistryFetchError, RegistryApiError, DEFAULT_DISCOVERY_PATH, DEFAULT_API_PATH, } from './lib/client.js';
+export type { ConsoleApi, RegistryListing, HeadState, PublishOutcome } from './lib/client.js';
+export { CONSOLE_STYLES, ensureStyles } from './lib/styles.js';

package/src/index.js

@@ -0,0 +1,30 @@
+/**
+ * @braidlabs/console — a read-only view of a Braid gateway's fragment registry.
+ *
+ * Two ways to use it, from one package:
+ *
+ * ```tsx
+ * // as a library, inside an admin app you already run
+ * import { RegistryConsole } from '@braidlabs/console';
+ * <RegistryConsole api={{ baseUrl: '/api/gateway' }} />
+ * ```
+ *
+ * ```sh
+ * # as a deployable app — a static bundle pointed at a gateway by config
+ * nx build-app braid-console
+ * ```
+ *
+ * It reads the discovery endpoint the gateway already serves, so it needs no snapshot store and
+ * no write API — it works against a gateway whose manifests are defined in code.
+ */
+export { RegistryConsole, filterEntries } from './lib/registry-console.js';
+export { TopologyGraph, layoutTopology } from './lib/topology-graph.js';
+export { IntegrationPanel } from './lib/integration-panel.js';
+export { integrationSnippet, allIntegrationSnippets, integrationWarnings, INTEGRATION_TARGETS } from './lib/integration.js';
+export { buildTopology, neighborhood, coTenants, edgeKey } from './lib/topology.js';
+export { RegistryEditor } from './lib/registry-editor.js';
+export { AccessPanel } from './lib/access-panel.js';
+export { createDraft, draftStatus, addFragment, removeFragment, updateFragment, resetDraft, parseList, formatList, } from './lib/draft.js';
+export { fetchRegistry, fetchHead, listSnapshots, publishSnapshot, pinSnapshot, RegistryFetchError, RegistryApiError, DEFAULT_DISCOVERY_PATH, DEFAULT_API_PATH, } from './lib/client.js';
+export { CONSOLE_STYLES, ensureStyles } from './lib/styles.js';
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../libs/braid-console/src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAE9D,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAG5H,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAGpF,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEpD,OAAO,EACL,WAAW,EACX,WAAW,EACX,WAAW,EACX,cAAc,EACd,cAAc,EACd,UAAU,EACV,SAAS,EACT,UAAU,GACX,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,aAAa,EACb,SAAS,EACT,aAAa,EACb,eAAe,EACf,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC"}

package/src/lib/access-panel.d.ts

@@ -0,0 +1,21 @@
+import type { FragmentManifest } from '@braidlabs/gateway';
+import { type NamedPrincipal } from '@braidlabs/registry';
+export interface AccessPanelProps {
+    /** The draft being edited. */
+    manifests: readonly FragmentManifest[];
+    /** What is currently pinned, so the panel can show what the draft would change. */
+    base?: readonly FragmentManifest[];
+    principals: readonly NamedPrincipal[];
+    onPrincipalsChange: (principals: NamedPrincipal[]) => void;
+}
+/**
+ * Who can see and load what, and what the draft would do to that.
+ *
+ * The losses lead and the grid follows, because the losses are the finding. A grid on its own asks
+ * an operator to scan for the one cell that moved, which is exactly the failure this exists to
+ * prevent — a fragment quietly ceasing to be listed for the people who use it.
+ *
+ * Principals are named by the operator and held here, not persisted: the gateway has no principal
+ * directory, and inventing one would make this look authoritative when it is a what-if.
+ */
+export declare function AccessPanel({ manifests, base, principals, onPrincipalsChange }: AccessPanelProps): import("react").JSX.Element;

package/src/lib/access-panel.js

@@ -0,0 +1,35 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useMemo, useState } from 'react';
+import { accessMatrix, ANONYMOUS, parsePrincipal } from '@braidlabs/registry';
+/**
+ * Who can see and load what, and what the draft would do to that.
+ *
+ * The losses lead and the grid follows, because the losses are the finding. A grid on its own asks
+ * an operator to scan for the one cell that moved, which is exactly the failure this exists to
+ * prevent — a fragment quietly ceasing to be listed for the people who use it.
+ *
+ * Principals are named by the operator and held here, not persisted: the gateway has no principal
+ * directory, and inventing one would make this look authoritative when it is a what-if.
+ */
+export function AccessPanel({ manifests, base, principals, onPrincipalsChange }) {
+    const [draftPrincipal, setDraftPrincipal] = useState('');
+    const matrix = useMemo(() => accessMatrix(manifests, [ANONYMOUS, ...principals], base), [manifests, principals, base]);
+    const addPrincipal = () => {
+        const spec = draftPrincipal.trim();
+        if (!spec)
+            return;
+        const parsed = parsePrincipal(spec);
+        if (parsed.name === ANONYMOUS.name)
+            return; // always present; adding it again would duplicate a column
+        onPrincipalsChange([...principals.filter((p) => p.name !== parsed.name), parsed]);
+        setDraftPrincipal('');
+    };
+    return (_jsxs("section", { className: "braid-console__access", children: [_jsxs("div", { className: "braid-console__accesshead", children: [_jsx("strong", { children: "Access" }), _jsx("span", { className: "braid-console__desc", children: "Named principals, not real users \u2014 the gateway holds no directory." }), _jsx("span", { className: "braid-console__spacer" }), _jsx("input", { className: "braid-console__search", value: draftPrincipal, placeholder: "trader:roles=trader", "aria-label": "Add a principal to test as", onChange: (event) => setDraftPrincipal(event.target.value), onKeyDown: (event) => event.key === 'Enter' && addPrincipal() }), _jsx("button", { className: "braid-console__ghost", type: "button", onClick: addPrincipal, children: "Test as" })] }), base && matrix.unchanged && _jsx("p", { className: "braid-console__desc", children: "This draft changes nobody\u2019s access." }), matrix.losses.length > 0 && (_jsx("ul", { className: "braid-console__findings", role: "alert", children: matrix.losses.map((loss, index) => (_jsxs("li", { className: "braid-console__finding braid-console__finding--error", children: [_jsx("strong", { children: loss.principal }), " can no longer ", loss.action, " ", _jsx("strong", { children: loss.fragmentId }), loss.to === 'absent' && _jsx("span", { className: "braid-console__desc", children: " (fragment removed)" })] }, index))) })), matrix.gains.length > 0 && (_jsx("ul", { className: "braid-console__findings", children: matrix.gains.map((gain, index) => (_jsxs("li", { className: "braid-console__finding", children: [_jsx("strong", { children: gain.principal }), " can now ", gain.action, " ", _jsx("strong", { children: gain.fragmentId })] }, index))) })), _jsxs("table", { className: "braid-console__table braid-console__matrix", children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: "Fragment" }), matrix.principals.map((name) => (_jsxs("th", { scope: "col", children: [name, name !== ANONYMOUS.name && (_jsx("button", { className: "braid-console__ghost braid-console__remove", type: "button", "aria-label": `Stop testing as ${name}`, onClick: () => onPrincipalsChange(principals.filter((p) => p.name !== name)), children: "\u00D7" }))] }, name)))] }) }), _jsx("tbody", { children: matrix.rows.map((row) => (_jsxs("tr", { children: [_jsxs("td", { children: [_jsx("span", { className: "braid-console__id", children: row.fragmentId }), ' ', _jsx("span", { className: "braid-console__mono", children: row.action })] }), row.cells.map((cellValue) => (_jsx("td", { children: cellValue.changed && base ? (_jsxs(_Fragment, { children: [_jsx(Mark, { outcome: cellValue.before }), " ", _jsx("span", { "aria-hidden": "true", children: "\u2192" }), ' ', _jsx(Mark, { outcome: cellValue.after })] })) : (_jsx(Mark, { outcome: cellValue.after })) }, cellValue.principal)))] }, `${row.fragmentId}:${row.action}`))) })] })] }));
+}
+/** Never colour alone — the label is what a screen reader and a colourblind reader both get. */
+function Mark({ outcome }) {
+    const symbol = outcome === 'allowed' ? '✓' : outcome === 'denied' ? '✗' : '·';
+    const label = outcome === 'allowed' ? 'allowed' : outcome === 'denied' ? 'denied' : 'not present';
+    return (_jsxs("span", { className: `braid-console__mark braid-console__mark--${outcome}`, title: label, children: [_jsx("span", { "aria-hidden": "true", children: symbol }), _jsx("span", { className: "braid-console__sronly", children: label })] }));
+}
+//# sourceMappingURL=access-panel.js.map

package/src/lib/access-panel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-panel.js","sourceRoot":"","sources":["../../../../../libs/braid-console/src/lib/access-panel.tsx"],"names":[],"mappings":"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"}

package/src/lib/client.d.ts

@@ -0,0 +1,94 @@
+import type { DiscoveryEntry, FragmentManifest } from '@braidlabs/gateway';
+import type { DescriptorNote, RegistryDiff, RegistryFinding, SnapshotRef } from '@braidlabs/registry';
+/**
+ * How the console reaches a gateway.
+ *
+ * Identity belongs to the host, exactly as it does for the gateway's own `principal` resolver:
+ * this takes a base URL and a headers hook (or a whole `fetch`) and never performs a login. A
+ * console mounted inside an internal admin app should inherit that app's session, not open a
+ * second one.
+ */
+export interface ConsoleApi {
+    /** Where the gateway is. Defaults to the page's own origin. */
+    baseUrl?: string;
+    /** Path of the discovery listing. Defaults to `/__braid/registry`. */
+    discoveryPath?: string;
+    /**
+     * Path the registry write API is mounted at. Defaults to `/__braid/registry-api`.
+     *
+     * Editing needs this API; the read-only console does not. A gateway that has not mounted one is
+     * simply not editable, which is the common case and not an error.
+     */
+    apiPath?: string;
+    /** Called before every request, so a short-lived token can be refreshed by the host. */
+    headers?: () => Record<string, string> | Promise<Record<string, string>>;
+    /** Full override, for hosts with their own fetch wrapper (retries, tracing, mTLS). */
+    fetch?: typeof fetch;
+}
+export declare const DEFAULT_DISCOVERY_PATH = "/__braid/registry";
+export interface RegistryListing {
+    entries: DiscoveryEntry[];
+    total: number;
+    /** True when the gateway is in development mode and skipped access filtering. */
+    unfiltered: boolean;
+    protocolVersion: string;
+}
+/**
+ * Reads a gateway's registry listing, following pagination to the end.
+ *
+ * The listing is what the *caller* may see — the gateway filters by `access.list` — so a console
+ * showing fewer fragments than the operator expects is usually correct and worth surfacing rather
+ * than hiding. {@link RegistryListing.unfiltered} distinguishes "you are seeing everything because
+ * this gateway is in development" from "you are seeing what you are allowed to see".
+ */
+export declare function fetchRegistry(api?: ConsoleApi, signal?: AbortSignal): Promise<RegistryListing>;
+export declare class RegistryFetchError extends Error {
+    readonly url: string;
+    readonly status: number;
+    constructor(url: string, status: number);
+}
+export declare const DEFAULT_API_PATH = "/__braid/registry-api";
+export interface HeadState {
+    id: string | null;
+    snapshot: {
+        id: string;
+        createdAt: string;
+        manifests: FragmentManifest[];
+    } | null;
+}
+export interface PublishOutcome {
+    snapshot: {
+        id: string;
+        createdAt: string;
+        fragmentCount: number;
+    };
+    findings: RegistryFinding[];
+    descriptorNotes: DescriptorNote[];
+    pinned: boolean;
+    diff?: RegistryDiff;
+}
+/** The currently pinned snapshot, or `{ id: null }` when nothing has been published. */
+export declare function fetchHead(api?: ConsoleApi, signal?: AbortSignal): Promise<HeadState>;
+export declare function listSnapshots(api?: ConsoleApi, signal?: AbortSignal): Promise<{
+    items: SnapshotRef[];
+    head: string | null;
+}>;
+/**
+ * Publishes a draft.
+ *
+ * The server re-validates whatever arrives, so a 422 here is not a client bug — it is the
+ * authoritative check disagreeing with the optimistic one, and its findings are what to show.
+ */
+export declare function publishSnapshot(api: ConsoleApi, body: {
+    manifests: FragmentManifest[];
+    labels?: Record<string, string>;
+    pin?: boolean;
+}): Promise<PublishOutcome>;
+/** Re-points HEAD. Rollback is this and nothing else. */
+export declare function pinSnapshot(api: ConsoleApi, id: string): Promise<void>;
+export declare class RegistryApiError extends Error {
+    readonly status: number;
+    readonly findings: RegistryFinding[];
+    readonly descriptorNotes: DescriptorNote[];
+    constructor(message: string, status: number, findings?: RegistryFinding[], descriptorNotes?: DescriptorNote[]);
+}

package/src/lib/client.js

@@ -0,0 +1,109 @@
+export const DEFAULT_DISCOVERY_PATH = '/__braid/registry';
+/**
+ * Reads a gateway's registry listing, following pagination to the end.
+ *
+ * The listing is what the *caller* may see — the gateway filters by `access.list` — so a console
+ * showing fewer fragments than the operator expects is usually correct and worth surfacing rather
+ * than hiding. {@link RegistryListing.unfiltered} distinguishes "you are seeing everything because
+ * this gateway is in development" from "you are seeing what you are allowed to see".
+ */
+export async function fetchRegistry(api = {}, signal) {
+    const doFetch = api.fetch ?? globalThis.fetch;
+    const base = api.baseUrl?.replace(/\/$/, '') ?? '';
+    const path = api.discoveryPath ?? DEFAULT_DISCOVERY_PATH;
+    const entries = [];
+    let page = 1;
+    let last;
+    do {
+        const url = `${base}${path}?page=${page}`;
+        const response = await doFetch(url, {
+            headers: { accept: 'application/json', ...(await resolveHeaders(api)) },
+            ...(signal ? { signal } : {}),
+        });
+        if (!response.ok)
+            throw new RegistryFetchError(url, response.status);
+        last = (await response.json());
+        entries.push(...last.items);
+        page += 1;
+        // guard against a gateway that reports hasMore forever
+    } while (last.hasMore && page <= last.totalPages && page < 1000);
+    return {
+        entries,
+        total: last?.total ?? entries.length,
+        unfiltered: last?.unfiltered === true,
+        protocolVersion: last?.protocolVersion ?? 'unknown',
+    };
+}
+export class RegistryFetchError extends Error {
+    url;
+    status;
+    constructor(url, status) {
+        super(status === 404
+            ? `No registry at ${url}. Discovery is off unless the gateway is configured with it — pass \`discovery\` to createGateway.`
+            : status === 401 || status === 403
+                ? `Not authorized to list the registry at ${url}.`
+                : `Reading the registry at ${url} failed with HTTP ${status}.`);
+        this.url = url;
+        this.status = status;
+        this.name = 'RegistryFetchError';
+    }
+}
+async function resolveHeaders(api) {
+    return api.headers ? await api.headers() : {};
+}
+// ---------------------------------------------------------------------------
+// Write API — only needed for editing
+// ---------------------------------------------------------------------------
+export const DEFAULT_API_PATH = '/__braid/registry-api';
+/** The currently pinned snapshot, or `{ id: null }` when nothing has been published. */
+export async function fetchHead(api = {}, signal) {
+    return apiRequest(api, '/head', { method: 'GET' }, signal);
+}
+export async function listSnapshots(api = {}, signal) {
+    return apiRequest(api, '/snapshots', { method: 'GET' }, signal);
+}
+/**
+ * Publishes a draft.
+ *
+ * The server re-validates whatever arrives, so a 422 here is not a client bug — it is the
+ * authoritative check disagreeing with the optimistic one, and its findings are what to show.
+ */
+export async function publishSnapshot(api, body) {
+    return apiRequest(api, '/snapshots', { method: 'POST', body: JSON.stringify(body) });
+}
+/** Re-points HEAD. Rollback is this and nothing else. */
+export async function pinSnapshot(api, id) {
+    await apiRequest(api, '/head', { method: 'POST', body: JSON.stringify({ id }) });
+}
+export class RegistryApiError extends Error {
+    status;
+    findings;
+    descriptorNotes;
+    constructor(message, status, findings = [], descriptorNotes = []) {
+        super(message);
+        this.status = status;
+        this.findings = findings;
+        this.descriptorNotes = descriptorNotes;
+        this.name = 'RegistryApiError';
+    }
+}
+async function apiRequest(api, route, init, signal) {
+    const doFetch = api.fetch ?? globalThis.fetch;
+    const base = api.baseUrl?.replace(/\/$/, '') ?? '';
+    const url = `${base}${api.apiPath ?? DEFAULT_API_PATH}${route}`;
+    const response = await doFetch(url, {
+        ...init,
+        headers: {
+            accept: 'application/json',
+            ...(init.body ? { 'content-type': 'application/json' } : {}),
+            ...(await resolveHeaders(api)),
+        },
+        ...(signal ? { signal } : {}),
+    });
+    const body = (await response.json().catch(() => ({})));
+    if (!response.ok) {
+        throw new RegistryApiError(typeof body.error === 'string' ? body.error : `HTTP ${response.status} from ${url}`, response.status, body.findings ?? [], body.descriptorNotes ?? []);
+    }
+    return body;
+}
+//# sourceMappingURL=client.js.map