@promptbook/core 0.112.0-44 → 0.112.0-45

package/esm/src/avatars/Avatar.d.ts

@@ -0,0 +1,7 @@
+import type { AvatarProps } from './types/AvatarVisualDefinition';
+/**
+ * Canvas-based deterministic avatar component.
+ *
+ * @private shared component for in-repository avatar previews
+ */
+export declare function Avatar(props: AvatarProps): import("react/jsx-runtime").JSX.Element;

package/esm/src/avatars/avatarRenderingUtils.d.ts

@@ -0,0 +1,117 @@
+import type { AgentBasicInformation } from '../book-2.0/agent-source/AgentBasicInformation';
+import type { string_color } from '../types/typeAliases';
+import type { AvatarDefinition } from './types/AvatarDefinition';
+import type { AvatarPalette } from './types/AvatarVisualDefinition';
+/**
+ * Default square size used by avatar renderers.
+ *
+ * @private utility of the avatar rendering system
+ */
+export declare const DEFAULT_AVATAR_SIZE = 192;
+/**
+ * Normalizes arbitrary agent colors into a stable non-empty color list.
+ *
+ * @param colors Raw color list.
+ * @returns Stable list of usable colors.
+ *
+ * @private utility of the avatar rendering system
+ */
+export declare function normalizeAvatarColors(colors: ReadonlyArray<string_color>): ReadonlyArray<string_color>;
+/**
+ * Normalizes the avatar input so visuals can rely on consistent data.
+ *
+ * @param avatarDefinition Raw avatar input.
+ * @returns Normalized avatar definition.
+ *
+ * @private utility of the avatar rendering system
+ */
+export declare function normalizeAvatarDefinition(avatarDefinition: AvatarDefinition): AvatarDefinition;
+/**
+ * Extracts avatar colors from the flexible `META COLOR` agent field.
+ *
+ * @param colorValue Raw `META COLOR` value.
+ * @returns Parsed avatar colors.
+ *
+ * @private utility of the avatar rendering system
+ */
+export declare function parseAvatarColors(colorValue: string | undefined): ReadonlyArray<string_color>;
+/**
+ * Creates a reusable avatar definition from parsed agent information.
+ *
+ * @param agentBasicInformation Parsed agent information.
+ * @returns Avatar definition ready for canvas rendering.
+ *
+ * @private shared helper for app-level avatar previews
+ */
+export declare function createAvatarDefinitionFromAgentBasicInformation(agentBasicInformation: Pick<AgentBasicInformation, 'agentName' | 'agentHash' | 'meta'>): AvatarDefinition;
+/**
+ * Creates the shared derived palette used by every avatar visual.
+ *
+ * @param avatarDefinition Stable avatar definition.
+ * @returns Derived palette.
+ *
+ * @private utility of the avatar rendering system
+ */
+export declare function createAvatarPalette(avatarDefinition: AvatarDefinition): AvatarPalette;
+/**
+ * Draws the common rounded background frame used by most visuals.
+ *
+ * @param context Canvas 2D context.
+ * @param size Canvas size in CSS pixels.
+ * @param palette Derived avatar palette.
+ *
+ * @private utility of the avatar rendering system
+ */
+export declare function drawAvatarFrame(context: CanvasRenderingContext2D, size: number, palette: AvatarPalette): void;
+/**
+ * Creates a rounded rectangle path on the current canvas context.
+ *
+ * @param context Canvas 2D context.
+ * @param x Left coordinate.
+ * @param y Top coordinate.
+ * @param width Rectangle width.
+ * @param height Rectangle height.
+ * @param radius Corner radius.
+ *
+ * @private utility of the avatar rendering system
+ */
+export declare function createRoundedRectPath(context: CanvasRenderingContext2D, x: number, y: number, width: number, height: number, radius: number): void;
+/**
+ * Creates a stable pseudo-random number generator from a string seed.
+ *
+ * @param seedSource String seed.
+ * @returns Generator producing values in `[0, 1)`.
+ *
+ * @private utility of the avatar rendering system
+ */
+export declare function createSeededRandom(seedSource: string): () => number;
+/**
+ * Creates a deterministic random factory scoped to the avatar definition.
+ *
+ * @param avatarDefinition Stable avatar definition.
+ * @returns Random factory that can be re-seeded per visual part.
+ *
+ * @private utility of the avatar rendering system
+ */
+export declare function createAvatarRandomFactory(avatarDefinition: AvatarDefinition): (salt: string) => () => number;
+/**
+ * Clears and scales the canvas for crisp avatar rendering on high DPI displays.
+ *
+ * @param canvas Canvas element to prepare.
+ * @param context Canvas 2D context.
+ * @param size Canvas size in CSS pixels.
+ * @param devicePixelRatio Device pixel ratio.
+ *
+ * @private utility of the avatar rendering system
+ */
+export declare function prepareAvatarCanvas(canvas: HTMLCanvasElement, context: CanvasRenderingContext2D, size: number, devicePixelRatio: number): void;
+/**
+ * Picks one deterministic element from a non-empty collection.
+ *
+ * @param items Candidate items.
+ * @param random Seeded random generator.
+ * @returns Picked item.
+ *
+ * @private utility of the avatar rendering system
+ */
+export declare function pickRandomItem<T>(items: ReadonlyArray<T>, random: () => number): T;

