@promptbook/utils 0.112.0-35 → 0.112.0-38

package/README.md

@@ -654,24 +654,6 @@ You can install all of them at once:
 npm i ptbk
 ```
 
-Promptbook also ships coding-agent CLI utilities through `ptbk coder`.
-For full `coder run` options and runner-specific examples, see [`scripts/run-codex-prompts/README.md`](./scripts/run-codex-prompts/README.md).
-
-#### `ptbk coder`
-
-Locally in this repository:
-
-```bash
-npx ts-node ./src/cli/test/ptbk.ts coder run --dry-run
-```
-
-In another project with `ptbk` installed:
-
-```bash
-npm install ptbk
-npx ptbk coder run --dry-run
-```
-
 Or you can install them separately:
 
 > ⭐ Marked packages are worth to try first
@@ -709,6 +691,125 @@ Or you can install them separately:
 
 
 
+### 🤖 Promptbook Coder
+
+`ptbk coder` is Promptbook's workflow layer for AI-assisted software changes. Instead of opening one chat and manually copy-pasting tasks, you keep a queue of coding prompts in `prompts/*.md`, let a coding agent execute the next ready task, and then verify the result before archiving the prompt.
+
+Promptbook Coder is **not another standalone coding model**. It is an orchestration layer over coding agents such as **GitHub Copilot**, **OpenAI Codex**, **Claude Code**, **Opencode**, **Cline**, and **Gemini CLI**. The difference is that Promptbook Coder adds a repeatable repository workflow on top of them:
+
+-   prompt files with explicit statuses like `[ ]`, `[x]`, and `[-]`
+-   automatic selection of the next runnable task, including priority support
+-   optional shared repo context loaded from a file such as `AGENTS.md`
+-   automatic `git add`, commit, and push after each successful prompt
+-   dedicated coding-agent Git identity and optional GPG signing
+-   verification and repair flow for work that is done, partial, or broken
+-   helper commands for generating boilerplates and finding refactor prompts
+
+In short: tools like Claude Code, Codex, or GitHub Copilot are the **engines**; Promptbook Coder is the **workflow** that keeps coding work structured, reviewable, and repeatable across many prompts.
+
+#### How the workflow works
+
+1. `ptbk coder init` prepares the project for the coder workflow, seeds project-owned generic templates in `prompts/templates/`, creates a starter `AGENTS.md` context file, adds helper `npm run coder:*` scripts, ensures `.gitignore` ignores `/.tmp`, and configures VS Code prompt screenshots in `prompts/screenshots/`.
+2. `ptbk coder generate-boilerplates` creates prompt files in `prompts/`.
+3. You replace placeholder `@@@` sections with real coding tasks.
+4. `ptbk coder run` sends the next ready `[ ]` prompt to the selected coding agent.
+5. Promptbook Coder marks the prompt as done `[x]`, records runner metadata, then stages, commits, and pushes the resulting changes.
+6. `ptbk coder verify` reviews completed prompts, archives finished files to `prompts/done/`, and appends a repair prompt when more work is needed.
+
+Prompts marked with `[-]` are not ready yet, prompts containing `@@@` are treated as not fully written, and prompts with more `!` markers have higher priority.
+
+#### Features
+
+-   **Multi-runner execution:** `openai-codex`, `github-copilot`, `cline`, `claude-code`, `opencode`, `gemini`
+-   **Context injection:** `--context AGENTS.md` or inline extra instructions
+-   **Reasoning control:** `--thinking-level low|medium|high|xhigh` for supported runners
+-   **Interactive or unattended runs:** default wait mode, or `--no-wait` for batch execution
+-   **Git safety:** clean working tree check by default, optional `--ignore-git-changes`
+-   **Prompt triage:** `--priority` to process only more important tasks first
+-   **Failure logging:** failed runs write a neighboring `.error.log`
+-   **Line-ending normalization:** changed files are normalized back to LF by default
+
+#### Local usage in this repository
+
+When working on Promptbook itself, the repository usually runs the CLI straight from source:
+
+```bash
+npx ts-node ./src/cli/test/ptbk.ts coder init
+
+npx ts-node ./src/cli/test/ptbk.ts coder generate-boilerplates --template prompts/templates/common.md
+
+npx ts-node ./src/cli/test/ptbk.ts coder generate-boilerplates --template prompts/templates/agents-server.md
+
+npx ts-node ./src/cli/test/ptbk.ts coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md
+
+npx ts-node ./src/cli/test/ptbk.ts coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --ignore-git-changes --no-wait
+
+npx ts-node ./src/cli/test/ptbk.ts coder find-refactor-candidates
+
+npx ts-node ./src/cli/test/ptbk.ts coder find-refactor-candidates --level xhigh
+
+npx ts-node ./src/cli/test/ptbk.ts coder verify
+```
+
+#### Using `ptbk coder` in an external project
+
+If you want to use the workflow in another repository, install the package and invoke the `ptbk` binary. After local installation, `npx ptbk ...` is the most portable form; plain `ptbk ...` also works when your environment exposes the local binary on `PATH`.
+
+```bash
+npm install ptbk
+
+ptbk coder init
+
+npx ptbk coder generate-boilerplates
+
+npx ptbk coder generate-boilerplates --template prompts/templates/common.md
+
+npx ptbk coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md
+
+npx ptbk coder run --agent github-copilot --model gpt-5.4 --thinking-level xhigh --context AGENTS.md --ignore-git-changes --no-wait
+
+npx ptbk coder find-refactor-candidates
+
+npx ptbk coder find-refactor-candidates --level xhigh
+
+npx ptbk coder verify
+```
+
+`ptbk coder init` also bootstraps a starter `AGENTS.md`, adds `package.json` scripts for the four main coder commands, adds the coder temp ignore to `.gitignore`, and configures `.vscode/settings.json` so pasted images from `prompts/*.md` land in `prompts/screenshots/`.
+
+#### What each command does
+
+| Command | What it does |
+| --- | --- |
+| `ptbk coder init` | Creates `prompts/`, `prompts/done/`, the project-generic template files materialized in `prompts/templates/` (currently `common.md`), and a starter `AGENTS.md`; ensures `.env` contains `CODING_AGENT_GIT_NAME`, `CODING_AGENT_GIT_EMAIL`, and `CODING_AGENT_GIT_SIGNING_KEY`; adds helper coder scripts to `package.json`; ensures `.gitignore` contains `/.tmp`; and configures `.vscode/settings.json` to save pasted prompt images into `prompts/screenshots/`. |
+| `ptbk coder generate-boilerplates` | Creates new prompt markdown files with fresh emoji tags so you can quickly fill in coding tasks; `--template` accepts either a built-in alias or a markdown file path relative to the project root. |
+| `ptbk coder run` | Picks the next ready prompt, appends optional context, runs it through the selected coding agent, marks success or failure, then commits and pushes the result. |
+| `ptbk coder find-refactor-candidates` | Scans the repository for oversized or overpacked files and writes prompt files for likely refactors; `--level <low|medium|high|xhigh>` makes the scan more or less aggressive. |
+| `ptbk coder verify` | Walks through completed prompts, archives truly finished work, and adds follow-up repair prompts for unfinished results. |
+
+#### Most useful `ptbk coder run` flags
+
+| Flag | Purpose |
+| --- | --- |
+| `--agent <name>` | Selects the coding backend. |
+| `--model <model>` | Chooses the runner model; required for `openai-codex` and `gemini`, optional for `github-copilot`. |
+| `--context <text-or-file>` | Appends extra instructions inline or from a file like `AGENTS.md`. |
+| `--thinking-level <level>` | Sets reasoning effort for supported runners. |
+| `--no-wait` | Skips interactive pauses between prompts for unattended execution. |
+| `--ignore-git-changes` | Disables the clean-working-tree guard. |
+| `--priority <n>` | Runs only prompts at or above the given priority. |
+| `--dry-run` | Prints which prompts are ready instead of executing them. |
+| `--allow-credits` | Lets OpenAI Codex spend credits when required. |
+| `--auto-migrate` | Runs testing-server database migrations after each successful prompt. |
+
+#### Typical usage pattern
+
+1. Initialize once with `ptbk coder init`.
+2. Customize `prompts/templates/*.md` if needed, then create or write prompt files in `prompts/`.
+3. Customize the starter `AGENTS.md` with repository-specific instructions, then pass `--context AGENTS.md`.
+4. Run one prompt at a time interactively, or use `--no-wait` for unattended batches.
+5. Finish with `ptbk coder verify` so resolved prompts are archived and broken ones get explicit repair follow-ups.
+
 
 
 

package/esm/index.es.js

@@ -18,7 +18,7 @@ const BOOK_LANGUAGE_VERSION = '2.0.0';
  * @generated
  * @see https://github.com/webgptorg/promptbook
  */
