@promptbook/cli 0.112.0-99 → 0.113.0-0

package/src/book-components/BookEditor/BookEditor.tsx

@@ -2,12 +2,11 @@
 // <- Note: [👲] 'use client' is enforced by Next.js when building the https://book-components.ptbk.io/ but in ideal case,
 //          this would not be here because the `@promptbook/components` package should be React library independent of Next.js specifics
 
-import { CSSProperties, useState } from 'react';
+import { type CSSProperties, useState } from 'react';
 import { createPortal } from 'react-dom';
 import type { Promisable } from 'type-fest';
 import type { string_book } from '../../book-2.0/agent-source/string_book';
 import { DEFAULT_BOOK } from '../../book-2.0/agent-source/string_book';
-import { DEFAULT_IS_VERBOSE } from '../../config';
 import type { number_percent } from '../../types/number_percent';
 import type { number_positive } from '../../types/number_positive';
 import type { string_knowledge_source_content } from '../../types/string_knowledge_source_content';
@@ -16,7 +15,10 @@ import { countLines } from '../../utils/expectation-counters/countLines';
 import type { HoistedMenuItem } from '../_common/MenuHoisting/MenuHoistingContext';
 import { classNames } from '../_common/react-utils/classNames';
 import styles from './BookEditor.module.css';
+import { DEFAULT_IS_VERBOSE } from './BookEditorBrowserConfig';
 import { BookEditorMonaco } from './BookEditorMonaco';
+import type { BookEditorTheme } from './BookEditorTheme';
+import { BOOK_EDITOR_RENDER_THEME, resolveBookEditorRenderTheme } from './BookEditorTheme';
 
 /**
  * Monaco diagnostic shown inside `BookEditor`.
@@ -123,14 +125,14 @@ export type BookEditorProps = {
     readonly style?: CSSProperties;
 
     /**
-     * Resolved visual theme used for the editor wrapper and Monaco instance.
+     * Resolved host application theme.
      *
-     * Host applications should pass the final light/dark theme instead of relying on
-     * browser media-query inference inside `<BookEditor/>`.
+     * `<BookEditor/>` accepts this for integration compatibility, but the notebook
+     * editor itself is intentionally rendered as light paper in every app theme.
      *
      * @default 'LIGHT'
      */
