akanjs 3.0.0-alpha.7 → 3.0.0-alpha.71

package/ui/Signal/RestApi.tsx

@@ -1,20 +1,22 @@
 "use client";
 import { PrimitiveRegistry } from "akanjs/base";
-import { usePage } from "akanjs/client";
+import { cn, usePage } from "akanjs/client";
+import { mcpHintsOf, mcpRefusalOf } from "akanjs/common";
 import { type ConstantCls, ConstantRegistry } from "akanjs/constant";
 import { FetchClient, type FetchProxy } from "akanjs/fetch";
 import type { SerializedEndpoint } from "akanjs/signal";
 import { st } from "akanjs/store";
-import { useMemo, useState } from "react";
-import { AiOutlineApi, AiOutlineCopy, AiOutlineFileWord, AiOutlineSend } from "react-icons/ai";
+import { type ReactNode, useMemo, useState } from "react";
+import { AiOutlineApi, AiOutlineCopy, AiOutlineFileWord, AiOutlineSend, AiOutlineWarning } from "react-icons/ai";
 import { buttonRecipe } from "../Button";
 import { Copy } from "../Copy";
+import { Collapse, dictText, docPill, docUi, Panel, Segmented } from "../Reference";
 import { Signal } from ".";
 import Arg from "./Arg";
-import { SignalCollapse } from "./Collapse";
+import { endpointEntriesOf, guardsOf, isWsEndpoint, matchesGuards, matchesSearch } from "./endpointEntries";
 import { getExampleData } from "./makeExample";
 import Response from "./Response";
