@promptbook/cli 0.113.0-8 → 0.113.0-9

package/src/avatars/visuals/octopus2AvatarVisual.ts

@@ -2,11 +2,7 @@
 
 import { drawAvatarFrame } from '../avatarRenderingUtils';
 import type { AvatarPalette, AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
-import {
-    createOrganicOctopusBodyPoints,
-    resolveOrganicEyeMotion,
-    traceSmoothClosedPath,
-} from './octopusAvatarVisualShared';
+import { createOrganicOctopusBodyPoints, resolveOrganicEyeMotion, traceSmoothClosedPath } from './octopusAvatarVisualShared';
 
 /**
  * Octopus2 avatar visual.

package/src/avatars/visuals/octopus3AvatarVisual.ts

@@ -3,14 +3,7 @@
 import { drawAvatarFrame } from '../avatarRenderingUtils';
 import type { AvatarPalette, AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
 import type { OrganicTentacleShape } from './octopusAvatarVisualShared';
-import {
-    createOrganicOctopusBodyPoints,
-    createOrganicOctopusTentacleShapes,
-    getCubicBezierPoint,
-    resolveOrganicEyeMotion,
-    sampleOrganicTentacleRibbonPoints,
-    traceSmoothClosedPath,
-} from './octopusAvatarVisualShared';
+import { createOrganicOctopusBodyPoints, createOrganicOctopusTentacleShapes, getCubicBezierPoint, resolveOrganicEyeMotion, sampleOrganicTentacleRibbonPoints, traceSmoothClosedPath } from './octopusAvatarVisualShared';
 
 /**
  * Deterministic morphology knobs that keep `Octopus3` recognizable while widening seeded body, face, and tentacle variety.

package/src/avatars/visuals/octopus3d2AvatarVisual.ts

@@ -2,20 +2,11 @@
 
 import { drawAvatarFrame } from '../avatarRenderingUtils';
 import type { AvatarPalette, AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
-import {
-    clampNumber,
-    crossProduct3D,
-    dotProduct3D,
-    getProjectedQuadPerimeter,
-    normalizeVector3,
-    projectScenePoint,
-    subtractPoint3D,
-    transformScenePoint,
-    type Point3D,
-    type ProjectedPoint,
-} from './avatar3dProjectionShared';
+import type { Point3D, ProjectedPoint } from './avatar3dProjectionShared';
+import { clampNumber, crossProduct3D, dotProduct3D, getProjectedQuadPerimeter, normalizeVector3, projectScenePoint, subtractPoint3D, transformScenePoint } from './avatar3dProjectionShared';
+import type { Octopus3MorphologyProfile } from './octopus3AvatarVisual';
+import { createOctopus3MorphologyProfile } from './octopus3AvatarVisual';
 import { drawProjectedOrganicEye, drawProjectedOrganicMouth, drawProjectedQuad } from './octopus3dAvatarVisualShared';
-import { createOctopus3MorphologyProfile, type Octopus3MorphologyProfile } from './octopus3AvatarVisual';
 
 /**
  * One visible projected patch on the continuous Octopus 3D 2 mesh.

package/src/avatars/visuals/octopus3d3AvatarVisual.ts

@@ -2,20 +2,11 @@
 
 import { drawAvatarFrame } from '../avatarRenderingUtils';
 import type { AvatarPalette, AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
-import {
-    clampNumber,
-    crossProduct3D,
-    dotProduct3D,
-    getProjectedQuadPerimeter,
-    normalizeVector3,
-    projectScenePoint,
-    subtractPoint3D,
-    transformScenePoint,
-    type Point3D,
-    type ProjectedPoint,
-} from './avatar3dProjectionShared';
+import type { Point3D, ProjectedPoint } from './avatar3dProjectionShared';
+import { clampNumber, crossProduct3D, dotProduct3D, getProjectedQuadPerimeter, normalizeVector3, projectScenePoint, subtractPoint3D, transformScenePoint } from './avatar3dProjectionShared';
+import type { Octopus3MorphologyProfile } from './octopus3AvatarVisual';
+import { createOctopus3MorphologyProfile } from './octopus3AvatarVisual';
 import { drawProjectedOrganicEye, drawProjectedOrganicMouth, drawProjectedQuad } from './octopus3dAvatarVisualShared';
-import { createOctopus3MorphologyProfile, type Octopus3MorphologyProfile } from './octopus3AvatarVisual';
 
 /**
  * One visible projected patch on the continuous Octopus 3D 3 mesh.

package/src/avatars/visuals/octopus3d4AvatarVisual.ts

@@ -2,20 +2,11 @@
 
 import { drawAvatarFrame } from '../avatarRenderingUtils';
 import type { AvatarPalette, AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
-import {
-    clampNumber,
-    crossProduct3D,
-    dotProduct3D,
-    getProjectedQuadPerimeter,
-    normalizeVector3,
-    projectScenePoint,
-    subtractPoint3D,
-    transformScenePoint,
-    type Point3D,
-    type ProjectedPoint,
-} from './avatar3dProjectionShared';
+import type { Point3D, ProjectedPoint } from './avatar3dProjectionShared';
+import { clampNumber, crossProduct3D, dotProduct3D, getProjectedQuadPerimeter, normalizeVector3, projectScenePoint, subtractPoint3D, transformScenePoint } from './avatar3dProjectionShared';
+import type { Octopus3MorphologyProfile } from './octopus3AvatarVisual';
+import { createOctopus3MorphologyProfile } from './octopus3AvatarVisual';
 import { drawProjectedOrganicEye, drawProjectedOrganicMouth, drawProjectedQuad } from './octopus3dAvatarVisualShared';
-import { createOctopus3MorphologyProfile, type Octopus3MorphologyProfile } from './octopus3AvatarVisual';
 
 /**
  * One visible projected patch on the continuous Octopus 3D 4 mesh.

package/src/avatars/visuals/octopus3dAvatarVisual.ts

@@ -2,6 +2,7 @@
 
 import { drawAvatarFrame } from '../avatarRenderingUtils';
 import type { AvatarPalette, AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
+import type { Point3D, ProjectedPoint } from './avatar3dProjectionShared';
 import {
     clampNumber,
     crossProduct3D,
@@ -11,11 +12,10 @@ import {
     projectScenePoint,
     subtractPoint3D,
     transformScenePoint,
-    type Point3D,
-    type ProjectedPoint,
 } from './avatar3dProjectionShared';
+import type { Octopus3MorphologyProfile } from './octopus3AvatarVisual';
+import { createOctopus3MorphologyProfile } from './octopus3AvatarVisual';
 import { drawProjectedOrganicEye, drawProjectedOrganicMouth, drawProjectedQuad } from './octopus3dAvatarVisualShared';
-import { createOctopus3MorphologyProfile, type Octopus3MorphologyProfile } from './octopus3AvatarVisual';
 
 /**
  * One visible projected surface patch on the octopus mesh.

package/src/avatars/visuals/octopus3dAvatarVisualShared.ts

@@ -1,13 +1,8 @@
 /* eslint-disable no-magic-numbers */
 
 import type { AvatarPalette } from '../types/AvatarVisualDefinition';
-import {
-    clampNumber,
-    projectScenePoint,
-    transformScenePoint,
-    type Point3D,
-    type ProjectedPoint,
-} from './avatar3dProjectionShared';
+import type { Point3D, ProjectedPoint } from './avatar3dProjectionShared';
+import { clampNumber, projectScenePoint, transformScenePoint } from './avatar3dProjectionShared';
 import { resolveOrganicEyeMotion } from './octopusAvatarVisualShared';
 
 // Note: [💞] Ignore a discrepancy between file name and entity name

package/src/book-2.0/agent-source/parseAgentSource/applyMetaCommitment.ts

@@ -16,6 +16,7 @@ type MetaCommitmentApplier = (state: ParseAgentSourceState, content: string) =>
  */
 const META_COMMITMENT_APPLIERS: Readonly<Record<string, MetaCommitmentApplier | undefined>> = {
     'META AVATAR': applyMetaAvatarContent,
+    'META VISUAL': applyMetaAvatarContent,
     'META LINK': applyMetaLinkContent,
     'META DOMAIN': applyMetaDomainContent,
     'META IMAGE': applyMetaImageContent,
@@ -72,7 +73,7 @@ function applyGenericMetaCommitment(state: ParseAgentSourceState, content: strin
 }
 
 /**
- * Applies META AVATAR content into the canonical `meta.avatar` field.
+ * Applies META AVATAR / META VISUAL content into the canonical `meta.avatar` field.
  */
 function applyMetaAvatarContent(state: ParseAgentSourceState, content: string): void {
     const avatarVisualId = resolveAvatarVisualId(content);

package/src/book-2.0/book-language-documentation/createStandaloneBookLanguageMarkdown.ts

@@ -1,9 +1,6 @@
 import { spaceTrim } from 'spacetrim';
 import { NotYetImplementedCommitmentDefinition } from '../../commitments/_base/NotYetImplementedCommitmentDefinition';
-import {
-    formatCommitmentReplacementText,
-    getCommitmentNoticeMetadata,
-} from '../../commitments/_common/getCommitmentNoticeMetadata';
+import { formatCommitmentReplacementText, getCommitmentNoticeMetadata } from '../../commitments/_common/getCommitmentNoticeMetadata';
 import { getGroupedCommitmentDefinitions } from '../../commitments/_common/getGroupedCommitmentDefinitions';
 import type { string_markdown } from '../../types/string_markdown';
 import { BOOK_LANGUAGE_VERSION } from '../../version';
@@ -55,6 +52,7 @@ const PROFILE_COMMITMENT_TYPES = new Set([
     'PERSONAE',
     'META',
     'META AVATAR',
+    'META VISUAL',
     'META IMAGE',
     'META LINK',
     'META DOMAIN',
@@ -333,7 +331,7 @@ export function createStandaloneBookLanguageMarkdown(): string_markdown {
             4. **Add capabilities**
             Add only necessary \`USE*\` and/or \`MEMORY\` commitments.
             5. **Set profile metadata**
-            Add \`META DESCRIPTION\`, \`META AVATAR\` or \`META IMAGE\`, \`META INPUT PLACEHOLDER\`, and disclaimers if needed.
+            Add \`META DESCRIPTION\`, \`META AVATAR\` / \`META VISUAL\` or \`META IMAGE\`, \`META INPUT PLACEHOLDER\`, and disclaimers if needed.
             6. **Add first interaction**
             Add \`INITIAL MESSAGE\` and optionally sample \`USER MESSAGE\` / \`AGENT MESSAGE\` pairs.
             7. **Close for deterministic behavior (optional)**

package/src/book-3.0/CliAgent.ts

@@ -6,13 +6,7 @@ import { resolvePromptbookTemporaryPath } from '../utils/filesystem/promptbookTe
 import { spaceTrim } from '../utils/organization/spaceTrim';
 import type { BookNodeAgentSourceOptions, ResolvedBookNodeAgentSource } from './BookNodeAgentSource';
 import { resolveBookNodeAgentSource } from './BookNodeAgentSource';
-import {
-    CLI_AGENT_HARNESS_NAMES,
-    CLI_AGENT_THINKING_LEVEL_VALUES,
-    PTBK_HARNESS_ENV,
-    PTBK_MODEL_ENV,
-    PTBK_THINKING_LEVEL_ENV,
-} from './cliAgentEnv';
+import { CLI_AGENT_HARNESS_NAMES, CLI_AGENT_THINKING_LEVEL_VALUES, PTBK_HARNESS_ENV, PTBK_MODEL_ENV, PTBK_THINKING_LEVEL_ENV } from './cliAgentEnv';
 
 /**
  * CLI harness names supported by `ptbk agent exec`.

package/src/book-3.0/LiteAgent.ts

@@ -8,22 +8,22 @@ import {
 import { readFile } from 'fs/promises';
 import { basename, resolve } from 'path';
 import { fileURLToPath } from 'url';
-import type { CreateAgentModelRequirementsOptions } from '../book-2.0/agent-source/CreateAgentModelRequirementsOptions';
-import { createAgentModelRequirements } from '../book-2.0/agent-source/createAgentModelRequirements';
 import type { AgentModelRequirements } from '../book-2.0/agent-source/AgentModelRequirements';
+import { createAgentModelRequirements } from '../book-2.0/agent-source/createAgentModelRequirements';
+import type { CreateAgentModelRequirementsOptions } from '../book-2.0/agent-source/CreateAgentModelRequirementsOptions';
 import { NotAllowed } from '../errors/NotAllowed';
 import type { ScriptExecutionTools } from '../execution/ScriptExecutionTools';
+import { computeOpenAiUsage } from '../llm-providers/openai/computeOpenAiUsage';
+import { OPENAI_MODELS } from '../llm-providers/openai/openai-models';
 import { OpenAiAgentKitExecutionToolsToolBuilder } from '../llm-providers/openai/OpenAiAgentKitExecutionToolsToolBuilder';
 import { OpenAiVectorStoreHandler } from '../llm-providers/openai/OpenAiVectorStoreHandler';
-import { OPENAI_MODELS } from '../llm-providers/openai/openai-models';
-import { computeOpenAiUsage } from '../llm-providers/openai/computeOpenAiUsage';
 import { $provideScriptingForNode } from '../scrapers/_common/register/$provideScriptingForNode';
 import type { string_knowledge_source_link } from '../types/string_knowledge_source_content';
 import type { string_markdown, string_markdown_text } from '../types/string_markdown';
 import type { string_model_name } from '../types/string_model_name';
 import type { string_title } from '../types/string_title';
-import type { TODO_any } from '../utils/organization/TODO_any';
 import { spaceTrim } from '../utils/organization/spaceTrim';
+import type { TODO_any } from '../utils/organization/TODO_any';
 import type { BookNodeAgentSourceOptions } from './BookNodeAgentSource';
 import { resolveBookNodeAgentSource } from './BookNodeAgentSource';
 

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

@@ -4,10 +4,7 @@ import { CSSProperties } from 'react';
 import type { AgentBasicInformation } from '../../../book-2.0/agent-source/AgentBasicInformation';
 import type { string_book } from '../../../book-2.0/agent-source/string_book';
 import type { string_css_class } from '../../../types/string_markdown';
-import {
-    resolveAgentAvatarFallbackUrl,
-    resolveAgentAvatarImageUrl,
-} from '../../../utils/agents/resolveAgentAvatarImageUrl';
+import { resolveAgentAvatarFallbackUrl, resolveAgentAvatarImageUrl } from '../../../utils/agents/resolveAgentAvatarImageUrl';
 import { classNames } from '../../_common/react-utils/classNames';
 import styles from './AvatarProfile.module.css';
 

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

@@ -2,11 +2,12 @@
 // <- 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 { type CSSProperties, useState } from 'react';
+import { useState, type CSSProperties } 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';
@@ -15,7 +16,6 @@ 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';

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

@@ -1,7 +1,8 @@
-import { BOOK_LANGUAGE_VERSION, PROMPTBOOK_ENGINE_VERSION } from '../../version';
+import { PUBLIC_AGENTS_SERVERS } from '../../../servers';
+import { CLAIM, IS_COST_PREVENTED, NAME } from '../../config';
 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 { BOOK_LANGUAGE_VERSION, PROMPTBOOK_ENGINE_VERSION } from '../../version';
 import styles from './BookEditor.module.css';
 
 /**

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

@@ -16,8 +16,8 @@ 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';
+import { BookEditorAboutPromptbookInformation } from './BookEditorAboutPromptbookInformation';
 
 /**
  * Props for book editor actionbar.

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

@@ -5,13 +5,14 @@
 import { useMonaco } from '@monaco-editor/react';
 import { useId } from 'react';
 import type { string_book } from '../../book-2.0/agent-source/string_book';
+import { SaveIcon } from '../icons/SaveIcon';
 import { MonacoEditorWithShadowDom } from '../_common/MonacoEditorWithShadowDom';
 import { classNames } from '../_common/react-utils/classNames';
-import { SaveIcon } from '../icons/SaveIcon';
 import type { BookEditorProps } from './BookEditor';
 import styles from './BookEditor.module.css';
 import { BookEditorActionbar } from './BookEditorActionbar';
 import { BookEditorMonacoConstants } from './BookEditorMonacoConstants';
+import { BookEditorMonacoUploadPanel } from './BookEditorMonacoUploadPanel';
 import { BOOK_EDITOR_RENDER_THEME, resolveBookEditorRenderTheme } from './BookEditorTheme';
 import { createDeprecatedCommitmentDiagnostics } from './createDeprecatedCommitmentDiagnostics.browser';
 import { useBookEditorMonacoDecorations } from './useBookEditorMonacoDecorations';
@@ -21,7 +22,6 @@ import { useBookEditorMonacoLanguage } from './useBookEditorMonacoLanguage';
 import { useBookEditorMonacoLifecycle } from './useBookEditorMonacoLifecycle';
 import { useBookEditorMonacoStyles } from './useBookEditorMonacoStyles';
 import { useBookEditorMonacoUploads } from './useBookEditorMonacoUploads';
-import { BookEditorMonacoUploadPanel } from './BookEditorMonacoUploadPanel';
 
 /**
  * Matches characters that are unsafe in CSS identifiers and HTML IDs.

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

@@ -1,6 +1,6 @@
 import styles from './BookEditor.module.css';
 import { BookEditorMonacoFormatting } from './BookEditorMonacoFormatting';
-import type { UploadItem, UploadStats } from './useBookEditorMonacoUploads';
+import type { UploadItem, UploadStats } from './useBookEditorMonacoUploads/bookEditorMonacoUploadTypes';
 
 /**
  * Map of upload status labels.

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

@@ -1,6 +1,6 @@
 import type { editor, Position } from 'monaco-editor';
 import { useEffect } from 'react';
-import { PROMPTBOOK_SYNTAX_COLORS } from './BookEditorBrowserConfig';
+import { PROMPTBOOK_SYNTAX_COLORS } from '../../config';
 import { BookEditorMonacoConstants } from './BookEditorMonacoConstants';
 import { BookEditorMonacoTokenization } from './BookEditorMonacoTokenization';
 import type { BookEditorTheme } from './BookEditorTheme';

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

@@ -1,5 +1,5 @@
 import { useEffect } from 'react';
-import { PROMPTBOOK_SYNTAX_COLORS } from './BookEditorBrowserConfig';
+import { PROMPTBOOK_SYNTAX_COLORS } from '../../config';
 import type { BookEditorTheme } from './BookEditorTheme';
 
 /**

package/src/book-components/BookEditor/useBookEditorMonacoUploads/bookEditorMonacoUploadTypes.ts

@@ -0,0 +1,147 @@
+import type { MutableRefObject } from 'react';
+import type { Promisable } from 'type-fest';
+
+// Note: [💞] This module groups the upload types shared across the `useBookEditorMonacoUploads` internals behind a
+//       descriptive name, so the file name intentionally does not match a single exported entity.
+
+/**
+ * Type describing upload status.
+ *
+ * @private function of BookEditorMonaco
+ */
+type UploadStatus = 'queued' | 'uploading' | 'paused' | 'completed' | 'failed';
+
+/**
+ * Type describing upload item.
+ */
+export type UploadItem = {
+    readonly id: string;
+    readonly fileName: string;
+    readonly fileSize: number;
+    readonly status: UploadStatus;
+    readonly progress: number;
+    readonly loadedBytes: number;
+    readonly totalBytes: number;
+    readonly startedAt: number | null;
+    readonly completedAt: number | null;
+    readonly errorMessage?: string;
+};
+
+/**
+ * Type describing upload progress update.
+ *
+ * @private function of BookEditorMonaco
+ */
+export type UploadProgressUpdate = {
+    readonly progress: number;
+    readonly loadedBytes: number;
+    readonly totalBytes: number;
+};
+
+/**
+ * Type describing placeholder entry inserted into Monaco while the file uploads.
+ *
+ * @private function of BookEditorMonaco
+ */
+export type UploadPlaceholderEntry = {
+    readonly id: string;
+    readonly file: File;
+    readonly placeholder: string;
+};
+
+/**
+ * Type describing upload stats.
+ */
+export type UploadStats = {
+    readonly totalFiles: number;
+    readonly queuedFiles: number;
+    readonly uploadingFiles: number;
+    readonly pausedFiles: number;
+    readonly failedFiles: number;
+    readonly completedFiles: number;
+    readonly totalBytes: number;
+    readonly uploadedBytes: number;
+    readonly progress: number;
+    readonly elapsedMs: number;
+    readonly speedBytesPerSecond: number;
+};
+
+/**
+ * Type describing book editor monaco upload progress callback.
+ *
+ * @private function of BookEditorMonaco
+ */
+export type BookEditorMonacoUploadProgressCallback = (
+    progress: number,
+    stats?: {
+        loadedBytes: number;
+        totalBytes: number;
+    },
+) => void;
+
+/**
+ * Options for book editor monaco upload.
+ *
+ * @private function of BookEditorMonaco
+ */
+export type BookEditorMonacoUploadOptions = {
+    readonly onProgress?: BookEditorMonacoUploadProgressCallback;
+    readonly abortSignal?: AbortSignal;
+};
+
+/**
+ * Type describing book editor monaco on file upload.
+ *
+ * @private function of BookEditorMonaco
+ */
+export type BookEditorMonacoOnFileUpload = (
+    file: File,
+    options?: BookEditorMonacoUploadOptions | BookEditorMonacoUploadProgressCallback,
+) => Promisable<string>;
+
+/**
+ * Setter-like updater used by upload state helpers.
+ *
+ * @private function of BookEditorMonaco
+ */
+export type SetUploadItems = (updater: (items: UploadItem[]) => UploadItem[]) => void;
+
+/**
+ * Single-upload updater used by upload state helpers.
+ *
+ * @private function of BookEditorMonaco
+ */
+export type UpdateUploadItem = (uploadId: string, createNextUploadItem: (uploadItem: UploadItem) => UploadItem) => void;
+
+/**
+ * Mutable upload items reference shared across upload helpers.
+ *
+ * @private function of BookEditorMonaco
+ */
+export type UploadItemsRef = MutableRefObject<UploadItem[]>;
+
+/**
+ * Mutable upload file registry reference shared across upload helpers.
+ *
+ * @private function of BookEditorMonaco
+ */
+export type UploadFilesRef = MutableRefObject<Map<string, File>>;
+
+/**
+ * Mutable Monaco decoration registry reference shared across upload helpers.
+ *
+ * @private function of BookEditorMonaco
+ */
+export type UploadDecorationIdsRef = MutableRefObject<Map<string, string>>;
+
+/**
+ * Type describing the callback used to enqueue debounced progress updates.
+ *
+ * @private function of BookEditorMonaco
+ */
+export type QueueProgressUpdate = (
+    uploadId: string,
+    progress: number,
+    loadedBytes: number,
+    totalBytes: number,
+) => void;

package/src/book-components/BookEditor/useBookEditorMonacoUploads/clearScheduledTimer.ts

@@ -0,0 +1,10 @@
+/**
+ * Clears an optional scheduled timer when it exists.
+ *
+ * @private function of BookEditorMonaco
+ */
+export function clearScheduledTimer(timerId: number | null): void {
+    if (timerId !== null) {
+        clearTimeout(timerId);
+    }
+}