-    readonly theme?: 'LIGHT' | 'DARK';
+    readonly theme?: BookEditorTheme;
 
     /**
      * Height of the `BookEditor` component
@@ -288,7 +290,7 @@ export function BookEditor(props: BookEditorProps) {
         agentSource,
         className,
         style,
-        theme = 'LIGHT',
+        theme: hostTheme = BOOK_EDITOR_RENDER_THEME,
         zoom = 1,
         value,
         onChange,
@@ -298,17 +300,18 @@ export function BookEditor(props: BookEditorProps) {
         isBorderRadiusDisabled = false,
         isReadonly = false,
         translations,
-        isUploadButtonShown = true,
+        isUploadButtonShown = false,
         isCameraButtonShown,
-        isDownloadButtonShown = true,
-        isAboutButtonShown = true,
-        isFullscreenButtonShown = true,
+        isDownloadButtonShown = false,
+        isAboutButtonShown = false,
+        isFullscreenButtonShown = false,
         sync,
         monacoModelPath,
         hoistedMenuItems,
     } = props;
 
     const [isFullscreen, setIsFullscreen] = useState(false);
+    const renderedTheme = resolveBookEditorRenderTheme(hostTheme);
 
     /**
      * Toggles fullscreen mode for the editor.
@@ -320,7 +323,7 @@ export function BookEditor(props: BookEditorProps) {
     const editorContent = (
         <div
             data-book-component="BookEditor"
-            data-book-editor-theme={theme.toLowerCase()}
+            data-book-editor-theme={renderedTheme.toLowerCase()}
             className={classNames(
                 styles.BookEditor,
                 isVerbose && styles.isVerbose,
@@ -365,7 +368,7 @@ export function BookEditor(props: BookEditorProps) {
                 zoom={zoom}
                 monacoModelPath={monacoModelPath}
                 hoistedMenuItems={hoistedMenuItems}
-                theme={theme}
+                theme={renderedTheme}
             />
         </div>
     );

package/src/book-components/BookEditor/BookEditorAboutPromptbookInformation.tsx

@@ -0,0 +1,72 @@
+import { BOOK_LANGUAGE_VERSION, PROMPTBOOK_ENGINE_VERSION } from '../../version';
+import { $detectRuntimeEnvironment } from '../../utils/environment/$detectRuntimeEnvironment';
+import type { AboutPromptbookInformationOptions } from '../../utils/misc/aboutPromptbookInformation';
+import { CLAIM, IS_COST_PREVENTED, NAME, PUBLIC_AGENTS_SERVERS } from './BookEditorBrowserConfig';
+import styles from './BookEditor.module.css';
+
+/**
+ * Browser-safe Promptbook information used by `BookEditor`.
+ *
+ * The shared `AboutPromptbookInformation` component renders markdown through the
+ * chat markdown pipeline, which has a server-side JSDOM sanitizer path. Keeping
+ * this component plain JSX prevents BookEditor from pulling JSDOM into client
+ * bundles.
+ *
+ * @private Internal component used by `BookEditorActionbar`
+ */
+export function BookEditorAboutPromptbookInformation(props: AboutPromptbookInformationOptions = {}) {
+    const { isServersInfoIncluded = true, isRuntimeEnvironmentInfoIncluded = true } = props;
+    const runtimeEnvironmentInfo = {
+        ...$detectRuntimeEnvironment(),
+        isCostPrevented: IS_COST_PREVENTED,
+    };
+
+    return (
+        <div className={styles.aboutPromptbookInformation}>
+            <h1>{NAME}</h1>
+            <p>{CLAIM}</p>
+
+            <ul>
+                <li>
+                    <a href="https://github.com/webgptorg/promptbook" target="_blank" rel="noopener noreferrer">
+                        Promptbook engine version <code>{PROMPTBOOK_ENGINE_VERSION}</code>
+                    </a>
+                </li>
+                <li>
+                    <a href="https://github.com/webgptorg/book" target="_blank" rel="noopener noreferrer">
+                        Book language version <code>{BOOK_LANGUAGE_VERSION}</code>
+                    </a>
+                </li>
+            </ul>
+
+            {isServersInfoIncluded && (
+                <>
+                    <h2>Servers</h2>
+                    <ol>
+                        {PUBLIC_AGENTS_SERVERS.map(({ title, description, url }) => (
+                            <li key={url}>
+                                <strong>{title}</strong> {description}{' '}
+                                <a href={url} target="_blank" rel="noopener noreferrer">
+                                    {url}
+                                </a>
+                            </li>
+                        ))}
+                    </ol>
+                </>
+            )}
+
+            {isRuntimeEnvironmentInfoIncluded && (
+                <>
+                    <h2>Environment</h2>
+                    <ul>
+                        {Object.entries(runtimeEnvironmentInfo).map(([key, value]) => (
+                            <li key={key}>
+                                <strong>{key}:</strong> {String(value)}
+                            </li>
+                        ))}
+                    </ul>
+                </>
+            )}
+        </div>
+    );
+}

package/src/book-components/BookEditor/BookEditorActionbar.tsx

@@ -6,8 +6,6 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 // Note: Do not import from `../../package.json` because it would be included in the bundle
 // TODO: [🧠] Is there a better way to get the version?
 import { DEFAULT_BOOK, validateBook } from '../../book-2.0/agent-source/string_book';
-import { $induceBookDownload } from '../../utils/files/$induceBookDownload';
-import { AboutPromptbookInformation } from '../../utils/misc/xAboutPromptbookInformation';
 import { AboutIcon } from '../icons/AboutIcon';
 import { AttachmentIcon } from '../icons/AttachmentIcon';
 import { CameraIcon } from '../icons/CameraIcon';