package/esm/src/avatars/index.d.ts

@@ -0,0 +1,6 @@
+export { Avatar } from './Avatar';
+export { renderAvatarVisual } from './renderAvatarVisual';
+export { createAvatarDefinitionFromAgentBasicInformation } from './avatarRenderingUtils';
+export { AVATAR_VISUALS, getAvatarVisualById } from './visuals/avatarVisualRegistry';
+export type { AvatarDefinition } from './types/AvatarDefinition';
+export type { AvatarPalette, AvatarProps, AvatarVisual, AvatarVisualDefinition, AvatarVisualId, AvatarVisualRenderContext, RenderAvatarVisualOptions, } from './types/AvatarVisualDefinition';

package/esm/src/avatars/renderAvatarVisual.d.ts

@@ -0,0 +1,9 @@
+import type { RenderAvatarVisualOptions } from './types/AvatarVisualDefinition';
+/**
+ * Renders one deterministic avatar frame into the provided canvas.
+ *
+ * @param options Rendering options.
+ *
+ * @private shared helper for canvas avatar rendering
+ */
+export declare function renderAvatarVisual(options: RenderAvatarVisualOptions): void;

package/esm/src/avatars/types/AvatarDefinition.d.ts

@@ -0,0 +1,20 @@
+import type { string_agent_hash, string_agent_name, string_color } from '../../types/typeAliases';
+/**
+ * Normalized identity payload used by all canvas avatar visuals.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarDefinition = {
+    /**
+     * Human-readable name of the agent.
+     */
+    readonly agentName: string_agent_name;
+    /**
+     * Stable hash of the agent.
+     */
+    readonly agentHash: string_agent_hash;
+    /**
+     * Ordered list of agent colors used to derive a palette.
+     */
+    readonly colors: ReadonlyArray<string_color>;
+};

package/esm/src/avatars/types/AvatarVisualDefinition.d.ts