-const PROMPTBOOK_ENGINE_VERSION = '0.112.0-35';
+const PROMPTBOOK_ENGINE_VERSION = '0.112.0-38';
 /**
  * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
  * Note: [💞] Ignore a discrepancy between file name and entity name

package/esm/src/_packages/components.index.d.ts

@@ -61,6 +61,7 @@ import { reactSaveFormatDefinition } from '../book-components/Chat/save/react/re
 import { txtSaveFormatDefinition } from '../book-components/Chat/save/text/txtSaveFormatDefinition';
 import type { ChatProgressItem } from '../book-components/Chat/types/ChatMessage';
 import type { ChatProgressCard } from '../book-components/Chat/types/ChatMessage';
+import type { ChatMessageReplyingTo } from '../book-components/Chat/types/ChatMessage';
 import type { ChatMessage } from '../book-components/Chat/types/ChatMessage';
 import type { ChatParticipant } from '../book-components/Chat/types/ChatParticipant';
 import type { MessageButton } from '../book-components/Chat/utils/parseMessageButtons';
@@ -142,6 +143,7 @@ export { reactSaveFormatDefinition };
 export { txtSaveFormatDefinition };
 export type { ChatProgressItem };
 export type { ChatProgressCard };
+export type { ChatMessageReplyingTo };
 export type { ChatMessage };
 export type { ChatParticipant };
 export type { MessageButton };

package/esm/src/_packages/types.index.d.ts

@@ -44,6 +44,7 @@ import type { SourceChipProps } from '../book-components/Chat/SourceChip/SourceC
 import type { ChatToolCall } from '../book-components/Chat/types/ChatMessage';
 import type { ChatProgressItem } from '../book-components/Chat/types/ChatMessage';
 import type { ChatProgressCard } from '../book-components/Chat/types/ChatMessage';
+import type { ChatMessageReplyingTo } from '../book-components/Chat/types/ChatMessage';
 import type { ChatMessage } from '../book-components/Chat/types/ChatMessage';
 import type { ChatParticipant } from '../book-components/Chat/types/ChatParticipant';
 import type { ParsedCitation } from '../book-components/Chat/utils/parseCitationsFromContent';
@@ -277,7 +278,13 @@ import type { string_agent_name } from '../types/string_agent_name';
 import type { string_agent_name_in_book } from '../types/string_agent_name';
 import type { string_agent_hash } from '../types/string_agent_name';
 import type { string_agent_permanent_id } from '../types/string_agent_name';
+import type { string_agent_url } from '../types/string_agent_url';
+import type { string_base_url } from '../types/string_base_url';
+import type { string_base64 } from '../types/string_base64';
+import type { string_data_url } from '../types/string_base64';
 import type { string_business_category_name } from '../types/string_business_category_name';
+import type { string_email } from '../types/string_email';
+import type { string_emails } from '../types/string_email';
 import type { string_absolute_filename } from '../types/string_filename';
 import type { string_relative_filename } from '../types/string_filename';
 import type { string_filename } from '../types/string_filename';
@@ -285,6 +292,16 @@ import type { string_absolute_dirname } from '../types/string_filename';
 import type { string_relative_dirname } from '../types/string_filename';
 import type { string_dirname } from '../types/string_filename';
 import type { string_executable_path } from '../types/string_filename';
+import type { string_domain } from '../types/string_host';
+import type { string_origin } from '../types/string_host';
+import type { string_tdl } from '../types/string_host';
+import type { string_hostname } from '../types/string_host';
+import type { string_host } from '../types/string_host';
+import type { string_protocol } from '../types/string_host';
+import type { string_ip_address } from '../types/string_host';
+import type { string_href } from '../types/string_href';
+import type { string_uri } from '../types/string_href';
+import type { string_uri_part } from '../types/string_href';
 import type { string_knowledge_source_content } from '../types/string_knowledge_source_content';
 import type { string_knowledge_source_link } from '../types/string_knowledge_source_content';
 import type { string_html } from '../types/string_markdown';
@@ -306,6 +323,8 @@ import type { string_css_property } from '../types/string_markdown';
 import type { string_fonts } from '../types/string_markdown';
 import type { string_css_value } from '../types/string_markdown';
 import type { string_css_selector } from '../types/string_markdown';
+import type { string_mime_type } from '../types/string_mime_type';
+import type { string_mime_type_with_wildcard } from '../types/string_mime_type';
 import type { string_model_name } from '../types/string_model_name';
 import type { string_name } from '../types/string_name';
 import type { string_parameter_name } from '../types/string_name';
@@ -329,6 +348,9 @@ import type { string_javascript_name } from '../types/string_person_fullname';
 import type { string_postprocessing_function_name } from '../types/string_person_fullname';
 import type { string_persona_description } from '../types/string_persona_description';
 import type { string_model_description } from '../types/string_persona_description';
+import type { string_pipeline_root_url } from '../types/string_pipeline_root_url';
+import type { string_pipeline_url } from '../types/string_pipeline_url';
+import type { string_pipeline_url_with_task_hash } from '../types/string_pipeline_url';
 import type { string_prompt } from '../types/string_prompt';
 import type { string_prompt_image } from '../types/string_prompt';
 import type { string_template } from '../types/string_prompt';
@@ -336,6 +358,7 @@ import type { string_text_prompt } from '../types/string_prompt';
 import type { string_chat_prompt } from '../types/string_prompt';
 import type { string_system_message } from '../types/string_prompt';
 import type { string_completion_prompt } from '../types/string_prompt';
+import type { string_promptbook_server_url } from '../types/string_promptbook_server_url';
 import type { string_uuid } from '../types/string_sha256';
 import type { string_sha256 } from '../types/string_sha256';
 import type { string_base_58 } from '../types/string_sha256';
@@ -355,30 +378,8 @@ import type { string_language } from '../types/string_token';
 import type { string_date_iso8601 } from '../types/string_token';
 import type { string_app_id } from '../types/string_token';
 import type { string_user_id } from '../types/string_token';
-import type { string_mime_type } from '../types/string_url';
-import type { string_mime_type_with_wildcard } from '../types/string_url';
-import type { string_base64 } from '../types/string_url';
-import type { string_data_url } from '../types/string_url';
-import type { string_domain } from '../types/string_url';
-import type { string_origin } from '../types/string_url';
-import type { string_tdl } from '../types/string_url';
-import type { string_hostname } from '../types/string_url';
-import type { string_host } from '../types/string_url';
-import type { string_protocol } from '../types/string_url';
-import type { string_ip_address } from '../types/string_url';
+import type { string_url_image } from '../types/string_url_image';
 import type { string_url } from '../types/string_url';
-import type { string_promptbook_server_url } from '../types/string_url';
-import type { string_base_url } from '../types/string_url';
-import type { string_pipeline_root_url } from '../types/string_url';
-import type { string_agent_url } from '../types/string_url';
-import type { string_pipeline_url } from '../types/string_url';
-import type { string_pipeline_url_with_task_hash } from '../types/string_url';
-import type { string_href } from '../types/string_url';
-import type { string_url_image } from '../types/string_url';
-import type { string_uri } from '../types/string_url';
-import type { string_uri_part } from '../types/string_url';
-import type { string_email } from '../types/string_url';
-import type { string_emails } from '../types/string_url';
 import type { TaskType } from '../types/TaskType';
 import type { ToolCallState } from '../types/ToolCall';
 import type { ToolCallLogLevel } from '../types/ToolCall';
@@ -472,6 +473,7 @@ export type { SourceChipProps };
 export type { ChatToolCall };
 export type { ChatProgressItem };
 export type { ChatProgressCard };
+export type { ChatMessageReplyingTo };
 export type { ChatMessage };
 export type { ChatParticipant };
 export type { ParsedCitation };
@@ -705,7 +707,13 @@ export type { string_agent_name };
 export type { string_agent_name_in_book };
 export type { string_agent_hash };
 export type { string_agent_permanent_id };
+export type { string_agent_url };
+export type { string_base_url };
+export type { string_base64 };
+export type { string_data_url };
 export type { string_business_category_name };
+export type { string_email };
+export type { string_emails };
 export type { string_absolute_filename };
 export type { string_relative_filename };
 export type { string_filename };
@@ -713,6 +721,16 @@ export type { string_absolute_dirname };
 export type { string_relative_dirname };
 export type { string_dirname };
 export type { string_executable_path };
+export type { string_domain };
+export type { string_origin };
+export type { string_tdl };
+export type { string_hostname };
+export type { string_host };
+export type { string_protocol };
+export type { string_ip_address };
+export type { string_href };
+export type { string_uri };
+export type { string_uri_part };
 export type { string_knowledge_source_content };
 export type { string_knowledge_source_link };
 export type { string_html };
@@ -734,6 +752,8 @@ export type { string_css_property };
 export type { string_fonts };
 export type { string_css_value };
 export type { string_css_selector };
+export type { string_mime_type };
+export type { string_mime_type_with_wildcard };
 export type { string_model_name };
 export type { string_name };
 export type { string_parameter_name };
@@ -757,6 +777,9 @@ export type { string_javascript_name };
 export type { string_postprocessing_function_name };
 export type { string_persona_description };
 export type { string_model_description };
+export type { string_pipeline_root_url };
+export type { string_pipeline_url };
+export type { string_pipeline_url_with_task_hash };
 export type { string_prompt };
 export type { string_prompt_image };
 export type { string_template };
@@ -764,6 +787,7 @@ export type { string_text_prompt };
 export type { string_chat_prompt };
 export type { string_system_message };
 export type { string_completion_prompt };
+export type { string_promptbook_server_url };
 export type { string_uuid };
 export type { string_sha256 };
 export type { string_base_58 };
@@ -783,30 +807,8 @@ export type { string_language };
 export type { string_date_iso8601 };
 export type { string_app_id };
 export type { string_user_id };
-export type { string_mime_type };
-export type { string_mime_type_with_wildcard };
-export type { string_base64 };
-export type { string_data_url };
-export type { string_domain };
-export type { string_origin };
-export type { string_tdl };
-export type { string_hostname };
-export type { string_host };
-export type { string_protocol };
-export type { string_ip_address };
-export type { string_url };
-export type { string_promptbook_server_url };
-export type { string_base_url };
-export type { string_pipeline_root_url };
-export type { string_agent_url };
-export type { string_pipeline_url };
-export type { string_pipeline_url_with_task_hash };
-export type { string_href };
 export type { string_url_image };
-export type { string_uri };
-export type { string_uri_part };
-export type { string_email };
-export type { string_emails };
+export type { string_url };
 export type { TaskType };
 export type { ToolCallState };
 export type { ToolCallLogLevel };

package/esm/src/book-components/Chat/Chat/ChatActionsBar.d.ts

@@ -17,6 +17,13 @@ export type ChatActionsBarProps = {
     title: string;
     onReset?: () => Promisable<void>;
     resetRequiresConfirmation?: boolean;
+    /**
+     * Optional navigation target for the "New chat" control.
+     *
+     * When provided, the control is rendered as a link so the host app can rely
+     * on browser-native navigation affordances such as opening in a new tab/window.
+     */
+    newChatButtonHref?: string;
     onUseTemplate?: () => void;
     extraActions?: ReactNode;
     saveFormats?: Array<string_chat_format_name>;