@@ -18,6 +16,7 @@ import { Dropdown } from '../_common/Dropdown/Dropdown';
 import type { HoistedMenuItem } from '../_common/MenuHoisting/MenuHoistingContext';
 import { useMenuHoisting } from '../_common/MenuHoisting/MenuHoistingContext';
 import { Modal } from '../_common/Modal/Modal';
+import { BookEditorAboutPromptbookInformation } from './BookEditorAboutPromptbookInformation';
 import styles from './BookEditor.module.css';
 
 /**
@@ -37,6 +36,37 @@ type BookEditorActionbarProps = {
     hoistedMenuItems?: ReadonlyArray<HoistedMenuItem>;
 };
 
+function induceBookDownloadInBrowser(book: string): void {
+    const filename = `${normalizeBookDownloadName(extractBookTitle(book) || 'AI Avatar')}.book`;
+    const objectUrl = URL.createObjectURL(new Blob([book], { type: 'application/json' }));
+    const link = window.document.createElement('a');
+
+    link.href = objectUrl;
+    link.download = filename;
+    link.click();
+    URL.revokeObjectURL(objectUrl);
+}
+
+function extractBookTitle(book: string): string | null {
+    return (
+        book
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .find(Boolean) || null
+    );
+}
+
+function normalizeBookDownloadName(value: string): string {
+    return (
+        value
+            .normalize('NFD')
+            .replace(/[\u0300-\u036f]/g, '')
+            .replace(/[^\dA-Za-z]+/g, '-')
+            .replace(/^-+|-+$/g, '')
+            .toLowerCase() || 'ai-avatar'
+    );
+}
+
 /**
  * Handles book editor actionbar.
  *
@@ -67,7 +97,7 @@ export function BookEditorActionbar(props: BookEditorActionbarProps) {
 
     const handleDownload = useCallback(() => {
         const book = validateBook(valueRef.current || DEFAULT_BOOK);
-        /* not await */ $induceBookDownload(book);
+        induceBookDownloadInBrowser(book);
     }, []);
 
     const actions = useMemo(() => {
@@ -157,7 +187,7 @@ export function BookEditorActionbar(props: BookEditorActionbarProps) {
                             setIsAboutModalOpen(false);
                         }}
                     >
-                        <AboutPromptbookInformation />
+                        <BookEditorAboutPromptbookInformation />
                     </Modal>
                 )}
             </>
@@ -183,7 +213,7 @@ export function BookEditorActionbar(props: BookEditorActionbarProps) {
                         setIsAboutModalOpen(false);
                     }}
                 >
-                    <AboutPromptbookInformation />
+                    <BookEditorAboutPromptbookInformation />
                 </Modal>
             )}
         </div>

package/src/book-components/BookEditor/BookEditorBrowserConfig.ts

@@ -0,0 +1,11 @@
+// Re-export browser-compatible constants from canonical sources to avoid duplicate entity names
+export {
+    NAME,
+    CLAIM,
+    PROMPTBOOK_LEGAL_ENTITY,
+    IS_COST_PREVENTED,
+    DEFAULT_IS_VERBOSE,
+    DEFAULT_MAX_CONCURRENT_UPLOADS,
+    PROMPTBOOK_SYNTAX_COLORS,
+} from '../../config';
+export { PUBLIC_AGENTS_SERVERS } from '../../../servers';

package/src/book-components/BookEditor/BookEditorForClient.tsx

@@ -0,0 +1,33 @@
+import { useEffect, useState } from 'react';
+import type { BookEditorProps } from './BookEditor';
+
+type BookEditorComponent = typeof import('./BookEditor').BookEditor;
+
+/**
+ * Renders a book editor
+ *
+ * @public exported from `@promptbook/components`
+ */
+export function BookEditorForClient(props: BookEditorProps) {
+    const [BookEditorComponent, setBookEditorComponent] = useState<BookEditorComponent | null>(null);
+
+    useEffect(() => {
+        let isCancelled = false;
+
+        void import('./BookEditor').then(({ BookEditor }) => {
+            if (!isCancelled) {
+                setBookEditorComponent(() => BookEditor);
+            }
+        });
+
+        return () => {
+            isCancelled = true;
+        };
+    }, []);
+
+    if (!BookEditorComponent) {
+        return <div style={{ minHeight: 260 }} />;
+    }
+
+    return <BookEditorComponent {...props} />;
+}