@@ -0,0 +1,96 @@
+import type { string_color, string_css_class } from '../../types/typeAliases';
+import type { AvatarDefinition } from './AvatarDefinition';
+/**
+ * Supported built-in avatar visual identifiers.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualId = 'pixel-art' | 'octopus' | 'minecraft';
+/**
+ * Derived color palette used by avatar visuals.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarPalette = {
+    readonly background: string_color;
+    readonly backgroundSecondary: string_color;
+    readonly primary: string_color;
+    readonly secondary: string_color;
+    readonly accent: string_color;
+    readonly highlight: string_color;
+    readonly shadow: string_color;
+    readonly ink: string_color;
+};
+/**
+ * Rendering context forwarded to a single avatar visual.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualRenderContext = {
+    readonly canvas: HTMLCanvasElement;
+    readonly context: CanvasRenderingContext2D;
+    readonly size: number;
+    readonly devicePixelRatio: number;
+    readonly timeMs: number;
+    readonly avatarDefinition: AvatarDefinition;
+    readonly palette: AvatarPalette;
+    readonly createRandom: (salt: string) => () => number;
+};
+/**
+ * Signature of one canvas-based avatar visual renderer.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisual = (context: AvatarVisualRenderContext) => void;
+/**
+ * Metadata and renderer for one built-in avatar visual.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarVisualDefinition = {
+    readonly id: AvatarVisualId;
+    readonly title: string;
+    readonly description: string;
+    readonly isAnimated: boolean;
+    readonly render: AvatarVisual;
+};
+/**
+ * Props of the shared `<Avatar/>` component.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type AvatarProps = {
+    /**
+     * Stable visual identity for the rendered avatar.
+     */
+    readonly avatarDefinition: AvatarDefinition;
+    /**
+     * Selected visual style.
+     */
+    readonly visualId: AvatarVisualId;
+    /**
+     * Output size in CSS pixels.
+     */
+    readonly size?: number;
+    /**
+     * Optional canvas title.
+     */
+    readonly title?: string;
+    /**
+     * Optional CSS class name applied to the canvas.
+     */
+    readonly className?: string_css_class;
+};
+/**
+ * Low-level rendering options for a single canvas frame.
+ *
+ * @private shared contract for the avatar rendering system
+ */
+export type RenderAvatarVisualOptions = {
+    readonly canvas: HTMLCanvasElement;
+    readonly avatarDefinition: AvatarDefinition;
+    readonly visualId: AvatarVisualId;
+    readonly size: number;
+    readonly timeMs: number;
+    readonly devicePixelRatio?: number;
+};

package/esm/src/avatars/visuals/avatarVisualRegistry.d.ts

@@ -0,0 +1,16 @@
+import type { AvatarVisualDefinition, AvatarVisualId } from '../types/AvatarVisualDefinition';
+/**
+ * Built-in avatar visuals available to the app.
+ *
+ * @private shared registry for the avatar rendering system
+ */
+export declare const AVATAR_VISUALS: ReadonlyArray<AvatarVisualDefinition>;
+/**
+ * Returns one avatar visual by its identifier.
+ *
+ * @param visualId Requested visual identifier.
+ * @returns Matching visual definition.
+ *
+ * @private shared registry for the avatar rendering system
+ */
+export declare function getAvatarVisualById(visualId: AvatarVisualId): AvatarVisualDefinition;

package/esm/src/avatars/visuals/minecraftAvatarVisual.d.ts

