@fgv/ts-app-shell 5.1.0-1

package/dist/packlets/url-sync/useUrlSync.js

@@ -0,0 +1,157 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+/**
+ * Generic URL hash synchronization for two-tier mode/tab navigation.
+ *
+ * Encodes mode + tab in the URL hash: `#/{mode}/{tab}`
+ * Syncs bidirectionally between application state and the URL.
+ * Handles browser back/forward via popstate.
+ *
+ * @packageDocumentation
+ */
+import { useEffect, useRef } from 'react';
+/**
+ * Encodes mode + tab into a URL hash string.
+ * @param mode - The current mode
+ * @param tab - The current tab
+ * @returns Hash string (e.g., '#/library/ingredients')
+ * @public
+ */
+export function encodeUrlHash(mode, tab) {
+    return `#/${mode}/${tab}`;
+}
+/**
+ * Parses a URL hash string into mode + tab, validated against the config.
+ * Returns undefined if the hash is invalid or empty.
+ * @param hash - The hash string (with or without leading '#')
+ * @param config - Validation configuration
+ * @returns Parsed mode and tab, or undefined
+ * @public
+ */
+export function parseUrlHash(hash, config) {
+    const cleaned = hash.replace(/^#\/?/, '');
+    if (cleaned.length === 0) {
+        return undefined;
+    }
+    const parts = cleaned.split('/');
+    if (parts.length < 1) {
+        return undefined;
+    }
+    const mode = parts[0];
+    if (!config.validModes.includes(mode)) {
+        return undefined;
+    }
+    const validTabs = config.validTabs[mode];
+    if (parts.length >= 2) {
+        const tab = parts[1];
+        if (validTabs.includes(tab)) {
+            return { mode, tab };
+        }
+    }
+    // Valid mode but no valid tab — use default
+    return { mode, tab: config.defaultTabs[mode] };
+}
+// ============================================================================
+// URL Sync Hook
+// ============================================================================
+/**
+ * Hook that synchronizes two-tier mode/tab navigation state with the URL hash.
+ *
+ * - On mount: reads the URL hash and applies it to the store
+ * - On state change: updates the URL hash (pushes history entry)
+ * - On popstate (back/forward): reads the URL hash and applies it to the store
+ *
+ * Should be called once at the app root level.
+ *
+ * @param config - Validation configuration (modes, tabs, defaults)
+ * @param state - Current navigation state
+ * @param callbacks - State mutation callbacks
+ * @public
+ */
+export function useUrlSync(config, state, callbacks) {
+    const { mode, activeTab } = state;
+    const { setMode, setTab } = callbacks;
+    // Track whether we're currently applying a URL change to avoid circular updates
+    const isApplyingUrl = useRef(false);
+    // Track whether we've done the initial load
+    const initialized = useRef(false);
+    // Keep refs to the latest values so the mount effect captures them without
+    // needing them in its dependency array (the effect must only run once).
+    const configRef = useRef(config);
+    configRef.current = config;
+    const modeRef = useRef(mode);
+    modeRef.current = mode;
+    const activeTabRef = useRef(activeTab);
+    activeTabRef.current = activeTab;
+    const setModeRef = useRef(setMode);
+    setModeRef.current = setMode;
+    const setTabRef = useRef(setTab);
+    setTabRef.current = setTab;
+    // ---- Initial load: URL → store ----
+    useEffect(() => {
+        if (initialized.current) {
+            return;
+        }
+        initialized.current = true;
+        const parsed = parseUrlHash(window.location.hash, configRef.current);
+        if (parsed) {
+            isApplyingUrl.current = true;
+            setModeRef.current(parsed.mode);
+            setTabRef.current(parsed.tab);
+            isApplyingUrl.current = false;
+        }
+        else {
+            // No valid hash — write current state to URL
+            const hash = encodeUrlHash(modeRef.current, activeTabRef.current);
+            window.history.replaceState(null, '', hash);
+        }
+        // Intentionally empty: this effect must run exactly once on mount.
+        // All values are accessed via refs to avoid stale closures.
+    }, []);
+    // ---- Store → URL: push history on navigation changes ----
+    useEffect(() => {
+        if (isApplyingUrl.current) {
+            return;
+        }
+        const hash = encodeUrlHash(mode, activeTab);
+        if (window.location.hash !== hash) {
+            window.history.pushState(null, '', hash);
+        }
+    }, [mode, activeTab]);
+    // ---- URL → store: handle popstate (back/forward) ----
+    useEffect(() => {
+        const handlePopState = () => {
+            const parsed = parseUrlHash(window.location.hash, config);
+            if (parsed) {
+                isApplyingUrl.current = true;
+                setMode(parsed.mode);
+                setTab(parsed.tab);
+                isApplyingUrl.current = false;
+            }
+        };
+        window.addEventListener('popstate', handlePopState);
+        return () => {
+            window.removeEventListener('popstate', handlePopState);
+        };
+    }, [config, setMode, setTab]);
+}
+//# sourceMappingURL=useUrlSync.js.map

package/eslint.config.js

@@ -0,0 +1,22 @@
+// ESLint 9 flat config
+const nodeProfile = require('@rushstack/eslint-config/flat/profile/node');
+const packletsPlugin = require('@rushstack/eslint-config/flat/mixins/packlets');
+const tsdocPlugin = require('@rushstack/eslint-config/flat/mixins/tsdoc');
+const reactHooksPlugin = require('eslint-plugin-react-hooks');
+
+module.exports = [
+  ...nodeProfile,
+  packletsPlugin,
+  ...tsdocPlugin,
+  {
+    plugins: {
+      'react-hooks': reactHooksPlugin
+    },
+    rules: {
+      ...reactHooksPlugin.configs.recommended.rules,
+      '@rushstack/packlets/mechanics': 'warn',
+      // Disable no-new-null rule for React components where null is conventional
+      '@rushstack/no-new-null': 'off'
+    }
+  }
+];

package/lib/index.browser.d.ts

@@ -0,0 +1,2 @@
+export * from './index';
+//# sourceMappingURL=index.browser.d.ts.map

package/lib/index.browser.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Browser entry point - re-exports everything from main index
+__exportStar(require("./index"), exports);
+//# sourceMappingURL=index.browser.js.map

package/lib/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * \@fgv/ts-app-shell - Shared React UI primitives for application shells.
+ *
+ * Provides reusable components for:
+ * - Column cascade (master-detail drill-down)
+ * - Compact sidebar with flyout filter selectors
+ * - Toast notifications and log message panel
+ * - Command palette
+ * - Keybinding registry
+ *
+ * @packageDocumentation
+ */
+export * from './packlets/top-bar';
+export * from './packlets/messages';
+export * from './packlets/url-sync';
+export * from './packlets/modal';
+export * from './packlets/keyboard';
+export * from './packlets/sidebar';
+export * from './packlets/cascade';
+export * from './packlets/selectors';
+export * from './packlets/drop-zone';
+export * from './packlets/editing';
+export * from './packlets/detail';
+export * from './packlets/ai-assist';
+export * from './packlets/print';
+export * from './packlets/theme';
+export * from './packlets/responsive';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * \@fgv/ts-app-shell - Shared React UI primitives for application shells.
+ *
+ * Provides reusable components for:
+ * - Column cascade (master-detail drill-down)
+ * - Compact sidebar with flyout filter selectors
+ * - Toast notifications and log message panel
+ * - Command palette
+ * - Keybinding registry
+ *
+ * @packageDocumentation
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Top bar components
+__exportStar(require("./packlets/top-bar"), exports);
+// Messages infrastructure (context, toasts, status bar)
+__exportStar(require("./packlets/messages"), exports);
+// URL hash synchronization for mode/tab navigation
+__exportStar(require("./packlets/url-sync"), exports);
+// Modal dialog
+__exportStar(require("./packlets/modal"), exports);
+// Keyboard shortcut registry
+__exportStar(require("./packlets/keyboard"), exports);
+// Sidebar layout, search, filters, and entity list
+__exportStar(require("./packlets/sidebar"), exports);
+// Column cascade container
+__exportStar(require("./packlets/cascade"), exports);
+// Selectors (PreferredSelector popover)
+__exportStar(require("./packlets/selectors"), exports);
+// JSON drop zone (generic drop/paste target with converter validation)
+__exportStar(require("./packlets/drop-zone"), exports);
+// Generic edit field primitives for entity editors
+__exportStar(require("./packlets/editing"), exports);
+// Generic detail-view primitive components
+__exportStar(require("./packlets/detail"), exports);
+// AI assist hook (generic, context-free)
+__exportStar(require("./packlets/ai-assist"), exports);
+// Print popup window enclosure
+__exportStar(require("./packlets/print"), exports);
+// Theme provider and hook
+__exportStar(require("./packlets/theme"), exports);
+// Responsive layout detection and context
+__exportStar(require("./packlets/responsive"), exports);
+//# sourceMappingURL=index.js.map

package/lib/packlets/ai-assist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * AI assist packlet — generic hook for AI-assisted entity generation.
+ * @packageDocumentation
+ */
+export { checkForAiErrorObject, useAiAssist, type IAiAssistAction, type IAiAssistResult, type IUseAiAssistParams, type IUseAiAssistResult } from './useAiAssist';
+//# sourceMappingURL=index.d.ts.map

package/lib/packlets/ai-assist/index.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * AI assist packlet — generic hook for AI-assisted entity generation.
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useAiAssist = exports.checkForAiErrorObject = void 0;
+var useAiAssist_1 = require("./useAiAssist");
+Object.defineProperty(exports, "checkForAiErrorObject", { enumerable: true, get: function () { return useAiAssist_1.checkForAiErrorObject; } });
+Object.defineProperty(exports, "useAiAssist", { enumerable: true, get: function () { return useAiAssist_1.useAiAssist; } });
+//# sourceMappingURL=index.js.map

package/lib/packlets/ai-assist/useAiAssist.d.ts

@@ -0,0 +1,77 @@
+import { AiAssist } from '@fgv/ts-extras';
+import { type Logging, Result } from '@fgv/ts-utils';
+/**
+ * Parameters for the generic useAiAssist hook.
+ * @public
+ */
+export interface IUseAiAssistParams {
+    /** Resolved AI assist settings (provider list + default). */
+    readonly settings: AiAssist.IAiAssistSettings | undefined;
+    /** Keystore for API key resolution (or undefined if no keystore). */
+    readonly keyStore: AiAssist.IAiAssistKeyStore | undefined;
+    /** Optional logger for request/response observability. */
+    readonly logger?: Logging.ILogger;
+}
+/**
+ * A single available AI assist action.
+ * @public
+ */
+export interface IAiAssistAction {
+    /** The provider identifier */
+    readonly provider: AiAssist.AiProviderId;
+    /** Display label (e.g. "AI Assist | Copy", "AI Assist | Grok") */
+    readonly label: string;
+    /** Whether this is the default (first) action */
+    readonly isDefault: boolean;
+    /** Whether the provider is currently available (keystore unlocked, secret present) */
+    readonly isAvailable: boolean;
+    /** Reason the provider is unavailable, if any */
+    readonly unavailableReason?: string;
+}
+/**
+ * Result of executing an AI assist action.
+ * @public
+ */
+export interface IAiAssistResult<TEntity> {
+    /** The generated entity */
+    readonly entity: TEntity;
+    /** Source indicator */
+    readonly source: 'ai';
+}
+/**
+ * Return type of the useAiAssist hook.
+ * @public
+ */
+export interface IUseAiAssistResult {
+    /** Available actions based on settings + keystore state */
+    readonly actions: ReadonlyArray<IAiAssistAction>;
+    /** Whether a direct assist call is in progress */
+    readonly isWorking: boolean;
+    /**
+     * Execute a copy-paste action: copies the combined prompt to clipboard.
+     * @returns Success with `'copied'`, or failure.
+     */
+    readonly copyPrompt: (prompt: AiAssist.AiPrompt) => Promise<Result<'copied'>>;
+    /**
+     * Execute a direct API action: calls the provider, validates the response, returns the entity.
+     * @returns Success with the validated entity, or failure.
+     */
+    readonly generateDirect: <TEntity>(provider: AiAssist.AiProviderId, prompt: AiAssist.AiPrompt, convert: (from: unknown) => Result<TEntity>, tools?: ReadonlyArray<AiAssist.AiServerToolConfig>) => Promise<Result<IAiAssistResult<TEntity>>>;
+}
+/**
+ * Checks whether a parsed AI response is an error object (with an "error" field)
+ * rather than a valid entity. AI prompts instruct the model to return
+ * `{ "error": "...", "term": "..." }` when it cannot confidently generate the entity.
+ *
+ * @param parsed - The parsed JSON from the AI response
+ * @returns A failure Result with the error message if it's an error object, or undefined if not
+ */
+export declare function checkForAiErrorObject(parsed: unknown): Result<never> | undefined;
+/**
+ * Generic hook providing AI assist actions based on supplied settings and keystore.
+ * @param params - Settings and keystore to use (typically from a workspace or app context)
+ * @returns Available actions and execution functions
+ * @public
+ */
+export declare function useAiAssist(params: IUseAiAssistParams): IUseAiAssistResult;
+//# sourceMappingURL=useAiAssist.d.ts.map

package/lib/packlets/ai-assist/useAiAssist.js

@@ -0,0 +1,223 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkForAiErrorObject = checkForAiErrorObject;
+exports.useAiAssist = useAiAssist;
+/**
+ * Generic AI assist hook — parameterized by settings and keystore, no app-specific context.
+ *
+ * Provides a list of available AI assist actions and functions for copy-paste
+ * and direct API generation flows.
+ *
+ * @packageDocumentation
+ */
+const react_1 = require("react");
+const ts_extras_1 = require("@fgv/ts-extras");
+const ts_utils_1 = require("@fgv/ts-utils");
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Checks whether a parsed AI response is an error object (with an "error" field)
+ * rather than a valid entity. AI prompts instruct the model to return
+ * `{ "error": "...", "term": "..." }` when it cannot confidently generate the entity.
+ *
+ * @param parsed - The parsed JSON from the AI response
+ * @returns A failure Result with the error message if it's an error object, or undefined if not
+ */
+function checkForAiErrorObject(parsed) {
+    if (typeof parsed === 'object' &&
+        parsed !== null &&
+        'error' in parsed &&
+        typeof parsed.error === 'string') {
+        const errorObj = parsed;
+        const term = typeof errorObj.term === 'string' ? ` (term: "${errorObj.term}")` : '';
+        return (0, ts_utils_1.fail)(`AI declined to generate${term}: ${errorObj.error}`);
+    }
+    return undefined;
+}
+// ============================================================================
+// Hook
+// ============================================================================
+/**
+ * Generic hook providing AI assist actions based on supplied settings and keystore.
+ * @param params - Settings and keystore to use (typically from a workspace or app context)
+ * @returns Available actions and execution functions
+ * @public
+ */
+function useAiAssist(params) {
+    const { settings, keyStore, logger } = params;
+    const [isWorking, setIsWorking] = (0, react_1.useState)(false);
+    const actions = (0, react_1.useMemo)(() => {
+        var _a, _b, _c;
+        const providers = (_a = settings === null || settings === void 0 ? void 0 : settings.providers) !== null && _a !== void 0 ? _a : [{ provider: 'copy-paste' }];
+        const enabledSet = new Set(providers.map((p) => p.provider));
+        const defaultProvider = (settings === null || settings === void 0 ? void 0 : settings.defaultProvider) && enabledSet.has(settings.defaultProvider)
+            ? settings.defaultProvider
+            : (_c = (_b = providers[0]) === null || _b === void 0 ? void 0 : _b.provider) !== null && _c !== void 0 ? _c : 'copy-paste';
+        return providers.map((config) => {
+            var _a, _b;
+            let isAvailable = true;
+            let unavailableReason;
+            if (config.provider !== 'copy-paste') {
+                // API-based providers need a secret name and unlocked keystore with that secret
+                if (!config.secretName) {
+                    isAvailable = false;
+                    unavailableReason = 'No API key secret configured';
+                }
+                else if (!keyStore) {
+                    isAvailable = false;
+                    unavailableReason = 'No keystore available';
+                }
+                else if (!keyStore.isUnlocked) {
+                    isAvailable = false;
+                    unavailableReason = 'Keystore is locked';
+                }
+                else {
+                    const hasSecret = keyStore.hasSecret(config.secretName);
+                    if (hasSecret.isFailure() || !hasSecret.value) {
+                        isAvailable = false;
+                        unavailableReason = `API key "${config.secretName}" not found in keystore`;
+                    }
+                }
+            }
+            const label = (_b = (_a = ts_extras_1.AiAssist.getProviderDescriptor(config.provider).orDefault()) === null || _a === void 0 ? void 0 : _a.buttonLabel) !== null && _b !== void 0 ? _b : config.provider;
+            return {
+                provider: config.provider,
+                label,
+                isDefault: config.provider === defaultProvider,
+                isAvailable,
+                unavailableReason
+            };
+        });
+    }, [settings, keyStore]);
+    const copyPrompt = (0, react_1.useCallback)(async (prompt) => {
+        try {
+            await navigator.clipboard.writeText(prompt.combined);
+            return (0, ts_utils_1.succeed)('copied');
+        }
+        catch (_a) {
+            return (0, ts_utils_1.fail)('Failed to copy prompt to clipboard');
+        }
+    }, []);
+    const generateDirect = (0, react_1.useCallback)(async (provider, prompt, convert, tools) => {
+        // Find the provider config and descriptor
+        const providerConfig = settings === null || settings === void 0 ? void 0 : settings.providers.find((p) => p.provider === provider);
+        if (!providerConfig) {
+            return (0, ts_utils_1.fail)(`Provider "${provider}" not configured`);
+        }
+        const descriptorResult = ts_extras_1.AiAssist.getProviderDescriptor(provider);
+        if (descriptorResult.isFailure()) {
+            return (0, ts_utils_1.fail)(descriptorResult.message);
+        }
+        const descriptor = descriptorResult.value;
+        if (!providerConfig.secretName) {
+            return (0, ts_utils_1.fail)(`Provider "${provider}" has no secret name configured`);
+        }
+        if (!keyStore) {
+            return (0, ts_utils_1.fail)('No keystore available');
+        }
+        // Get API key from keystore
+        const apiKeyResult = keyStore.getApiKey(providerConfig.secretName);
+        if (apiKeyResult.isFailure()) {
+            return (0, ts_utils_1.fail)(`Failed to get API key: ${apiKeyResult.message}`);
+        }
+        setIsWorking(true);
+        try {
+            const maxAttempts = 3;
+            const correctionMessages = [];
+            for (let attempt = 0; attempt < maxAttempts; attempt++) {
+                // Resolve effective tools: per-call override > settings defaults > none
+                const effectiveTools = ts_extras_1.AiAssist.resolveEffectiveTools(descriptor, providerConfig.tools, tools);
+                // Call the API — through proxy if configured, otherwise direct
+                const completionParams = {
+                    descriptor,
+                    apiKey: apiKeyResult.value,
+                    prompt,
+                    additionalMessages: correctionMessages.length > 0 ? correctionMessages : undefined,
+                    modelOverride: providerConfig.model,
+                    logger,
+                    tools: effectiveTools.length > 0 ? effectiveTools : undefined
+                };
+                const useProxy = !!(settings === null || settings === void 0 ? void 0 : settings.proxyUrl) && (settings.proxyAllProviders === true || descriptor.corsRestricted);
+                const responseResult = useProxy
+                    ? await ts_extras_1.AiAssist.callProxiedCompletion(settings.proxyUrl, completionParams)
+                    : await ts_extras_1.AiAssist.callProviderCompletion(completionParams);
+                if (responseResult.isFailure()) {
+                    logger === null || logger === void 0 ? void 0 : logger.error(`AI completion failed: ${responseResult.message}`);
+                    return (0, ts_utils_1.fail)(responseResult.message);
+                }
+                const { content: rawResponse, truncated } = responseResult.value;
+                logger === null || logger === void 0 ? void 0 : logger.detail(`AI response received (${rawResponse.length} chars, truncated=${truncated})`);
+                // Truncated responses are almost certainly malformed JSON — fail early
+                if (truncated) {
+                    logger === null || logger === void 0 ? void 0 : logger.warn('AI response truncated due to token limits');
+                    return (0, ts_utils_1.fail)('AI response was truncated due to token limits — try a shorter prompt');
+                }
+                // Strip markdown code fences and parse JSON
+                const stripped = rawResponse
+                    .trim()
+                    .replace(/^```(?:\w+)?\s*\n?([\s\S]*?)\n?\s*```$/, '$1')
+                    .trim();
+                let parsed;
+                try {
+                    parsed = JSON.parse(stripped);
+                }
+                catch (err) {
+                    const detail = err instanceof Error ? err.message : String(err);
+                    // JSON parse failures are not retryable — the model isn't producing valid JSON at all
+                    return (0, ts_utils_1.fail)(`AI returned invalid JSON: ${detail}`);
+                }
+                // Check for AI error object (model declined to generate)
+                const aiError = checkForAiErrorObject(parsed);
+                if (aiError !== undefined) {
+                    return aiError;
+                }
+                // Validate with the provided converter
+                const entityResult = convert(parsed);
+                if (entityResult.isSuccess()) {
+                    return (0, ts_utils_1.succeed)({ entity: entityResult.value, source: 'ai' });
+                }
+                // Validation failed — if we have retries left, send a correction
+                logger === null || logger === void 0 ? void 0 : logger.warn(`AI response validation failed (attempt ${attempt + 1}/${maxAttempts}): ${entityResult.message}`);
+                if (attempt < maxAttempts - 1) {
+                    correctionMessages.push({ role: 'assistant', content: rawResponse }, {
+                        role: 'user',
+                        content: `The JSON you returned failed validation with the following error:\n\n${entityResult.message}\n\nPlease fix the JSON and return ONLY the corrected JSON object, nothing else.`
+                    });
+                }
+                else {
+                    // Out of retries
+                    return (0, ts_utils_1.fail)(`AI response validation failed after ${maxAttempts} attempts: ${entityResult.message}`);
+                }
+            }
+            // Unreachable, but TypeScript needs it
+            return (0, ts_utils_1.fail)('AI generation failed');
+        }
+        finally {
+            setIsWorking(false);
+        }
+    }, [settings, keyStore, logger]);
+    return { actions, isWorking, copyPrompt, generateDirect };
+}
+//# sourceMappingURL=useAiAssist.js.map

package/lib/packlets/cascade/CascadeContainer.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Column cascade container — horizontal scroll of detail columns.
+ * @packageDocumentation
+ */
+import React from 'react';
+/**
+ * Describes a single column in the cascade.
+ * @public
+ */
+export interface ICascadeColumn {
+    /** Unique key for React reconciliation */
+    readonly key: string;
+    /** Breadcrumb label for this column */
+    readonly label: string;
+    /** Column content */
+    readonly content: React.ReactNode;
+}
+/**
+ * Props for the CascadeContainer component.
+ * @public
+ */
+export interface ICascadeContainerProps {
+    /** Ordered columns (left-to-right) */
+    readonly columns: ReadonlyArray<ICascadeColumn>;
+    /** Callback to pop the cascade back to a specific depth (0 = clear all) */
+    readonly onPopTo: (depth: number) => void;
+    /** Minimum column width in CSS units (default: '400px') */
+    readonly minColumnWidth?: string;
+    /** Callback when the user clicks inside a cascade column (signals list should collapse) */
+    readonly onFocus?: () => void;
+    /** Label for the breadcrumb root link (default: 'List') */
+    readonly rootLabel?: string;
+}
+/**
+ * Horizontal scroll container for the column cascade.
+ *
+ * Renders a breadcrumb trail at the top and horizontally-scrollable
+ * detail columns below. Auto-scrolls to the rightmost column when
+ * a new column is pushed.
+ *
+ * @public
+ */
+export declare function CascadeContainer(props: ICascadeContainerProps): React.ReactElement | null;
+//# sourceMappingURL=CascadeContainer.d.ts.map