package/src/book-components/BookEditor/BookEditorMonaco.tsx

@@ -12,7 +12,8 @@ import type { BookEditorProps } from './BookEditor';
 import styles from './BookEditor.module.css';
 import { BookEditorActionbar } from './BookEditorActionbar';
 import { BookEditorMonacoConstants } from './BookEditorMonacoConstants';
-import { createDeprecatedCommitmentDiagnostics } from './createDeprecatedCommitmentDiagnostics';
+import { BOOK_EDITOR_RENDER_THEME, resolveBookEditorRenderTheme } from './BookEditorTheme';
+import { createDeprecatedCommitmentDiagnostics } from './createDeprecatedCommitmentDiagnostics.browser';
 import { useBookEditorMonacoDecorations } from './useBookEditorMonacoDecorations';
 import { useBookEditorMonacoDiagnostics } from './useBookEditorMonacoDiagnostics';
 import { useBookEditorMonacoInteractions } from './useBookEditorMonacoInteractions';
@@ -204,7 +205,7 @@ export function BookEditorMonaco(props: BookEditorProps) {
         onChange,
         diagnostics,
         isReadonly,
-        theme = 'LIGHT',
+        theme: hostTheme = BOOK_EDITOR_RENDER_THEME,
         translations,
         onFileUpload,
         isUploadButtonShown,
@@ -219,6 +220,7 @@ export function BookEditorMonaco(props: BookEditorProps) {
         hoistedMenuItems,
     } = props;
 
+    const theme = resolveBookEditorRenderTheme(hostTheme);
     const zoomLevel = zoom;
     const { scaledLineHeight, scaledContentPaddingLeft, scaledVerticalLineLeft, scaledFontSize, scaledScrollbarSize } =
         createBookEditorMonacoScale(zoomLevel);

package/src/book-components/BookEditor/BookEditorMonacoTokenization.ts

@@ -1,7 +1,3 @@
-import type { string_book } from '../../book-2.0/agent-source/string_book';
-import { parseAgentSourceWithCommitments } from '../../book-2.0/agent-source/parseAgentSourceWithCommitments';
-import type { BookCommitment } from '../../commitments/_base/BookCommitment';
-
 /**
  * Regex source for absolute URL references inside TEAM/FROM/IMPORT commitments.
  *
@@ -11,10 +7,12 @@ const AGENT_REFERENCE_URL_PATTERN = 'https?:\\/\\/[^\\s{}]+';
 
 /**
  * Regex source for compact `@id` references.
+ * The negative lookbehind `(?<!\S)` ensures the `@` is preceded only by whitespace or is at the
+ * start of the string, so email addresses like `team@foo.bar` are not treated as agent references.
  *
  * @private function of BookEditorMonaco
  */
-const AGENT_REFERENCE_AT_PATTERN = '@[A-Za-z0-9_-]+';
+const AGENT_REFERENCE_AT_PATTERN = '(?<!\\S)@[A-Za-z0-9_-]+';
 
 /**
  * Regex source for braced references (`{Agent}`, `{Agent Name}`, `{https://...}`).
@@ -23,17 +21,43 @@ const AGENT_REFERENCE_AT_PATTERN = '@[A-Za-z0-9_-]+';
  */
 const AGENT_REFERENCE_BRACED_PATTERN = '\\{[^{}\\r\\n]+\\}';
 
+/**
+ * Pattern matching plain inline `@` tokens, for example email addresses.
+ *
+ * Monaco tokenizes from the current offset, so `team@foo.bar` can otherwise reach
+ * the `@foo` suffix and look like a standalone compact reference.
+ *
+ * @private function of BookEditorMonaco
+ */
+const NON_AGENT_REFERENCE_INLINE_AT_TOKEN_REGEX = /[^\s{}]*[^\s@{}]@[^\s{}]+/;
+
 /**
  * Commitment types where compact agent references are supported.
  *
  * @private function of BookEditorMonaco
  */
-const AGENT_REFERENCE_COMMITMENT_TYPES: ReadonlySet<BookCommitment> = new Set<BookCommitment>([
-    'FROM',
-    'IMPORT',
-    'IMPORTS',
-    'TEAM',
-]);
+const AGENT_REFERENCE_COMMITMENT_TYPES = ['FROM', 'IMPORT', 'IMPORTS', 'TEAM'] as const;
+
+/**
+ * Regex matching any line that starts with one or more all-uppercase words (minimum 2 characters each).
+ * Used to detect commitment line boundaries without a hardcoded list of commitment types.
+ *
+ * Single-letter uppercase words (e.g. "V", "A") are excluded to avoid false positives with
+ * natural-language sentences that start with a short uppercase word.
+ *
+ * @private function of BookEditorMonaco
+ */
+const DYNAMIC_COMMITMENT_REGEX = /^\s*[A-Z][A-Z0-9]+(?:\s+[A-Z][A-Z0-9]+)*(?=\s|$)/;
+
+/**
+ * Regex pattern to match horizontal lines.
+ *
+ * @private function of BookEditorMonaco
+ */
+const HORIZONTAL_LINE_PATTERN = /^[\s]*[-_*][\s]*[-_*][\s]*[-_*][\s]*[-_*]*[\s]*$/;
+
+const BOOK_EDITOR_COMMITMENT_LINE_REGEX = DYNAMIC_COMMITMENT_REGEX;
+const AGENT_REFERENCE_COMMITMENT_LINE_REGEX = createCommitmentLineRegex(AGENT_REFERENCE_COMMITMENT_TYPES);
 
 /**
  * Range descriptor for one commitment block in source coordinates.
@@ -179,13 +203,6 @@ const extractAgentReferenceMatches = (content: string): Array<AgentReferenceMatc
 
                 const absoluteIndex = lineStartOffset + indexInLine;
 
-                if (token.startsWith('@') && absoluteIndex > 0) {
-                    const previousChar = content[absoluteIndex - 1] || '';
-                    if (/[A-Za-z0-9_.-]/.test(previousChar)) {
-                        continue;
-                    }
-                }
-
                 const value = extractAgentReferenceValue(token);
                 const url = resolveAgentReferenceToUrl(value);
 
@@ -249,40 +266,85 @@ function collectAgentReferenceCommitmentLineRanges(
     content: string,
     sourceLines: ReadonlyArray<string>,
 ): Array<CommitmentLineRange> {
-    const parsed = parseAgentSourceWithCommitments(content as string_book);
     const ranges: Array<CommitmentLineRange> = [];
+    let activeRangeStartLineNumber: number | null = null;
+    let isInsideCodeBlock = false;
+    const startLineIndex = findBookBodyStartLineIndex(sourceLines);
+
+    for (let lineIndex = startLineIndex; lineIndex < sourceLines.length; lineIndex++) {
+        const line = sourceLines[lineIndex] || '';
+        const trimmedLine = line.trim();
+
+        if (trimmedLine.startsWith('```')) {
+            isInsideCodeBlock = !isInsideCodeBlock;
+            continue;
+        }
 
-    for (let index = 0; index < parsed.commitments.length; index++) {
-        const commitment = parsed.commitments[index];
-        if (!commitment || !AGENT_REFERENCE_COMMITMENT_TYPES.has(commitment.type)) {
+        if (isInsideCodeBlock) {
             continue;
         }
 
-        const nextCommitmentStartLine = parsed.commitments[index + 1]?.lineNumber ?? sourceLines.length + 1;
-        const endLineNumber = Math.min(nextCommitmentStartLine - 1, sourceLines.length);
+        if (HORIZONTAL_LINE_PATTERN.test(line)) {
+            if (activeRangeStartLineNumber !== null) {
+                ranges.push({
+                    startLineNumber: activeRangeStartLineNumber,
+                    endLineNumber: lineIndex,
+                });
+                activeRangeStartLineNumber = null;
+            }
+            continue;
+        }
 
-        if (commitment.lineNumber > endLineNumber) {
+        if (!BOOK_EDITOR_COMMITMENT_LINE_REGEX.test(trimmedLine)) {
             continue;
         }
 
+        if (activeRangeStartLineNumber !== null) {
+            ranges.push({
+                startLineNumber: activeRangeStartLineNumber,
+                endLineNumber: lineIndex,
+            });
+        }
+
+        activeRangeStartLineNumber = AGENT_REFERENCE_COMMITMENT_LINE_REGEX.test(trimmedLine) ? lineIndex + 1 : null;
+    }
+
+    if (activeRangeStartLineNumber !== null) {
         ranges.push({
-            startLineNumber: commitment.lineNumber,
-            endLineNumber,
+            startLineNumber: activeRangeStartLineNumber,
+            endLineNumber: sourceLines.length,
         });
     }
 
     return ranges;
 }
 
+function createCommitmentLineRegex(commitmentTypes: ReadonlyArray<string>): RegExp {
+    const commitmentPattern = [...commitmentTypes]
+        .sort((a, b) => b.length - a.length)
+        .map((type) => type.replace(/\s+/, '\\s+'))
+        .join('|');
+
+    return new RegExp(`^\\s*(${commitmentPattern})(?=\\s|$)`, 'i');
+}
+
+function findBookBodyStartLineIndex(sourceLines: ReadonlyArray<string>): number {
+    const titleLineIndex = sourceLines.findIndex((line) => line.trim().length > 0);
+
+    return titleLineIndex === -1 ? 0 : titleLineIndex + 1;
+}
+
 /**
  * Agent reference helpers for `BookEditorMonaco`.
  *
  * @private function of BookEditorMonaco
  */
 export const BookEditorMonacoTokenization = {
+    DYNAMIC_COMMITMENT_REGEX,
     AGENT_URL_REFERENCE_REGEX,
     AGENT_REFERENCE_TOKEN_REGEX,
     AGENT_REFERENCE_BRACED_REGEX,
+    NON_AGENT_REFERENCE_INLINE_AT_TOKEN_REGEX,
     AGENT_REFERENCE_HIGHLIGHT_REGEXES,
     extractAgentReferenceValue,
     resolveAgentReferenceToUrl,

package/src/book-components/BookEditor/BookEditorTheme.ts

@@ -0,0 +1,32 @@
+/**
+ * Visual theme accepted by `<BookEditor/>` integrations.
+ *
+ * @private internal type of `BookEditor`
+ */
+export type BookEditorTheme = 'LIGHT' | 'DARK';
+
+/**
+ * Theme used for the actual notebook editor surface.
+ *
+ * The host application can still pass its resolved app theme, but book sources
+ * are intentionally rendered as light paper in both light and dark app modes.
+ *
+ * @private internal constant of `BookEditor`
+ */
+export const BOOK_EDITOR_RENDER_THEME = 'LIGHT' satisfies BookEditorTheme;
+
+/**
+ * Resolves an app-level theme into the visual theme used by `<BookEditor/>`.
+ *
+ * @param hostTheme - Resolved theme from the embedding application.
+ * @returns Light theme used by the Book editor surface.
+ *
+ * @private internal utility of `BookEditor`
+ */
+export function resolveBookEditorRenderTheme(hostTheme: BookEditorTheme = BOOK_EDITOR_RENDER_THEME): BookEditorTheme {
+    if (hostTheme === 'DARK') {
+        return BOOK_EDITOR_RENDER_THEME;
+    }
+
+    return hostTheme;
+}

package/src/book-components/BookEditor/createDeprecatedCommitmentDiagnostics.browser.ts

@@ -0,0 +1,11 @@
+/**
+ * Browser-compatible stub for `createDeprecatedCommitmentDiagnostics`.
+ *
+ * In the browser build the full Node.js implementation is not available,
+ * so this stub always returns an empty array to keep the editor functional.
+ *
+ * @private internal utility of `BookEditorMonaco`
+ */
+export function createDeprecatedCommitmentDiagnostics(_agentSource?: string): [] {
+    return [];
+}