package/esm/src/book-components/Chat/Chat/ChatActionsBar.test.d.ts

@@ -0,0 +1,2 @@
+/** @jest-environment jsdom */
+export {};

package/esm/src/book-components/Chat/Chat/ChatInputArea.d.ts

@@ -1,6 +1,7 @@
 import { type MouseEvent } from 'react';
 import { Color } from '../../../utils/color/Color';
 import type { WithTake } from '../../../utils/take/interfaces/ITakeChain';
+import type { ChatMessage } from '../types/ChatMessage';
 import type { ChatParticipant } from '../types/ChatParticipant';
 import type { ChatProps, ChatSoundSystem } from './ChatProps';
 /**
@@ -31,6 +32,8 @@ export type ChatInputAreaProps = {
     speechRecognition?: ChatProps['speechRecognition'];
     speechRecognitionLanguage?: ChatProps['speechRecognitionLanguage'];
     defaultMessage?: string;
+    replyingToMessage?: ChatMessage | null;
+    onCancelReply?: ChatProps['onCancelReply'];
     enterBehavior?: ChatProps['enterBehavior'];
     resolveEnterBehavior?: ChatProps['resolveEnterBehavior'];
     placeholderMessageContent?: string;
@@ -42,6 +45,7 @@ export type ChatInputAreaProps = {
     soundSystem?: ChatSoundSystem;
     onButtonClick: ChatInputButtonClickHandler;
     chatInputClassName?: string;
+    chatUiTranslations?: ChatProps['chatUiTranslations'];
 };
 /**
  * Renders the chat input area with text, file upload, and voice controls.

package/esm/src/book-components/Chat/Chat/ChatMessageItem.d.ts

@@ -60,6 +60,14 @@ type ChatMessageItemProps = Pick<ChatProps, 'onMessage' | 'onActionButton' | 'on
      * Maps tool name to agent information
      */
     teammates?: ChatProps['teammates'];