@@ -0,0 +1,7 @@
+import type { AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
+/**
+ * Minecraft-style 3D avatar visual.
+ *
+ * @private built-in avatar visual
+ */
+export declare const minecraftAvatarVisual: AvatarVisualDefinition;

package/esm/src/avatars/visuals/octopusAvatarVisual.d.ts

@@ -0,0 +1,7 @@
+import type { AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
+/**
+ * Octopus avatar visual.
+ *
+ * @private built-in avatar visual
+ */
+export declare const octopusAvatarVisual: AvatarVisualDefinition;

package/esm/src/avatars/visuals/pixelArtAvatarVisual.d.ts

@@ -0,0 +1,7 @@
+import type { AvatarVisualDefinition } from '../types/AvatarVisualDefinition';
+/**
+ * Pixel-art avatar visual.
+ *
+ * @private built-in avatar visual
+ */
+export declare const pixelArtAvatarVisual: AvatarVisualDefinition;

package/esm/src/commitments/STYLE/STYLE.d.ts

@@ -3,8 +3,8 @@ import { BaseCommitmentDefinition } from '../_base/BaseCommitmentDefinition';
 /**
  * STYLE commitment definition
  *
- * The STYLE commitment defines how the agent should format and present its responses.
- * This includes tone, writing style, formatting preferences, and communication patterns.
+ * Deprecated legacy writing-style commitment kept for backward compatibility.
+ * New books should prefer `WRITING RULES` for writing-only constraints.
  *
  * Example usage in agent source:
  *
@@ -21,6 +21,13 @@ export declare class StyleCommitmentDefinition extends BaseCommitmentDefinition<
      * Short one-line description of STYLE.
      */
     get description(): string;
+    /**
+     * Optional UI/docs-only deprecation metadata.
+     */
+    get deprecation(): {
+        readonly message: "Use `WRITING RULES` for writing-only constraints such as tone, length, formatting, or emoji usage.";
+        readonly replacedBy: readonly ["WRITING RULES"];
+    };
     /**
      * Icon for this commitment.
      */

package/esm/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.112.0-43`).
+ * It follows semantic versioning (e.g., `0.112.0-44`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/core",
-    "version": "0.112.0-44",
+    "version": "0.112.0-45",
     "description": "Promptbook: Turn your company's scattered knowledge into AI ready books",
     "private": false,
     "sideEffects": false,

package/umd/index.umd.js

@@ -27,7 +27,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-44';
+    const PROMPTBOOK_ENGINE_VERSION = '0.112.0-45';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -8342,7 +8342,7 @@
             DELETE Casual conversational style
             REMOVE All emoji usage
             GOAL Provide professional business communications
-            STYLE Use formal language and proper business etiquette
+            WRITING RULES Use formal language and proper business etiquette
             \`\`\`
 
             \`\`\`book
@@ -8353,7 +8353,7 @@
             DISCARD Technical jargon explanations
             CANCEL Advanced troubleshooting procedures
             GOAL Help users with simple, easy-to-follow solutions
-            STYLE Use plain language that anyone can understand
+            WRITING RULES Use plain language that anyone can understand
             \`\`\`
 
             \`\`\`book
@@ -8370,11 +8370,11 @@
             Concise Information Provider
 
             PERSONA You are a helpful assistant who provides detailed explanations
-            STYLE Include examples, analogies, and comprehensive context
+            WRITING RULES Include examples, analogies, and comprehensive context
             CANCEL Detailed explanation style
             DISCARD Examples and analogies
             GOAL Provide brief, direct answers without unnecessary elaboration
-            STYLE Be concise and to the point
+            WRITING RULES Be concise and to the point
             \`\`\`
         `);
         }
@@ -8558,7 +8558,7 @@
             PERSONA You are a data analysis expert
             FORMAT Present results in structured tables
             FORMAT Include confidence scores for all predictions
-            STYLE Be concise and precise in explanations
+            WRITING RULES Be concise and precise in explanations
             \`\`\`
         `);
         }
@@ -11454,7 +11454,7 @@
 
             GOAL Help students understand mathematical concepts clearly
             GOAL Ensure all explanations are age-appropriate and accessible
-            STYLE Use simple language and provide step-by-step explanations
+            WRITING RULES Use simple language and provide step-by-step explanations
             \`\`\`
 
             \`\`\`book
@@ -11868,7 +11868,7 @@
             KNOWLEDGE Academic research requires careful citation and verification
             KNOWLEDGE https://example.com/research-guidelines.pdf
             ACTION Can help with literature reviews and data analysis
-            STYLE Present information in clear, academic format
+            WRITING RULES Present information in clear, academic format
             \`\`\`
         `);
         }
@@ -13619,7 +13619,7 @@
 
             META IMAGE https://example.com/professional-avatar.jpg
             PERSONA You are a professional business assistant
-            STYLE Maintain a formal and courteous tone
+            WRITING RULES Maintain a formal and courteous tone
             \`\`\`
 
             \`\`\`book
@@ -13627,7 +13627,7 @@
 
             META IMAGE /assets/creative-bot-avatar.png
             PERSONA You are a creative and inspiring assistant
-            STYLE Be enthusiastic and encouraging
+            WRITING RULES Be enthusiastic and encouraging
             ACTION Can help with brainstorming and ideation
             \`\`\`
         `);
@@ -13786,7 +13786,7 @@
             META LINK https://twitter.com/devhandle
             PERSONA You are an experienced open source developer
             ACTION Can help with code reviews and architecture decisions
-            STYLE Be direct and technical in explanations
+            WRITING RULES Be direct and technical in explanations
             \`\`\`
         `);
         }