-import { getEndpointBadgeClassName, getGuardBadgeClassName, signalUi } from "./style";
+import { getGuardBadgeClassName, getMcpBadgeClassName, getMethodBadgeClassName, getMethodLabel } from "./style";
 
 type RestApiFetchFn = (
   ...args: [...args: unknown[], option: { token?: string; crystalize?: boolean }]
@@ -24,6 +26,22 @@ export default function RestApi() {
   return <div></div>;
 }
 
+const restViewItems = [
+  { key: "doc", label: "Reference", icon: <AiOutlineFileWord /> },
+  { key: "test", label: "Try it", icon: <AiOutlineApi /> },
+] as const;
+
+interface ArgSectionProps {
+  label: string;
+  children: ReactNode;
+}
+const ArgSection = ({ label, children }: ArgSectionProps) => (
+  <div className="flex flex-col gap-2">
+    <div className={docUi.sectionLabel}>{label}</div>
+    {children}
+  </div>
+);
+
 interface RestApiEndpointsProps {
   refName: string;
   fetch: FetchProxy;
@@ -31,45 +49,34 @@ interface RestApiEndpointsProps {
   endpoints?: string[];
   openAll?: boolean;
   httpUri?: string;
+  search?: string;
 }
-const RestApiEndpoints = ({ refName, fetch, prefix, endpoints, openAll, httpUri }: RestApiEndpointsProps) => {
-  const tryRoles = st.use.tryRoles();
+const RestApiEndpoints = ({ refName, fetch, prefix, endpoints, openAll, httpUri, search }: RestApiEndpointsProps) => {
+  const tryGuards = st.use.tryGuards({ agent: false });
   const signal = fetch.serializedSignal[refName];
+  if (!signal) return <div className={docUi.emptyPanel}>No signal is registered as “{refName}”.</div>;
   const signalPrefix = prefix ?? signal.prefix;
-  const baseEndpointEntries = Object.entries(FetchClient.getBaseEndpoint(refName, signal));
-  const sliceEndpointEntries = signal.slice
-    ? Object.entries(signal.slice).flatMap(([suffix, slice]) => {
-        const endpoint = FetchClient.getEndpointFromSlice(refName, suffix, slice);
-        return Object.entries(endpoint);
-      })
-    : [];
-  const endpointEntries = [...baseEndpointEntries, ...sliceEndpointEntries, ...Object.entries(signal.endpoint)]
-    .filter(([key, endpoint]) => !endpoints || endpoints.includes(key))
-    .sort(([keyA], [keyB]) => (keyA > keyB ? 1 : -1))
-    .filter(([key, endpoint]) => {
-      if (endpoint.type === "pubsub" || endpoint.type === "message") return false;
-      if (!endpoint.guards?.length) return true;
-      if (endpoint.guards?.includes("Public") && tryRoles.includes("Public")) return true;
-      if ((endpoint.guards?.includes("User") || endpoint.guards?.includes("Every")) && tryRoles.includes("User"))
-        return true;
-      if ((endpoint.guards?.includes("Admin") || endpoint.guards?.includes("Every")) && tryRoles.includes("Admin"))
-        return true;
-      if (
-        (endpoint.guards?.includes("SuperAdmin") || endpoint.guards?.includes("Every")) &&
-        tryRoles.includes("SuperAdmin")
-      )
-        return true;
-      return false;
-    });
+  const endpointEntries = endpointEntriesOf(refName, fetch)
+    .filter(({ key }) => !endpoints || endpoints.includes(key))
+    .filter(({ key, endpoint }) =>
+      matchesSearch(key, FetchClient.makeHttpUrl(key, endpoint, signalPrefix, new Map()), search ?? ""),
+    )
+    .filter(({ endpoint }) => !isWsEndpoint(endpoint) && matchesGuards(endpoint, tryGuards));
+  if (!endpointEntries.length)
+    return (
+      <div className={docUi.emptyPanel}>
+        {search?.trim() ? `No endpoint matches “${search.trim()}”.` : "No endpoint is gated by the selected guards."}
+      </div>
+    );
   return (
-    <div>
-      {endpointEntries.map(([endpointKey, endpoint], idx) => (
+    <div className="flex flex-col gap-2">
+      {endpointEntries.map(({ key, endpoint }) => (
         <RestApiEndpoint
-          key={endpointKey}
+          key={key}
           signalPrefix={signalPrefix}
           refName={refName}
           fetch={fetch}
-          endpointKey={endpointKey}
+          endpointKey={key}
           endpoint={endpoint}
           open={openAll}
           httpUri={httpUri}
@@ -102,73 +109,62 @@ const RestApiEndpoint = ({
   const { l } = usePage();
   const [viewStatus, setViewStatus] = useState<"doc" | "test">("doc");
   const path = FetchClient.makeHttpUrl(endpointKey, endpoint, signalPrefix, new Map());
+
+  const mcpRefusal = mcpRefusalOf(endpoint, { refName, key: endpointKey });
+  const guards = guardsOf(endpoint);
+  const label = dictText(l, `${refName}.signal.${endpointKey}`);
+  const desc = dictText(l, `${refName}.signal.${endpointKey}.desc`);
+  const hints = Object.entries(mcpHintsOf(endpointKey, endpoint)).filter(([, on]) => on);
   return (
-    <SignalCollapse
+    <Collapse
       open={open}
-      contentClassName="bg-background/60"
       summary={
-        <div className="flex flex-wrap items-center gap-2">
-          <div className={getEndpointBadgeClassName(endpoint.type)}>{endpoint.type === "query" ? "GET" : "POST"}</div>
-          <div className="font-bold text-lg">{path}</div>
-          <div className="text-foreground/70 text-sm">{l._(`${refName}.signal.${endpointKey}`)}</div>
-        </div>
-      }
-    >
-      <div>
-        <div className="rounded-xl bg-background p-3">
-          <div className={signalUi.sectionTitle}>Description</div>
-          {endpoint.guards?.some((guard) => guard !== "None") ? (
-            <div className="mt-2 flex flex-wrap items-center gap-2 font-normal text-sm">
-              <span className="text-foreground/70">Guards</span>
-              {endpoint.guards.map((guard) => (
+        <div className="flex min-w-0 flex-col gap-1.5">
+          <div className="flex flex-wrap items-center gap-2">
+            <span className={getMethodBadgeClassName(endpoint.type)}>{getMethodLabel(endpoint.type)}</span>
+            <span className="break-all font-medium font-mono text-sm">{path}</span>
+            <span className="ml-auto flex flex-wrap items-center gap-1.5">
+              {guards.map((guard) => (
                 <span className={getGuardBadgeClassName(guard)} key={guard}>
                   {guard}
                 </span>
               ))}
-            </div>
-          ) : null}
-          <div className="mt-2 font-normal text-foreground/70 text-sm">
-            {l._(`${refName}.signal.${endpointKey}.desc`)}
+              <span className={getMcpBadgeClassName(!mcpRefusal)}>{mcpRefusal ? "MCP refused" : "MCP"}</span>
+            </span>
           </div>
+          {label ? <div className="text-foreground/55 text-sm">{label}</div> : null}
         </div>
-        <div className="inline-flex w-fit overflow-hidden rounded-field">
-          <button
-            onClick={() => {
-              setViewStatus("doc");
-            }}
-            className={buttonRecipe(
-              { variant: viewStatus === "doc" ? "primary" : "outline", size: "sm" },
-              "rounded-none",
-            )}
-          >
-            <AiOutlineFileWord className="text-xl" /> View Doc
-          </button>
-          <button
-            onClick={() => {
-              setViewStatus("test");
-            }}
-            className={buttonRecipe(
-              { variant: viewStatus === "test" ? "primary" : "outline", size: "sm" },
-              "rounded-none",
-            )}
-          >
-            <AiOutlineApi className="text-xl" /> Restful API
-          </button>
+      }
+    >
+      {desc ? <p className={docUi.prose}>{desc}</p> : null}
+      {mcpRefusal ? (
+        <div className="flex items-start gap-2 rounded-box border border-warning/30 bg-warning/10 p-3 text-sm text-warning">
+          <AiOutlineWarning className="mt-0.5 shrink-0" />
+          <span>{mcpRefusal}</span>
         </div>
-        {viewStatus === "doc" ? (
-          <RestApiInterface refName={refName} endpointKey={endpointKey} endpoint={endpoint} />
-        ) : (
-          <RestApiTry
-            signalPrefix={signalPrefix}
-            fetch={fetch}
-            refName={refName}
-            endpointKey={endpointKey}
-            endpoint={endpoint}
-            httpUri={httpUri}
-          />
-        )}
-      </div>
-    </SignalCollapse>
+      ) : hints.length ? (
+        <div className="flex flex-wrap items-center gap-1.5">
+          {hints.map(([hint]) => (
+            <span className={docPill("muted")} key={hint}>
+              {hint}
+            </span>
+          ))}
+        </div>
+      ) : null}
+      <Segmented items={restViewItems} onChange={setViewStatus} value={viewStatus} />
+      {viewStatus === "doc" ? (
+        <RestApiInterface refName={refName} endpointKey={endpointKey} endpoint={endpoint} />
+      ) : (
+        <RestApiTry
+          signalPrefix={signalPrefix}
+          fetch={fetch}
+          refName={refName}
+          endpointKey={endpointKey}
+          endpoint={endpoint}
+          httpUri={httpUri}
+        />
+      )}
+    </Collapse>
   );
 };
 RestApi.Endpoint = RestApiEndpoint;
@@ -181,58 +177,31 @@ interface RestApiInterfaceProps {
 const RestApiInterface = ({ refName, endpointKey, endpoint }: RestApiInterfaceProps) => {
   const returnRef = ConstantRegistry.getModelRef(endpoint.returns.refName, endpoint.returns.modelType);
   const isReturnModelType = !PrimitiveRegistry.has(returnRef);
-  const uploadArgs = endpoint.args.filter((arg) => arg.type === "upload");
-  const paramArgs = endpoint.args.filter((arg) => arg.type === "param");
-  const searchArgs = endpoint.args.filter((arg) => arg.type === "search");
-  const bodyArgs = endpoint.args.filter((arg) => arg.type === "body");
+  const argSections = [
+    { label: "Form data", args: endpoint.args.filter((arg) => arg.type === "upload") },
+    { label: "Path parameters", args: endpoint.args.filter((arg) => arg.type === "param") },
+    { label: "Query", args: endpoint.args.filter((arg) => arg.type === "search") },
+    { label: "Body", args: endpoint.args.filter((arg) => arg.type === "body") },
+  ].filter((section) => section.args.length);
   return (
     <div className="flex w-full flex-col gap-4">
-      {uploadArgs.length ? (
-        <div>
-          <div className={signalUi.sectionTitle}>Form data upload</div>
-          <div className={signalUi.tablePanel}>
-            <Arg.Table refName={refName} endpointKey={endpointKey} args={uploadArgs} />
+      {argSections.map((section) => (
+        <ArgSection key={section.label} label={section.label}>
+          <div className={docUi.tablePanel}>
+            <Arg.Table refName={refName} endpointKey={endpointKey} args={section.args} />
           </div>
-        </div>
-      ) : null}
-      {paramArgs.length ? (
-        <div>
-          <div className={signalUi.sectionTitle}>Parameters</div>
-          <div className={signalUi.tablePanel}>
-            <Arg.Table refName={refName} endpointKey={endpointKey} args={paramArgs} />
-          </div>
-        </div>
-      ) : null}
-      {searchArgs.length ? (
-        <div>
-          <div className={signalUi.sectionTitle}>Query</div>
-          <div className={signalUi.tablePanel}>
-            <Arg.Table refName={refName} endpointKey={endpointKey} args={searchArgs} />
-          </div>
-        </div>
-      ) : null}
-      {bodyArgs.length ? (
-        <div>
-          <div className={signalUi.sectionTitle}>Body</div>
-          <div className={signalUi.tablePanel}>
-            <Arg.Table refName={refName} endpointKey={endpointKey} args={bodyArgs} />
-          </div>
-        </div>
-      ) : null}
-      <div className="font-bold text-lg">
-        <div className="flex w-full flex-col gap-2 rounded-md font-normal md:flex-row">
-          <div className="w-full md:w-1/2">
-            <div className={signalUi.sectionTitle}>Response Type</div>
-            <div className="max-h-72 overflow-auto rounded-xl bg-background p-4 md:h-72">
-              Returns: <Signal.Object.Type objRef={returnRef} arrDepth={endpoint.returns.arrDepth ?? 0} />
-              {isReturnModelType ? <Signal.Object.Detail objRef={returnRef as ConstantCls} /> : null}
-            </div>
-          </div>
-          <div className="w-full md:w-1/2">
-            <div className={signalUi.sectionTitle}>Response Example</div>
-            <Response.Example endpoint={endpoint} />
+        </ArgSection>
+      ))}
+      <div className="grid gap-3 md:grid-cols-2 md:items-start">
+        <Panel bodyClassName="max-h-none" label="Returns">
+          <div className="flex flex-col items-start gap-3">
+            <Signal.Object.Type objRef={returnRef} arrDepth={endpoint.returns.arrDepth ?? 0} />
+            {isReturnModelType ? (
+              <Signal.Object.Detail className="w-full border-0 bg-transparent" objRef={returnRef as ConstantCls} />
+            ) : null}
           </div>
-        </div>
+        </Panel>
+        <Response.Example endpoint={endpoint} />
       </div>
     </div>
   );
@@ -252,7 +221,7 @@ const RestApiTry = ({ signalPrefix, refName, endpointKey, endpoint, fetch, httpU
   const paramArgs = endpoint.args.filter((arg) => arg.type === "param");
   const bodyArgs = endpoint.args.filter((arg) => arg.type === "body");
   const uploadArgs = endpoint.args.filter((arg) => arg.type === "upload");
-  const tryJwt = st.use.tryJwt();
+  const tryJwt = st.use.tryJwt({ agent: false });
   const paramExample = useMemo(() => getExampleData<string>(paramArgs, "restapi"), []);
   const queryExample = useMemo(() => getExampleData<string>(queryArgs, "restapi"), []);
   const bodyExample = useMemo(() => JSON.stringify(getExampleData(bodyArgs, "restapi"), null, 2), []);
@@ -307,77 +276,78 @@ const RestApiTry = ({ signalPrefix, refName, endpointKey, endpoint, fetch, httpU
   };
   return (
     <div className="flex w-full flex-col gap-4">
-      <div className="flex flex-wrap items-center gap-2 rounded-xl bg-background p-3">
-        <div className={signalUi.sectionTitle}>Request URL</div>
+      <div className="flex flex-wrap items-center gap-2 rounded-box border border-border bg-background px-3 py-2">
+        <span className={getMethodBadgeClassName(endpoint.type)}>{getMethodLabel(endpoint.type)}</span>
+        <span className="min-w-0 flex-1 break-all font-mono text-foreground/80 text-sm">
+          {httpUri ?? ""}
+          {requestPath}
+        </span>
         <Copy text={`${httpUri ?? ""}${requestPath}`}>
-          <button className={buttonRecipe({ variant: "outline", size: "sm" })}>
-            {requestPath} <AiOutlineCopy />
+          <button className={buttonRecipe({ variant: "ghost", size: "xs" }, "text-foreground/50")} type="button">
+            <AiOutlineCopy />
           </button>
         </Copy>
       </div>
       {uploadArgs.length ? (
-        <div>
-          <div className={signalUi.sectionTitle}>Form data upload</div>
-          {uploadArgs.map((arg) => (
-            <Arg.FormData
-              key={arg.name}
-              endpointKey={endpointKey}
-              arg={arg}
-              value={""}
-              onChange={(fileList: FileList) => {
-                setUploadRequest({ ...uploadRequest, [arg.name]: fileList });
-              }}
-            />
-          ))}
-        </div>
+        <ArgSection label="Form data">
+          <div className={docUi.panel}>
+            {uploadArgs.map((arg) => (
+              <Arg.FormData
+                key={arg.name}
+                endpointKey={endpointKey}
+                arg={arg}
+                value={""}
+                onChange={(fileList: FileList) => {
+                  setUploadRequest({ ...uploadRequest, [arg.name]: fileList });
+                }}
+              />
+            ))}
+          </div>
+        </ArgSection>
       ) : null}
       {paramArgs.length ? (
-        <div className={signalUi.sectionPanel}>
-          <div className={signalUi.sectionTitle}>Parameters</div>
-          {paramArgs.map((arg, idx) => (
-            <Arg.Param
-              key={idx}
-              endpointKey={endpointKey}
-              arg={arg}
-              value={paramRequest[arg.name]}
-              onChange={(value: string) => {
-                setParamRequest({ ...paramRequest, [arg.name]: value });
-              }}
-            />
-          ))}
-        </div>
+        <ArgSection label="Path parameters">
+          <div className={cn(docUi.panel, "px-3 py-1")}>
+            {paramArgs.map((arg, idx) => (
+              <Arg.Param
+                key={idx}
+                endpointKey={endpointKey}
+                arg={arg}
+                value={paramRequest[arg.name]}
+                onChange={(value: string) => {
+                  setParamRequest({ ...paramRequest, [arg.name]: value });
+                }}
+              />
+            ))}
+          </div>
+        </ArgSection>
       ) : null}
       {queryArgs.length ? (
-        <div className={signalUi.sectionPanel}>
-          <div className={signalUi.sectionTitle}>Queries</div>
-          {queryArgs.map((arg, idx) => (
-            <Arg.Query
-              key={idx}
-              endpointKey={endpointKey}
-              arg={arg}
-              value={queryRequest[arg.name] ?? ""}
-              onChange={(value: string) => {
-                setQueryRequest({ ...queryRequest, [arg.name]: value });
-              }}
-            />
-          ))}
-        </div>
+        <ArgSection label="Query">
+          <div className={cn(docUi.panel, "px-3 py-1")}>
+            {queryArgs.map((arg, idx) => (
+              <Arg.Query
+                key={idx}
+                endpointKey={endpointKey}
+                arg={arg}
+                value={queryRequest[arg.name] ?? ""}
+                onChange={(value: string) => {
+                  setQueryRequest({ ...queryRequest, [arg.name]: value });
+                }}
+              />
+            ))}
+          </div>
+        </ArgSection>
       ) : null}
       {bodyArgs.length ? (
-        <div>
-          <div className={signalUi.sectionTitle}>Body</div>
+        <ArgSection label="Body">
           <Arg.Json value={bodyRequest} onChange={setBodyRequest} />
-        </div>
+        </ArgSection>
       ) : null}
-      <div>
-        <button className={buttonRecipe({ variant: "primary" }, "w-full")} onClick={() => void onSend()}>
-          <AiOutlineSend className="-mt-0.5" /> Send Request
-        </button>
-      </div>
-      <div>
-        <div className={signalUi.sectionTitle}>Response</div>
-        <Response.Result status={response.status} data={response.data as object} />
-      </div>
+      <button className={buttonRecipe({ variant: "primary" }, "w-full")} onClick={() => void onSend()} type="button">
+        <AiOutlineSend /> Send Request
+      </button>
+      <Response.Result status={response.status} data={response.data as object} />
     </div>
   );
 };

package/ui/Signal/WebSocket.tsx

@@ -1,5 +1,8 @@
 "use client";
 import type { FetchProxy } from "akanjs/fetch";
+import { st } from "akanjs/store";
+import { docUi } from "../Reference";
+import { endpointEntriesOf, isWsEndpoint, matchesGuards, matchesSearch } from "./endpointEntries";
 import Message from "./Message";
 import PubSub from "./PubSub";
 
@@ -11,36 +14,36 @@ interface WebSocketEndpointsProps {
   refName: string;
   fetch: FetchProxy;
   openAll?: boolean;
+  search?: string;
 }
-const WebSocketEndpoints = ({ refName, fetch, openAll }: WebSocketEndpointsProps) => {
-  const signal = fetch.serializedSignal[refName];
+const WebSocketEndpoints = ({ refName, fetch, openAll, search }: WebSocketEndpointsProps) => {
+  const tryGuards = st.use.tryGuards({ agent: false });
+  if (!fetch.serializedSignal[refName])
+    return <div className={docUi.emptyPanel}>No signal is registered as “{refName}”.</div>;
+  const wsEntries = endpointEntriesOf(refName, fetch).filter(({ endpoint }) => isWsEndpoint(endpoint));
   
-  const endpointEntries = Object.entries(signal.endpoint)
-    .sort(([keyA], [keyB]) => (keyA > keyB ? 1 : -1))
-    .filter(([key, endpoint]) => {
-      if (endpoint.type === "query" || endpoint.type === "mutation") return false;
-
-      return false;
-    });
+  const endpointEntries = wsEntries
+    .filter(({ endpoint }) => matchesGuards(endpoint, tryGuards))
+    .filter(({ key }) => matchesSearch(key, key, search ?? ""));
+  if (!endpointEntries.length)
+    return (
+      <div className={docUi.emptyPanel}>
+        {!wsEntries.length
+          ? "This signal declares no websocket endpoint."
+          : search?.trim()
+            ? `No endpoint matches “${search.trim()}”.`
+            : "No websocket endpoint is gated by the selected guards."}
+      </div>
+    );
   return (
     <div className="flex flex-col gap-2">
-      {endpointEntries.map(([endpointKey, endpoint], idx) => {
-        if (endpoint.type === "pubsub") {
-          return (
-            <PubSub.Endpoint key={idx} refName={refName} endpointKey={endpointKey} endpoint={endpoint} open={openAll} />
-          );
-        } else {
-          return (
-            <Message.Endpoint
-              key={idx}
-              refName={refName}
-              endpointKey={endpointKey}
-              endpoint={endpoint}
-              open={openAll}
-            />
-          );
-        }
-      })}
+      {endpointEntries.map(({ key, endpoint }) =>
+        endpoint.type === "pubsub" ? (
+          <PubSub.Endpoint key={key} refName={refName} endpointKey={key} endpoint={endpoint} open={openAll} />
+        ) : (
+          <Message.Endpoint key={key} refName={refName} endpointKey={key} endpoint={endpoint} open={openAll} />
+        ),
+      )}
     </div>
   );
 };

package/ui/Signal/endpointEntries.ts

@@ -0,0 +1,59 @@
+import { FetchClient, type FetchProxy } from "akanjs/fetch";
+import type { SerializedEndpoint } from "akanjs/signal";
+
+export interface EndpointEntry {
+  key: string;
+  endpoint: SerializedEndpoint;
+}
+
+export const isWsEndpoint = (endpoint: SerializedEndpoint) => endpoint.type === "pubsub" || endpoint.type === "message";
+
+/** Generated CRUD, slice reads, and hand-written endpoints in one list — what the summary counts and the list share. */
+export const endpointEntriesOf = (refName: string, fetch: FetchProxy): EndpointEntry[] => {
+  const signal = fetch.serializedSignal[refName];
+  if (!signal) return [];
+  const base = Object.entries(FetchClient.getBaseEndpoint(refName, signal));
+  const slices = Object.entries(signal.slice ?? {}).flatMap(([suffix, slice]) =>
+    Object.entries(FetchClient.getEndpointFromSlice(refName, suffix, slice)),
+  );
+  const custom = Object.entries(signal.endpoint);
+  return [...base, ...slices, ...custom]
+    .map(([key, endpoint]) => ({ key, endpoint }))
+    .sort((a, b) => (a.key > b.key ? 1 : -1));
+};
+
+export const matchesSearch = (key: string, path: string, search: string) => {
+  const text = search.trim().toLowerCase();
+  if (!text) return true;
+  return key.toLowerCase().includes(text) || path.toLowerCase().includes(text);
+};
+
+/** `None` refuses every caller and is never badged, so it is not a name anyone filters by either. */
+export const guardsOf = (endpoint: SerializedEndpoint) => endpoint.guards?.filter((guard) => guard !== "None") ?? [];
+
+/** Naming no guard is `Public` spelled by omission — both are reachable by every caller, so the filter reads them
+ *  as the same thing even though only the explicit one carries a badge. */
+export const isPublicEndpoint = (endpoint: SerializedEndpoint) => {
+  const guards = guardsOf(endpoint);
+  return !guards.length || guards.every((guard) => guard === "Public");
+};
+
+/** Every guard name the serialized signals declare — the app's own authorization vocabulary, not a fixed role list. */
+export const guardNamesOf = (fetch: FetchProxy) => {
+  const names = new Set<string>();
+  for (const refName of Object.keys(fetch.serializedSignal))
+    for (const { endpoint } of endpointEntriesOf(refName, fetch)) {
+
+      if (isPublicEndpoint(endpoint)) names.add("Public");
+      for (const guard of guardsOf(endpoint)) names.add(guard);
+    }
+  return [...names].sort((a, b) => (a > b ? 1 : -1));
+};
+
+/** No selection is no filter, and a selection is a claim about the guard list — so a public endpoint answers to
+ *  `Public` alone rather than surviving every other filter. */
+export const matchesGuards = (endpoint: SerializedEndpoint, selected: string[]) => {
+  if (!selected.length) return true;
+  if (isPublicEndpoint(endpoint)) return selected.includes("Public");
+  return guardsOf(endpoint).some((guard) => selected.includes(guard));
+};

package/ui/Signal/makeExample.ts

@@ -8,10 +8,15 @@ import {
   PrimitiveRegistry,
   type PrimitiveScalar,
 } from "akanjs/base";
-import { type ConstantCls, ConstantRegistry } from "akanjs/constant";
+import { type ConstantCls, type ConstantField, ConstantRegistry } from "akanjs/constant";
 
 import type { SerializedArg, SerializedEndpoint, SignalType } from "akanjs/signal";
 
+const getMapExample = (field: ConstantField, getValueExample: (modelRef: Cls) => unknown) => {
+  const [valueRef, valueArrDepth] = getNonArrayModel(field.of as Cls);
+  return { key: arraiedModel(getValueExample(valueRef as Cls), valueArrDepth) };
+};
+
 const getResponseExample = (ref: Cls | Cls[]) => {
   const [modelRef, arrDepth] = getNonArrayModel(ref);
   const isPrimitive = PrimitiveRegistry.has(modelRef);
@@ -21,6 +26,7 @@ const getResponseExample = (ref: Cls | Cls[]) => {
   Object.entries((modelRef as ConstantCls)[FIELD_META]).forEach(([key, field]) => {
     if (field.example) example[key] = field.example as unknown;
     else if (field.enum) example[key] = arraiedModel<string>(field.enum.values[0] as string, field.arrDepth);
+    else if (field.isMap) example[key] = getMapExample(field, getResponseExample);
     else example[key] = getResponseExample(field.modelRef);
   });
   const result = arraiedModel(example, arrDepth);
@@ -33,11 +39,12 @@ const getRequestExample = (modelRef: Cls) => {
   if (isPrimitive) return (modelRef as typeof PrimitiveScalar)[EXAMPLE_VALUE];
   else {
     Object.entries((modelRef as ConstantCls)[FIELD_META]).forEach(([key, field]) => {
-      if (!field.isScalar && field.isClass) example[key] = "ObjectID";
+      if (field.isMap) example[key] = getMapExample(field, getRequestExample);
+      else if (!field.isScalar && field.isClass) example[key] = "ObjectID";
       else
         example[key] = (
           (field.example ?? field.enum)
-            ? arraiedModel(field.example ?? (field.enum?.values as string[])[0], field.optArrDepth)
+            ? arraiedModel(field.example ?? field.enum?.values[0], field.optArrDepth)
             : arraiedModel(getRequestExample(field.modelRef), field.arrDepth)
         ) as unknown;
     });