toolcraft 0.0.26 → 0.0.33

package/node_modules/mcp-oauth/dist/client/default-oauth-client-provider.js

@@ -98,7 +98,7 @@ export function createDefaultOAuthClientProvider(options) {
                 while (true) {
                     try {
                         refreshedTokens = await refreshAccessToken({
-                            tokenEndpoint: discovery.authorizationServerMetadata.token_endpoint,
+                            tokenEndpoint: requireOwnString(discovery.authorizationServerMetadata, "token_endpoint", "Authorization server metadata"),
                             clientId: session.client.clientId,
                             clientSecret: session.client.clientSecret,
                             refreshToken: session.tokens.refreshToken,
@@ -184,7 +184,7 @@ export function createDefaultOAuthClientProvider(options) {
                     });
                     const code = await loopback.waitForCode(authorizationUrl);
                     const tokens = await exchangeAuthorizationCode({
-                        tokenEndpoint: discovery.authorizationServerMetadata.token_endpoint,
+                        tokenEndpoint: requireOwnString(discovery.authorizationServerMetadata, "token_endpoint", "Authorization server metadata"),
                         clientId: resolvedClient.client.clientId,
                         clientSecret: resolvedClient.client.clientSecret,
                         code,
@@ -239,7 +239,7 @@ export function createDefaultOAuthClientProvider(options) {
                 },
             };
         }
-        const registrationEndpoint = discovery.authorizationServerMetadata.registration_endpoint;
+        const registrationEndpoint = getOwnString(discovery.authorizationServerMetadata, "registration_endpoint");
         if (registrationEndpoint === undefined && options.client.clientId !== undefined) {
             return {
                 kind: "static",
@@ -290,14 +290,16 @@ export function createDefaultOAuthClientProvider(options) {
             body: JSON.stringify(registrationBody),
         });
         const payload = await readOAuthJsonObjectResponse(response);
-        if (typeof payload.client_id !== "string" ||
-            payload.client_id.trim().length === 0) {
+        const clientId = getOwnString(payload, "client_id");
+        if (clientId === undefined ||
+            clientId.trim().length === 0) {
             throw new Error("OAuth client registration response missing client_id");
         }
+        const clientSecret = getOwnString(payload, "client_secret");
         const registeredClient = {
-            clientId: payload.client_id,
-            clientSecret: typeof payload.client_secret === "string" && payload.client_secret.length > 0
-                ? payload.client_secret
+            clientId,
+            clientSecret: clientSecret !== undefined && clientSecret.length > 0
+                ? clientSecret
                 : undefined,
         };
         await saveRegisteredClient(discovery.authorizationServer, registeredClient);
@@ -324,12 +326,13 @@ export function createDefaultOAuthClientProvider(options) {
             return null;
         }
         const client = await clientStore.load(issuer);
-        if (client !== null && !isUsableClient(client)) {
+        const normalizedClient = client === null ? null : normalizeStoredClient(client);
+        if (client !== null && normalizedClient === null) {
             await clientStore.clear(issuer);
             return null;
         }
-        registeredClients.set(issuer, client);
-        return client;
+        registeredClients.set(issuer, normalizedClient);
+        return normalizedClient;
     }
     async function saveRegisteredClient(issuer, client) {
         registeredClients.set(issuer, client);
@@ -345,7 +348,7 @@ export function createDefaultOAuthClientProvider(options) {
     }
 }
 function isProviderOptions(options) {
-    return "provider" in options;
+    return Object.prototype.hasOwnProperty.call(options, "provider");
 }
 function isExpired(tokens, now) {
     return tokens.expiresAt !== null && tokens.expiresAt <= now();
@@ -361,11 +364,15 @@ function resolveDiscovery(discovery, session) {
         return undefined;
     }
     const metadata = session.discovery.authorizationServerMetadata;
-    if (typeof metadata.issuer !== "string" ||
-        typeof metadata.authorization_endpoint !== "string" ||
-        typeof metadata.token_endpoint !== "string" ||
-        !Array.isArray(metadata.code_challenge_methods_supported) ||
-        !metadata.code_challenge_methods_supported.includes("S256")) {
+    const issuer = getOwnString(metadata, "issuer");
+    const authorizationEndpoint = getOwnString(metadata, "authorization_endpoint");
+    const tokenEndpoint = getOwnString(metadata, "token_endpoint");
+    const codeChallengeMethodsSupported = getOwnStringArray(metadata, "code_challenge_methods_supported");
+    if (issuer === undefined ||
+        authorizationEndpoint === undefined ||
+        tokenEndpoint === undefined ||
+        codeChallengeMethodsSupported === undefined ||
+        !codeChallengeMethodsSupported.includes("S256")) {
         return undefined;
     }
     return {
@@ -389,39 +396,96 @@ function normalizeLoadedSession(session) {
     if (session === null) {
         return null;
     }
-    if (!isUsableClient(session.client)) {
+    const client = normalizeStoredClient(getOwnEntry(session, "client"));
+    if (client === null) {
         return { ...session, client: { clientId: "" }, tokens: undefined };
     }
-    return isUsableTokens(session.tokens)
-        ? session
-        : { ...session, tokens: undefined };
+    return {
+        ...session,
+        client,
+        tokens: normalizeStoredTokens(getOwnEntry(session, "tokens")),
+    };
 }
-function isUsableClient(client) {
-    return (typeof client.clientId === "string"
-        && client.clientId.trim().length > 0
-        && (client.clientSecret === undefined
-            || (typeof client.clientSecret === "string" && client.clientSecret.trim().length > 0)));
+function normalizeStoredClient(value) {
+    if (!isObjectRecord(value)) {
+        return null;
+    }
+    const clientId = getOwnString(value, "clientId");
+    if (clientId === undefined || clientId.trim().length === 0) {
+        return null;
+    }
+    const clientSecret = getOwnEntry(value, "clientSecret");
+    if (clientSecret === undefined) {
+        return { clientId };
+    }
+    if (typeof clientSecret !== "string" || clientSecret.trim().length === 0) {
+        return null;
+    }
+    return { clientId, clientSecret };
 }
-function isUsableTokens(tokens) {
-    if (tokens === undefined) {
-        return true;
-    }
-    return (typeof tokens.accessToken === "string"
-        && tokens.accessToken.trim().length > 0
-        && tokens.tokenType === "Bearer"
-        && (tokens.expiresAt === null || (typeof tokens.expiresAt === "number" && Number.isFinite(tokens.expiresAt)))
-        && (tokens.refreshToken === undefined
-            || (typeof tokens.refreshToken === "string" && tokens.refreshToken.trim().length > 0)));
+function normalizeStoredTokens(value) {
+    if (value === undefined || !isObjectRecord(value)) {
+        return undefined;
+    }
+    const accessToken = getOwnString(value, "accessToken");
+    const tokenType = getOwnString(value, "tokenType");
+    const expiresAt = getOwnEntry(value, "expiresAt");
+    const refreshToken = getOwnEntry(value, "refreshToken");
+    const scope = getOwnString(value, "scope");
+    const normalizedRefreshToken = typeof refreshToken === "string" ? refreshToken : undefined;
+    if (accessToken === undefined ||
+        accessToken.trim().length === 0 ||
+        tokenType !== "Bearer" ||
+        !(expiresAt === null ||
+            (typeof expiresAt === "number" && Number.isFinite(expiresAt))) ||
+        (refreshToken !== undefined &&
+            (typeof refreshToken !== "string" || refreshToken.trim().length === 0))) {
+        return undefined;
+    }
+    return {
+        accessToken,
+        tokenType,
+        expiresAt,
+        ...(normalizedRefreshToken === undefined ? {} : { refreshToken: normalizedRefreshToken }),
+        ...(scope === undefined || scope.length === 0 ? {} : { scope }),
+    };
 }
 function getClientMetadata(client) {
     return client.metadata;
 }
+function getOwnEntry(record, key) {
+    return Object.prototype.hasOwnProperty.call(record, key)
+        ? record[key]
+        : undefined;
+}
+function isObjectRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function getOwnString(record, key) {
+    const value = getOwnEntry(record, key);
+    return typeof value === "string" ? value : undefined;
+}
+function requireOwnString(record, key, label) {
+    const value = getOwnString(record, key);
+    if (value === undefined) {
+        throw new Error(`${label} is missing ${key}`);
+    }
+    return value;
+}
+function getOwnStringArray(record, key) {
+    const value = getOwnEntry(record, key);
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string")
+        ? value
+        : undefined;
+}
 function buildAuthorizationUrl(input) {
-    const url = new URL(input.metadata.authorization_endpoint);
+    const authorizationEndpoint = requireOwnString(input.metadata, "authorization_endpoint", "Authorization server metadata");
+    const issuer = requireOwnString(input.metadata, "issuer", "Authorization server metadata");
+    const url = new URL(authorizationEndpoint);
     const resource = canonicalizeResourceIndicator(input.resource);
     const state = createAuthorizationState({
-        issuer: input.metadata.issuer,
-        requireIssuer: input.metadata.authorization_response_iss_parameter_supported === true,
+        issuer,
+        requireIssuer: getOwnEntry(input.metadata, "authorization_response_iss_parameter_supported") === true,
     });
     url.searchParams.set("response_type", "code");
     url.searchParams.set("client_id", input.clientId);
@@ -436,7 +500,7 @@ function buildAuthorizationUrl(input) {
     return url.toString();
 }
 function assertS256PkceSupport(metadata) {
-    if (!metadata.code_challenge_methods_supported.includes("S256")) {
+    if (!getOwnStringArray(metadata, "code_challenge_methods_supported")?.includes("S256")) {
         throw new Error("Authorization server metadata must advertise code_challenge_methods_supported including S256");
     }
 }
@@ -460,13 +524,16 @@ function assertSecureUrl(value, label) {
     throw new Error(`${label} must use https unless it targets a loopback host`);
 }
 function assertSecureOAuthFlowEndpoints(metadata) {
-    assertNoAccessTokenInUrl(metadata.authorization_endpoint, "Authorization endpoint");
-    assertNoAccessTokenInUrl(metadata.token_endpoint, "Token endpoint");
-    assertSecureUrl(metadata.authorization_endpoint, "Authorization endpoint");
-    assertSecureUrl(metadata.token_endpoint, "Token endpoint");
-    if (metadata.registration_endpoint !== undefined) {
-        assertNoAccessTokenInUrl(metadata.registration_endpoint, "Registration endpoint");
-        assertSecureUrl(metadata.registration_endpoint, "Registration endpoint");
+    const authorizationEndpoint = requireOwnString(metadata, "authorization_endpoint", "Authorization server metadata");
+    const tokenEndpoint = requireOwnString(metadata, "token_endpoint", "Authorization server metadata");
+    const registrationEndpoint = getOwnString(metadata, "registration_endpoint");
+    assertNoAccessTokenInUrl(authorizationEndpoint, "Authorization endpoint");
+    assertNoAccessTokenInUrl(tokenEndpoint, "Token endpoint");
+    assertSecureUrl(authorizationEndpoint, "Authorization endpoint");
+    assertSecureUrl(tokenEndpoint, "Token endpoint");
+    if (registrationEndpoint !== undefined) {
+        assertNoAccessTokenInUrl(registrationEndpoint, "Registration endpoint");
+        assertSecureUrl(registrationEndpoint, "Registration endpoint");
     }
 }
 function assertNoAccessTokenInUrl(value, label) {
@@ -487,17 +554,23 @@ function buildClientRegistrationBody(metadata, redirectUri) {
         response_types: ["code"],
         token_endpoint_auth_method: "none",
     };
-    if (metadata?.clientName !== undefined && metadata.clientName.length > 0) {
-        body.client_name = metadata.clientName;
+    const clientName = metadata === undefined ? undefined : getOwnString(metadata, "clientName");
+    const scope = metadata === undefined ? undefined : getOwnString(metadata, "scope");
+    const softwareId = metadata === undefined ? undefined : getOwnString(metadata, "softwareId");
+    const softwareVersion = metadata === undefined
+        ? undefined
+        : getOwnString(metadata, "softwareVersion");
+    if (clientName !== undefined && clientName.length > 0) {
+        body.client_name = clientName;
     }
-    if (metadata?.scope !== undefined && metadata.scope.length > 0) {
-        body.scope = metadata.scope;
+    if (scope !== undefined && scope.length > 0) {
+        body.scope = scope;
     }
-    if (metadata?.softwareId !== undefined && metadata.softwareId.length > 0) {
-        body.software_id = metadata.softwareId;
+    if (softwareId !== undefined && softwareId.length > 0) {
+        body.software_id = softwareId;
     }
-    if (metadata?.softwareVersion !== undefined && metadata.softwareVersion.length > 0) {
-        body.software_version = metadata.softwareVersion;
+    if (softwareVersion !== undefined && softwareVersion.length > 0) {
+        body.software_version = softwareVersion;
     }
     return body;
 }

package/node_modules/mcp-oauth/dist/client/token-endpoint.js

@@ -75,29 +75,33 @@ async function requestTokens(input) {
         body: body.toString(),
     });
     const payload = await readOAuthJsonObjectResponse(response);
-    if (typeof payload.access_token !== "string" || payload.access_token.trim().length === 0) {
+    const accessToken = getOwnEntry(payload, "access_token");
+    if (typeof accessToken !== "string" || accessToken.trim().length === 0) {
         throw new Error("OAuth token response missing access_token");
     }
-    const tokenType = normalizeBearerTokenType(payload.token_type);
+    const tokenType = normalizeBearerTokenType(getOwnEntry(payload, "token_type"));
     if (tokenType === null) {
         throw new Error("OAuth token response missing token_type=Bearer");
     }
-    if (typeof payload.expires_in === "number"
-        && Number.isFinite(payload.expires_in)
-        && payload.expires_in < 0) {
+    const expiresIn = getOwnEntry(payload, "expires_in");
+    if (typeof expiresIn === "number"
+        && Number.isFinite(expiresIn)
+        && expiresIn < 0) {
         throw new Error("OAuth token response has invalid expires_in");
     }
+    const refreshToken = getOwnEntry(payload, "refresh_token");
+    const scope = getOwnEntry(payload, "scope");
     return {
-        accessToken: payload.access_token,
-        refreshToken: typeof payload.refresh_token === "string" && payload.refresh_token.length > 0
-            ? payload.refresh_token
+        accessToken,
+        refreshToken: typeof refreshToken === "string" && refreshToken.length > 0
+            ? refreshToken
             : undefined,
         tokenType,
-        expiresAt: typeof payload.expires_in === "number" && Number.isFinite(payload.expires_in)
-            ? input.now() + (payload.expires_in * 1000)
+        expiresAt: typeof expiresIn === "number" && Number.isFinite(expiresIn)
+            ? input.now() + (expiresIn * 1000)
             : null,
-        scope: typeof payload.scope === "string" && payload.scope.length > 0
-            ? payload.scope
+        scope: typeof scope === "string" && scope.length > 0
+            ? scope
             : undefined,
     };
 }
@@ -126,16 +130,22 @@ export async function readOAuthJsonObjectResponse(response) {
     return record;
 }
 function readOAuthError(payload, fallbackError = "server_error") {
+    const error = getOwnEntry(payload, "error");
+    const errorDescription = getOwnEntry(payload, "error_description");
+    const errorUri = getOwnEntry(payload, "error_uri");
     return {
-        error: typeof payload.error === "string" ? payload.error : fallbackError,
-        error_description: typeof payload.error_description === "string"
-            ? payload.error_description
+        error: typeof error === "string" ? error : fallbackError,
+        error_description: typeof errorDescription === "string"
+            ? errorDescription
             : undefined,
-        error_uri: typeof payload.error_uri === "string"
-            ? payload.error_uri
+        error_uri: typeof errorUri === "string"
+            ? errorUri
             : undefined,
     };
 }
+function getOwnEntry(record, key) {
+    return Object.prototype.hasOwnProperty.call(record, key) ? record[key] : undefined;
+}
 function createFallbackOAuthError(status) {
     const error = status === 503 ? "temporarily_unavailable" : "server_error";
     return new OAuthError({ error }, status);

package/node_modules/mcp-oauth/dist/server/jwks-token-verifier.js

@@ -26,6 +26,15 @@ function isObjectRecord(value) {
 function isStringArray(value) {
     return Array.isArray(value) && value.every((item) => typeof item === "string");
 }
+function getOwnEntry(record, key) {
+    return Object.prototype.hasOwnProperty.call(record, key)
+        ? record[key]
+        : undefined;
+}
+function getOwnString(record, key) {
+    const value = getOwnEntry(record, key);
+    return typeof value === "string" ? value : undefined;
+}
 function toUrl(value, label) {
     try {
         return new URL(String(value));
@@ -58,10 +67,12 @@ function normalizeVerifiedAudience(value, expectedResource) {
     return [normalizedAudience];
 }
 function parseScopes(payload) {
-    const raw = typeof payload.scope === "string"
-        ? payload.scope
-        : typeof payload.scopes === "string"
-            ? payload.scopes
+    const scope = getOwnString(payload, "scope");
+    const scopes = getOwnEntry(payload, "scopes");
+    const raw = scope !== undefined
+        ? scope
+        : typeof scopes === "string"
+            ? scopes
             : null;
     if (raw !== null) {
         return raw
@@ -69,24 +80,28 @@ function parseScopes(payload) {
             .map((scope) => scope.trim())
             .filter((scope) => scope.length > 0);
     }
-    return isStringArray(payload.scopes) ? [...payload.scopes] : [];
+    return isStringArray(scopes) ? [...scopes] : [];
 }
-function toVerifiedAccessToken(token, payload, audience = normalizeAudience(payload.aud)) {
+function toVerifiedAccessToken(token, payload, audience = normalizeAudience(getOwnEntry(payload, "aud"))) {
+    const issuer = getOwnString(payload, "iss");
+    const expiresAt = getOwnEntry(payload, "exp");
+    const subject = getOwnString(payload, "sub");
+    const clientId = getOwnString(payload, "client_id");
     return {
         token,
-        issuer: typeof payload.iss === "string" ? payload.iss : "",
+        issuer: issuer ?? "",
         audience,
         scopes: parseScopes(payload),
-        expiresAt: typeof payload.exp === "number" ? payload.exp : 0,
+        expiresAt: typeof expiresAt === "number" ? expiresAt : 0,
         claims: { ...payload },
-        ...(typeof payload.sub === "string"
+        ...(subject !== undefined
             ? {
-                subject: payload.sub,
+                subject,
             }
             : {}),
-        ...(typeof payload.client_id === "string"
+        ...(clientId !== undefined
             ? {
-                clientId: payload.client_id,
+                clientId,
             }
             : {}),
     };
@@ -151,14 +166,15 @@ async function loadJwks(jwksUrl, fetchImplementation) {
         throw createInvalidTokenError(`unable to load JWKS (${response.status})`);
     }
     const payload = (await response.json());
-    if (!isObjectRecord(payload) || !Array.isArray(payload.keys)) {
+    const keys = isObjectRecord(payload) ? getOwnEntry(payload, "keys") : undefined;
+    if (!isObjectRecord(payload) || !Array.isArray(keys)) {
         throw createInvalidTokenError("invalid JWKS document");
     }
-    return payload;
+    return { ...payload, keys };
 }
 function resolveAlgorithm(token, allowedAlgorithms) {
     const header = decodeProtectedHeader(token);
-    const alg = header.alg;
+    const alg = getOwnString(header, "alg");
     if (hasCriticalHeaderClaims(header)) {
         throw createInvalidTokenError("unsupported critical token claims");
     }
@@ -171,19 +187,24 @@ function resolveAlgorithm(token, allowedAlgorithms) {
     return alg;
 }
 function hasCriticalHeaderClaims(header) {
-    return Array.isArray(header.crit) && header.crit.length > 0;
+    const criticalClaims = getOwnEntry(header, "crit");
+    return Array.isArray(criticalClaims) && criticalClaims.length > 0;
 }
 function isVerificationCandidate(key, alg, kid) {
-    if (kid !== undefined && key.kid !== kid) {
+    const keyId = getOwnString(key, "kid");
+    const keyAlgorithm = getOwnString(key, "alg");
+    const keyUse = getOwnString(key, "use");
+    const keyOps = getOwnEntry(key, "key_ops");
+    if (kid !== undefined && keyId !== kid) {
         return false;
     }
-    if (typeof key.alg === "string" && key.alg !== alg) {
+    if (keyAlgorithm !== undefined && keyAlgorithm !== alg) {
         return false;
     }
-    if (typeof key.use === "string" && key.use !== "sig") {
+    if (keyUse !== undefined && keyUse !== "sig") {
         return false;
     }
-    if (Array.isArray(key.key_ops) && !key.key_ops.includes("verify")) {
+    if (Array.isArray(keyOps) && !keyOps.includes("verify")) {
         return false;
     }
     return true;
@@ -193,7 +214,7 @@ function shouldContinueWithNextKey(error) {
 }
 async function verifyJwtAgainstJwks(input) {
     const protectedHeader = decodeProtectedHeader(input.token);
-    const kid = typeof protectedHeader.kid === "string" ? protectedHeader.kid : undefined;
+    const kid = getOwnString(protectedHeader, "kid");
     const candidateKeys = input.jwks.keys.filter((key) => isVerificationCandidate(key, input.alg, kid));
     if (candidateKeys.length === 0) {
         throw createInvalidTokenError("token signature invalid");
@@ -239,7 +260,7 @@ export function createJwksTokenVerifier(options) {
                     authorizationServers: input.authorizationServers,
                     clockSkewSeconds,
                 });
-                const audience = normalizeVerifiedAudience(verified.payload.aud, expectedResource);
+                const audience = normalizeVerifiedAudience(getOwnEntry(verified.payload, "aud"), expectedResource);
                 const accessToken = toVerifiedAccessToken(input.token, verified.payload, audience);
                 if (input.requiredScopes.length > 0
                     && !input.requiredScopes.every((scope) => accessToken.scopes.includes(scope))) {

package/node_modules/toolcraft-design/README.md

@@ -0,0 +1,148 @@
+# toolcraft-design
+
+Shared terminal design system for Toolcraft applications. It provides design tokens, ANSI-aware text and layout components, interactive prompts, dashboards, explorers, terminal Markdown rendering, and deterministic static renderers from one package.
+
+## Install
+
+```sh
+npm install toolcraft-design
+```
+
+Import from the package root:
+
+```ts
+import { configureTheme, promptText, renderMarkdown, renderTable, text } from "toolcraft-design";
+```
+
+The package does not expose public subpath imports.
+
+## Public API
+
+### Tokens
+
+- `tokens`: namespace containing the token exports.
+- `brand`: the default purple brand color.
+- `dark`, `light`: built-in purple `ThemePalette` values.
+- `brands`: mutable registry of available brands.
+- `spacing`, `typography`, `widths`: shared design token collections.
+- Types: `Brand`, `ThemeName`, `ThemePalette`.
+
+### Components
+
+- `text`, `color`, `symbols`: text styles, color helpers, and terminal symbols.
+- `createLogger`, `logger`: styled logger creation and the default logger.
+- `helpFormatter`, `helpFormatterPlain`: styled and plain help formatting APIs.
+- `formatColumns`, `formatCommand`, `formatUsage`, `formatOption`, `formatCommandList`, `formatOptionList`: individual help-formatting functions.
+- `formatCommandNotFound`, `formatCommandNotFoundPanel`: command error rendering.
+- `renderTable`, `renderDetailCard`: tabular and detail-card rendering.
+- `getTemplatePartialNames`, `renderTemplate`, `resolveTemplatePartials`: template rendering utilities.
+- `openExternal`: opens a URL or file with the platform browser command.
+- Types: `Color`, `LoggerOutput`, `CommandInfo`, `OptionInfo`, `FormatColumnsOptions`, `TableColumn`, `RenderTableOptions`, `DetailCardRow`, `DetailCardSection`, `RenderDetailCardOptions`, `RenderTemplateOptions`, `TemplateEscape`.
+
+### Prompts
+
+- `prompts`: namespace containing the prompt exports.
+- `intro`, `introPlain`, `outro`, `note`: prompt flow presentation.
+- `select`, `multiselect`, `promptText`, `confirm`, `confirmOrCancel`, `password`: interactive inputs. The prompt text function is exported as `promptText` at the package root and as `text` on `prompts`.
+- `spinner`, `withSpinner`: spinner APIs.
+- `isCancel`, `cancel`, `log`, `PromptCancelledError`: cancellation and prompt logging utilities.
+- `promptTheme`: the brand-aware prompt theme.
+- Types: `SelectOptions`, `MultiselectOptions`, `TextOptions`, `ConfirmOptions`, `PasswordOptions`, `SpinnerOptions`, `WithSpinnerOptions`.
+
+### Dashboard
+
+- `dashboard`: namespace containing the complete dashboard API.
+- `createDashboard`, `shouldUseInteractiveDashboard`: root-level dashboard exports.
+- Root-level types: `Dashboard`, `DashboardOptions`.
+- The namespace also exports `renderDashboardSnapshot`, `defaultHints`, and the dashboard snapshot, state, output, command, statistics, and footer-hint types.
+
+### Explorer
+
+- `explorer`: namespace containing the complete explorer API.
+- `runExplorer`, `singleDetail`: root-level explorer exports.
+- Root-level types: `Row`, `DetailItem`, `Detail`, `DetailCtx`, `Action`, `ActionContext`, `ExplorerConfig`, `ReorderContext`, `Tone`.
+- The namespace also exports `createInitialState`, `resolveBindings`, and the remaining explorer event, binding, layout, size, state, and effect types.
+
+### Terminal Markdown
+
+- `parse`: parses Markdown into `MdNode` values.
+- `render`: renders parsed Markdown nodes for the terminal.
+- `renderMarkdown`: parses and renders a Markdown string.
+- Types: `MdNode`, `RenderOptions`.
+
+### Static Rendering
+
+- `staticRender`: namespace containing the static rendering exports.
+- `SPINNER_FRAMES`, `renderSpinnerFrame`, `renderSpinnerStopped`: deterministic spinner rendering.
+- `renderMenu`: deterministic menu rendering.
+- Types: `SpinnerFrameOptions`, `SpinnerStoppedOptions`, `MenuOption`, `RenderMenuOptions`.
+
+### ACP Rendering
+
+- `acp`: namespace containing `renderAgentMessage`, `renderToolStart`, `renderToolComplete`, `renderReasoning`, `renderUsage`, `renderError`, `getAcpWriter`, and `withAcpWriter`.
+- Namespace type: `AcpLineWriter`.
+
+### Advanced Utilities
+
+- `getTheme`, `resolveThemeName`, `resetThemeCache`: theme resolution and cache control.
+- `configureTheme`, `getThemeConfig`, `resetTheme`: brand and label configuration.
+- `resolveOutputFormat`, `resetOutputFormatCache`, `withOutputFormat`: terminal, Markdown, or JSON output-format selection.
+- Types: `ThemeEnv`, `OutputFormat`.
+
+## Brand Theme
+
+The default configuration is `{ brand: "purple", label: "Poe" }`. Configure the package before producing design-system output:
+
+```ts
+import { configureTheme, getThemeConfig, resetTheme } from "toolcraft-design";
+
+configureTheme({ brand: "blue", label: "Toolcraft" });
+
+console.log(getThemeConfig());
+// { brand: "blue", label: "Toolcraft" }
+
+resetTheme();
+```
+
+`configureTheme` accepts either or both fields and merges them into the current configuration. It throws for an unknown brand. `getThemeConfig` returns a copy of the current configuration, and `resetTheme` restores the purple `Poe` defaults.
+
+The built-in brands are:
+
+- `purple`: `#a200ff`
+- `blue`: `#2f6fed`
+- `green`: `#1f9d57`
+
+Register another brand by adding a `Brand` to the exported `brands` registry before selecting it:
+
+```ts
+import { brands, configureTheme, type Brand } from "toolcraft-design";
+
+const orange: Brand = {
+  name: "orange",
+  primary: "#f97316"
+};
+
+brands.orange = orange;
+configureTheme({ brand: "orange", label: "My CLI" });
+```
+
+The registry key and `Brand.name` should match. Brand primary colors are CSS-style hex strings used to build light and dark terminal palettes.
+
+## Environment Variables
+
+### Theme and Brand
+
+- `POE_CODE_THEME`: forces the rendering mode when set to `light` or `dark`. It takes precedence over `POE_THEME` and automatic terminal theme detection.
+- `POE_THEME`: legacy light/dark override used when `POE_CODE_THEME` is not set to a valid mode.
+- `POE_BRAND`: debug-only built-in or registered brand override. An explicit `configureTheme({ brand })` call takes precedence. Unknown values are ignored.
+- `APPLE_INTERFACE_STYLE`: automatic macOS theme hint used when no valid explicit light/dark override is present.
+- `VSCODE_COLOR_THEME_KIND`: automatic VS Code theme hint used after the macOS hint.
+- `COLORFGBG`: terminal foreground/background hint used after the macOS and VS Code hints. Rendering defaults to dark when no hint resolves a mode.
+
+### Output and Color
+
+- `OUTPUT_FORMAT`: selects `terminal`, `markdown`, or `json` output for components that use the output-format resolver. Invalid or missing values default to `terminal`.
+- `FORCE_COLOR`: enables color when present and not `0`, taking precedence over `NO_COLOR`.
+- `NO_COLOR`: disables color when `FORCE_COLOR` does not enable it.
+- `TERM`: participates in color support detection; an unset or `dumb` terminal disables color unless forced.
+- `POE_NO_SPINNER`: uses non-animated spinner behavior when set to `1`.