@@ -13992,7 +13992,7 @@
             MODEL TEMPERATURE 0.8
             MODEL TOP_P 0.9
             MODEL MAX_TOKENS 2048
-            STYLE Be imaginative and expressive
+            WRITING RULES Be imaginative and expressive
             ACTION Can help with storytelling and character development
             \`\`\`
 
@@ -14204,7 +14204,7 @@
             NOTE Uses RAG for accessing latest research papers
             PERSONA You are a knowledgeable research assistant
             ACTION Can help with literature reviews and citations
-            STYLE Present information in academic format
+            WRITING RULES Present information in academic format
             \`\`\`
         `);
         }
@@ -14498,7 +14498,7 @@
             RULE Always ask for clarification if the user's request is ambiguous
             RULE Be polite and professional in all interactions
             RULES Never provide medical or legal advice
-            STYLE Maintain a friendly and helpful tone
+            WRITING RULES Maintain a friendly and helpful tone
             \`\`\`
 
             \`\`\`book
@@ -14767,8 +14767,8 @@
     /**
      * STYLE commitment definition
      *
-     * The STYLE commitment defines how the agent should format and present its responses.
-     * This includes tone, writing style, formatting preferences, and communication patterns.
+     * Deprecated legacy writing-style commitment kept for backward compatibility.
+     * New books should prefer `WRITING RULES` for writing-only constraints.
      *
      * Example usage in agent source:
      *
@@ -14787,7 +14787,16 @@
          * Short one-line description of STYLE.
          */
         get description() {
-            return 'Control the tone and writing style of responses.';
+            return 'Deprecated legacy writing-style commitment. Prefer `WRITING RULES` for new books.';
+        }
+        /**
+         * Optional UI/docs-only deprecation metadata.
+         */
+        get deprecation() {
+            return {
+                message: 'Use `WRITING RULES` for writing-only constraints such as tone, length, formatting, or emoji usage.',
+                replacedBy: ['WRITING RULES'],
+            };
         }
         /**
          * Icon for this commitment.
@@ -14802,15 +14811,34 @@
             return spacetrim.spaceTrim(`
             # ${this.type}
 
-            Defines how the agent should format and present its responses (tone, writing style, formatting).
+            Deprecated legacy commitment for writing and presentation instructions.
+
+            ## Migration
+
+            - Existing \`${this.type}\` books still parse and compile.
+            - New books should prefer \`WRITING RULES\`.
+            - Use \`WRITING SAMPLE\` when you want to anchor voice by example instead of stating constraints directly.
+            - The plural alias \`STYLES\` is the same legacy commitment family.
 
             ## Key aspects
 
-            - Both terms work identically and can be used interchangeably.
+            - \`${this.type}\` remains functional for backward compatibility only.
             - Later style instructions can override earlier ones.
             - Style affects both tone and presentation format.
 
-            ## Examples
+            ## Preferred replacement
+
+            \`\`\`book
+            Technical Writer
+
+            GOAL Help the user understand technical topics with practical, accurate guidance.
+            WRITING RULES Write in a professional but friendly tone.
+            WRITING RULES Use bullet points for lists.
+            WRITING RULES Always provide code examples when explaining programming concepts.
+            FORMAT Use markdown formatting with clear headings
+            \`\`\`
+
+            ## Legacy compatibility examples
 
             \`\`\`book
             Technical Writer
@@ -15551,7 +15579,7 @@
 
             PERSONA You are a helpful customer support representative
             TEMPLATE Always structure your response with: 1) Acknowledgment, 2) Solution, 3) Follow-up question
-            STYLE Be professional and empathetic
+            WRITING RULES Be professional and empathetic
             \`\`\`
 
             \`\`\`book
@@ -15995,7 +16023,7 @@
 
             PERSONA You are a news analyst who stays up-to-date with current events
             USE BROWSER
-            STYLE Present news in a balanced and objective manner
+            WRITING RULES Present news in a balanced and objective manner
             ACTION Can search for and summarize news articles
             \`\`\`