+    /**
+     * Called when the user chooses to reply to this message.
+     */
+    onReplyToMessage?: ChatProps['onReplyToMessage'];
+    /**
+     * Determines whether this message can be replied to.
+     */
+    canReplyToMessage?: ChatProps['canReplyToMessage'];
     /**
      * Optional cached metadata keyed by TEAM tool names to enrich tool call chips.
      */

package/esm/src/book-components/Chat/Chat/ChatMessageList.d.ts

@@ -40,6 +40,8 @@ export type ChatMessageListProps = {
     onMessage?: (messageContent: string) => Promisable<void>;
     onActionButton?: ChatProps['onActionButton'];
     onQuickMessageButton?: ChatProps['onQuickMessageButton'];
+    onReplyToMessage?: ChatProps['onReplyToMessage'];
+    canReplyToMessage?: ChatProps['canReplyToMessage'];
     onCreateAgent?: (bookContent: string) => void;
     toolTitles?: Record<string, string>;
     teammates?: ChatProps['teammates'];

package/esm/src/book-components/Chat/Chat/ChatProps.d.ts

@@ -2,6 +2,7 @@ import type { CSSProperties, ReactNode } from 'react';
 import type { Promisable } from 'type-fest';
 import { Color } from '../../../_packages/color.index';
 import { SpeechRecognition } from '../../../types/SpeechRecognition';
+import type { string_href } from '../../../types/typeAliases';
 import { string_color } from '../../../types/typeAliases';
 import type { string_chat_format_name } from '../save/_common/string_chat_format_name';
 import type { ChatMessage } from '../types/ChatMessage';
@@ -124,6 +125,26 @@ export type ChatUiTranslations = {
      * @default "Write a message..."
      */
     readonly inputPlaceholder?: string;
+    /**
+     * Label shown above quoted reply previews in both composer and reply bubbles.
+     * @default "Replying to"
+     */
+    readonly replyingToLabel?: string;
+    /**
+     * Visible label for the explicit reply action on one message.
+     * @default "Reply"
+     */
+    readonly replyActionLabel?: string;
+    /**
+     * Accessible title for the explicit reply action on one message.
+     * @default "Reply to this message"
+     */
+    readonly replyActionTitle?: string;
+    /**
+     * Accessible label for the composer button that cancels reply mode.
+     * @default "Cancel reply"
+     */
+    readonly cancelReplyLabel?: string;
     /**
      * Label for the "Save" button in the chat actions bar.
      * @default "Save"
@@ -433,7 +454,11 @@ export type ChatProps = {
      * - When set, the send textarea and button will be shown
      * - When undefined, the chat has no input and is read-only showing only the messages
      */
-    onMessage?(messageContent: string): Promisable<void>;
+    onMessage?(messageContent: string, attachments?: Array<{
+        name: string;
+        type: string;
+        url: string;
+    }>, replyingToMessage?: ChatMessage | null): Promisable<void>;
     /**
      * Called when user clicks a quick action button parsed from message markdown.
      *
@@ -447,6 +472,22 @@ export type ChatProps = {
      * When not provided, quick message buttons fall back to `onMessage`.
      */
     onQuickMessageButton?(messageContent: string): Promisable<void>;
+    /**
+     * Optional callback fired when the user starts replying to one existing message.
+     */
+    onReplyToMessage?(message: ChatMessage): void;
+    /**
+     * Optional callback fired when the user cancels the currently composed reply.
+     */
+    onCancelReply?(): void;
+    /**
+     * Optional callback that determines whether one message can be replied to.
+     */
+    canReplyToMessage?(message: ChatMessage): boolean;
+    /**
+     * Optional message currently being quoted by the composer.
+     */
+    readonly replyingToMessage?: ChatMessage | null;
     /**
      * Optional callback
      *
@@ -460,6 +501,14 @@ export type ChatProps = {
      * @default true
      */
     readonly resetRequiresConfirmation?: boolean;
+    /**
+     * Optional navigation target for the action-bar "New chat" control.
+     *
+     * When provided, the control is rendered as a plain link instead of invoking `onReset`.
+     * This allows host applications to rely on browser-native navigation affordances such as
+     * right-click "Open in new tab/window".
+     */
+    readonly newChatButtonHref?: string_href;
     /**
      * Determines whether the voice recognition button is rendered
      */

package/esm/src/book-components/Chat/Chat/ChatReplyPreview.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Props for one faded quoted-message preview rendered inside the chat UI.
+ *
+ * @private component of `<Chat/>`
+ */
+export type ChatReplyPreviewProps = {
+    readonly label: string;
+    readonly senderLabel: string;
+    readonly previewText: string;
+    readonly className?: string;
+    readonly dismissLabel?: string;
+    readonly onDismiss?: () => void;
+};
+/**
+ * Renders the common faded preview used for reply bubbles and composer reply mode.
+ *
+ * @private component of `<Chat/>`
+ */
+export declare function ChatReplyPreview(props: ChatReplyPreviewProps): import("react/jsx-runtime").JSX.Element;

package/esm/src/book-components/Chat/Chat/createProgressCardChecklistMarkdown.d.ts

@@ -1,9 +1,9 @@
 import type { ChatMessage } from '../types/ChatMessage';
 /**
- * Converts one structured progress card payload into markdown checklist content.
+ * Converts one structured progress card payload into markdown content.
  *
  * @param progressCard Structured progress card payload.
- * @returns Markdown checklist rendered through the normal message markdown pipeline.
+ * @returns Markdown rendered through the normal message markdown pipeline.
  *
  * @private internal helper of `<ChatMessageItem/>`
  */

package/esm/src/book-components/Chat/MockedChat/MockedChat.d.ts

@@ -53,7 +53,7 @@ export type MockedChatDelayConfig = {
  *
  * @public exported from `@promptbook/components`
  */
-export type MockedChatProps = Omit<ChatProps, 'onReset' | /*'onMessage' | */ 'onUseTemplate' | 'isVoiceRecognitionButtonShown'> & {
+export type MockedChatProps = Omit<ChatProps, 'onReset' | 'newChatButtonHref' | /*'onMessage' | */ 'onUseTemplate' | 'isVoiceRecognitionButtonShown'> & {
     /**
      * Whether the chat can be reset via the "New chat" button.
      *

package/esm/src/book-components/Chat/types/ChatMessage.d.ts

@@ -58,6 +58,37 @@ export type ChatProgressCard = {
      */
     readonly isVisible?: boolean;
 };
+/**
+ * Serialized reference to an earlier chat message quoted by a reply bubble.
+ *
+ * Stores the durable relationship (`threadId` + `messageId`) together with a
+ * lightweight snapshot of the original message so UIs and prompt builders can
+ * render reply context without performing extra fetches.
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type ChatMessageReplyingTo = {
+    /**
+     * Durable chat thread identifier that owns the replied-to message.
+     */
+    readonly threadId: string;
+    /**
+     * Durable identifier of the specific replied-to message inside the thread.
+     */
+    readonly messageId: string;
+    /**
+     * Sender of the original replied-to message.
+     */
+    readonly sender: string;
+    /**
+     * Original markdown content of the replied-to message.
+     */
+    readonly content: string_markdown;
+    /**
+     * Optional list of attachment names from the replied-to message.
+     */
+    readonly attachmentNames?: ReadonlyArray<string>;
+};
 /**
  * Serializable prompt snapshot stored alongside one assistant message for debugging and inspection.
  */
@@ -243,5 +274,9 @@ export type ChatMessage = Omit<Message<id>, 'direction' | 'recipients' | 'thread
      * resolved parameters, tool availability, and provider payload associated with one turn.
      */
     readonly prompt?: ChatMessagePrompt;
+    /**
+     * Optional metadata describing which earlier message this one replies to.
+     */
+    readonly replyingTo?: ChatMessageReplyingTo;
 };
 export {};

package/esm/src/book-components/Chat/utils/resolveChatMessageReplyPreviewText.d.ts

@@ -0,0 +1,25 @@
+import type { ChatMessage, ChatMessageReplyingTo } from '../types/ChatMessage';
+/**
+ * Lightweight message-like shape accepted by reply-preview text helpers.
+ *
+ * @private helper contract for chat reply previews
+ */
+type ChatMessageReplyPreviewSource = Pick<ChatMessage, 'content' | 'attachments'> & {
+    readonly attachmentNames?: ChatMessageReplyingTo['attachmentNames'];
+};
+/**
+ * Optional settings for reply-preview text generation.
+ *
+ * @private helper contract for chat reply previews
+ */
+type ResolveChatMessageReplyPreviewTextOptions = {
+    readonly maxLength?: number;
+    readonly emptyLabel?: string;
+};
+/**
+ * Resolves one compact plain-text preview for reply UI surfaces and prompt context.
+ *
+ * @private helper for chat reply previews
+ */
+export declare function resolveChatMessageReplyPreviewText(source: ChatMessageReplyPreviewSource, options?: ResolveChatMessageReplyPreviewTextOptions): string;
+export {};

package/esm/src/book-components/Chat/utils/resolveChatMessageReplySenderLabel.d.ts

@@ -0,0 +1,12 @@
+import type { ChatMessage } from '../types/ChatMessage';
+import type { ChatParticipant } from '../types/ChatParticipant';
+/**
+ * Resolves the human-readable sender label shown in reply previews.
+ *
+ * @private helper for chat reply previews
+ */
+export declare function resolveChatMessageReplySenderLabel(options: {
+    sender: ChatMessage['sender'];
+    participants?: ReadonlyArray<ChatParticipant>;
+    fallbackLabel?: string;
+}): string;