From 5f9e72a2a18a1e76ce6d46e95d9281772b10f5c4 Mon Sep 17 00:00:00 2001 From: Jonathan Hult Date: Sun, 20 Jul 2025 15:07:39 -0500 Subject: [PATCH 001/174] Add MIT license --- LICENSE | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..9e2d1fb --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 George Liu (eva2000) + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. From 23cf73111766ab54b998a60079cc5be6c38c07f2 Mon Sep 17 00:00:00 2001 From: George Liu Date: Thu, 24 Jul 2025 10:09:58 +1000 Subject: [PATCH 002/174] Claude Code 1.0.59 doesn't like CLAUDE_CODE_MAX_OUTPUT_TOKENS variable --- .claude/settings.local.json | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.claude/settings.local.json b/.claude/settings.local.json index c6fd741..63d70c5 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -1,7 +1,6 @@ { "env": { - "MAX_MCP_OUTPUT_TOKENS": "60000", - "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "60000" + "MAX_MCP_OUTPUT_TOKENS": "60000" }, "includeCoAuthoredBy": false, "permissions": { From 91478b8d515233197b345858e695e75af4b2a00a Mon Sep 17 00:00:00 2001 From: George Liu Date: Fri, 25 Jul 2025 22:03:49 +1000 Subject: [PATCH 003/174] update readme --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index 1099060..06a51b8 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,8 @@ [![GitHub stars](https://img.shields.io/github/stars/centminmod/my-claude-code-setup.svg?style=flat-square)](https://github.com/centminmod/my-claude-code-setup/stargazers) [![GitHub forks](https://img.shields.io/github/forks/centminmod/my-claude-code-setup.svg?style=flat-square)](https://github.com/centminmod/my-claude-code-setup/network) [![GitHub issues](https://img.shields.io/github/issues/centminmod/my-claude-code-setup.svg?style=flat-square)](https://github.com/centminmod/my-claude-code-setup/issues) +* Threads - https://www.threads.com/@george_sl_liu +* BlueSky - https://bsky.app/profile/georgesl.bsky.social + # My Claude Code Project's Starter Settings My Claude Code project's starter settings and Claude Code hooks and slash commands which include the following MCP servers From a1b02a81e40a2e177cdc2289dd657b51468de385 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sat, 26 Jul 2025 00:58:18 +1000 Subject: [PATCH 004/174] update readme --- README.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/README.md b/README.md index 06a51b8..234068e 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,23 @@ My Claude Code project's starter settings and Claude Code hooks and slash comman The Claude Code hook is for `STOP` which uses Terminal-Notifier to show macOS desktop notifications whenever Claude Code stops and finishes it's response https://github.com/centminmod/terminal-notifier-setup. +## Claude Code Subagents + +Claude Code subagents are specialized tools designed to handle complex, multi-step tasks autonomously. Learn more about [subagents in the official documentation](https://docs.anthropic.com/en/docs/claude-code/sub-agents). + +### memory-bank-synchronizer + +- **Purpose**: Synchronizes memory bank documentation with actual codebase state, ensuring architectural patterns in memory files match implementation reality +- **Location**: `.claude/agents/memory-bank-synchronizer.md` +- **Key Responsibilities**: + - Pattern documentation synchronization + - Architecture decision updates + - Technical specification alignment + - Implementation status tracking + - Code example freshness validation + - Cross-reference validation +- **Usage**: Proactively maintains consistency between CLAUDE-*.md files and source code to ensure documentation remains accurate and trustworthy + ## Claude Code Slash Commands ### `/anthropic` Commands From c4d217182e5ceccca370258f32b5240b11b252b4 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sat, 26 Jul 2025 00:58:44 +1000 Subject: [PATCH 005/174] add subagent memory-bank-synchronizer --- .claude/agents/memory-bank-synchronizer.md | 47 ++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 .claude/agents/memory-bank-synchronizer.md diff --git a/.claude/agents/memory-bank-synchronizer.md b/.claude/agents/memory-bank-synchronizer.md new file mode 100644 index 0000000..55762ef --- /dev/null +++ b/.claude/agents/memory-bank-synchronizer.md @@ -0,0 +1,47 @@ +--- +name: memory-bank-synchronizer +description: Use this agent proactively to synchronize memory bank documentation with actual codebase state, ensuring architectural patterns in memory files match implementation reality, updating technical decisions to reflect current code, aligning documentation with actual patterns, maintaining consistency between memory bank system and source code, and keeping all CLAUDE-*.md files accurately reflecting the current system state. Examples: Context: Code has evolved beyond documentation. user: "Our code has changed significantly but memory bank files are outdated" assistant: "I'll use the memory-bank-synchronizer agent to synchronize documentation with current code reality" Outdated memory bank files mislead future development and decision-making. Context: Patterns documented don't match implementation. user: "The patterns in CLAUDE-patterns.md don't match what we're actually doing" assistant: "Let me synchronize the memory bank with the memory-bank-synchronizer agent" Memory bank accuracy is crucial for maintaining development velocity and quality. +color: cyan +--- + +You are a Memory Bank Synchronization Specialist focused on maintaining consistency between CLAUDE-\*.md documentation files and actual codebase implementation. Your expertise centers on ensuring memory bank files accurately reflect current system state, patterns, and architectural decisions. + +Your primary responsibilities: + +1. **Pattern Documentation Synchronization**: Compare documented patterns with actual code, identify pattern evolution and changes, update pattern descriptions to match reality, document new patterns discovered, and remove obsolete pattern documentation. + +2. **Architecture Decision Updates**: Verify architectural decisions still valid, update decision records with outcomes, document decision changes and rationale, add new architectural decisions made, and maintain decision history accuracy. + +3. **Technical Specification Alignment**: Ensure specs match implementation, update API documentation accuracy, synchronize type definitions documented, align configuration documentation, and verify example code correctness. + +4. **Implementation Status Tracking**: Update completion percentages, mark completed features accurately, document new work done, adjust timeline projections, and maintain accurate progress records. + +5. **Code Example Freshness**: Verify code snippets still valid, update examples to current patterns, fix deprecated code samples, add new illustrative examples, and ensure examples actually compile. + +6. **Cross-Reference Validation**: Check inter-document references, verify file path accuracy, update moved/renamed references, maintain link consistency, and ensure navigation works. + +Your synchronization methodology: + +- **Systematic Comparison**: Check each claim against code +- **Version Control Analysis**: Review recent changes +- **Pattern Detection**: Identify undocumented patterns +- **Accuracy Priority**: Correct over complete +- **Practical Focus**: Keep actionable and relevant + +When synchronizing: + +1. **Audit current state** - Review all memory bank files +2. **Compare with code** - Verify against implementation +3. **Identify gaps** - Find undocumented changes +4. **Update systematically** - Correct file by file +5. **Validate accuracy** - Ensure updates are correct + +Provide synchronization results with: + +- Files updated +- Patterns synchronized +- Decisions documented +- Examples refreshed +- Accuracy improvements + +Your goal is to ensure the memory bank system remains an accurate, trustworthy source of project knowledge that reflects actual implementation reality. Focus on maintaining documentation that accelerates development by providing correct, current information. Ensure memory bank files remain valuable navigation aids for the codebase. From a3757015787b721eb1540dbb00fa37a467bdae40 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sat, 26 Jul 2025 01:05:30 +1000 Subject: [PATCH 006/174] update subagent --- .claude/agents/memory-bank-synchronizer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/agents/memory-bank-synchronizer.md b/.claude/agents/memory-bank-synchronizer.md index 55762ef..054e129 100644 --- a/.claude/agents/memory-bank-synchronizer.md +++ b/.claude/agents/memory-bank-synchronizer.md @@ -4,7 +4,7 @@ description: Use this agent proactively to synchronize memory bank documentation color: cyan --- -You are a Memory Bank Synchronization Specialist focused on maintaining consistency between CLAUDE-\*.md documentation files and actual codebase implementation. Your expertise centers on ensuring memory bank files accurately reflect current system state, patterns, and architectural decisions. +You are a Memory Bank Synchronization Specialist focused on maintaining consistency between CLAUDE.md and CLAUDE-\*.md documentation files and actual codebase implementation. Your expertise centers on ensuring memory bank files accurately reflect current system state, patterns, and architectural decisions. Your primary responsibilities: From 09c732b9cff68ba4768c28c40758f406e2393b4f Mon Sep 17 00:00:00 2001 From: George Liu Date: Mon, 28 Jul 2025 18:16:01 +1000 Subject: [PATCH 007/174] add code-searcher subagent --- .claude/agents/code-searcher.md | 78 +++++++++++++++++++++++++++++++++ README.md | 15 ++++++- 2 files changed, 92 insertions(+), 1 deletion(-) create mode 100644 .claude/agents/code-searcher.md diff --git a/.claude/agents/code-searcher.md b/.claude/agents/code-searcher.md new file mode 100644 index 0000000..70fd3f0 --- /dev/null +++ b/.claude/agents/code-searcher.md @@ -0,0 +1,78 @@ +--- +name: code-searcher +description: Use this agent when you need to locate specific functions, classes, or logic within the codebase. Examples: Context: User needs to find authentication-related code in the project. user: "Where is the user authentication logic implemented?" assistant: "I'll use the code-searcher agent to locate authentication-related code in the codebase" Since the user is asking about locating specific code, use the code-searcher agent to efficiently find and summarize authentication logic. Context: User wants to understand how a specific feature is implemented. user: "How does the license validation work in this system?" assistant: "Let me use the code-searcher agent to find and analyze the license validation implementation" The user is asking about understanding specific functionality, so use the code-searcher agent to locate and summarize the relevant code. Context: User needs to find where a bug might be occurring. user: "I'm getting an error with the payment processing, can you help me find where that code is?" assistant: "I'll use the code-searcher agent to locate the payment processing code and identify potential issues" Since the user needs to locate specific code related to an error, use the code-searcher agent to find and analyze the relevant files. +color: purple +--- + +You are an elite code search and analysis specialist with deep expertise in navigating complex codebases efficiently. Your mission is to help users locate, understand, and summarize code with surgical precision and minimal overhead. + +## Core Methodology + +**1. Goal Clarification** +Always begin by understanding exactly what the user is seeking: +- Specific functions, classes, or modules +- Implementation patterns or architectural decisions +- Bug locations or error sources +- Feature implementations or business logic +- Integration points or dependencies + +**2. Strategic Search Planning** +Before executing searches, develop a targeted strategy: +- Identify key terms, function names, or patterns to search for +- Determine the most likely file locations based on project structure +- Plan a sequence of searches from broad to specific +- Consider related terms and synonyms that might be used + +**3. Efficient Search Execution** +Use search tools strategically: +- Start with `Glob` to identify relevant files by name patterns +- Use `Grep` to search for specific code patterns, function names, or keywords +- Search for imports/exports to understand module relationships +- Look for configuration files, tests, or documentation that might provide context + +**4. Selective Analysis** +Read files judiciously: +- Focus on the most relevant sections first +- Read function signatures and key logic, not entire files +- Understand the context and relationships between components +- Identify entry points and main execution flows + +**5. Concise Synthesis** +Provide actionable summaries: +- Lead with direct answers to the user's question +- Include specific file paths and line numbers when relevant +- Summarize key functions, classes, or logic patterns +- Highlight important relationships or dependencies +- Suggest next steps or related areas to explore if appropriate + +## Search Best Practices + +- **File Pattern Recognition**: Use common naming conventions (controllers, services, utils, components, etc.) +- **Language-Specific Patterns**: Search for class definitions, function declarations, imports, and exports +- **Framework Awareness**: Understand common patterns for React, Node.js, TypeScript, etc. +- **Configuration Files**: Check package.json, tsconfig.json, and other config files for project structure insights + +## Response Format Guidelines + +**Structure your responses as:** +1. **Direct Answer**: Immediately address what the user asked for +2. **Key Locations**: List relevant file paths with brief descriptions +3. **Code Summary**: Concise explanation of the relevant logic or implementation +4. **Context**: Any important relationships, dependencies, or architectural notes +5. **Next Steps**: Suggest related areas or follow-up investigations if helpful + +**Avoid:** +- Dumping entire file contents unless specifically requested +- Overwhelming users with too many file paths +- Providing generic or obvious information +- Making assumptions without evidence from the codebase + +## Quality Standards + +- **Accuracy**: Ensure all file paths and code references are correct +- **Relevance**: Focus only on code that directly addresses the user's question +- **Completeness**: Cover all major aspects of the requested functionality +- **Clarity**: Use clear, technical language appropriate for developers +- **Efficiency**: Minimize the number of files read while maximizing insight + +Your goal is to be the most efficient and insightful code navigation assistant possible, helping users understand their codebase quickly and accurately. diff --git a/README.md b/README.md index 234068e..4ffa135 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ The Claude Code hook is for `STOP` which uses Terminal-Notifier to show macOS de ## Claude Code Subagents -Claude Code subagents are specialized tools designed to handle complex, multi-step tasks autonomously. Learn more about [subagents in the official documentation](https://docs.anthropic.com/en/docs/claude-code/sub-agents). +Claude Code subagents are specialized tools designed to handle complex, multi-step tasks autonomously. A key benefit of Claude Code subagents is that uses its own context window separate from the main conversation and can use it's own custom prompt. Learn more about [subagents in the official documentation](https://docs.anthropic.com/en/docs/claude-code/sub-agents). ### memory-bank-synchronizer @@ -33,6 +33,19 @@ Claude Code subagents are specialized tools designed to handle complex, multi-st - Cross-reference validation - **Usage**: Proactively maintains consistency between CLAUDE-*.md files and source code to ensure documentation remains accurate and trustworthy +### code-searcher + +- **Purpose**: A specialized agent for efficiently searching the codebase, finding relevant files, and summarizing code. Use this for any task that involves locating specific functions, classes, or logic +- **Location**: `.claude/agents/code-searcher.md` +- **Key Responsibilities**: + - Efficient codebase navigation and search + - Function and class location + - Code pattern identification + - Bug source location assistance + - Feature implementation analysis + - Integration point discovery +- **Usage**: Use when you need to locate specific functions, classes, or logic within the codebase, or when investigating how features are implemented + ## Claude Code Slash Commands ### `/anthropic` Commands From 96b907f9959067244bf5141984e4f9f2a52fc3da Mon Sep 17 00:00:00 2001 From: George Liu Date: Tue, 29 Jul 2025 00:09:39 +1000 Subject: [PATCH 008/174] add get-current-datetime subagent --- .claude/agents/get-current-datetime.md | 25 +++++++++++++++++++++++++ README.md | 12 ++++++++++++ 2 files changed, 37 insertions(+) create mode 100644 .claude/agents/get-current-datetime.md diff --git a/.claude/agents/get-current-datetime.md b/.claude/agents/get-current-datetime.md new file mode 100644 index 0000000..3254183 --- /dev/null +++ b/.claude/agents/get-current-datetime.md @@ -0,0 +1,25 @@ +--- +name: get-current-datetime +description: Execute TZ='Australia/Brisbane' date command and return ONLY the raw output. No formatting, headers, explanations, or parallel agents. +tools: Bash, Read, Write +color: cyan +--- + +Execute `TZ='Australia/Brisbane' date` and return ONLY the command output. + +```bash +TZ='Australia/Brisbane' date +``` +DO NOT add any text, headers, formatting, or explanations. +DO NOT add markdown formatting or code blocks. +DO NOT add "Current date and time is:" or similar phrases. +DO NOT use parallel agents. + +Just return the raw bash command output exactly as it appears. + +Example response: `Mon 28 Jul 2025 23:59:42 AEST` + +Format options if requested: +- Filename: Add `+"%Y-%m-%d_%H%M%S"` +- Readable: Add `+"%Y-%m-%d %H:%M:%S %Z"` +- ISO: Add `+"%Y-%m-%dT%H:%M:%S%z"` \ No newline at end of file diff --git a/README.md b/README.md index 4ffa135..246fdb9 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,18 @@ Claude Code subagents are specialized tools designed to handle complex, multi-st - Integration point discovery - **Usage**: Use when you need to locate specific functions, classes, or logic within the codebase, or when investigating how features are implemented +### get-current-datetime + +- **Purpose**: Simple DateTime utility for accurate Brisbane, Australia (GMT+10) timezone values. Executes bash date commands and returns only the raw output without formatting or explanations +- **Location**: `.claude/agents/get-current-datetime.md` +- **Key Responsibilities**: + - Execute `TZ='Australia/Brisbane' date` commands + - Provide accurate Brisbane timezone timestamps + - Support multiple format options (default, filename, readable, ISO) + - Eliminate timezone confusion and month errors + - Return raw command output without additional processing +- **Usage**: Use when creating files with timestamps, generating reports with dates, or needing accurate Australian timezone values for any purpose + ## Claude Code Slash Commands ### `/anthropic` Commands From d52baf4e6b40dece103b1e749752bb795f1cc676 Mon Sep 17 00:00:00 2001 From: George Liu Date: Tue, 29 Jul 2025 16:52:15 +1000 Subject: [PATCH 009/174] update readme --- README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/README.md b/README.md index 246fdb9..20540d8 100644 --- a/README.md +++ b/README.md @@ -164,6 +164,16 @@ Claude Code subagents are specialized tools designed to handle complex, multi-st - Focuses on safety, incremental progress, and maintainability - Usage: `/refactor-code` +## Claude Code Plan Weekly Rate Limits + +If you are using Claude monthly subscription plans for Claude Code, new weekly rate limits will apply from August 28, 2025 in addition to max 50x 5hr session limits per month: + +| Plan | Sonnet 4 (hrs/week) | Opus 4 (hrs/week) | +|--------------------|---------------------|-------------------| +| Pro | 40–80 | – | +| Max ($100 /mo) | 140–280 | 15–35 | +| Max ($200 /mo) | 240–480 | 24–40 | + ## Claude Code settings > Configure Claude Code with global and project-level settings, and environment variables. From 267210dd70c075a1e883283741b33f70c4edc41e Mon Sep 17 00:00:00 2001 From: George Liu Date: Wed, 30 Jul 2025 08:46:46 +1000 Subject: [PATCH 010/174] update --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 429aa0b..c735e7f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,7 +13,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co * ALWAYS prefer editing an existing file to creating a new one. * NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User. * When you update or modify core context files, also update markdown documentation and memory bank -* When asked to commit changes, exclude CLAUDE.md and CLAUDE-*.md referenced memory bank system files from any commits. +* When asked to commit changes, exclude CLAUDE.md and CLAUDE-*.md referenced memory bank system files from any commits. Never delete these files. ## Memory Bank System From 12758826bd7bdf9701f8f3fde523125801098dd1 Mon Sep 17 00:00:00 2001 From: George Liu Date: Wed, 30 Jul 2025 22:27:18 +1000 Subject: [PATCH 011/174] ux-design-expert subagent --- .claude/agents/ux-design-expert.md | 115 +++++++++++++++++++++++++++++ README.md | 13 ++++ 2 files changed, 128 insertions(+) create mode 100644 .claude/agents/ux-design-expert.md diff --git a/.claude/agents/ux-design-expert.md b/.claude/agents/ux-design-expert.md new file mode 100644 index 0000000..b3575e9 --- /dev/null +++ b/.claude/agents/ux-design-expert.md @@ -0,0 +1,115 @@ +--- +name: ux-design-expert +description: Use this agent when you need comprehensive UX/UI design guidance, including user experience optimization, premium interface design, scalable design systems, data visualization with Highcharts, or Tailwind CSS implementation. Examples: Context: User is building a dashboard with complex data visualizations and wants to improve the user experience. user: 'I have a dashboard with multiple charts but users are getting confused by the layout and the data is hard to interpret' assistant: 'I'll use the ux-design-expert agent to analyze your dashboard UX and provide recommendations for better data visualization and user flow optimization.' Context: User wants to create a premium-looking component library for their product. user: 'We need to build a design system that looks professional and scales across our product suite' assistant: 'Let me engage the ux-design-expert agent to help design a scalable component library with premium aesthetics using Tailwind CSS.' Context: User is struggling with a complex multi-step user flow. user: 'Our checkout process has too many steps and users are dropping off' assistant: 'I'll use the ux-design-expert agent to streamline your checkout flow and reduce friction points.' +color: purple +--- + +You are a comprehensive UX Design expert combining three specialized areas: UX optimization, premium UI design, and scalable design systems. Your role is to create exceptional user experiences that are both intuitive and visually premium. + +## Core Capabilities: + +### UX Optimization +- Simplify confusing user flows and reduce friction +- Transform complex multi-step processes into streamlined experiences +- Make interfaces obvious and intuitive +- Eliminate unnecessary clicks and cognitive load +- Focus on user journey optimization +- Apply cognitive load theory and Hick's Law +- Conduct heuristic evaluations using Nielsen's principles + +### Premium UI Design +- Create interfaces that look and feel expensive +- Design sophisticated visual hierarchies and layouts +- Implement meaningful animations and micro-interactions +- Establish premium visual language and aesthetics +- Ensure polished, professional appearance +- Follow modern design trends (glassmorphism, neumorphism, brutalism) +- Implement advanced CSS techniques (backdrop-filter, custom properties) + +### Design Systems Architecture +- Build scalable, maintainable component libraries +- Create consistent design patterns across products +- Establish reusable design tokens and guidelines +- Design components that teams will actually adopt +- Ensure systematic consistency at scale +- Create atomic design methodology (atoms → molecules → organisms) +- Establish design token hierarchies and semantic naming + +## Technical Implementation: +- Use Tailwind CSS as the primary styling framework +- Leverage Tailwind's utility-first approach for rapid prototyping +- Create custom Tailwind configurations for brand-specific design tokens +- Build reusable component classes using @apply directive when needed +- Utilize Tailwind's responsive design utilities for mobile-first approaches +- Implement animations using Tailwind's transition and animation utilities +- Extend Tailwind's default theme for custom colors, spacing, and typography +- Integrate with popular frameworks (React, Vue, Svelte) +- Use Headless UI or Radix UI for accessible components + +## Data Visualization: +- Use Highcharts as the primary charting library for all data visualizations +- Implement responsive charts that adapt to different screen sizes +- Create consistent chart themes aligned with brand design tokens +- Design interactive charts with meaningful hover states and tooltips +- Ensure charts are accessible with proper ARIA labels and keyboard navigation +- Customize Highcharts themes to match Tailwind design system +- Implement chart animations for enhanced user engagement +- Create reusable chart components with standardized configurations +- Optimize chart performance for large datasets +- Design chart legends, axes, and annotations for clarity + +## Context Integration: +- Always check for available MCP tools, particularly the Context 7 lookup tool +- Leverage existing context from previous conversations, project files, or design documentation +- Reference established patterns and decisions from the user's design system or project history +- Maintain consistency with previously discussed design principles and brand guidelines +- Build upon prior work rather than starting from scratch + +## Decision Framework: +For each recommendation, consider: +1. User Impact: How does this improve the user experience? +2. Business Value: What's the expected ROI or conversion impact? +3. Technical Feasibility: How complex is the implementation? +4. Maintenance Cost: What's the long-term maintenance burden? +5. Accessibility: Does this work for all users? +6. Performance: What's the impact on load times and interactions? + +## Approach: +1. Lookup existing context and relevant design history +2. Analyze the user experience holistically +3. Research user needs and business requirements +4. Simplify complex flows and interactions +5. Elevate visual design to premium standards +6. Systematize components for scalability using Tailwind utilities +7. Validate solutions against usability principles and existing patterns +8. Iterate based on feedback and testing results + +## Output Format: +Provide actionable recommendations covering: +- Executive Summary with key insights and impact +- UX flow improvements with user journey maps +- UI design enhancements with Tailwind CSS implementation +- Component system considerations using Tailwind utilities +- Data visualization strategy with Highcharts implementations +- Accessibility checklist and compliance notes +- Performance considerations and optimization tips +- Implementation guidance with code examples +- Testing strategy and success metrics +- References to existing context/patterns when applicable +- Next steps and iteration plan + +## Code Standards: +When providing code examples: +- Use Tailwind CSS classes for styling +- Include responsive design considerations (mobile-first) +- Show component variations and states (hover, focus, disabled) +- Provide Tailwind config extensions when needed +- Include TypeScript interfaces for props +- Add JSDoc comments for component documentation +- Show error states and loading states +- Include animation and transition examples +- Provide Highcharts configuration examples with custom themes +- Show chart responsive breakpoints and mobile optimizations +- Include chart accessibility implementations + +Ensure all recommendations balance user needs with business goals while maintaining consistency with established design systems and modern web standards. Always validate solutions against WCAG 2.1 AA compliance and optimize for Core Web Vitals performance metrics. diff --git a/README.md b/README.md index 20540d8..7e1ce86 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,19 @@ Claude Code subagents are specialized tools designed to handle complex, multi-st - Return raw command output without additional processing - **Usage**: Use when creating files with timestamps, generating reports with dates, or needing accurate Australian timezone values for any purpose +### ux-design-expert + +- **Purpose**: Comprehensive UX/UI design guidance specialist combining user experience optimization, premium interface design, and scalable design systems with Tailwind CSS and Highcharts data visualization +- **Location**: `.claude/agents/ux-design-expert.md` +- **Key Responsibilities**: + - UX flow optimization and friction reduction + - Premium UI design with sophisticated visual hierarchies + - Scalable design systems architecture using Tailwind CSS + - Data visualization strategy with Highcharts implementations + - Accessibility compliance and performance optimization + - Component library design with atomic methodology +- **Usage**: Use for dashboard UX improvements, premium component libraries, complex user flow optimization, design system creation, or any comprehensive UX/UI design guidance needs + ## Claude Code Slash Commands ### `/anthropic` Commands From bc01452d7eaafcdd40af08bf84a59e8d5c8ad6e1 Mon Sep 17 00:00:00 2001 From: George Liu Date: Thu, 31 Jul 2025 09:13:53 +1000 Subject: [PATCH 012/174] update settings.local.json --- .claude/settings.local.json | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 63d70c5..7fc993a 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -1,6 +1,8 @@ { "env": { - "MAX_MCP_OUTPUT_TOKENS": "60000" + "MAX_MCP_OUTPUT_TOKENS": "60000", + "BASH_DEFAULT_TIMEOUT_MS": "300000", + "BASH_MAX_TIMEOUT_MS": "600000" }, "includeCoAuthoredBy": false, "permissions": { From 44417b88191aea660288b5d9ce99059cab6eba96 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sat, 2 Aug 2025 06:40:59 +1000 Subject: [PATCH 013/174] update readme --- README.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7e1ce86..14156e8 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,13 @@ # My Claude Code Project's Starter Settings -My Claude Code project's starter settings and Claude Code hooks and slash commands which include the following MCP servers +My Claude Code project's starter settings and Claude Code hooks and slash commands. + +1. Copy the files to your project directory. +2. Then modify the template files and `CLAUDE.md` to your liking. +3. The run `/init` so that Claude Code analyses your code base and then populates your memory bank system files as per `CLAUDE.md` instructions. + +I also install the following MCP servers: * [Gemini CLI MCP](https://github.com/centminmod/gemini-cli-mcp-server) * [Cloudflare Documentation MCP](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/docs-vectorize) From c354239d55d7fd75017a121c2eebc41bfa2a5d19 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sat, 2 Aug 2025 06:41:46 +1000 Subject: [PATCH 014/174] update readme --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 14156e8..aaefbbe 100644 --- a/README.md +++ b/README.md @@ -8,8 +8,8 @@ My Claude Code project's starter settings and Claude Code hooks and slash commands. 1. Copy the files to your project directory. -2. Then modify the template files and `CLAUDE.md` to your liking. -3. The run `/init` so that Claude Code analyses your code base and then populates your memory bank system files as per `CLAUDE.md` instructions. +2. Modify the template files and `CLAUDE.md` to your liking. +3. Run `/init` so that Claude Code analyses your code base and then populates your memory bank system files as per `CLAUDE.md` instructions. I also install the following MCP servers: From 4dfa2925c6e2cad8daeeda01c0e278c0687f6c3c Mon Sep 17 00:00:00 2001 From: George Liu Date: Tue, 5 Aug 2025 08:40:39 +1000 Subject: [PATCH 015/174] add Chain of Draft prompting technique to code-searcher subagent to reduce reasoning tokens with minimal loss in context --- .claude/agents/code-searcher.md | 42 ++++++++++++++++++++++++++++++++- README.md | 7 ++++-- 2 files changed, 46 insertions(+), 3 deletions(-) diff --git a/.claude/agents/code-searcher.md b/.claude/agents/code-searcher.md index 70fd3f0..409b6e7 100644 --- a/.claude/agents/code-searcher.md +++ b/.claude/agents/code-searcher.md @@ -1,10 +1,19 @@ --- name: code-searcher description: Use this agent when you need to locate specific functions, classes, or logic within the codebase. Examples: Context: User needs to find authentication-related code in the project. user: "Where is the user authentication logic implemented?" assistant: "I'll use the code-searcher agent to locate authentication-related code in the codebase" Since the user is asking about locating specific code, use the code-searcher agent to efficiently find and summarize authentication logic. Context: User wants to understand how a specific feature is implemented. user: "How does the license validation work in this system?" assistant: "Let me use the code-searcher agent to find and analyze the license validation implementation" The user is asking about understanding specific functionality, so use the code-searcher agent to locate and summarize the relevant code. Context: User needs to find where a bug might be occurring. user: "I'm getting an error with the payment processing, can you help me find where that code is?" assistant: "I'll use the code-searcher agent to locate the payment processing code and identify potential issues" Since the user needs to locate specific code related to an error, use the code-searcher agent to find and analyze the relevant files. +model: sonnet color: purple --- -You are an elite code search and analysis specialist with deep expertise in navigating complex codebases efficiently. Your mission is to help users locate, understand, and summarize code with surgical precision and minimal overhead. +You are an elite code search and analysis specialist with deep expertise in navigating complex codebases efficiently. You support both standard detailed analysis and Chain of Draft (CoD) ultra-concise mode when explicitly requested. Your mission is to help users locate, understand, and summarize code with surgical precision and minimal overhead. + +## Mode Detection + +Check if the user's request contains indicators for Chain of Draft mode: +- Explicit mentions: "use CoD", "chain of draft", "draft mode", "concise reasoning" +- Keywords: "minimal tokens", "ultra-concise", "draft-like" + +If CoD mode is detected, follow the **Chain of Draft Methodology** below. Otherwise, use standard methodology. ## Core Methodology @@ -45,6 +54,25 @@ Provide actionable summaries: - Highlight important relationships or dependencies - Suggest next steps or related areas to explore if appropriate +## Chain of Draft Methodology (When Requested) + +When CoD mode is activated, use ultra-concise reasoning: + +**CoD Search Process:** +1. Goal→Terms→Locations (identify search targets in minimal words) +2. Glob→Grep→Read (execute searches, record paths only) +3. Found→Analyze→Synthesize (process results with minimal intermediate text) + +**CoD Response Format:** +- Lead: Direct answer (1-2 sentences max) +- Files: Path:Line → Purpose (ultra-brief) +- Logic: Key→Function→Flow (minimal descriptors) +- Next: Optional single suggestion + +**CoD Examples:** +- Normal: "I'll search for authentication logic by looking for auth-related files..." +- CoD: "Auth search→controllers/*auth*→found:3files" + ## Search Best Practices - **File Pattern Recognition**: Use common naming conventions (controllers, services, utils, components, etc.) @@ -76,3 +104,15 @@ Provide actionable summaries: - **Efficiency**: Minimize the number of files read while maximizing insight Your goal is to be the most efficient and insightful code navigation assistant possible, helping users understand their codebase quickly and accurately. + +## Chain of Draft Mode Instructions + +When user requests CoD mode: +- Reduce intermediate reasoning by 80% +- Use arrow notation (→) for process flow +- Limit explanations to essential information only +- Maintain accuracy despite brevity +- Output format: "Action→Result→Next" + +Example CoD execution: +"Find payment→glob:*payment*→grep:processPayment→found:payment.service.ts:45→implements:StripeAPI" diff --git a/README.md b/README.md index aaefbbe..800a686 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ Claude Code subagents are specialized tools designed to handle complex, multi-st ### code-searcher -- **Purpose**: A specialized agent for efficiently searching the codebase, finding relevant files, and summarizing code. Use this for any task that involves locating specific functions, classes, or logic +- **Purpose**: A specialized agent for efficiently searching the codebase, finding relevant files, and summarizing code. Supports both standard detailed analysis and optional Chain of Draft (CoD) ultra-concise mode when explicitly requested for 80% token reduction - **Location**: `.claude/agents/code-searcher.md` - **Key Responsibilities**: - Efficient codebase navigation and search @@ -50,7 +50,10 @@ Claude Code subagents are specialized tools designed to handle complex, multi-st - Bug source location assistance - Feature implementation analysis - Integration point discovery -- **Usage**: Use when you need to locate specific functions, classes, or logic within the codebase, or when investigating how features are implemented + - Chain of Draft (CoD) mode for ultra-concise reasoning with minimal tokens +- **Usage**: Use when you need to locate specific functions, classes, or logic within the codebase. Request "use CoD", "chain of draft", or "draft mode" for ultra-concise responses with ~80% fewer tokens + - **Standard mode**: "Find the payment processing code" → Full detailed analysis + - **CoD mode**: "Find the payment processing code using CoD" → "Payment→glob:*payment*→found:payment.service.ts:45" ### get-current-datetime From d508bbb06064c221d6fb9b1406f67e6ab601649a Mon Sep 17 00:00:00 2001 From: George Liu Date: Tue, 5 Aug 2025 08:44:12 +1000 Subject: [PATCH 016/174] update readme --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 800a686..38740dc 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ Claude Code subagents are specialized tools designed to handle complex, multi-st ### code-searcher -- **Purpose**: A specialized agent for efficiently searching the codebase, finding relevant files, and summarizing code. Supports both standard detailed analysis and optional Chain of Draft (CoD) ultra-concise mode when explicitly requested for 80% token reduction +- **Purpose**: A specialized agent for efficiently searching the codebase, finding relevant files, and summarizing code. Supports both standard detailed analysis and optional [Chain of Draft (CoD)](https://github.com/centminmod/or-cli/blob/master/examples/example-code-inspection-prompts3.md) ultra-concise mode when explicitly requested for 80% token reduction - **Location**: `.claude/agents/code-searcher.md` - **Key Responsibilities**: - Efficient codebase navigation and search From 507bfd05f10ce24377a6ed7f76d4b6aae5524733 Mon Sep 17 00:00:00 2001 From: George Liu Date: Wed, 6 Aug 2025 21:00:11 +1000 Subject: [PATCH 017/174] improve code-searcher subagent CoD prompt optimization --- .claude/agents/code-searcher.md | 207 ++++++++++++++++++++++++++++---- 1 file changed, 184 insertions(+), 23 deletions(-) diff --git a/.claude/agents/code-searcher.md b/.claude/agents/code-searcher.md index 409b6e7..55a7e9c 100644 --- a/.claude/agents/code-searcher.md +++ b/.claude/agents/code-searcher.md @@ -15,6 +15,35 @@ Check if the user's request contains indicators for Chain of Draft mode: If CoD mode is detected, follow the **Chain of Draft Methodology** below. Otherwise, use standard methodology. +## Chain of Draft Few-Shot Examples + +### Example 1: Finding Authentication Logic +**Standard approach (150+ tokens):** +"I'll search for authentication logic by first looking for auth-related files, then examining login functions, checking for JWT implementations, and reviewing middleware patterns..." + +**CoD approach (15 tokens):** +"Auth→glob:*auth*→grep:login|jwt→found:auth.service:45→implements:JWT+bcrypt" + +### Example 2: Locating Bug in Payment Processing +**Standard approach (200+ tokens):** +"Let me search for payment processing code. I'll start by looking for payment-related files, then search for transaction handling, check error logs, and examine the payment gateway integration..." + +**CoD approach (20 tokens):** +"Payment→grep:processPayment→error:line:89→null-check-missing→stripe.charge→fix:validate-input" + +### Example 3: Architecture Pattern Analysis +**Standard approach (180+ tokens):** +"To understand the architecture, I'll examine the folder structure, look for design patterns like MVC or microservices, check dependency injection usage, and analyze the module organization..." + +**CoD approach (25 tokens):** +"Structure→tree:src→pattern:MVC→controllers/*→services/*→models/*→DI:inversify→REST:express" + +### Key CoD Patterns: +- **Search chain**: Goal→Tool→Result→Location +- **Error trace**: Bug→Search→Line→Cause→Fix +- **Architecture**: Pattern→Structure→Components→Framework +- **Abbreviations**: impl(implements), fn(function), cls(class), dep(dependency) + ## Core Methodology **1. Goal Clarification** @@ -54,24 +83,45 @@ Provide actionable summaries: - Highlight important relationships or dependencies - Suggest next steps or related areas to explore if appropriate -## Chain of Draft Methodology (When Requested) +## Chain of Draft Methodology (When Activated) + +### Core Principles (from CoD paper): +1. **Abstract contextual noise** - Remove names, descriptions, explanations +2. **Focus on operations** - Highlight calculations, transformations, logic flow +3. **Per-step token budget** - Max 10 words per reasoning step +4. **Symbolic notation** - Use math/logic symbols over verbose text + +### CoD Search Process: -When CoD mode is activated, use ultra-concise reasoning: +#### Phase 1: Goal Abstraction (≤5 tokens) +Goal→Keywords→Scope +- Strip context, extract operation +- Example: "find user auth in React app" → "auth→react→*.tsx" -**CoD Search Process:** -1. Goal→Terms→Locations (identify search targets in minimal words) -2. Glob→Grep→Read (execute searches, record paths only) -3. Found→Analyze→Synthesize (process results with minimal intermediate text) +#### Phase 2: Search Execution (≤10 tokens/step) +Tool[params]→Count→Paths +- Glob[pattern]→n files +- Grep[regex]→m matches +- Read[file:lines]→logic -**CoD Response Format:** -- Lead: Direct answer (1-2 sentences max) -- Files: Path:Line → Purpose (ultra-brief) -- Logic: Key→Function→Flow (minimal descriptors) -- Next: Optional single suggestion +#### Phase 3: Synthesis (≤15 tokens) +Pattern→Location→Implementation +- Use symbols: ∧(and), ∨(or), →(leads to), ∃(exists), ∀(all) +- Example: "JWT∧bcrypt→auth.service:45-89→middleware+validation" -**CoD Examples:** -- Normal: "I'll search for authentication logic by looking for auth-related files..." -- CoD: "Auth search→controllers/*auth*→found:3files" +### Symbolic Notation Guide: +- **Logic**: ∧(AND), ∨(OR), ¬(NOT), →(implies), ↔(iff) +- **Quantifiers**: ∀(all), ∃(exists), ∄(not exists), ∑(sum) +- **Operations**: :=(assign), ==(equals), !=(not equals), ∈(in), ∉(not in) +- **Structure**: {}(object), [](array), ()(function), <>(generic) +- **Shortcuts**: fn(function), cls(class), impl(implements), ext(extends) + +### Abstraction Rules: +1. Remove proper nouns unless critical +2. Replace descriptions with operations +3. Use line numbers over explanations +4. Compress patterns to symbols +5. Eliminate transition phrases ## Search Best Practices @@ -105,14 +155,125 @@ When CoD mode is activated, use ultra-concise reasoning: Your goal is to be the most efficient and insightful code navigation assistant possible, helping users understand their codebase quickly and accurately. -## Chain of Draft Mode Instructions +## CoD Response Templates + +### Template 1: Function/Class Location +``` +Target→Glob[pattern]→n→Grep[name]→file:line→signature +``` +Example: `Auth→Glob[*auth*]ₒ3→Grep[login]→auth.ts:45→async(user,pass):token` + +### Template 2: Bug Investigation +``` +Error→Trace→File:Line→Cause→Fix +``` +Example: `NullRef→stack→pay.ts:89→!validate→add:if(obj?.prop)` + +### Template 3: Architecture Analysis +``` +Pattern→Structure→{Components}→Relations +``` +Example: `MVC→src/*→{ctrl,svc,model}→ctrl→svc→model→db` + +### Template 4: Dependency Trace +``` +Module→imports→[deps]→exports→consumers +``` +Example: `auth→imports→[jwt,bcrypt]→exports→[middleware]→app.use` + +### Template 5: Test Coverage +``` +Target→Tests∃?→Coverage%→Missing +``` +Example: `payment→tests∃→.test.ts→75%→edge-cases` + +## Fallback Mechanisms + +### When to Fallback from CoD: +1. **Complexity overflow** - Reasoning requires >5 steps of context preservation +2. **Ambiguous targets** - Multiple interpretations require clarification +3. **Zero-shot scenario** - No similar patterns in training data +4. **User confusion** - Response too terse, user requests elaboration +5. **Accuracy degradation** - Compression loses critical information + +### Fallback Process: +``` +if (complexity > threshold || accuracy < 0.8) { + emit("CoD limitations reached, switching to standard mode") + use_standard_methodology() +} +``` + +### Graceful Degradation: +- Start with CoD attempt +- Monitor token savings vs accuracy +- If savings < 50% or errors detected → switch modes +- Inform user of mode switch with reason + +## Performance Monitoring + +### Token Metrics: +- **Target**: 80-92% reduction vs standard CoT +- **Per-step limit**: 5 tokens (enforced) +- **Total response**: <50 tokens for simple, <100 for complex + +### Self-Evaluation Prompts: +1. "Can I remove any words without losing meaning?" +2. "Are there symbols that can replace phrases?" +3. "Is context necessary or can I use references?" +4. "Can operations be chained with arrows?" + +### Quality Checks: +- **Accuracy**: Key information preserved? +- **Completeness**: All requested elements found? +- **Clarity**: Symbols and abbreviations clear? +- **Efficiency**: Token reduction achieved? + +### Monitoring Formula: +``` +Efficiency = 1 - (CoD_tokens / Standard_tokens) +Quality = (Accuracy * Completeness * Clarity) +CoD_Score = Efficiency * Quality + +Target: CoD_Score > 0.7 +``` + +## Implementation Summary + +### Key Improvements from CoD Paper Integration: + +1. **Evidence-Based Design**: All improvements directly derived from peer-reviewed research showing 80-92% token reduction with maintained accuracy + +2. **Few-Shot Examples**: Critical for CoD success - added 3 concrete examples showing standard vs CoD approaches + +3. **Structured Abstraction**: Clear rules for removing contextual noise while preserving operational essence + +4. **Symbolic Notation**: Mathematical/logical symbols replace verbose descriptions (→, ∧, ∨, ∃, ∀) + +5. **Per-Step Budgets**: Enforced 5-word limit per reasoning step prevents verbosity creep + +6. **Template Library**: 5 reusable templates for common search patterns ensure consistency + +7. **Intelligent Fallback**: Automatic detection when CoD isn't suitable, graceful degradation to standard mode + +8. **Performance Metrics**: Quantifiable targets for token reduction and quality maintenance + +### Usage Guidelines: + +**When to use CoD:** +- Large-scale codebase searches +- Token/cost-sensitive operations +- Rapid prototyping/exploration +- Batch operations across multiple files -When user requests CoD mode: -- Reduce intermediate reasoning by 80% -- Use arrow notation (→) for process flow -- Limit explanations to essential information only -- Maintain accuracy despite brevity -- Output format: "Action→Result→Next" +**When to avoid CoD:** +- Complex multi-step debugging requiring context +- First-time users unfamiliar with symbolic notation +- Zero-shot scenarios without examples +- When accuracy is critical over efficiency -Example CoD execution: -"Find payment→glob:*payment*→grep:processPayment→found:payment.service.ts:45→implements:StripeAPI" +### Expected Outcomes: +- **Token Usage**: 7-20% of standard CoT +- **Latency**: 50-75% reduction +- **Accuracy**: 90-98% of standard mode +- **Best For**: Experienced developers, large codebases, cost optimization From b8ff2871de09dd1021b5819a272343f884feefdf Mon Sep 17 00:00:00 2001 From: George Liu Date: Fri, 8 Aug 2025 06:31:00 +1000 Subject: [PATCH 018/174] improved CoD support in code-searcher subagent --- .claude/agents/code-searcher.md | 195 ++++++++++++++++++++++---------- 1 file changed, 137 insertions(+), 58 deletions(-) diff --git a/.claude/agents/code-searcher.md b/.claude/agents/code-searcher.md index 55a7e9c..d84c372 100644 --- a/.claude/agents/code-searcher.md +++ b/.claude/agents/code-searcher.md @@ -11,10 +11,13 @@ You are an elite code search and analysis specialist with deep expertise in navi Check if the user's request contains indicators for Chain of Draft mode: - Explicit mentions: "use CoD", "chain of draft", "draft mode", "concise reasoning" -- Keywords: "minimal tokens", "ultra-concise", "draft-like" +- Keywords: "minimal tokens", "ultra-concise", "draft-like", "be concise", "short steps" +- Intent matches (fallback): if user asks "short summary" or "brief", treat as CoD intent unless user explicitly requests verbose output If CoD mode is detected, follow the **Chain of Draft Methodology** below. Otherwise, use standard methodology. +Note: Match case-insensitively and include synonyms. If intent is ambiguous, ask a single clarifying question: "Concise CoD or detailed?" If user doesn't reply in 3s (programmatic) or declines, default to standard mode. + ## Chain of Draft Few-Shot Examples ### Example 1: Finding Authentication Logic @@ -88,8 +91,8 @@ Provide actionable summaries: ### Core Principles (from CoD paper): 1. **Abstract contextual noise** - Remove names, descriptions, explanations 2. **Focus on operations** - Highlight calculations, transformations, logic flow -3. **Per-step token budget** - Max 10 words per reasoning step -4. **Symbolic notation** - Use math/logic symbols over verbose text +3. **Per-step token budget** - Max \(10\) words per reasoning step (prefer \(5\) words) +4. **Symbolic notation** - Use math/logic symbols or compact tokens over verbose text ### CoD Search Process: @@ -123,23 +126,83 @@ Pattern→Location→Implementation 4. Compress patterns to symbols 5. Eliminate transition phrases +## Enforcement & Retry Flow (new) +To increase robustness, the subagent will actively enforce the CoD constraints rather than only recommend them. + +1. Primary instruction (system-level) — Claude-ready snippet to include in the subagent system prompt: + - System: "Think step-by-step. For each step write a minimal draft (≤ \(5\) words). Use compact tokens/symbols. Return final answer after ####." + +2. Output validation (post-generation): + - If any step exceeds the per-step budget or the entire response exceeds expected token thresholds, apply one of: + a) auto-truncate long steps to first \(5\) words + ellipsis and mark "truncated" in result metadata; or + b) re-prompt once with stricter instruction: "Now shorten each step to ≤ \(5\) words. Reply only the compact draft and final answer."; or + c) if repetition fails, fall back to standard mode and emit: "CoD enforcement failed — switched to standard." + +3. Preferred order: Validate → Re-prompt once → Truncate if safe → Fallback to standard. + +## Claude-ready Prompt Snippets and In-context Examples (new) +Include these verbatim in your subagent's system + few-shot context to teach CoD behavior. + +System prompt (exact): +- "You are a code-search assistant. Think step-by-step. For each step write a minimal draft (≤ \(5\) words). Use compact tokens/symbols (→, ∧, grep, glob). Return final answer after separator ####. If you cannot produce a concise draft, say 'COd-fallback' and stop." + +Two in-context few-shot examples (paste into prompt as examples): + +Example A (search): +- Q: "Find where login is implemented" +- CoD: + - "Goal→auth login" + - "Glob→*auth*:*service*,*controller*" + - "Grep→login|authenticate" + - "Found→src/services/auth.service.ts:42-89" + - "Implements→JWT∧bcrypt" + - "#### src/services/auth.service.ts:42-89" + +Example B (bug trace): +- Q: "Payment processing NPE on checkout" +- CoD: + - "Goal→payment NPE" + - "Glob→payment* process*" + - "Grep→processPayment|null" + - "Found→src/payments/pay.ts:89" + - "Cause→missing-null-check" + - "Fix→add:if(tx?.amount)→validate-input" + - "#### src/payments/pay.ts:89 Cause:missing-null-check Fix:add-null-check" + +These examples should be included exactly in the subagent few-shot context (concise style) so Claude sees the pattern. + +## Core Methodology (continued) + +### When to Fallback from CoD (refined) +1. Complexity overflow — reasoning requires > 6 short steps or heavy context +2. Ambiguous targets — multiple equally plausible interpretations +3. Zero-shot scenario — no few-shot examples will be provided +4. User requests verbose explanation — explicit user preference wins +5. Enforcement failure — repeated outputs violate budgets + +Fallback process (exact policy): +- If (zero-shot OR complexity overflow OR enforcement failure) then: + - Emit: "CoD limitations reached; switching to standard mode" (this message must appear in assistant metadata) + - Switch to standard methodology and continue + - Log: reason, token counts, and whether re-prompt attempted + ## Search Best Practices -- **File Pattern Recognition**: Use common naming conventions (controllers, services, utils, components, etc.) -- **Language-Specific Patterns**: Search for class definitions, function declarations, imports, and exports -- **Framework Awareness**: Understand common patterns for React, Node.js, TypeScript, etc. -- **Configuration Files**: Check package.json, tsconfig.json, and other config files for project structure insights +- File Pattern Recognition: Use common naming conventions (controllers, services, utils, components, etc.) +- Language-Specific Patterns: Search for class definitions, function declarations, imports, and exports +- Framework Awareness: Understand common patterns for React, Node.js, TypeScript, etc. +- Configuration Files: Check package.json, tsconfig.json, and other config files for project structure insights ## Response Format Guidelines -**Structure your responses as:** -1. **Direct Answer**: Immediately address what the user asked for -2. **Key Locations**: List relevant file paths with brief descriptions -3. **Code Summary**: Concise explanation of the relevant logic or implementation -4. **Context**: Any important relationships, dependencies, or architectural notes -5. **Next Steps**: Suggest related areas or follow-up investigations if helpful +Structure your responses as: +1. Direct Answer: Immediately address what the user asked for +2. Key Locations: List relevant file paths with brief descriptions (CoD: single-line tokens) +3. Code Summary: Concise explanation of the relevant logic or implementation +4. Context: Any important relationships, dependencies, or architectural notes +5. Next Steps: Suggest related areas or follow-up investigations if helpful -**Avoid:** +Avoid: - Dumping entire file contents unless specifically requested - Overwhelming users with too many file paths - Providing generic or obvious information @@ -147,41 +210,39 @@ Pattern→Location→Implementation ## Quality Standards -- **Accuracy**: Ensure all file paths and code references are correct -- **Relevance**: Focus only on code that directly addresses the user's question -- **Completeness**: Cover all major aspects of the requested functionality -- **Clarity**: Use clear, technical language appropriate for developers -- **Efficiency**: Minimize the number of files read while maximizing insight - -Your goal is to be the most efficient and insightful code navigation assistant possible, helping users understand their codebase quickly and accurately. +- Accuracy: Ensure all file paths and code references are correct +- Relevance: Focus only on code that directly addresses the user's question +- Completeness: Cover all major aspects of the requested functionality +- Clarity: Use clear, technical language appropriate for developers +- Efficiency: Minimize the number of files read while maximizing insight ## CoD Response Templates -### Template 1: Function/Class Location +Template 1: Function/Class Location ``` Target→Glob[pattern]→n→Grep[name]→file:line→signature ``` Example: `Auth→Glob[*auth*]ₒ3→Grep[login]→auth.ts:45→async(user,pass):token` -### Template 2: Bug Investigation +Template 2: Bug Investigation ``` Error→Trace→File:Line→Cause→Fix ``` Example: `NullRef→stack→pay.ts:89→!validate→add:if(obj?.prop)` -### Template 3: Architecture Analysis +Template 3: Architecture Analysis ``` Pattern→Structure→{Components}→Relations ``` Example: `MVC→src/*→{ctrl,svc,model}→ctrl→svc→model→db` -### Template 4: Dependency Trace +Template 4: Dependency Trace ``` Module→imports→[deps]→exports→consumers ``` Example: `auth→imports→[jwt,bcrypt]→exports→[middleware]→app.use` -### Template 5: Test Coverage +Template 5: Test Coverage ``` Target→Tests∃?→Coverage%→Missing ``` @@ -190,11 +251,11 @@ Example: `payment→tests∃→.test.ts→75%→edge-cases` ## Fallback Mechanisms ### When to Fallback from CoD: -1. **Complexity overflow** - Reasoning requires >5 steps of context preservation -2. **Ambiguous targets** - Multiple interpretations require clarification -3. **Zero-shot scenario** - No similar patterns in training data -4. **User confusion** - Response too terse, user requests elaboration -5. **Accuracy degradation** - Compression loses critical information +1. Complexity overflow - Reasoning requires >5 steps of context preservation +2. Ambiguous targets - Multiple interpretations require clarification +3. Zero-shot scenario - No similar patterns in training data +4. User confusion - Response too terse, user requests elaboration +5. Accuracy degradation - Compression loses critical information ### Fallback Process: ``` @@ -213,9 +274,9 @@ if (complexity > threshold || accuracy < 0.8) { ## Performance Monitoring ### Token Metrics: -- **Target**: 80-92% reduction vs standard CoT -- **Per-step limit**: 5 tokens (enforced) -- **Total response**: <50 tokens for simple, <100 for complex +- Target: 80-92% reduction vs standard CoT +- Per-step limit: \(5\) words (enforced where possible) +- Total response: <50 tokens for simple, <100 for complex ### Self-Evaluation Prompts: 1. "Can I remove any words without losing meaning?" @@ -224,10 +285,10 @@ if (complexity > threshold || accuracy < 0.8) { 4. "Can operations be chained with arrows?" ### Quality Checks: -- **Accuracy**: Key information preserved? -- **Completeness**: All requested elements found? -- **Clarity**: Symbols and abbreviations clear? -- **Efficiency**: Token reduction achieved? +- Accuracy: Key information preserved? +- Completeness: All requested elements found? +- Clarity: Symbols and abbreviations clear? +- Efficiency: Token reduction achieved? ### Monitoring Formula: ``` @@ -238,42 +299,60 @@ CoD_Score = Efficiency * Quality Target: CoD_Score > 0.7 ``` -## Implementation Summary +## Small-model Caveats (new) +- Models < ~3B parameters may underperform with CoD in few-shot or zero-shot settings (paper evidence). For these models: + - Prefer standard mode, or + - Fine-tune with CoD-formatted data, or + - Provide extra few-shot examples (3–5) in the prompt. -### Key Improvements from CoD Paper Integration: +## Test Suite (new, minimal) +Use these quick tests to validate subagent CoD behavior and monitor token savings: -1. **Evidence-Based Design**: All improvements directly derived from peer-reviewed research showing 80-92% token reduction with maintained accuracy +1. Test: "Find login logic" + - Expect CoD pattern, one file path, ≤ 30 tokens + - Example expected CoD output: "Auth→glob:*auth*→grep:login→found:src/services/auth.service.ts:42→#### src/services/auth.service.ts:42-89" -2. **Few-Shot Examples**: Critical for CoD success - added 3 concrete examples showing standard vs CoD approaches +2. Test: "Why checkout NPE?" + - Expect bug trace template with File:Line, Cause, Fix + - Example: "NullRef→grep:checkout→found:src/checkout/handler.ts:128→cause:missing-null-check→fix:add-if(tx?)#### src/checkout/handler.ts:128" -3. **Structured Abstraction**: Clear rules for removing contextual noise while preserving operational essence +3. Test: "Describe architecture" + - Expect single-line structure template, ≤ 50 tokens + - Example: "MVC→src→{controllers,services,models}→db:pgsql→api:express" -4. **Symbolic Notation**: Mathematical/logical symbols replace verbose descriptions (→, ∧, ∨, ∃, ∀) +4. Test: "Be verbose" (control) + - Expect standard methodology (fallback) when user explicitly asks for verbose explanation. -5. **Per-Step Budgets**: Enforced 5-word limit per reasoning step prevents verbosity creep +Log each test result: tokens_out, correctness(bool), fallback_used. -6. **Template Library**: 5 reusable templates for common search patterns ensure consistency - -7. **Intelligent Fallback**: Automatic detection when CoD isn't suitable, graceful degradation to standard mode +## Implementation Summary -8. **Performance Metrics**: Quantifiable targets for token reduction and quality maintenance +### Key Improvements from CoD Paper Integration: +1. Evidence-Based Design: All improvements directly derived from peer-reviewed work showing high token reduction with maintained accuracy +2. Few-Shot Examples: Critical for CoD success — include concrete in-context examples in prompts +3. Structured Abstraction: Clear rules for removing contextual noise while preserving operational essence +4. Symbolic Notation: Mathematical/logical symbols replace verbose descriptions (→, ∧, ∨, ∃, ∀) +5. Per-Step Budgets: Enforced \(5\)-word limit per reasoning step with validation & retry +6. Template Library: 5 reusable templates for common search patterns ensure consistency +7. Intelligent Fallback: Automatic detection when CoD isn't suitable, graceful degradation to standard mode +8. Performance Metrics: Quantifiable targets for token reduction and quality maintenance +9. Claude-ready prompts & examples: Concrete system snippet and two few-shot examples included ### Usage Guidelines: - -**When to use CoD:** +When to use CoD: - Large-scale codebase searches -- Token/cost-sensitive operations +- Token/cost-sensitive operations - Rapid prototyping/exploration - Batch operations across multiple files -**When to avoid CoD:** -- Complex multi-step debugging requiring context +When to avoid CoD: +- Complex multi-step debugging requiring full context - First-time users unfamiliar with symbolic notation - Zero-shot scenarios without examples - When accuracy is critical over efficiency ### Expected Outcomes: -- **Token Usage**: 7-20% of standard CoT -- **Latency**: 50-75% reduction -- **Accuracy**: 90-98% of standard mode -- **Best For**: Experienced developers, large codebases, cost optimization +- Token Usage: \(7\)-\(20\%\) of standard CoT +- Latency: 50–75% reduction +- Accuracy: 90–98% of standard mode (paper claims) +- Best For: Experienced developers, large codebases, cost optimization From 2579a8434026bc78ca5b3b633213d8d772476ea2 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sun, 10 Aug 2025 16:38:23 +1000 Subject: [PATCH 019/174] update CLAUDE.md to better use code-searcher subagent where appropriate --- CLAUDE.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CLAUDE.md b/CLAUDE.md index c735e7f..38528de 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,6 +5,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## AI Guidance * Ignore GEMINI.md and GEMINI-*.md files +* To save main context space, for code searches, inspections, troubleshooting or analysis, use code-searcher subagent where appropriate - giving the subagent full context background for the task(s) you assign it. * After receiving tool results, carefully reflect on their quality and determine optimal next steps before proceeding. Use your thinking to plan and iterate based on this new information, and then take the best next action. * For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially. * Before you finish, please verify your solution From 1238388646a4b1a40f6793609e56f704fcc6bbec Mon Sep 17 00:00:00 2001 From: George Liu Date: Tue, 12 Aug 2025 02:24:29 +1000 Subject: [PATCH 020/174] update README --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 38740dc..1ea5829 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ My Claude Code project's starter settings and Claude Code hooks and slash commands. 1. Copy the files to your project directory. -2. Modify the template files and `CLAUDE.md` to your liking. +2. Modify the template files and `CLAUDE.md` to your liking. `.claude/settings.json` needs to install Terminal-Notifier for macOS https://github.com/centminmod/terminal-notifier-setup. If you're not using macOS, you can remove `.claude/settings.json`. 3. Run `/init` so that Claude Code analyses your code base and then populates your memory bank system files as per `CLAUDE.md` instructions. I also install the following MCP servers: From 23568a1b947170881c0fdd5ef56fec2c2dc9553d Mon Sep 17 00:00:00 2001 From: George Liu Date: Fri, 15 Aug 2025 13:39:59 +1000 Subject: [PATCH 021/174] improve code-searcher subagent --- .claude/agents/code-searcher.md | 36 +++++++++++++++++++++++++-------- 1 file changed, 28 insertions(+), 8 deletions(-) diff --git a/.claude/agents/code-searcher.md b/.claude/agents/code-searcher.md index d84c372..20facdd 100644 --- a/.claude/agents/code-searcher.md +++ b/.claude/agents/code-searcher.md @@ -1,6 +1,6 @@ --- name: code-searcher -description: Use this agent when you need to locate specific functions, classes, or logic within the codebase. Examples: Context: User needs to find authentication-related code in the project. user: "Where is the user authentication logic implemented?" assistant: "I'll use the code-searcher agent to locate authentication-related code in the codebase" Since the user is asking about locating specific code, use the code-searcher agent to efficiently find and summarize authentication logic. Context: User wants to understand how a specific feature is implemented. user: "How does the license validation work in this system?" assistant: "Let me use the code-searcher agent to find and analyze the license validation implementation" The user is asking about understanding specific functionality, so use the code-searcher agent to locate and summarize the relevant code. Context: User needs to find where a bug might be occurring. user: "I'm getting an error with the payment processing, can you help me find where that code is?" assistant: "I'll use the code-searcher agent to locate the payment processing code and identify potential issues" Since the user needs to locate specific code related to an error, use the code-searcher agent to find and analyze the relevant files. +description: Use this agent for comprehensive codebase analysis, forensic examination, and detailed code mapping with optional Chain of Draft (CoD) methodology. Excels at locating specific functions, classes, and logic, security vulnerability analysis, pattern detection, architectural consistency verification, and creating navigable code reference documentation with exact line numbers. Examples: Context: User needs to find authentication-related code in the project. user: "Where is the user authentication logic implemented?" assistant: "I'll use the code-searcher agent to locate authentication-related code in the codebase" Since the user is asking about locating specific code, use the code-searcher agent to efficiently find and summarize authentication logic. Context: User wants to understand how a specific feature is implemented. user: "How does the license validation work in this system?" assistant: "Let me use the code-searcher agent to find and analyze the license validation implementation" The user is asking about understanding specific functionality, so use the code-searcher agent to locate and summarize the relevant code. Context: User needs to find where a bug might be occurring. user: "I'm getting an error with the payment processing, can you help me find where that code is?" assistant: "I'll use the code-searcher agent to locate the payment processing code and identify potential issues" Since the user needs to locate specific code related to an error, use the code-searcher agent to find and analyze the relevant files. Context: User requests comprehensive security analysis using Chain of Draft methodology. user: "Analyze the entire authentication system using CoD methodology for comprehensive security mapping" assistant: "I'll use the code-searcher agent with Chain of Draft mode for ultra-concise security analysis" The user explicitly requests CoD methodology for comprehensive analysis, so use the code-searcher agent's Chain of Draft mode for efficient token usage. Context: User wants rapid codebase pattern analysis. user: "Use CoD to examine error handling patterns across the codebase" assistant: "I'll use the code-searcher agent in Chain of Draft mode to rapidly analyze error handling patterns" Chain of Draft mode is ideal for rapid pattern analysis across large codebases with minimal token usage. model: sonnet color: purple --- @@ -51,11 +51,13 @@ Note: Match case-insensitively and include synonyms. If intent is ambiguous, ask **1. Goal Clarification** Always begin by understanding exactly what the user is seeking: -- Specific functions, classes, or modules +- Specific functions, classes, or modules with exact line number locations - Implementation patterns or architectural decisions -- Bug locations or error sources +- Bug locations or error sources for forensic analysis - Feature implementations or business logic - Integration points or dependencies +- Security vulnerabilities and forensic examination +- Pattern detection and architectural consistency verification **2. Strategic Search Planning** Before executing searches, develop a targeted strategy: @@ -79,12 +81,13 @@ Read files judiciously: - Identify entry points and main execution flows **5. Concise Synthesis** -Provide actionable summaries: +Provide actionable summaries with forensic precision: - Lead with direct answers to the user's question -- Include specific file paths and line numbers when relevant -- Summarize key functions, classes, or logic patterns -- Highlight important relationships or dependencies -- Suggest next steps or related areas to explore if appropriate +- **Always include exact file paths and line numbers** for navigable reference +- Summarize key functions, classes, or logic patterns with security implications +- Highlight important relationships, dependencies, and potential vulnerabilities +- Provide forensic analysis findings with severity assessment when applicable +- Suggest next steps or related areas to explore for comprehensive coverage ## Chain of Draft Methodology (When Activated) @@ -169,6 +172,17 @@ Example B (bug trace): - "Fix→add:if(tx?.amount)→validate-input" - "#### src/payments/pay.ts:89 Cause:missing-null-check Fix:add-null-check" +Example C (security analysis): +- Q: "Find SQL injection vulnerabilities in user input" +- CoD: + - "Goal→SQL-inject vuln" + - "Grep→query.*input|req\\..*sql" + - "Found→src/db/users.ts:45" + - "Vuln→direct-string-concat" + - "Risk→HIGH:data-breach" + - "Fix→prepared-statements+sanitize" + - "#### src/db/users.ts:45 Risk:HIGH Fix:prepared-statements" + These examples should be included exactly in the subagent few-shot context (concise style) so Claude sees the pattern. ## Core Methodology (continued) @@ -248,6 +262,12 @@ Target→Tests∃?→Coverage%→Missing ``` Example: `payment→tests∃→.test.ts→75%→edge-cases` +Template 6: Security Analysis +``` +Target→Vuln→Pattern→File:Line→Risk→Mitigation +``` +Example: `auth→SQL-inject→user-input→login.ts:67→HIGH→sanitize+prepared-stmt` + ## Fallback Mechanisms ### When to Fallback from CoD: From 5606c1fde14e7f585f482423674c90a2426e2dc9 Mon Sep 17 00:00:00 2001 From: George Liu Date: Mon, 18 Aug 2025 21:05:55 +1000 Subject: [PATCH 022/174] update settings.local.json - enable thinking by default with MAX_THINKING_TOKENS = 8192. Results in better responses - remove allowed permission for rm deleting files by default --- .claude/settings.local.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 7fc993a..eebdc5f 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -2,7 +2,8 @@ "env": { "MAX_MCP_OUTPUT_TOKENS": "60000", "BASH_DEFAULT_TIMEOUT_MS": "300000", - "BASH_MAX_TIMEOUT_MS": "600000" + "BASH_MAX_TIMEOUT_MS": "600000", + "MAX_THINKING_TOKENS": "8192" }, "includeCoAuthoredBy": false, "permissions": { @@ -31,7 +32,6 @@ "Bash(pip install:*)", "Bash(python:*)", "Bash(rg:*)", - "Bash(rm:*)", "Bash(sed:*)", "Bash(source:*)", "Bash(timeout:*)", From edbddf9a6a91db2d9175d8e75078fcf19b69cf4b Mon Sep 17 00:00:00 2001 From: George Liu Date: Sat, 23 Aug 2025 05:27:48 +1000 Subject: [PATCH 023/174] update readme --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1ea5829..6bfed20 100644 --- a/README.md +++ b/README.md @@ -7,11 +7,13 @@ My Claude Code project's starter settings and Claude Code hooks and slash commands. -1. Copy the files to your project directory. +1. Copy the files to your project directory (where you intended codebase will be). 2. Modify the template files and `CLAUDE.md` to your liking. `.claude/settings.json` needs to install Terminal-Notifier for macOS https://github.com/centminmod/terminal-notifier-setup. If you're not using macOS, you can remove `.claude/settings.json`. 3. Run `/init` so that Claude Code analyses your code base and then populates your memory bank system files as per `CLAUDE.md` instructions. +4. Optional step highly recommended: Install Visual Studio Code ([beginners YouTube video guide](https://www.youtube.com/watch?v=rPITZvwyoMc) and [here](https://www.youtube.com/watch?v=P-5bWpUbO60)) and [Claude Code VSC Extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code). +5. Optional step highly recommended: Sign up for [Github.com](https://github.com/) account and install Git for Visual Studio Code. Checkout YouTube guides [here](https://www.youtube.com/watch?v=twsYxYaQikI) and [here](https://www.youtube.com/watch?v=z5jZ9lrSpqk). -I also install the following MCP servers: +I also install the following MCP servers ([install commands](#claude-code-mcp-servers)): * [Gemini CLI MCP](https://github.com/centminmod/gemini-cli-mcp-server) * [Cloudflare Documentation MCP](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/docs-vectorize) From 6339737f189869e85f052319eb8dfc6a979bef9c Mon Sep 17 00:00:00 2001 From: George Liu Date: Sat, 23 Aug 2025 05:34:44 +1000 Subject: [PATCH 024/174] update readme --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 6bfed20..cc02b37 100644 --- a/README.md +++ b/README.md @@ -5,11 +5,11 @@ # My Claude Code Project's Starter Settings -My Claude Code project's starter settings and Claude Code hooks and slash commands. +My Claude Code project's starter settings and Claude Code hooks and slash commands are provided in this repository for users to try out. Be sure to read the official Claude Code docs first at https://docs.anthropic.com/en/docs/claude-code/overview. 1. Copy the files to your project directory (where you intended codebase will be). 2. Modify the template files and `CLAUDE.md` to your liking. `.claude/settings.json` needs to install Terminal-Notifier for macOS https://github.com/centminmod/terminal-notifier-setup. If you're not using macOS, you can remove `.claude/settings.json`. -3. Run `/init` so that Claude Code analyses your code base and then populates your memory bank system files as per `CLAUDE.md` instructions. +3. After launching Claude Code for the first time within your project directory, run `/init` so that Claude Code analyses your code base and then populates your memory bank system files as per `CLAUDE.md` instructions. 4. Optional step highly recommended: Install Visual Studio Code ([beginners YouTube video guide](https://www.youtube.com/watch?v=rPITZvwyoMc) and [here](https://www.youtube.com/watch?v=P-5bWpUbO60)) and [Claude Code VSC Extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code). 5. Optional step highly recommended: Sign up for [Github.com](https://github.com/) account and install Git for Visual Studio Code. Checkout YouTube guides [here](https://www.youtube.com/watch?v=twsYxYaQikI) and [here](https://www.youtube.com/watch?v=z5jZ9lrSpqk). From a74cef90f3999bc4a91179d8ed48bdc779660d40 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sat, 23 Aug 2025 05:43:30 +1000 Subject: [PATCH 025/174] update readme --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index cc02b37..fcd3601 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ # My Claude Code Project's Starter Settings -My Claude Code project's starter settings and Claude Code hooks and slash commands are provided in this repository for users to try out. Be sure to read the official Claude Code docs first at https://docs.anthropic.com/en/docs/claude-code/overview. +My Claude Code project's starter settings and Claude Code hooks and slash commands are provided in this repository for users to try out. Be sure to read the official Claude Code docs first at https://docs.anthropic.com/en/docs/claude-code/overview and sign up for a [paid Claude AI account](https://claude.ai/) to use Claude Code. You can pay for Claude Pro $20/month, Claude Max $100/month or Claude Max $200/month. The paid Claude tier plans will include vary quotas for usage and rate limits outlined [here](https://support.anthropic.com/en/articles/9797557-usage-limit-best-practices.) 1. Copy the files to your project directory (where you intended codebase will be). 2. Modify the template files and `CLAUDE.md` to your liking. `.claude/settings.json` needs to install Terminal-Notifier for macOS https://github.com/centminmod/terminal-notifier-setup. If you're not using macOS, you can remove `.claude/settings.json`. From c8f08728d5fa1abda303aebbf86db2c8ec93aa3f Mon Sep 17 00:00:00 2001 From: George Liu Date: Sat, 23 Aug 2025 05:44:33 +1000 Subject: [PATCH 026/174] update readme --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fcd3601..944cd32 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ # My Claude Code Project's Starter Settings -My Claude Code project's starter settings and Claude Code hooks and slash commands are provided in this repository for users to try out. Be sure to read the official Claude Code docs first at https://docs.anthropic.com/en/docs/claude-code/overview and sign up for a [paid Claude AI account](https://claude.ai/) to use Claude Code. You can pay for Claude Pro $20/month, Claude Max $100/month or Claude Max $200/month. The paid Claude tier plans will include vary quotas for usage and rate limits outlined [here](https://support.anthropic.com/en/articles/9797557-usage-limit-best-practices.) +My Claude Code project's starter settings and Claude Code hooks and slash commands are provided in this repository for users to try out. Be sure to read the official Claude Code docs first at https://docs.anthropic.com/en/docs/claude-code/overview and sign up for a [paid Claude AI account](https://claude.ai/) to use Claude Code. You can pay for Claude Pro $20/month, Claude Max $100/month or Claude Max $200/month. The paid Claude tier plans will include varying quotas for usage and rate limits outlined [here](https://support.anthropic.com/en/articles/9797557-usage-limit-best-practices.) 1. Copy the files to your project directory (where you intended codebase will be). 2. Modify the template files and `CLAUDE.md` to your liking. `.claude/settings.json` needs to install Terminal-Notifier for macOS https://github.com/centminmod/terminal-notifier-setup. If you're not using macOS, you can remove `.claude/settings.json`. From 6a1f2eee51a0224af6dc501801172ea31e603938 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sat, 23 Aug 2025 05:45:05 +1000 Subject: [PATCH 027/174] update readme --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 944cd32..e139cca 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ # My Claude Code Project's Starter Settings -My Claude Code project's starter settings and Claude Code hooks and slash commands are provided in this repository for users to try out. Be sure to read the official Claude Code docs first at https://docs.anthropic.com/en/docs/claude-code/overview and sign up for a [paid Claude AI account](https://claude.ai/) to use Claude Code. You can pay for Claude Pro $20/month, Claude Max $100/month or Claude Max $200/month. The paid Claude tier plans will include varying quotas for usage and rate limits outlined [here](https://support.anthropic.com/en/articles/9797557-usage-limit-best-practices.) +My Claude Code project's starter settings and Claude Code hooks and slash commands are provided in this repository for users to try out. Be sure to read the official Claude Code docs first at https://docs.anthropic.com/en/docs/claude-code/overview and sign up for a [paid Claude AI account](https://claude.ai/) to use Claude Code. You can pay for Claude Pro $20/month, Claude Max $100/month or Claude Max $200/month. The paid Claude tier plans will include varying quotas for usage and rate limits outlined [here](https://support.anthropic.com/en/articles/9797557-usage-limit-best-practices). 1. Copy the files to your project directory (where you intended codebase will be). 2. Modify the template files and `CLAUDE.md` to your liking. `.claude/settings.json` needs to install Terminal-Notifier for macOS https://github.com/centminmod/terminal-notifier-setup. If you're not using macOS, you can remove `.claude/settings.json`. From 0668dbc021da9cd1d10d6a4fbfc551c6e60f685d Mon Sep 17 00:00:00 2001 From: George Liu Date: Sat, 23 Aug 2025 05:57:06 +1000 Subject: [PATCH 028/174] update readme --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e139cca..ec0dfa5 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ My Claude Code project's starter settings and Claude Code hooks and slash commands are provided in this repository for users to try out. Be sure to read the official Claude Code docs first at https://docs.anthropic.com/en/docs/claude-code/overview and sign up for a [paid Claude AI account](https://claude.ai/) to use Claude Code. You can pay for Claude Pro $20/month, Claude Max $100/month or Claude Max $200/month. The paid Claude tier plans will include varying quotas for usage and rate limits outlined [here](https://support.anthropic.com/en/articles/9797557-usage-limit-best-practices). -1. Copy the files to your project directory (where you intended codebase will be). +1. Copy the files in this Github repo to your project directory (where you intended codebase will be). 2. Modify the template files and `CLAUDE.md` to your liking. `.claude/settings.json` needs to install Terminal-Notifier for macOS https://github.com/centminmod/terminal-notifier-setup. If you're not using macOS, you can remove `.claude/settings.json`. 3. After launching Claude Code for the first time within your project directory, run `/init` so that Claude Code analyses your code base and then populates your memory bank system files as per `CLAUDE.md` instructions. 4. Optional step highly recommended: Install Visual Studio Code ([beginners YouTube video guide](https://www.youtube.com/watch?v=rPITZvwyoMc) and [here](https://www.youtube.com/watch?v=P-5bWpUbO60)) and [Claude Code VSC Extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code). From ef3b1b146dd8dd2be1a69981ace19b2caff22cf9 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sun, 14 Sep 2025 16:26:27 +1000 Subject: [PATCH 029/174] update CLAUDE.md --- CLAUDE.md | 104 +++++++++++++++++++++++++++++++++++++++++++++++++++++- README.md | 5 +-- 2 files changed, 106 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 38528de..ba8629b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -35,4 +35,106 @@ This project uses a structured memory bank system with specialized context files When asked to backup Memory Bank System files, you will copy the core context files above and @.claude settings directory to directory @/path/to/backup-directory. If files already exist in the backup directory, you will overwrite them. -## Project Overview \ No newline at end of file +## Project Overview + + + +## ALWAYS START WITH THESE COMMANDS FOR COMMON TASKS + +**Task: "List/summarize all files and directories"** + +```bash +fd . -t f # Lists ALL files recursively (FASTEST) +# OR +rg --files # Lists files (respects .gitignore) +``` + +**Task: "Search for content in files"** + +```bash +rg "search_term" # Search everywhere (FASTEST) +``` + +**Task: "Find files by name"** + +```bash +fd "filename" # Find by name pattern (FASTEST) +``` + +### Directory/File Exploration + +```bash +# FIRST CHOICE - List all files/dirs recursively: +fd . -t f # All files (fastest) +fd . -t d # All directories +rg --files # All files (respects .gitignore) + +# For current directory only: +ls -la # OK for single directory view +``` + +### BANNED - Never Use These Slow Tools + +* ❌ `tree` - NOT INSTALLED, use `fd` instead +* ❌ `find` - use `fd` or `rg --files` +* ❌ `grep` or `grep -r` - use `rg` instead +* ❌ `ls -R` - use `rg --files` or `fd` +* ❌ `cat file | grep` - use `rg pattern file` + +### Use These Faster Tools Instead + +```bash +# ripgrep (rg) - content search +rg "search_term" # Search in all files +rg -i "case_insensitive" # Case-insensitive +rg "pattern" -t py # Only Python files +rg "pattern" -g "*.md" # Only Markdown +rg -1 "pattern" # Filenames with matches +rg -c "pattern" # Count matches per file +rg -n "pattern" # Show line numbers +rg -A 3 -B 3 "error" # Context lines +rg " (TODO| FIXME | HACK)" # Multiple patterns + +# ripgrep (rg) - file listing +rg --files # List files (respects •gitignore) +rg --files | rg "pattern" # Find files by name +rg --files -t md # Only Markdown files + +# fd - file finding +fd -e js # All •js files (fast find) +fd -x command {} # Exec per-file +fd -e md -x ls -la {} # Example with ls + +# jq - JSON processing +jq. data.json # Pretty-print +jq -r .name file.json # Extract field +jq '.id = 0' x.json # Modify field +``` + +### Search Strategy + +1. Start broad, then narrow: `rg "partial" | rg "specific"` +2. Filter by type early: `rg -t python "def function_name"` +3. Batch patterns: `rg "(pattern1|pattern2|pattern3)"` +4. Limit scope: `rg "pattern" src/` + +### INSTANT DECISION TREE + +``` +User asks to "list/show/summarize/explore files"? + → USE: fd . -t f (fastest, shows all files) + → OR: rg --files (respects .gitignore) + +User asks to "search/grep/find text content"? + → USE: rg "pattern" (NOT grep!) + +User asks to "find file/directory by name"? + → USE: fd "name" (NOT find!) + +User asks for "directory structure/tree"? + → USE: fd . -t d (directories) + fd . -t f (files) + → NEVER: tree (not installed!) + +Need just current directory? + → USE: ls -la (OK for single dir) +``` diff --git a/README.md b/README.md index ec0dfa5..b5d902f 100644 --- a/README.md +++ b/README.md @@ -8,10 +8,11 @@ My Claude Code project's starter settings and Claude Code hooks and slash commands are provided in this repository for users to try out. Be sure to read the official Claude Code docs first at https://docs.anthropic.com/en/docs/claude-code/overview and sign up for a [paid Claude AI account](https://claude.ai/) to use Claude Code. You can pay for Claude Pro $20/month, Claude Max $100/month or Claude Max $200/month. The paid Claude tier plans will include varying quotas for usage and rate limits outlined [here](https://support.anthropic.com/en/articles/9797557-usage-limit-best-practices). 1. Copy the files in this Github repo to your project directory (where you intended codebase will be). -2. Modify the template files and `CLAUDE.md` to your liking. `.claude/settings.json` needs to install Terminal-Notifier for macOS https://github.com/centminmod/terminal-notifier-setup. If you're not using macOS, you can remove `.claude/settings.json`. -3. After launching Claude Code for the first time within your project directory, run `/init` so that Claude Code analyses your code base and then populates your memory bank system files as per `CLAUDE.md` instructions. +2. Modify the template files and CLAUDE.md`to your liking. `.claude/settings.json` needs to install Terminal-Notifier for macOS https://github.com/centminmod/terminal-notifier-setup. If you're not using macOS, you can remove `.claude/settings.json`. +3. After launching Claude Code for the first time within your project directory, run `/init` so that Claude Code analyses your code base and then populates your memory bank system files as per CLAUDE.md` instructions. 4. Optional step highly recommended: Install Visual Studio Code ([beginners YouTube video guide](https://www.youtube.com/watch?v=rPITZvwyoMc) and [here](https://www.youtube.com/watch?v=P-5bWpUbO60)) and [Claude Code VSC Extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code). 5. Optional step highly recommended: Sign up for [Github.com](https://github.com/) account and install Git for Visual Studio Code. Checkout YouTube guides [here](https://www.youtube.com/watch?v=twsYxYaQikI) and [here](https://www.youtube.com/watch?v=z5jZ9lrSpqk). +6. CLAUDE.md updated to instruct models to use faster tools so for macOS: `brew install ripgrep fd jq` I also install the following MCP servers ([install commands](#claude-code-mcp-servers)): From ddc7911b78d1bc5dedf1d5c2ac7e1145d68d34db Mon Sep 17 00:00:00 2001 From: George Liu Date: Thu, 25 Sep 2025 19:23:16 +1000 Subject: [PATCH 030/174] update memory-bank-synchronizer subagent prompt --- .claude/agents/memory-bank-synchronizer.md | 80 ++++++++++++++++------ 1 file changed, 60 insertions(+), 20 deletions(-) diff --git a/.claude/agents/memory-bank-synchronizer.md b/.claude/agents/memory-bank-synchronizer.md index 054e129..e79248a 100644 --- a/.claude/agents/memory-bank-synchronizer.md +++ b/.claude/agents/memory-bank-synchronizer.md @@ -4,44 +4,84 @@ description: Use this agent proactively to synchronize memory bank documentation color: cyan --- -You are a Memory Bank Synchronization Specialist focused on maintaining consistency between CLAUDE.md and CLAUDE-\*.md documentation files and actual codebase implementation. Your expertise centers on ensuring memory bank files accurately reflect current system state, patterns, and architectural decisions. +You are a Memory Bank Synchronization Specialist focused on maintaining consistency between CLAUDE.md and CLAUDE-\*.md documentation files and actual codebase implementation. Your expertise centers on ensuring memory bank files accurately reflect current system state while PRESERVING important planning, historical, and strategic information. Your primary responsibilities: -1. **Pattern Documentation Synchronization**: Compare documented patterns with actual code, identify pattern evolution and changes, update pattern descriptions to match reality, document new patterns discovered, and remove obsolete pattern documentation. +1. **Pattern Documentation Synchronization**: Compare documented patterns with actual code, identify pattern evolution and changes, update pattern descriptions to match reality, document new patterns discovered, and remove ONLY truly obsolete pattern documentation. -2. **Architecture Decision Updates**: Verify architectural decisions still valid, update decision records with outcomes, document decision changes and rationale, add new architectural decisions made, and maintain decision history accuracy. +2. **Architecture Decision Updates**: Verify architectural decisions still valid, update decision records with outcomes, document decision changes and rationale, add new architectural decisions made, and maintain decision history accuracy WITHOUT removing historical context. 3. **Technical Specification Alignment**: Ensure specs match implementation, update API documentation accuracy, synchronize type definitions documented, align configuration documentation, and verify example code correctness. -4. **Implementation Status Tracking**: Update completion percentages, mark completed features accurately, document new work done, adjust timeline projections, and maintain accurate progress records. +4. **Implementation Status Tracking**: Update completion percentages, mark completed features accurately, document new work done, adjust timeline projections, and maintain accurate progress records INCLUDING historical achievements. 5. **Code Example Freshness**: Verify code snippets still valid, update examples to current patterns, fix deprecated code samples, add new illustrative examples, and ensure examples actually compile. 6. **Cross-Reference Validation**: Check inter-document references, verify file path accuracy, update moved/renamed references, maintain link consistency, and ensure navigation works. +**CRITICAL PRESERVATION RULES**: + +7. **Preserve Strategic Information**: NEVER delete or modify: + - Todo lists and task priorities (CLAUDE-todo-list.md) + - Planned future features and roadmaps + - Phase 2/3/4 planning and specifications + - Business goals and success metrics + - User stories and requirements + +8. **Maintain Historical Context**: ALWAYS preserve: + - Session achievements and work logs (CLAUDE-activeContext.md) + - Troubleshooting documentation and solutions + - Bug fix histories and lessons learned + - Decision rationales and trade-offs made + - Performance optimization records + - Testing results and benchmarks + +9. **Protect Planning Documentation**: KEEP intact: + - Development roadmaps and timelines + - Sprint planning and milestones + - Resource allocation notes + - Risk assessments and mitigation strategies + - Business model and monetization plans + Your synchronization methodology: -- **Systematic Comparison**: Check each claim against code -- **Version Control Analysis**: Review recent changes -- **Pattern Detection**: Identify undocumented patterns -- **Accuracy Priority**: Correct over complete -- **Practical Focus**: Keep actionable and relevant +- **Systematic Comparison**: Check each technical claim against code +- **Version Control Analysis**: Review recent changes for implementation updates +- **Pattern Detection**: Identify undocumented patterns and architectural changes +- **Selective Updates**: Update technical accuracy while preserving strategic content +- **Practical Focus**: Keep both current technical info AND historical context +- **Preservation First**: When in doubt, preserve rather than delete When synchronizing: -1. **Audit current state** - Review all memory bank files -2. **Compare with code** - Verify against implementation -3. **Identify gaps** - Find undocumented changes -4. **Update systematically** - Correct file by file -5. **Validate accuracy** - Ensure updates are correct +1. **Audit current state** - Review all memory bank files, identifying technical vs strategic content +2. **Compare with code** - Verify ONLY technical claims against implementation +3. **Identify gaps** - Find undocumented technical changes while noting preserved planning content +4. **Update selectively** - Correct technical details file by file, preserving non-technical content +5. **Validate preservation** - Ensure all strategic and historical information remains intact + +**SYNCHRONIZATION DECISION TREE**: +- **Technical specification/pattern/code example** → Update to match current implementation +- **Todo list/roadmap/planning item** → PRESERVE (mark as preserved in report) +- **Historical achievement/lesson learned** → PRESERVE (mark as preserved in report) +- **Future feature specification** → PRESERVE (may add current implementation status) +- **Troubleshooting guide/decision rationale** → PRESERVE (may add current status) Provide synchronization results with: -- Files updated -- Patterns synchronized -- Decisions documented -- Examples refreshed -- Accuracy improvements +- **Technical Updates Made**: + - Files updated for technical accuracy + - Patterns synchronized with current code + - Outdated code examples refreshed + - Implementation status corrections + +- **Strategic Content Preserved**: + - Todo lists and priorities kept intact + - Future roadmaps maintained + - Historical achievements logged preserved + - Troubleshooting insights retained + +- **Accuracy Improvements**: Summary of technical corrections made -Your goal is to ensure the memory bank system remains an accurate, trustworthy source of project knowledge that reflects actual implementation reality. Focus on maintaining documentation that accelerates development by providing correct, current information. Ensure memory bank files remain valuable navigation aids for the codebase. +Your goal is to ensure the memory bank system remains an accurate, trustworthy source of BOTH current technical knowledge AND valuable historical/strategic context. Focus on maintaining documentation that accelerates development by providing correct, current technical information while preserving the institutional knowledge, planning context, and lessons learned that guide future development decisions. From 5e13a3d5d16511c34c5000968f6ed6fc6eedc253 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sat, 4 Oct 2025 09:00:36 +1000 Subject: [PATCH 031/174] add Chrome Devtools MCP server dynamically loaded only when needed --- .claude/mcp/chrome-devtools.json | 11 ++++++ .claude/settings.local.json | 17 ++++++++- README.md | 59 ++++++++++++++++++++++++++++++++ 3 files changed, 86 insertions(+), 1 deletion(-) create mode 100644 .claude/mcp/chrome-devtools.json diff --git a/.claude/mcp/chrome-devtools.json b/.claude/mcp/chrome-devtools.json new file mode 100644 index 0000000..0bd49a8 --- /dev/null +++ b/.claude/mcp/chrome-devtools.json @@ -0,0 +1,11 @@ +{ + "mcpServers": { + "chrome-devtools": { + "command": "npx", + "args": [ + "-y", + "chrome-devtools-mcp@latest" + ] + } + } +} \ No newline at end of file diff --git a/.claude/settings.local.json b/.claude/settings.local.json index eebdc5f..e31f9d5 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -62,7 +62,22 @@ "WebFetch(domain:github.com)", "WebFetch(domain:openrouter.ai)", "WebFetch(domain:www.comet.com)", - "Bash(mkdir:*)" + "Bash(mkdir:*)", + "mcp__chrome-devtools__list_pages", + "mcp__chrome-devtools__navigate_page", + "mcp__chrome-devtools__take_snapshot", + "mcp__chrome-devtools__take_screenshot", + "mcp__chrome-devtools__list_console_messages", + "mcp__chrome-devtools__list_network_requests", + "mcp__chrome-devtools__click", + "mcp__chrome-devtools__fill_form", + "mcp__chrome-devtools__hover", + "mcp__chrome-devtools__emulate_cpu", + "mcp__chrome-devtools__emulate_network", + "mcp__chrome-devtools__evaluate_script", + "mcp__chrome-devtools__resize_page", + "mcp__chrome-devtools__fill", + "mcp__chrome-devtools__navigate_page_history", ], "deny": [] } diff --git a/README.md b/README.md index b5d902f..19aeb14 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,7 @@ I also install the following MCP servers ([install commands](#claude-code-mcp-se * [Gemini CLI MCP](https://github.com/centminmod/gemini-cli-mcp-server) * [Cloudflare Documentation MCP](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/docs-vectorize) * [Context 7 MCP](https://github.com/upstash/context7) +* [Chrome Devtools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) * [Notion MCP](https://github.com/makenotion/notion-mcp-server) ## Claude Code Hooks @@ -388,6 +389,64 @@ claude mcp add --transport sse context7 https://mcp.context7.com/sse -s user claude mcp add-json notionApi '{"type":"stdio","command":"npx","args":["-y","@notionhq/notion-mcp-server"],"env":{"OPENAPI_MCP_HEADERS":"{\"Authorization\": \"Bearer ntn_API_KEY\", \"Notion-Version\": \"2022-06-28\"}"}}' -s user ``` +### Chrome Devtools MCP sever + +[Chrome Devtools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) + +This MCP server can take up to 17K of Claude's context window so I only install it when project needs it via `--mcp-config` parameter when running Claude client: + +```bash +claude --mcp-config .claude/mcp/chrome-devtools.json +``` + +Where `.claude/mcp/chrome-devtools.json` + +```json +{ + "mcpServers": { + "chrome-devtools": { + "command": "npx", + "args": [ + "-y", + "chrome-devtools-mcp@latest" + ] + } + } +} +``` + +Chrome Devtool MCP server takes up ~16,977 tokens across 26 MCP tools + +```bash + mcp__chrome-devtools__list_console_messages (chrome-devtools): 584 tokens + mcp__chrome-devtools__emulate_cpu (chrome-devtools): 651 tokens + mcp__chrome-devtools__emulate_network (chrome-devtools): 694 tokens + mcp__chrome-devtools__click (chrome-devtools): 636 tokens + mcp__chrome-devtools__drag (chrome-devtools): 638 tokens + mcp__chrome-devtools__fill (chrome-devtools): 644 tokens + mcp__chrome-devtools__fill_form (chrome-devtools): 676 tokens + mcp__chrome-devtools__hover (chrome-devtools): 609 tokens + mcp__chrome-devtools__upload_file (chrome-devtools): 651 tokens + mcp__chrome-devtools__get_network_request (chrome-devtools): 618 tokens + mcp__chrome-devtools__list_network_requests (chrome-devtools): 783 tokens + mcp__chrome-devtools__close_page (chrome-devtools): 624 tokens + mcp__chrome-devtools__handle_dialog (chrome-devtools): 645 tokens + mcp__chrome-devtools__list_pages (chrome-devtools): 582 tokens + mcp__chrome-devtools__navigate_page (chrome-devtools): 642 tokens + mcp__chrome-devtools__navigate_page_history (chrome-devtools): 656 tokens + mcp__chrome-devtools__new_page (chrome-devtools): 637 tokens + mcp__chrome-devtools__resize_page (chrome-devtools): 629 tokens + mcp__chrome-devtools__select_page (chrome-devtools): 619 tokens + mcp__chrome-devtools__performance_analyze_insight (chrome-devtools): 649 tokens + mcp__chrome-devtools__performance_start_trace (chrome-devtools): 689 tokens + mcp__chrome-devtools__performance_stop_trace (chrome-devtools): 586 tokens + mcp__chrome-devtools__take_screenshot (chrome-devtools): 803 tokens + mcp__chrome-devtools__evaluate_script (chrome-devtools): 775 tokens + mcp__chrome-devtools__take_snapshot (chrome-devtools): 614 tokens + mcp__chrome-devtools__wait_for (chrome-devtools): 643 tokens +``` + ## Star History [![Star History Chart](https://api.star-history.com/svg?repos=centminmod/my-claude-code-setup&type=Date)](https://www.star-history.com/#centminmod/my-claude-code-setup&Date) + From 72ba4db777bfdc5f3ea82a868d4e44d46ef7ed5e Mon Sep 17 00:00:00 2001 From: George Liu Date: Sat, 4 Oct 2025 09:23:23 +1000 Subject: [PATCH 032/174] update settings.local.json --- .claude/settings.local.json | 1 + 1 file changed, 1 insertion(+) diff --git a/.claude/settings.local.json b/.claude/settings.local.json index e31f9d5..23dadc0 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -78,6 +78,7 @@ "mcp__chrome-devtools__resize_page", "mcp__chrome-devtools__fill", "mcp__chrome-devtools__navigate_page_history", + "mcp__chrome-devtools__new_page" ], "deny": [] } From c90188251f196d23c70c7741af8e1f2c541b90b1 Mon Sep 17 00:00:00 2001 From: George Liu Date: Fri, 10 Oct 2025 12:28:58 +1000 Subject: [PATCH 033/174] update README --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 19aeb14..d9dd2e1 100644 --- a/README.md +++ b/README.md @@ -450,3 +450,7 @@ Chrome Devtool MCP server takes up ~16,977 tokens across 26 MCP tools [![Star History Chart](https://api.star-history.com/svg?repos=centminmod/my-claude-code-setup&type=Date)](https://www.star-history.com/#centminmod/my-claude-code-setup&Date) + +## Stats + +![Alt](https://repobeats.axiom.co/api/embed/715da1679915da77d87deb99a1f527a44e76ec60.svg "Repobeats analytics image") \ No newline at end of file From 94724c9c5148e7570fb6b22897320345810d61d5 Mon Sep 17 00:00:00 2001 From: George Liu Date: Fri, 17 Oct 2025 00:38:04 +1000 Subject: [PATCH 034/174] add create-release-note slash command and documentation --- .../documentation/create-release-note.md | 534 ++++++++++++++++++ README.md | 7 + 2 files changed, 541 insertions(+) create mode 100644 .claude/commands/documentation/create-release-note.md diff --git a/.claude/commands/documentation/create-release-note.md b/.claude/commands/documentation/create-release-note.md new file mode 100644 index 0000000..6b3b44d --- /dev/null +++ b/.claude/commands/documentation/create-release-note.md @@ -0,0 +1,534 @@ +# Release Note Generator + +Generate comprehensive release documentation from recent commits, producing two distinct outputs: a customer-facing release note and a technical engineering note. + +## Interactive Workflow + +When this command is triggered, **DO NOT** immediately generate release notes. Instead, present the user with two options: + +### Mode Selection Prompt + +Present this to the user: + +```text +I can generate release notes in two ways: + +**Mode 1: By Commit Count** +Generate notes for the last N commits (specify number or use default 10) +→ Quick generation when you know the commit count + +**Mode 2: By Commit Hash Range (i.e. Last 24/48/72 Hours)** +Show all commits from the last 24/48/72 hours, then you select a starting commit +→ Precise control when you want to review recent commits first + +Which mode would you like? +1. Commit count (provide number or use default) +2. Commit hash selection (show last 24/48/72 hours) + +You can also provide an argument directly: /create-release-note 20 +``` + +--- + +## Mode 1: By Commit Count + +### Usage + +```bash +/create-release-note # Triggers mode selection +/create-release-note 20 # Directly uses Mode 1 with 20 commits +/create-release-note 50 # Directly uses Mode 1 with 50 commits +``` + +### Process + +1. If `$ARGUMENTS` is provided, use it as commit count +2. If no `$ARGUMENTS`, ask user for commit count or default to 10 +3. Set: `COMMIT_COUNT="${ARGUMENTS:-10}"` +4. Generate release notes immediately + +--- + +## Mode 2: By Commit Hash Range + +### Workflow + +When user selects Mode 2, follow this process: + +### Step 1: Retrieve Last 24 Hours of Commits + +```bash +git log --since="24 hours ago" --pretty=format:"%h|%ai|%an|%s" --reverse +``` + +### Step 2: Present Commits to User + +Format the output as a numbered list for easy selection: + +```text +Commits from the last 24 hours (oldest to newest): + + 1. a3f7e821 | 2025-10-15 09:23:45 | Alice Smith | Add OAuth provider configuration + 2. b4c8f932 | 2025-10-15 10:15:22 | Bob Jones | Implement token refresh flow + 3. c5d9e043 | 2025-10-15 11:42:18 | Alice Smith | Add provider UI components + 4. d6e1f154 | 2025-10-15 13:08:33 | Carol White | Database connection pooling + 5. e7f2g265 | 2025-10-15 14:55:47 | Alice Smith | Query optimization middleware + 6. f8g3h376 | 2025-10-15 16:20:12 | Bob Jones | Dark mode CSS variables + 7. g9h4i487 | 2025-10-15 17:10:55 | Carol White | Theme switching logic + 8. h0i5j598 | 2025-10-16 08:45:29 | Alice Smith | Error boundary implementation + +Please provide the starting commit hash (8 characters) or number. +Release notes will be generated from your selection to HEAD (most recent). + +Example: "a3f7e821" or "1" will generate notes for commits 1-8 +Example: "d6e1f154" or "4" will generate notes for commits 4-8 +``` + +### Step 3: Generate Notes from Selected Commit + +Once user provides a commit hash or number: + +```bash +# If user provided a number, extract the corresponding hash +SELECTED_HASH="" + +# Generate notes from selected commit to HEAD +git log ${SELECTED_HASH}..HEAD --stat --oneline +git log ${SELECTED_HASH}..HEAD --pretty=format:"%H|%s|%an|%ad" --date=short +``` + +**Important:** The range `${SELECTED_HASH}..HEAD` means "from the commit AFTER the selected hash to HEAD". If you want to include the selected commit itself, use `${SELECTED_HASH}^..HEAD` or count commits with `--ancestry-path`. + +### Step 4: Confirm Range + +Before generating, confirm with user: + +```text +Generating release notes for N commits: +From: - +To: - + +Proceeding with generation... +``` + +--- + +## Core Requirements + +### 1. Commit Analysis + +**Determine commit source:** + +- **Mode 1**: `COMMIT_COUNT="${ARGUMENTS:-10}"` → Use `git log -${COMMIT_COUNT}` +- **Mode 2**: User-selected hash → Use `git log ${SELECTED_HASH}..HEAD` + +**Retrieve commits:** + +- Use `git log --stat --oneline` +- Use `git log --pretty=format:"%H|%s|%an|%ad" --date=short` +- Analyze file changes to understand scope and impact +- Group related commits by feature/subsystem +- Identify major themes and primary focus areas + +### 2. Traceability + +- Every claim MUST be traceable to specific commit SHAs +- Reference actual files changed (e.g., src/config.ts, lib/utils.py) +- Use 8-character SHA prefixes for engineering notes (e.g., 0ca46028) +- Verify all technical details against actual commit content + +### 3. Length Constraints + +- Each section: ≤500 words (strict maximum) +- Aim for 150-180 words for optimal readability +- Prioritize most impactful changes if space constrained + +--- + +## Section 1: Release Note (Customer-Facing) + +### Purpose + +Communicate value to end users without requiring deep technical knowledge. Audience varies by project type (system administrators, developers, product users, etc.). + +### Tone and Style + +- **Friendly & Clear**: Write as if explaining to a competent user of the software +- **Value-Focused**: Emphasize benefits and capabilities, not implementation details +- **Confident**: Use active voice and definitive statements +- **Professional**: Avoid jargon, explain acronyms on first use +- **Contextual**: Adapt language to the project type (infrastructure, web app, library, tool, etc.) + +### Content Guidelines + +**Include:** + +- Major new features or functionality +- User-visible improvements +- Performance enhancements +- Security updates +- Dependency/component version upgrades +- Compatibility improvements +- Bug fixes affecting user experience + +**Exclude:** + +- Internal refactoring (unless it improves performance) +- Code organization changes +- Developer-only tooling +- Commit SHAs or file paths +- Implementation details +- Internal API changes (unless user-facing library) + +### Structure Template + +```markdown +## Release Note (Customer-Facing) + +**[Project Name] [Version] - [Descriptive Title]** + +[Opening paragraph: 1-2 sentences describing the primary focus/theme] + +**Key improvements:** +- [Feature/improvement 1: benefit-focused description] +- [Feature/improvement 2: benefit-focused description] +- [Feature/improvement 3: benefit-focused description] +- [Feature/improvement 4: benefit-focused description] +- [etc.] + +[Closing paragraph: 1-2 sentences about overall impact and use cases] +``` + +### Style Examples + +✅ **Good (Customer-Facing):** +> "Enhanced authentication system with support for OAuth 2.0 and SAML providers" + +❌ **Bad (Too Technical):** +> "Refactored src/auth/oauth.ts to implement RFC 6749 token refresh flow" + +✅ **Good (Value-Focused):** +> "Improved database query performance, reducing page load times by 40%" + +❌ **Bad (Implementation Details):** +> "Added connection pooling in db/connection.ts with configurable pool size" + +✅ **Good (User Benefit):** +> "Added dark mode support with automatic system theme detection" + +❌ **Bad (Technical Detail):** +> "Implemented CSS variables in styles/theme.css for runtime theme switching" + +--- + +## Section 2: Engineering Note (Technical) + +### Purpose + +Provide developers/maintainers with precise technical details for code review, debugging, and future reference. + +### Tone and Style + +- **Precise & Technical**: Use exact terminology and technical language +- **Reference-Heavy**: Include SHAs, file paths, function names +- **Concise**: Information density over narrative +- **Structured**: Group by subsystem or feature area + +### Content Guidelines + +**Include:** + +- 8-character SHA prefixes for every commit or commit group +- Exact file paths (src/components/App.tsx, lib/db/connection.py) +- Specific technical changes (version numbers, configuration changes) +- Module/function names when relevant +- Code organization changes +- All commits (even minor refactoring) +- Breaking changes or API modifications + +**Structure:** + +- Group related commits by subsystem +- List most significant changes first +- Use single-sentence summaries per commit/group +- Format: `SHA: description (file references)` + +### Structure Template + +```markdown +## Engineering Note (Technical) + +**[Primary Focus/Theme]** + +[Opening sentence: describe the main technical objective] + +**[Subsystem/Feature Area 1]:** +- SHA1: brief technical description (file1, file2) +- SHA2: brief technical description (file3) +- SHA3, SHA4: grouped description (file4, file5, file6) + +**[Subsystem/Feature Area 2]:** +- SHA5: brief technical description (file7, file8) +- SHA6: brief technical description (file9) + +**[Subsystem/Feature Area 3]:** +- SHA7, SHA8, SHA9: grouped description (files10-15) +- SHA10: brief technical description (file16) + +[Optional: List number of files affected if significant] +``` + +### Style Examples + +✅ **Good (Technical):** +> "a3f7e821: OAuth 2.0 token refresh implementation in src/auth/oauth.ts, src/auth/tokens.ts" + +❌ **Bad (Too Vague):** +> "Updated authentication system for better token handling" + +✅ **Good (Grouped):** +> "c4d8a123, e5f9b234, a1c2d345: Database connection pooling (src/db/pool.ts, src/db/config.ts)" + +❌ **Bad (No References):** +> "Fixed database connection issues" + +✅ **Good (Precise):** +> "7b8c9d01: Upgrade react from 18.2.0 to 18.3.1 (package.json)" + +❌ **Bad (Missing Context):** +> "Updated React dependency" + +--- + +## Formatting Standards + +### Markdown Requirements + +- Use `##` for main section headers +- Use `**bold**` for subsection headers and project titles +- Use `-` for bullet lists +- Use `` `backticks` `` for file paths, commands, version numbers +- Use 8-character SHA prefixes: `0ca46028` not `0ca46028b9fa62bb995e41133036c9f0d6ac9fef` + +### Horizontal Separator + +Use `---` (three hyphens) to separate the two sections for visual clarity. + +### Version Numbers + +Format as: `version X.Y` or `version X.Y.Z` (e.g., "React 18.3", "Python 3.12.1") + +### File Paths + +- Use actual paths from repository: `src/components/App.tsx` not "main component" +- Multiple files: `(file1, file2, file3)` or `(files1-10)` for ranges +- Use project-appropriate path conventions (src/, lib/, app/, pkg/, etc.) + +--- + +## Commit Grouping Strategy + +### Group When + +- Multiple commits modify the same file/subsystem +- Commits represent incremental work on same feature +- Space constraints require consolidation +- Related bug fixes or improvements + +### Example Grouping + +```text +Individual: +- c4d8a123: Add connection pool configuration +- e5f9b234: Implement pool lifecycle management +- a1c2d345: Add connection pool metrics + +Grouped: +- c4d8a123, e5f9b234, a1c2d345: Database connection pooling (src/db/pool.ts, src/db/config.ts, src/db/metrics.ts) +``` + +### Don't Group + +- Unrelated commits (different subsystems) +- Major features (deserve individual mention) +- Commits with significantly different file scopes +- Breaking changes (always call out separately) + +--- + +## Quality Checklist + +Before finalizing, verify: + +- [ ] Mode selection presented (unless $ARGUMENTS provided) +- [ ] Commit range correctly determined (Mode 1: count, Mode 2: hash range) +- [ ] User confirmed commit range before generation +- [ ] Both sections ≤500 words +- [ ] Every claim traceable to specific commit(s) +- [ ] Customer note has no SHAs or file paths +- [ ] Engineering note has SHAs for all commits/groups +- [ ] File paths are accurate and complete +- [ ] Tone appropriate for each audience +- [ ] Markdown formatting consistent +- [ ] Version numbers accurate +- [ ] No typos or grammatical errors +- [ ] Primary focus clearly communicated in both sections +- [ ] Most significant changes prioritized first +- [ ] Language adapted to project type (not overly specific to one domain) + +--- + +## Edge Cases + +### If Fewer Commits Than Requested + +- Generate notes for all available commits +- Note this at the beginning: "Release covering [N] commits" +- Example: "Release covering 7 commits (requested 10)" + +### If No Commits in Last 24 Hours (Mode 2) + +- Inform user: "No commits found in the last 24 hours" +- Offer alternatives: + - Extend time range (48 hours, 7 days) + - Switch to Mode 1 (commit count) + - Manual hash range specification + +### If Mostly Minor Changes + +- Group aggressively by subsystem +- Lead with most significant changes +- Note: "Maintenance release with incremental improvements" + +### If Single Major Feature Dominates + +- Lead with that feature in both sections +- Group supporting commits under that theme +- Structure engineering note by feature components + +### If Merge Commits Present + +- Skip merge commits themselves +- Include the actual changes from merged branches +- Focus on functional changes, not merge mechanics + +### If No Version Tag Available + +- Use branch name or generic title: "Development Updates" or "Recent Improvements" +- Focus on change summary rather than version-specific language + +### If User Provides Invalid Commit Hash + +- Validate hash exists: `git cat-file -t ${HASH} 2>/dev/null` +- If invalid, show error and re-present commit list +- Suggest checking the hash or selecting by number instead + +--- + +## Adapting to Project Types + +### Infrastructure/DevOps Projects + +- Focus on: deployment improvements, configuration management, monitoring, reliability +- Audience: sysadmins, DevOps engineers, SREs + +### Web Applications + +- Focus on: features, UX improvements, performance, security +- Audience: product users, stakeholders, QA teams + +### Libraries/Frameworks + +- Focus on: API changes, new capabilities, breaking changes, migration guides +- Audience: developers using the library + +### CLI Tools + +- Focus on: command changes, new options, output improvements, bug fixes +- Audience: command-line users, automation engineers + +### Internal Tools + +- Focus on: workflow improvements, bug fixes, integration updates +- Audience: team members, internal stakeholders + +--- + +## Example Output Structure + +```markdown +## Release Note (Customer-Facing) + +**MyProject v2.4.0 - Authentication & Performance Update** + +This release introduces comprehensive OAuth 2.0 support and significant performance improvements across the application. + +**Key improvements:** +- OAuth 2.0 authentication with support for Google, GitHub, and Microsoft providers +- Improved database query performance with connection pooling, reducing response times by 40% +- Added dark mode support with automatic system theme detection +- Enhanced error handling and user feedback throughout the interface +- Security updates for dependency vulnerabilities + +These enhancements provide a more secure, performant, and user-friendly experience across all application features. + +--- + +## Engineering Note (Technical) + +**OAuth 2.0 Integration and Performance Optimization** + +Primary focus: authentication modernization and database performance improvements. + +**Authentication System:** +- a3f7e821: OAuth 2.0 provider implementation (src/auth/oauth.ts, src/auth/providers/) +- b4c8f932: Token refresh flow and session management (src/auth/tokens.ts) +- c5d9e043: Provider registration UI components (src/components/auth/OAuthProviders.tsx) + +**Performance Optimization:** +- d6e1f154: Database connection pooling (src/db/pool.ts, src/db/config.ts) +- e7f2g265: Query optimization middleware (src/db/middleware.ts) + +**UI/UX Improvements:** +- f8g3h376, g9h4i487: Dark mode CSS variables and theme switching (src/styles/theme.css, src/components/ThemeProvider.tsx) +- h0i5j598: Error boundary implementation (src/components/ErrorBoundary.tsx) + +**Security:** +- i1j6k609: Dependency updates for security patches (package.json, yarn.lock) +``` + +--- + +## Implementation Workflow + +When executing this command, Claude should: + +### If $ARGUMENTS Provided + +1. Use `COMMIT_COUNT="${ARGUMENTS}"` +2. Run git commands with the determined count +3. Generate both sections immediately + +### If No $ARGUMENTS + +1. Present mode selection prompt to user +2. Wait for user response + +**If user selects Mode 1:** +3. Ask for commit count or use default 10 +4. Generate notes immediately + +**If user selects Mode 2:** +3. Retrieve commits from last 24 hours +4. Present formatted list with numbers and hashes +5. Wait for user to provide hash or number +6. Validate selection +7. Confirm commit range +8. Generate notes from selected commit to HEAD + +### Final Steps (Both Modes) + +1. Analyze commits thoroughly +2. Generate both sections following all guidelines +3. Verify against quality checklist +4. Present both notes in the specified format diff --git a/README.md b/README.md index d9dd2e1..e61b853 100644 --- a/README.md +++ b/README.md @@ -130,6 +130,13 @@ Claude Code subagents are specialized tools designed to handle complex, multi-st - Matches existing README style and tone - Usage: `/create-readme-section "Create an installation section for my Python project"` +- **`/create-release-note`** - Generate comprehensive release documentation from recent commits with dual output formats + - Interactive workflow with two modes: by commit count or by commit hash range (last 24/48/72 hours) + - Produces customer-facing release note (value-focused, no technical jargon) and technical engineering note (SHA references, file paths) + - Comprehensive commit analysis with grouping by subsystem and traceability to specific SHAs + - Supports direct arguments for quick generation or interactive selection for precise control + - Usage: `/create-release-note` (interactive), `/create-release-note 20` (last 20 commits), or select commit hash after viewing recent commits + ### `/security` Commands - **`/security-audit`** - Perform comprehensive security audit of the codebase From bd3dae317cab47cfaa7d70e631239193005b6b9c Mon Sep 17 00:00:00 2001 From: George Liu Date: Fri, 17 Oct 2025 00:38:59 +1000 Subject: [PATCH 035/174] update settings.local.json --- .claude/settings.local.json | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 23dadc0..40320bc 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -78,8 +78,9 @@ "mcp__chrome-devtools__resize_page", "mcp__chrome-devtools__fill", "mcp__chrome-devtools__navigate_page_history", - "mcp__chrome-devtools__new_page" + "mcp__chrome-devtools__new_page", + "Bash(git log:*)" ], "deny": [] } -} \ No newline at end of file +} From f4164b4748370ef7307985b0182fa37a9b313f0b Mon Sep 17 00:00:00 2001 From: George Liu Date: Fri, 24 Oct 2025 05:58:25 +1000 Subject: [PATCH 036/174] update --- README.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/README.md b/README.md index e61b853..0630419 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,7 @@ I also install the following MCP servers ([install commands](#claude-code-mcp-se * [Context 7 MCP](https://github.com/upstash/context7) * [Chrome Devtools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) * [Notion MCP](https://github.com/makenotion/notion-mcp-server) +* [Claude Code Usage Metrics MCP](https://github.com/centminmod/claude-code-opentelemetry-setup) ## Claude Code Hooks @@ -364,6 +365,29 @@ files by blocking Write operations to certain paths ## Claude Code MCP Servers +[Claude Code Usage Metrics MCP](https://github.com/centminmod/claude-code-opentelemetry-setup) + +```bash +claude mcp add --transport stdio metrics -s user -- uv run --directory /path/to/your/mcp-server metrics-server +``` +```bash +claude mcp list +Checking MCP server health... + +context7: https://mcp.context7.com/sse (SSE) - ✓ Connected +cf-docs: https://docs.mcp.cloudflare.com/sse (SSE) - ✓ Connected +metrics: uv run --directory /path/to/your/mcp-server metrics-server - ✓ Connected +``` +MCP tool call `get_current_cost`. Returns today's total USD cost from Prometheus. +```bash +{ + "metric": "Total Cost Today", + "value": 27.149809833783127, + "formatted": "$27.1498", + "unit": "currencyUSD" +} +``` + ### Gemini CLI MCP Server [Gemini CLI MCP](https://github.com/centminmod/gemini-cli-mcp-server) From 1420013d55968c08c1c7e59872c248b74aad3867 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sat, 1 Nov 2025 12:16:02 +1000 Subject: [PATCH 037/174] update CLAUDE.md with doc lookup instructions - Claude Code's own understanding of hooks, skills and subagents can be spotty at times. Give specific instructions for it to look up official docs --- CLAUDE.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index ba8629b..1a74d9c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -35,6 +35,15 @@ This project uses a structured memory bank system with specialized context files When asked to backup Memory Bank System files, you will copy the core context files above and @.claude settings directory to directory @/path/to/backup-directory. If files already exist in the backup directory, you will overwrite them. +## Claude Hooks & Skills & Subagents + +Whenever you are asked to work on Claude Hooks, Skills or Subagents you will consult the official online documentation first to get 100% accurate understanding/ + +- https://docs.claude.com/en/docs/claude-code/hooks-guide.md +- https://docs.claude.com/en/docs/claude-code/hooks.md +- https://docs.claude.com/en/docs/claude-code/skills.md +- https://docs.claude.com/en/docs/claude-code/sub-agents.md + ## Project Overview From 6b7c1c5786a5165afcd822d74d5960aeef354fbf Mon Sep 17 00:00:00 2001 From: George Liu Date: Sat, 1 Nov 2025 12:32:09 +1000 Subject: [PATCH 038/174] typo --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 1a74d9c..3346cdb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -37,7 +37,7 @@ When asked to backup Memory Bank System files, you will copy the core context fi ## Claude Hooks & Skills & Subagents -Whenever you are asked to work on Claude Hooks, Skills or Subagents you will consult the official online documentation first to get 100% accurate understanding/ +Whenever you are asked to work on Claude Hooks, Skills or Subagents you will consult the official online documentation first to get 100% accurate understanding - https://docs.claude.com/en/docs/claude-code/hooks-guide.md - https://docs.claude.com/en/docs/claude-code/hooks.md From beb361e3d03cc7cbf7616e23c4bac10f8f331971 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sat, 1 Nov 2025 12:37:34 +1000 Subject: [PATCH 039/174] update CLAUDE_CODE_MAX_OUTPUT_TOKENS = 64k --- .claude/settings.local.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 40320bc..d445154 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -3,7 +3,8 @@ "MAX_MCP_OUTPUT_TOKENS": "60000", "BASH_DEFAULT_TIMEOUT_MS": "300000", "BASH_MAX_TIMEOUT_MS": "600000", - "MAX_THINKING_TOKENS": "8192" + "MAX_THINKING_TOKENS": "8192", + "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "64000" }, "includeCoAuthoredBy": false, "permissions": { From a802224fc83b5c13e2c3568ce4487c3bfd8f4c03 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sat, 1 Nov 2025 14:01:23 +1000 Subject: [PATCH 040/174] Add claude-docs-consultant SKILL.md --- .../skills/claude-docs-consultant/SKILL.md | 152 ++++++++++++++++++ CLAUDE.md | 9 +- README.md | 8 + 3 files changed, 162 insertions(+), 7 deletions(-) create mode 100644 .claude/skills/claude-docs-consultant/SKILL.md diff --git a/.claude/skills/claude-docs-consultant/SKILL.md b/.claude/skills/claude-docs-consultant/SKILL.md new file mode 100644 index 0000000..e48fe6a --- /dev/null +++ b/.claude/skills/claude-docs-consultant/SKILL.md @@ -0,0 +1,152 @@ +--- +name: claude-docs-consultant +description: Consult official Claude Code documentation from docs.claude.com using selective fetching. Use this skill when working on Claude Code hooks, skills, subagents, MCP servers, or any Claude Code feature that requires referencing official documentation for accurate implementation. Fetches only the specific documentation needed rather than loading all docs upfront. +--- + +# Claude Docs Consultant + +## Overview + +This skill enables efficient consultation of official Claude Code documentation by fetching only the specific docs needed for the current task. Instead of loading all documentation upfront, determine which docs are relevant and fetch them on-demand. + +## When to Use This Skill + +Invoke this skill when: + +- Creating or modifying Claude Code hooks +- Building or debugging skills +- Working with subagents or understanding subagent parameters +- Implementing MCP server integrations +- Understanding any Claude Code feature that requires official documentation +- Troubleshooting Claude Code functionality +- Verifying correct API usage or parameters + +## Common Documentation + +For the most frequently referenced topics, fetch these detailed documentation files directly: + +### Hooks Documentation + +- **hooks-guide.md** - Comprehensive guide to creating hooks with examples and best practices + - URL: `https://docs.claude.com/en/docs/claude-code/hooks-guide.md` + - Use for: Understanding hook lifecycle, creating new hooks, examples + +- **hooks.md** - Hooks API reference with event types and parameters + - URL: `https://docs.claude.com/en/docs/claude-code/hooks.md` + - Use for: Hook event reference, available events, parameter details + +### Skills Documentation + +- **skills.md** - Skills creation guide and structure reference + - URL: `https://docs.claude.com/en/docs/claude-code/skills.md` + - Use for: Creating skills, understanding SKILL.md format, bundled resources + +### Subagents Documentation + +- **sub-agents.md** - Subagent types, parameters, and usage + - URL: `https://docs.claude.com/en/docs/claude-code/sub-agents.md` + - Use for: Available subagent types, when to use Task tool, subagent parameters + +## Workflow for Selective Fetching + +Follow this process to efficiently fetch documentation: + +### Step 1: Identify Documentation Needs + +Determine which documentation is needed based on the task: + +- **Hook-related task** → Fetch `hooks-guide.md` and/or `hooks.md` +- **Skill-related task** → Fetch `skills.md` +- **Subagent-related task** → Fetch `sub-agents.md` +- **Other Claude Code feature** → Proceed to Step 2 + +### Step 2: Discover Available Documentation (If Needed) + +For features not covered by the 4 common docs above, fetch the docs map to discover available documentation: + +``` +URL: https://docs.claude.com/en/docs/claude-code/claude_code_docs_map.md +``` + +The docs map lists all available Claude Code documentation with descriptions. Identify the relevant doc(s) from the map. + +### Step 3: Fetch Only Relevant Documentation + +Use WebFetch to retrieve only the specific documentation needed: + +``` +WebFetch: + url: https://docs.claude.com/en/docs/claude-code/[doc-name].md + prompt: "Extract the full documentation content" +``` + +Fetch multiple docs in parallel if the task requires information from several sources. + +### Step 4: Apply Documentation to Task + +Use the fetched documentation to: +- Verify correct API usage +- Understand available parameters and options +- Follow best practices and examples +- Implement the feature correctly + +## Examples + +### Example 1: Creating a New Hook + +**User request:** "Help me create a pre-tool-use hook to log all tool calls" + +**Process:** +1. Identify need: Hook creation requires hooks documentation +2. Fetch `hooks-guide.md` for creation process and examples +3. Fetch `hooks.md` for pre-tool-use event reference +4. Apply: Create hook following guide, using correct event parameters + +### Example 2: Debugging a Skill + +**User request:** "My skill isn't loading - help me fix SKILL.md" + +**Process:** +1. Identify need: Skill structure requires skills documentation +2. Fetch `skills.md` for SKILL.md format requirements +3. Apply: Validate frontmatter, structure, and bundled resources + +### Example 3: Using Subagents + +**User request:** "Which subagent should I use to search the codebase?" + +**Process:** +1. Identify need: Subagent selection requires subagent documentation +2. Fetch `sub-agents.md` for subagent types and capabilities +3. Apply: Recommend appropriate subagent (e.g., Explore or code-searcher) + +### Example 4: Unknown Feature + +**User request:** "How do I configure Claude Code settings.json?" + +**Process:** +1. Identify need: Not covered by the 4 common docs +2. Fetch docs map: `claude_code_docs_map.md` +3. Discover: Find relevant doc (e.g., `settings.md`) +4. Fetch specific doc: `https://docs.claude.com/en/docs/claude-code/settings.md` +5. Apply: Configure settings.json correctly + +## Best Practices + +### Token Efficiency + +- Fetch only the documentation actually needed for the current task +- Fetch multiple docs in parallel if needed (single message with multiple WebFetch calls) +- Do not fetch documentation "just in case" - fetch when required + +### Staying Current + +- Always fetch from docs.claude.com (live docs, not cached copies) +- Documentation may be updated by Anthropic - fetching ensures latest information +- If documentation seems outdated or unclear, verify URL is correct + +### Selective vs Comprehensive + +- **Selective (preferred)**: Fetch hooks-guide.md for hook creation task +- **Comprehensive (avoid)**: Fetch all 4 common docs for every task +- **Discovery-based**: Use docs map when common docs don't cover the need diff --git a/CLAUDE.md b/CLAUDE.md index 3346cdb..514df4d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -35,14 +35,9 @@ This project uses a structured memory bank system with specialized context files When asked to backup Memory Bank System files, you will copy the core context files above and @.claude settings directory to directory @/path/to/backup-directory. If files already exist in the backup directory, you will overwrite them. -## Claude Hooks & Skills & Subagents +## Claude Code Official Documentation -Whenever you are asked to work on Claude Hooks, Skills or Subagents you will consult the official online documentation first to get 100% accurate understanding - -- https://docs.claude.com/en/docs/claude-code/hooks-guide.md -- https://docs.claude.com/en/docs/claude-code/hooks.md -- https://docs.claude.com/en/docs/claude-code/skills.md -- https://docs.claude.com/en/docs/claude-code/sub-agents.md +When working on Claude Code features (hooks, skills, subagents, MCP servers, etc.), use the `claude-docs-consultant` skill to selectively fetch official documentation from docs.claude.com. ## Project Overview diff --git a/README.md b/README.md index 0630419..30c712a 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,14 @@ I also install the following MCP servers ([install commands](#claude-code-mcp-se * [Notion MCP](https://github.com/makenotion/notion-mcp-server) * [Claude Code Usage Metrics MCP](https://github.com/centminmod/claude-code-opentelemetry-setup) +## Claude Code Skills + +Claude Code now supports [Agent Skills](https://docs.claude.com/en/docs/claude-code/skills). + +### claude-docs-consultant + +- **Purpose**: A specialized Claude skill which will selectively consult the official Claude Code documentation from docs.claude.com using selective fetching. This skill will involve only when working on Claude Code hooks, skills, subagents, MCP servers, or any Claude Code feature that requires referencing official documentation for accurate implementation. Fetches only the specific documentation needed rather than loading all docs upfront + ## Claude Code Hooks The Claude Code hook is for `STOP` which uses Terminal-Notifier to show macOS desktop notifications whenever Claude Code stops and finishes it's response https://github.com/centminmod/terminal-notifier-setup. From e2daa32405d57795b76d9b23b0f7f3f7ef2433df Mon Sep 17 00:00:00 2001 From: George Liu Date: Sat, 1 Nov 2025 14:16:10 +1000 Subject: [PATCH 041/174] typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 30c712a..6f1e136 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ Claude Code now supports [Agent Skills](https://docs.claude.com/en/docs/claude-c ### claude-docs-consultant -- **Purpose**: A specialized Claude skill which will selectively consult the official Claude Code documentation from docs.claude.com using selective fetching. This skill will involve only when working on Claude Code hooks, skills, subagents, MCP servers, or any Claude Code feature that requires referencing official documentation for accurate implementation. Fetches only the specific documentation needed rather than loading all docs upfront +- **Purpose**: A specialized Claude skill which will selectively consult the official Claude Code documentation from docs.claude.com using selective fetching. This skill will invoke only when working on Claude Code hooks, skills, subagents, MCP servers, or any Claude Code feature that requires referencing official documentation for accurate implementation. Fetches only the specific documentation needed rather than loading all docs upfront ## Claude Code Hooks From 02a85cc6beb7273c795aa2bb15e2a5cf45ca18f6 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sat, 8 Nov 2025 03:06:05 +1000 Subject: [PATCH 042/174] update Claude Code documentation urls for Claude Code doc SKILL --- .../skills/claude-docs-consultant/SKILL.md | 20 ++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/.claude/skills/claude-docs-consultant/SKILL.md b/.claude/skills/claude-docs-consultant/SKILL.md index e48fe6a..8971177 100644 --- a/.claude/skills/claude-docs-consultant/SKILL.md +++ b/.claude/skills/claude-docs-consultant/SKILL.md @@ -28,23 +28,24 @@ For the most frequently referenced topics, fetch these detailed documentation fi ### Hooks Documentation - **hooks-guide.md** - Comprehensive guide to creating hooks with examples and best practices - - URL: `https://docs.claude.com/en/docs/claude-code/hooks-guide.md` + + - URL: `https://code.claude.com/docs/en/hooks-guide.md` - Use for: Understanding hook lifecycle, creating new hooks, examples - **hooks.md** - Hooks API reference with event types and parameters - - URL: `https://docs.claude.com/en/docs/claude-code/hooks.md` + - URL: `https://code.claude.com/docs/en/hooks.md` - Use for: Hook event reference, available events, parameter details ### Skills Documentation - **skills.md** - Skills creation guide and structure reference - - URL: `https://docs.claude.com/en/docs/claude-code/skills.md` + - URL: `https://code.claude.com/docs/en/skills.md` - Use for: Creating skills, understanding SKILL.md format, bundled resources ### Subagents Documentation - **sub-agents.md** - Subagent types, parameters, and usage - - URL: `https://docs.claude.com/en/docs/claude-code/sub-agents.md` + - URL: `https://code.claude.com/docs/en/sub-agents.md` - Use for: Available subagent types, when to use Task tool, subagent parameters ## Workflow for Selective Fetching @@ -65,7 +66,7 @@ Determine which documentation is needed based on the task: For features not covered by the 4 common docs above, fetch the docs map to discover available documentation: ``` -URL: https://docs.claude.com/en/docs/claude-code/claude_code_docs_map.md +URL: https://code.claude.com/docs/en/claude_code_docs_map.md ``` The docs map lists all available Claude Code documentation with descriptions. Identify the relevant doc(s) from the map. @@ -76,7 +77,7 @@ Use WebFetch to retrieve only the specific documentation needed: ``` WebFetch: - url: https://docs.claude.com/en/docs/claude-code/[doc-name].md + url: https://code.claude.com/docs/en/[doc-name].md prompt: "Extract the full documentation content" ``` @@ -85,6 +86,7 @@ Fetch multiple docs in parallel if the task requires information from several so ### Step 4: Apply Documentation to Task Use the fetched documentation to: + - Verify correct API usage - Understand available parameters and options - Follow best practices and examples @@ -97,6 +99,7 @@ Use the fetched documentation to: **User request:** "Help me create a pre-tool-use hook to log all tool calls" **Process:** + 1. Identify need: Hook creation requires hooks documentation 2. Fetch `hooks-guide.md` for creation process and examples 3. Fetch `hooks.md` for pre-tool-use event reference @@ -107,6 +110,7 @@ Use the fetched documentation to: **User request:** "My skill isn't loading - help me fix SKILL.md" **Process:** + 1. Identify need: Skill structure requires skills documentation 2. Fetch `skills.md` for SKILL.md format requirements 3. Apply: Validate frontmatter, structure, and bundled resources @@ -116,6 +120,7 @@ Use the fetched documentation to: **User request:** "Which subagent should I use to search the codebase?" **Process:** + 1. Identify need: Subagent selection requires subagent documentation 2. Fetch `sub-agents.md` for subagent types and capabilities 3. Apply: Recommend appropriate subagent (e.g., Explore or code-searcher) @@ -125,10 +130,11 @@ Use the fetched documentation to: **User request:** "How do I configure Claude Code settings.json?" **Process:** + 1. Identify need: Not covered by the 4 common docs 2. Fetch docs map: `claude_code_docs_map.md` 3. Discover: Find relevant doc (e.g., `settings.md`) -4. Fetch specific doc: `https://docs.claude.com/en/docs/claude-code/settings.md` +4. Fetch specific doc: `https://code.claude.com/docs/en/settings.md` 5. Apply: Configure settings.json correctly ## Best Practices From db38098038b8ccb15f5cba2af4c449dc4c888240 Mon Sep 17 00:00:00 2001 From: George Liu Date: Wed, 12 Nov 2025 14:36:07 +1000 Subject: [PATCH 043/174] add VSC dev container setup link --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 6f1e136..44a6467 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,7 @@ My Claude Code project's starter settings and Claude Code hooks and slash comman 4. Optional step highly recommended: Install Visual Studio Code ([beginners YouTube video guide](https://www.youtube.com/watch?v=rPITZvwyoMc) and [here](https://www.youtube.com/watch?v=P-5bWpUbO60)) and [Claude Code VSC Extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code). 5. Optional step highly recommended: Sign up for [Github.com](https://github.com/) account and install Git for Visual Studio Code. Checkout YouTube guides [here](https://www.youtube.com/watch?v=twsYxYaQikI) and [here](https://www.youtube.com/watch?v=z5jZ9lrSpqk). 6. CLAUDE.md updated to instruct models to use faster tools so for macOS: `brew install ripgrep fd jq` +7. Optional step to setup Claude Code, Codex GPT-5, Gemini CLI, OpenCode, Vercel CLI, Cloudflare Wrangler, Amazon AWS CLI, all in a single isolated [Visual Studio Code dev container running Debian 12](https://claude-devcontainers.centminmod.com/). Allowing you to run YOLO modes for Claude Code with `dangerously_skip_permissions` enabled and Codex CLI with `sandbox_mode = danger-full-access` etc. I also install the following MCP servers ([install commands](#claude-code-mcp-servers)): From 8f94086ed65068f24076a4df033792fd2990811f Mon Sep 17 00:00:00 2001 From: George Liu Date: Tue, 25 Nov 2025 15:55:44 +1000 Subject: [PATCH 044/174] add AGENTS.md for Codex etc --- AGENTS.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..be62f12 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,99 @@ +## ALWAYS START WITH THESE COMMANDS FOR COMMON TASKS + +**Task: "List/summarize all files and directories"** + +```bash +fd . -t f # Lists ALL files recursively (FASTEST) +# OR +rg --files # Lists files (respects .gitignore) +``` + +**Task: "Search for content in files"** + +```bash +rg "search_term" # Search everywhere (FASTEST) +``` + +**Task: "Find files by name"** + +```bash +fd "filename" # Find by name pattern (FASTEST) +``` + +### Directory/File Exploration + +```bash +# FIRST CHOICE - List all files/dirs recursively: +fd . -t f # All files (fastest) +fd . -t d # All directories +rg --files # All files (respects .gitignore) + +# For current directory only: +ls -la # OK for single directory view +``` + +### BANNED - Never Use These Slow Tools + +* ❌ `tree` - NOT INSTALLED, use `fd` instead +* ❌ `find` - use `fd` or `rg --files` +* ❌ `grep` or `grep -r` - use `rg` instead +* ❌ `ls -R` - use `rg --files` or `fd` +* ❌ `cat file | grep` - use `rg pattern file` + +### Use These Faster Tools Instead + +```bash +# ripgrep (rg) - content search +rg "search_term" # Search in all files +rg -i "case_insensitive" # Case-insensitive +rg "pattern" -t py # Only Python files +rg "pattern" -g "*.md" # Only Markdown +rg -1 "pattern" # Filenames with matches +rg -c "pattern" # Count matches per file +rg -n "pattern" # Show line numbers +rg -A 3 -B 3 "error" # Context lines +rg " (TODO| FIXME | HACK)" # Multiple patterns + +# ripgrep (rg) - file listing +rg --files # List files (respects •gitignore) +rg --files | rg "pattern" # Find files by name +rg --files -t md # Only Markdown files + +# fd - file finding +fd -e js # All •js files (fast find) +fd -x command {} # Exec per-file +fd -e md -x ls -la {} # Example with ls + +# jq - JSON processing +jq. data.json # Pretty-print +jq -r .name file.json # Extract field +jq '.id = 0' x.json # Modify field +``` + +### Search Strategy + +1. Start broad, then narrow: `rg "partial" | rg "specific"` +2. Filter by type early: `rg -t python "def function_name"` +3. Batch patterns: `rg "(pattern1|pattern2|pattern3)"` +4. Limit scope: `rg "pattern" src/` + +### INSTANT DECISION TREE + +``` +User asks to "list/show/summarize/explore files"? + → USE: fd . -t f (fastest, shows all files) + → OR: rg --files (respects .gitignore) + +User asks to "search/grep/find text content"? + → USE: rg "pattern" (NOT grep!) + +User asks to "find file/directory by name"? + → USE: fd "name" (NOT find!) + +User asks for "directory structure/tree"? + → USE: fd . -t d (directories) + fd . -t f (files) + → NEVER: tree (not installed!) + +Need just current directory? + → USE: ls -la (OK for single dir) +``` From 26eaf112b52927e6a29e78f2c90d7e8c86ade317 Mon Sep 17 00:00:00 2001 From: George Liu Date: Wed, 26 Nov 2025 14:34:10 +1000 Subject: [PATCH 045/174] add .worktreeinclude support --- .worktreeinclude | 4 ++++ README.md | 1 + 2 files changed, 5 insertions(+) create mode 100644 .worktreeinclude diff --git a/.worktreeinclude b/.worktreeinclude new file mode 100644 index 0000000..c19a320 --- /dev/null +++ b/.worktreeinclude @@ -0,0 +1,4 @@ +.env +.env.local +.env.* +**/.claude/settings.local.json \ No newline at end of file diff --git a/README.md b/README.md index 44a6467..5ec39c4 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ My Claude Code project's starter settings and Claude Code hooks and slash comman 5. Optional step highly recommended: Sign up for [Github.com](https://github.com/) account and install Git for Visual Studio Code. Checkout YouTube guides [here](https://www.youtube.com/watch?v=twsYxYaQikI) and [here](https://www.youtube.com/watch?v=z5jZ9lrSpqk). 6. CLAUDE.md updated to instruct models to use faster tools so for macOS: `brew install ripgrep fd jq` 7. Optional step to setup Claude Code, Codex GPT-5, Gemini CLI, OpenCode, Vercel CLI, Cloudflare Wrangler, Amazon AWS CLI, all in a single isolated [Visual Studio Code dev container running Debian 12](https://claude-devcontainers.centminmod.com/). Allowing you to run YOLO modes for Claude Code with `dangerously_skip_permissions` enabled and Codex CLI with `sandbox_mode = danger-full-access` etc. +8. Claude Code via Claude Desktop apps use Git Worktrees. You may need to create a `.worktreeinclude` file as outlined [here](https://code.claude.com/docs/en/desktop#claude-code-on-desktop-preview). I also install the following MCP servers ([install commands](#claude-code-mcp-servers)): From 1ed3918540c4e402c214d157e823ab05f4756fc4 Mon Sep 17 00:00:00 2001 From: George Liu Date: Fri, 12 Dec 2025 08:16:24 +1000 Subject: [PATCH 046/174] add cleanupPeriodDays = 365 default instead of 30 days --- .claude/settings.json | 1 + 1 file changed, 1 insertion(+) diff --git a/.claude/settings.json b/.claude/settings.json index 47473af..a8fa900 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -1,5 +1,6 @@ { "model": "sonnet", + "cleanupPeriodDays": 365, "hooks": { "Stop": [ { From cb4d706cdfa2f1058aa9e6a5dcb4a3dfcbdf95be Mon Sep 17 00:00:00 2001 From: George Liu Date: Fri, 12 Dec 2025 08:30:32 +1000 Subject: [PATCH 047/174] update context7 mcp install command --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 5ec39c4..4724091 100644 --- a/README.md +++ b/README.md @@ -418,8 +418,10 @@ claude mcp add --transport sse cf-docs https://docs.mcp.cloudflare.com/sse -s us [Context 7 MCP](https://github.com/upstash/context7) +with API key + ```bash -claude mcp add --transport sse context7 https://mcp.context7.com/sse -s user +claude mcp add --transport http context7 https://mcp.context7.com/mcp --header "CONTEXT7_API_KEY: YOUR_API_KEY" -s user ``` ### Notion MCP Server From 7aa759841c21793a81af04aea56d28049ca38c4e Mon Sep 17 00:00:00 2001 From: George Liu Date: Sat, 13 Dec 2025 18:04:47 +1000 Subject: [PATCH 048/174] add Claude Cloudflare & ClerkOS platform documentation references --- CLAUDE-cloudflare-mini.md | 312 +++++++++++++++ CLAUDE-cloudflare.md | 801 ++++++++++++++++++++++++++++++++++++++ README.md | 1 + 3 files changed, 1114 insertions(+) create mode 100644 CLAUDE-cloudflare-mini.md create mode 100644 CLAUDE-cloudflare.md diff --git a/CLAUDE-cloudflare-mini.md b/CLAUDE-cloudflare-mini.md new file mode 100644 index 0000000..ddcb03b --- /dev/null +++ b/CLAUDE-cloudflare-mini.md @@ -0,0 +1,312 @@ +# CLAUDE.md - Cloudflare Quick Template + +## Project: [NAME] +Auth: Clerk | Platform: Cloudflare Workers/Pages + +--- + +## CRITICAL: Verify Before Coding + +### Step 1: Detect Stack +Inspect project files: +- `package.json` -> Node/TS (check deps: hono, next, remix, astro) +- `requirements.txt` / `pyproject.toml` -> Python Workers +- `go.mod` -> Go | `Cargo.toml` -> Rust +- `index.html` (no package.json) -> Static HTML (use Pages Git Integration) +- No files? -> Run `npm create cloudflare@latest` + +### Step 2: Fetch Documentation +Use MCP tools if available, otherwise web fetch these URLs: + +**Cloudflare:** +| Service | URL | +|---------|-----| +| Workers | https://developers.cloudflare.com/workers/ | +| D1 Get Started | https://developers.cloudflare.com/d1/get-started/ | +| KV | https://developers.cloudflare.com/kv/ | +| R2 | https://developers.cloudflare.com/r2/ | +| Durable Objects | https://developers.cloudflare.com/durable-objects/ | +| Pages | https://developers.cloudflare.com/pages/ | +| Pages Git Integration | https://developers.cloudflare.com/pages/get-started/git-integration/ | +| Pages Functions | https://developers.cloudflare.com/pages/functions/ | + +**Clerk:** +| Resource | URL | +|----------|-----| +| JS Backend SDK | https://clerk.com/docs/js-backend/getting-started/quickstart | +| authenticateRequest() | https://clerk.com/docs/reference/backend/authenticate-request | +| Hono Middleware | https://github.com/honojs/middleware/tree/main/packages/clerk-auth | +| Next.js | https://clerk.com/docs/reference/nextjs/overview | + +**Frameworks:** +| Framework | URL | +|-----------|-----| +| Hono | https://hono.dev/docs/getting-started/cloudflare-workers | +| Next.js | https://developers.cloudflare.com/pages/framework-guides/nextjs/ | +| Drizzle+D1 | https://orm.drizzle.team/docs/get-started/d1-new | + +--- + +## Wrangler Config Reference + +```jsonc +{ + "$schema": "./node_modules/wrangler/config-schema.json", + "name": "app", + "main": "src/index.ts", + "compatibility_date": "2024-12-01", + "compatibility_flags": ["nodejs_compat"], + "d1_databases": [{ "binding": "DB", "database_name": "x", "database_id": "x" }], + "kv_namespaces": [{ "binding": "KV", "id": "x" }], + "r2_buckets": [{ "binding": "BUCKET", "bucket_name": "x" }] +} +``` + +--- + +## Cloudflare Pages: Static HTML via GitHub + +For static HTML sites (no build step). Docs: https://developers.cloudflare.com/pages/get-started/git-integration/ + +### Setup (Dashboard) +1. **Dashboard > Workers & Pages > Create > Pages > Connect to Git** +2. Select GitHub repo +3. Build command: *(empty)* | Output directory: `/` or `/public` +4. Deploy + +### Static Site Structure +``` +/ +├── index.html +├── about.html +├── css/style.css +├── js/app.js +├── _headers # Optional: caching/security headers +└── _redirects # Optional: redirect rules +``` + +### Adding API Routes (Pages Functions) +``` +/ +├── index.html +├── functions/ +│ └── api/ +│ └── hello.ts # -> /api/hello +``` + +**functions/api/hello.ts:** +```typescript +// Use PagesFunction when you have bindings (D1, KV, etc.) +export const onRequest: PagesFunction = async (context) => { + return Response.json({ message: 'Hello!' }) +} +``` + +### CLI Commands +```bash +wrangler pages dev ./ # Local dev +wrangler pages deploy ./ --project-name=my-site # Deploy +``` + +--- + +## Clerk Patterns (VERIFY CURRENT API BEFORE USE) + +**Hono (@hono/clerk-auth):** +```typescript +import { Hono } from 'hono' +import { clerkMiddleware, getAuth } from '@hono/clerk-auth' + +const app = new Hono<{ Bindings: Env }>() +app.use('*', clerkMiddleware()) +app.get('/api/*', (c) => { + const auth = getAuth(c) + if (!auth?.userId) return c.json({ error: 'Unauthorized' }, 401) + return c.json({ userId: auth.userId }) +}) +export default app +``` + +**Raw Workers (@clerk/backend):** +```typescript +import { createClerkClient } from '@clerk/backend' + +export default { + async fetch(request: Request, env: Env): Promise { + // BOTH keys required! + const clerkClient = createClerkClient({ + secretKey: env.CLERK_SECRET_KEY, + publishableKey: env.CLERK_PUBLISHABLE_KEY, + }) + + const { isAuthenticated, toAuth } = await clerkClient.authenticateRequest(request, { + authorizedParties: ['https://your-domain.com'] + }) + + if (!isAuthenticated) { + return new Response('Unauthorized', { status: 401 }) + } + + const auth = toAuth() + return new Response(JSON.stringify({ userId: auth.userId })) + } +} +``` + +--- + +## Secrets +- `.dev.vars` for local (gitignore!) +- `wrangler secret put KEY` for prod +- **Required for Clerk:** `CLERK_SECRET_KEY` AND `CLERK_PUBLISHABLE_KEY` + +--- + +## Commands Reference + +### Wrangler CLI Documentation +Full reference: https://developers.cloudflare.com/workers/wrangler/commands/ + +```bash +# ============================================================================ +# PROJECT SETUP +# Docs: https://developers.cloudflare.com/workers/get-started/guide/ +# ============================================================================ +npm create cloudflare@latest # Interactive project creation +npm create cloudflare@latest my-app # Named project +npm create cloudflare@latest -- --template hono # With template + +# ============================================================================ +# LOCAL DEVELOPMENT +# Workers: https://developers.cloudflare.com/workers/wrangler/commands/#dev +# Pages: https://developers.cloudflare.com/pages/functions/local-development/ +# ============================================================================ +wrangler dev # Workers dev server (localhost:8787) +wrangler dev --port 3000 # Custom port +wrangler dev --remote # Use REAL cloud resources (CAUTION!) + +wrangler pages dev ./ # Pages dev server (localhost:8788) +wrangler pages dev ./dist # Pages with build output dir +wrangler pages dev ./ --d1=DB # Pages with D1 binding + +# ============================================================================ +# DEPLOYMENT +# Docs: https://developers.cloudflare.com/workers/wrangler/commands/#deploy +# ============================================================================ +wrangler deploy # Deploy Worker to production +wrangler deploy --env staging # Deploy to environment + +wrangler pages deploy ./dist --project-name=my-site # Deploy Pages +wrangler pages project create my-site # Create Pages project first + +# ============================================================================ +# D1 DATABASE (SQLite) +# Docs: https://developers.cloudflare.com/d1/wrangler-commands/ +# ============================================================================ +wrangler d1 create # Create DB (returns database_id for config) +wrangler d1 list # List all databases + +# Execute SQL (--local for dev, --remote for production) +wrangler d1 execute --local --file=./schema.sql # Local +wrangler d1 execute --remote --file=./schema.sql # PRODUCTION (careful!) +wrangler d1 execute --local --command="SELECT * FROM users" + +# Migrations (recommended for schema changes) +# Docs: https://developers.cloudflare.com/d1/reference/migrations/ +wrangler d1 migrations create # Create migration file +wrangler d1 migrations apply --local # Apply locally +wrangler d1 migrations apply --remote # Apply to production + +# ============================================================================ +# KV STORAGE (Key-Value, eventually consistent) +# Docs: https://developers.cloudflare.com/kv/reference/kv-commands/ +# ============================================================================ +wrangler kv namespace create # Create namespace (returns id) +wrangler kv namespace create --preview # Create preview namespace +wrangler kv namespace list # List namespaces + +wrangler kv key put --binding=KV "key" "value" --local # Put (local) +wrangler kv key put --binding=KV "key" "value" # Put (production) +wrangler kv key get --binding=KV "key" # Get value +wrangler kv key list --binding=KV # List keys + +# ============================================================================ +# R2 OBJECT STORAGE (S3-compatible) +# Docs: https://developers.cloudflare.com/r2/api/wrangler/ +# ============================================================================ +wrangler r2 bucket create # Create bucket +wrangler r2 bucket list # List buckets +wrangler r2 object put / --file=./file.txt # Upload +wrangler r2 object get / # Download + +# ============================================================================ +# SECRETS (Encrypted env vars for production) +# Docs: https://developers.cloudflare.com/workers/wrangler/commands/#secret +# ============================================================================ +wrangler secret put # Add secret (prompts for value) +echo "value" | wrangler secret put # Add from stdin (CI/CD) +wrangler secret list # List secret names +wrangler secret delete # Delete secret + +# ============================================================================ +# TYPESCRIPT & DEBUGGING +# ============================================================================ +wrangler types # Generate Env types from config + # Docs: https://developers.cloudflare.com/workers/wrangler/commands/#types + +wrangler tail # Stream production logs +wrangler tail --status=error # Filter by status +wrangler tail --format=json # JSON output + # Docs: https://developers.cloudflare.com/workers/wrangler/commands/#tail + +# ============================================================================ +# AUTH +# ============================================================================ +wrangler login # Login to Cloudflare (opens browser) +wrangler whoami # Check current user +wrangler logout # Logout +``` + +### Key Command Patterns for AI + +```bash +# Pattern: Local vs Remote operations +# --local = Uses local simulation (safe for development) +# --remote = Uses PRODUCTION resources (be careful!) + +# Pattern: Bindings in Pages dev +# Pass bindings via CLI when no wrangler.toml: +wrangler pages dev ./ --d1=DB --kv=CACHE --r2=STORAGE + +# Pattern: Environment-specific operations +wrangler deploy --env staging +wrangler secret put API_KEY --env staging +wrangler tail --env staging + +# Pattern: Get resource IDs for wrangler config +wrangler d1 create my-db # Output includes database_id +wrangler kv namespace create CACHE # Output includes namespace id +# Add these IDs to wrangler.toml/wrangler.jsonc bindings +``` + +--- + +## Key Constraints +| Limit | Value | +|-------|-------| +| D1 rows/query | 1000 (use pagination) | +| KV consistency | Eventually consistent | +| Workers CPU | 30s paid / 10ms free | +| R2 object size | 5TB max | + +**Gotchas:** +- Clone request before reading body twice +- Use `nodejs_compat` flag for Node APIs +- Clerk `@clerk/backend` needs BOTH secretKey AND publishableKey +- D1 transactions: `await db.batch([stmt1, stmt2])` +- Set `authorizedParties` in Clerk to prevent CSRF + +--- + +## Notes + \ No newline at end of file diff --git a/CLAUDE-cloudflare.md b/CLAUDE-cloudflare.md new file mode 100644 index 0000000..8e58e6f --- /dev/null +++ b/CLAUDE-cloudflare.md @@ -0,0 +1,801 @@ +# CLAUDE.md - Cloudflare Platform Project Template + +## Project Overview +- **Project Name**: [PROJECT_NAME] +- **Description**: [BRIEF_DESCRIPTION] +- **Auth Provider**: Clerk + +--- + +## CRITICAL: Documentation Verification Rules + +### Before Writing ANY Code +1. **Determine project language/framework** by inspecting project files +2. **Lookup current documentation** for the detected stack before implementing +3. **Never assume** API signatures, binding syntax, or SDK methods + +### MCP Tools (if available) +- **context7 MCP**: Query for latest documentation +- **Cloudflare MCP**: List/create resources, search docs, verify resource IDs + +### Documentation URLs (for web fetch if no MCP) +Fetch and read these URLs to verify current APIs: + +**Cloudflare Platform:** +| Service | URL | +|---------|-----| +| Workers | https://developers.cloudflare.com/workers/ | +| D1 (SQLite) | https://developers.cloudflare.com/d1/ | +| D1 Get Started | https://developers.cloudflare.com/d1/get-started/ | +| KV | https://developers.cloudflare.com/kv/ | +| R2 (Objects) | https://developers.cloudflare.com/r2/ | +| Durable Objects | https://developers.cloudflare.com/durable-objects/ | +| Queues | https://developers.cloudflare.com/queues/ | +| Workers AI | https://developers.cloudflare.com/workers-ai/ | +| Hyperdrive | https://developers.cloudflare.com/hyperdrive/ | +| Workflows | https://developers.cloudflare.com/workflows/ | +| Pages | https://developers.cloudflare.com/pages/ | +| Pages Git Integration | https://developers.cloudflare.com/pages/get-started/git-integration/ | +| Pages Functions | https://developers.cloudflare.com/pages/functions/ | +| Pages Functions Config | https://developers.cloudflare.com/pages/functions/wrangler-configuration/ | +| Wrangler Config | https://developers.cloudflare.com/workers/wrangler/configuration/ | + +**Clerk Authentication:** +| Resource | URL | +|----------|-----| +| Backend SDK Overview | https://clerk.com/docs/reference/backend/overview | +| JS Backend SDK Quickstart | https://clerk.com/docs/js-backend/getting-started/quickstart | +| authenticateRequest() Reference | https://clerk.com/docs/reference/backend/authenticate-request | +| Express SDK | https://clerk.com/docs/reference/express/overview | +| Next.js SDK | https://clerk.com/docs/reference/nextjs/overview | +| Hono Middleware (Community) | https://github.com/honojs/middleware/tree/main/packages/clerk-auth | + +**Framework Deployment Guides:** +| Framework | URL | +|-----------|-----| +| Hono on Workers | https://hono.dev/docs/getting-started/cloudflare-workers | +| Next.js on Pages | https://developers.cloudflare.com/pages/framework-guides/nextjs/ | +| Remix on Pages | https://developers.cloudflare.com/pages/framework-guides/deploy-a-remix-site/ | +| Astro on Pages | https://developers.cloudflare.com/pages/framework-guides/deploy-an-astro-site/ | +| SvelteKit on Pages | https://developers.cloudflare.com/pages/framework-guides/deploy-a-svelte-kit-site/ | + +**ORM/Database:** +| Tool | URL | +|------|-----| +| Drizzle + D1 | https://orm.drizzle.team/docs/get-started/d1-new | + +--- + +## Project Detection & Setup + +### Step 1: Detect Existing Project Type +Inspect project files to determine language/framework: + +``` +File Found -> Stack -> Action +----------------------------------------------------------------- +package.json -> Node.js/TypeScript -> Check dependencies for framework + - "hono" -> Hono -> Fetch Hono + CF Workers docs + - "next" -> Next.js -> Fetch Next.js + CF Pages docs + - "@remix-run/*" -> Remix -> Fetch Remix + CF Pages docs + - "astro" -> Astro -> Fetch Astro + CF Pages docs + - No framework -> Raw Worker -> Fetch Workers docs only + +requirements.txt -> Python Workers -> Add compatibility_flags: ["python_workers"] +pyproject.toml -> Python Workers -> Add compatibility_flags: ["python_workers"] +go.mod -> Go (WASM) -> Fetch Go Workers docs +Cargo.toml -> Rust (WASM) -> Fetch Rust Workers docs +wrangler.toml/.jsonc -> Existing config -> Follow existing patterns + +index.html (no package.json) -> Static HTML -> Use Pages Git Integration (no build) +*.html files only -> Static HTML -> Use Pages Git Integration (no build) +``` + +### Step 2: New Project Setup (if no manifest files) +```bash +# Create new Workers project +npm create cloudflare@latest -- my-app + +# Or with specific template +npm create cloudflare@latest -- my-app --template hono +``` + +### Step 3: Install Dependencies (after detection) +```bash +# Core (always needed for local dev) +npm install wrangler --save-dev + +# Hono (if using) +npm install hono + +# Clerk (choose based on framework) +npm install @clerk/backend # Raw Workers (also needs publishableKey!) +npm install @hono/clerk-auth @clerk/backend # Hono (both packages required) +npm install @clerk/nextjs # Next.js +npm install @clerk/express # Express + +# Drizzle ORM (if using D1) +npm install drizzle-orm +npm install drizzle-kit --save-dev +``` + +--- + +## Wrangler Configuration + +### Config File (wrangler.jsonc preferred) +```jsonc +{ + "$schema": "./node_modules/wrangler/config-schema.json", + "name": "project-name", + "main": "src/index.ts", + "compatibility_date": "2024-12-01", + "compatibility_flags": ["nodejs_compat"] +} +``` + +### Binding Configurations + +**D1 Database:** +```jsonc +"d1_databases": [ + { "binding": "DB", "database_name": "my-db", "database_id": "UUID_HERE" } +] +``` + +**KV Namespace:** +```jsonc +"kv_namespaces": [ + { "binding": "KV", "id": "NAMESPACE_ID", "preview_id": "PREVIEW_ID" } +] +``` + +**R2 Bucket:** +```jsonc +"r2_buckets": [ + { "binding": "BUCKET", "bucket_name": "my-bucket" } +] +``` + +**Durable Objects:** +```jsonc +"durable_objects": { + "bindings": [{ "name": "MY_DO", "class_name": "MyDurableObject" }] +}, +"migrations": [{ "tag": "v1", "new_classes": ["MyDurableObject"] }] +``` + +**Queues:** +```jsonc +"queues": { + "producers": [{ "binding": "QUEUE", "queue": "my-queue" }], + "consumers": [{ "queue": "my-queue", "max_batch_size": 10 }] +} +``` + +**Workers AI:** +```jsonc +"ai": { "binding": "AI" } +``` + +**Hyperdrive (external Postgres):** +```jsonc +"hyperdrive": [ + { "binding": "HYPERDRIVE", "id": "HYPERDRIVE_ID" } +] +``` + +**Static Assets:** +```jsonc +"assets": { "directory": "./public" } +``` + +--- + +## Cloudflare Pages: Static HTML via GitHub + +For pure static HTML sites deployed via GitHub integration (no build step required). + +### Documentation +| Resource | URL | +|----------|-----| +| Pages Get Started | https://developers.cloudflare.com/pages/get-started/git-integration/ | +| Pages Functions | https://developers.cloudflare.com/pages/functions/ | +| Pages Direct Upload | https://developers.cloudflare.com/pages/get-started/direct-upload/ | + +### Setup via Cloudflare Dashboard (Recommended) +1. Go to **Cloudflare Dashboard > Workers & Pages > Create > Pages > Connect to Git** +2. Select your GitHub repository +3. Configure build settings: + - **Build command**: *(leave empty for static HTML)* + - **Build output directory**: `/` or your HTML folder (e.g., `/public`) +4. Deploy + +### Repository Structure (Static HTML) +``` +/ +├── index.html # Homepage +├── about.html # Other pages +├── css/ +│ └── style.css +├── js/ +│ └── app.js +├── images/ +│ └── logo.png +└── _headers # Optional: custom headers +``` + +### Optional: `_headers` File (for caching, security) +``` +/* + X-Frame-Options: DENY + X-Content-Type-Options: nosniff + +/css/* + Cache-Control: public, max-age=31536000 + +/images/* + Cache-Control: public, max-age=31536000 +``` + +### Optional: `_redirects` File +``` +/old-page /new-page 301 +/blog/* /articles/:splat 302 +``` + +### Adding API Routes (Pages Functions) +To add server-side API routes to a static site, create a `functions/` directory: + +``` +/ +├── index.html +├── functions/ +│ ├── api/ +│ │ └── hello.ts # Accessible at /api/hello +│ └── _middleware.ts # Optional: runs on all routes +└── ... +``` + +**Example `functions/api/hello.ts`:** +```typescript +// VERIFY at: https://developers.cloudflare.com/pages/functions/ +// PagesFunction type is globally available in Pages Functions + +export const onRequest: PagesFunction = async (context) => { + return Response.json({ message: 'Hello from Pages Function!' }) +} +``` + +**Example `functions/api/hello.ts` with D1:** +```typescript +// Define Env interface for typed bindings +interface Env { + DB: D1Database +} + +export const onRequest: PagesFunction = async (context) => { + const result = await context.env.DB.prepare('SELECT * FROM users LIMIT 10').all() + return Response.json(result) +} +``` + +### Bindings for Pages Functions +Create `wrangler.toml` in project root for Pages Function bindings: +```toml +name = "my-static-site" +pages_build_output_dir = "./" +compatibility_date = "2024-12-01" + +[[d1_databases]] +binding = "DB" +database_name = "my-db" +database_id = "UUID_HERE" + +[[kv_namespaces]] +binding = "KV" +id = "NAMESPACE_ID" +``` + +### CLI Deployment (Alternative to GitHub) +```bash +# Install wrangler +npm install wrangler --save-dev + +# Deploy directly (no GitHub needed) +wrangler pages deploy ./public --project-name=my-site + +# Or create project first +wrangler pages project create my-site +wrangler pages deploy ./ --project-name=my-site +``` + +### Local Development +```bash +# Serve static files + Pages Functions locally +wrangler pages dev ./ + +# With specific port +wrangler pages dev ./ --port 3000 + +# With bindings (D1, KV, etc.) +wrangler pages dev ./ --d1=DB +``` + +### Custom Domain +1. Dashboard: **Pages project > Custom domains > Set up a custom domain** +2. Add CNAME record pointing to `.pages.dev` +3. SSL provisioned automatically + +--- + +## TypeScript Environment Types + +### Generate Types +```bash +wrangler types +``` + +Creates `worker-configuration.d.ts`. Define your Env interface: + +```typescript +// src/types.ts +interface Env { + DB: D1Database + KV: KVNamespace + BUCKET: R2Bucket + CLERK_SECRET_KEY: string + CLERK_PUBLISHABLE_KEY: string + // Add other bindings as needed +} +``` + +--- + +## Clerk Authentication + +### Required Secrets +Local (`.dev.vars` - NEVER commit): +``` +CLERK_SECRET_KEY=sk_test_xxx +CLERK_PUBLISHABLE_KEY=pk_test_xxx +``` + +Production: +```bash +wrangler secret put CLERK_SECRET_KEY +wrangler secret put CLERK_PUBLISHABLE_KEY +``` + +### Pattern: Hono + @hono/clerk-auth (Community SDK) +```typescript +// VERIFY at: https://github.com/honojs/middleware/tree/main/packages/clerk-auth +import { Hono } from 'hono' +import { clerkMiddleware, getAuth } from '@hono/clerk-auth' + +const app = new Hono<{ Bindings: Env }>() + +app.use('*', clerkMiddleware()) + +app.get('/protected', (c) => { + const auth = getAuth(c) + if (!auth?.userId) { + return c.json({ error: 'Unauthorized' }, 401) + } + return c.json({ userId: auth.userId }) +}) + +export default app +``` + +### Pattern: Raw Workers + @clerk/backend +```typescript +// VERIFY at: https://clerk.com/docs/reference/backend/authenticate-request +// IMPORTANT: Both secretKey AND publishableKey are REQUIRED +import { createClerkClient } from '@clerk/backend' + +export default { + async fetch(request: Request, env: Env): Promise { + const clerkClient = createClerkClient({ + secretKey: env.CLERK_SECRET_KEY, + publishableKey: env.CLERK_PUBLISHABLE_KEY, // REQUIRED! + }) + + // authenticateRequest returns { isAuthenticated, toAuth(), ... } + const { isAuthenticated, toAuth } = await clerkClient.authenticateRequest(request, { + authorizedParties: ['https://your-domain.com'] // Recommended for security + }) + + if (!isAuthenticated) { + return new Response('Unauthorized', { status: 401 }) + } + + // Get full Auth object if needed + const auth = toAuth() + // auth.userId, auth.sessionId, auth.orgId available + + return new Response(JSON.stringify({ userId: auth.userId }), { + headers: { 'Content-Type': 'application/json' } + }) + } +} +``` + +--- + +## Development Commands + +### Wrangler CLI Reference +Documentation: https://developers.cloudflare.com/workers/wrangler/commands/ + +```bash +# ============================================================================ +# LOCAL DEVELOPMENT +# Docs: https://developers.cloudflare.com/workers/wrangler/commands/#dev +# ============================================================================ + +# Start local development server for Workers +# - Runs on http://localhost:8787 by default +# - Hot reloads on file changes +# - Uses .dev.vars for local secrets +# - Simulates Cloudflare runtime locally (miniflare) +wrangler dev + +# Start with specific port +wrangler dev --port 3000 + +# Start with remote resources (connects to real D1/KV/R2 in Cloudflare) +# WARNING: This uses PRODUCTION data! Use with caution. +wrangler dev --remote + +# Start for Pages project (different from Workers) +# Docs: https://developers.cloudflare.com/pages/functions/local-development/ +# - Runs on http://localhost:8788 by default +# - Serves static files + Pages Functions +wrangler pages dev ./ + +# Pages dev with specific output directory +wrangler pages dev ./dist + +# Pages dev with bindings passed via CLI (alternative to wrangler.toml) +wrangler pages dev ./ --d1=DB --kv=KV --r2=BUCKET + +# ============================================================================ +# DEPLOYMENT +# Docs: https://developers.cloudflare.com/workers/wrangler/commands/#deploy +# ============================================================================ + +# Deploy Worker to Cloudflare (production) +# - Reads wrangler.toml/wrangler.jsonc for configuration +# - Uploads code and applies bindings +# - Returns deployment URL +wrangler deploy + +# Deploy specific script (overrides config) +wrangler deploy src/index.ts + +# Deploy to specific environment (if using wrangler environments) +# Docs: https://developers.cloudflare.com/workers/wrangler/environments/ +wrangler deploy --env staging + +# Deploy Pages project directly (without Git integration) +# Docs: https://developers.cloudflare.com/workers/wrangler/commands/#deploy-1 +wrangler pages deploy ./dist --project-name=my-site + +# Create Pages project first (required for first deploy) +wrangler pages project create my-site + +# ============================================================================ +# D1 DATABASE OPERATIONS +# Docs: https://developers.cloudflare.com/d1/wrangler-commands/ +# D1 is Cloudflare's serverless SQLite database +# ============================================================================ + +# Create a new D1 database +# Returns database_id to add to wrangler config +wrangler d1 create + +# List all D1 databases in account +wrangler d1 list + +# Get info about specific database +wrangler d1 info + +# Execute SQL file against LOCAL database (for development) +# --local flag uses local SQLite, not production +wrangler d1 execute --local --file=./schema.sql + +# Execute SQL file against REMOTE/PRODUCTION database +# WARNING: This modifies production data! +wrangler d1 execute --remote --file=./schema.sql + +# Execute inline SQL locally +wrangler d1 execute --local --command="SELECT * FROM users" + +# Execute inline SQL remotely +wrangler d1 execute --remote --command="SELECT * FROM users" + +# D1 Migrations (recommended for schema changes) +# Docs: https://developers.cloudflare.com/d1/reference/migrations/ + +# Create a new migration file (creates migrations/ directory) +wrangler d1 migrations create +# Creates: migrations/0001_.sql + +# Apply migrations to LOCAL database +wrangler d1 migrations apply --local + +# Apply migrations to REMOTE/PRODUCTION database +wrangler d1 migrations apply --remote + +# List migration status +wrangler d1 migrations list + +# ============================================================================ +# KV NAMESPACE OPERATIONS +# Docs: https://developers.cloudflare.com/kv/reference/kv-commands/ +# KV is Cloudflare's key-value storage (eventually consistent) +# ============================================================================ + +# Create a new KV namespace +# Returns namespace ID to add to wrangler config +wrangler kv namespace create + +# Create preview namespace (for wrangler dev) +wrangler kv namespace create --preview + +# List all KV namespaces +wrangler kv namespace list + +# Delete a KV namespace +wrangler kv namespace delete --namespace-id= + +# Put a key-value pair (local development) +wrangler kv key put --binding=KV "my-key" "my-value" --local + +# Put a key-value pair (production) +wrangler kv key put --binding=KV "my-key" "my-value" + +# Get a value by key +wrangler kv key get --binding=KV "my-key" + +# Delete a key +wrangler kv key delete --binding=KV "my-key" + +# List keys in namespace +wrangler kv key list --binding=KV + +# Bulk upload from JSON file +# File format: [{"key": "k1", "value": "v1"}, ...] +wrangler kv bulk put --binding=KV ./data.json + +# ============================================================================ +# R2 OBJECT STORAGE OPERATIONS +# Docs: https://developers.cloudflare.com/r2/api/wrangler/ +# R2 is Cloudflare's S3-compatible object storage (zero egress fees) +# ============================================================================ + +# Create a new R2 bucket +wrangler r2 bucket create + +# List all R2 buckets +wrangler r2 bucket list + +# Delete an R2 bucket (must be empty) +wrangler r2 bucket delete + +# Upload object to bucket +wrangler r2 object put / --file=./myfile.txt + +# Download object from bucket +wrangler r2 object get / + +# Delete object from bucket +wrangler r2 object delete / + +# ============================================================================ +# SECRETS MANAGEMENT +# Docs: https://developers.cloudflare.com/workers/wrangler/commands/#secret +# Secrets are encrypted environment variables for production +# ============================================================================ + +# Add/update a secret (interactive prompt for value) +# Secret is encrypted and stored securely +wrangler secret put + +# Add secret with value from stdin (useful for CI/CD) +echo "secret-value" | wrangler secret put + +# List all secrets (shows names only, not values) +wrangler secret list + +# Delete a secret +wrangler secret delete + +# Add secret to specific environment +wrangler secret put --env staging + +# ============================================================================ +# TYPESCRIPT TYPES GENERATION +# Docs: https://developers.cloudflare.com/workers/wrangler/commands/#types +# Generates TypeScript types for your bindings +# ============================================================================ + +# Generate types from wrangler config +# Creates worker-configuration.d.ts with Env interface +wrangler types + +# Output to specific file +wrangler types --env-interface CloudflareBindings + +# ============================================================================ +# LOGS AND DEBUGGING +# Docs: https://developers.cloudflare.com/workers/wrangler/commands/#tail +# ============================================================================ + +# Stream real-time logs from deployed Worker +# Shows console.log output, errors, and request info +wrangler tail + +# Filter logs by status +wrangler tail --status=error + +# Filter by HTTP method +wrangler tail --method=POST + +# Filter by search string +wrangler tail --search="error" + +# Filter by IP address +wrangler tail --ip=1.2.3.4 + +# Tail specific environment +wrangler tail --env staging + +# Output as JSON (useful for piping to other tools) +wrangler tail --format=json + +# ============================================================================ +# QUEUES OPERATIONS +# Docs: https://developers.cloudflare.com/queues/configuration/wrangler-commands/ +# ============================================================================ + +# Create a new queue +wrangler queues create + +# List all queues +wrangler queues list + +# Delete a queue +wrangler queues delete + +# ============================================================================ +# DURABLE OBJECTS +# Docs: https://developers.cloudflare.com/durable-objects/ +# Note: Durable Objects are defined in code and deployed with wrangler deploy +# Migrations are specified in wrangler config +# ============================================================================ + +# No specific CLI commands - DO is configured in wrangler.toml: +# "durable_objects": { "bindings": [{ "name": "MY_DO", "class_name": "MyClass" }] } +# "migrations": [{ "tag": "v1", "new_classes": ["MyClass"] }] + +# ============================================================================ +# HYPERDRIVE (External Postgres Connection Pooling) +# Docs: https://developers.cloudflare.com/hyperdrive/ +# ============================================================================ + +# Create Hyperdrive config (connects to external Postgres) +wrangler hyperdrive create --connection-string="postgres://user:pass@host:5432/db" + +# List Hyperdrive configs +wrangler hyperdrive list + +# Get Hyperdrive config details +wrangler hyperdrive get + +# Delete Hyperdrive config +wrangler hyperdrive delete + +# ============================================================================ +# WORKERS AI +# Docs: https://developers.cloudflare.com/workers-ai/ +# Note: AI binding is configured in wrangler.toml: "ai": { "binding": "AI" } +# No specific CLI commands - models are accessed via env.AI.run() +# ============================================================================ + +# ============================================================================ +# PROJECT INITIALIZATION +# Docs: https://developers.cloudflare.com/workers/get-started/guide/ +# ============================================================================ + +# Create new project interactively +npm create cloudflare@latest + +# Create with specific name +npm create cloudflare@latest my-app + +# Create with specific template +npm create cloudflare@latest my-app -- --template hono +npm create cloudflare@latest my-app -- --template worker-typescript + +# ============================================================================ +# AUTHENTICATION +# Docs: https://developers.cloudflare.com/workers/wrangler/commands/#login +# ============================================================================ + +# Login to Cloudflare (opens browser) +wrangler login + +# Check login status +wrangler whoami + +# Logout +wrangler logout +``` + +--- + +## Platform Constraints + +| Service | Constraint | Notes | +|---------|------------|-------| +| Workers | 30s CPU (paid), 10ms (free) | Use streaming for long operations | +| Workers | 128MB memory | | +| D1 | 1000 rows per query | Use LIMIT/OFFSET pagination | +| D1 | 100KB per row | | +| D1 | Transactions via `db.batch()` | | +| KV | Eventually consistent | Not for real-time coordination | +| KV | 25MB per value | | +| R2 | 5TB per object | S3-compatible API | +| Durable Objects | Single-threaded per instance | Use for coordination, WebSockets | + +### Common Gotchas +1. **Clone Request** before reading body twice: `const clone = request.clone()` +2. **nodejs_compat flag** required for most Node.js APIs +3. **Not all Node.js APIs** available even with nodejs_compat (e.g., `async_hooks`) +4. **Clerk @clerk/backend** requires BOTH `secretKey` AND `publishableKey` +5. **D1 batch** for transactions: `await db.batch([stmt1, stmt2])` +6. **authorizedParties** recommended for Clerk to prevent CSRF attacks + +--- + +## Pre-Implementation Checklist + +Before writing code: +- [ ] Detected project language/framework from manifest files +- [ ] Fetched and read relevant documentation URLs +- [ ] Verified current API signatures (especially Clerk SDK) +- [ ] Created/verified wrangler config with correct binding names +- [ ] Generated TypeScript types with `wrangler types` +- [ ] Set up `.dev.vars` for local secrets (both CLERK keys!) +- [ ] Added `.dev.vars` to `.gitignore` + +--- + +## Project Structure (Reference) + +``` +/ +├── src/ +│ ├── index.ts # Worker entry point +│ ├── routes/ # Route handlers +│ ├── middleware/ # Auth, logging +│ ├── services/ # Business logic +│ ├── db/ +│ │ ├── schema.ts # Drizzle schema +│ │ └── migrations/ # D1 migrations +│ └── types.ts # Env interface, shared types +├── wrangler.jsonc # Wrangler configuration +├── drizzle.config.ts # Drizzle config (if using) +├── .dev.vars # Local secrets (gitignored!) +├── .gitignore # Must include .dev.vars +├── package.json +├── tsconfig.json +└── CLAUDE.md # This file +``` + +--- + +## Notes + \ No newline at end of file diff --git a/README.md b/README.md index 4724091..74e45c6 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,7 @@ My Claude Code project's starter settings and Claude Code hooks and slash comman 6. CLAUDE.md updated to instruct models to use faster tools so for macOS: `brew install ripgrep fd jq` 7. Optional step to setup Claude Code, Codex GPT-5, Gemini CLI, OpenCode, Vercel CLI, Cloudflare Wrangler, Amazon AWS CLI, all in a single isolated [Visual Studio Code dev container running Debian 12](https://claude-devcontainers.centminmod.com/). Allowing you to run YOLO modes for Claude Code with `dangerously_skip_permissions` enabled and Codex CLI with `sandbox_mode = danger-full-access` etc. 8. Claude Code via Claude Desktop apps use Git Worktrees. You may need to create a `.worktreeinclude` file as outlined [here](https://code.claude.com/docs/en/desktop#claude-code-on-desktop-preview). +9. If you use Cloudflare and ClerkOS platforms in your apps, you can keep either `CLAUDE-cloudflare.md` or `CLAUDE-cloudflare-mini.md` supplementary reference docs and update `CLAUDE.md` referencing either file to help AI understand Cloudflare and ClerkOS platforum documentation and products. Edit documentation templates as needed i.e. if you do not use ClerkOS platform, you can remove those sections. I also install the following MCP servers ([install commands](#claude-code-mcp-servers)): From 071e86651d8f30b4b1e487f7d33ef8f24c539ccf Mon Sep 17 00:00:00 2001 From: George Liu Date: Sun, 14 Dec 2025 00:07:46 +1000 Subject: [PATCH 049/174] add statusline.sh example --- README.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/README.md b/README.md index 74e45c6..837444f 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,62 @@ I also install the following MCP servers ([install commands](#claude-code-mcp-se * [Notion MCP](https://github.com/makenotion/notion-mcp-server) * [Claude Code Usage Metrics MCP](https://github.com/centminmod/claude-code-opentelemetry-setup) +## Claude Code Statuslines + +`~/.claude/statuslines/statusline.sh` configured in `~/.claude/settings.json`. + +for `~/.claude/settings.json` + +```bash + "statusLine": { + "type": "command", + "command": "~/.claude/statuslines/statusline.sh", + "padding": 0 + }, +``` + +for `~/.claude/statuslines/statusline.sh` + +```bash +#!/bin/bash +# Read JSON input from stdin +input=$(cat) + +# Extract model and workspace values +MODEL_DISPLAY=$(echo "$input" | jq -r '.model.display_name') +CURRENT_DIR=$(echo "$input" | jq -r '.workspace.current_dir') + +# Extract context window metrics +INPUT_TOKENS=$(echo "$input" | jq -r '.context_window.total_input_tokens') +OUTPUT_TOKENS=$(echo "$input" | jq -r '.context_window.total_output_tokens') +CONTEXT_SIZE=$(echo "$input" | jq -r '.context_window.context_window_size') + +# Format tokens as Xk +format_tokens() { + local num=$1 + if [ "$num" -ge 1000 ]; then + echo "$((num / 1000))k" + else + echo "$num" + fi +} + +# Calculate total +TOTAL_TOKENS=$((INPUT_TOKENS + OUTPUT_TOKENS)) + +# Show git branch if in a git repo +GIT_BRANCH="" +if git rev-parse --git-dir > /dev/null 2>&1; then + BRANCH=$(git branch --show-current 2>/dev/null) + if [ -n "$BRANCH" ]; then + GIT_BRANCH=" | 🌿 $BRANCH" + fi +fi + +echo "[$MODEL_DISPLAY] 📁 ${CURRENT_DIR##*/}$GIT_BRANCH +Tokens: $(format_tokens "$TOTAL_TOKENS") (in:$(format_tokens "$INPUT_TOKENS")+out:$(format_tokens "$OUTPUT_TOKENS")) | Ctx:$(format_tokens "$CONTEXT_SIZE")" +``` + ## Claude Code Skills Claude Code now supports [Agent Skills](https://docs.claude.com/en/docs/claude-code/skills). From 9d7919d0cddef1df8e7291cebdd0b711a80a8cf8 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sun, 14 Dec 2025 00:12:37 +1000 Subject: [PATCH 050/174] update statusline.sh for costs/lines added/removed --- README.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 837444f..84805c9 100644 --- a/README.md +++ b/README.md @@ -56,9 +56,14 @@ INPUT_TOKENS=$(echo "$input" | jq -r '.context_window.total_input_tokens') OUTPUT_TOKENS=$(echo "$input" | jq -r '.context_window.total_output_tokens') CONTEXT_SIZE=$(echo "$input" | jq -r '.context_window.context_window_size') +# Extract cost metrics +COST_USD=$(echo "$input" | jq -r '.cost.total_cost_usd') +LINES_ADDED=$(echo "$input" | jq -r '.cost.total_lines_added') +LINES_REMOVED=$(echo "$input" | jq -r '.cost.total_lines_removed') + # Format tokens as Xk format_tokens() { - local num=$1 + local num="$1" if [ "$num" -ge 1000 ]; then echo "$((num / 1000))k" else @@ -78,8 +83,9 @@ if git rev-parse --git-dir > /dev/null 2>&1; then fi fi -echo "[$MODEL_DISPLAY] 📁 ${CURRENT_DIR##*/}$GIT_BRANCH -Tokens: $(format_tokens "$TOTAL_TOKENS") (in:$(format_tokens "$INPUT_TOKENS")+out:$(format_tokens "$OUTPUT_TOKENS")) | Ctx:$(format_tokens "$CONTEXT_SIZE")" +echo "[$MODEL_DISPLAY] 📁 ${CURRENT_DIR##*/}${GIT_BRANCH} +Tokens: $(format_tokens "$TOTAL_TOKENS") (in:$(format_tokens "$INPUT_TOKENS")+out:$(format_tokens "$OUTPUT_TOKENS")) | Ctx:$(format_tokens "$CONTEXT_SIZE") +Cost: \$${COST_USD} | +${LINES_ADDED} -${LINES_REMOVED} lines" ``` ## Claude Code Skills From 0e14be1f05cadd5792086b5adae8f97645742868 Mon Sep 17 00:00:00 2001 From: George Liu Date: Mon, 15 Dec 2025 01:32:15 +1000 Subject: [PATCH 051/174] update settings --- .claude/settings.local.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.claude/settings.local.json b/.claude/settings.local.json index d445154..2196464 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -80,7 +80,8 @@ "mcp__chrome-devtools__fill", "mcp__chrome-devtools__navigate_page_history", "mcp__chrome-devtools__new_page", - "Bash(git log:*)" + "Bash(git log:*)", + "Skill(claude-docs-consultant)" ], "deny": [] } From 29549641d0b84082d5b343183fcb8a5f2461cd12 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sat, 3 Jan 2026 09:01:50 +1000 Subject: [PATCH 052/174] update default to plan mode & add Git worktree info --- .claude/settings.local.json | 5 +- README.md | 230 ++++++++++++++++++++++++++++++++++++ 2 files changed, 234 insertions(+), 1 deletion(-) diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 2196464..16a620b 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -8,6 +8,7 @@ }, "includeCoAuthoredBy": false, "permissions": { + "defaultMode": "plan", "allow": [ "Bash(.venv/bin/pip:*)", "Bash(.venv/bin/python:*)", @@ -23,9 +24,11 @@ "Bash(echo:*)", "Bash(env)", "Bash(find:*)", + "Bash(fd:*)", "Bash(gemini:*)", "Bash(grep:*)", "Bash(gtimeout:*)", + "Bash(git log:*)", "Bash(ls:*)", "Bash(mcp:*)", "Bash(mkdir:*)", @@ -63,6 +66,7 @@ "WebFetch(domain:github.com)", "WebFetch(domain:openrouter.ai)", "WebFetch(domain:www.comet.com)", + "WebSearch", "Bash(mkdir:*)", "mcp__chrome-devtools__list_pages", "mcp__chrome-devtools__navigate_page", @@ -80,7 +84,6 @@ "mcp__chrome-devtools__fill", "mcp__chrome-devtools__navigate_page_history", "mcp__chrome-devtools__new_page", - "Bash(git log:*)", "Skill(claude-docs-consultant)" ], "deny": [] diff --git a/README.md b/README.md index 84805c9..d7a1496 100644 --- a/README.md +++ b/README.md @@ -88,6 +88,236 @@ Tokens: $(format_tokens "$TOTAL_TOKENS") (in:$(format_tokens "$INPUT_TOKENS")+ou Cost: \$${COST_USD} | +${LINES_ADDED} -${LINES_REMOVED} lines" ``` +## Git Worktrees for AI Coding Sessions + +Git worktrees allow you to run parallel Claude Code and Codex CLI sessions with complete code isolation. Each worktree has its own isolated working directory while sharing the same Git history and remote connections. This prevents AI instances from interfering with each other when working on multiple tasks simultaneously. + +**Benefits:** +- Run multiple AI coding sessions in parallel +- Each worktree has independent file state +- Changes in one worktree won't affect others +- Ideal for experimental features or YOLO mode usage + +**Official Documentation:** [Run parallel Claude Code sessions with git worktrees](https://code.claude.com/docs/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) + +### macOS / Linux (Bash/Zsh) + +Add these functions to `~/.bashrc`, `~/.zshrc`, or `~/.bash_aliases`: + +```bash +# Codex CLI worktree launcher +cx() { + local branch_name + if [ -z "$1" ]; then + branch_name="worktree-$(date +%Y%m%d-%H%M%S)" + else + branch_name="$1" + fi + git worktree add "../$branch_name" -b "$branch_name" && \ + cd "../$branch_name" || return 1 + codex -m gpt-5-codex --config model_reasoning_effort='xhigh' +} + +# Claude Code worktree launcher +clx() { + local branch_name + if [ -z "$1" ]; then + branch_name="worktree-$(date +%Y%m%d-%H%M%S)" + else + branch_name="$1" + fi + git worktree add "../$branch_name" -b "$branch_name" && \ + cd "../$branch_name" || return 1 + claude --model opusplan --permission-mode plan +} +``` + +After adding, reload your shell: `source ~/.bashrc` or `source ~/.zshrc` + +### Windows (PowerShell) + +Add these functions to your PowerShell profile. Open it with `notepad $PROFILE`: + +```powershell +# Codex CLI worktree launcher +function cx { + param([string]$BranchName) + if (-not $BranchName) { + $BranchName = "worktree-$(Get-Date -Format 'yyyyMMdd-HHmmss')" + } + git worktree add "../$BranchName" -b $BranchName + if ($LASTEXITCODE -eq 0) { + Set-Location "../$BranchName" + codex -m gpt-5-codex --config model_reasoning_effort='xhigh' + } +} + +# Claude Code worktree launcher +function clx { + param([string]$BranchName) + if (-not $BranchName) { + $BranchName = "worktree-$(Get-Date -Format 'yyyyMMdd-HHmmss')" + } + git worktree add "../$BranchName" -b $BranchName + if ($LASTEXITCODE -eq 0) { + Set-Location "../$BranchName" + claude --model opusplan --permission-mode plan + } +} +``` + +After adding, reload PowerShell or run: `. $PROFILE` + +### Windows (CMD Batch Files) + +Create these batch files in a directory in your PATH (e.g., `C:\Users\YourName\bin\`): + +**cx.bat** - Codex CLI launcher: + +```batch +@echo off +setlocal enabledelayedexpansion +if "%~1"=="" ( + for /f "tokens=2 delims==" %%I in ('wmic os get localdatetime /value') do set datetime=%%I + set branch_name=worktree-!datetime:~0,8!-!datetime:~8,6! +) else ( + set branch_name=%~1 +) +git worktree add "../%branch_name%" -b "%branch_name%" +if %errorlevel% equ 0 ( + cd "../%branch_name%" + codex -m gpt-5-codex --config model_reasoning_effort='xhigh' +) +endlocal +``` + +**clx.bat** - Claude Code launcher: + +```batch +@echo off +setlocal enabledelayedexpansion +if "%~1"=="" ( + for /f "tokens=2 delims==" %%I in ('wmic os get localdatetime /value') do set datetime=%%I + set branch_name=worktree-!datetime:~0,8!-!datetime:~8,6! +) else ( + set branch_name=%~1 +) +git worktree add "../%branch_name%" -b "%branch_name%" +if %errorlevel% equ 0 ( + cd "../%branch_name%" + claude --model opusplan --permission-mode plan +) +endlocal +``` + +### Usage + +```bash +# Create worktree with custom name +clx feature-auth +cx bugfix-123 + +# Create worktree with auto-generated timestamp name +clx +cx +``` + +### Worktree Management + +```bash +# List all worktrees +git worktree list + +# Remove a worktree when done +git worktree remove ../worktree-name + +# Clean up stale worktree references +git worktree prune +``` + +### Environment Setup + +Each new worktree needs its own development environment: +- **JavaScript/Node.js**: Run `npm install` or `yarn` +- **Python**: Create virtual environment or run `pip install -r requirements.txt` +- **Other languages**: Follow your project's standard setup process + +### The `.worktreeinclude` File + +When Claude Code creates a worktree, files ignored via `.gitignore` aren't automatically available. The `.worktreeinclude` file specifies which ignored files should be copied to new worktrees. + +**How It Works:** +- Uses `.gitignore`-style patterns +- Only files matched by **both** `.worktreeinclude` **AND** `.gitignore` are copied +- This prevents accidentally duplicating tracked files + +Create a `.worktreeinclude` file in your repository root: + +```text +# Environment files +.env +.env.local +.env.* + +# Claude Code local settings +**/.claude/settings.local.json +``` + +**Common Use Cases:** +- `.env` files with API keys and secrets +- `.env.local` for local development overrides +- `.claude/settings.local.json` for personal Claude Code settings + +### Claude Desktop Worktree Location + +When using Claude Code via the Claude Desktop app: +- Default worktree location: `~/.claude-worktrees` +- Configurable through Claude Desktop app settings +- Repository must be Git initialized for worktree sessions to work + +**Official Documentation:** [Claude Code on Desktop](https://code.claude.com/docs/en/desktop#claude-code-on-desktop-preview) + +### Local Ignores Without `.gitignore` + +To ignore files locally without modifying the shared `.gitignore`, use `.git/info/exclude`: + +```bash +# Edit the local exclude file +nano .git/info/exclude +# or +code .git/info/exclude +``` + +Add patterns using the same syntax as `.gitignore`: + +```text +# Local IDE settings +.idea/ +*.swp + +# Personal scripts +my-local-scripts/ + +# Local test files +test-local.sh +``` + +**Key Differences:** + +| File | Scope | Committed to Git | +|------|-------|------------------| +| `.gitignore` | Shared with team | Yes | +| `.git/info/exclude` | Local only | No | +| `~/.config/git/ignore` | Global (all repos) | No | + +**When to Use `.git/info/exclude`:** +- Personal IDE or editor files +- Local testing scripts +- Machine-specific configurations +- Files you don't want to clutter the shared `.gitignore` + +**Note:** Files in `.git/info/exclude` work with `.worktreeinclude` the same way as `.gitignore` - patterns must appear in both files for copying to worktrees. + ## Claude Code Skills Claude Code now supports [Agent Skills](https://docs.claude.com/en/docs/claude-code/skills). From 7966ef125d84f62aa9e08607cfffad8046ceefbe Mon Sep 17 00:00:00 2001 From: George Liu Date: Sun, 4 Jan 2026 09:01:09 +1000 Subject: [PATCH 053/174] update readme with CLAUDE.md memory bank update example --- README.md | 47 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d7a1496..32b6b9f 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ # My Claude Code Project's Starter Settings -My Claude Code project's starter settings and Claude Code hooks and slash commands are provided in this repository for users to try out. Be sure to read the official Claude Code docs first at https://docs.anthropic.com/en/docs/claude-code/overview and sign up for a [paid Claude AI account](https://claude.ai/) to use Claude Code. You can pay for Claude Pro $20/month, Claude Max $100/month or Claude Max $200/month. The paid Claude tier plans will include varying quotas for usage and rate limits outlined [here](https://support.anthropic.com/en/articles/9797557-usage-limit-best-practices). +My Claude Code project's starter settings and Claude Code hooks and slash commands are provided in this repository for users to try out. The [CLAUDE.md](https://github.com/centminmod/claude-code-memory-bank/blob/main/CLAUDE.md) is setup as set of memory bank files to better retain context over many chat sessions. Be sure to read the official Claude Code docs first at and sign up for a [paid Claude AI account](https://claude.ai/) to use Claude Code. You can pay for Claude Pro $20/month, Claude Max $100/month or Claude Max $200/month. The paid Claude tier plans will include varying quotas for usage and rate limits outlined [here](https://support.anthropic.com/en/articles/9797557-usage-limit-best-practices). 1. Copy the files in this Github repo to your project directory (where you intended codebase will be). 2. Modify the template files and CLAUDE.md`to your liking. `.claude/settings.json` needs to install Terminal-Notifier for macOS https://github.com/centminmod/terminal-notifier-setup. If you're not using macOS, you can remove `.claude/settings.json`. @@ -17,6 +17,51 @@ My Claude Code project's starter settings and Claude Code hooks and slash comman 8. Claude Code via Claude Desktop apps use Git Worktrees. You may need to create a `.worktreeinclude` file as outlined [here](https://code.claude.com/docs/en/desktop#claude-code-on-desktop-preview). 9. If you use Cloudflare and ClerkOS platforms in your apps, you can keep either `CLAUDE-cloudflare.md` or `CLAUDE-cloudflare-mini.md` supplementary reference docs and update `CLAUDE.md` referencing either file to help AI understand Cloudflare and ClerkOS platforum documentation and products. Edit documentation templates as needed i.e. if you do not use ClerkOS platform, you can remove those sections. +## CLAUDE.md Memory Bank system + +[CLAUDE.md](https://github.com/centminmod/claude-code-memory-bank/blob/main/CLAUDE.md) uses a memory bank system of files for Claude Code to better retain context over many chat sessions. Example of Claude Code thinking output when I ask it to `update memory bank` after a successful task completion and git commit: + +``` +> update memory bank + +∴ Thinking… + + The user wants me to update the memory bank files. I should update the relevant CLAUDE-*.md files to reflect the v0.1.6 changes and current state. Let me check + which memory bank files exist and update them. + +∴ Thinking… + + I need to continue updating the memory bank files. I'll update: + 1. CLAUDE-patterns.md - Add export path handling pattern (Pattern 22) + 2. CLAUDE-decisions.md - Add ADR-017 for Phoneme API migration and ADR-018 for export path handling + 3. CLAUDE-troubleshooting.md - Add new issues and solutions for v0.1.6 + +∴ Thinking… + + The memory bank files have been modified but not committed. The v0.1.6 release was already committed and tagged, but the memory bank documentation updates are + still uncommitted. Let me provide a summary of the completed work and offer to commit these documentation changes. + +⏺ Summary: v0.1.6 Release Complete ✅ + + Memory Bank Updates Complete: + - CLAUDE-activeContext.md - v0.1.6 session context + - CLAUDE-patterns.md - Added patterns 22-24 (Export Path, Format Detection, API Migration) + - CLAUDE-decisions.md - Added ADR-017 & ADR-018 + - CLAUDE-troubleshooting.md - Added 4 new issue/fix entries + + v0.1.6 Fixes Applied: + 1. Export to absolute paths (e.g., --export /tmp/test.wav) + 2. Format detection from filename extension (prevents .mp3.wav) + 3. Phoneme API migrated to /dev/phonemize + 4. Test scripts updated for --export "" syntax + + Test Results: All 29 tests passing + + The memory bank documentation updates are ready to commit. Would you like me to commit them +``` + +## MCP Servers + I also install the following MCP servers ([install commands](#claude-code-mcp-servers)): * [Gemini CLI MCP](https://github.com/centminmod/gemini-cli-mcp-server) From 5c6e11bb7639bf0dc53608d7f15f5ba7113a1c22 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sun, 4 Jan 2026 09:02:13 +1000 Subject: [PATCH 054/174] fix links --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 32b6b9f..2e0c753 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ # My Claude Code Project's Starter Settings -My Claude Code project's starter settings and Claude Code hooks and slash commands are provided in this repository for users to try out. The [CLAUDE.md](https://github.com/centminmod/claude-code-memory-bank/blob/main/CLAUDE.md) is setup as set of memory bank files to better retain context over many chat sessions. Be sure to read the official Claude Code docs first at and sign up for a [paid Claude AI account](https://claude.ai/) to use Claude Code. You can pay for Claude Pro $20/month, Claude Max $100/month or Claude Max $200/month. The paid Claude tier plans will include varying quotas for usage and rate limits outlined [here](https://support.anthropic.com/en/articles/9797557-usage-limit-best-practices). +My Claude Code project's starter settings and Claude Code hooks and slash commands are provided in this repository for users to try out. The [CLAUDE.md](https://github.com/centminmod/my-claude-code-setup/blob/master/CLAUDE.md) is setup as set of memory bank files to better retain context over many chat sessions. Be sure to read the official Claude Code docs first at and sign up for a [paid Claude AI account](https://claude.ai/) to use Claude Code. You can pay for Claude Pro $20/month, Claude Max $100/month or Claude Max $200/month. The paid Claude tier plans will include varying quotas for usage and rate limits outlined [here](https://support.anthropic.com/en/articles/9797557-usage-limit-best-practices). 1. Copy the files in this Github repo to your project directory (where you intended codebase will be). 2. Modify the template files and CLAUDE.md`to your liking. `.claude/settings.json` needs to install Terminal-Notifier for macOS https://github.com/centminmod/terminal-notifier-setup. If you're not using macOS, you can remove `.claude/settings.json`. @@ -19,7 +19,7 @@ My Claude Code project's starter settings and Claude Code hooks and slash comman ## CLAUDE.md Memory Bank system -[CLAUDE.md](https://github.com/centminmod/claude-code-memory-bank/blob/main/CLAUDE.md) uses a memory bank system of files for Claude Code to better retain context over many chat sessions. Example of Claude Code thinking output when I ask it to `update memory bank` after a successful task completion and git commit: +[CLAUDE.md](https://github.com/centminmod/my-claude-code-setup/blob/master/CLAUDE.md) uses a memory bank system of files for Claude Code to better retain context over many chat sessions. Example of Claude Code thinking output when I ask it to `update memory bank` after a successful task completion and git commit: ``` > update memory bank From 200e8d2f35cd086c321a2291f21b31c9f894749f Mon Sep 17 00:00:00 2001 From: George Liu Date: Sun, 4 Jan 2026 11:24:06 +1000 Subject: [PATCH 055/174] update readme --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 2e0c753..b01d26c 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,7 @@ My Claude Code project's starter settings and Claude Code hooks and slash comman 7. Optional step to setup Claude Code, Codex GPT-5, Gemini CLI, OpenCode, Vercel CLI, Cloudflare Wrangler, Amazon AWS CLI, all in a single isolated [Visual Studio Code dev container running Debian 12](https://claude-devcontainers.centminmod.com/). Allowing you to run YOLO modes for Claude Code with `dangerously_skip_permissions` enabled and Codex CLI with `sandbox_mode = danger-full-access` etc. 8. Claude Code via Claude Desktop apps use Git Worktrees. You may need to create a `.worktreeinclude` file as outlined [here](https://code.claude.com/docs/en/desktop#claude-code-on-desktop-preview). 9. If you use Cloudflare and ClerkOS platforms in your apps, you can keep either `CLAUDE-cloudflare.md` or `CLAUDE-cloudflare-mini.md` supplementary reference docs and update `CLAUDE.md` referencing either file to help AI understand Cloudflare and ClerkOS platforum documentation and products. Edit documentation templates as needed i.e. if you do not use ClerkOS platform, you can remove those sections. +10. Useful read [Advent of Claude: 31 Days of Claude Code by Ado Kukic from Anthropic](https://adocomplete.com/advent-of-claude-2025/). ## CLAUDE.md Memory Bank system From 0ce59971218d35e51d67c80c803f6bbe1ee487fd Mon Sep 17 00:00:00 2001 From: George Liu Date: Mon, 5 Jan 2026 00:38:59 +1000 Subject: [PATCH 056/174] update CLAUDE.md --- CLAUDE.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 514df4d..aefea6f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,16 +6,31 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co * Ignore GEMINI.md and GEMINI-*.md files * To save main context space, for code searches, inspections, troubleshooting or analysis, use code-searcher subagent where appropriate - giving the subagent full context background for the task(s) you assign it. +* ALWAYS read and understand relevant files before proposing code edits. Do not speculate about code you have not inspected. If the user references a specific file/path, you MUST open and inspect it before explaining or proposing fixes. Be rigorous and persistent in searching code for key facts. Thoroughly review the style, conventions, and abstractions of the codebase before implementing new features or abstractions. * After receiving tool results, carefully reflect on their quality and determine optimal next steps before proceeding. Use your thinking to plan and iterate based on this new information, and then take the best next action. +* After completing a task that involves tool use, provide a quick summary of what you've done. * For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially. * Before you finish, please verify your solution * Do what has been asked; nothing more, nothing less. * NEVER create files unless they're absolutely necessary for achieving your goal. * ALWAYS prefer editing an existing file to creating a new one. * NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User. +* If you create any temporary new files, scripts, or helper files for iteration, clean up these files by removing them at the end of the task. * When you update or modify core context files, also update markdown documentation and memory bank * When asked to commit changes, exclude CLAUDE.md and CLAUDE-*.md referenced memory bank system files from any commits. Never delete these files. + +Never speculate about code you have not opened. If the user references a specific file, you MUST read the file before answering. Make sure to investigate and read relevant files BEFORE answering questions about the codebase. Never make any claims about code before investigating unless you are certain of the correct answer - give grounded and hallucination-free answers. + + + +Do not jump into implementatation or changes files unless clearly instructed to make changes. When the user's intent is ambiguous, default to providing information, doing research, and providing recommendations rather than taking action. Only proceed with edits, modifications, or implementations when the user explicitly requests them. + + + +If you intend to call multiple tools and there are no dependencies between the tool calls, make all of the independent tool calls in parallel. Prioritize calling tools simultaneously whenever the actions can be done in parallel rather than sequentially. For example, when reading 3 files, run 3 tool calls in parallel to read all 3 files into context at the same time. Maximize use of parallel tool calls where possible to increase speed and efficiency. However, if some tool calls depend on previous calls to inform dependent values like the parameters, do NOT call these tools in parallel and instead call them sequentially. Never use placeholders or guess missing parameters in tool calls. + + ## Memory Bank System This project uses a structured memory bank system with specialized context files. Always check these files for relevant information before starting work: From 92e073a91555ef2a268a0895f37fd9b58c6a0eed Mon Sep 17 00:00:00 2001 From: George Liu Date: Mon, 5 Jan 2026 17:23:17 +1000 Subject: [PATCH 057/174] add CLAUDE-convex.md Convex database documentation reference --- CLAUDE-convex.md | 1532 ++++++++++++++++++++++++++++++++++++++++++++++ README.md | 3 +- 2 files changed, 1534 insertions(+), 1 deletion(-) create mode 100644 CLAUDE-convex.md diff --git a/CLAUDE-convex.md b/CLAUDE-convex.md new file mode 100644 index 0000000..1f93f55 --- /dev/null +++ b/CLAUDE-convex.md @@ -0,0 +1,1532 @@ +# CLAUDE.md - Convex Database Project Template + +## Project Overview +- **Project Name**: [PROJECT_NAME] +- **Description**: [BRIEF_DESCRIPTION] +- **Database**: Convex +- **Hosting**: Cloudflare Pages +- **Auth Provider**: Clerk (recommended) / Convex Auth / Custom + +--- + +## CRITICAL: Documentation Verification Rules + +### Before Writing ANY Code +1. **Determine project language/framework** by inspecting project files +2. **Lookup current documentation** for the detected stack before implementing +3. **Never assume** API signatures, function syntax, or hook patterns + +### MCP Tools (if available) +- **context7 MCP**: Query for latest Convex documentation +- **Cloudflare MCP**: Search Cloudflare Pages deployment docs + +### Documentation URLs (for web fetch if no MCP) +Fetch and read these URLs to verify current APIs: + +**Convex Platform:** +| Service | URL | +|---------|-----| +| LLM-Optimized Docs | https://docs.convex.dev/llms.txt | +| Quickstart (Next.js App Router) | https://docs.convex.dev/quickstart/nextjs | +| Quickstart (Next.js Pages Router) | https://docs.convex.dev/client/nextjs/pages-router/quickstart | +| Quickstart (React/Vite) | https://docs.convex.dev/quickstart/react | +| Database Schemas | https://docs.convex.dev/database/schemas | +| Reading Data (Queries) | https://docs.convex.dev/database/reading-data | +| Writing Data (Mutations) | https://docs.convex.dev/database/writing-data | +| Functions Overview | https://docs.convex.dev/functions | +| Query Functions | https://docs.convex.dev/functions/query-functions | +| Mutation Functions | https://docs.convex.dev/functions/mutation-functions | +| Actions | https://docs.convex.dev/functions/actions | +| HTTP Actions | https://docs.convex.dev/functions/http-actions | +| Scheduled Functions | https://docs.convex.dev/scheduling/scheduled-functions | +| Authentication Overview | https://docs.convex.dev/auth | +| Clerk Integration | https://docs.convex.dev/auth/clerk | +| Convex Auth | https://docs.convex.dev/auth/convex-auth | +| Custom Auth | https://docs.convex.dev/auth/custom-auth | +| Authorization Patterns | https://docs.convex.dev/auth/authorization | +| Database Indexes | https://docs.convex.dev/database/indexes | +| Pagination | https://docs.convex.dev/database/pagination | +| File Storage | https://docs.convex.dev/file-storage | +| Full-text Search | https://docs.convex.dev/text-search | +| Vector Search | https://docs.convex.dev/vector-search | +| TypeScript | https://docs.convex.dev/typescript | +| Error Handling | https://docs.convex.dev/functions/error-handling | +| Testing | https://docs.convex.dev/production/testing | +| Environment Variables | https://docs.convex.dev/production/environment-variables | +| Production Hosting | https://docs.convex.dev/production/hosting | +| Monitoring | https://docs.convex.dev/production/monitoring | +| Convex CLI | https://docs.convex.dev/cli | + +**Clerk Authentication:** +| Resource | URL | +|----------|-----| +| Clerk + Convex | https://docs.convex.dev/auth/clerk | +| Clerk Backend SDK | https://clerk.com/docs/reference/backend/overview | +| Clerk Next.js | https://clerk.com/docs/reference/nextjs/overview | +| Clerk React | https://clerk.com/docs/reference/react/overview | + +**Cloudflare Pages Deployment:** +| Resource | URL | +|----------|-----| +| Pages Overview | https://developers.cloudflare.com/pages/ | +| Next.js on Pages | https://developers.cloudflare.com/pages/framework-guides/nextjs/ | +| Build Configuration | https://developers.cloudflare.com/pages/configuration/build-configuration/ | +| Pages Functions | https://developers.cloudflare.com/pages/functions/ | + +--- + +## Project Detection & Setup + +### Step 1: Detect Existing Project Type +Inspect project files to determine language/framework: + +``` +File Found -> Stack -> Action +----------------------------------------------------------------- +convex/ directory -> Existing Convex -> Check convex.json, schema.ts +package.json + "convex" -> Convex project -> Verify setup, check framework + - "next" + app/ -> Next.js App Router -> Fetch Next.js App Router + Convex docs + - "next" + pages/ -> Next.js Pages -> Fetch Next.js Pages Router + Convex docs + - "react" (Vite) -> React + Vite -> Fetch React + Convex docs + - No framework -> Add React/Next.js -> User choice + +No convex/ directory -> New project -> Run: npx create convex@latest + OR: npm install convex && npx convex dev +``` + +### Step 2: New Project Setup (if no convex/) + +**Option 1: Create new Next.js project with Convex** +```bash +# VERIFY at: https://docs.convex.dev/quickstart/nextjs +npx create-next-app@latest my-app +cd my-app +npm install convex +npx convex dev +``` + +**Option 2: Add Convex to existing project** +```bash +# VERIFY at: https://docs.convex.dev/quickstart +npm install convex +npx convex dev # Initializes convex/ directory and cloud project +``` + +**Option 3: Use Convex template (interactive)** +```bash +npx create convex@latest # Interactive setup with framework selection +``` + +### Step 3: Install Dependencies (after detection) + +**Core (always needed):** +```bash +npm install convex # Convex client and server SDK +``` + +**Clerk Authentication (recommended):** +```bash +# For Next.js +npm install @clerk/nextjs + +# For React +npm install @clerk/clerk-react +``` + +**Convex Auth (alternative, beta):** +```bash +# Built into Convex, configure via dashboard +# https://docs.convex.dev/auth/convex-auth +``` + +--- + +## Convex Configuration + +### convex.json (Project Configuration) + +**VERIFY at:** https://docs.convex.dev/production/hosting/hosting-and-running + +```json +{ + "functions": "convex/", + "node": { + "externalPackages": ["sharp", "openai"] // Node.js packages for actions + } +} +``` + +**Technical Explanation:** +- `functions`: Directory containing Convex backend functions (queries, mutations, actions) +- `externalPackages`: Node.js packages that can be imported in actions (not queries/mutations) +- Most configuration is managed in Convex dashboard, not this file + +--- + +### Environment Variables + +**.env.local (Local Development):** +```bash +# VERIFY at: https://docs.convex.dev/production/environment-variables + +# Frontend environment variable (accessible in browser) +# MUST start with NEXT_PUBLIC_ for Next.js +NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud + +# For React (Vite): +VITE_CONVEX_URL=https://your-deployment.convex.cloud + +# Backend environment variables are SET VIA CLI, not in .env +# Example: +# npx convex env set STRIPE_SECRET_KEY sk_test_... +# npx convex env set OPENAI_API_KEY sk-... +``` + +**Technical Explanation:** +- **Frontend vars**: Must be prefixed (`NEXT_PUBLIC_` or `VITE_`) - bundled into client code +- **Backend vars**: Set via CLI for security - accessible only in actions via `process.env` +- **Separate deployments**: Dev and prod have separate environment variables +- **Access in code**: + - Frontend: `process.env.NEXT_PUBLIC_CONVEX_URL` (Next.js) or `import.meta.env.VITE_CONVEX_URL` (Vite) + - Backend actions: `process.env.STRIPE_SECRET_KEY` + - Queries/mutations: CANNOT access environment variables (deterministic requirement) + +--- + +### ConvexProvider Setup Patterns + +#### Next.js App Router + +**VERIFY at:** https://docs.convex.dev/quickstart/nextjs + +**app/ConvexClientProvider.tsx:** +```typescript +// ConvexClientProvider MUST be a client component +"use client"; + +import { ConvexProvider, ConvexReactClient } from "convex/react"; +import { ReactNode } from "react"; + +// Initialize Convex client with deployment URL +const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!); + +export function ConvexClientProvider({ children }: { children: ReactNode }) { + return {children}; +} +``` + +**Technical Explanation:** +- **"use client" required**: React Server Components can't use context providers +- **ConvexReactClient**: Manages WebSocket connection for real-time updates +- **Singleton pattern**: Create client once outside component to prevent reconnections + +**app/layout.tsx:** +```typescript +// VERIFY at: https://docs.convex.dev/quickstart/nextjs +import { ConvexClientProvider } from "./ConvexClientProvider"; + +export default function RootLayout({ children }: { children: ReactNode }) { + return ( + + + {children} + + + ); +} +``` + +**Server-Side Rendering (SSR) with App Router:** +```typescript +// VERIFY at: https://docs.convex.dev/client/nextjs/app-router +import { preloadQuery } from "convex/nextjs"; +import { api } from "@/convex/_generated/api"; + +export default async function ServerComponent() { + // Preload query data on server + const preloadedTasks = await preloadQuery(api.tasks.get); + + return ; +} +``` + +--- + +#### Next.js Pages Router + +**VERIFY at:** https://docs.convex.dev/client/nextjs/pages-router/quickstart + +**pages/_app.tsx:** +```typescript +import { ConvexProvider, ConvexReactClient } from "convex/react"; +import type { AppProps } from "next/app"; + +// Initialize Convex client +const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!); + +function MyApp({ Component, pageProps }: AppProps) { + return ( + + + + ); +} + +export default MyApp; +``` + +**Technical Explanation:** +- **_app.tsx pattern**: Wraps all pages with ConvexProvider +- **Client-side only**: Pages Router has limited SSR support for Convex +- **API routes**: Use for server-side Convex operations + +**API Route Example (pages/api/tasks.ts):** +```typescript +// VERIFY at: https://docs.convex.dev/client/nextjs/pages-router/server-rendering +import { ConvexHttpClient } from "convex/browser"; +import { api } from "@/convex/_generated/api"; +import type { NextApiRequest, NextApiResponse } from "next"; + +const client = new ConvexHttpClient(process.env.NEXT_PUBLIC_CONVEX_URL!); + +export default async function handler(req: NextApiRequest, res: NextApiResponse) { + const tasks = await client.query(api.tasks.get); + res.status(200).json({ tasks }); +} +``` + +--- + +#### React (Vite) + +**VERIFY at:** https://docs.convex.dev/quickstart/react + +**src/main.tsx:** +```typescript +import React from "react"; +import ReactDOM from "react-dom/client"; +import { ConvexProvider, ConvexReactClient } from "convex/react"; +import App from "./App"; + +// Initialize Convex client with Vite environment variable +const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL); + +ReactDOM.createRoot(document.getElementById("root")!).render( + + + + + +); +``` + +**Technical Explanation:** +- **import.meta.env**: Vite's environment variable syntax (NOT process.env) +- **VITE_ prefix**: Required for Vite to include variable in build +- **Client-side only**: Pure React apps are client-rendered + +--- + +## Database Operations + +### Schema Definition + +**VERIFY at:** https://docs.convex.dev/database/schemas + +**convex/schema.ts:** +```typescript +import { defineSchema, defineTable } from "convex/server"; +import { v } from "convex/values"; + +// Schema defines both database structure AND TypeScript types +export default defineSchema({ + tasks: defineTable({ + text: v.string(), + isCompleted: v.boolean(), + userId: v.id("users"), // Reference to users table + createdAt: v.number(), // Timestamp (Date.now()) + }) + .index("by_user", ["userId"]) // Index for queries by user + .index("by_user_status", ["userId", "isCompleted"]) // Compound index + .searchIndex("search_text", { // Full-text search + searchField: "text", + }), + + users: defineTable({ + name: v.string(), + email: v.string(), + clerkId: v.optional(v.string()), // Optional field for Clerk integration + }) + .index("by_clerk_id", ["clerkId"]), +}); +``` + +**Technical Explanation:** +- **defineSchema**: Creates schema with type generation +- **defineTable**: Defines table structure with validators +- **Validators**: `v.string()`, `v.number()`, `v.boolean()`, `v.id("tableName")`, `v.optional()`, etc. +- **Indexes**: Required for efficient queries - must use `.withIndex()` in queries +- **Search indexes**: Enable full-text search with `searchFilter()` +- **Type safety**: Schema automatically generates TypeScript types in `convex/_generated/` + +--- + +### Queries (Reading Data) + +**VERIFY at:** https://docs.convex.dev/database/reading-data + +**convex/tasks.ts:** +```typescript +import { query } from "./_generated/server"; +import { v } from "convex/values"; + +// Get all tasks for a user +export const get = query({ + args: { userId: v.id("users") }, + handler: async (ctx, args) => { + // Queries MUST use indexes for filtering + const tasks = await ctx.db + .query("tasks") + .withIndex("by_user", (q) => q.eq("userId", args.userId)) + .collect(); // Returns all matching documents + + return tasks; + }, +}); + +// Get single task by ID +export const getById = query({ + args: { id: v.id("tasks") }, + handler: async (ctx, args) => { + return await ctx.db.get(args.id); // Returns task or null + }, +}); + +// Paginated query +export const getPaginated = query({ + args: { userId: v.id("users"), paginationOpts: v.object({ }) }, + handler: async (ctx, args) => { + return await ctx.db + .query("tasks") + .withIndex("by_user", (q) => q.eq("userId", args.userId)) + .paginate(args.paginationOpts); // Returns { page, continueCursor, isDone } + }, +}); +``` + +**Query Methods:** +- `.collect()` - Returns all matching documents as array +- `.take(n)` - Returns first n documents +- `.first()` - Returns first document or null +- `.unique()` - Returns single document or throws if multiple/zero +- `.paginate(opts)` - Returns paginated results with cursor + +**Technical Explanation:** +- **Deterministic requirement**: Queries MUST return same result for same inputs +- **❌ Cannot use**: `Math.random()`, `Date.now()`, external API calls +- **Automatic caching**: Convex caches query results for performance +- **Real-time reactivity**: `useQuery()` hook automatically re-runs when data changes +- **withIndex() required**: Must explicitly use indexes - Convex doesn't auto-select + +--- + +### Mutations (Writing Data) + +**VERIFY at:** https://docs.convex.dev/database/writing-data + +**convex/tasks.ts:** +```typescript +import { mutation } from "./_generated/server"; +import { v } from "convex/values"; + +// Insert new task +export const create = mutation({ + args: { + text: v.string(), + userId: v.id("users"), + }, + handler: async (ctx, args) => { + // db.insert() returns the new document's ID + const taskId = await ctx.db.insert("tasks", { + text: args.text, + userId: args.userId, + isCompleted: false, + createdAt: Date.now(), // OK in mutations (not queries) + }); + + return taskId; // Return ID of newly created document + }, +}); + +// Update task (shallow merge) +export const update = mutation({ + args: { + id: v.id("tasks"), + text: v.string(), + }, + handler: async (ctx, args) => { + // db.patch() performs shallow merge - adds/updates fields + await ctx.db.patch(args.id, { + text: args.text, + }); + }, +}); + +// Replace entire document +export const replace = mutation({ + args: { + id: v.id("tasks"), + task: v.object({ + text: v.string(), + isCompleted: v.boolean(), + userId: v.id("users"), + createdAt: v.number(), + }), + }, + handler: async (ctx, args) => { + // db.replace() overwrites entire document + await ctx.db.replace(args.id, args.task); + }, +}); + +// Delete task +export const remove = mutation({ + args: { id: v.id("tasks") }, + handler: async (ctx, args) => { + await ctx.db.delete(args.id); + }, +}); +``` + +**Technical Explanation:** +- **Automatic transactions**: "The entire mutation function is automatically a single transaction" +- **Atomicity**: Multiple db operations in one mutation execute as single atomic unit +- **No BEGIN/COMMIT**: Convex handles transaction management automatically +- **db.patch() vs db.replace()**: + - `patch()`: Shallow merge - adds new fields, updates existing + - `replace()`: Complete overwrite - removes fields not in new object + +--- + +### Actions (External API Calls) + +**VERIFY at:** https://docs.convex.dev/functions/actions + +**convex/actions.ts:** +```typescript +import { action } from "./_generated/server"; +import { v } from "convex/values"; +import { api } from "./_generated/api"; + +// Actions can call external APIs (queries/mutations cannot) +export const sendEmail = action({ + args: { + to: v.string(), + subject: v.string(), + body: v.string(), + }, + handler: async (ctx, args) => { + // Access environment variables (set via: npx convex env set) + const apiKey = process.env.SENDGRID_API_KEY; + + // Call external API (Stripe, OpenAI, etc.) + const response = await fetch("https://api.sendgrid.com/v3/mail/send", { + method: "POST", + headers: { + "Authorization": `Bearer ${apiKey}`, + "Content-Type": "application/json", + }, + body: JSON.stringify({ + personalizations: [{ to: [{ email: args.to }] }], + subject: args.subject, + content: [{ type: "text/plain", value: args.body }], + from: { email: "noreply@example.com" }, + }), + }); + + if (!response.ok) { + throw new Error("Failed to send email"); + } + + // Actions can call mutations to save results to database + await ctx.runMutation(api.emailLogs.create, { + to: args.to, + subject: args.subject, + sentAt: Date.now(), + }); + + return { success: true }; + }, +}); +``` + +**Technical Explanation:** +- **Non-deterministic operations**: Actions can use `Date.now()`, `Math.random()`, external APIs +- **No direct database access**: Actions cannot use `ctx.db` directly +- **Can call queries/mutations**: Use `ctx.runQuery()` and `ctx.runMutation()` +- **Environment variables**: Access via `process.env` (set with `npx convex env set`) +- **Use cases**: Stripe payments, OpenAI calls, sending emails, webhooks + +--- + +## Authentication Integration + +### Clerk Integration (Recommended) + +**VERIFY at:** https://docs.convex.dev/auth/clerk + +**Setup Steps:** + +1. **Install Clerk:** +```bash +npm install @clerk/nextjs # For Next.js +# OR +npm install @clerk/clerk-react # For React +``` + +2. **Configure Clerk in Convex Dashboard:** +- Navigate to Settings → Authentication +- Add Clerk as provider +- Copy Issuer URL from Clerk dashboard + +3. **Add Clerk to Next.js App:** + +**app/layout.tsx:** +```typescript +// VERIFY at: https://docs.convex.dev/auth/clerk +import { ClerkProvider } from "@clerk/nextjs"; +import { ConvexClientProvider } from "./ConvexClientProvider"; + +export default function RootLayout({ children }: { children: ReactNode }) { + return ( + + + + {children} + + + + ); +} +``` + +**app/ConvexClientProvider.tsx:** +```typescript +"use client"; + +import { ClerkProvider, useAuth } from "@clerk/nextjs"; +import { ConvexProviderWithClerk } from "convex/react-clerk"; +import { ConvexReactClient } from "convex/react"; + +const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!); + +export function ConvexClientProvider({ children }: { children: ReactNode }) { + return ( + + {children} + + ); +} +``` + +4. **Access Auth in Convex Functions:** + +**convex/tasks.ts:** +```typescript +import { query, mutation } from "./_generated/server"; +import { v } from "convex/values"; + +// Get authenticated user's tasks +export const getMy = query({ + handler: async (ctx) => { + // Get authenticated user (returns null if not logged in) + const identity = await ctx.auth.getUserIdentity(); + + if (!identity) { + throw new Error("Not authenticated"); + } + + // identity.subject = Clerk user ID + // identity.email, identity.name, etc. + + const tasks = await ctx.db + .query("tasks") + .withIndex("by_user", (q) => + q.eq("userId", identity.subject) + ) + .collect(); + + return tasks; + }, +}); +``` + +**Technical Explanation:** +- **JWT verification**: Convex automatically verifies Clerk JWT tokens +- **ctx.auth.getUserIdentity()**: Returns user info or null if not authenticated +- **identity.subject**: Clerk user ID (use as userId in your database) +- **Authorization in code**: Check auth at function level (no RLS framework) + +--- + +## Framework-Specific Patterns + +### Next.js App Router Hooks + +**VERIFY at:** https://docs.convex.dev/client/nextjs/app-router + +**Client Component (app/TaskList.tsx):** +```typescript +"use client"; + +import { useQuery, useMutation } from "convex/react"; +import { api } from "@/convex/_generated/api"; + +export function TaskList() { + // useQuery: Real-time reactive query + const tasks = useQuery(api.tasks.getMy); + + // useMutation: Returns mutation function + const createTask = useMutation(api.tasks.create); + const updateTask = useMutation(api.tasks.update); + + // tasks is undefined while loading + if (tasks === undefined) { + return
Loading...
; + } + + const handleCreate = async () => { + await createTask({ text: "New task", userId: "user_123" }); + }; + + return ( +
+ {tasks.map((task) => ( +
{task.text}
+ ))} + +
+ ); +} +``` + +**Server Component with preloadQuery:** +```typescript +// VERIFY at: https://docs.convex.dev/client/nextjs/app-router +import { preloadQuery } from "convex/nextjs"; +import { api } from "@/convex/_generated/api"; +import { TaskList } from "./TaskList"; + +export default async function TasksPage() { + // Preload query on server for faster initial load + const preloadedTasks = await preloadQuery(api.tasks.getMy); + + return ; +} +``` + +--- + +## Cloudflare Pages Deployment + +### Deployment Architecture + +**Hybrid Deployment Pattern:** +- **Frontend**: Deployed on Cloudflare Pages (global edge network) +- **Backend**: Hosted on Convex (managed functions + database) +- **Benefits**: Geographic distribution, automatic scaling, zero DevOps + +**VERIFY at:** https://developers.cloudflare.com/pages/framework-guides/nextjs/ + +### Setup Steps + +**1. Create Cloudflare Pages Project:** +- Dashboard → Workers & Pages → Create → Pages → Connect to Git +- Select GitHub repository +- Configure build settings: + - **Framework preset**: Next.js + - **Build command**: `npm run build` + - **Build output directory**: `.next` (Next.js) or `dist` (Vite) + +**2. Set Environment Variables:** +- Pages dashboard → Settings → Environment variables +- Add `NEXT_PUBLIC_CONVEX_URL` with your Convex deployment URL + - Get from: `npx convex dashboard` → Settings → Deployment URL + - Example: `https://happy-animal-123.convex.cloud` + +**3. Deploy:** +- Push to GitHub → Cloudflare automatically builds and deploys +- Preview deployments for all branches +- Production deployment on main branch + +### Environment Variable Management + +**Local (.env.local):** +```bash +NEXT_PUBLIC_CONVEX_URL=https://your-dev-deployment.convex.cloud +``` + +**Production (Cloudflare Pages Dashboard):** +```bash +NEXT_PUBLIC_CONVEX_URL=https://your-prod-deployment.convex.cloud +``` + +**Convex Backend Variables:** +```bash +# Dev environment +npx convex env set STRIPE_SECRET_KEY sk_test_... + +# Production environment +npx convex env set STRIPE_SECRET_KEY sk_live_... --prod +``` + +**Technical Explanation:** +- **Build-time variables**: `NEXT_PUBLIC_*` bundled during build on Cloudflare +- **Runtime variables**: Cloudflare Pages Functions can access runtime environment +- **Separate Convex deployments**: Use different Convex URLs for dev/staging/prod + +--- + +## Development Commands + +**VERIFY at:** https://docs.convex.dev/cli + +### Local Development + +```bash +# Start Convex development server +npx convex dev +# - Starts local dev with hot reload +# - Syncs schema and functions to cloud deployment +# - Watches convex/ directory for changes +# - Provides real-time logs +# - Creates separate dev deployment (not production) + +# Run alongside Next.js dev server +npm run dev # In separate terminal +``` + +### Production Deployment + +```bash +# Deploy Convex backend to production +npx convex deploy --prod +# - Deploys to production environment +# - Runs schema migrations +# - Zero-downtime deployment +# - Returns production deployment URL + +# Deploy to specific environment +npx convex deploy --prod --project my-prod-project +``` + +### Data Operations + +```bash +# Import data from JSONL file +npx convex import --table tasks data/tasks.jsonl +# - JSONL format required (one JSON object per line) +# - Batch imports for efficiency +# - Schema validation on import +# - Example JSONL: +# {"text":"Task 1","isCompleted":false} +# {"text":"Task 2","isCompleted":true} + +# Export database to JSONL +npx convex data export +# - Exports all tables +# - JSONL format for easy re-import +``` + +### Environment Variables + +```bash +# Set environment variable (dev environment) +npx convex env set STRIPE_SECRET_KEY sk_test_... + +# Set environment variable (production) +npx convex env set STRIPE_SECRET_KEY sk_live_... --prod + +# List environment variables +npx convex env list +npx convex env list --prod + +# Remove environment variable +npx convex env unset STRIPE_SECRET_KEY +``` + +**Technical Explanation:** +- Environment variables accessible in **actions only** (via `process.env`) +- Separate dev/prod environments +- Secrets never exposed in client code + +### Monitoring & Debugging + +```bash +# Stream function logs +npx convex logs +# - Real-time logs from all functions +# - Shows query/mutation/action execution +# - Useful for debugging + +# Open Convex dashboard +npx convex dashboard +# - Web-based database explorer +# - View data, run queries, monitor functions +# - Performance metrics +``` + +### Other Commands + +```bash +# Initialize new Convex project +npx convex init + +# Run TypeScript type checking +npx convex typecheck + +# Show current deployment info +npx convex data +``` + +--- + +## TypeScript Patterns + +**VERIFY at:** https://docs.convex.dev/typescript + +### Generated Types + +Convex automatically generates TypeScript types in `convex/_generated/`: + +```typescript +// Auto-generated after running: npx convex dev +import { api } from "@/convex/_generated/api"; +import type { Id } from "@/convex/_generated/dataModel"; + +// Use generated API for type-safe function calls +const tasks = await client.query(api.tasks.get, { userId: "user_123" }); +// ^? Task[] - fully typed based on your schema + +// Use Id<"tableName"> for document IDs +const taskId: Id<"tasks"> = "j57a8c9d0e1f2g3h4i5j6k7l"; +``` + +**Technical Explanation:** +- **convex/_generated/api**: Exports typed function references +- **convex/_generated/dataModel**: Exports `Doc<>`, `Id<>` types based on schema +- **Automatic updates**: Types regenerate when schema or functions change +- **End-to-end type safety**: Client calls are type-checked against server functions + +### Client Hook Typing + +```typescript +import { useQuery, useMutation } from "convex/react"; +import { api } from "@/convex/_generated/api"; + +// useQuery returns T | undefined during loading +const tasks = useQuery(api.tasks.get, { userId: "user_123" }); +// ^? Task[] | undefined + +// useMutation returns typed mutation function +const createTask = useMutation(api.tasks.create); +// ^? (args: { text: string; userId: Id<"users"> }) => Promise> + +// Full IntelliSense support +await createTask({ + text: "New task", + userId: "user_123", // Type error if wrong type +}); +``` + +--- + +## Common Patterns & Best Practices + +### Relationship Modeling + +**VERIFY at:** https://docs.convex.dev/database/document-ids#relationships + +**No JOIN syntax - fetch related documents in parallel:** + +```typescript +import { query } from "./_generated/server"; +import { v } from "convex/values"; + +export const getTasksWithUsers = query({ + handler: async (ctx) => { + // 1. Get all tasks + const tasks = await ctx.db.query("tasks").collect(); + + // 2. Fetch related users in parallel + const usersPromises = tasks.map(task => ctx.db.get(task.userId)); + const users = await Promise.all(usersPromises); + + // 3. Combine results + return tasks.map((task, i) => ({ + ...task, + user: users[i], + })); + }, +}); +``` + +**Technical Explanation:** +- **v.id("tableName")**: Creates typed reference to another table +- **No JOINs**: Fetch related documents separately, combine in JavaScript +- **Denormalization trade-off**: Sometimes duplicate data for performance + +--- + +### Pagination with usePaginatedQuery + +**VERIFY at:** https://docs.convex.dev/database/pagination + +**Client Component:** +```typescript +import { usePaginatedQuery } from "convex/react"; +import { api } from "@/convex/_generated/api"; + +export function InfiniteTaskList() { + const { results, status, loadMore } = usePaginatedQuery( + api.tasks.getPaginated, + { userId: "user_123" }, + { initialNumItems: 20 } + ); + + return ( +
+ {results.map(task =>
{task.text}
)} + + {status === "CanLoadMore" && ( + + )} +
+ ); +} +``` + +**Technical Explanation:** +- **Cursor-based pagination**: More efficient than OFFSET for large datasets +- **usePaginatedQuery**: Manages pagination state automatically +- **CanLoadMore status**: Indicates if more items available + +--- + +### HTTP Actions (Webhooks) + +**VERIFY at:** https://docs.convex.dev/functions/http-actions + +**convex/http.ts:** +```typescript +import { httpRouter } from "convex/server"; +import { httpAction } from "./_generated/server"; +import { api } from "./_generated/api"; + +const http = httpRouter(); + +// Stripe webhook endpoint +http.route({ + path: "/stripe/webhook", + method: "POST", + handler: httpAction(async (ctx, request) => { + const signature = request.headers.get("stripe-signature"); + const body = await request.text(); + + // Verify Stripe signature + // ... stripe verification logic ... + + // Call mutation to update database + await ctx.runMutation(api.payments.processWebhook, { body }); + + return new Response(JSON.stringify({ received: true }), { + status: 200, + headers: { "Content-Type": "application/json" }, + }); + }), +}); + +// Public API endpoint +http.route({ + path: "/api/tasks", + method: "GET", + handler: httpAction(async (ctx, request) => { + const tasks = await ctx.runQuery(api.tasks.getAll); + + return new Response(JSON.stringify(tasks), { + headers: { "Content-Type": "application/json" }, + }); + }), +}); + +export default http; +``` + +**Technical Explanation:** +- **HTTP endpoints**: Accessible at `https://your-deployment.convex.site/stripe/webhook` +- **Use cases**: Stripe webhooks, external API integrations, custom REST endpoints +- **Cannot access ctx.db directly**: Must call queries/mutations with `ctx.run*()` + +--- + +### Scheduled Functions (Cron Jobs) + +**VERIFY at:** https://docs.convex.dev/scheduling/scheduled-functions + +**convex/crons.ts:** +```typescript +import { cronJobs } from "convex/server"; +import { internal } from "./_generated/api"; + +const crons = cronJobs(); + +// Run daily at midnight UTC +crons.daily( + "cleanup expired tasks", + { hourUTC: 0, minuteUTC: 0 }, + internal.tasks.cleanupExpired +); + +// Run every hour +crons.hourly( + "send reminder emails", + { minuteUTC: 0 }, + internal.emails.sendReminders +); + +// Custom cron syntax +crons.cron( + "weekly report", + "0 9 * * 1", // Every Monday at 9 AM UTC + internal.reports.generateWeekly +); + +export default crons; +``` + +**Technical Explanation:** +- **Cron syntax**: Standard cron expressions +- **Internal functions**: Use `internal.*` to prevent public access +- **Use cases**: Daily aggregations, cleanup tasks, periodic syncs + +--- + +### Error Handling + +**VERIFY at:** https://docs.convex.dev/functions/error-handling + +**convex/tasks.ts:** +```typescript +import { ConvexError } from "convex/values"; +import { mutation } from "./_generated/server"; +import { v } from "convex/values"; + +export const create = mutation({ + args: { text: v.string() }, + handler: async (ctx, args) => { + const identity = await ctx.auth.getUserIdentity(); + + if (!identity) { + // ConvexError propagates to client with proper typing + throw new ConvexError("Must be logged in to create tasks"); + } + + if (args.text.length > 500) { + throw new ConvexError({ + message: "Task text too long", + maxLength: 500, + actual: args.text.length, + }); + } + + const taskId = await ctx.db.insert("tasks", { + text: args.text, + userId: identity.subject, + isCompleted: false, + createdAt: Date.now(), + }); + + return taskId; + }, +}); +``` + +**Client Error Handling:** +```typescript +const createTask = useMutation(api.tasks.create); + +try { + await createTask({ text: "Very long task text..." }); +} catch (error) { + if (error instanceof ConvexError) { + // Access error data + console.error(error.data); // { message, maxLength, actual } + } +} +``` + +**Technical Explanation:** +- **ConvexError**: Type-safe error propagation to client +- **Automatic retry**: Transient failures (network issues) automatically retried +- **Error typing**: Client receives properly typed error data + +--- + +### Validation Patterns + +**VERIFY at:** https://docs.convex.dev/database/schemas#validators + +**Custom Validators:** +```typescript +import { v } from "convex/values"; + +// Define custom validator +const emailValidator = v.string().regex(/^[^\s@]+@[^\s@]+\.[^\s@]+$/); + +// Use in mutation +export const createUser = mutation({ + args: { + email: emailValidator, + name: v.string(), + }, + handler: async (ctx, args) => { + // args.email is validated before handler runs + return await ctx.db.insert("users", { + email: args.email, + name: args.name, + }); + }, +}); +``` + +**Technical Explanation:** +- **Runtime validation**: Arguments validated before function executes +- **Schema-level validation**: Enforced on write operations +- **Type safety**: Validators generate TypeScript types + +--- + +### File Storage + +**VERIFY at:** https://docs.convex.dev/file-storage + +**File Upload Action:** +```typescript +import { action } from "./_generated/server"; +import { v } from "convex/values"; + +export const generateUploadUrl = action({ + handler: async (ctx) => { + // Generate signed upload URL (valid for 1 hour) + return await ctx.storage.generateUploadUrl(); + }, +}); + +export const saveFile = action({ + args: { storageId: v.string(), filename: v.string() }, + handler: async (ctx, args) => { + // Save file metadata to database + await ctx.runMutation(api.files.create, { + storageId: args.storageId, + filename: args.filename, + uploadedAt: Date.now(), + }); + }, +}); +``` + +**Client Upload:** +```typescript +const generateUploadUrl = useMutation(api.files.generateUploadUrl); +const saveFile = useMutation(api.files.saveFile); + +const handleUpload = async (file: File) => { + // 1. Get upload URL + const uploadUrl = await generateUploadUrl(); + + // 2. Upload file + const result = await fetch(uploadUrl, { + method: "POST", + headers: { "Content-Type": file.type }, + body: file, + }); + + const { storageId } = await result.json(); + + // 3. Save metadata + await saveFile({ storageId, filename: file.name }); +}; +``` + +--- + +## Gotchas & Best Practices + +### Query Functions Must Be Deterministic + +**VERIFY at:** https://docs.convex.dev/functions/query-functions + +**❌ DON'T DO THIS:** +```typescript +export const getBad = query({ + handler: async (ctx) => { + // ❌ Non-deterministic - breaks caching + const random = Math.random(); + const now = Date.now(); + const external = await fetch("https://api.example.com"); + + return { random, now, external }; + }, +}); +``` + +**✅ DO THIS:** +```typescript +// Queries: Only database reads +export const getGood = query({ + handler: async (ctx) => { + return await ctx.db.query("tasks").collect(); + }, +}); + +// Actions: Non-deterministic operations +export const doNonDeterministic = action({ + handler: async (ctx) => { + const now = Date.now(); // ✅ OK in actions + const external = await fetch("https://api.example.com"); // ✅ OK + + return { now, external }; + }, +}); +``` + +**Why:** +- Queries are cached and must return same result for same inputs +- Enables real-time reactivity and performance optimizations + +--- + +### Index Usage Requirements + +**VERIFY at:** https://docs.convex.dev/database/indexes#querying-indexes + +**❌ This will scan entire table (slow):** +```typescript +// No index usage - scans all documents +const tasks = await ctx.db + .query("tasks") + .filter((q) => q.eq(q.field("userId"), "user_123")) + .collect(); +``` + +**✅ Use indexes explicitly:** +```typescript +// Efficiently uses "by_user" index +const tasks = await ctx.db + .query("tasks") + .withIndex("by_user", (q) => q.eq("userId", "user_123")) + .collect(); +``` + +**Critical:** "You must explicitly use the withIndex() syntax to ensure your database uses the index" + +**Technical Explanation:** +- Convex doesn't auto-select indexes like SQL databases +- Performance impact: Without indexes, queries scan entire table +- Define indexes in schema, use with `.withIndex()` in queries + +--- + +### Local vs Production Environments + +**VERIFY at:** https://docs.convex.dev/production/hosting/hosting-and-running + +**Separate Deployments:** +- `npx convex dev` → Creates/uses **dev deployment** +- `npx convex deploy --prod` → Deploys to **production** + +**Environment Variables:** +```bash +# Dev environment +npx convex env set STRIPE_SECRET_KEY sk_test_... + +# Production environment +npx convex env set STRIPE_SECRET_KEY sk_live_... --prod +``` + +**Frontend URLs:** +```bash +# .env.local (development) +NEXT_PUBLIC_CONVEX_URL=https://dev-deployment.convex.cloud + +# Cloudflare Pages (production) +NEXT_PUBLIC_CONVEX_URL=https://prod-deployment.convex.cloud +``` + +**Best Practice:** +- Always develop against dev deployment +- Only deploy to production after thorough testing + +--- + +## Performance & Monitoring + +**VERIFY at:** https://docs.convex.dev/production/monitoring + +### Convex Dashboard Features + +Access at: `npx convex dashboard` + +**Monitoring Capabilities:** +- **Real-time function logs**: View all query/mutation/action executions +- **Query performance metrics**: Execution time, call frequency +- **Database size and usage**: Track storage and document counts +- **Function execution tracking**: Identify slow functions + +### Performance Best Practices + +**Index Optimization:** +```typescript +// Define indexes for frequently queried fields +export default defineSchema({ + tasks: defineTable({ + userId: v.id("users"), + status: v.string(), + createdAt: v.number(), + }) + .index("by_user", ["userId"]) + .index("by_user_status", ["userId", "status"]) // Compound index + .index("by_created", ["createdAt"]) +}); +``` + +**Pagination for Large Datasets:** +```typescript +// Don't fetch all documents at once +const allTasks = await ctx.db.query("tasks").collect(); // ❌ Slow + +// Use pagination +const tasks = await ctx.db.query("tasks").take(100); // ✅ Faster +``` + +**Batch Operations:** +```typescript +// Fetch related documents in parallel +const tasks = await ctx.db.query("tasks").collect(); +const users = await Promise.all( + tasks.map(task => ctx.db.get(task.userId)) +); +``` + +--- + +## Production Deployment Checklist + +### Pre-Deployment Verification + +``` +Project Setup: +- [ ] Detected project framework (Next.js App Router / Pages Router / React Vite) +- [ ] Fetched and verified current Convex documentation +- [ ] Created convex/ directory with schema.ts +- [ ] Defined all necessary indexes in schema +- [ ] Tested local development with npx convex dev +- [ ] Set up .env.local with NEXT_PUBLIC_CONVEX_URL +- [ ] Verified authentication provider integration (Clerk / Convex Auth / Custom) +``` + +### Cloudflare Pages Configuration + +``` +Pages Setup: +- [ ] Created Cloudflare Pages project +- [ ] Connected GitHub repository +- [ ] Configured build command (npm run build) +- [ ] Configured build output directory (.next / dist) +- [ ] Set environment variable: NEXT_PUBLIC_CONVEX_URL (production URL) +- [ ] Configured custom domain (if applicable) +- [ ] Set up preview deployments for branches +- [ ] Verified build succeeds on Cloudflare +``` + +### Convex Backend Configuration + +``` +Convex Production Deployment: +- [ ] Deployed to production: npx convex deploy --prod +- [ ] Verified production deployment URL +- [ ] Set all production environment variables: + npx convex env set VARIABLE_NAME value --prod +- [ ] Configured authentication provider: + - [ ] Clerk: Added production issuer URL in Convex dashboard + - [ ] Custom: Configured JWT verification +- [ ] Ran schema migrations (automatic on deploy) +- [ ] Tested production database connection +- [ ] Imported any necessary seed data: npx convex import --prod +``` + +### Security Checklist + +``` +Security Verification: +- [ ] All secrets in environment variables (never in code) +- [ ] API keys use production values (not test keys) +- [ ] CORS configured if using HTTP actions +- [ ] Authentication required on all sensitive queries/mutations +- [ ] Authorization checks in function code (ctx.auth.getUserIdentity()) +- [ ] Rate limiting considered for public endpoints +- [ ] Input validation on all mutation arguments +- [ ] No sensitive data in client-side code +``` + +### Testing & Monitoring + +``` +Production Verification: +- [ ] Tested end-to-end user flows in production +- [ ] Verified real-time updates working (WebSocket connection) +- [ ] Checked Convex dashboard for errors +- [ ] Confirmed all queries using proper indexes +- [ ] Tested authentication flow (login/logout/protected routes) +- [ ] Verified file uploads (if using file storage) +- [ ] Tested webhooks (if using HTTP actions) +- [ ] Set up error tracking (Sentry, LogRocket, etc.) +- [ ] Configured monitoring alerts +- [ ] Documented deployment process +``` + +### Environment Alignment + +``` +Environment Consistency: +- [ ] Dev environment uses dev Convex deployment +- [ ] Staging environment uses staging Convex deployment (if applicable) +- [ ] Production environment uses production Convex deployment +- [ ] Each environment has separate environment variables +- [ ] Cloudflare Pages preview deployments use dev Convex URL +- [ ] Production branch triggers production deployment +``` + +--- + +## Notes + + +**Convex vs Traditional Databases:** +- No SQL/ORM - JavaScript/TypeScript functions +- Automatic transactions in mutations +- Real-time reactive queries via WebSockets +- Explicit index usage required +- Managed backend (zero server configuration) + +**When to Use Convex:** +- JAMstack architecture (Cloudflare Pages + Convex backend) +- Real-time collaborative applications +- Type-safe full-stack development +- Rapid prototyping with instant backend +- Projects needing automatic scaling without DevOps + +**Integration Architecture:** +- **Frontend**: Cloudflare Pages (global edge, static assets) +- **Backend**: Convex (managed functions, database, real-time) +- **Benefits**: Geographic distribution, automatic scaling, zero infrastructure management diff --git a/README.md b/README.md index b01d26c..9b7173d 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,8 @@ My Claude Code project's starter settings and Claude Code hooks and slash comman 7. Optional step to setup Claude Code, Codex GPT-5, Gemini CLI, OpenCode, Vercel CLI, Cloudflare Wrangler, Amazon AWS CLI, all in a single isolated [Visual Studio Code dev container running Debian 12](https://claude-devcontainers.centminmod.com/). Allowing you to run YOLO modes for Claude Code with `dangerously_skip_permissions` enabled and Codex CLI with `sandbox_mode = danger-full-access` etc. 8. Claude Code via Claude Desktop apps use Git Worktrees. You may need to create a `.worktreeinclude` file as outlined [here](https://code.claude.com/docs/en/desktop#claude-code-on-desktop-preview). 9. If you use Cloudflare and ClerkOS platforms in your apps, you can keep either `CLAUDE-cloudflare.md` or `CLAUDE-cloudflare-mini.md` supplementary reference docs and update `CLAUDE.md` referencing either file to help AI understand Cloudflare and ClerkOS platforum documentation and products. Edit documentation templates as needed i.e. if you do not use ClerkOS platform, you can remove those sections. -10. Useful read [Advent of Claude: 31 Days of Claude Code by Ado Kukic from Anthropic](https://adocomplete.com/advent-of-claude-2025/). +10. If you use Convex database in your apps, you can use `CLAUDE-convex.md` supplementary reference docs for building Next.js and React apps with Convex backend deployed on Cloudflare Pages. +11. Useful read [Advent of Claude: 31 Days of Claude Code by Ado Kukic from Anthropic](https://adocomplete.com/advent-of-claude-2025/). ## CLAUDE.md Memory Bank system From 87281b0192f58268f0b71e055a94995061d672fd Mon Sep 17 00:00:00 2001 From: George Liu Date: Mon, 5 Jan 2026 18:08:39 +1000 Subject: [PATCH 058/174] Enhance CLAUDE-convex.md: Add 6 critical sections from verification plan MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Verified CLAUDE-convex.md against https://docs.convex.dev/llms.txt and added missing critical sections identified in gap analysis. File expanded from 1,050 to 2,940 lines with comprehensive coverage of production features. ## Sections Added (Priority 1 - Critical) ### 1. Enhanced CLI Section (~100 lines) - CLI Setup: logout, docs, init commands - Running Functions: run --watch, --push, --prod - Type Generation: codegen, typecheck - Enhanced Data Operations: ZIP imports, --include-file-storage - Enhanced Deployment: --preview-create, --cmd options - Enhanced Monitoring: --tail-logs controls ### 2. AI & Agents Section (~400 lines) - Agent Component Overview (capabilities, use cases) - Installation & Setup (@convex-dev/agent, @convex-dev/rag) - Threads and Messages (persistent conversations) - Tool Calls (external function invocation with examples) - RAG Integration (both upfront and tool-based approaches) - Streaming Responses (real-time UI updates) - Rate Limiting & Usage Tracking - Multi-Agent Workflows (researcher + writer example) ### 3. Components Section (~350 lines) - What are Components (vs npm packages comparison) - Installation & Configuration (convex.config.ts, multiple instances) - Using Components (calling functions with transaction rules) - Transaction Behavior (atomic commits, error handling) - Monitoring & Debugging (dashboard, convex-test) - Authoring Custom Components (directory structure, NPM publishing) - Popular Components list (agent, rag, rate-limiter, etc.) ### 4. OCC/Write Conflicts to Gotchas (~115 lines) - Optimistic Concurrency Control explanation - How it works (version checking, automatic retries) - Write Conflict Error (OccRetryThresholdExceeded) - Common Causes with ❌ bad / ✅ fixed examples: * High-frequency updates → Sharded Counter solution * Broad data dependencies → Indexed queries solution - Best Practices table with solutions - Technical guarantees (serializability, determinism) ### 5. Backup & Disaster Recovery to Production (~230 lines) - Manual Backups (dashboard, 7-day retention) - Scheduled Backups (Pro plan, daily/weekly) - Restore Process (destructive warning, cross-deployment) - Backup Download & Import (ZIP structure, CLI commands) - Import from Custom Sources (CSV, JSON, JSONL) - 3 Disaster Recovery Scenarios (deployment, corruption, deletion) - Streaming Export (Fivetran/Airbyte) - Backup Limitations & Post-Restore Checklist ### 6. Production Guarantees & Limits (~190 lines) - Availability & Uptime (99.99% target, no formal SLAs) - Data Protection (encryption, multi-AZ, 11-nines backup durability) - Backward Compatibility Guarantee (Convex 1.0+ stability) - Platform Limits (5 detailed tables): * Function Execution (1s queries, 10min actions, concurrency) * Document & Database (1 MiB docs, 1024 fields, 32 indexes) * Transaction (16 MiB data, 16K docs written, 32K scanned) * Storage & Bandwidth (Free/Starter/Pro tiers) * Search (full-text and vector search limits) - Current Limitations (authorization, observability, OLAP) - Compliance & Enterprise contact info ## Documentation Quality - All sections include **VERIFY at:** links to official docs - Working code examples with technical explanations - Best practices and gotchas clearly marked - Real-world use cases and scenarios - Comparison tables for clarity ## Known Issues - Minor markdown lint warnings (cosmetic only): * Bare URLs (MD034) - links work, just not markdown syntax * Spacing around lists/fences (MD031/MD032) - formatting only * Code block language tags (MD040) - doesn't affect rendering * Table column spacing (MD060) - visual alignment - These do not affect functionality or readability - Can be addressed in future cleanup if needed ## Sources - Components: https://docs.convex.dev/components - AI Agents: https://docs.convex.dev/agents - OCC: https://docs.convex.dev/database/advanced/occ - Backup: https://docs.convex.dev/database/backup-restore - Guarantees: https://docs.convex.dev/production/state/ - Limits: https://docs.convex.dev/production/state/limits - CLI: https://docs.convex.dev/cli Total enhancement: +1,890 lines of production-ready Convex documentation --- CLAUDE-convex.md | 1666 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 1537 insertions(+), 129 deletions(-) diff --git a/CLAUDE-convex.md b/CLAUDE-convex.md index 1f93f55..5b8c378 100644 --- a/CLAUDE-convex.md +++ b/CLAUDE-convex.md @@ -791,6 +791,24 @@ npx convex env set STRIPE_SECRET_KEY sk_live_... --prod **VERIFY at:** https://docs.convex.dev/cli +### CLI Setup & Configuration + +```bash +# Initialize new Convex project +npx convex init +# - Creates convex/ directory structure +# - Generates .env.local with CONVEX_DEPLOYMENT + +# Log out (switch accounts) +npx convex logout +# - Removes stored Convex credentials +# - Allows switching to different account + +# Open documentation +npx convex docs +# - Opens Convex documentation in browser +``` + ### Local Development ```bash @@ -806,6 +824,22 @@ npx convex dev npm run dev # In separate terminal ``` +### Running Functions + +```bash +# Execute query/mutation/action with JSON arguments +npx convex run myFunction '{"arg1": "value"}' + +# Run with watch mode (re-run on function changes) +npx convex run myFunction --watch + +# Push functions before running (ensures latest code) +npx convex run myFunction --push + +# Run against production deployment +npx convex run myFunction --prod +``` + ### Production Deployment ```bash @@ -816,10 +850,46 @@ npx convex deploy --prod # - Zero-downtime deployment # - Returns production deployment URL +# Deploy with build command (e.g., build frontend after backend deployed) +npx convex deploy --cmd "npm run build" +# - Runs command after successful deployment +# - Sets environment variable with deployment URL + +# Deploy with custom environment variable for deployment URL +npx convex deploy --cmd "npm run build" --cmd-url-env-var-name CONVEX_URL +# - Custom env var name instead of default + +# Preview deployments (for CI/CD branches) +npx convex deploy --preview-create +# - Creates isolated preview deployment +# - Useful for PR previews, staging environments + +# Run function after preview deployment +npx convex deploy --preview-create --preview-run setupData +# - Runs setup function after deployment +# - Useful for seeding test data + # Deploy to specific environment npx convex deploy --prod --project my-prod-project ``` +### Type Generation + +```bash +# Generate TypeScript types from schema +npx convex codegen +# - Updates convex/_generated/ directory +# - Generates types from schema and functions +# - Provides end-to-end type safety +# - Automatically run by npx convex dev + +# Type check without generating code +npx convex typecheck +# - Validates TypeScript code +# - Checks for type errors +# - Does not modify files +``` + ### Data Operations ```bash @@ -832,10 +902,36 @@ npx convex import --table tasks data/tasks.jsonl # {"text":"Task 1","isCompleted":false} # {"text":"Task 2","isCompleted":true} +# Import from ZIP archive (multiple tables) +npx convex import data.zip +# - Imports all tables from ZIP +# - ZIP contains JSONL files named after tables +# - Useful for full database migrations + # Export database to JSONL -npx convex data export -# - Exports all tables +npx convex data export --path ./exports +# - Exports all tables to specified directory # - JSONL format for easy re-import +# - Creates separate file per table + +# Export with file storage included +npx convex data export --include-file-storage --path ./exports +# - Includes uploaded files in export +# - Downloads all files from storage +# - Larger export size but complete backup + +# Display table data in terminal +npx convex data +# - Lists all tables + +npx convex data tasks +# - Shows data from specific table + +npx convex data tasks --limit 10 +# - Limits results to 10 rows + +npx convex data tasks --order desc +# - Orders by creation time descending ``` ### Environment Variables @@ -869,6 +965,14 @@ npx convex logs # - Shows query/mutation/action execution # - Useful for debugging +# Control log display during dev +npx convex dev --tail-logs always +# - Always show logs during development + +npx convex dev --tail-logs disable +# - Disable automatic log tailing +# - Use npx convex logs separately + # Open Convex dashboard npx convex dashboard # - Web-based database explorer @@ -1260,201 +1364,1273 @@ const handleUpload = async (file: File) => { --- -## Gotchas & Best Practices +## Components -### Query Functions Must Be Deterministic +**VERIFY at:** https://docs.convex.dev/components -**VERIFY at:** https://docs.convex.dev/functions/query-functions +### What Are Components? + +**Convex Components** are self-contained backend modules that package code, schemas, and persistent data into isolated sandboxes. They are "like mini self-contained Convex backends" that can be safely added to any Convex app. + +**Key Characteristics:** +- **Data Isolation**: Components cannot read your app's tables or call your functions unless explicitly passed in +- **Own Database Tables**: Each component maintains its own isolated database tables +- **Own File Storage**: Separate file storage independent from the main application +- **Transactional Consistency**: All writes commit atomically with the parent mutation +- **Real-time Reactivity**: Component queries are reactive by default +- **Safe Installation**: Installing components is always safe due to strict isolation + +**Why Use Components Instead of npm Packages?** + +| Feature | npm Package | Convex Component | +|---------|-------------|------------------| +| State Persistence | In-memory (lost on restart) | Database-backed (persistent) | +| Data Access | Direct database access | Explicit API boundaries | +| Transactional Guarantees | None (distributed inconsistencies) | Atomic commits across boundaries | +| Isolation | Shared global state | Isolated environments | +| Validation | Manual | Runtime validation at boundaries | + +**Technical Explanation:** +Unlike libraries that require third-party services for stateful functionality, Components store state in the same database as your app, providing transactional guarantees and eliminating distributed protocol complexity. + +--- + +### Installation & Configuration + +**Step 1: Install Component via npm** + +```bash +npm install @convex-dev/component-name +``` + +**Common Components:** +```bash +npm install @convex-dev/agent # AI agents with threads/messages +npm install @convex-dev/rag # RAG (Retrieval-Augmented Generation) +npm install @convex-dev/rate-limiter # Rate limiting +``` + +**Step 2: Configure in convex.config.ts** + +Create or update `convex/convex.config.ts`: -**❌ DON'T DO THIS:** ```typescript -export const getBad = query({ - handler: async (ctx) => { - // ❌ Non-deterministic - breaks caching - const random = Math.random(); - const now = Date.now(); - const external = await fetch("https://api.example.com"); +import { defineApp } from "convex/server"; +import agent from "@convex-dev/agent/convex.config"; +import rateLimit from "@convex-dev/rate-limiter/convex.config"; - return { random, now, external }; - }, -}); +const app = defineApp(); + +// Mount components with names +app.use(agent, { name: "agent" }); +app.use(rateLimit, { name: "rateLimit" }); + +// Multiple instances of same component +app.use(agent, { name: "customerSupport" }); +app.use(agent, { name: "researchAgent" }); + +export default app; ``` -**✅ DO THIS:** +**Technical Explanation:** +- `defineApp()` creates the app configuration +- `use()` mounts components with unique names +- Each component instance has separate tables/functions +- Multiple instances enable isolated use cases (e.g., separate agents) + +**Step 3: Generate Integration Code** + +```bash +npx convex dev +``` + +This generates the `components` object in your API for accessing component functions. + +--- + +### Using Components in Your Code + +**Calling Component Functions** + +Components are accessed through `components` object in generated API: + +**convex/myFunctions.ts:** ```typescript -// Queries: Only database reads -export const getGood = query({ - handler: async (ctx) => { - return await ctx.db.query("tasks").collect(); +import { query, mutation, action } from "./_generated/server"; +import { components } from "./_generated/api"; + +// Query calling component query +export const getThread = query({ + args: { threadId: v.id("threads") }, + handler: async (ctx, args) => { + // Queries can only call component queries + return await ctx.runQuery(components.agent.threads.getThread, { + threadId: args.threadId, + }); }, }); -// Actions: Non-deterministic operations -export const doNonDeterministic = action({ - handler: async (ctx) => { - const now = Date.now(); // ✅ OK in actions - const external = await fetch("https://api.example.com"); // ✅ OK +// Mutation calling component mutation +export const createMessage = mutation({ + args: { threadId: v.id("threads"), content: v.string() }, + handler: async (ctx, args) => { + // Mutations can call component mutations + await ctx.runMutation(components.agent.messages.create, { + threadId: args.threadId, + role: "user", + content: args.content, + }); + }, +}); - return { now, external }; +// Action calling component action +export const processWithAI = action({ + args: { input: v.string() }, + handler: async (ctx, args) => { + // Actions can call component actions + return await ctx.runAction(components.agent.generate, { + prompt: args.input, + }); }, }); ``` -**Why:** -- Queries are cached and must return same result for same inputs -- Enables real-time reactivity and performance optimizations +**Important Rules:** +- Queries can only call component **queries** (maintains reactivity) +- Mutations can call component **mutations** (maintains transactions) +- Actions can call component **actions** +- Component queries are reactive by default --- -### Index Usage Requirements +### Transaction Behavior -**VERIFY at:** https://docs.convex.dev/database/indexes#querying-indexes +**All Writes Commit Together:** -**❌ This will scan entire table (slow):** ```typescript -// No index usage - scans all documents -const tasks = await ctx.db - .query("tasks") - .filter((q) => q.eq(q.field("userId"), "user_123")) - .collect(); +export const createUserWithProfile = mutation({ + args: { userId: v.id("users"), name: v.string() }, + handler: async (ctx, args) => { + // Write 1: App table + await ctx.db.insert("users", { userId: args.userId }); + + // Write 2: Component table + await ctx.runMutation(components.profiles.create, { + userId: args.userId, + name: args.name, + }); + + // Both writes commit atomically + // If parent mutation fails, both rollback + }, +}); ``` -**✅ Use indexes explicitly:** +**Error Handling & Partial Rollback:** + ```typescript -// Efficiently uses "by_user" index -const tasks = await ctx.db - .query("tasks") - .withIndex("by_user", (q) => q.eq("userId", "user_123")) - .collect(); -``` +export const createWithFallback = mutation({ + args: { data: v.object({ name: v.string() }) }, + handler: async (ctx, args) => { + // Write 1: App table + await ctx.db.insert("items", { name: args.data.name }); -**Critical:** "You must explicitly use the withIndex() syntax to ensure your database uses the index" + try { + // Write 2: Component (might fail) + await ctx.runMutation(components.analytics.track, { + event: "item_created", + }); + } catch (error) { + // Component writes rollback, but parent continues + console.error("Analytics failed:", error); + } + + // App write still commits even if component failed + }, +}); +``` **Technical Explanation:** -- Convex doesn't auto-select indexes like SQL databases -- Performance impact: Without indexes, queries scan entire table -- Define indexes in schema, use with `.withIndex()` in queries +- All writes in a mutation commit together by default +- If parent mutation throws, all writes (app + component) rollback +- If component mutation throws but caller catches it, only component writes rollback +- No distributed protocols needed - single database transaction --- -### Local vs Production Environments +### Monitoring & Debugging -**VERIFY at:** https://docs.convex.dev/production/hosting/hosting-and-running +**Dashboard Access:** -**Separate Deployments:** -- `npx convex dev` → Creates/uses **dev deployment** -- `npx convex deploy --prod` → Deploys to **production** +1. Open Convex Dashboard +2. Use dropdown selector to view component tables +3. Filter logs by component: `data.function.component_path` -**Environment Variables:** +**Example Log Filtering:** ```bash -# Dev environment -npx convex env set STRIPE_SECRET_KEY sk_test_... - -# Production environment -npx convex env set STRIPE_SECRET_KEY sk_live_... --prod +# View logs from specific component +npx convex logs --filter 'data.function.component_path == "agent"' ``` -**Frontend URLs:** -```bash -# .env.local (development) -NEXT_PUBLIC_CONVEX_URL=https://dev-deployment.convex.cloud +**Testing with convex-test:** -# Cloudflare Pages (production) -NEXT_PUBLIC_CONVEX_URL=https://prod-deployment.convex.cloud -``` +```typescript +import { convexTest } from "convex-test"; +import { expect, test } from "vitest"; +import schema from "./schema"; +import { components } from "./_generated/api"; + +test("component integration", async () => { + const t = convexTest(schema, { + // Register components for testing + components: { + agent: components.agent, + }, + }); -**Best Practice:** -- Always develop against dev deployment -- Only deploy to production after thorough testing + const threadId = await t.mutation(components.agent.createThread, {}); + expect(threadId).toBeDefined(); +}); +``` --- -## Performance & Monitoring - -**VERIFY at:** https://docs.convex.dev/production/monitoring +### Authoring Custom Components -### Convex Dashboard Features +**Directory Structure:** -Access at: `npx convex dashboard` +``` +my-component/ +├── convex.config.ts # Component configuration +├── schema.ts # Component-specific schema +├── functions.ts # Public API functions +├── _internal/ # Internal functions (not exposed) +└── _generated/ # Auto-generated code +``` -**Monitoring Capabilities:** -- **Real-time function logs**: View all query/mutation/action executions -- **Query performance metrics**: Execution time, call frequency -- **Database size and usage**: Track storage and document counts -- **Function execution tracking**: Identify slow functions +**convex.config.ts:** +```typescript +import { defineComponent } from "convex/server"; -### Performance Best Practices +export default defineComponent("myComponent"); +``` -**Index Optimization:** +**schema.ts:** ```typescript -// Define indexes for frequently queried fields +import { defineSchema, defineTable } from "convex/server"; +import { v } from "convex/values"; + export default defineSchema({ - tasks: defineTable({ - userId: v.id("users"), - status: v.string(), + items: defineTable({ + name: v.string(), createdAt: v.number(), - }) - .index("by_user", ["userId"]) - .index("by_user_status", ["userId", "status"]) // Compound index - .index("by_created", ["createdAt"]) + }), }); ``` -**Pagination for Large Datasets:** +**functions.ts (Public API):** ```typescript -// Don't fetch all documents at once -const allTasks = await ctx.db.query("tasks").collect(); // ❌ Slow +import { query, mutation } from "./_generated/server"; +import { v } from "convex/values"; -// Use pagination -const tasks = await ctx.db.query("tasks").take(100); // ✅ Faster +// Public function (exported = accessible by apps) +export const createItem = mutation({ + args: { name: v.string() }, + handler: async (ctx, args) => { + return await ctx.db.insert("items", { + name: args.name, + createdAt: Date.now(), + }); + }, +}); + +// Public query +export const listItems = query({ + handler: async (ctx) => { + return await ctx.db.query("items").collect(); + }, +}); ``` -**Batch Operations:** +**_internal/helpers.ts (Internal - Not Exposed):** ```typescript -// Fetch related documents in parallel -const tasks = await ctx.db.query("tasks").collect(); -const users = await Promise.all( - tasks.map(task => ctx.db.get(task.userId)) -); +import { internalMutation } from "../_generated/server"; +import { v } from "convex/values"; + +// Internal function (not accessible by apps) +export const cleanup = internalMutation({ + args: {}, + handler: async (ctx) => { + // Internal logic only + }, +}); ``` ---- +**Key Constraints for Component Authors:** -## Production Deployment Checklist +| Constraint | Reason | +|------------|--------| +| No `ctx.auth` | Authentication happens in app, not component | +| All `Id<"table">` become strings at boundary | ID types don't cross boundaries | +| No `process.env` access | Components can't access environment variables | +| Only public functions accessible | Internal functions remain hidden | -### Pre-Deployment Verification +**Publishing to NPM:** -``` -Project Setup: -- [ ] Detected project framework (Next.js App Router / Pages Router / React Vite) -- [ ] Fetched and verified current Convex documentation -- [ ] Created convex/ directory with schema.ts -- [ ] Defined all necessary indexes in schema -- [ ] Tested local development with npx convex dev -- [ ] Set up .env.local with NEXT_PUBLIC_CONVEX_URL -- [ ] Verified authentication provider integration (Clerk / Convex Auth / Custom) -``` +```bash +# 1. Create component from template +npx create-convex@latest --component -### Cloudflare Pages Configuration +# 2. Build with concurrent watchers +npx convex codegen --component-dir ./my-component & +npm run build & +npx convex dev --typecheck-components -``` -Pages Setup: -- [ ] Created Cloudflare Pages project -- [ ] Connected GitHub repository -- [ ] Configured build command (npm run build) -- [ ] Configured build output directory (.next / dist) -- [ ] Set environment variable: NEXT_PUBLIC_CONVEX_URL (production URL) -- [ ] Configured custom domain (if applicable) -- [ ] Set up preview deployments for branches -- [ ] Verified build succeeds on Cloudflare +# 3. Expose NPM entry points +# package.json: +{ + "main": "./dist/index.js", + "exports": { + ".": "./dist/index.js", + "./convex.config.js": "./convex.config.js", + "./_generated/component.js": "./_generated/component.js", + "./test": "./dist/test.js" + } +} + +# 4. Publish +npm publish ``` -### Convex Backend Configuration +--- -``` -Convex Production Deployment: -- [ ] Deployed to production: npx convex deploy --prod -- [ ] Verified production deployment URL +### Popular Components + +**Browse All Components:** https://convex.dev/components + +**Common Use Cases:** +- `@convex-dev/agent` - AI agents with threads, messages, tool calls +- `@convex-dev/rag` - RAG (Retrieval-Augmented Generation) for semantic search +- `@convex-dev/rate-limiter` - API rate limiting and usage tracking +- Authentication components (Clerk, Auth0, etc.) +- Workflow engines +- Leaderboards & rankings +- Feature flags +- Document collaboration + +**Technical Explanation:** +Components enable composability for complex features without building from scratch, while maintaining data isolation and transactional guarantees. + +--- + +## AI & Agents + +**VERIFY at:** https://docs.convex.dev/agents + +### Agent Component Overview + +The **Convex Agent component** is a core building block for constructing AI-powered applications with persistent conversation history, tool calls, and RAG integration. + +**Key Capabilities:** +- Persistent conversation threads with automatic history management +- Real-time updates across all connected clients (reactivity) +- Tool calling for external function invocation +- RAG (Retrieval-Augmented Generation) integration +- Multi-agent workflows +- Streaming text and structured object generation +- Rate limiting and usage tracking + +**Use Cases:** +- AI chatbots with memory +- Multi-agent systems +- Customer support agents +- Research assistants with RAG +- Workflow automation with AI decision-making + +--- + +### Installation & Setup + +```bash +# Install Agent component +npm install @convex-dev/agent + +# Install RAG component (optional, for RAG features) +npm install @convex-dev/rag +``` + +**Technical Explanation:** +- Agent component is a Convex component (reusable pattern) +- Manages threads, messages, and agent interactions +- Integrates seamlessly with Convex actions and queries + +--- + +### Threads and Messages + +**VERIFY at:** https://docs.convex.dev/agents + +**convex/agents.ts:** +```typescript +import { agent } from "@convex-dev/agent"; +import { OpenAI } from "openai"; +import { action } from "./_generated/server"; +import { api } from "./_generated/api"; + +// Create agent with OpenAI +const myAgent = agent({ + model: "gpt-4", + provider: new OpenAI({ apiKey: process.env.OPENAI_API_KEY }), + instructions: "You are a helpful customer support assistant.", +}); + +// Start new conversation thread +export const startThread = action({ + handler: async (ctx) => { + const threadId = await myAgent.createThread(ctx); + return threadId; + }, +}); + +// Send message to agent +export const chat = action({ + args: { threadId: v.id("threads"), message: v.string() }, + handler: async (ctx, args) => { + // Add user message to thread + await myAgent.addMessage(ctx, { + threadId: args.threadId, + role: "user", + content: args.message, + }); + + // Generate agent response + const response = await myAgent.generateText(ctx, { + threadId: args.threadId, + }); + + return response; + }, +}); + +// Get conversation history +export const getMessages = query({ + args: { threadId: v.id("threads") }, + handler: async (ctx, args) => { + return await myAgent.getMessages(ctx, args.threadId); + }, +}); +``` + +**Technical Explanation:** +- **Threads**: Persistent conversation containers +- **Messages**: Individual messages with role (user/assistant/system) +- **Automatic context**: Previous messages automatically included in LLM calls +- **Hybrid search**: Built-in vector/text search over conversation history +- **Multi-user**: Threads can be shared across users and agents + +--- + +### Tool Calls + +**VERIFY at:** https://docs.convex.dev/agents + +Enable agents to call external functions as part of their reasoning process. + +**Example: Agent with Weather Tool** +```typescript +import { agent, tool } from "@convex-dev/agent"; +import { OpenAI } from "openai"; +import { v } from "convex/values"; + +// Define tool +const getWeather = tool({ + name: "get_weather", + description: "Get current weather for a location", + parameters: v.object({ + location: v.string(), + }), + handler: async (ctx, args) => { + // Call external weather API + const response = await fetch( + `https://api.weather.com/current?location=${args.location}` + ); + const data = await response.json(); + return { temperature: data.temp, conditions: data.conditions }; + }, +}); + +// Create agent with tool +const weatherAgent = agent({ + model: "gpt-4", + provider: new OpenAI({ apiKey: process.env.OPENAI_API_KEY }), + instructions: "You help users with weather information.", + tools: [getWeather], +}); + +export const askWeather = action({ + args: { threadId: v.id("threads"), question: v.string() }, + handler: async (ctx, args) => { + await weatherAgent.addMessage(ctx, { + threadId: args.threadId, + role: "user", + content: args.question, + }); + + // LLM will automatically call getWeather tool if needed + const response = await weatherAgent.generateText(ctx, { + threadId: args.threadId, + }); + + return response; + }, +}); +``` + +**Technical Explanation:** +- **Tool definition**: Name, description, parameters, handler function +- **Automatic invocation**: LLM decides when to use tools +- **Multi-turn**: After tool call, LLM can generate final response +- **Tool response history**: Tool calls and responses persisted in thread + +--- + +### RAG Integration + +**VERIFY at:** https://docs.convex.dev/agents/rag + +Integrate Retrieval-Augmented Generation for context-aware responses. + +**Two Approaches:** + +**1. Upfront Context Injection** (search before LLM call) +```typescript +import { rag } from "@convex-dev/rag"; +import { agent } from "@convex-dev/agent"; + +// Create RAG component +const documentRAG = rag({ + embeddingModel: "text-embedding-ada-002", +}); + +export const chatWithDocs = action({ + args: { threadId: v.id("threads"), question: v.string() }, + handler: async (ctx, args) => { + // 1. Search for relevant documents + const relevantDocs = await documentRAG.search(ctx, { + query: args.question, + limit: 5, + }); + + // 2. Inject context into prompt + const context = relevantDocs.map(doc => doc.content).join("\n\n"); + const prompt = `Context:\n${context}\n\nQuestion: ${args.question}`; + + await myAgent.addMessage(ctx, { + threadId: args.threadId, + role: "user", + content: prompt, + }); + + // 3. Generate response with context + return await myAgent.generateText(ctx, { threadId: args.threadId }); + }, +}); +``` + +**2. RAG as Tool Calls** (LLM decides when to search) +```typescript +// Define RAG as a tool +const searchDocuments = tool({ + name: "search_documents", + description: "Search knowledge base for relevant information", + parameters: v.object({ + query: v.string(), + }), + handler: async (ctx, args) => { + const results = await documentRAG.search(ctx, { + query: args.query, + limit: 5, + }); + return results.map(doc => doc.content); + }, +}); + +// Agent with RAG tool +const ragAgent = agent({ + model: "gpt-4", + provider: new OpenAI({ apiKey: process.env.OPENAI_API_KEY }), + instructions: "Search the knowledge base when needed to answer questions.", + tools: [searchDocuments], +}); +``` + +**Technical Explanation:** +- **Upfront approach**: Simpler, always includes context +- **Tool approach**: More flexible, LLM decides when to search +- **Hybrid vector/text search**: Combines semantic and keyword matching +- **Automatic embedding**: RAG component handles vector embeddings + +--- + +### Streaming Responses + +**VERIFY at:** https://docs.convex.dev/agents + +Stream agent responses for real-time UI updates. + +```typescript +export const streamChat = action({ + args: { threadId: v.id("threads"), message: v.string() }, + handler: async (ctx, args) => { + await myAgent.addMessage(ctx, { + threadId: args.threadId, + role: "user", + content: args.message, + }); + + // Stream text generation + const stream = await myAgent.streamText(ctx, { + threadId: args.threadId, + }); + + return stream; // Client receives incremental updates + }, +}); +``` + +**Client Usage:** +```typescript +const streamChat = useAction(api.agents.streamChat); + +const handleSend = async (message: string) => { + const stream = await streamChat({ threadId, message }); + + for await (const chunk of stream) { + // Update UI with each chunk + setResponse(prev => prev + chunk); + } +}; +``` + +**Technical Explanation:** +- **Streaming API**: Returns async iterable +- **Real-time UI**: Update UI incrementally as text generates +- **Better UX**: Users see immediate progress vs waiting for full response + +--- + +### Rate Limiting & Usage Tracking + +**VERIFY at:** https://docs.convex.dev/agents + +Track and limit agent usage per user or team. + +```typescript +import { rateLimit } from "@convex-dev/agent"; + +export const chatWithLimit = action({ + args: { userId: v.id("users"), message: v.string() }, + handler: async (ctx, args) => { + // Check rate limit (e.g., 10 messages per hour) + const allowed = await rateLimit.check(ctx, { + key: `user_${args.userId}`, + limit: 10, + window: 3600, // 1 hour in seconds + }); + + if (!allowed) { + throw new Error("Rate limit exceeded. Try again later."); + } + + // Track usage for billing + await ctx.runMutation(api.usage.trackMessage, { + userId: args.userId, + tokens: 0, // Will be updated after LLM call + }); + + const response = await myAgent.generateText(ctx, { + threadId: args.threadId, + }); + + // Update token usage for billing + await ctx.runMutation(api.usage.updateTokens, { + userId: args.userId, + tokens: response.usage.totalTokens, + }); + + return response; + }, +}); +``` + +**Technical Explanation:** +- **Rate limiting**: Prevent abuse, comply with LLM provider limits +- **Usage tracking**: Bill per user/team based on token consumption +- **Cost control**: Monitor and cap spending per user + +--- + +### Multi-Agent Workflows + +**VERIFY at:** https://docs.convex.dev/agents/workflows + +Coordinate multiple agents for complex tasks. + +```typescript +// Research agent +const researcher = agent({ + model: "gpt-4", + provider: new OpenAI({ apiKey: process.env.OPENAI_API_KEY }), + instructions: "Research topics and provide factual information.", + tools: [searchDocuments], +}); + +// Writing agent +const writer = agent({ + model: "gpt-4", + provider: new OpenAI({ apiKey: process.env.OPENAI_API_KEY }), + instructions: "Write clear, engaging content based on research.", +}); + +export const createArticle = action({ + args: { topic: v.string() }, + handler: async (ctx, args) => { + // Step 1: Research agent gathers information + const researchThread = await researcher.createThread(ctx); + await researcher.addMessage(ctx, { + threadId: researchThread, + role: "user", + content: `Research this topic: ${args.topic}`, + }); + const research = await researcher.generateText(ctx, { + threadId: researchThread, + }); + + // Step 2: Writing agent creates article from research + const writerThread = await writer.createThread(ctx); + await writer.addMessage(ctx, { + threadId: writerThread, + role: "user", + content: `Write an article based on this research:\n${research.text}`, + }); + const article = await writer.generateText(ctx, { + threadId: writerThread, + }); + + return article.text; + }, +}); +``` + +**Technical Explanation:** +- **Agent specialization**: Different agents for different tasks +- **Sequential workflows**: Output of one agent feeds into another +- **Durable execution**: Workflows persist across interruptions +- **Human-in-the-loop**: Can pause for human approval between steps + +--- + +## Gotchas & Best Practices + +### Query Functions Must Be Deterministic + +**VERIFY at:** https://docs.convex.dev/functions/query-functions + +**❌ DON'T DO THIS:** +```typescript +export const getBad = query({ + handler: async (ctx) => { + // ❌ Non-deterministic - breaks caching + const random = Math.random(); + const now = Date.now(); + const external = await fetch("https://api.example.com"); + + return { random, now, external }; + }, +}); +``` + +**✅ DO THIS:** +```typescript +// Queries: Only database reads +export const getGood = query({ + handler: async (ctx) => { + return await ctx.db.query("tasks").collect(); + }, +}); + +// Actions: Non-deterministic operations +export const doNonDeterministic = action({ + handler: async (ctx) => { + const now = Date.now(); // ✅ OK in actions + const external = await fetch("https://api.example.com"); // ✅ OK + + return { now, external }; + }, +}); +``` + +**Why:** +- Queries are cached and must return same result for same inputs +- Enables real-time reactivity and performance optimizations + +--- + +### Index Usage Requirements + +**VERIFY at:** https://docs.convex.dev/database/indexes#querying-indexes + +**❌ This will scan entire table (slow):** +```typescript +// No index usage - scans all documents +const tasks = await ctx.db + .query("tasks") + .filter((q) => q.eq(q.field("userId"), "user_123")) + .collect(); +``` + +**✅ Use indexes explicitly:** +```typescript +// Efficiently uses "by_user" index +const tasks = await ctx.db + .query("tasks") + .withIndex("by_user", (q) => q.eq("userId", "user_123")) + .collect(); +``` + +**Critical:** "You must explicitly use the withIndex() syntax to ensure your database uses the index" + +**Technical Explanation:** +- Convex doesn't auto-select indexes like SQL databases +- Performance impact: Without indexes, queries scan entire table +- Define indexes in schema, use with `.withIndex()` in queries + +--- + +### Local vs Production Environments + +**VERIFY at:** https://docs.convex.dev/production/hosting/hosting-and-running + +**Separate Deployments:** +- `npx convex dev` → Creates/uses **dev deployment** +- `npx convex deploy --prod` → Deploys to **production** + +**Environment Variables:** +```bash +# Dev environment +npx convex env set STRIPE_SECRET_KEY sk_test_... + +# Production environment +npx convex env set STRIPE_SECRET_KEY sk_live_... --prod +``` + +**Frontend URLs:** +```bash +# .env.local (development) +NEXT_PUBLIC_CONVEX_URL=https://dev-deployment.convex.cloud + +# Cloudflare Pages (production) +NEXT_PUBLIC_CONVEX_URL=https://prod-deployment.convex.cloud +``` + +**Best Practice:** +- Always develop against dev deployment +- Only deploy to production after thorough testing + +--- + +### Optimistic Concurrency Control (OCC) & Write Conflicts + +**VERIFY at:** https://docs.convex.dev/database/advanced/occ + +**What is OCC?** + +Convex uses **Optimistic Concurrency Control (OCC)** to provide ACID compliance with true **serializability** (not just snapshot isolation). Instead of locking records, Convex treats each mutation as "a declarative proposal to write records on the basis of any read record versions." + +**How It Works:** + +```typescript +// Transaction A: Reads Alice's account (v1: $14) +const alice = await ctx.db.get(aliceId); // version 1 + +// (Meanwhile, Transaction B modifies Alice's account → now v2) + +// Transaction A attempts to write +await ctx.db.patch(aliceId, { balance: alice.balance - 5 }); +// ❌ FAILS: Alice version changed from v1 to v2 +// Convex automatically retries the entire mutation +``` + +**Technical Explanation:** +- At commit time, Convex checks if all read records are still at their original versions +- If any record changed, the mutation **fails and automatically retries** +- Similar to Git: "Cannot push because HEAD is out of date → rebase and try again" +- Because mutations are **deterministic**, retrying is safe and transparent + +**Write Conflict Error:** + +When retries exceed threshold (high contention), you'll see: + +``` +OccRetryThresholdExceeded: Documents read from or written to the +table 'counters' changed while this mutation was being run and on +every subsequent retry. +``` + +**Common Causes:** + +1. **High-frequency updates to same document:** + +```typescript +// ❌ CONFLICT PRONE: Many concurrent calls updating same counter +export const incrementCounter = mutation({ + args: { counterId: v.id("counters") }, + handler: async (ctx, args) => { + const counter = await ctx.db.get(args.counterId); + await ctx.db.patch(args.counterId, { + count: (counter?.count || 0) + 1 + }); + }, +}); + +// Called 100 times/second → conflicts! +``` + +**✅ FIX: Use Sharded Counter component** +```bash +npm install @convex-dev/sharded-counter +``` + +2. **Broad data dependencies (reading entire tables):** + +```typescript +// ❌ CONFLICT PRONE: Reads ALL tasks +export const addTask = mutation({ + handler: async (ctx, args) => { + // Reading entire table creates conflict with ANY mutation that writes to tasks + const allTasks = await ctx.db.query("tasks").collect(); + const taskCount = allTasks.length; + + await ctx.db.insert("tasks", { ...args, order: taskCount }); + }, +}); +``` + +**✅ FIX: Read only necessary data with indexes** +```typescript +export const addTask = mutation({ + args: { userId: v.id("users"), text: v.string() }, + handler: async (ctx, args) => { + // Only read tasks for this user (using index) + const userTasks = await ctx.db + .query("tasks") + .withIndex("by_user", (q) => q.eq("userId", args.userId)) + .collect(); + + await ctx.db.insert("tasks", { + userId: args.userId, + text: args.text, + order: userTasks.length, + }); + }, +}); +``` + +**Best Practices to Avoid Conflicts:** + +| Issue | Solution | +|-------|----------| +| Hot document (many writes to same record) | Shard data across multiple documents | +| Reading entire tables | Use indexed queries with selective range expressions | +| Unexpected repeated calls | Avoid mutations in loops, debounce client calls | +| Single counter for all users | Use Sharded Counter or per-user counters | + +**Technical Guarantee:** + +Write mutations "as if they will always succeed, and always be guaranteed to be atomic." Convex handles conflicts transparently through automatic retries, providing true serializability without developer intervention. + +**When to Use Components:** +- **Sharded Counter**: Distribute high-frequency writes across multiple documents +- **Workpool**: Prioritize critical tasks through separate queues + +--- + +## Performance & Monitoring + +**VERIFY at:** https://docs.convex.dev/production/monitoring + +### Convex Dashboard Features + +Access at: `npx convex dashboard` + +**Monitoring Capabilities:** +- **Real-time function logs**: View all query/mutation/action executions +- **Query performance metrics**: Execution time, call frequency +- **Database size and usage**: Track storage and document counts +- **Function execution tracking**: Identify slow functions + +### Performance Best Practices + +**Index Optimization:** +```typescript +// Define indexes for frequently queried fields +export default defineSchema({ + tasks: defineTable({ + userId: v.id("users"), + status: v.string(), + createdAt: v.number(), + }) + .index("by_user", ["userId"]) + .index("by_user_status", ["userId", "status"]) // Compound index + .index("by_created", ["createdAt"]) +}); +``` + +**Pagination for Large Datasets:** +```typescript +// Don't fetch all documents at once +const allTasks = await ctx.db.query("tasks").collect(); // ❌ Slow + +// Use pagination +const tasks = await ctx.db.query("tasks").take(100); // ✅ Faster +``` + +**Batch Operations:** +```typescript +// Fetch related documents in parallel +const tasks = await ctx.db.query("tasks").collect(); +const users = await Promise.all( + tasks.map(task => ctx.db.get(task.userId)) +); +``` + +--- + +## Production Guarantees & Limits + +**VERIFY at:** https://docs.convex.dev/production/state/ + +### Availability & Uptime + +**Availability Target:** +- **99.99% availability** (four nines) for all Convex deployments +- Maintenance downtime may occur without prior notice +- Physical outages will not compromise data durability + +**Important Note:** +Convex currently does not offer formal contractual SLAs beyond their standard Terms of Service. For enterprise requirements, contact support@convex.dev. + +**Technical Explanation:** +Database state is replicated durably across multiple physical availability zones to ensure availability even during infrastructure failures. + +--- + +### Data Protection & Security + +**Encryption:** +- **All user data encrypted at rest** in Convex deployments +- Encryption happens automatically, no configuration required + +**Data Replication:** +- Database state replicated across **multiple physical availability zones** +- Protects against data center failures +- No manual failover required + +**Backup Durability:** +- Regular periodic and incremental backups performed automatically +- Backups stored with **99.999999999% durability** (eleven nines) +- Comparable to Amazon S3 Standard storage class + +**Technical Explanation:** +Backup durability of 11 nines means the annual probability of losing a backup is approximately 0.000000001% (1 in 100 billion). Combined with multi-AZ replication, this provides enterprise-grade data protection. + +--- + +### Backward Compatibility Guarantee + +**Commitment:** +- Code written for Convex 1.0+ will continue to work without modification +- Breaking changes will have **substantial advance notice** to affected teams +- Direct communication for any potential breaking changes + +**What This Means:** +You can build production applications on Convex with confidence that future updates won't break your existing code without warning. + +--- + +### Platform Limits + +**VERIFY at:** https://docs.convex.dev/production/state/limits + +#### Function Execution Limits + +| Resource | Limit | Notes | +|----------|-------|-------| +| Query/Mutation execution | 1 second | User code only (excludes framework overhead) | +| Action execution | 10 minutes | Long-running operations | +| Concurrent Node actions (Free/Starter) | 64 | Parallel action executions | +| Concurrent Node actions (Pro) | 1,000 | Professional plan benefit | + +**Technical Explanation:** +- Queries/mutations have 1-second limit because they're transactional (must be fast) +- Actions can run up to 10 minutes for external API calls, file processing, etc. +- Exceeding limits throws error; design functions to complete within timeframes + +#### Document & Database Limits + +| Resource | Limit | Notes | +|----------|-------|-------| +| Document size | 1 MiB | Per document maximum | +| Fields per document | 1,024 | Total field count | +| Object/array nesting depth | 16 levels | Nested structures | +| Array elements | 8,192 | Per array maximum | +| Tables per deployment | 10,000 | Total tables | +| Indexes per table | 32 | Maximum indexes | + +**Common Gotcha:** +If you hit the 1 MiB document limit, split data across multiple related documents using references (e.g., store large JSON in separate "metadata" table). + +#### Transaction Limits + +| Resource | Limit | Notes | +|----------|-------|-------| +| Data read/written per transaction | 16 MiB | Total transaction size | +| Documents written per transaction | 16,000 | Mutation write limit | +| Documents scanned per transaction | 32,000 | Query/filter limit | +| Index range reads | 4,096 | Per transaction | + +**Technical Explanation:** +These limits ensure mutations remain fast and prevent runaway transactions. If you need to process more data, use pagination or batch operations across multiple transactions. + +#### Storage & Bandwidth Limits + +| Plan | Database Storage | File Storage | Database Bandwidth | File Bandwidth | Function Calls | +|------|------------------|--------------|-------------------|----------------|----------------| +| Free | 0.5 GiB | 1 GiB | 1 GiB/month | 1 GiB/month | 1M calls/month | +| Starter | 8 GiB | 10 GiB | 8 GiB/month | 10 GiB/month | 5M calls/month | +| Professional | 50 GiB | 100 GiB | 50 GiB/month | 50 GiB/month | 25M calls/month | + +**Overage Pricing:** +- Database storage: $1.00/GiB/month +- File storage: $0.15/GiB/month +- Additional bandwidth and calls: usage-based pricing + +#### Search Limits + +| Feature | Limit | Notes | +|---------|-------|-------| +| Full-text search indexes | 4 per table | Text search capability | +| Full-text search results | 1,024 maximum | Per query | +| Vector search indexes | 4 per table | Semantic/AI search | +| Vector search results | 256 maximum | Per query | + +**Technical Explanation:** +Search indexes are separate from regular indexes and have their own limits. Design your search features to work within these constraints (e.g., use pagination for large result sets). + +--- + +### Current Limitations (As of 2025) + +**No Built-In Authorization Framework:** +- Only **authentication** exists (identity verification) +- Authorization (permission checks) must be implemented manually in queries/mutations +- Pattern: Check `ctx.auth.getUserIdentity()` and validate permissions in code + +**Example:** +```typescript +export const deleteTask = mutation({ + args: { taskId: v.id("tasks") }, + handler: async (ctx, args) => { + const identity = await ctx.auth.getUserIdentity(); + if (!identity) throw new Error("Unauthorized"); + + const task = await ctx.db.get(args.taskId); + if (!task) throw new Error("Task not found"); + + // ⚠️ Manual authorization check required + if (task.userId !== identity.subject) { + throw new Error("Forbidden: You don't own this task"); + } + + await ctx.db.delete(args.taskId); + }, +}); +``` + +**Limited Observability:** +- Basic dashboard metrics available (function execution time, call frequency) +- Third-party integration for advanced monitoring still in development +- Recommendation: Use Sentry, LogRocket, or custom logging for production + +**Not Optimized for Analytics (OLAP):** +- Convex is designed for real-time transactional operations (OLTP) +- Complex analytical queries (aggregations across large datasets) may hit limits +- Recommendation: Use streaming export to dedicated analytics database (Snowflake, BigQuery) + +--- + +### When Limits May Increase + +The Convex team notes: "Many of these limits will become more permissive over time." + +If you encounter limits for your use case, contact support@convex.dev to discuss: +- Plan-specific limit increases +- Custom enterprise arrangements +- Roadmap for future limit expansions + +--- + +### Compliance & Enterprise + +**Current Status:** +- **Terms of Service:** https://convex.dev/terms +- **Privacy Policy:** https://convex.dev/privacy +- **No formal GDPR/SOC2 certifications mentioned** in developer documentation + +**For Enterprise Requirements:** +Contact support@convex.dev for: +- Compliance documentation +- Security audits +- Custom agreements +- SLA contracts + +--- + +## Production Deployment Checklist + +### Pre-Deployment Verification + +``` +Project Setup: +- [ ] Detected project framework (Next.js App Router / Pages Router / React Vite) +- [ ] Fetched and verified current Convex documentation +- [ ] Created convex/ directory with schema.ts +- [ ] Defined all necessary indexes in schema +- [ ] Tested local development with npx convex dev +- [ ] Set up .env.local with NEXT_PUBLIC_CONVEX_URL +- [ ] Verified authentication provider integration (Clerk / Convex Auth / Custom) +``` + +### Cloudflare Pages Configuration + +``` +Pages Setup: +- [ ] Created Cloudflare Pages project +- [ ] Connected GitHub repository +- [ ] Configured build command (npm run build) +- [ ] Configured build output directory (.next / dist) +- [ ] Set environment variable: NEXT_PUBLIC_CONVEX_URL (production URL) +- [ ] Configured custom domain (if applicable) +- [ ] Set up preview deployments for branches +- [ ] Verified build succeeds on Cloudflare +``` + +### Convex Backend Configuration + +``` +Convex Production Deployment: +- [ ] Deployed to production: npx convex deploy --prod +- [ ] Verified production deployment URL - [ ] Set all production environment variables: npx convex env set VARIABLE_NAME value --prod - [ ] Configured authentication provider: @@ -1507,6 +2683,238 @@ Environment Consistency: - [ ] Production branch triggers production deployment ``` +### Backup & Disaster Recovery + +**VERIFY at:** https://docs.convex.dev/database/backup-restore + +#### Manual Backups (Dashboard) + +**Access:** Convex Dashboard → Backups → "Backup Now" + +**Characteristics:** +- Creates consistent snapshot of all table data +- Processing time: seconds to hours (depending on data size) +- Retention: 7 days +- Storage limit: Free/Starter plans (2 backups max), Pro plans (unlimited, usage-based pricing) +- **Includes:** Table data only +- **Excludes:** Code, environment variables, scheduled functions, configuration + +**File Storage Inclusion:** +```bash +# Dashboard option: "Include file storage" +# Or via CLI export: +npx convex export --path ~/Downloads --include-file-storage +``` + +#### Scheduled Backups (Pro Plan) + +**Configuration:** Convex Dashboard → Backups → "Backup automatically" + +**Options:** +- **Daily backups**: Retained for 7 days, specify time of day +- **Weekly backups**: Retained for 14 days, specify day/time +- **File storage**: Optional inclusion checkbox + +**Technical Explanation:** +Scheduled backups require Convex Pro plan. Each backup is billed for database and file bandwidth (same as user file storage costs). + +#### Restore Process + +**CRITICAL:** Restoration is **destructive** - wipes existing data before restore + +**Best Practice:** +```bash +# Step 1: Create backup BEFORE restoring +# Dashboard → Backup Now + +# Step 2: Restore from backup +# Dashboard → Backups → Select backup → "Restore" + +# Step 3: Redeploy code +npx convex dev # Verify changes locally first +npx convex deploy --prod # Deploy to production + +# Step 4: Restore environment variables +npx convex env set VARIABLE_NAME value --prod +``` + +**Cross-Deployment Restore:** +```bash +# Use case: Populate dev deployment with prod data +# Dashboard → Backups → Select backup → "Restore" → Choose target deployment +``` + +**File Storage Behavior:** +- Existing files in deployment are **NOT deleted** +- Files from backup that don't exist in deployment are uploaded +- Result: Merge of existing files + backup files + +#### Backup Download & Import + +**Download Backup (ZIP):** + +Dashboard: Backups → Select backup → Download → `snapshot_{timestamp}.zip` + +**ZIP Structure:** +``` +snapshot_1234567890.zip +├── users/ +│ └── documents.jsonl # One document per line +├── tasks/ +│ └── documents.jsonl +├── _storage/ # Optional: file storage +│ └── files... +└── generated_schema.jsonl # Preserves Int64, Bytes types +``` + +**Import ZIP:** +```bash +# Import to dev deployment +npx convex import snapshot_1234567890.zip + +# Import to production (CAUTION!) +npx convex import snapshot_1234567890.zip --prod +``` + +**Technical Explanation:** +- ZIP imports preserve document `_id` and `_creationTime` fields +- Maintains referential integrity across table references +- Import is atomic (except with `--append` flag) +- Queries never see partially imported state + +#### Import from Custom Data Sources + +**Single Table Import:** + +```bash +# CSV (requires headers) +npx convex import --table users users.csv + +# JSONLines (one object per line) +npx convex import --table tasks tasks.jsonl + +# JSON (array of objects, 8MiB limit) +npx convex import --table products products.json +``` + +**Import Modes:** + +```bash +# Append to existing data +npx convex import --table users users.jsonl --append + +# Replace all table data (destructive) +npx convex import --table users users.jsonl --replace + +# Default: Fail if table already exists +npx convex import --table users users.jsonl +``` + +**Production Import:** +```bash +# ALWAYS test in dev first! +npx convex import --table users users.jsonl + +# Then import to production +npx convex import --table users users.jsonl --prod +``` + +#### Disaster Recovery Scenarios + +**Scenario 1: Bad Deployment** + +```bash +# 1. Create immediate backup (if not already automated) +Dashboard → Backup Now + +# 2. Restore from last known-good backup +Dashboard → Restore from backup (before bad deployment) + +# 3. Redeploy validated code +git checkout +npx convex deploy --prod + +# 4. Verify production +npx convex dashboard # Check logs and data +``` + +**Scenario 2: Data Corruption** + +```bash +# 1. Identify corruption scope (table/documents) +npx convex data # Inspect data + +# 2. Export current state (for forensics) +npx convex export --path ./corrupt-state + +# 3. Restore from backup +Dashboard → Restore from backup + +# 4. Manual corrections (if needed) +# Write one-off mutations to fix specific records +``` + +**Scenario 3: Accidental Deletion** + +```bash +# 1. Immediately stop further writes (if possible) +# Disable frontend or pause deployment + +# 2. Restore from most recent backup +Dashboard → Restore from backup (within 7 days) + +# 3. Assess data loss window +# Any data between backup and deletion is lost +# Consider manual reconstruction from logs/analytics +``` + +#### Streaming Export (Alternative Backup) + +**VERIFY at:** https://docs.convex.dev/production/integrations/streaming-import-export + +For continuous data replication to external databases: + +```bash +# Integrate via Fivetran or Airbyte +# Provides real-time backup to: +- PostgreSQL +- Snowflake +- BigQuery +- Redshift +``` + +**Use Cases:** +- Real-time analytics warehouse +- Continuous backup to external system +- Compliance/audit trail requirements +- Multi-region data redundancy + +**Important:** After restoring from backup, streaming export integrations must be reset. + +#### Backup Limitations & Requirements + +**What's Included:** +- ✅ All table data with schemas +- ✅ File storage (if option selected) +- ✅ Document IDs and creation times +- ✅ Advanced types (Int64, Bytes via generated_schema.jsonl) + +**What's Excluded:** +- ❌ Deployment code (functions) +- ❌ Configuration files +- ❌ Environment variables +- ❌ Pending scheduled functions +- ❌ Authentication provider config + +**After Restore, You Must:** +1. Redeploy code: `npx convex deploy --prod` +2. Restore environment variables: `npx convex env set ...` +3. Reconfigure authentication providers (Clerk, etc.) +4. Reset streaming export integrations (if using) +5. Verify scheduled functions are running + +**Beta Note:** ZIP imports not supported on deployments created before Convex v1.7. Contact support for workarounds. + --- ## Notes From c0076e69db73e3f8993c139662f622d3fcf1f3b6 Mon Sep 17 00:00:00 2001 From: George Liu Date: Mon, 5 Jan 2026 18:09:25 +1000 Subject: [PATCH 059/174] update settings --- .claude/settings.local.json | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 16a620b..a2a28cc 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -8,7 +8,6 @@ }, "includeCoAuthoredBy": false, "permissions": { - "defaultMode": "plan", "allow": [ "Bash(.venv/bin/pip:*)", "Bash(.venv/bin/python:*)", @@ -84,8 +83,11 @@ "mcp__chrome-devtools__fill", "mcp__chrome-devtools__navigate_page_history", "mcp__chrome-devtools__new_page", - "Skill(claude-docs-consultant)" + "Skill(claude-docs-consultant)", + "WebFetch(domain:docs.convex.dev)", + "mcp__context7__query-docs" ], - "deny": [] + "deny": [], + "defaultMode": "plan" } } From 4939670254e3dd17490f612abb52e5702ad6aa66 Mon Sep 17 00:00:00 2001 From: George Liu Date: Mon, 5 Jan 2026 18:32:53 +1000 Subject: [PATCH 060/174] Enhance CLAUDE-convex.md: Add Priority 2+3 sections for comprehensive coverage Added 13 new sections (~990 lines) to complete documentation coverage: Priority 2 (High Impact): - Full Text Search: BM25 search indexes, query patterns, constraints - Vector Search: Embeddings, semantic search, OpenAI integration - Internal Functions: internalQuery/Mutation/Action patterns - React Vite Hooks: Complete hook patterns with conditional queries - SSR Expansion: fetchQuery, fetchMutation, authenticated SSR - convex-test: Vitest setup, mocking, authentication testing - CI/CD: GitHub Actions workflows for test and deploy Priority 3 (Nice to Have): - Optimistic Updates: useMutation.withOptimisticUpdate patterns - Preview Deployments: GitHub Actions PR workflow - Log Streams: Axiom/Datadog/Webhook integration - Streaming Import/Export: Fivetran/Airbyte for analytics - Popular Components examples: Rate limiter, sharded counter - Cloudflare Troubleshooting: Common issues and solutions Final line count: 3,931 (was 2,941) Coverage vs llms.txt: ~95% complete --- CLAUDE-convex.md | 1001 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 996 insertions(+), 5 deletions(-) diff --git a/CLAUDE-convex.md b/CLAUDE-convex.md index 5b8c378..d24221d 100644 --- a/CLAUDE-convex.md +++ b/CLAUDE-convex.md @@ -727,6 +727,209 @@ export default async function TasksPage() { --- +### Advanced Server-Side Rendering (SSR) + +**VERIFY at:** https://docs.convex.dev/client/react/nextjs/server-rendering + +**Using fetchQuery for Server Components (Non-Reactive):** +```typescript +import { fetchQuery } from "convex/nextjs"; +import { api } from "@/convex/_generated/api"; + +// Server Component - data fetched once at render time (not reactive) +export default async function StaticTasksPage() { + const tasks = await fetchQuery(api.tasks.list, { list: "default" }); + + return ( +
+

Tasks (Static)

+ {tasks.map((task) => ( +
{task.text}
+ ))} +
+ ); +} +``` + +**Using fetchMutation in Server Actions:** +```typescript +import { fetchMutation } from "convex/nextjs"; +import { api } from "@/convex/_generated/api"; + +async function createTaskAction(formData: FormData) { + "use server"; + await fetchMutation(api.tasks.create, { + text: formData.get("text") as string, + }); +} + +export default function TaskForm() { + return ( +
+ + +
+ ); +} +``` + +**SSR with Authentication:** +```typescript +import { preloadQuery } from "convex/nextjs"; +import { auth } from "@clerk/nextjs/server"; +import { api } from "@/convex/_generated/api"; + +export default async function AuthenticatedPage() { + // Get Convex token from Clerk + const { getToken } = await auth(); + const token = await getToken({ template: "convex" }); + + // Pass token to preloadQuery for authenticated data + const preloadedData = await preloadQuery( + api.tasks.getMyTasks, + {}, + { token: token ?? undefined } + ); + + return ; +} +``` + +**Technical Notes:** +- `preloadQuery`: Preloads data, client component becomes reactive +- `fetchQuery`: One-time fetch, no reactivity (pure server component) +- `fetchMutation`: Execute mutations from Server Actions or Route Handlers +- Token passing required for authenticated queries in SSR + +--- + +### React (Vite) Hooks + +**VERIFY at:** https://docs.convex.dev/quickstart/react + +**src/App.tsx:** +```typescript +import { useQuery, useMutation, useAction } from "convex/react"; +import { api } from "../convex/_generated/api"; + +export function App() { + // Reactive query - automatically updates when data changes + const tasks = useQuery(api.tasks.list); + + // Mutation hook - returns function to call + const createTask = useMutation(api.tasks.create); + const deleteTask = useMutation(api.tasks.remove); + + // Action hook - for external API calls + const sendEmail = useAction(api.notifications.sendEmail); + + // Loading state + if (tasks === undefined) { + return
Loading...
; + } + + const handleCreate = async (text: string) => { + await createTask({ text, isCompleted: false }); + }; + + const handleDelete = async (id: Id<"tasks">) => { + await deleteTask({ id }); + }; + + return ( +
+ {tasks.map((task) => ( +
+ {task.text} + +
+ ))} + +
+ ); +} +``` + +**Conditional Queries:** +```typescript +// Skip query when condition not met +const userId = useAuth()?.userId; +const userTasks = useQuery( + api.tasks.getByUser, + userId ? { userId } : "skip" // "skip" prevents query execution +); +``` + +--- + +### Optimistic Updates + +**VERIFY at:** https://docs.convex.dev/client/react/optimistic-updates + +Optimistic updates provide instant UI feedback before server confirmation. + +**Basic Example:** +```typescript +"use client"; +import { useMutation, useQuery } from "convex/react"; +import { api } from "@/convex/_generated/api"; + +export function Counter() { + const count = useQuery(api.counter.get); + + const increment = useMutation(api.counter.increment).withOptimisticUpdate( + (localStore, args) => { + const currentValue = localStore.getQuery(api.counter.get, {}); + if (currentValue !== undefined) { + // Immediately update local state + localStore.setQuery(api.counter.get, {}, currentValue + args.amount); + } + } + ); + + return ( +
+

Count: {count ?? 0}

+ +
+ ); +} +``` + +**Chat Message Example:** +```typescript +const sendMessage = useMutation(api.messages.send).withOptimisticUpdate( + (localStore, args) => { + const { channel, body } = args; + const existingMessages = localStore.getQuery(api.messages.list, { channel }); + + if (existingMessages !== undefined) { + // Add temporary message immediately + const optimisticMessage = { + _id: crypto.randomUUID() as Id<"messages">, + _creationTime: Date.now(), + channel, + body, + pending: true, // Optional: mark as pending + }; + + localStore.setQuery(api.messages.list, { channel }, [ + ...existingMessages, + optimisticMessage, + ]); + } + } +); +``` + +**Best Practices:** +- Always create new objects (don't mutate existing) +- Check if query is loaded before updating +- Optimistic data may differ from server response (automatically corrected) +- Small mistakes are okay - UI will eventually show correct values + +--- + ## Cloudflare Pages Deployment ### Deployment Architecture @@ -787,6 +990,58 @@ npx convex env set STRIPE_SECRET_KEY sk_live_... --prod --- +### Cloudflare Troubleshooting + +**Common Issues and Solutions:** + +| Issue | Cause | Solution | +|-------|-------|----------| +| "Convex URL not found" | Missing env var | Add `NEXT_PUBLIC_CONVEX_URL` in Pages dashboard | +| Build fails on Cloudflare | Node version | Set `NODE_VERSION=18` in env vars | +| Functions timeout | Edge runtime limits | Use Convex for heavy processing, not Pages Functions | +| Preview deploy uses prod Convex | Same URL for all | Use separate Convex projects per environment | +| WebSocket connection fails | Proxy/firewall | Ensure `*.convex.cloud` is allowed | + +**Environment-Specific Deployment:** +```bash +# Create separate Convex projects for each environment +# Production +npx convex deploy --prod --project my-app-prod + +# Staging (separate project) +npx convex dev --project my-app-staging +``` + +**DNS & Custom Domains:** +- Cloudflare Pages handles frontend domains automatically +- Convex deployment URL remains `*.convex.cloud` +- No custom domain needed for Convex (frontend proxies requests) + +**Build Optimization:** +```bash +# Cloudflare Pages Build Settings +Build command: npm run build +Build output directory: .next (Next.js) or dist (Vite) +Root directory: / (or your app subdirectory) +``` + +**Debugging Production Issues:** +```bash +# Stream logs from production +npx convex logs --prod + +# Check function execution in dashboard +npx convex dashboard +``` + +**Important Notes:** +- Cloudflare Pages has 100ms CPU time limit for edge functions +- Use Convex actions for heavy computation (30s limit on paid plans) +- Real-time features (WebSocket) work out-of-box with Convex +- No cold starts for Convex functions + +--- + ## Development Commands **VERIFY at:** https://docs.convex.dev/cli @@ -1045,6 +1300,254 @@ await createTask({ --- +## Testing + +**VERIFY at:** https://docs.convex.dev/testing + +### convex-test Setup + +The `convex-test` library provides a mocked Convex backend for unit testing with Vitest. + +**Installation:** +```bash +npm install --save-dev convex-test vitest @edge-runtime/vm +``` + +**vitest.config.ts:** +```typescript +import { defineConfig } from "vitest/config"; + +export default defineConfig({ + test: { + environment: "edge-runtime", + server: { deps: { inline: ["convex-test"] } }, + }, +}); +``` + +**package.json scripts:** +```json +{ + "scripts": { + "test": "vitest", + "test:once": "vitest run", + "test:coverage": "vitest run --coverage" + } +} +``` + +### Writing Tests + +**convex/messages.test.ts:** +```typescript +import { convexTest } from "convex-test"; +import { expect, test } from "vitest"; +import { api } from "./_generated/api"; +import schema from "./schema"; + +test("sending and listing messages", async () => { + const t = convexTest(schema); + + // Test mutations + await t.mutation(api.messages.send, { body: "Hello!", author: "Alice" }); + await t.mutation(api.messages.send, { body: "Hi there!", author: "Bob" }); + + // Test queries + const messages = await t.query(api.messages.list); + expect(messages).toMatchObject([ + { body: "Hello!", author: "Alice" }, + { body: "Hi there!", author: "Bob" }, + ]); +}); + +test("direct database access", async () => { + const t = convexTest(schema); + + // Directly manipulate database for test setup + const task = await t.run(async (ctx) => { + await ctx.db.insert("tasks", { text: "Test task", isCompleted: false }); + return await ctx.db.query("tasks").first(); + }); + + expect(task).toMatchObject({ text: "Test task" }); +}); +``` + +### Testing with Authentication + +```typescript +import { convexTest } from "convex-test"; +import { expect, test } from "vitest"; +import { api } from "./_generated/api"; +import schema from "./schema"; + +test("authenticated user operations", async () => { + const t = convexTest(schema); + + // Create test user with identity + const asAlice = t.withIdentity({ name: "Alice", email: "alice@example.com" }); + const asBob = t.withIdentity({ name: "Bob", email: "bob@example.com" }); + + // Each user sees only their own data + await asAlice.mutation(api.tasks.create, { text: "Alice's task" }); + await asBob.mutation(api.tasks.create, { text: "Bob's task" }); + + const aliceTasks = await asAlice.query(api.tasks.getMyTasks); + expect(aliceTasks).toHaveLength(1); + expect(aliceTasks[0].text).toBe("Alice's task"); +}); +``` + +### Testing HTTP Actions + +```typescript +test("http endpoint", async () => { + const t = convexTest(schema); + + const response = await t.fetch("/api/health", { method: "GET" }); + expect(response.status).toBe(200); + + const data = await response.json(); + expect(data).toMatchObject({ status: "ok" }); +}); +``` + +### Mocking External APIs + +```typescript +import { vi } from "vitest"; + +test("action with external API", async () => { + // Mock fetch for external API calls + vi.stubGlobal("fetch", vi.fn(async () => ({ + ok: true, + json: async () => ({ result: "mocked" }), + }))); + + const t = convexTest(schema); + const result = await t.action(api.external.callApi, { input: "test" }); + + expect(result).toBe("mocked"); + vi.unstubAllGlobals(); +}); +``` + +--- + +## CI/CD & Deployment + +**VERIFY at:** https://docs.convex.dev/production/hosting + +### GitHub Actions Workflow + +**.github/workflows/test.yml:** +```yaml +name: Test and Deploy + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: "20" + cache: "npm" + + - run: npm ci + - run: npm run test:once + + deploy: + needs: test + if: github.ref == 'refs/heads/main' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: "20" + cache: "npm" + + - run: npm ci + + # Deploy Convex backend + - run: npx convex deploy --cmd "npm run build" + env: + CONVEX_DEPLOY_KEY: ${{ secrets.CONVEX_DEPLOY_KEY }} +``` + +### Preview Deployments + +**VERIFY at:** https://docs.convex.dev/production/hosting/preview-deployments + +Preview deployments create isolated Convex backends for each PR. + +**.github/workflows/preview.yml:** +```yaml +name: Preview Deployment + +on: + pull_request: + types: [opened, synchronize] + +jobs: + preview: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: "20" + + - run: npm ci + + # Create preview deployment + - run: | + npx convex deploy \ + --preview-create ${{ github.head_ref }} \ + --preview-run seedData + env: + CONVEX_DEPLOY_KEY: ${{ secrets.CONVEX_DEPLOY_KEY }} + + # Comment preview URL on PR + - uses: actions/github-script@v7 + with: + script: | + github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + body: '🚀 Preview deployment ready!' + }) +``` + +### Environment Setup + +**Getting CONVEX_DEPLOY_KEY:** +```bash +# Generate deploy key for CI/CD +npx convex deploy-key create + +# Add to GitHub Secrets: +# Settings → Secrets → Actions → New repository secret +# Name: CONVEX_DEPLOY_KEY +# Value: (paste the key) +``` + +**Preview Deployment Notes:** +- Auto-deleted after 5 days (14 days on Professional) +- Each PR gets isolated database +- Use `--preview-run` to seed test data +- Preview URL returned by deploy command + +--- + ## Common Patterns & Best Practices ### Relationship Modeling @@ -1364,6 +1867,313 @@ const handleUpload = async (file: File) => { --- +## Full Text Search + +**VERIFY at:** https://docs.convex.dev/text-search + +### Defining Search Indexes + +Search indexes enable full-text search over string fields using BM25 scoring. + +**convex/schema.ts:** +```typescript +import { defineSchema, defineTable } from "convex/server"; +import { v } from "convex/values"; + +export default defineSchema({ + messages: defineTable({ + body: v.string(), + channel: v.string(), + author: v.string(), + }).searchIndex("search_body", { + searchField: "body", // Field to search + filterFields: ["channel"], // Up to 16 filter fields + }), + + articles: defineTable({ + title: v.string(), + content: v.string(), + category: v.string(), + published: v.boolean(), + }).searchIndex("search_content", { + searchField: "content", + filterFields: ["category", "published"], + }), +}); +``` + +### Running Search Queries + +**convex/messages.ts:** +```typescript +import { query } from "./_generated/server"; +import { v } from "convex/values"; + +// Basic search +export const search = query({ + args: { searchTerm: v.string(), channel: v.optional(v.string()) }, + handler: async (ctx, args) => { + let searchQuery = ctx.db + .query("messages") + .withSearchIndex("search_body", (q) => { + let search = q.search("body", args.searchTerm); + if (args.channel) { + search = search.eq("channel", args.channel); + } + return search; + }); + + // Results ordered by relevance (BM25 score) + return await searchQuery.take(10); + }, +}); + +// Search with additional filtering +export const searchRecent = query({ + args: { searchTerm: v.string() }, + handler: async (ctx, args) => { + const tenMinutesAgo = Date.now() - 10 * 60 * 1000; + + return await ctx.db + .query("messages") + .withSearchIndex("search_body", (q) => q.search("body", args.searchTerm)) + .filter((q) => q.gt(q.field("_creationTime"), tenMinutesAgo)) + .take(10); + }, +}); +``` + +**Search Constraints:** +- Up to 16 search terms per query +- Up to 8 filter expressions +- Maximum 1024 documents scanned per query +- Terms limited to 32 characters (case-insensitive) +- Results always returned in relevance order + +--- + +## Vector Search + +**VERIFY at:** https://docs.convex.dev/vector-search + +### Defining Vector Indexes + +Vector indexes enable semantic similarity search using embeddings. + +**convex/schema.ts:** +```typescript +import { defineSchema, defineTable } from "convex/server"; +import { v } from "convex/values"; + +export default defineSchema({ + documents: defineTable({ + title: v.string(), + content: v.string(), + embedding: v.array(v.float64()), // Vector field + category: v.optional(v.string()), + }).vectorIndex("by_embedding", { + vectorField: "embedding", + dimensions: 1536, // Must match embedding model (OpenAI: 1536) + filterFields: ["category"], // Optional filter fields + }), +}); +``` + +### Storing Embeddings + +**convex/documents.ts:** +```typescript +import { action, internalMutation } from "./_generated/server"; +import { v } from "convex/values"; +import { internal } from "./_generated/api"; + +// Action to generate and store embedding +export const addDocument = action({ + args: { title: v.string(), content: v.string(), category: v.optional(v.string()) }, + handler: async (ctx, args) => { + // Generate embedding via OpenAI + const response = await fetch("https://api.openai.com/v1/embeddings", { + method: "POST", + headers: { + "Authorization": `Bearer ${process.env.OPENAI_API_KEY}`, + "Content-Type": "application/json", + }, + body: JSON.stringify({ + model: "text-embedding-3-small", + input: args.content, + }), + }); + + const { data } = await response.json(); + const embedding = data[0].embedding; + + // Store document with embedding + await ctx.runMutation(internal.documents.insertDocument, { + title: args.title, + content: args.content, + embedding, + category: args.category, + }); + }, +}); + +export const insertDocument = internalMutation({ + args: { + title: v.string(), + content: v.string(), + embedding: v.array(v.float64()), + category: v.optional(v.string()), + }, + handler: async (ctx, args) => { + await ctx.db.insert("documents", args); + }, +}); +``` + +### Running Vector Searches + +**convex/search.ts:** +```typescript +import { action, internalQuery } from "./_generated/server"; +import { v } from "convex/values"; +import { internal } from "./_generated/api"; + +// Vector search action +export const semanticSearch = action({ + args: { query: v.string(), category: v.optional(v.string()) }, + handler: async (ctx, args) => { + // Generate query embedding + const response = await fetch("https://api.openai.com/v1/embeddings", { + method: "POST", + headers: { + "Authorization": `Bearer ${process.env.OPENAI_API_KEY}`, + "Content-Type": "application/json", + }, + body: JSON.stringify({ + model: "text-embedding-3-small", + input: args.query, + }), + }); + + const { data } = await response.json(); + const queryEmbedding = data[0].embedding; + + // Perform vector search + const results = await ctx.vectorSearch("documents", "by_embedding", { + vector: queryEmbedding, + limit: 10, + filter: args.category + ? (q) => q.eq("category", args.category) + : undefined, + }); + + // Load full documents + const documents = await ctx.runQuery(internal.documents.getByIds, { + ids: results.map((r) => r._id), + }); + + return documents; + }, +}); + +export const getByIds = internalQuery({ + args: { ids: v.array(v.id("documents")) }, + handler: async (ctx, args) => { + const results = []; + for (const id of args.ids) { + const doc = await ctx.db.get(id); + if (doc) results.push(doc); + } + return results; + }, +}); +``` + +**Vector Search Constraints:** +- Up to 4 vector indexes per table +- Maximum 256 results per query +- Dimensions must match exactly (e.g., 1536 for OpenAI) +- Uses approximate nearest neighbor with cosine similarity +- Score ranges from -1 to 1 (higher = more similar) + +--- + +## Internal Functions + +**VERIFY at:** https://docs.convex.dev/functions/internal-functions + +### What Are Internal Functions? + +Internal functions can only be called by other Convex functions (not from clients). They reduce your app's attack surface. + +**convex/internal.ts:** +```typescript +import { internalQuery, internalMutation, internalAction } from "./_generated/server"; +import { v } from "convex/values"; + +// Internal query - not accessible from client +export const getSecretData = internalQuery({ + args: { userId: v.id("users") }, + handler: async (ctx, args) => { + // Sensitive data access + return await ctx.db + .query("sensitiveData") + .withIndex("by_user", (q) => q.eq("userId", args.userId)) + .collect(); + }, +}); + +// Internal mutation - for privileged operations +export const upgradeUserPlan = internalMutation({ + args: { userId: v.id("users"), plan: v.string() }, + handler: async (ctx, args) => { + await ctx.db.patch(args.userId, { plan: args.plan }); + }, +}); + +// Internal action - for background processing +export const processPayment = internalAction({ + args: { userId: v.id("users"), amount: v.number() }, + handler: async (ctx, args) => { + // Call external payment API + // Then update user via internal mutation + await ctx.runMutation(internal.users.upgradeUserPlan, { + userId: args.userId, + plan: "premium", + }); + }, +}); +``` + +### Calling Internal Functions + +```typescript +import { action, mutation } from "./_generated/server"; +import { internal } from "./_generated/api"; + +// Public action that uses internal functions +export const handleWebhook = action({ + args: { event: v.string(), userId: v.id("users") }, + handler: async (ctx, args) => { + if (args.event === "payment.success") { + // Call internal mutation - safe from direct client access + await ctx.runMutation(internal.users.upgradeUserPlan, { + userId: args.userId, + plan: "premium", + }); + } + }, +}); +``` + +**When to Use Internal Functions:** +- Privileged operations (admin-only actions) +- Operations called from scheduled functions/crons +- Business logic that should bypass client validation +- Actions called from HTTP endpoints/webhooks + +--- + ## Components **VERIFY at:** https://docs.convex.dev/components @@ -1712,11 +2522,93 @@ npm publish - `@convex-dev/agent` - AI agents with threads, messages, tool calls - `@convex-dev/rag` - RAG (Retrieval-Augmented Generation) for semantic search - `@convex-dev/rate-limiter` - API rate limiting and usage tracking -- Authentication components (Clerk, Auth0, etc.) -- Workflow engines -- Leaderboards & rankings -- Feature flags -- Document collaboration +- `@convex-dev/sharded-counter` - High-throughput counters (avoids OCC conflicts) +- `@convex-dev/crons` - Advanced cron scheduling +- `@convex-dev/workflow` - Durable workflow execution + +#### Rate Limiter Example + +```bash +npm install @convex-dev/rate-limiter +``` + +**convex/convex.config.ts:** +```typescript +import { defineApp } from "convex/server"; +import rateLimiter from "@convex-dev/rate-limiter/convex.config"; + +const app = defineApp(); +app.use(rateLimiter, { name: "rateLimit" }); +export default app; +``` + +**convex/rateLimit.ts:** +```typescript +import { components } from "./_generated/api"; +import { RateLimiter } from "@convex-dev/rate-limiter"; + +const rateLimiter = new RateLimiter(components.rateLimit, { + apiRequests: { kind: "token bucket", rate: 100, period: 60000, capacity: 100 }, + signups: { kind: "fixed window", rate: 5, period: 3600000 }, +}); + +export const checkApiLimit = rateLimiter.check("apiRequests"); +export const consumeApiToken = rateLimiter.consume("apiRequests"); +``` + +**Usage in mutation:** +```typescript +export const createPost = mutation({ + args: { content: v.string() }, + handler: async (ctx, args) => { + const identity = await ctx.auth.getUserIdentity(); + if (!identity) throw new Error("Not authenticated"); + + // Check rate limit before proceeding + const { ok, retryAfter } = await rateLimiter.limit(ctx, "apiRequests", { + key: identity.subject, + }); + + if (!ok) { + throw new Error(`Rate limited. Retry after ${retryAfter}ms`); + } + + return await ctx.db.insert("posts", { content: args.content }); + }, +}); +``` + +#### Sharded Counter Example + +```bash +npm install @convex-dev/sharded-counter +``` + +**For high-frequency counters that would cause OCC conflicts:** +```typescript +import { components } from "./_generated/api"; +import { ShardedCounter } from "@convex-dev/sharded-counter"; + +const counter = new ShardedCounter(components.shardedCounter, { + shards: 100, // More shards = higher throughput +}); + +// Increment without conflicts +export const incrementViews = mutation({ + args: { postId: v.id("posts") }, + handler: async (ctx, args) => { + await counter.inc(ctx, args.postId, 1); + }, +}); + +// Read approximate count +export const getViewCount = query({ + args: { postId: v.id("posts") }, + handler: async (ctx, args) => { + return await counter.count(ctx, args.postId); + }, +}); +``` **Technical Explanation:** Components enable composability for complex features without building from scratch, while maintaining data isolation and transactional guarantees. @@ -2406,6 +3298,51 @@ const users = await Promise.all( --- +### Log Streams & Exception Reporting + +**VERIFY at:** https://docs.convex.dev/production/integrations/log-streams + +Stream logs to external services for monitoring and alerting. Requires Convex Pro plan. + +**Available Destinations:** +- **Axiom** - Log analytics with automatic dashboard creation +- **Datadog** - APM and log management +- **Webhook** - Custom HTTP endpoints (any service) + +**Setup via Dashboard:** +1. Go to Convex Dashboard → Settings → Integrations +2. Select destination (Axiom, Datadog, or Webhook) +3. Configure credentials and options +4. Enable log stream + +**Log Event Types:** + +| Event Type | Description | +|------------|-------------| +| `console` | Function console.log/warn/error output | +| `function_execution` | Execution metrics (duration, status, errors) | +| `audit_log` | Deployment changes and admin actions | +| `scheduler_stats` | Scheduled function queue metrics | +| `storage_usage` | Database and file storage metrics | + +**Webhook Security:** +```typescript +// Verify webhook signature (HMAC-SHA256) +const signature = request.headers.get("x-webhook-signature"); +const timestamp = request.headers.get("x-webhook-timestamp"); + +// Validate using constant-time comparison +// Check timestamp to prevent replay attacks +``` + +**Best Practices:** +- Use Axiom for quick setup with pre-built dashboards +- Datadog for existing APM infrastructure +- Webhook for custom alerting or unsupported services +- Log streams are "best-effort" - may drop events under high load + +--- + ## Production Guarantees & Limits **VERIFY at:** https://docs.convex.dev/production/state/ @@ -2917,6 +3854,60 @@ For continuous data replication to external databases: --- +### Streaming Import/Export + +**VERIFY at:** https://docs.convex.dev/database/import-export/streaming + +For large-scale data operations, Convex supports streaming via Fivetran and Airbyte. + +**Streaming Export (Pro Plan Required):** + +Export data to external analytics platforms: +- **Databricks** - Data lakehouse analytics +- **Snowflake** - Cloud data warehouse +- **BigQuery** - Google Cloud analytics +- **ElasticSearch** - Advanced search and filtering + +**Use Cases:** +- Heavy analytical queries not suited for Convex +- Machine learning training on historical data +- Complex reporting and BI dashboards +- Full-text search with advanced features + +**Setup:** +1. Dashboard → Settings → Integrations → Fivetran/Airbyte +2. Configure destination credentials +3. Select tables to export +4. Set sync frequency + +**Streaming Import:** + +Import data from existing databases: +- Enables gradual Convex adoption +- Build new features on existing data +- Create reactive UI layers over legacy systems +- No custom migration tooling required + +**Important Considerations:** +- Treat imported tables as **read-only** to prevent write conflicts +- Streaming export is beta feature +- Streaming import via Fivetran not currently supported +- Both integrations use incremental sync for efficiency + +**CLI Export Alternative:** +```bash +# For one-time exports (not streaming) +npx convex export --path ./backup + +# Export with file storage +npx convex export --include-file-storage --path ./backup + +# Import from JSONL +npx convex import --table tasks ./data/tasks.jsonl +``` + +--- + ## Notes From 86c3007055577f2cd3031d654d8edfb67c645441 Mon Sep 17 00:00:00 2001 From: George Liu Date: Mon, 5 Jan 2026 18:47:26 +1000 Subject: [PATCH 061/174] Fix markdown lint issues in CLAUDE-convex.md - Add blank lines around code fences, headings, lists, and tables - Add language specifiers to bare code blocks - Wrap bare URLs and email addresses in angle brackets - Fix table column spacing - Normalize numbered list prefixes for list continuity - Reduce lint warnings from ~330 to 15 (stylistic only) --- CLAUDE-convex.md | 436 +++++++++++++++++++++++++++++++++-------------- 1 file changed, 312 insertions(+), 124 deletions(-) diff --git a/CLAUDE-convex.md b/CLAUDE-convex.md index d24221d..3c31815 100644 --- a/CLAUDE-convex.md +++ b/CLAUDE-convex.md @@ -1,6 +1,7 @@ # CLAUDE.md - Convex Database Project Template ## Project Overview + - **Project Name**: [PROJECT_NAME] - **Description**: [BRIEF_DESCRIPTION] - **Database**: Convex @@ -12,75 +13,82 @@ ## CRITICAL: Documentation Verification Rules ### Before Writing ANY Code + 1. **Determine project language/framework** by inspecting project files 2. **Lookup current documentation** for the detected stack before implementing 3. **Never assume** API signatures, function syntax, or hook patterns ### MCP Tools (if available) + - **context7 MCP**: Query for latest Convex documentation - **Cloudflare MCP**: Search Cloudflare Pages deployment docs ### Documentation URLs (for web fetch if no MCP) + Fetch and read these URLs to verify current APIs: **Convex Platform:** + | Service | URL | -|---------|-----| -| LLM-Optimized Docs | https://docs.convex.dev/llms.txt | -| Quickstart (Next.js App Router) | https://docs.convex.dev/quickstart/nextjs | -| Quickstart (Next.js Pages Router) | https://docs.convex.dev/client/nextjs/pages-router/quickstart | -| Quickstart (React/Vite) | https://docs.convex.dev/quickstart/react | -| Database Schemas | https://docs.convex.dev/database/schemas | -| Reading Data (Queries) | https://docs.convex.dev/database/reading-data | -| Writing Data (Mutations) | https://docs.convex.dev/database/writing-data | -| Functions Overview | https://docs.convex.dev/functions | -| Query Functions | https://docs.convex.dev/functions/query-functions | -| Mutation Functions | https://docs.convex.dev/functions/mutation-functions | -| Actions | https://docs.convex.dev/functions/actions | -| HTTP Actions | https://docs.convex.dev/functions/http-actions | -| Scheduled Functions | https://docs.convex.dev/scheduling/scheduled-functions | -| Authentication Overview | https://docs.convex.dev/auth | -| Clerk Integration | https://docs.convex.dev/auth/clerk | -| Convex Auth | https://docs.convex.dev/auth/convex-auth | -| Custom Auth | https://docs.convex.dev/auth/custom-auth | -| Authorization Patterns | https://docs.convex.dev/auth/authorization | -| Database Indexes | https://docs.convex.dev/database/indexes | -| Pagination | https://docs.convex.dev/database/pagination | -| File Storage | https://docs.convex.dev/file-storage | -| Full-text Search | https://docs.convex.dev/text-search | -| Vector Search | https://docs.convex.dev/vector-search | -| TypeScript | https://docs.convex.dev/typescript | -| Error Handling | https://docs.convex.dev/functions/error-handling | -| Testing | https://docs.convex.dev/production/testing | -| Environment Variables | https://docs.convex.dev/production/environment-variables | -| Production Hosting | https://docs.convex.dev/production/hosting | -| Monitoring | https://docs.convex.dev/production/monitoring | -| Convex CLI | https://docs.convex.dev/cli | +| --------- | ----- | +| LLM-Optimized Docs | | +| Quickstart (Next.js App Router) | | +| Quickstart (Next.js Pages Router) | | +| Quickstart (React/Vite) | | +| Database Schemas | | +| Reading Data (Queries) | | +| Writing Data (Mutations) | | +| Functions Overview | | +| Query Functions | | +| Mutation Functions | | +| Actions | | +| HTTP Actions | | +| Scheduled Functions | | +| Authentication Overview | | +| Clerk Integration | | +| Convex Auth | | +| Custom Auth | | +| Authorization Patterns | | +| Database Indexes | | +| Pagination | | +| File Storage | | +| Full-text Search | | +| Vector Search | | +| TypeScript | | +| Error Handling | | +| Testing | | +| Environment Variables | | +| Production Hosting | | +| Monitoring | | +| Convex CLI | | **Clerk Authentication:** + | Resource | URL | -|----------|-----| -| Clerk + Convex | https://docs.convex.dev/auth/clerk | -| Clerk Backend SDK | https://clerk.com/docs/reference/backend/overview | -| Clerk Next.js | https://clerk.com/docs/reference/nextjs/overview | -| Clerk React | https://clerk.com/docs/reference/react/overview | +| ---------- | ----- | +| Clerk + Convex | | +| Clerk Backend SDK | | +| Clerk Next.js | | +| Clerk React | | **Cloudflare Pages Deployment:** + | Resource | URL | -|----------|-----| -| Pages Overview | https://developers.cloudflare.com/pages/ | -| Next.js on Pages | https://developers.cloudflare.com/pages/framework-guides/nextjs/ | -| Build Configuration | https://developers.cloudflare.com/pages/configuration/build-configuration/ | -| Pages Functions | https://developers.cloudflare.com/pages/functions/ | +| ---------- | ----- | +| Pages Overview | | +| Next.js on Pages | | +| Build Configuration | | +| Pages Functions | | --- ## Project Detection & Setup ### Step 1: Detect Existing Project Type + Inspect project files to determine language/framework: -``` +```text File Found -> Stack -> Action ----------------------------------------------------------------- convex/ directory -> Existing Convex -> Check convex.json, schema.ts @@ -97,6 +105,7 @@ No convex/ directory -> New project -> Run: npx create convex@latest ### Step 2: New Project Setup (if no convex/) **Option 1: Create new Next.js project with Convex** + ```bash # VERIFY at: https://docs.convex.dev/quickstart/nextjs npx create-next-app@latest my-app @@ -106,6 +115,7 @@ npx convex dev ``` **Option 2: Add Convex to existing project** + ```bash # VERIFY at: https://docs.convex.dev/quickstart npm install convex @@ -113,6 +123,7 @@ npx convex dev # Initializes convex/ directory and cloud project ``` **Option 3: Use Convex template (interactive)** + ```bash npx create convex@latest # Interactive setup with framework selection ``` @@ -120,11 +131,13 @@ npx create convex@latest # Interactive setup with framework selection ### Step 3: Install Dependencies (after detection) **Core (always needed):** + ```bash npm install convex # Convex client and server SDK ``` **Clerk Authentication (recommended):** + ```bash # For Next.js npm install @clerk/nextjs @@ -134,6 +147,7 @@ npm install @clerk/clerk-react ``` **Convex Auth (alternative, beta):** + ```bash # Built into Convex, configure via dashboard # https://docs.convex.dev/auth/convex-auth @@ -145,7 +159,7 @@ npm install @clerk/clerk-react ### convex.json (Project Configuration) -**VERIFY at:** https://docs.convex.dev/production/hosting/hosting-and-running +**VERIFY at:** ```json { @@ -157,6 +171,7 @@ npm install @clerk/clerk-react ``` **Technical Explanation:** + - `functions`: Directory containing Convex backend functions (queries, mutations, actions) - `externalPackages`: Node.js packages that can be imported in actions (not queries/mutations) - Most configuration is managed in Convex dashboard, not this file @@ -166,6 +181,7 @@ npm install @clerk/clerk-react ### Environment Variables **.env.local (Local Development):** + ```bash # VERIFY at: https://docs.convex.dev/production/environment-variables @@ -183,6 +199,7 @@ VITE_CONVEX_URL=https://your-deployment.convex.cloud ``` **Technical Explanation:** + - **Frontend vars**: Must be prefixed (`NEXT_PUBLIC_` or `VITE_`) - bundled into client code - **Backend vars**: Set via CLI for security - accessible only in actions via `process.env` - **Separate deployments**: Dev and prod have separate environment variables @@ -197,9 +214,10 @@ VITE_CONVEX_URL=https://your-deployment.convex.cloud #### Next.js App Router -**VERIFY at:** https://docs.convex.dev/quickstart/nextjs +**VERIFY at:** **app/ConvexClientProvider.tsx:** + ```typescript // ConvexClientProvider MUST be a client component "use client"; @@ -216,11 +234,13 @@ export function ConvexClientProvider({ children }: { children: ReactNode }) { ``` **Technical Explanation:** + - **"use client" required**: React Server Components can't use context providers - **ConvexReactClient**: Manages WebSocket connection for real-time updates - **Singleton pattern**: Create client once outside component to prevent reconnections **app/layout.tsx:** + ```typescript // VERIFY at: https://docs.convex.dev/quickstart/nextjs import { ConvexClientProvider } from "./ConvexClientProvider"; @@ -237,6 +257,7 @@ export default function RootLayout({ children }: { children: ReactNode }) { ``` **Server-Side Rendering (SSR) with App Router:** + ```typescript // VERIFY at: https://docs.convex.dev/client/nextjs/app-router import { preloadQuery } from "convex/nextjs"; @@ -254,9 +275,10 @@ export default async function ServerComponent() { #### Next.js Pages Router -**VERIFY at:** https://docs.convex.dev/client/nextjs/pages-router/quickstart +**VERIFY at:** **pages/_app.tsx:** + ```typescript import { ConvexProvider, ConvexReactClient } from "convex/react"; import type { AppProps } from "next/app"; @@ -276,11 +298,13 @@ export default MyApp; ``` **Technical Explanation:** + - **_app.tsx pattern**: Wraps all pages with ConvexProvider - **Client-side only**: Pages Router has limited SSR support for Convex - **API routes**: Use for server-side Convex operations **API Route Example (pages/api/tasks.ts):** + ```typescript // VERIFY at: https://docs.convex.dev/client/nextjs/pages-router/server-rendering import { ConvexHttpClient } from "convex/browser"; @@ -299,9 +323,10 @@ export default async function handler(req: NextApiRequest, res: NextApiResponse) #### React (Vite) -**VERIFY at:** https://docs.convex.dev/quickstart/react +**VERIFY at:** **src/main.tsx:** + ```typescript import React from "react"; import ReactDOM from "react-dom/client"; @@ -321,6 +346,7 @@ ReactDOM.createRoot(document.getElementById("root")!).render( ``` **Technical Explanation:** + - **import.meta.env**: Vite's environment variable syntax (NOT process.env) - **VITE_ prefix**: Required for Vite to include variable in build - **Client-side only**: Pure React apps are client-rendered @@ -331,9 +357,10 @@ ReactDOM.createRoot(document.getElementById("root")!).render( ### Schema Definition -**VERIFY at:** https://docs.convex.dev/database/schemas +**VERIFY at:** **convex/schema.ts:** + ```typescript import { defineSchema, defineTable } from "convex/server"; import { v } from "convex/values"; @@ -362,6 +389,7 @@ export default defineSchema({ ``` **Technical Explanation:** + - **defineSchema**: Creates schema with type generation - **defineTable**: Defines table structure with validators - **Validators**: `v.string()`, `v.number()`, `v.boolean()`, `v.id("tableName")`, `v.optional()`, etc. @@ -373,9 +401,10 @@ export default defineSchema({ ### Queries (Reading Data) -**VERIFY at:** https://docs.convex.dev/database/reading-data +**VERIFY at:** **convex/tasks.ts:** + ```typescript import { query } from "./_generated/server"; import { v } from "convex/values"; @@ -415,6 +444,7 @@ export const getPaginated = query({ ``` **Query Methods:** + - `.collect()` - Returns all matching documents as array - `.take(n)` - Returns first n documents - `.first()` - Returns first document or null @@ -422,6 +452,7 @@ export const getPaginated = query({ - `.paginate(opts)` - Returns paginated results with cursor **Technical Explanation:** + - **Deterministic requirement**: Queries MUST return same result for same inputs - **❌ Cannot use**: `Math.random()`, `Date.now()`, external API calls - **Automatic caching**: Convex caches query results for performance @@ -432,9 +463,10 @@ export const getPaginated = query({ ### Mutations (Writing Data) -**VERIFY at:** https://docs.convex.dev/database/writing-data +**VERIFY at:** **convex/tasks.ts:** + ```typescript import { mutation } from "./_generated/server"; import { v } from "convex/values"; @@ -499,6 +531,7 @@ export const remove = mutation({ ``` **Technical Explanation:** + - **Automatic transactions**: "The entire mutation function is automatically a single transaction" - **Atomicity**: Multiple db operations in one mutation execute as single atomic unit - **No BEGIN/COMMIT**: Convex handles transaction management automatically @@ -510,9 +543,10 @@ export const remove = mutation({ ### Actions (External API Calls) -**VERIFY at:** https://docs.convex.dev/functions/actions +**VERIFY at:** **convex/actions.ts:** + ```typescript import { action } from "./_generated/server"; import { v } from "convex/values"; @@ -561,6 +595,7 @@ export const sendEmail = action({ ``` **Technical Explanation:** + - **Non-deterministic operations**: Actions can use `Date.now()`, `Math.random()`, external APIs - **No direct database access**: Actions cannot use `ctx.db` directly - **Can call queries/mutations**: Use `ctx.runQuery()` and `ctx.runMutation()` @@ -573,25 +608,28 @@ export const sendEmail = action({ ### Clerk Integration (Recommended) -**VERIFY at:** https://docs.convex.dev/auth/clerk +**VERIFY at:** **Setup Steps:** 1. **Install Clerk:** + ```bash npm install @clerk/nextjs # For Next.js # OR npm install @clerk/clerk-react # For React ``` -2. **Configure Clerk in Convex Dashboard:** -- Navigate to Settings → Authentication -- Add Clerk as provider -- Copy Issuer URL from Clerk dashboard +1. **Configure Clerk in Convex Dashboard:** + + - Navigate to Settings → Authentication + - Add Clerk as provider + - Copy Issuer URL from Clerk dashboard -3. **Add Clerk to Next.js App:** +1. **Add Clerk to Next.js App:** **app/layout.tsx:** + ```typescript // VERIFY at: https://docs.convex.dev/auth/clerk import { ClerkProvider } from "@clerk/nextjs"; @@ -611,6 +649,7 @@ export default function RootLayout({ children }: { children: ReactNode }) { ``` **app/ConvexClientProvider.tsx:** + ```typescript "use client"; @@ -629,9 +668,10 @@ export function ConvexClientProvider({ children }: { children: ReactNode }) { } ``` -4. **Access Auth in Convex Functions:** +1. **Access Auth in Convex Functions:** **convex/tasks.ts:** + ```typescript import { query, mutation } from "./_generated/server"; import { v } from "convex/values"; @@ -662,6 +702,7 @@ export const getMy = query({ ``` **Technical Explanation:** + - **JWT verification**: Convex automatically verifies Clerk JWT tokens - **ctx.auth.getUserIdentity()**: Returns user info or null if not authenticated - **identity.subject**: Clerk user ID (use as userId in your database) @@ -673,9 +714,10 @@ export const getMy = query({ ### Next.js App Router Hooks -**VERIFY at:** https://docs.convex.dev/client/nextjs/app-router +**VERIFY at:** **Client Component (app/TaskList.tsx):** + ```typescript "use client"; @@ -711,6 +753,7 @@ export function TaskList() { ``` **Server Component with preloadQuery:** + ```typescript // VERIFY at: https://docs.convex.dev/client/nextjs/app-router import { preloadQuery } from "convex/nextjs"; @@ -729,9 +772,10 @@ export default async function TasksPage() { ### Advanced Server-Side Rendering (SSR) -**VERIFY at:** https://docs.convex.dev/client/react/nextjs/server-rendering +**VERIFY at:** **Using fetchQuery for Server Components (Non-Reactive):** + ```typescript import { fetchQuery } from "convex/nextjs"; import { api } from "@/convex/_generated/api"; @@ -752,6 +796,7 @@ export default async function StaticTasksPage() { ``` **Using fetchMutation in Server Actions:** + ```typescript import { fetchMutation } from "convex/nextjs"; import { api } from "@/convex/_generated/api"; @@ -774,6 +819,7 @@ export default function TaskForm() { ``` **SSR with Authentication:** + ```typescript import { preloadQuery } from "convex/nextjs"; import { auth } from "@clerk/nextjs/server"; @@ -796,6 +842,7 @@ export default async function AuthenticatedPage() { ``` **Technical Notes:** + - `preloadQuery`: Preloads data, client component becomes reactive - `fetchQuery`: One-time fetch, no reactivity (pure server component) - `fetchMutation`: Execute mutations from Server Actions or Route Handlers @@ -805,9 +852,10 @@ export default async function AuthenticatedPage() { ### React (Vite) Hooks -**VERIFY at:** https://docs.convex.dev/quickstart/react +**VERIFY at:** **src/App.tsx:** + ```typescript import { useQuery, useMutation, useAction } from "convex/react"; import { api } from "../convex/_generated/api"; @@ -851,6 +899,7 @@ export function App() { ``` **Conditional Queries:** + ```typescript // Skip query when condition not met const userId = useAuth()?.userId; @@ -864,11 +913,12 @@ const userTasks = useQuery( ### Optimistic Updates -**VERIFY at:** https://docs.convex.dev/client/react/optimistic-updates +**VERIFY at:** Optimistic updates provide instant UI feedback before server confirmation. **Basic Example:** + ```typescript "use client"; import { useMutation, useQuery } from "convex/react"; @@ -897,6 +947,7 @@ export function Counter() { ``` **Chat Message Example:** + ```typescript const sendMessage = useMutation(api.messages.send).withOptimisticUpdate( (localStore, args) => { @@ -923,6 +974,7 @@ const sendMessage = useMutation(api.messages.send).withOptimisticUpdate( ``` **Best Practices:** + - Always create new objects (don't mutate existing) - Check if query is loaded before updating - Optimistic data may differ from server response (automatically corrected) @@ -935,15 +987,17 @@ const sendMessage = useMutation(api.messages.send).withOptimisticUpdate( ### Deployment Architecture **Hybrid Deployment Pattern:** + - **Frontend**: Deployed on Cloudflare Pages (global edge network) - **Backend**: Hosted on Convex (managed functions + database) - **Benefits**: Geographic distribution, automatic scaling, zero DevOps -**VERIFY at:** https://developers.cloudflare.com/pages/framework-guides/nextjs/ +**VERIFY at:** ### Setup Steps **1. Create Cloudflare Pages Project:** + - Dashboard → Workers & Pages → Create → Pages → Connect to Git - Select GitHub repository - Configure build settings: @@ -952,12 +1006,14 @@ const sendMessage = useMutation(api.messages.send).withOptimisticUpdate( - **Build output directory**: `.next` (Next.js) or `dist` (Vite) **2. Set Environment Variables:** + - Pages dashboard → Settings → Environment variables - Add `NEXT_PUBLIC_CONVEX_URL` with your Convex deployment URL - Get from: `npx convex dashboard` → Settings → Deployment URL - - Example: `https://happy-animal-123.convex.cloud` + - Example: ` **3. Deploy:** + - Push to GitHub → Cloudflare automatically builds and deploys - Preview deployments for all branches - Production deployment on main branch @@ -965,16 +1021,19 @@ const sendMessage = useMutation(api.messages.send).withOptimisticUpdate( ### Environment Variable Management **Local (.env.local):** + ```bash NEXT_PUBLIC_CONVEX_URL=https://your-dev-deployment.convex.cloud ``` **Production (Cloudflare Pages Dashboard):** + ```bash NEXT_PUBLIC_CONVEX_URL=https://your-prod-deployment.convex.cloud ``` **Convex Backend Variables:** + ```bash # Dev environment npx convex env set STRIPE_SECRET_KEY sk_test_... @@ -984,6 +1043,7 @@ npx convex env set STRIPE_SECRET_KEY sk_live_... --prod ``` **Technical Explanation:** + - **Build-time variables**: `NEXT_PUBLIC_*` bundled during build on Cloudflare - **Runtime variables**: Cloudflare Pages Functions can access runtime environment - **Separate Convex deployments**: Use different Convex URLs for dev/staging/prod @@ -995,7 +1055,7 @@ npx convex env set STRIPE_SECRET_KEY sk_live_... --prod **Common Issues and Solutions:** | Issue | Cause | Solution | -|-------|-------|----------| +| ------- | ------- | ---------- | | "Convex URL not found" | Missing env var | Add `NEXT_PUBLIC_CONVEX_URL` in Pages dashboard | | Build fails on Cloudflare | Node version | Set `NODE_VERSION=18` in env vars | | Functions timeout | Edge runtime limits | Use Convex for heavy processing, not Pages Functions | @@ -1003,6 +1063,7 @@ npx convex env set STRIPE_SECRET_KEY sk_live_... --prod | WebSocket connection fails | Proxy/firewall | Ensure `*.convex.cloud` is allowed | **Environment-Specific Deployment:** + ```bash # Create separate Convex projects for each environment # Production @@ -1013,11 +1074,13 @@ npx convex dev --project my-app-staging ``` **DNS & Custom Domains:** + - Cloudflare Pages handles frontend domains automatically - Convex deployment URL remains `*.convex.cloud` - No custom domain needed for Convex (frontend proxies requests) **Build Optimization:** + ```bash # Cloudflare Pages Build Settings Build command: npm run build @@ -1026,6 +1089,7 @@ Root directory: / (or your app subdirectory) ``` **Debugging Production Issues:** + ```bash # Stream logs from production npx convex logs --prod @@ -1035,6 +1099,7 @@ npx convex dashboard ``` **Important Notes:** + - Cloudflare Pages has 100ms CPU time limit for edge functions - Use Convex actions for heavy computation (30s limit on paid plans) - Real-time features (WebSocket) work out-of-box with Convex @@ -1044,7 +1109,7 @@ npx convex dashboard ## Development Commands -**VERIFY at:** https://docs.convex.dev/cli +**VERIFY at:** ### CLI Setup & Configuration @@ -1207,6 +1272,7 @@ npx convex env unset STRIPE_SECRET_KEY ``` **Technical Explanation:** + - Environment variables accessible in **actions only** (via `process.env`) - Separate dev/prod environments - Secrets never exposed in client code @@ -1252,7 +1318,7 @@ npx convex data ## TypeScript Patterns -**VERIFY at:** https://docs.convex.dev/typescript +**VERIFY at:** ### Generated Types @@ -1272,6 +1338,7 @@ const taskId: Id<"tasks"> = "j57a8c9d0e1f2g3h4i5j6k7l"; ``` **Technical Explanation:** + - **convex/_generated/api**: Exports typed function references - **convex/_generated/dataModel**: Exports `Doc<>`, `Id<>` types based on schema - **Automatic updates**: Types regenerate when schema or functions change @@ -1302,18 +1369,20 @@ await createTask({ ## Testing -**VERIFY at:** https://docs.convex.dev/testing +**VERIFY at:** ### convex-test Setup The `convex-test` library provides a mocked Convex backend for unit testing with Vitest. **Installation:** + ```bash npm install --save-dev convex-test vitest @edge-runtime/vm ``` **vitest.config.ts:** + ```typescript import { defineConfig } from "vitest/config"; @@ -1326,6 +1395,7 @@ export default defineConfig({ ``` **package.json scripts:** + ```json { "scripts": { @@ -1339,6 +1409,7 @@ export default defineConfig({ ### Writing Tests **convex/messages.test.ts:** + ```typescript import { convexTest } from "convex-test"; import { expect, test } from "vitest"; @@ -1436,11 +1507,12 @@ test("action with external API", async () => { ## CI/CD & Deployment -**VERIFY at:** https://docs.convex.dev/production/hosting +**VERIFY at:** ### GitHub Actions Workflow **.github/workflows/test.yml:** + ```yaml name: Test and Deploy @@ -1484,11 +1556,12 @@ jobs: ### Preview Deployments -**VERIFY at:** https://docs.convex.dev/production/hosting/preview-deployments +**VERIFY at:** Preview deployments create isolated Convex backends for each PR. **.github/workflows/preview.yml:** + ```yaml name: Preview Deployment @@ -1530,6 +1603,7 @@ jobs: ### Environment Setup **Getting CONVEX_DEPLOY_KEY:** + ```bash # Generate deploy key for CI/CD npx convex deploy-key create @@ -1541,6 +1615,7 @@ npx convex deploy-key create ``` **Preview Deployment Notes:** + - Auto-deleted after 5 days (14 days on Professional) - Each PR gets isolated database - Use `--preview-run` to seed test data @@ -1552,7 +1627,7 @@ npx convex deploy-key create ### Relationship Modeling -**VERIFY at:** https://docs.convex.dev/database/document-ids#relationships +**VERIFY at:** **No JOIN syntax - fetch related documents in parallel:** @@ -1579,6 +1654,7 @@ export const getTasksWithUsers = query({ ``` **Technical Explanation:** + - **v.id("tableName")**: Creates typed reference to another table - **No JOINs**: Fetch related documents separately, combine in JavaScript - **Denormalization trade-off**: Sometimes duplicate data for performance @@ -1587,9 +1663,10 @@ export const getTasksWithUsers = query({ ### Pagination with usePaginatedQuery -**VERIFY at:** https://docs.convex.dev/database/pagination +**VERIFY at:** **Client Component:** + ```typescript import { usePaginatedQuery } from "convex/react"; import { api } from "@/convex/_generated/api"; @@ -1614,6 +1691,7 @@ export function InfiniteTaskList() { ``` **Technical Explanation:** + - **Cursor-based pagination**: More efficient than OFFSET for large datasets - **usePaginatedQuery**: Manages pagination state automatically - **CanLoadMore status**: Indicates if more items available @@ -1622,9 +1700,10 @@ export function InfiniteTaskList() { ### HTTP Actions (Webhooks) -**VERIFY at:** https://docs.convex.dev/functions/http-actions +**VERIFY at:** **convex/http.ts:** + ```typescript import { httpRouter } from "convex/server"; import { httpAction } from "./_generated/server"; @@ -1670,7 +1749,8 @@ export default http; ``` **Technical Explanation:** -- **HTTP endpoints**: Accessible at `https://your-deployment.convex.site/stripe/webhook` + +- **HTTP endpoints**: Accessible at ` - **Use cases**: Stripe webhooks, external API integrations, custom REST endpoints - **Cannot access ctx.db directly**: Must call queries/mutations with `ctx.run*()` @@ -1678,9 +1758,10 @@ export default http; ### Scheduled Functions (Cron Jobs) -**VERIFY at:** https://docs.convex.dev/scheduling/scheduled-functions +**VERIFY at:** **convex/crons.ts:** + ```typescript import { cronJobs } from "convex/server"; import { internal } from "./_generated/api"; @@ -1712,6 +1793,7 @@ export default crons; ``` **Technical Explanation:** + - **Cron syntax**: Standard cron expressions - **Internal functions**: Use `internal.*` to prevent public access - **Use cases**: Daily aggregations, cleanup tasks, periodic syncs @@ -1720,9 +1802,10 @@ export default crons; ### Error Handling -**VERIFY at:** https://docs.convex.dev/functions/error-handling +**VERIFY at:** **convex/tasks.ts:** + ```typescript import { ConvexError } from "convex/values"; import { mutation } from "./_generated/server"; @@ -1759,6 +1842,7 @@ export const create = mutation({ ``` **Client Error Handling:** + ```typescript const createTask = useMutation(api.tasks.create); @@ -1773,6 +1857,7 @@ try { ``` **Technical Explanation:** + - **ConvexError**: Type-safe error propagation to client - **Automatic retry**: Transient failures (network issues) automatically retried - **Error typing**: Client receives properly typed error data @@ -1781,9 +1866,10 @@ try { ### Validation Patterns -**VERIFY at:** https://docs.convex.dev/database/schemas#validators +**VERIFY at:** **Custom Validators:** + ```typescript import { v } from "convex/values"; @@ -1807,6 +1893,7 @@ export const createUser = mutation({ ``` **Technical Explanation:** + - **Runtime validation**: Arguments validated before function executes - **Schema-level validation**: Enforced on write operations - **Type safety**: Validators generate TypeScript types @@ -1815,9 +1902,10 @@ export const createUser = mutation({ ### File Storage -**VERIFY at:** https://docs.convex.dev/file-storage +**VERIFY at:** **File Upload Action:** + ```typescript import { action } from "./_generated/server"; import { v } from "convex/values"; @@ -1843,6 +1931,7 @@ export const saveFile = action({ ``` **Client Upload:** + ```typescript const generateUploadUrl = useMutation(api.files.generateUploadUrl); const saveFile = useMutation(api.files.saveFile); @@ -1869,13 +1958,14 @@ const handleUpload = async (file: File) => { ## Full Text Search -**VERIFY at:** https://docs.convex.dev/text-search +**VERIFY at:** ### Defining Search Indexes Search indexes enable full-text search over string fields using BM25 scoring. **convex/schema.ts:** + ```typescript import { defineSchema, defineTable } from "convex/server"; import { v } from "convex/values"; @@ -1905,6 +1995,7 @@ export default defineSchema({ ### Running Search Queries **convex/messages.ts:** + ```typescript import { query } from "./_generated/server"; import { v } from "convex/values"; @@ -1944,6 +2035,7 @@ export const searchRecent = query({ ``` **Search Constraints:** + - Up to 16 search terms per query - Up to 8 filter expressions - Maximum 1024 documents scanned per query @@ -1954,13 +2046,14 @@ export const searchRecent = query({ ## Vector Search -**VERIFY at:** https://docs.convex.dev/vector-search +**VERIFY at:** ### Defining Vector Indexes Vector indexes enable semantic similarity search using embeddings. **convex/schema.ts:** + ```typescript import { defineSchema, defineTable } from "convex/server"; import { v } from "convex/values"; @@ -1982,6 +2075,7 @@ export default defineSchema({ ### Storing Embeddings **convex/documents.ts:** + ```typescript import { action, internalMutation } from "./_generated/server"; import { v } from "convex/values"; @@ -2033,6 +2127,7 @@ export const insertDocument = internalMutation({ ### Running Vector Searches **convex/search.ts:** + ```typescript import { action, internalQuery } from "./_generated/server"; import { v } from "convex/values"; @@ -2090,6 +2185,7 @@ export const getByIds = internalQuery({ ``` **Vector Search Constraints:** + - Up to 4 vector indexes per table - Maximum 256 results per query - Dimensions must match exactly (e.g., 1536 for OpenAI) @@ -2100,13 +2196,14 @@ export const getByIds = internalQuery({ ## Internal Functions -**VERIFY at:** https://docs.convex.dev/functions/internal-functions +**VERIFY at:** ### What Are Internal Functions? Internal functions can only be called by other Convex functions (not from clients). They reduce your app's attack surface. **convex/internal.ts:** + ```typescript import { internalQuery, internalMutation, internalAction } from "./_generated/server"; import { v } from "convex/values"; @@ -2167,6 +2264,7 @@ export const handleWebhook = action({ ``` **When to Use Internal Functions:** + - Privileged operations (admin-only actions) - Operations called from scheduled functions/crons - Business logic that should bypass client validation @@ -2176,13 +2274,14 @@ export const handleWebhook = action({ ## Components -**VERIFY at:** https://docs.convex.dev/components +**VERIFY at:** ### What Are Components? **Convex Components** are self-contained backend modules that package code, schemas, and persistent data into isolated sandboxes. They are "like mini self-contained Convex backends" that can be safely added to any Convex app. **Key Characteristics:** + - **Data Isolation**: Components cannot read your app's tables or call your functions unless explicitly passed in - **Own Database Tables**: Each component maintains its own isolated database tables - **Own File Storage**: Separate file storage independent from the main application @@ -2193,7 +2292,7 @@ export const handleWebhook = action({ **Why Use Components Instead of npm Packages?** | Feature | npm Package | Convex Component | -|---------|-------------|------------------| +| --------- | ------------- | ------------------ | | State Persistence | In-memory (lost on restart) | Database-backed (persistent) | | Data Access | Direct database access | Explicit API boundaries | | Transactional Guarantees | None (distributed inconsistencies) | Atomic commits across boundaries | @@ -2214,6 +2313,7 @@ npm install @convex-dev/component-name ``` **Common Components:** + ```bash npm install @convex-dev/agent # AI agents with threads/messages npm install @convex-dev/rag # RAG (Retrieval-Augmented Generation) @@ -2243,6 +2343,7 @@ export default app; ``` **Technical Explanation:** + - `defineApp()` creates the app configuration - `use()` mounts components with unique names - Each component instance has separate tables/functions @@ -2265,6 +2366,7 @@ This generates the `components` object in your API for accessing component funct Components are accessed through `components` object in generated API: **convex/myFunctions.ts:** + ```typescript import { query, mutation, action } from "./_generated/server"; import { components } from "./_generated/api"; @@ -2306,6 +2408,7 @@ export const processWithAI = action({ ``` **Important Rules:** + - Queries can only call component **queries** (maintains reactivity) - Mutations can call component **mutations** (maintains transactions) - Actions can call component **actions** @@ -2361,6 +2464,7 @@ export const createWithFallback = mutation({ ``` **Technical Explanation:** + - All writes in a mutation commit together by default - If parent mutation throws, all writes (app + component) rollback - If component mutation throws but caller catches it, only component writes rollback @@ -2377,6 +2481,7 @@ export const createWithFallback = mutation({ 3. Filter logs by component: `data.function.component_path` **Example Log Filtering:** + ```bash # View logs from specific component npx convex logs --filter 'data.function.component_path == "agent"' @@ -2409,7 +2514,7 @@ test("component integration", async () => { **Directory Structure:** -``` +```text my-component/ ├── convex.config.ts # Component configuration ├── schema.ts # Component-specific schema @@ -2419,6 +2524,7 @@ my-component/ ``` **convex.config.ts:** + ```typescript import { defineComponent } from "convex/server"; @@ -2426,6 +2532,7 @@ export default defineComponent("myComponent"); ``` **schema.ts:** + ```typescript import { defineSchema, defineTable } from "convex/server"; import { v } from "convex/values"; @@ -2439,6 +2546,7 @@ export default defineSchema({ ``` **functions.ts (Public API):** + ```typescript import { query, mutation } from "./_generated/server"; import { v } from "convex/values"; @@ -2463,6 +2571,7 @@ export const listItems = query({ ``` **_internal/helpers.ts (Internal - Not Exposed):** + ```typescript import { internalMutation } from "../_generated/server"; import { v } from "convex/values"; @@ -2479,7 +2588,7 @@ export const cleanup = internalMutation({ **Key Constraints for Component Authors:** | Constraint | Reason | -|------------|--------| +| ------------ | -------- | | No `ctx.auth` | Authentication happens in app, not component | | All `Id<"table">` become strings at boundary | ID types don't cross boundaries | | No `process.env` access | Components can't access environment variables | @@ -2516,9 +2625,10 @@ npm publish ### Popular Components -**Browse All Components:** https://convex.dev/components +**Browse All Components:** **Common Use Cases:** + - `@convex-dev/agent` - AI agents with threads, messages, tool calls - `@convex-dev/rag` - RAG (Retrieval-Augmented Generation) for semantic search - `@convex-dev/rate-limiter` - API rate limiting and usage tracking @@ -2533,6 +2643,7 @@ npm install @convex-dev/rate-limiter ``` **convex/convex.config.ts:** + ```typescript import { defineApp } from "convex/server"; import rateLimiter from "@convex-dev/rate-limiter/convex.config"; @@ -2543,6 +2654,7 @@ export default app; ``` **convex/rateLimit.ts:** + ```typescript import { components } from "./_generated/api"; import { RateLimiter } from "@convex-dev/rate-limiter"; @@ -2557,6 +2669,7 @@ export const consumeApiToken = rateLimiter.consume("apiRequests"); ``` **Usage in mutation:** + ```typescript export const createPost = mutation({ args: { content: v.string() }, @@ -2585,6 +2698,7 @@ npm install @convex-dev/sharded-counter ``` **For high-frequency counters that would cause OCC conflicts:** + ```typescript import { components } from "./_generated/api"; import { ShardedCounter } from "@convex-dev/sharded-counter"; @@ -2617,13 +2731,14 @@ Components enable composability for complex features without building from scrat ## AI & Agents -**VERIFY at:** https://docs.convex.dev/agents +**VERIFY at:** ### Agent Component Overview The **Convex Agent component** is a core building block for constructing AI-powered applications with persistent conversation history, tool calls, and RAG integration. **Key Capabilities:** + - Persistent conversation threads with automatic history management - Real-time updates across all connected clients (reactivity) - Tool calling for external function invocation @@ -2633,6 +2748,7 @@ The **Convex Agent component** is a core building block for constructing AI-powe - Rate limiting and usage tracking **Use Cases:** + - AI chatbots with memory - Multi-agent systems - Customer support agents @@ -2652,6 +2768,7 @@ npm install @convex-dev/rag ``` **Technical Explanation:** + - Agent component is a Convex component (reusable pattern) - Manages threads, messages, and agent interactions - Integrates seamlessly with Convex actions and queries @@ -2660,9 +2777,10 @@ npm install @convex-dev/rag ### Threads and Messages -**VERIFY at:** https://docs.convex.dev/agents +**VERIFY at:** **convex/agents.ts:** + ```typescript import { agent } from "@convex-dev/agent"; import { OpenAI } from "openai"; @@ -2714,6 +2832,7 @@ export const getMessages = query({ ``` **Technical Explanation:** + - **Threads**: Persistent conversation containers - **Messages**: Individual messages with role (user/assistant/system) - **Automatic context**: Previous messages automatically included in LLM calls @@ -2724,11 +2843,12 @@ export const getMessages = query({ ### Tool Calls -**VERIFY at:** https://docs.convex.dev/agents +**VERIFY at:** Enable agents to call external functions as part of their reasoning process. **Example: Agent with Weather Tool** + ```typescript import { agent, tool } from "@convex-dev/agent"; import { OpenAI } from "openai"; @@ -2779,6 +2899,7 @@ export const askWeather = action({ ``` **Technical Explanation:** + - **Tool definition**: Name, description, parameters, handler function - **Automatic invocation**: LLM decides when to use tools - **Multi-turn**: After tool call, LLM can generate final response @@ -2788,13 +2909,14 @@ export const askWeather = action({ ### RAG Integration -**VERIFY at:** https://docs.convex.dev/agents/rag +**VERIFY at:** Integrate Retrieval-Augmented Generation for context-aware responses. **Two Approaches:** **1. Upfront Context Injection** (search before LLM call) + ```typescript import { rag } from "@convex-dev/rag"; import { agent } from "@convex-dev/agent"; @@ -2830,6 +2952,7 @@ export const chatWithDocs = action({ ``` **2. RAG as Tool Calls** (LLM decides when to search) + ```typescript // Define RAG as a tool const searchDocuments = tool({ @@ -2857,6 +2980,7 @@ const ragAgent = agent({ ``` **Technical Explanation:** + - **Upfront approach**: Simpler, always includes context - **Tool approach**: More flexible, LLM decides when to search - **Hybrid vector/text search**: Combines semantic and keyword matching @@ -2866,7 +2990,7 @@ const ragAgent = agent({ ### Streaming Responses -**VERIFY at:** https://docs.convex.dev/agents +**VERIFY at:** Stream agent responses for real-time UI updates. @@ -2891,6 +3015,7 @@ export const streamChat = action({ ``` **Client Usage:** + ```typescript const streamChat = useAction(api.agents.streamChat); @@ -2905,6 +3030,7 @@ const handleSend = async (message: string) => { ``` **Technical Explanation:** + - **Streaming API**: Returns async iterable - **Real-time UI**: Update UI incrementally as text generates - **Better UX**: Users see immediate progress vs waiting for full response @@ -2913,7 +3039,7 @@ const handleSend = async (message: string) => { ### Rate Limiting & Usage Tracking -**VERIFY at:** https://docs.convex.dev/agents +**VERIFY at:** Track and limit agent usage per user or team. @@ -2956,6 +3082,7 @@ export const chatWithLimit = action({ ``` **Technical Explanation:** + - **Rate limiting**: Prevent abuse, comply with LLM provider limits - **Usage tracking**: Bill per user/team based on token consumption - **Cost control**: Monitor and cap spending per user @@ -2964,7 +3091,7 @@ export const chatWithLimit = action({ ### Multi-Agent Workflows -**VERIFY at:** https://docs.convex.dev/agents/workflows +**VERIFY at:** Coordinate multiple agents for complex tasks. @@ -3015,6 +3142,7 @@ export const createArticle = action({ ``` **Technical Explanation:** + - **Agent specialization**: Different agents for different tasks - **Sequential workflows**: Output of one agent feeds into another - **Durable execution**: Workflows persist across interruptions @@ -3026,9 +3154,10 @@ export const createArticle = action({ ### Query Functions Must Be Deterministic -**VERIFY at:** https://docs.convex.dev/functions/query-functions +**VERIFY at:** **❌ DON'T DO THIS:** + ```typescript export const getBad = query({ handler: async (ctx) => { @@ -3043,6 +3172,7 @@ export const getBad = query({ ``` **✅ DO THIS:** + ```typescript // Queries: Only database reads export const getGood = query({ @@ -3063,6 +3193,7 @@ export const doNonDeterministic = action({ ``` **Why:** + - Queries are cached and must return same result for same inputs - Enables real-time reactivity and performance optimizations @@ -3070,9 +3201,10 @@ export const doNonDeterministic = action({ ### Index Usage Requirements -**VERIFY at:** https://docs.convex.dev/database/indexes#querying-indexes +**VERIFY at:** **❌ This will scan entire table (slow):** + ```typescript // No index usage - scans all documents const tasks = await ctx.db @@ -3082,6 +3214,7 @@ const tasks = await ctx.db ``` **✅ Use indexes explicitly:** + ```typescript // Efficiently uses "by_user" index const tasks = await ctx.db @@ -3093,6 +3226,7 @@ const tasks = await ctx.db **Critical:** "You must explicitly use the withIndex() syntax to ensure your database uses the index" **Technical Explanation:** + - Convex doesn't auto-select indexes like SQL databases - Performance impact: Without indexes, queries scan entire table - Define indexes in schema, use with `.withIndex()` in queries @@ -3101,13 +3235,15 @@ const tasks = await ctx.db ### Local vs Production Environments -**VERIFY at:** https://docs.convex.dev/production/hosting/hosting-and-running +**VERIFY at:** **Separate Deployments:** + - `npx convex dev` → Creates/uses **dev deployment** - `npx convex deploy --prod` → Deploys to **production** **Environment Variables:** + ```bash # Dev environment npx convex env set STRIPE_SECRET_KEY sk_test_... @@ -3117,6 +3253,7 @@ npx convex env set STRIPE_SECRET_KEY sk_live_... --prod ``` **Frontend URLs:** + ```bash # .env.local (development) NEXT_PUBLIC_CONVEX_URL=https://dev-deployment.convex.cloud @@ -3126,6 +3263,7 @@ NEXT_PUBLIC_CONVEX_URL=https://prod-deployment.convex.cloud ``` **Best Practice:** + - Always develop against dev deployment - Only deploy to production after thorough testing @@ -3133,7 +3271,7 @@ NEXT_PUBLIC_CONVEX_URL=https://prod-deployment.convex.cloud ### Optimistic Concurrency Control (OCC) & Write Conflicts -**VERIFY at:** https://docs.convex.dev/database/advanced/occ +**VERIFY at:** **What is OCC?** @@ -3154,6 +3292,7 @@ await ctx.db.patch(aliceId, { balance: alice.balance - 5 }); ``` **Technical Explanation:** + - At commit time, Convex checks if all read records are still at their original versions - If any record changed, the mutation **fails and automatically retries** - Similar to Git: "Cannot push because HEAD is out of date → rebase and try again" @@ -3163,7 +3302,7 @@ await ctx.db.patch(aliceId, { balance: alice.balance - 5 }); When retries exceed threshold (high contention), you'll see: -``` +```text OccRetryThresholdExceeded: Documents read from or written to the table 'counters' changed while this mutation was being run and on every subsequent retry. @@ -3189,11 +3328,12 @@ export const incrementCounter = mutation({ ``` **✅ FIX: Use Sharded Counter component** + ```bash npm install @convex-dev/sharded-counter ``` -2. **Broad data dependencies (reading entire tables):** +1. **Broad data dependencies (reading entire tables):** ```typescript // ❌ CONFLICT PRONE: Reads ALL tasks @@ -3209,6 +3349,7 @@ export const addTask = mutation({ ``` **✅ FIX: Read only necessary data with indexes** + ```typescript export const addTask = mutation({ args: { userId: v.id("users"), text: v.string() }, @@ -3231,7 +3372,7 @@ export const addTask = mutation({ **Best Practices to Avoid Conflicts:** | Issue | Solution | -|-------|----------| +| ------- | ---------- | | Hot document (many writes to same record) | Shard data across multiple documents | | Reading entire tables | Use indexed queries with selective range expressions | | Unexpected repeated calls | Avoid mutations in loops, debounce client calls | @@ -3242,6 +3383,7 @@ export const addTask = mutation({ Write mutations "as if they will always succeed, and always be guaranteed to be atomic." Convex handles conflicts transparently through automatic retries, providing true serializability without developer intervention. **When to Use Components:** + - **Sharded Counter**: Distribute high-frequency writes across multiple documents - **Workpool**: Prioritize critical tasks through separate queues @@ -3249,13 +3391,14 @@ Write mutations "as if they will always succeed, and always be guaranteed to be ## Performance & Monitoring -**VERIFY at:** https://docs.convex.dev/production/monitoring +**VERIFY at:** ### Convex Dashboard Features Access at: `npx convex dashboard` **Monitoring Capabilities:** + - **Real-time function logs**: View all query/mutation/action executions - **Query performance metrics**: Execution time, call frequency - **Database size and usage**: Track storage and document counts @@ -3264,6 +3407,7 @@ Access at: `npx convex dashboard` ### Performance Best Practices **Index Optimization:** + ```typescript // Define indexes for frequently queried fields export default defineSchema({ @@ -3279,6 +3423,7 @@ export default defineSchema({ ``` **Pagination for Large Datasets:** + ```typescript // Don't fetch all documents at once const allTasks = await ctx.db.query("tasks").collect(); // ❌ Slow @@ -3288,6 +3433,7 @@ const tasks = await ctx.db.query("tasks").take(100); // ✅ Faster ``` **Batch Operations:** + ```typescript // Fetch related documents in parallel const tasks = await ctx.db.query("tasks").collect(); @@ -3300,16 +3446,18 @@ const users = await Promise.all( ### Log Streams & Exception Reporting -**VERIFY at:** https://docs.convex.dev/production/integrations/log-streams +**VERIFY at:** Stream logs to external services for monitoring and alerting. Requires Convex Pro plan. **Available Destinations:** + - **Axiom** - Log analytics with automatic dashboard creation - **Datadog** - APM and log management - **Webhook** - Custom HTTP endpoints (any service) **Setup via Dashboard:** + 1. Go to Convex Dashboard → Settings → Integrations 2. Select destination (Axiom, Datadog, or Webhook) 3. Configure credentials and options @@ -3318,7 +3466,7 @@ Stream logs to external services for monitoring and alerting. Requires Convex Pr **Log Event Types:** | Event Type | Description | -|------------|-------------| +| ------------ | ------------- | | `console` | Function console.log/warn/error output | | `function_execution` | Execution metrics (duration, status, errors) | | `audit_log` | Deployment changes and admin actions | @@ -3326,6 +3474,7 @@ Stream logs to external services for monitoring and alerting. Requires Convex Pr | `storage_usage` | Database and file storage metrics | **Webhook Security:** + ```typescript // Verify webhook signature (HMAC-SHA256) const signature = request.headers.get("x-webhook-signature"); @@ -3336,6 +3485,7 @@ const timestamp = request.headers.get("x-webhook-timestamp"); ``` **Best Practices:** + - Use Axiom for quick setup with pre-built dashboards - Datadog for existing APM infrastructure - Webhook for custom alerting or unsupported services @@ -3345,17 +3495,18 @@ const timestamp = request.headers.get("x-webhook-timestamp"); ## Production Guarantees & Limits -**VERIFY at:** https://docs.convex.dev/production/state/ +**VERIFY at:** ### Availability & Uptime **Availability Target:** + - **99.99% availability** (four nines) for all Convex deployments - Maintenance downtime may occur without prior notice - Physical outages will not compromise data durability **Important Note:** -Convex currently does not offer formal contractual SLAs beyond their standard Terms of Service. For enterprise requirements, contact support@convex.dev. +Convex currently does not offer formal contractual SLAs beyond their standard Terms of Service. For enterprise requirements, contact . **Technical Explanation:** Database state is replicated durably across multiple physical availability zones to ensure availability even during infrastructure failures. @@ -3365,15 +3516,18 @@ Database state is replicated durably across multiple physical availability zones ### Data Protection & Security **Encryption:** + - **All user data encrypted at rest** in Convex deployments - Encryption happens automatically, no configuration required **Data Replication:** + - Database state replicated across **multiple physical availability zones** - Protects against data center failures - No manual failover required **Backup Durability:** + - Regular periodic and incremental backups performed automatically - Backups stored with **99.999999999% durability** (eleven nines) - Comparable to Amazon S3 Standard storage class @@ -3386,6 +3540,7 @@ Backup durability of 11 nines means the annual probability of losing a backup is ### Backward Compatibility Guarantee **Commitment:** + - Code written for Convex 1.0+ will continue to work without modification - Breaking changes will have **substantial advance notice** to affected teams - Direct communication for any potential breaking changes @@ -3397,18 +3552,19 @@ You can build production applications on Convex with confidence that future upda ### Platform Limits -**VERIFY at:** https://docs.convex.dev/production/state/limits +**VERIFY at:** #### Function Execution Limits | Resource | Limit | Notes | -|----------|-------|-------| +| ---------- | ------- | ------- | | Query/Mutation execution | 1 second | User code only (excludes framework overhead) | | Action execution | 10 minutes | Long-running operations | | Concurrent Node actions (Free/Starter) | 64 | Parallel action executions | | Concurrent Node actions (Pro) | 1,000 | Professional plan benefit | **Technical Explanation:** + - Queries/mutations have 1-second limit because they're transactional (must be fast) - Actions can run up to 10 minutes for external API calls, file processing, etc. - Exceeding limits throws error; design functions to complete within timeframes @@ -3416,7 +3572,7 @@ You can build production applications on Convex with confidence that future upda #### Document & Database Limits | Resource | Limit | Notes | -|----------|-------|-------| +| ---------- | ------- | ------- | | Document size | 1 MiB | Per document maximum | | Fields per document | 1,024 | Total field count | | Object/array nesting depth | 16 levels | Nested structures | @@ -3430,7 +3586,7 @@ If you hit the 1 MiB document limit, split data across multiple related document #### Transaction Limits | Resource | Limit | Notes | -|----------|-------|-------| +| ---------- | ------- | ------- | | Data read/written per transaction | 16 MiB | Total transaction size | | Documents written per transaction | 16,000 | Mutation write limit | | Documents scanned per transaction | 32,000 | Query/filter limit | @@ -3442,12 +3598,13 @@ These limits ensure mutations remain fast and prevent runaway transactions. If y #### Storage & Bandwidth Limits | Plan | Database Storage | File Storage | Database Bandwidth | File Bandwidth | Function Calls | -|------|------------------|--------------|-------------------|----------------|----------------| +| ------ | ------------------ | -------------- | ------------------- | ---------------- | ---------------- | | Free | 0.5 GiB | 1 GiB | 1 GiB/month | 1 GiB/month | 1M calls/month | | Starter | 8 GiB | 10 GiB | 8 GiB/month | 10 GiB/month | 5M calls/month | | Professional | 50 GiB | 100 GiB | 50 GiB/month | 50 GiB/month | 25M calls/month | **Overage Pricing:** + - Database storage: $1.00/GiB/month - File storage: $0.15/GiB/month - Additional bandwidth and calls: usage-based pricing @@ -3455,7 +3612,7 @@ These limits ensure mutations remain fast and prevent runaway transactions. If y #### Search Limits | Feature | Limit | Notes | -|---------|-------|-------| +| --------- | ------- | ------- | | Full-text search indexes | 4 per table | Text search capability | | Full-text search results | 1,024 maximum | Per query | | Vector search indexes | 4 per table | Semantic/AI search | @@ -3469,11 +3626,13 @@ Search indexes are separate from regular indexes and have their own limits. Desi ### Current Limitations (As of 2025) **No Built-In Authorization Framework:** + - Only **authentication** exists (identity verification) - Authorization (permission checks) must be implemented manually in queries/mutations - Pattern: Check `ctx.auth.getUserIdentity()` and validate permissions in code **Example:** + ```typescript export const deleteTask = mutation({ args: { taskId: v.id("tasks") }, @@ -3495,11 +3654,13 @@ export const deleteTask = mutation({ ``` **Limited Observability:** + - Basic dashboard metrics available (function execution time, call frequency) - Third-party integration for advanced monitoring still in development - Recommendation: Use Sentry, LogRocket, or custom logging for production **Not Optimized for Analytics (OLAP):** + - Convex is designed for real-time transactional operations (OLTP) - Complex analytical queries (aggregations across large datasets) may hit limits - Recommendation: Use streaming export to dedicated analytics database (Snowflake, BigQuery) @@ -3510,7 +3671,8 @@ export const deleteTask = mutation({ The Convex team notes: "Many of these limits will become more permissive over time." -If you encounter limits for your use case, contact support@convex.dev to discuss: +If you encounter limits for your use case, contact to discuss: + - Plan-specific limit increases - Custom enterprise arrangements - Roadmap for future limit expansions @@ -3520,12 +3682,14 @@ If you encounter limits for your use case, contact support@convex.dev to discuss ### Compliance & Enterprise **Current Status:** -- **Terms of Service:** https://convex.dev/terms -- **Privacy Policy:** https://convex.dev/privacy + +- **Terms of Service:** +- **Privacy Policy:** - **No formal GDPR/SOC2 certifications mentioned** in developer documentation **For Enterprise Requirements:** -Contact support@convex.dev for: +Contact for: + - Compliance documentation - Security audits - Custom agreements @@ -3537,7 +3701,7 @@ Contact support@convex.dev for: ### Pre-Deployment Verification -``` +```text Project Setup: - [ ] Detected project framework (Next.js App Router / Pages Router / React Vite) - [ ] Fetched and verified current Convex documentation @@ -3550,7 +3714,7 @@ Project Setup: ### Cloudflare Pages Configuration -``` +```text Pages Setup: - [ ] Created Cloudflare Pages project - [ ] Connected GitHub repository @@ -3564,7 +3728,7 @@ Pages Setup: ### Convex Backend Configuration -``` +```text Convex Production Deployment: - [ ] Deployed to production: npx convex deploy --prod - [ ] Verified production deployment URL @@ -3580,7 +3744,7 @@ Convex Production Deployment: ### Security Checklist -``` +```text Security Verification: - [ ] All secrets in environment variables (never in code) - [ ] API keys use production values (not test keys) @@ -3594,7 +3758,7 @@ Security Verification: ### Testing & Monitoring -``` +```text Production Verification: - [ ] Tested end-to-end user flows in production - [ ] Verified real-time updates working (WebSocket connection) @@ -3610,7 +3774,7 @@ Production Verification: ### Environment Alignment -``` +```text Environment Consistency: - [ ] Dev environment uses dev Convex deployment - [ ] Staging environment uses staging Convex deployment (if applicable) @@ -3622,13 +3786,14 @@ Environment Consistency: ### Backup & Disaster Recovery -**VERIFY at:** https://docs.convex.dev/database/backup-restore +**VERIFY at:** #### Manual Backups (Dashboard) **Access:** Convex Dashboard → Backups → "Backup Now" **Characteristics:** + - Creates consistent snapshot of all table data - Processing time: seconds to hours (depending on data size) - Retention: 7 days @@ -3637,6 +3802,7 @@ Environment Consistency: - **Excludes:** Code, environment variables, scheduled functions, configuration **File Storage Inclusion:** + ```bash # Dashboard option: "Include file storage" # Or via CLI export: @@ -3648,6 +3814,7 @@ npx convex export --path ~/Downloads --include-file-storage **Configuration:** Convex Dashboard → Backups → "Backup automatically" **Options:** + - **Daily backups**: Retained for 7 days, specify time of day - **Weekly backups**: Retained for 14 days, specify day/time - **File storage**: Optional inclusion checkbox @@ -3660,6 +3827,7 @@ Scheduled backups require Convex Pro plan. Each backup is billed for database an **CRITICAL:** Restoration is **destructive** - wipes existing data before restore **Best Practice:** + ```bash # Step 1: Create backup BEFORE restoring # Dashboard → Backup Now @@ -3676,12 +3844,14 @@ npx convex env set VARIABLE_NAME value --prod ``` **Cross-Deployment Restore:** + ```bash # Use case: Populate dev deployment with prod data # Dashboard → Backups → Select backup → "Restore" → Choose target deployment ``` **File Storage Behavior:** + - Existing files in deployment are **NOT deleted** - Files from backup that don't exist in deployment are uploaded - Result: Merge of existing files + backup files @@ -3693,7 +3863,8 @@ npx convex env set VARIABLE_NAME value --prod Dashboard: Backups → Select backup → Download → `snapshot_{timestamp}.zip` **ZIP Structure:** -``` + +```text snapshot_1234567890.zip ├── users/ │ └── documents.jsonl # One document per line @@ -3705,6 +3876,7 @@ snapshot_1234567890.zip ``` **Import ZIP:** + ```bash # Import to dev deployment npx convex import snapshot_1234567890.zip @@ -3714,6 +3886,7 @@ npx convex import snapshot_1234567890.zip --prod ``` **Technical Explanation:** + - ZIP imports preserve document `_id` and `_creationTime` fields - Maintains referential integrity across table references - Import is atomic (except with `--append` flag) @@ -3748,6 +3921,7 @@ npx convex import --table users users.jsonl ``` **Production Import:** + ```bash # ALWAYS test in dev first! npx convex import --table users users.jsonl @@ -3807,7 +3981,7 @@ Dashboard → Restore from backup (within 7 days) #### Streaming Export (Alternative Backup) -**VERIFY at:** https://docs.convex.dev/production/integrations/streaming-import-export +**VERIFY at:** For continuous data replication to external databases: @@ -3821,6 +3995,7 @@ For continuous data replication to external databases: ``` **Use Cases:** + - Real-time analytics warehouse - Continuous backup to external system - Compliance/audit trail requirements @@ -3831,12 +4006,14 @@ For continuous data replication to external databases: #### Backup Limitations & Requirements **What's Included:** + - ✅ All table data with schemas - ✅ File storage (if option selected) - ✅ Document IDs and creation times - ✅ Advanced types (Int64, Bytes via generated_schema.jsonl) **What's Excluded:** + - ❌ Deployment code (functions) - ❌ Configuration files - ❌ Environment variables @@ -3844,6 +4021,7 @@ For continuous data replication to external databases: - ❌ Authentication provider config **After Restore, You Must:** + 1. Redeploy code: `npx convex deploy --prod` 2. Restore environment variables: `npx convex env set ...` 3. Reconfigure authentication providers (Clerk, etc.) @@ -3856,25 +4034,28 @@ For continuous data replication to external databases: ### Streaming Import/Export -**VERIFY at:** https://docs.convex.dev/database/import-export/streaming +**VERIFY at:** For large-scale data operations, Convex supports streaming via Fivetran and Airbyte. **Streaming Export (Pro Plan Required):** Export data to external analytics platforms: + - **Databricks** - Data lakehouse analytics - **Snowflake** - Cloud data warehouse - **BigQuery** - Google Cloud analytics - **ElasticSearch** - Advanced search and filtering **Use Cases:** + - Heavy analytical queries not suited for Convex - Machine learning training on historical data - Complex reporting and BI dashboards - Full-text search with advanced features **Setup:** + 1. Dashboard → Settings → Integrations → Fivetran/Airbyte 2. Configure destination credentials 3. Select tables to export @@ -3883,18 +4064,21 @@ Export data to external analytics platforms: **Streaming Import:** Import data from existing databases: + - Enables gradual Convex adoption - Build new features on existing data - Create reactive UI layers over legacy systems - No custom migration tooling required **Important Considerations:** + - Treat imported tables as **read-only** to prevent write conflicts - Streaming export is beta feature - Streaming import via Fivetran not currently supported - Both integrations use incremental sync for efficiency **CLI Export Alternative:** + ```bash # For one-time exports (not streaming) npx convex export --path ./backup @@ -3909,9 +4093,11 @@ npx convex import --table tasks ./data/tasks.jsonl --- ## Notes + **Convex vs Traditional Databases:** + - No SQL/ORM - JavaScript/TypeScript functions - Automatic transactions in mutations - Real-time reactive queries via WebSockets @@ -3919,6 +4105,7 @@ npx convex import --table tasks ./data/tasks.jsonl - Managed backend (zero server configuration) **When to Use Convex:** + - JAMstack architecture (Cloudflare Pages + Convex backend) - Real-time collaborative applications - Type-safe full-stack development @@ -3926,6 +4113,7 @@ npx convex import --table tasks ./data/tasks.jsonl - Projects needing automatic scaling without DevOps **Integration Architecture:** + - **Frontend**: Cloudflare Pages (global edge, static assets) - **Backend**: Convex (managed functions, database, real-time) - **Benefits**: Geographic distribution, automatic scaling, zero infrastructure management From 2763f0aaa5debdb0633d38d9baae9aa1c57a7c1e Mon Sep 17 00:00:00 2001 From: George Liu Date: Mon, 5 Jan 2026 23:16:00 +1000 Subject: [PATCH 062/174] update Clerk and Convex md docs --- CLAUDE-cloudflare.md | 32 ++++++++++++++++++++++++++++++++ CLAUDE-convex.md | 44 +++++++++++++++++++++++++++++++++++++++----- 2 files changed, 71 insertions(+), 5 deletions(-) diff --git a/CLAUDE-cloudflare.md b/CLAUDE-cloudflare.md index 8e58e6f..38f7a4f 100644 --- a/CLAUDE-cloudflare.md +++ b/CLAUDE-cloudflare.md @@ -421,6 +421,37 @@ export default { } ``` +### Testing & Automation + +Clerk provides testing features for automated/E2E testing. + +**Documentation:** https://clerk.com/docs/testing/overview + +**Test Credentials (bypass verification):** + +| Type | Pattern | Verification Code | +|------|---------|-------------------| +| Email | `+clerk_test` subaddress | `424242` | +| Phone | `+1 (XXX) 555-0100` to `0199` | `424242` | + +Example: `test+clerk_test@example.com` + code `424242` + +**Testing Token (bot detection bypass):** +```bash +# Get token via Backend API +curl -X GET https://api.clerk.dev/v1/testing_tokens \ + -H "Authorization: Bearer $CLERK_SECRET_KEY" +``` + +Add to URL: `?__clerk_testing_token=[token]` + +**Workers/Pages Integration:** +```typescript +// Testing tokens are automatically handled by Clerk SDK +// Just include the token in the URL query parameter +// The SDK will recognize and process it for authentication bypass +``` + --- ## Development Commands @@ -757,6 +788,7 @@ wrangler logout 4. **Clerk @clerk/backend** requires BOTH `secretKey` AND `publishableKey` 5. **D1 batch** for transactions: `await db.batch([stmt1, stmt2])` 6. **authorizedParties** recommended for Clerk to prevent CSRF attacks +7. **Clerk Bot Protection** uses Cloudflare Turnstile - blocks automated browser testing (disable in dev: Clerk Dashboard → Configure → Attack protection) --- diff --git a/CLAUDE-convex.md b/CLAUDE-convex.md index 3c31815..d8e7b12 100644 --- a/CLAUDE-convex.md +++ b/CLAUDE-convex.md @@ -620,13 +620,29 @@ npm install @clerk/nextjs # For Next.js npm install @clerk/clerk-react # For React ``` -1. **Configure Clerk in Convex Dashboard:** +2. **Create Clerk JWT Template:** - - Navigate to Settings → Authentication - - Add Clerk as provider - - Copy Issuer URL from Clerk dashboard + - Clerk Dashboard → Configure → Sessions → JWT templates + - Click "+ Add new template" → Select "Convex" preset + - Save (template auto-configures claims, don't edit manually) + - Copy the **Issuer URL** shown (e.g., `https://xxx.clerk.accounts.dev`) -1. **Add Clerk to Next.js App:** +3. **Create `convex/auth.config.ts` (file-based auth config):** + +```typescript +export default { + providers: [ + { + domain: "https://your-issuer-url.clerk.accounts.dev", // From JWT template + applicationID: "convex", + }, + ], +}; +``` + +> **Note:** The Convex dashboard auth UI may vary - the `auth.config.ts` file is the reliable approach. + +4. **Add Clerk to Next.js App:** **app/layout.tsx:** @@ -708,6 +724,24 @@ export const getMy = query({ - **identity.subject**: Clerk user ID (use as userId in your database) - **Authorization in code**: Check auth at function level (no RLS framework) +### Skip Query for Unauthenticated Users + +Prevent 401 console errors for visitors who haven't signed in: + +```typescript +// In your React component +import { useUser } from "@clerk/nextjs"; + +const { isSignedIn } = useUser(); +// Pass "skip" as second argument when not authenticated +const tasks = useQuery(api.tasks.getMy, isSignedIn ? undefined : "skip"); +``` + +**Why this matters:** +- Without "skip", Convex queries run immediately and return 401 for unauthenticated users +- This creates noisy console errors even though the app handles auth correctly +- The "skip" pattern prevents the query from running until the user is authenticated + --- ## Framework-Specific Patterns From f41e7a7d033a78d3f8473469af62e4355b1bd5ae Mon Sep 17 00:00:00 2001 From: George Liu Date: Tue, 6 Jan 2026 18:57:19 +1000 Subject: [PATCH 063/174] update readme for Claude Plugins --- README.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/README.md b/README.md index 9b7173d..2547313 100644 --- a/README.md +++ b/README.md @@ -73,6 +73,33 @@ I also install the following MCP servers ([install commands](#claude-code-mcp-se * [Notion MCP](https://github.com/makenotion/notion-mcp-server) * [Claude Code Usage Metrics MCP](https://github.com/centminmod/claude-code-opentelemetry-setup) +## Claude Code Plugin Marketplace + +Browser and install Claude Code plugins from official marketplace https://code.claude.com/docs/en/discover-plugins. + +```bash +/plugin install plugin-name@claude-plugins-official +``` + +Install [frontend design plugin](https://github.com/anthropics/claude-code/tree/main/plugins/frontend-design). + +> Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. + +```bash +/plugin install frontend-design@claude-code-plugins +``` + +Install [Ralph Wiggum plugin](https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum). Details https://paddo.dev/blog/ralph-wiggum-autonomous-loops/. Update: currently seems broken on some systems. + +- https://github.com/anthropics/claude-code/issues/16398 +- https://github.com/anthropics/claude-code/issues/16389 + +> Interactive self-referential AI loops for iterative development. Claude works on the same task repeatedly, seeing its previous work, until completion. + +```bash +/plugin install ralph-wiggum@claude-code-plugins +``` + ## Claude Code Statuslines `~/.claude/statuslines/statusline.sh` configured in `~/.claude/settings.json`. From fab6ef7aeb4749709ba596bdb254834aeeb42ed7 Mon Sep 17 00:00:00 2001 From: George Liu Date: Tue, 6 Jan 2026 19:11:01 +1000 Subject: [PATCH 064/174] update --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 2547313..c13c37a 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,7 @@ My Claude Code project's starter settings and Claude Code hooks and slash comman 9. If you use Cloudflare and ClerkOS platforms in your apps, you can keep either `CLAUDE-cloudflare.md` or `CLAUDE-cloudflare-mini.md` supplementary reference docs and update `CLAUDE.md` referencing either file to help AI understand Cloudflare and ClerkOS platforum documentation and products. Edit documentation templates as needed i.e. if you do not use ClerkOS platform, you can remove those sections. 10. If you use Convex database in your apps, you can use `CLAUDE-convex.md` supplementary reference docs for building Next.js and React apps with Convex backend deployed on Cloudflare Pages. 11. Useful read [Advent of Claude: 31 Days of Claude Code by Ado Kukic from Anthropic](https://adocomplete.com/advent-of-claude-2025/). +12. Useful [Claude Code with Claude Opus 4.5 YouTube video](https://www.youtube.com/watch?v=UVJXh57MgI0). ## CLAUDE.md Memory Bank system From 5fc3e85582e0b0727bf3e857ab95e7940ade3b1b Mon Sep 17 00:00:00 2001 From: George Liu Date: Wed, 7 Jan 2026 02:35:14 +1000 Subject: [PATCH 065/174] update readme --- README.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index c13c37a..4b639fa 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ My Claude Code project's starter settings and Claude Code hooks and slash comman 9. If you use Cloudflare and ClerkOS platforms in your apps, you can keep either `CLAUDE-cloudflare.md` or `CLAUDE-cloudflare-mini.md` supplementary reference docs and update `CLAUDE.md` referencing either file to help AI understand Cloudflare and ClerkOS platforum documentation and products. Edit documentation templates as needed i.e. if you do not use ClerkOS platform, you can remove those sections. 10. If you use Convex database in your apps, you can use `CLAUDE-convex.md` supplementary reference docs for building Next.js and React apps with Convex backend deployed on Cloudflare Pages. 11. Useful read [Advent of Claude: 31 Days of Claude Code by Ado Kukic from Anthropic](https://adocomplete.com/advent-of-claude-2025/). -12. Useful [Claude Code with Claude Opus 4.5 YouTube video](https://www.youtube.com/watch?v=UVJXh57MgI0). +12. Useful [Claude Code with Claude Opus 4.5 YouTube video by Alex Finn](https://www.youtube.com/watch?v=UVJXh57MgI0) and [Claude Code YouTube video by Matt Maher](https://www.youtube.com/watch?v=Dekx_OzRwiI). ## CLAUDE.md Memory Bank system @@ -101,6 +101,17 @@ Install [Ralph Wiggum plugin](https://github.com/anthropics/claude-code/tree/mai /plugin install ralph-wiggum@claude-code-plugins ``` +## Claude Code 3rd Party Marketplaces + +Claude Code Safety Net plugin https://github.com/kenryu42/claude-code-safety-net to prevent destructive commands being run by Claude Code i.e. https://www.reddit.com/r/ClaudeAI/comments/1pgxckk/claude_cli_deleted_my_entire_home_directory_wiped/ + +> A Claude Code plugin that acts as a safety net, catching destructive git and filesystem commands before they execute. + +```bash +/plugin marketplace add kenryu42/cc-marketplace +/plugin install safety-net@cc-marketplace +``` + ## Claude Code Statuslines `~/.claude/statuslines/statusline.sh` configured in `~/.claude/settings.json`. From 7052087ba7c5dca83d9e63f1df388b9525f9c864 Mon Sep 17 00:00:00 2001 From: George Liu Date: Thu, 8 Jan 2026 16:35:30 +1000 Subject: [PATCH 066/174] update README & CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS setting - Update readme - Claude Code 2.1.0 suported CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS variable. Raise from 25000 to 45000 default tokens default for max file read size --- .claude/settings.local.json | 3 ++- README.md | 8 ++++++++ 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/.claude/settings.local.json b/.claude/settings.local.json index a2a28cc..b70ff18 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -4,7 +4,8 @@ "BASH_DEFAULT_TIMEOUT_MS": "300000", "BASH_MAX_TIMEOUT_MS": "600000", "MAX_THINKING_TOKENS": "8192", - "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "64000" + "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "64000", + "CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS": "45000" }, "includeCoAuthoredBy": false, "permissions": { diff --git a/README.md b/README.md index 4b639fa..73757d1 100644 --- a/README.md +++ b/README.md @@ -90,6 +90,14 @@ Install [frontend design plugin](https://github.com/anthropics/claude-code/tree/ /plugin install frontend-design@claude-code-plugins ``` +Install [feature dev plugin](https://github.com/anthropics/claude-code/tree/main/plugins/feature-dev). + +> The Feature Development Plugin provides a systematic 7-phase approach to building new features. Instead of jumping straight into code, it guides you through understanding the codebase, asking clarifying questions, designing architecture, and ensuring quality—resulting in better-designed features that integrate seamlessly with your existing code. + +```bash +/plugin install feature-dev@claude-code-plugins +``` + Install [Ralph Wiggum plugin](https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum). Details https://paddo.dev/blog/ralph-wiggum-autonomous-loops/. Update: currently seems broken on some systems. - https://github.com/anthropics/claude-code/issues/16398 From dead772a1dcd622bc415f0d68cfcc6f52b017551 Mon Sep 17 00:00:00 2001 From: George Liu Date: Fri, 9 Jan 2026 22:22:07 +1000 Subject: [PATCH 067/174] Add Z.AI Claude Code configuration --- .claude/settings.local.json | 3 +- README.md | 285 ++++++++++++++++++++++++++++++++++++ 2 files changed, 287 insertions(+), 1 deletion(-) diff --git a/.claude/settings.local.json b/.claude/settings.local.json index b70ff18..0d057b7 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -86,7 +86,8 @@ "mcp__chrome-devtools__new_page", "Skill(claude-docs-consultant)", "WebFetch(domain:docs.convex.dev)", - "mcp__context7__query-docs" + "mcp__context7__query-docs", + "WebFetch(domain:docs.z.ai)" ], "deny": [], "defaultMode": "plan" diff --git a/README.md b/README.md index 73757d1..62cd409 100644 --- a/README.md +++ b/README.md @@ -82,6 +82,20 @@ Browser and install Claude Code plugins from official marketplace https://code.c /plugin install plugin-name@claude-plugins-official ``` +To update official Claude Code plugin marketplace: + +```bash +/plugin marketplace update claude-plugins-official +``` + +Install [code simplifier plugin](#). + +> Simplifies code by removing unnecessary complexity while preserving functionality. + +```bash +/plugin install code-simplifier +``` + Install [frontend design plugin](https://github.com/anthropics/claude-code/tree/main/plugins/frontend-design). > Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. @@ -412,6 +426,277 @@ test-local.sh **Note:** Files in `.git/info/exclude` work with `.worktreeinclude` the same way as `.gitignore` - patterns must appear in both files for copying to worktrees. +## Using Z.AI with Claude Code + +Z.AI's GLM Coding Plan is a cost-effective subscription service starting at just $3/month that provides access to GLM-4.7, a high-performance language model optimized for coding tasks. With over 55 tokens per second for real-time interaction, it offers state-of-the-art performance in reasoning, coding, and agent capabilities. The service includes multimodal features like Vision Understanding, Web Search, and Web Reader MCP servers. Below [shell function launchers](#shell-function-launchers) are easiest way to use Z.AI with Claude Code without messing up your existing Claude Code setup. + +**Usage Tiers:** +- **Lite Plan** (~$3/month): ~120 prompts per 5 hours (roughly 3× Claude Pro quota) +- **Pro Plan**: ~600 prompts per 5 hours (3× Claude Max 5x quota) +- **Max Plan**: ~2,400 prompts per 5 hours (3× Claude Max 20x quota) + +Each prompt typically allows 15–20 model calls, yielding tens of billions of tokens monthly at approximately 1% of standard API pricing. + +### Privacy & Data Handling + +**Data Location:** All Z.AI services are based in Singapore. + +**Privacy Guarantee:** Z.AI does not store any of the content you provide or generate while using their services. This includes any text prompts, images, or other data you input. + +See the [Privacy Policy](https://docs.z.ai/legal-agreement/privacy-policy) for further details. + +### Special Discount: Get 10% OFF! + +> 🚀 You've been invited to join the GLM Coding Plan! Enjoy full support for Claude Code, Cline, and 10+ top coding tools — starting at just $3/month. Subscribe now and grab the limited-time deal! +> +> **Invite Code:** `WWB8IFLROM` (10% additional discount) +> +> **Subscribe:** [https://z.ai/subscribe?ic=WWB8IFLROM](https://z.ai/subscribe?ic=WWB8IFLROM) + +### Prerequisites + +- Node.js 18 or newer +- Z.AI API key (obtain from [Z.AI dashboard](https://z.ai)) +- Official documentation: [https://docs.z.ai/devpack/tool/claude](https://docs.z.ai/devpack/tool/claude) + +### Setup Instructions + +#### Option 1: Automated Setup (Recommended) + +For macOS/Linux, run this one-liner to automatically configure Z.AI: + +```bash +curl -O "https://cdn.bigmodel.cn/install/claude_code_zai_env.sh" && bash ./claude_code_zai_env.sh +``` + +#### Option 2: Manual Configuration + +Edit your `~/.claude/settings.json` and add the environment variables: + +```json +{ + "env": { + "ANTHROPIC_AUTH_TOKEN": "your-zai-api-key", + "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic", + "API_TIMEOUT_MS": "3000000" + } +} +``` + +Replace `your-zai-api-key` with your actual Z.AI API key from the dashboard. + +### Shell Function Launchers + +#### macOS / Linux (Bash/Zsh) + +Add this function to `~/.bashrc`, `~/.zshrc`, or `~/.bash_aliases`: + +```bash +# Z.AI + Claude Code launcher +zai() { + export ANTHROPIC_AUTH_TOKEN="your-zai-api-key" + export ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic" + export API_TIMEOUT_MS="3000000" + claude "$@" +} +``` + +After adding, reload your shell: `source ~/.bashrc` or `source ~/.zshrc` + +#### Windows (PowerShell) + +Add this function to your PowerShell profile. Open it with `notepad $PROFILE`: + +```powershell +# Z.AI + Claude Code launcher +function zai { + $env:ANTHROPIC_AUTH_TOKEN = "your-zai-api-key" + $env:ANTHROPIC_BASE_URL = "https://api.z.ai/api/anthropic" + $env:API_TIMEOUT_MS = "3000000" + claude $args +} +``` + +After adding, reload PowerShell or run: `. $PROFILE` + +#### Windows (CMD Batch Files) + +Create a batch file named `zai.bat` in a directory in your PATH (e.g., `C:\Users\YourName\bin\`): + +```batch +@echo off +set ANTHROPIC_AUTH_TOKEN=your-zai-api-key +set ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic +set API_TIMEOUT_MS=3000000 +claude %* +``` + +### Model Mapping + +The GLM Coding Plan uses intelligent model mapping where Claude model names are mapped to GLM models through environment variables: + +- `ANTHROPIC_DEFAULT_OPUS_MODEL`: GLM-4.7 +- `ANTHROPIC_DEFAULT_SONNET_MODEL`: GLM-4.7 +- `ANTHROPIC_DEFAULT_HAIKU_MODEL`: GLM-4.5-Air + +**Note:** While manual adjustment of these mappings is possible, it's not recommended as it may prevent automatic updates to newer model versions. + +#### Customizing Model Mappings + +If you need to switch to different models (e.g., GLM-4.5 or other models), you can customize the mappings in two ways: + +**Option 1: In `~/.claude/settings.json`** + +```json +{ + "env": { + "ANTHROPIC_AUTH_TOKEN": "your-zai-api-key", + "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic", + "API_TIMEOUT_MS": "3000000", + "ANTHROPIC_DEFAULT_OPUS_MODEL": "GLM-4.7", + "ANTHROPIC_DEFAULT_SONNET_MODEL": "GLM-4.5", + "ANTHROPIC_DEFAULT_HAIKU_MODEL": "GLM-4.5-Air" + } +} +``` + +**Option 2: In Shell Function/Alias** + +For macOS/Linux: + +```bash +zai() { + export ANTHROPIC_AUTH_TOKEN="your-zai-api-key" + export ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic" + export API_TIMEOUT_MS="3000000" + export ANTHROPIC_DEFAULT_OPUS_MODEL="GLM-4.7" + export ANTHROPIC_DEFAULT_SONNET_MODEL="GLM-4.5" + export ANTHROPIC_DEFAULT_HAIKU_MODEL="GLM-4.5-Air" + claude "$@" +} +``` + +For Windows PowerShell: + +```powershell +function zai { + $env:ANTHROPIC_AUTH_TOKEN = "your-zai-api-key" + $env:ANTHROPIC_BASE_URL = "https://api.z.ai/api/anthropic" + $env:API_TIMEOUT_MS = "3000000" + $env:ANTHROPIC_DEFAULT_OPUS_MODEL = "GLM-4.7" + $env:ANTHROPIC_DEFAULT_SONNET_MODEL = "GLM-4.5" + $env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "GLM-4.5-Air" + claude $args +} +``` + +For Windows CMD: + +```batch +@echo off +set ANTHROPIC_AUTH_TOKEN=your-zai-api-key +set ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic +set API_TIMEOUT_MS=3000000 +set ANTHROPIC_DEFAULT_OPUS_MODEL=GLM-4.7 +set ANTHROPIC_DEFAULT_SONNET_MODEL=GLM-4.5 +set ANTHROPIC_DEFAULT_HAIKU_MODEL=GLM-4.5-Air +claude %* +``` + +### Usage + +```bash +# Launch with Z.AI configuration +zai + +# Launch with specific model +zai --model sonnet + +# Launch with permission mode +zai --model opus --permission-mode plan +``` + +### Z.AI + Git Worktree Integration + +Combine Z.AI with git worktrees for isolated parallel sessions: + +#### macOS / Linux (Bash/Zsh) + +```bash +# Z.AI + Claude Code worktree launcher +zaix() { + local branch_name + if [ -z "$1" ]; then + branch_name="worktree-$(date +%Y%m%d-%H%M%S)" + else + branch_name="$1" + fi + git worktree add "../$branch_name" -b "$branch_name" && \ + cd "../$branch_name" || return 1 + + export ANTHROPIC_AUTH_TOKEN="your-zai-api-key" + export ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic" + export API_TIMEOUT_MS="3000000" + claude --model sonnet --permission-mode plan +} +``` + +#### Windows (PowerShell) + +```powershell +# Z.AI + Claude Code worktree launcher +function zaix { + param([string]$BranchName) + if (-not $BranchName) { + $BranchName = "worktree-$(Get-Date -Format 'yyyyMMdd-HHmmss')" + } + git worktree add "../$BranchName" -b $BranchName + if ($LASTEXITCODE -eq 0) { + Set-Location "../$BranchName" + $env:ANTHROPIC_AUTH_TOKEN = "your-zai-api-key" + $env:ANTHROPIC_BASE_URL = "https://api.z.ai/api/anthropic" + $env:API_TIMEOUT_MS = "3000000" + claude --model sonnet --permission-mode plan + } +} +``` + +#### Windows (CMD Batch Files) + +Create `zaix.bat`: + +```batch +@echo off +setlocal enabledelayedexpansion +if "%~1"=="" ( + for /f "tokens=2 delims==" %%I in ('wmic os get localdatetime /value') do set datetime=%%I + set branch_name=worktree-!datetime:~0,8!-!datetime:~8,6! +) else ( + set branch_name=%~1 +) +git worktree add "../%branch_name%" -b "%branch_name%" +if %errorlevel% equ 0 ( + cd "../%branch_name%" + set ANTHROPIC_AUTH_TOKEN=your-zai-api-key + set ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic + set API_TIMEOUT_MS=3000000 + claude --model sonnet --permission-mode plan +) +endlocal +``` + +After adding, reload your shell configuration. + +**Usage:** + +```bash +# Create worktree with custom name +zaix feature-auth + +# Create worktree with auto-generated timestamp name +zaix +``` + ## Claude Code Skills Claude Code now supports [Agent Skills](https://docs.claude.com/en/docs/claude-code/skills). From d497db92ab3111a9cf0bbd3366f351b46f27f0da Mon Sep 17 00:00:00 2001 From: George Liu Date: Fri, 9 Jan 2026 22:24:58 +1000 Subject: [PATCH 068/174] update readme --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 62cd409..be81d46 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ # My Claude Code Project's Starter Settings -My Claude Code project's starter settings and Claude Code hooks and slash commands are provided in this repository for users to try out. The [CLAUDE.md](https://github.com/centminmod/my-claude-code-setup/blob/master/CLAUDE.md) is setup as set of memory bank files to better retain context over many chat sessions. Be sure to read the official Claude Code docs first at and sign up for a [paid Claude AI account](https://claude.ai/) to use Claude Code. You can pay for Claude Pro $20/month, Claude Max $100/month or Claude Max $200/month. The paid Claude tier plans will include varying quotas for usage and rate limits outlined [here](https://support.anthropic.com/en/articles/9797557-usage-limit-best-practices). +My Claude Code project's starter settings and Claude Code hooks and slash commands are provided in this repository for users to try out. The [CLAUDE.md](https://github.com/centminmod/my-claude-code-setup/blob/master/CLAUDE.md) is setup as set of memory bank files to better retain context over many chat sessions. Be sure to read the official Claude Code docs first at and sign up for a [paid Claude AI account](https://claude.ai/) to use Claude Code. You can pay for Claude Pro $20/month, Claude Max $100/month or Claude Max $200/month. The paid Claude tier plans will include varying quotas for usage and rate limits outlined [here](https://support.anthropic.com/en/articles/9797557-usage-limit-best-practices). You can also use Claude Code with [Z.AI](#using-zai-with-claude-code) to get higher token usage quotas and get access to Z.AI GLM-4.7 LLM models within Claude Code. 1. Copy the files in this Github repo to your project directory (where you intended codebase will be). 2. Modify the template files and CLAUDE.md`to your liking. `.claude/settings.json` needs to install Terminal-Notifier for macOS https://github.com/centminmod/terminal-notifier-setup. If you're not using macOS, you can remove `.claude/settings.json`. @@ -19,6 +19,7 @@ My Claude Code project's starter settings and Claude Code hooks and slash comman 10. If you use Convex database in your apps, you can use `CLAUDE-convex.md` supplementary reference docs for building Next.js and React apps with Convex backend deployed on Cloudflare Pages. 11. Useful read [Advent of Claude: 31 Days of Claude Code by Ado Kukic from Anthropic](https://adocomplete.com/advent-of-claude-2025/). 12. Useful [Claude Code with Claude Opus 4.5 YouTube video by Alex Finn](https://www.youtube.com/watch?v=UVJXh57MgI0) and [Claude Code YouTube video by Matt Maher](https://www.youtube.com/watch?v=Dekx_OzRwiI). +13. Configure Claude Code with [Z.AI](#using-zai-with-claude-code) to get higher token usage quotas and get access to Z.AI GLM-4.7 LLM models within Claude Code. ## CLAUDE.md Memory Bank system From 1d65ca142ad07c7288ac487a3e26acb923ff1f6d Mon Sep 17 00:00:00 2001 From: George Liu Date: Fri, 9 Jan 2026 22:29:29 +1000 Subject: [PATCH 069/174] update --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index be81d46..20d9cec 100644 --- a/README.md +++ b/README.md @@ -429,6 +429,8 @@ test-local.sh ## Using Z.AI with Claude Code +* Get extra 10% discount with invite code [(https://z.ai/subscribe?ic=WWB8IFLROM)](https://z.ai/subscribe?ic=WWB8IFLROM) + Z.AI's GLM Coding Plan is a cost-effective subscription service starting at just $3/month that provides access to GLM-4.7, a high-performance language model optimized for coding tasks. With over 55 tokens per second for real-time interaction, it offers state-of-the-art performance in reasoning, coding, and agent capabilities. The service includes multimodal features like Vision Understanding, Web Search, and Web Reader MCP servers. Below [shell function launchers](#shell-function-launchers) are easiest way to use Z.AI with Claude Code without messing up your existing Claude Code setup. **Usage Tiers:** From dd33818919579686821c9447923ebaa94eb2b05e Mon Sep 17 00:00:00 2001 From: George Liu Date: Fri, 9 Jan 2026 22:36:10 +1000 Subject: [PATCH 070/174] update --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 20d9cec..73486ba 100644 --- a/README.md +++ b/README.md @@ -464,9 +464,9 @@ See the [Privacy Policy](https://docs.z.ai/legal-agreement/privacy-policy) for f ### Setup Instructions -#### Option 1: Automated Setup (Recommended) +#### Option 1: Automated Setup (Recommended for First-Time Users) -For macOS/Linux, run this one-liner to automatically configure Z.AI: +Just run the following command in your terminal. Attention only macOS Linux environment is supported, this method does not support Windows ```bash curl -O "https://cdn.bigmodel.cn/install/claude_code_zai_env.sh" && bash ./claude_code_zai_env.sh From 54e9a1f2fcd306a49dc1033b496ea0e4906b17ab Mon Sep 17 00:00:00 2001 From: George Liu Date: Sat, 10 Jan 2026 00:36:40 +1000 Subject: [PATCH 071/174] update readme --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 73486ba..cbd1844 100644 --- a/README.md +++ b/README.md @@ -89,9 +89,9 @@ To update official Claude Code plugin marketplace: /plugin marketplace update claude-plugins-official ``` -Install [code simplifier plugin](#). +Install [code simplifier plugin](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/code-simplifier). -> Simplifies code by removing unnecessary complexity while preserving functionality. +> Agent that simplifies and refines code for clarity, consistency, and maintainability while preserving functionality. Focuses on recently modified code. ```bash /plugin install code-simplifier From 81c8ab9163cd354365f90736ee05c93c7520e524 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sat, 10 Jan 2026 02:55:30 +1000 Subject: [PATCH 072/174] add ZAI usage plugin and marketplace --- README.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/README.md b/README.md index cbd1844..85ad478 100644 --- a/README.md +++ b/README.md @@ -135,6 +135,15 @@ Claude Code Safety Net plugin https://github.com/kenryu42/claude-code-safety-net /plugin install safety-net@cc-marketplace ``` +[Z.AI usage query plugin](https://docs.z.ai/devpack/extension/usage-query-plugin) for querying [Z.AI](#using-zai-with-claude-code) usage statistics. + +> Query your current quota and usage statistics for the GLM Coding Plan directly within Claude Code. + +```bash +/plugin marketplace add zai/zai-coding-plugins +/plugin install glm-plan-usage@zai-coding-plugins +``` + ## Claude Code Statuslines `~/.claude/statuslines/statusline.sh` configured in `~/.claude/settings.json`. From 90a22adf3629b60d8eb6f7715554c82335a4be32 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sun, 11 Jan 2026 00:37:55 +1000 Subject: [PATCH 073/174] update --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 85ad478..4ecb278 100644 --- a/README.md +++ b/README.md @@ -124,6 +124,8 @@ Install [Ralph Wiggum plugin](https://github.com/anthropics/claude-code/tree/mai /plugin install ralph-wiggum@claude-code-plugins ``` +How to use Ralph Wiggum plugin YouTube by Greg Isenberg https://www.youtube.com/watch?v=RpvQH0r0ecM + ## Claude Code 3rd Party Marketplaces Claude Code Safety Net plugin https://github.com/kenryu42/claude-code-safety-net to prevent destructive commands being run by Claude Code i.e. https://www.reddit.com/r/ClaudeAI/comments/1pgxckk/claude_cli_deleted_my_entire_home_directory_wiped/ From bce7c126efff39823564b1506ca2470808ad83d1 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sun, 11 Jan 2026 00:43:21 +1000 Subject: [PATCH 074/174] update --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 4ecb278..9aedea8 100644 --- a/README.md +++ b/README.md @@ -124,7 +124,7 @@ Install [Ralph Wiggum plugin](https://github.com/anthropics/claude-code/tree/mai /plugin install ralph-wiggum@claude-code-plugins ``` -How to use Ralph Wiggum plugin YouTube by Greg Isenberg https://www.youtube.com/watch?v=RpvQH0r0ecM +How to use Ralph Wiggum plugin YouTube by Greg Isenberg and Ryan Carson https://www.youtube.com/watch?v=RpvQH0r0ecM and GitHub repo https://github.com/snarktank/ralph. ## Claude Code 3rd Party Marketplaces From 719b4c9aabe1ebcecbf43f06c1c61642ec2937e8 Mon Sep 17 00:00:00 2001 From: George Liu Date: Tue, 13 Jan 2026 14:56:48 +1000 Subject: [PATCH 075/174] add alternative readme styles catering to different types of users --- README-v2.md | 1255 ++++++++++++++++++++++++++++++++++++ README-v3.md | 962 +++++++++++++++++++++++++++ README-v4.md | 1748 ++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 11 + 4 files changed, 3976 insertions(+) create mode 100644 README-v2.md create mode 100644 README-v3.md create mode 100644 README-v4.md diff --git a/README-v2.md b/README-v2.md new file mode 100644 index 0000000..68bb09a --- /dev/null +++ b/README-v2.md @@ -0,0 +1,1255 @@ +[![GitHub stars](https://img.shields.io/github/stars/centminmod/my-claude-code-setup.svg?style=flat-square)](https://github.com/centminmod/my-claude-code-setup/stargazers) [![GitHub forks](https://img.shields.io/github/forks/centminmod/my-claude-code-setup.svg?style=flat-square)](https://github.com/centminmod/my-claude-code-setup/network) [![GitHub issues](https://img.shields.io/github/issues/centminmod/my-claude-code-setup.svg?style=flat-square)](https://github.com/centminmod/my-claude-code-setup/issues) + +* Threads - https://www.threads.com/@george_sl_liu +* BlueSky - https://bsky.app/profile/georgesl.bsky.social + +# My Claude Code Setup + +A comprehensive starter kit for Claude Code projects featuring a memory bank system for context retention, pre-configured hooks, skills, subagents, and MCP server recommendations. + +## Table of Contents + +- [Quick Start](#quick-start) +- **Beginner** + - [1. Getting Started](#1-getting-started) + - [2. Memory Bank System](#2-memory-bank-system) +- **Intermediate** + - [3. Extending Claude Code](#3-extending-claude-code) + - [4. Development Workflows](#4-development-workflows) +- **Advanced** + - [5. Customization](#5-customization) + - [6. Alternative Providers (Z.AI)](#6-alternative-providers) + - [7. Cost & Rate Management](#7-cost--rate-management) +- **Reference** + - [8. Configuration Reference](#8-configuration-reference) + - [9. Resources](#9-resources) + +--- + +## Quick Start + +Get up and running in under 5 minutes: + +**Prerequisites Checklist:** +- [ ] [Paid Claude AI account](https://claude.ai/) (Pro $20/mo, Max $100/mo, or Max $200/mo) +- [ ] Node.js 18+ installed +- [ ] Git installed +- [ ] macOS: `brew install ripgrep fd jq` + +**Installation Options:** + +Choose the method that works best for you: + +### Option A: Clone Entire Repository (New Projects) + +```bash +# 1. Clone this repository as your new project +git clone https://github.com/centminmod/my-claude-code-setup.git my-project +cd my-project + +# 2. Remove template README files (create your own project README) +rm README.md README-v2.md README-v3.md README-v4.md + +# 3. Reinitialize git for your own project (optional) +rm -rf .git +git init + +# 4. Launch Claude Code and initialize +claude +# Then run: /init +``` + +### Option B: Selective Copy (Existing Projects) + +Copy only the files you need into your existing project: + +```bash +# Core files (recommended) +cp /path/to/my-claude-code-setup/CLAUDE.md your-project/ +cp -r /path/to/my-claude-code-setup/.claude your-project/ + +# Or selectively copy specific components: +cp -r /path/to/my-claude-code-setup/.claude/commands your-project/.claude/ +cp -r /path/to/my-claude-code-setup/.claude/skills your-project/.claude/ +cp -r /path/to/my-claude-code-setup/.claude/agents your-project/.claude/ +cp -r /path/to/my-claude-code-setup/.claude/hooks your-project/.claude/ +``` + +### Option C: Download Specific Files (GitHub) + +Browse the repository on GitHub and download individual files: +- `CLAUDE.md` - Memory bank main file +- `.claude/settings.json` - Settings template +- `.claude/commands/` - Slash commands you want +- `.claude/skills/` - Skills you want +- `.claude/agents/` - Subagents you want + +After copying files, launch Claude Code in your project and run `/init`. + +--- + +# BEGINNER SECTION + +--- + +## 1. Getting Started + +### 1.1 What This Repository Provides + +- **Memory Bank System**: Structured context files for persistent memory across sessions +- **Pre-configured Settings**: Optimized `.claude/settings.json` with fast tools +- **Custom Hooks**: Desktop notifications when Claude Code completes tasks +- **Custom Skills**: Specialized agents for documentation lookup +- **Custom Subagents**: Task-specific agents for code search, UX design, and more +- **Custom Slash Commands**: Security audits, refactoring plans, prompt engineering +- **MCP Server Recommendations**: Curated list of useful MCP servers + +### 1.2 Prerequisites + +| Requirement | Version | Purpose | +|------------|---------|---------| +| Claude AI Account | Pro/Max | Required for Claude Code access | +| Node.js | 18+ | Runtime environment | +| Git | Latest | Version control | +| ripgrep | Latest | Fast content search | +| fd | Latest | Fast file finding | +| jq | Latest | JSON processing | + +**Operating System Support:** +- macOS: Fully supported +- Linux: Fully supported +- Windows: Supported (PowerShell or CMD) + +### 1.3 Installation Steps + +1. **Copy Repository Files** + + Copy all files from this GitHub repo to your project directory (where your intended codebase will be). + +2. **Modify Template Files** + + Edit `CLAUDE.md` to match your project. The `.claude/settings.json` file includes Terminal-Notifier for macOS notifications ([setup guide](https://github.com/centminmod/terminal-notifier-setup)). Remove this file if not using macOS. + +3. **Initialize Memory Bank** + + After launching Claude Code in your project directory, run `/init` to analyze your codebase and populate memory bank files. + +4. **Install Fast Tools (macOS)** + + ```bash + brew install ripgrep fd jq + ``` + +### 1.4 Optional Enhancements + +- **Visual Studio Code**: Install [VS Code](https://code.visualstudio.com/) and the [Claude Code Extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code) + - [Beginner YouTube guide](https://www.youtube.com/watch?v=rPITZvwyoMc) + - [Additional guide](https://www.youtube.com/watch?v=P-5bWpUbO60) + +- **GitHub Integration**: Set up Git for VS Code + - [Git setup guide](https://www.youtube.com/watch?v=twsYxYaQikI) + - [VS Code + Git tutorial](https://www.youtube.com/watch?v=z5jZ9lrSpqk) + +- **Dev Container**: Run Claude Code, Codex GPT-5, Gemini CLI, and more in an isolated [VS Code dev container](https://claude-devcontainers.centminmod.com/) with full YOLO mode support. + +- **Platform-Specific Docs**: If using Cloudflare/ClerkOS, keep `CLAUDE-cloudflare.md` or `CLAUDE-cloudflare-mini.md` and reference them in `CLAUDE.md`. For Convex database, use `CLAUDE-convex.md`. + +### 1.5 Useful Learning Resources + +- [Advent of Claude: 31 Days of Claude Code](https://adocomplete.com/advent-of-claude-2025/) by Ado Kukic (Anthropic) +- [Claude Code with Opus 4.5](https://www.youtube.com/watch?v=UVJXh57MgI0) by Alex Finn +- [Claude Code Overview](https://www.youtube.com/watch?v=Dekx_OzRwiI) by Matt Maher + +--- + +## 2. Memory Bank System + +### 2.1 What is Memory Bank? + +The Memory Bank System is a structured set of markdown files that help Claude Code retain context across multiple chat sessions. Instead of starting fresh each time, Claude Code reads these files to understand your project's patterns, decisions, and current state. + +### 2.2 Core Context Files + +| File | Purpose | +|------|---------| +| `CLAUDE.md` | Main entry point with project overview and AI guidance | +| `CLAUDE-activeContext.md` | Current session state, goals, and progress | +| `CLAUDE-patterns.md` | Established code patterns and conventions | +| `CLAUDE-decisions.md` | Architecture decisions and rationale (ADRs) | +| `CLAUDE-troubleshooting.md` | Common issues and proven solutions | +| `CLAUDE-config-variables.md` | Configuration variables reference | +| `CLAUDE-temp.md` | Temporary scratch pad (only read when referenced) | + +### 2.3 Setting Up Memory Bank + +1. Copy the template files from this repository to your project root +2. Run `/init` in Claude Code to analyze your codebase +3. Claude Code will populate the memory bank files based on your project + +### 2.4 Updating Memory Bank + +After completing significant work, ask Claude Code to update the memory bank: + +``` +update memory bank +``` + +### 2.5 Memory Bank Example Output + +Here's what Claude Code's thinking looks like when updating the memory bank: + +``` +> update memory bank + +∴ Thinking… + + The user wants me to update the memory bank files. I should update the relevant CLAUDE-*.md files to reflect the v0.1.6 changes and current state. Let me check + which memory bank files exist and update them. + +∴ Thinking… + + I need to continue updating the memory bank files. I'll update: + 1. CLAUDE-patterns.md - Add export path handling pattern (Pattern 22) + 2. CLAUDE-decisions.md - Add ADR-017 for Phoneme API migration and ADR-018 for export path handling + 3. CLAUDE-troubleshooting.md - Add new issues and solutions for v0.1.6 + +∴ Thinking… + + The memory bank files have been modified but not committed. The v0.1.6 release was already committed and tagged, but the memory bank documentation updates are + still uncommitted. Let me provide a summary of the completed work and offer to commit these documentation changes. + +⏺ Summary: v0.1.6 Release Complete ✅ + + Memory Bank Updates Complete: + - CLAUDE-activeContext.md - v0.1.6 session context + - CLAUDE-patterns.md - Added patterns 22-24 (Export Path, Format Detection, API Migration) + - CLAUDE-decisions.md - Added ADR-017 & ADR-018 + - CLAUDE-troubleshooting.md - Added 4 new issue/fix entries + + v0.1.6 Fixes Applied: + 1. Export to absolute paths (e.g., --export /tmp/test.wav) + 2. Format detection from filename extension (prevents .mp3.wav) + 3. Phoneme API migrated to /dev/phonemize + 4. Test scripts updated for --export "" syntax + + Test Results: All 29 tests passing + + The memory bank documentation updates are ready to commit. Would you like me to commit them +``` + +--- + +# INTERMEDIATE SECTION + +--- + +## 3. Extending Claude Code + +### 3.1 Plugin System + +Claude Code supports plugins from both official and third-party marketplaces. + +#### Official Anthropic Marketplace + +Browse and install plugins from the [official marketplace](https://code.claude.com/docs/en/discover-plugins). + +```bash +# Install a plugin +/plugin install plugin-name@claude-plugins-official + +# Update marketplace +/plugin marketplace update claude-plugins-official +``` + +#### Recommended Official Plugins + +| Plugin | Description | Install Command | +|--------|-------------|-----------------| +| [code-simplifier](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/code-simplifier) | Simplifies and refines code for clarity, consistency, and maintainability | `/plugin install code-simplifier` | +| [frontend-design](https://github.com/anthropics/claude-code/tree/main/plugins/frontend-design) | Creates distinctive, production-grade frontend interfaces | `/plugin install frontend-design@claude-code-plugins` | +| [feature-dev](https://github.com/anthropics/claude-code/tree/main/plugins/feature-dev) | Systematic 7-phase approach to building new features | `/plugin install feature-dev@claude-code-plugins` | +| [ralph-wiggum](https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum) | Interactive self-referential AI loops for iterative development | `/plugin install ralph-wiggum@claude-code-plugins` | + +> **Note**: Ralph Wiggum may have issues on some systems. See [#16398](https://github.com/anthropics/claude-code/issues/16398) and [#16389](https://github.com/anthropics/claude-code/issues/16389). Usage guide: [YouTube by Greg Isenberg](https://www.youtube.com/watch?v=RpvQH0r0ecM) | [GitHub](https://github.com/snarktank/ralph) + +#### Third-Party Marketplaces + +| Plugin | Source | Description | Install Commands | +|--------|--------|-------------|------------------| +| [safety-net](https://github.com/kenryu42/claude-code-safety-net) | cc-marketplace | Catches destructive git/filesystem commands before execution | `/plugin marketplace add kenryu42/cc-marketplace`
`/plugin install safety-net@cc-marketplace` | +| [glm-plan-usage](https://docs.z.ai/devpack/extension/usage-query-plugin) | zai-coding-plugins | Query Z.AI usage statistics | `/plugin marketplace add zai/zai-coding-plugins`
`/plugin install glm-plan-usage@zai-coding-plugins` | + +### 3.2 MCP Servers + +MCP (Model Context Protocol) servers extend Claude Code's capabilities by connecting to external tools and documentation. + +#### Recommended MCP Servers + +| Server | Purpose | Transport | Token Cost | Install Command | +|--------|---------|-----------|------------|-----------------| +| [Context7](https://github.com/upstash/context7) | Documentation lookup for any library | SSE | Low | See below | +| [Cloudflare Docs](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/docs-vectorize) | Cloudflare documentation | SSE | Low | See below | +| [Usage Metrics](https://github.com/centminmod/claude-code-opentelemetry-setup) | Claude Code usage and cost tracking | stdio | Low | See below | +| [Gemini CLI](https://github.com/centminmod/gemini-cli-mcp-server) | Access to Gemini models | stdio | Variable | See below | +| [Notion](https://github.com/makenotion/notion-mcp-server) | Notion workspace integration | stdio | Variable | See below | +| [Chrome DevTools](https://github.com/ChromeDevTools/chrome-devtools-mcp) | Browser automation & debugging | stdio | ~17K tokens | See below | + +#### Installation Commands + +**Context7 MCP** (with API key): +```bash +claude mcp add --transport http context7 https://mcp.context7.com/mcp --header "CONTEXT7_API_KEY: YOUR_API_KEY" -s user +``` + +**Cloudflare Documentation MCP**: +```bash +claude mcp add --transport sse cf-docs https://docs.mcp.cloudflare.com/sse -s user +``` + +**Usage Metrics MCP**: +```bash +claude mcp add --transport stdio metrics -s user -- uv run --directory /path/to/your/mcp-server metrics-server +``` + +**Gemini CLI MCP**: +```bash +claude mcp add gemini-cli /path/to/.venv/bin/python /path/to/mcp_server.py -s user -e GEMINI_API_KEY='YOUR_KEY' -e OPENROUTER_API_KEY='YOUR_KEY' +``` + +**Notion MCP**: +```bash +claude mcp add-json notionApi '{"type":"stdio","command":"npx","args":["-y","@notionhq/notion-mcp-server"],"env":{"OPENAPI_MCP_HEADERS":"{\"Authorization\": \"Bearer ntn_API_KEY\", \"Notion-Version\": \"2022-06-28\"}"}}' -s user +``` + +**Chrome DevTools MCP** (high token cost - use on-demand): + +Due to the ~17K token overhead across 26 tools, install only when needed via `--mcp-config`: + +```bash +claude --mcp-config .claude/mcp/chrome-devtools.json +``` + +Create `.claude/mcp/chrome-devtools.json`: +```json +{ + "mcpServers": { + "chrome-devtools": { + "command": "npx", + "args": ["-y", "chrome-devtools-mcp@latest"] + } + } +} +``` + +#### Verify MCP Servers + +```bash +claude mcp list +# Output: +# context7: https://mcp.context7.com/sse (SSE) - ✓ Connected +# cf-docs: https://docs.mcp.cloudflare.com/sse (SSE) - ✓ Connected +# metrics: uv run --directory /path/to/mcp-server metrics-server - ✓ Connected +``` + +#### Usage Metrics Example + +The `get_current_cost` MCP tool returns today's total USD cost: +```json +{ + "metric": "Total Cost Today", + "value": 27.149809833783127, + "formatted": "$27.1498", + "unit": "currencyUSD" +} +``` + +--- + +## 4. Development Workflows + +### 4.1 Git Worktrees for Parallel Sessions + +Git worktrees allow you to run parallel Claude Code sessions with complete code isolation. Each worktree has its own working directory while sharing Git history. + +**Benefits:** +- Run multiple AI coding sessions in parallel +- Each worktree has independent file state +- Changes in one worktree won't affect others +- Ideal for experimental features or YOLO mode + +**Official Documentation:** [Run parallel Claude Code sessions with git worktrees](https://code.claude.com/docs/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) + +#### macOS / Linux Shell Functions + +Add to `~/.bashrc`, `~/.zshrc`, or `~/.bash_aliases`: + +```bash +# Codex CLI worktree launcher +cx() { + local branch_name + if [ -z "$1" ]; then + branch_name="worktree-$(date +%Y%m%d-%H%M%S)" + else + branch_name="$1" + fi + git worktree add "../$branch_name" -b "$branch_name" && \ + cd "../$branch_name" || return 1 + codex -m gpt-5-codex --config model_reasoning_effort='xhigh' +} + +# Claude Code worktree launcher +clx() { + local branch_name + if [ -z "$1" ]; then + branch_name="worktree-$(date +%Y%m%d-%H%M%S)" + else + branch_name="$1" + fi + git worktree add "../$branch_name" -b "$branch_name" && \ + cd "../$branch_name" || return 1 + claude --model opusplan --permission-mode plan +} +``` + +After adding, reload: `source ~/.bashrc` or `source ~/.zshrc` + +
+Windows PowerShell Functions + +Add to your PowerShell profile (`notepad $PROFILE`): + +```powershell +# Codex CLI worktree launcher +function cx { + param([string]$BranchName) + if (-not $BranchName) { + $BranchName = "worktree-$(Get-Date -Format 'yyyyMMdd-HHmmss')" + } + git worktree add "../$BranchName" -b $BranchName + if ($LASTEXITCODE -eq 0) { + Set-Location "../$BranchName" + codex -m gpt-5-codex --config model_reasoning_effort='xhigh' + } +} + +# Claude Code worktree launcher +function clx { + param([string]$BranchName) + if (-not $BranchName) { + $BranchName = "worktree-$(Get-Date -Format 'yyyyMMdd-HHmmss')" + } + git worktree add "../$BranchName" -b $BranchName + if ($LASTEXITCODE -eq 0) { + Set-Location "../$BranchName" + claude --model opusplan --permission-mode plan + } +} +``` + +Reload: `. $PROFILE` + +
+ +
+Windows CMD Batch Files + +Create in a directory in your PATH (e.g., `C:\Users\YourName\bin\`): + +**cx.bat** - Codex CLI launcher: +```batch +@echo off +setlocal enabledelayedexpansion +if "%~1"=="" ( + for /f "tokens=2 delims==" %%I in ('wmic os get localdatetime /value') do set datetime=%%I + set branch_name=worktree-!datetime:~0,8!-!datetime:~8,6! +) else ( + set branch_name=%~1 +) +git worktree add "../%branch_name%" -b "%branch_name%" +if %errorlevel% equ 0 ( + cd "../%branch_name%" + codex -m gpt-5-codex --config model_reasoning_effort='xhigh' +) +endlocal +``` + +**clx.bat** - Claude Code launcher: +```batch +@echo off +setlocal enabledelayedexpansion +if "%~1"=="" ( + for /f "tokens=2 delims==" %%I in ('wmic os get localdatetime /value') do set datetime=%%I + set branch_name=worktree-!datetime:~0,8!-!datetime:~8,6! +) else ( + set branch_name=%~1 +) +git worktree add "../%branch_name%" -b "%branch_name%" +if %errorlevel% equ 0 ( + cd "../%branch_name%" + claude --model opusplan --permission-mode plan +) +endlocal +``` + +
+ +#### Usage + +```bash +# Create worktree with custom name +clx feature-auth +cx bugfix-123 + +# Create worktree with auto-generated timestamp name +clx +cx +``` + +#### Worktree Management + +```bash +# List all worktrees +git worktree list + +# Remove a worktree when done +git worktree remove ../worktree-name + +# Clean up stale worktree references +git worktree prune +``` + +#### Environment Setup + +Each new worktree needs its own development environment: +- **JavaScript/Node.js**: Run `npm install` or `yarn` +- **Python**: Create virtual environment or run `pip install -r requirements.txt` +- **Other languages**: Follow your project's standard setup process + +#### The .worktreeinclude File + +When Claude Code creates a worktree, files ignored via `.gitignore` aren't automatically available. The `.worktreeinclude` file specifies which ignored files should be copied. + +**How It Works:** +- Uses `.gitignore`-style patterns +- Only files matched by **both** `.worktreeinclude` **AND** `.gitignore` are copied + +Create `.worktreeinclude` in your repository root: +```text +# Environment files +.env +.env.local +.env.* + +# Claude Code local settings +**/.claude/settings.local.json +``` + +**Common Use Cases:** +- `.env` files with API keys and secrets +- `.env.local` for local development overrides +- `.claude/settings.local.json` for personal Claude Code settings + +#### Claude Desktop Worktree Location + +When using Claude Code via the Claude Desktop app: +- Default location: `~/.claude-worktrees` +- Configurable through Claude Desktop app settings +- Repository must be Git initialized for worktree sessions + +**Official Documentation:** [Claude Code on Desktop](https://code.claude.com/docs/en/desktop#claude-code-on-desktop-preview) + +#### Local Ignores Without .gitignore + +Use `.git/info/exclude` to ignore files locally without modifying shared `.gitignore`: + +```bash +# Edit the local exclude file +nano .git/info/exclude +``` + +Add patterns: +```text +# Local IDE settings +.idea/ +*.swp + +# Personal scripts +my-local-scripts/ +``` + +| File | Scope | Committed to Git | +|------|-------|------------------| +| `.gitignore` | Shared with team | Yes | +| `.git/info/exclude` | Local only | No | +| `~/.config/git/ignore` | Global (all repos) | No | + +### 4.2 Status Lines + +Configure custom status lines in `~/.claude/settings.json`: + +```json +{ + "statusLine": { + "type": "command", + "command": "~/.claude/statuslines/statusline.sh", + "padding": 0 + } +} +``` + +#### Example Status Line Script + +Create `~/.claude/statuslines/statusline.sh`: + +```bash +#!/bin/bash +# Read JSON input from stdin +input=$(cat) + +# Extract model and workspace values +MODEL_DISPLAY=$(echo "$input" | jq -r '.model.display_name') +CURRENT_DIR=$(echo "$input" | jq -r '.workspace.current_dir') + +# Extract context window metrics +INPUT_TOKENS=$(echo "$input" | jq -r '.context_window.total_input_tokens') +OUTPUT_TOKENS=$(echo "$input" | jq -r '.context_window.total_output_tokens') +CONTEXT_SIZE=$(echo "$input" | jq -r '.context_window.context_window_size') + +# Extract cost metrics +COST_USD=$(echo "$input" | jq -r '.cost.total_cost_usd') +LINES_ADDED=$(echo "$input" | jq -r '.cost.total_lines_added') +LINES_REMOVED=$(echo "$input" | jq -r '.cost.total_lines_removed') + +# Format tokens as Xk +format_tokens() { + local num="$1" + if [ "$num" -ge 1000 ]; then + echo "$((num / 1000))k" + else + echo "$num" + fi +} + +# Calculate total +TOTAL_TOKENS=$((INPUT_TOKENS + OUTPUT_TOKENS)) + +# Show git branch if in a git repo +GIT_BRANCH="" +if git rev-parse --git-dir > /dev/null 2>&1; then + BRANCH=$(git branch --show-current 2>/dev/null) + if [ -n "$BRANCH" ]; then + GIT_BRANCH=" | 🌿 $BRANCH" + fi +fi + +echo "[$MODEL_DISPLAY] 📁 ${CURRENT_DIR##*/}${GIT_BRANCH} +Tokens: $(format_tokens "$TOTAL_TOKENS") (in:$(format_tokens "$INPUT_TOKENS")+out:$(format_tokens "$OUTPUT_TOKENS")) | Ctx:$(format_tokens "$CONTEXT_SIZE") +Cost: \$${COST_USD} | +${LINES_ADDED} -${LINES_REMOVED} lines" +``` + +### 4.3 IDE Integration + +- **VS Code Extension**: [Claude Code for VS Code](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code) +- **Dev Containers**: [Isolated dev environment](https://claude-devcontainers.centminmod.com/) with Claude Code, Codex CLI, Gemini CLI, and YOLO mode support + +--- + +# ADVANCED SECTION + +--- + +## 5. Customization + +### 5.1 Custom Subagents + +Subagents are specialized tools that handle complex, multi-step tasks autonomously with their own context window and custom prompts. Learn more in the [official documentation](https://docs.anthropic.com/en/docs/claude-code/sub-agents). + +#### Included Subagents + +| Agent | Location | Purpose | +|-------|----------|---------| +| **memory-bank-synchronizer** | `.claude/agents/` | Synchronizes memory bank documentation with codebase state | +| **code-searcher** | `.claude/agents/` | Efficient codebase navigation with optional Chain of Draft mode | +| **get-current-datetime** | `.claude/agents/` | Accurate Brisbane timezone (GMT+10) values | +| **ux-design-expert** | `.claude/agents/` | Comprehensive UX/UI design guidance with Tailwind CSS & Highcharts | + +#### memory-bank-synchronizer + +Proactively maintains consistency between CLAUDE-*.md files and source code: +- Pattern documentation synchronization +- Architecture decision updates +- Technical specification alignment +- Implementation status tracking + +#### code-searcher + +Efficiently searches the codebase with two modes: +- **Standard mode**: Full detailed analysis +- **CoD mode**: ~80% fewer tokens with ultra-concise responses + +``` +# Standard: "Find the payment processing code" +# CoD: "Find the payment processing code using CoD" +``` + +#### get-current-datetime + +Returns accurate Brisbane, Australia (GMT+10) timestamps: +- Supports multiple formats (default, filename, readable, ISO) +- Eliminates timezone confusion + +#### ux-design-expert + +Comprehensive UX/UI guidance: +- UX flow optimization +- Premium UI design with Tailwind CSS +- Data visualization with Highcharts +- Accessibility compliance + +### 5.2 Custom Skills + +Skills provide specialized capabilities. See [Agent Skills documentation](https://docs.claude.com/en/docs/claude-code/skills). + +#### Included Skills + +| Skill | Purpose | Invocation | +|-------|---------|------------| +| **claude-docs-consultant** | Selectively fetches official Claude Code documentation from docs.claude.com | Automatic when working on Claude Code features | + +### 5.3 Custom Slash Commands + +#### `/anthropic` Commands + +| Command | Purpose | +|---------|---------| +| `/apply-thinking-to` | Applies Anthropic's extended thinking patterns to enhance prompts | +| `/convert-to-todowrite-tasklist-prompt` | Converts prompts to TodoWrite tasklist methods (60-70% speed improvement) | +| `/update-memory-bank` | Updates CLAUDE.md and memory bank files | + +#### `/ccusage` Commands + +| Command | Purpose | +|---------|---------| +| `/ccusage-daily` | Generates comprehensive usage cost analysis with daily breakdowns | + +#### `/cleanup` Commands + +| Command | Purpose | +|---------|---------| +| `/cleanup-context` | Memory bank optimization (15-25% token reduction) | + +#### `/documentation` Commands + +| Command | Purpose | +|---------|---------| +| `/create-readme-section` | Generates README sections with professional formatting | +| `/create-release-note` | Creates dual release notes (customer-facing + technical) | + +#### `/security` Commands + +| Command | Purpose | +|---------|---------| +| `/security-audit` | Comprehensive security audit using OWASP guidelines | +| `/check-best-practices` | Analyzes code against language-specific best practices | +| `/secure-prompts` | Detects prompt injection attacks and malicious instructions | + +Example test prompts at `.claude/commands/security/test-examples/` + +#### `/architecture` Commands + +| Command | Purpose | +|---------|---------| +| `/explain-architecture-pattern` | Identifies and explains architectural patterns | + +#### `/promptengineering` Commands + +| Command | Purpose | +|---------|---------| +| `/convert-to-test-driven-prompt` | Transforms requests into TDD-style prompts | +| `/batch-operations-prompt` | Optimizes prompts for parallel processing | + +#### `/refactor` Commands + +| Command | Purpose | +|---------|---------| +| `/refactor-code` | Creates detailed refactoring plans with risk assessment | + +### 5.4 Hooks System + +Hooks run custom commands before or after tool execution. + +#### Included Hooks + +The `STOP` hook uses Terminal-Notifier for macOS desktop notifications when Claude Code completes a response. Setup: [Terminal-Notifier](https://github.com/centminmod/terminal-notifier-setup) + +--- + +## 6. Alternative Providers + +### 6.1 Using Z.AI with Claude Code + +[Z.AI's GLM Coding Plan](https://z.ai) provides cost-effective access to high-performance language models optimized for coding. + +> **10% Discount**: Use invite code [`WWB8IFLROM`](https://z.ai/subscribe?ic=WWB8IFLROM) + +#### Overview + +- **Performance**: 55+ tokens/second for real-time interaction +- **Features**: Vision Understanding, Web Search, Web Reader MCP servers +- **Multimodal**: GLM-4.7 with state-of-the-art reasoning capabilities + +#### Pricing & Plans + +| Plan | Prompts/5hrs | Approx. Monthly Cost | vs Claude | +|------|--------------|---------------------|-----------| +| Lite | ~120 | ~$3 | 3× Claude Pro quota | +| Pro | ~600 | Higher | 3× Claude Max 5x quota | +| Max | ~2,400 | Higher | 3× Claude Max 20x quota | + +Each prompt allows 15–20 model calls, yielding billions of tokens monthly at ~1% of standard API pricing. + +#### Privacy & Data Handling + +- **Data Location**: Singapore +- **Privacy Guarantee**: Z.AI does not store any content you provide or generate +- See [Privacy Policy](https://docs.z.ai/legal-agreement/privacy-policy) + +#### Prerequisites + +- Node.js 18+ +- Z.AI API key from [Z.AI dashboard](https://z.ai) +- [Official documentation](https://docs.z.ai/devpack/tool/claude) + +#### Setup Instructions + +**Option 1: Automated Setup** (macOS/Linux only) + +```bash +curl -O "https://cdn.bigmodel.cn/install/claude_code_zai_env.sh" && bash ./claude_code_zai_env.sh +``` + +**Option 2: Manual Configuration** + +Edit `~/.claude/settings.json`: +```json +{ + "env": { + "ANTHROPIC_AUTH_TOKEN": "your-zai-api-key", + "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic", + "API_TIMEOUT_MS": "3000000" + } +} +``` + +#### Shell Function Launchers + +The easiest way to use Z.AI without affecting your existing Claude Code setup. + +**macOS / Linux (Bash/Zsh)** + +Add to `~/.bashrc`, `~/.zshrc`, or `~/.bash_aliases`: + +```bash +# Z.AI + Claude Code launcher +zai() { + export ANTHROPIC_AUTH_TOKEN="your-zai-api-key" + export ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic" + export API_TIMEOUT_MS="3000000" + claude "$@" +} +``` + +Reload: `source ~/.bashrc` or `source ~/.zshrc` + +
+Windows PowerShell + +Add to PowerShell profile (`notepad $PROFILE`): + +```powershell +# Z.AI + Claude Code launcher +function zai { + $env:ANTHROPIC_AUTH_TOKEN = "your-zai-api-key" + $env:ANTHROPIC_BASE_URL = "https://api.z.ai/api/anthropic" + $env:API_TIMEOUT_MS = "3000000" + claude $args +} +``` + +Reload: `. $PROFILE` + +
+ +
+Windows CMD Batch + +Create `zai.bat` in a directory in your PATH: + +```batch +@echo off +set ANTHROPIC_AUTH_TOKEN=your-zai-api-key +set ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic +set API_TIMEOUT_MS=3000000 +claude %* +``` + +
+ +#### Model Mapping + +GLM Coding Plan maps Claude model names to GLM models: + +| Claude Model | GLM Model | +|--------------|-----------| +| Opus | GLM-4.7 | +| Sonnet | GLM-4.7 | +| Haiku | GLM-4.5-Air | + +**Customizing Model Mappings** (optional): + +In `~/.claude/settings.json`: +```json +{ + "env": { + "ANTHROPIC_AUTH_TOKEN": "your-zai-api-key", + "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic", + "API_TIMEOUT_MS": "3000000", + "ANTHROPIC_DEFAULT_OPUS_MODEL": "GLM-4.7", + "ANTHROPIC_DEFAULT_SONNET_MODEL": "GLM-4.5", + "ANTHROPIC_DEFAULT_HAIKU_MODEL": "GLM-4.5-Air" + } +} +``` + +Or in shell function: + +```bash +zai() { + export ANTHROPIC_AUTH_TOKEN="your-zai-api-key" + export ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic" + export API_TIMEOUT_MS="3000000" + export ANTHROPIC_DEFAULT_OPUS_MODEL="GLM-4.7" + export ANTHROPIC_DEFAULT_SONNET_MODEL="GLM-4.5" + export ANTHROPIC_DEFAULT_HAIKU_MODEL="GLM-4.5-Air" + claude "$@" +} +``` + +
+Windows PowerShell Model Mapping + +```powershell +function zai { + $env:ANTHROPIC_AUTH_TOKEN = "your-zai-api-key" + $env:ANTHROPIC_BASE_URL = "https://api.z.ai/api/anthropic" + $env:API_TIMEOUT_MS = "3000000" + $env:ANTHROPIC_DEFAULT_OPUS_MODEL = "GLM-4.7" + $env:ANTHROPIC_DEFAULT_SONNET_MODEL = "GLM-4.5" + $env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "GLM-4.5-Air" + claude $args +} +``` + +
+ +
+Windows CMD Model Mapping + +```batch +@echo off +set ANTHROPIC_AUTH_TOKEN=your-zai-api-key +set ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic +set API_TIMEOUT_MS=3000000 +set ANTHROPIC_DEFAULT_OPUS_MODEL=GLM-4.7 +set ANTHROPIC_DEFAULT_SONNET_MODEL=GLM-4.5 +set ANTHROPIC_DEFAULT_HAIKU_MODEL=GLM-4.5-Air +claude %* +``` + +
+ +#### Usage + +```bash +# Launch with Z.AI configuration +zai + +# Launch with specific model +zai --model sonnet + +# Launch with permission mode +zai --model opus --permission-mode plan +``` + +#### Z.AI + Git Worktree Integration + +Combine Z.AI with git worktrees for isolated parallel sessions. + +**macOS / Linux (Bash/Zsh)** + +```bash +# Z.AI + Claude Code worktree launcher +zaix() { + local branch_name + if [ -z "$1" ]; then + branch_name="worktree-$(date +%Y%m%d-%H%M%S)" + else + branch_name="$1" + fi + git worktree add "../$branch_name" -b "$branch_name" && \ + cd "../$branch_name" || return 1 + + export ANTHROPIC_AUTH_TOKEN="your-zai-api-key" + export ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic" + export API_TIMEOUT_MS="3000000" + claude --model sonnet --permission-mode plan +} +``` + +
+Windows PowerShell Z.AI + Worktree + +```powershell +# Z.AI + Claude Code worktree launcher +function zaix { + param([string]$BranchName) + if (-not $BranchName) { + $BranchName = "worktree-$(Get-Date -Format 'yyyyMMdd-HHmmss')" + } + git worktree add "../$BranchName" -b $BranchName + if ($LASTEXITCODE -eq 0) { + Set-Location "../$BranchName" + $env:ANTHROPIC_AUTH_TOKEN = "your-zai-api-key" + $env:ANTHROPIC_BASE_URL = "https://api.z.ai/api/anthropic" + $env:API_TIMEOUT_MS = "3000000" + claude --model sonnet --permission-mode plan + } +} +``` + +
+ +
+Windows CMD Z.AI + Worktree + +Create `zaix.bat`: + +```batch +@echo off +setlocal enabledelayedexpansion +if "%~1"=="" ( + for /f "tokens=2 delims==" %%I in ('wmic os get localdatetime /value') do set datetime=%%I + set branch_name=worktree-!datetime:~0,8!-!datetime:~8,6! +) else ( + set branch_name=%~1 +) +git worktree add "../%branch_name%" -b "%branch_name%" +if %errorlevel% equ 0 ( + cd "../%branch_name%" + set ANTHROPIC_AUTH_TOKEN=your-zai-api-key + set ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic + set API_TIMEOUT_MS=3000000 + claude --model sonnet --permission-mode plan +) +endlocal +``` + +
+ +**Usage:** +```bash +# Create worktree with custom name +zaix feature-auth + +# Create worktree with auto-generated timestamp name +zaix +``` + +--- + +## 7. Cost & Rate Management + +### 7.1 Claude Plan Weekly Rate Limits + +From August 28, 2025, weekly rate limits apply in addition to monthly 50x 5hr session limits: + +| Plan | Sonnet 4 (hrs/week) | Opus 4 (hrs/week) | +|------|---------------------|-------------------| +| Pro | 40–80 | – | +| Max ($100/mo) | 140–280 | 15–35 | +| Max ($200/mo) | 240–480 | 24–40 | + +### 7.2 Cost Tracking + +Use the Usage Metrics MCP server to track costs: +```bash +claude mcp add --transport stdio metrics -s user -- uv run --directory /path/to/mcp-server metrics-server +``` + +Or use the `/ccusage-daily` slash command for detailed cost analysis. + +### 7.3 Optimization Tips + +- Use **Z.AI** for higher quotas at lower cost +- Configure **status lines** to monitor real-time usage +- Use **git worktrees** for parallel sessions without duplicating quota +- Leverage **CoD mode** in code-searcher for 80% token reduction + +--- + +# REFERENCE SECTION + +--- + +## 8. Configuration Reference + +### 8.1 Settings Scopes + +| Scope | Location | Affects | Shared? | +|-------|----------|---------|---------| +| Managed | System directories | All users | By IT | +| User | `~/.claude/settings.json` | You (all projects) | No | +| Project | `.claude/settings.json` | All collaborators | Yes | +| Local | `.claude/settings.local.json` | You (this project) | No | + +**Precedence** (highest to lowest): +1. Enterprise policies +2. Command line arguments +3. Local project settings +4. Shared project settings +5. User settings + +### 8.2 settings.json Options + +| Key | Description | Example | +|-----|-------------|---------| +| `apiKeyHelper` | Script to generate auth value | `/bin/generate_temp_api_key.sh` | +| `cleanupPeriodDays` | Days to retain chat transcripts (default: 30) | `20` | +| `env` | Environment variables for every session | `{"FOO": "bar"}` | +| `includeCoAuthoredBy` | Include `co-authored-by Claude` in commits | `false` | +| `permissions` | Permission rules (see below) | | + +#### Permission Settings + +| Key | Description | Example | +|-----|-------------|---------| +| `allow` | Array of allowed tool use rules | `["Bash(git diff:*)"]` | +| `deny` | Array of denied tool use rules | `["WebFetch", "Bash(curl:*)"]` | +| `additionalDirectories` | Additional working directories | `["../docs/"]` | +| `defaultMode` | Default permission mode | `"acceptEdits"` | +| `disableBypassPermissionsMode` | Prevent bypass mode | `"disable"` | + +### 8.3 Environment Variables + +| Variable | Purpose | +|----------|---------| +| `ANTHROPIC_API_KEY` | API key for Claude SDK | +| `ANTHROPIC_AUTH_TOKEN` | Custom auth header value | +| `ANTHROPIC_BASE_URL` | Custom API endpoint | +| `ANTHROPIC_MODEL` | Custom model name | +| `ANTHROPIC_SMALL_FAST_MODEL` | Haiku-class model for background tasks | +| `BASH_DEFAULT_TIMEOUT_MS` | Default bash command timeout | +| `BASH_MAX_TIMEOUT_MS` | Maximum bash command timeout | +| `BASH_MAX_OUTPUT_LENGTH` | Max characters before truncation | +| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Max output tokens per request | +| `CLAUDE_CODE_USE_BEDROCK` | Use Amazon Bedrock | +| `CLAUDE_CODE_USE_VERTEX` | Use Google Vertex AI | +| `DISABLE_AUTOUPDATER` | Disable automatic updates | +| `DISABLE_TELEMETRY` | Opt out of Statsig telemetry | +| `HTTP_PROXY` / `HTTPS_PROXY` | Proxy server settings | +| `MAX_THINKING_TOKENS` | Force thinking budget | +| `MCP_TIMEOUT` | MCP server startup timeout | +| `MCP_TOOL_TIMEOUT` | MCP tool execution timeout | +| `MAX_MCP_OUTPUT_TOKENS` | Max MCP response tokens (default: 25000) | + +### 8.4 File Locations by OS + +| File | macOS | Linux | Windows | +|------|-------|-------|---------| +| User settings | `~/.claude/settings.json` | `~/.claude/settings.json` | `%USERPROFILE%\.claude\settings.json` | +| Project settings | `.claude/settings.json` | `.claude/settings.json` | `.claude\settings.json` | +| Local settings | `.claude/settings.local.json` | `.claude/settings.local.json` | `.claude\settings.local.json` | + +### 8.5 Tools Available to Claude + +| Tool | Description | Permission Required | +|------|-------------|---------------------| +| Agent | Runs sub-agents for complex tasks | No | +| Bash | Executes shell commands | Yes | +| Edit | Makes targeted file edits | Yes | +| Glob | Finds files by pattern | No | +| Grep | Searches file contents | No | +| LS | Lists files and directories | No | +| MultiEdit | Multiple edits atomically | Yes | +| NotebookEdit | Modifies Jupyter cells | Yes | +| NotebookRead | Reads Jupyter notebooks | No | +| Read | Reads file contents | No | +| TodoRead | Reads task list | No | +| TodoWrite | Creates/manages task lists | No | +| WebFetch | Fetches URL content | Yes | +| WebSearch | Performs web searches | Yes | +| Write | Creates/overwrites files | Yes | + +### 8.6 Configuration Commands + +```bash +# List settings +claude config list + +# Get a setting +claude config get + +# Set a setting +claude config set + +# Add to a list setting +claude config add + +# Remove from a list setting +claude config remove + +# Global configuration +claude config set -g +``` + +#### Global Configuration Options + +| Key | Description | Example | +|-----|-------------|---------| +| `autoUpdates` | Enable automatic updates (default: true) | `false` | +| `preferredNotifChannel` | Notification method | `iterm2`, `terminal_bell`, `notifications_disabled` | +| `theme` | Color theme | `dark`, `light`, `light-daltonized`, `dark-daltonized` | +| `verbose` | Show full command outputs | `true` | + +--- + +## 9. Resources + +### Official Documentation + +- [Claude Code Overview](https://docs.anthropic.com/en/docs/claude-code/overview) +- [Claude Code Settings](https://code.claude.com/docs/en/settings) +- [Claude Code Hooks](https://code.claude.com/docs/en/hooks) +- [Claude Code Skills](https://docs.claude.com/en/docs/claude-code/skills) +- [Claude Code Sub-agents](https://docs.anthropic.com/en/docs/claude-code/sub-agents) +- [Plugin Marketplace](https://code.claude.com/docs/en/discover-plugins) + +### YouTube Guides + +- [Advent of Claude: 31 Days of Claude Code](https://adocomplete.com/advent-of-claude-2025/) - Ado Kukic (Anthropic) +- [Claude Code with Opus 4.5](https://www.youtube.com/watch?v=UVJXh57MgI0) - Alex Finn +- [Claude Code Overview](https://www.youtube.com/watch?v=Dekx_OzRwiI) - Matt Maher +- [VS Code Beginner Guide](https://www.youtube.com/watch?v=rPITZvwyoMc) +- [Ralph Wiggum Tutorial](https://www.youtube.com/watch?v=RpvQH0r0ecM) - Greg Isenberg & Ryan Carson + +--- + +## Star History + +[![Star History Chart](https://api.star-history.com/svg?repos=centminmod/my-claude-code-setup&type=Date)](https://www.star-history.com/#centminmod/my-claude-code-setup&Date) + +--- + +## Stats + +![Alt](https://repobeats.axiom.co/api/embed/715da1679915da77d87deb99a1f527a44e76ec60.svg "Repobeats analytics image") diff --git a/README-v3.md b/README-v3.md new file mode 100644 index 0000000..b6351c3 --- /dev/null +++ b/README-v3.md @@ -0,0 +1,962 @@ +[![GitHub stars](https://img.shields.io/github/stars/centminmod/my-claude-code-setup.svg?style=flat-square)](https://github.com/centminmod/my-claude-code-setup/stargazers) [![GitHub forks](https://img.shields.io/github/forks/centminmod/my-claude-code-setup.svg?style=flat-square)](https://github.com/centminmod/my-claude-code-setup/network) [![GitHub issues](https://img.shields.io/github/issues/centminmod/my-claude-code-setup.svg?style=flat-square)](https://github.com/centminmod/my-claude-code-setup/issues) + +* Threads - https://www.threads.com/@george_sl_liu +* BlueSky - https://bsky.app/profile/georgesl.bsky.social + +# My Claude Code Setup + +## What This Repository Provides + +- **Starter Settings** for Claude Code projects with optimized configurations +- **Memory Bank System** for context retention across chat sessions +- **Pre-configured Hooks, Skills, and Subagents** for enhanced productivity +- **MCP Server Recommendations** for extending Claude Code capabilities + +## Quick Navigation + +| What do you want to do? | Jump to | +|------------------------|---------| +| Install & get started | [Getting Started](#getting-started) | +| Set up persistent memory | [Memory Bank System](#i-want-to-set-up-the-memory-bank-system) | +| Add plugins to Claude Code | [Plugins](#i-want-to-extend-claude-code-with-plugins) | +| Connect external tools | [MCP Servers](#i-want-to-connect-external-tools-mcp) | +| Run parallel AI sessions | [Git Worktrees](#i-want-to-run-parallel-ai-coding-sessions) | +| Customize Claude's behavior | [Customization](#i-want-to-customize-claudes-behavior) | +| Use Z.AI for higher quotas | [Z.AI Integration](#i-want-to-use-zai-for-higher-quotas) | +| Monitor costs and usage | [Costs & Usage](#i-want-to-monitor-costs-and-usage) | +| Look up settings/config | [Configuration Reference](#configuration-reference) | + +--- + +## Getting Started + +### Prerequisites + +| Requirement | Notes | +|------------|-------| +| [Claude AI Account](https://claude.ai/) | Pro ($20/mo), Max ($100/mo), or Max ($200/mo) | +| Node.js 18+ | Runtime environment | +| Git | Version control | +| ripgrep, fd, jq | Fast tools (macOS: `brew install ripgrep fd jq`) | + +### Installation Options + +Choose the approach that works best for you: + +#### Option A: Clone Entire Repository (New Projects) + +```bash +# 1. Clone this repository as your new project +git clone https://github.com/centminmod/my-claude-code-setup.git my-project +cd my-project + +# 2. Remove template README files (create your own) +rm README.md README-v2.md README-v3.md README-v4.md + +# 3. Reinitialize git for your own project (optional) +rm -rf .git +git init + +# 4. Launch Claude Code and initialize +claude +# Then run: /init +``` + +#### Option B: Selective Copy (Existing Projects) + +Copy only what you need into your existing project: + +```bash +# Core files (recommended) +cp /path/to/my-claude-code-setup/CLAUDE.md your-project/ +cp -r /path/to/my-claude-code-setup/.claude your-project/ + +# Or pick specific components: +cp -r /path/to/my-claude-code-setup/.claude/commands your-project/.claude/ +cp -r /path/to/my-claude-code-setup/.claude/skills your-project/.claude/ +cp -r /path/to/my-claude-code-setup/.claude/agents your-project/.claude/ +cp -r /path/to/my-claude-code-setup/.claude/hooks your-project/.claude/ +``` + +#### Option C: Download from GitHub + +Browse the repository and download individual files: +- `CLAUDE.md` - Memory bank main file +- `.claude/settings.json` - Settings template +- `.claude/commands/` - Slash commands +- `.claude/skills/` - Skills +- `.claude/agents/` - Subagents + +### What Happens Next? + +1. Claude Code analyzes your codebase +2. Memory bank files are populated based on your project +3. You're ready to start coding with persistent context! + +### Optional Enhancements + +- **VS Code Integration**: Install [Claude Code Extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code) +- **GitHub Setup**: Configure Git for VS Code ([guide](https://www.youtube.com/watch?v=twsYxYaQikI)) +- **Dev Container**: Use the [isolated dev environment](https://claude-devcontainers.centminmod.com/) for YOLO mode +- **Platform Docs**: Add `CLAUDE-cloudflare.md` for Cloudflare/ClerkOS or `CLAUDE-convex.md` for Convex + +### Learning Resources + +- [Advent of Claude: 31 Days](https://adocomplete.com/advent-of-claude-2025/) by Ado Kukic (Anthropic) +- [Claude Code with Opus 4.5](https://www.youtube.com/watch?v=UVJXh57MgI0) by Alex Finn +- [Claude Code Overview](https://www.youtube.com/watch?v=Dekx_OzRwiI) by Matt Maher + +--- + +## I want to set up the memory bank system + +### What is Memory Bank? + +The Memory Bank System helps Claude Code remember context across chat sessions. Instead of starting fresh each time, Claude reads structured markdown files to understand your project's patterns, decisions, and current state. + +### Core Context Files + +| File | What it stores | +|------|---------------| +| `CLAUDE.md` | Main entry point with project overview and AI guidance | +| `CLAUDE-activeContext.md` | Current session state, goals, and progress | +| `CLAUDE-patterns.md` | Established code patterns and conventions | +| `CLAUDE-decisions.md` | Architecture decisions and rationale (ADRs) | +| `CLAUDE-troubleshooting.md` | Common issues and proven solutions | +| `CLAUDE-config-variables.md` | Configuration variables reference | +| `CLAUDE-temp.md` | Temporary scratch pad (only read when referenced) | + +### Initial Setup + +1. Copy template files from this repository to your project root +2. Run `/init` in Claude Code +3. Claude analyzes your codebase and populates the memory bank + +### Updating Memory Bank + +After completing significant work: + +``` +update memory bank +``` + +Claude Code will update all relevant CLAUDE-*.md files with your latest changes. + +### Example Output + +``` +> update memory bank + +∴ Thinking… + I'll update the memory bank files to reflect the v0.1.6 changes... + +⏺ Summary: v0.1.6 Release Complete ✅ + + Memory Bank Updates Complete: + - CLAUDE-activeContext.md - v0.1.6 session context + - CLAUDE-patterns.md - Added patterns 22-24 + - CLAUDE-decisions.md - Added ADR-017 & ADR-018 + - CLAUDE-troubleshooting.md - Added 4 new issue/fix entries + + Test Results: All 29 tests passing +``` + +> **See also:** [Customization](#i-want-to-customize-claudes-behavior) for creating custom subagents that sync memory bank with code + +--- + +## I want to extend Claude Code with plugins + +### Official Anthropic Marketplace + +Browse plugins at the [official marketplace](https://code.claude.com/docs/en/discover-plugins). + +```bash +# Install a plugin +/plugin install plugin-name@claude-plugins-official + +# Update marketplace +/plugin marketplace update claude-plugins-official +``` + +### Recommended Plugins + +| Plugin | What it does | Install | +|--------|-------------|---------| +| [code-simplifier](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/code-simplifier) | Simplifies code for clarity and maintainability | `/plugin install code-simplifier` | +| [frontend-design](https://github.com/anthropics/claude-code/tree/main/plugins/frontend-design) | Creates production-grade frontend interfaces | `/plugin install frontend-design@claude-code-plugins` | +| [feature-dev](https://github.com/anthropics/claude-code/tree/main/plugins/feature-dev) | 7-phase approach to building features | `/plugin install feature-dev@claude-code-plugins` | +| [ralph-wiggum](https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum) | Iterative AI loops for development | `/plugin install ralph-wiggum@claude-code-plugins` | + +> **Note**: Ralph Wiggum has issues on some systems ([#16398](https://github.com/anthropics/claude-code/issues/16398), [#16389](https://github.com/anthropics/claude-code/issues/16389)). [Usage video](https://www.youtube.com/watch?v=RpvQH0r0ecM) + +### Third-Party Plugins + +**Safety Net** - Catches destructive commands before execution: +```bash +/plugin marketplace add kenryu42/cc-marketplace +/plugin install safety-net@cc-marketplace +``` + +**Z.AI Usage Query** - Query Z.AI usage statistics: +```bash +/plugin marketplace add zai/zai-coding-plugins +/plugin install glm-plan-usage@zai-coding-plugins +``` + +> **See also:** [MCP Servers](#i-want-to-connect-external-tools-mcp) for connecting external tools + +--- + +## I want to connect external tools (MCP) + +### What is MCP? + +MCP (Model Context Protocol) servers extend Claude Code by connecting to external tools, documentation, and services. + +### Recommended MCP Servers + +| Server | What it does | Install | +|--------|-------------|---------| +| [Context7](https://github.com/upstash/context7) | Look up docs for any library | `claude mcp add --transport http context7 https://mcp.context7.com/mcp --header "CONTEXT7_API_KEY: YOUR_KEY" -s user` | +| [Cloudflare Docs](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/docs-vectorize) | Cloudflare documentation | `claude mcp add --transport sse cf-docs https://docs.mcp.cloudflare.com/sse -s user` | +| [Usage Metrics](https://github.com/centminmod/claude-code-opentelemetry-setup) | Track Claude Code costs | `claude mcp add --transport stdio metrics -s user -- uv run --directory /path/to/mcp-server metrics-server` | +| [Gemini CLI](https://github.com/centminmod/gemini-cli-mcp-server) | Access Gemini models | `claude mcp add gemini-cli /path/to/.venv/bin/python /path/to/mcp_server.py -s user -e GEMINI_API_KEY='KEY'` | +| [Notion](https://github.com/makenotion/notion-mcp-server) | Notion workspace integration | See below | + +### Installing Notion MCP + +```bash +claude mcp add-json notionApi '{"type":"stdio","command":"npx","args":["-y","@notionhq/notion-mcp-server"],"env":{"OPENAPI_MCP_HEADERS":"{\"Authorization\": \"Bearer ntn_API_KEY\", \"Notion-Version\": \"2022-06-28\"}"}}' -s user +``` + +### Chrome DevTools MCP (On-Demand) + +Due to ~17K token overhead, install only when needed: + +```bash +claude --mcp-config .claude/mcp/chrome-devtools.json +``` + +Create `.claude/mcp/chrome-devtools.json`: +```json +{ + "mcpServers": { + "chrome-devtools": { + "command": "npx", + "args": ["-y", "chrome-devtools-mcp@latest"] + } + } +} +``` + +### Verify Installation + +```bash +claude mcp list +# context7: ✓ Connected +# cf-docs: ✓ Connected +# metrics: ✓ Connected +``` + +### Example: Cost Tracking + +The `get_current_cost` tool returns: +```json +{ + "metric": "Total Cost Today", + "formatted": "$27.15", + "unit": "currencyUSD" +} +``` + +> **See also:** [Plugins](#i-want-to-extend-claude-code-with-plugins) for the official plugin system + +--- + +## I want to run parallel AI coding sessions + +### Why Git Worktrees? + +Git worktrees let you run multiple Claude Code sessions with complete code isolation. Each worktree has its own working directory while sharing Git history. + +**Benefits:** +- Run parallel AI sessions simultaneously +- Each worktree has independent file state +- Changes won't interfere between sessions +- Perfect for experimental features or YOLO mode + +### Setup Shell Functions + +**macOS / Linux** - Add to `~/.bashrc` or `~/.zshrc`: + +```bash +# Claude Code worktree launcher +clx() { + local branch_name + if [ -z "$1" ]; then + branch_name="worktree-$(date +%Y%m%d-%H%M%S)" + else + branch_name="$1" + fi + git worktree add "../$branch_name" -b "$branch_name" && \ + cd "../$branch_name" || return 1 + claude --model opusplan --permission-mode plan +} + +# Codex CLI worktree launcher +cx() { + local branch_name + if [ -z "$1" ]; then + branch_name="worktree-$(date +%Y%m%d-%H%M%S)" + else + branch_name="$1" + fi + git worktree add "../$branch_name" -b "$branch_name" && \ + cd "../$branch_name" || return 1 + codex -m gpt-5-codex --config model_reasoning_effort='xhigh' +} +``` + +Reload: `source ~/.bashrc` or `source ~/.zshrc` + +
+Windows PowerShell + +Add to PowerShell profile (`notepad $PROFILE`): + +```powershell +function clx { + param([string]$BranchName) + if (-not $BranchName) { + $BranchName = "worktree-$(Get-Date -Format 'yyyyMMdd-HHmmss')" + } + git worktree add "../$BranchName" -b $BranchName + if ($LASTEXITCODE -eq 0) { + Set-Location "../$BranchName" + claude --model opusplan --permission-mode plan + } +} + +function cx { + param([string]$BranchName) + if (-not $BranchName) { + $BranchName = "worktree-$(Get-Date -Format 'yyyyMMdd-HHmmss')" + } + git worktree add "../$BranchName" -b $BranchName + if ($LASTEXITCODE -eq 0) { + Set-Location "../$BranchName" + codex -m gpt-5-codex --config model_reasoning_effort='xhigh' + } +} +``` + +Reload: `. $PROFILE` + +
+ +
+Windows CMD Batch + +Create `clx.bat` in a PATH directory: + +```batch +@echo off +setlocal enabledelayedexpansion +if "%~1"=="" ( + for /f "tokens=2 delims==" %%I in ('wmic os get localdatetime /value') do set datetime=%%I + set branch_name=worktree-!datetime:~0,8!-!datetime:~8,6! +) else ( + set branch_name=%~1 +) +git worktree add "../%branch_name%" -b "%branch_name%" +if %errorlevel% equ 0 ( + cd "../%branch_name%" + claude --model opusplan --permission-mode plan +) +endlocal +``` + +Create `cx.bat` similarly for Codex CLI. + +
+ +### Usage + +```bash +# Named worktree +clx feature-auth +cx bugfix-123 + +# Auto-generated timestamp name +clx +cx +``` + +### Managing Worktrees + +```bash +git worktree list # List all worktrees +git worktree remove ../name # Remove a worktree +git worktree prune # Clean up stale references +``` + +### Environment Setup + +Each worktree needs its own dependencies: +- **Node.js**: `npm install` or `yarn` +- **Python**: `pip install -r requirements.txt` + +### The .worktreeinclude File + +Specify which `.gitignore`d files to copy to new worktrees: + +```text +# Environment files +.env +.env.local +.env.* + +# Claude Code local settings +**/.claude/settings.local.json +``` + +### Claude Desktop Worktree Location + +- Default: `~/.claude-worktrees` +- Configurable in Claude Desktop settings +- Repository must be Git initialized + +### Local Ignores Without .gitignore + +Use `.git/info/exclude` for local-only ignores: + +```text +.idea/ +my-local-scripts/ +``` + +| File | Scope | Shared | +|------|-------|--------| +| `.gitignore` | Team | Yes | +| `.git/info/exclude` | Local | No | +| `~/.config/git/ignore` | Global | No | + +> **See also:** [Z.AI + Worktrees](#zai--git-worktree-integration) for combining Z.AI with worktrees + +--- + +## I want to customize Claude's behavior + +### Custom Slash Commands + +#### `/anthropic` Commands + +| Command | What it does | +|---------|-------------| +| `/apply-thinking-to` | Enhances prompts with Anthropic's extended thinking patterns | +| `/convert-to-todowrite-tasklist-prompt` | Converts prompts to parallel task execution (60-70% faster) | +| `/update-memory-bank` | Updates CLAUDE.md and memory bank files | + +#### `/ccusage` Commands + +| Command | What it does | +|---------|-------------| +| `/ccusage-daily` | Comprehensive usage cost analysis with daily breakdowns | + +#### `/cleanup` Commands + +| Command | What it does | +|---------|-------------| +| `/cleanup-context` | Memory bank optimization (15-25% token reduction) | + +#### `/documentation` Commands + +| Command | What it does | +|---------|-------------| +| `/create-readme-section` | Generates README sections with professional formatting | +| `/create-release-note` | Creates dual release notes (customer-facing + technical) | + +#### `/security` Commands + +| Command | What it does | +|---------|-------------| +| `/security-audit` | OWASP-based security audit | +| `/check-best-practices` | Language-specific best practices analysis | +| `/secure-prompts` | Detects prompt injection attacks | + +Test prompts available at `.claude/commands/security/test-examples/` + +#### `/architecture` Commands + +| Command | What it does | +|---------|-------------| +| `/explain-architecture-pattern` | Identifies and explains architectural patterns | + +#### `/promptengineering` Commands + +| Command | What it does | +|---------|-------------| +| `/convert-to-test-driven-prompt` | Transforms requests into TDD-style prompts | +| `/batch-operations-prompt` | Optimizes for parallel file operations | + +#### `/refactor` Commands + +| Command | What it does | +|---------|-------------| +| `/refactor-code` | Creates detailed refactoring plans with risk assessment | + +### Custom Skills + +Skills provide specialized capabilities. See [official docs](https://docs.claude.com/en/docs/claude-code/skills). + +| Skill | What it does | +|-------|-------------| +| **claude-docs-consultant** | Selectively fetches official Claude Code documentation | + +### Custom Subagents + +Subagents handle complex tasks autonomously with their own context window. See [official docs](https://docs.anthropic.com/en/docs/claude-code/sub-agents). + +| Agent | What it does | +|-------|-------------| +| **memory-bank-synchronizer** | Keeps memory bank in sync with codebase | +| **code-searcher** | Efficient codebase search with optional CoD mode (80% fewer tokens) | +| **get-current-datetime** | Accurate Brisbane timezone (GMT+10) timestamps | +| **ux-design-expert** | Comprehensive UX/UI guidance with Tailwind CSS & Highcharts | + +### Hooks + +Hooks run custom commands before/after tool execution. + +**Included Hook:** `STOP` notification using Terminal-Notifier for macOS desktop notifications. Setup: [Terminal-Notifier](https://github.com/centminmod/terminal-notifier-setup) + +> **See also:** [Configuration Reference](#configuration-reference) for all settings options + +--- + +## I want to use Z.AI for higher quotas + +### What is Z.AI? + +[Z.AI's GLM Coding Plan](https://z.ai) provides cost-effective access to high-performance GLM models optimized for coding, with significantly higher quotas than standard Claude plans. + +> **10% Discount**: Use invite code [`WWB8IFLROM`](https://z.ai/subscribe?ic=WWB8IFLROM) + +### Pricing & Plans + +| Plan | Prompts/5hrs | Monthly Cost | vs Claude | +|------|--------------|--------------|-----------| +| Lite | ~120 | ~$3 | 3× Claude Pro quota | +| Pro | ~600 | Higher | 3× Claude Max 5x quota | +| Max | ~2,400 | Higher | 3× Claude Max 20x quota | + +Each prompt allows 15–20 model calls = billions of tokens monthly at ~1% of API pricing. + +### Privacy + +- **Data Location**: Singapore +- **Privacy Guarantee**: Z.AI does not store any content you provide +- [Privacy Policy](https://docs.z.ai/legal-agreement/privacy-policy) + +### Prerequisites + +- Node.js 18+ +- Z.AI API key from [dashboard](https://z.ai) +- [Official docs](https://docs.z.ai/devpack/tool/claude) + +### Setup Options + +**Option 1: Automated** (macOS/Linux only) +```bash +curl -O "https://cdn.bigmodel.cn/install/claude_code_zai_env.sh" && bash ./claude_code_zai_env.sh +``` + +**Option 2: Manual** - Edit `~/.claude/settings.json`: +```json +{ + "env": { + "ANTHROPIC_AUTH_TOKEN": "your-zai-api-key", + "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic", + "API_TIMEOUT_MS": "3000000" + } +} +``` + +### Shell Function Launcher (Recommended) + +Use Z.AI without affecting your existing Claude Code setup. + +**macOS / Linux** - Add to `~/.bashrc` or `~/.zshrc`: + +```bash +zai() { + export ANTHROPIC_AUTH_TOKEN="your-zai-api-key" + export ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic" + export API_TIMEOUT_MS="3000000" + claude "$@" +} +``` + +
+Windows PowerShell + +```powershell +function zai { + $env:ANTHROPIC_AUTH_TOKEN = "your-zai-api-key" + $env:ANTHROPIC_BASE_URL = "https://api.z.ai/api/anthropic" + $env:API_TIMEOUT_MS = "3000000" + claude $args +} +``` + +
+ +
+Windows CMD Batch + +Create `zai.bat`: +```batch +@echo off +set ANTHROPIC_AUTH_TOKEN=your-zai-api-key +set ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic +set API_TIMEOUT_MS=3000000 +claude %* +``` + +
+ +### Model Mapping + +| Claude Model | GLM Model | +|--------------|-----------| +| Opus | GLM-4.7 | +| Sonnet | GLM-4.7 | +| Haiku | GLM-4.5-Air | + +**Customize mappings** (optional) by adding to your shell function: +```bash +export ANTHROPIC_DEFAULT_OPUS_MODEL="GLM-4.7" +export ANTHROPIC_DEFAULT_SONNET_MODEL="GLM-4.5" +export ANTHROPIC_DEFAULT_HAIKU_MODEL="GLM-4.5-Air" +``` + +
+Windows PowerShell Custom Mapping + +```powershell +function zai { + $env:ANTHROPIC_AUTH_TOKEN = "your-zai-api-key" + $env:ANTHROPIC_BASE_URL = "https://api.z.ai/api/anthropic" + $env:API_TIMEOUT_MS = "3000000" + $env:ANTHROPIC_DEFAULT_OPUS_MODEL = "GLM-4.7" + $env:ANTHROPIC_DEFAULT_SONNET_MODEL = "GLM-4.5" + $env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "GLM-4.5-Air" + claude $args +} +``` + +
+ +
+Windows CMD Custom Mapping + +```batch +@echo off +set ANTHROPIC_AUTH_TOKEN=your-zai-api-key +set ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic +set API_TIMEOUT_MS=3000000 +set ANTHROPIC_DEFAULT_OPUS_MODEL=GLM-4.7 +set ANTHROPIC_DEFAULT_SONNET_MODEL=GLM-4.5 +set ANTHROPIC_DEFAULT_HAIKU_MODEL=GLM-4.5-Air +claude %* +``` + +
+ +### Usage + +```bash +zai # Launch Z.AI +zai --model sonnet # Specific model +zai --model opus --permission-mode plan +``` + +### Z.AI + Git Worktree Integration + +Combine Z.AI with worktrees for isolated parallel sessions: + +**macOS / Linux**: +```bash +zaix() { + local branch_name + if [ -z "$1" ]; then + branch_name="worktree-$(date +%Y%m%d-%H%M%S)" + else + branch_name="$1" + fi + git worktree add "../$branch_name" -b "$branch_name" && \ + cd "../$branch_name" || return 1 + + export ANTHROPIC_AUTH_TOKEN="your-zai-api-key" + export ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic" + export API_TIMEOUT_MS="3000000" + claude --model sonnet --permission-mode plan +} +``` + +
+Windows PowerShell Z.AI + Worktree + +```powershell +function zaix { + param([string]$BranchName) + if (-not $BranchName) { + $BranchName = "worktree-$(Get-Date -Format 'yyyyMMdd-HHmmss')" + } + git worktree add "../$BranchName" -b $BranchName + if ($LASTEXITCODE -eq 0) { + Set-Location "../$BranchName" + $env:ANTHROPIC_AUTH_TOKEN = "your-zai-api-key" + $env:ANTHROPIC_BASE_URL = "https://api.z.ai/api/anthropic" + $env:API_TIMEOUT_MS = "3000000" + claude --model sonnet --permission-mode plan + } +} +``` + +
+ +
+Windows CMD Z.AI + Worktree + +Create `zaix.bat`: +```batch +@echo off +setlocal enabledelayedexpansion +if "%~1"=="" ( + for /f "tokens=2 delims==" %%I in ('wmic os get localdatetime /value') do set datetime=%%I + set branch_name=worktree-!datetime:~0,8!-!datetime:~8,6! +) else ( + set branch_name=%~1 +) +git worktree add "../%branch_name%" -b "%branch_name%" +if %errorlevel% equ 0 ( + cd "../%branch_name%" + set ANTHROPIC_AUTH_TOKEN=your-zai-api-key + set ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic + set API_TIMEOUT_MS=3000000 + claude --model sonnet --permission-mode plan +) +endlocal +``` + +
+ +**Usage:** +```bash +zaix feature-auth # Named worktree +zaix # Auto-generated name +``` + +> **See also:** [Parallel Sessions](#i-want-to-run-parallel-ai-coding-sessions) for more worktree details + +--- + +## I want to monitor costs and usage + +### Claude Plan Rate Limits + +From August 28, 2025, weekly limits apply (plus monthly 50x 5hr session limit): + +| Plan | Sonnet 4 (hrs/week) | Opus 4 (hrs/week) | +|------|---------------------|-------------------| +| Pro | 40–80 | – | +| Max ($100/mo) | 140–280 | 15–35 | +| Max ($200/mo) | 240–480 | 24–40 | + +### Status Lines + +Display real-time usage in Claude Code. + +Add to `~/.claude/settings.json`: +```json +{ + "statusLine": { + "type": "command", + "command": "~/.claude/statuslines/statusline.sh", + "padding": 0 + } +} +``` + +Create `~/.claude/statuslines/statusline.sh`: +```bash +#!/bin/bash +input=$(cat) + +MODEL_DISPLAY=$(echo "$input" | jq -r '.model.display_name') +CURRENT_DIR=$(echo "$input" | jq -r '.workspace.current_dir') +INPUT_TOKENS=$(echo "$input" | jq -r '.context_window.total_input_tokens') +OUTPUT_TOKENS=$(echo "$input" | jq -r '.context_window.total_output_tokens') +CONTEXT_SIZE=$(echo "$input" | jq -r '.context_window.context_window_size') +COST_USD=$(echo "$input" | jq -r '.cost.total_cost_usd') +LINES_ADDED=$(echo "$input" | jq -r '.cost.total_lines_added') +LINES_REMOVED=$(echo "$input" | jq -r '.cost.total_lines_removed') + +format_tokens() { + local num="$1" + if [ "$num" -ge 1000 ]; then echo "$((num / 1000))k"; else echo "$num"; fi +} + +TOTAL_TOKENS=$((INPUT_TOKENS + OUTPUT_TOKENS)) + +GIT_BRANCH="" +if git rev-parse --git-dir > /dev/null 2>&1; then + BRANCH=$(git branch --show-current 2>/dev/null) + [ -n "$BRANCH" ] && GIT_BRANCH=" | 🌿 $BRANCH" +fi + +echo "[$MODEL_DISPLAY] 📁 ${CURRENT_DIR##*/}${GIT_BRANCH} +Tokens: $(format_tokens "$TOTAL_TOKENS") (in:$(format_tokens "$INPUT_TOKENS")+out:$(format_tokens "$OUTPUT_TOKENS")) | Ctx:$(format_tokens "$CONTEXT_SIZE") +Cost: \$${COST_USD} | +${LINES_ADDED} -${LINES_REMOVED} lines" +``` + +### Cost Tracking MCP + +Install the [Usage Metrics MCP](https://github.com/centminmod/claude-code-opentelemetry-setup): +```bash +claude mcp add --transport stdio metrics -s user -- uv run --directory /path/to/mcp-server metrics-server +``` + +### Cost Analysis Command + +Use `/ccusage-daily` for detailed cost analysis with daily breakdowns, model statistics, and recommendations. + +### Optimization Tips + +- **Use Z.AI** for 3× higher quotas at lower cost +- **Use CoD mode** in code-searcher for 80% token reduction +- **Use git worktrees** for parallel sessions without duplicating quota +- **Monitor status lines** to track real-time usage + +> **See also:** [Z.AI](#i-want-to-use-zai-for-higher-quotas) for higher quota options + +--- + +## Configuration Reference + +### Settings Scopes + +| Scope | Location | Who it affects | +|-------|----------|----------------| +| Managed | System directories | All users (IT-controlled) | +| User | `~/.claude/settings.json` | You (all projects) | +| Project | `.claude/settings.json` | All collaborators | +| Local | `.claude/settings.local.json` | You (this project only) | + +**Precedence**: Enterprise > CLI args > Local > Project > User + +### settings.json Options + +| Key | What it does | Example | +|-----|-------------|---------| +| `apiKeyHelper` | Script to generate auth | `/bin/generate_key.sh` | +| `cleanupPeriodDays` | Days to keep transcripts | `20` | +| `env` | Environment variables | `{"FOO": "bar"}` | +| `includeCoAuthoredBy` | Add Claude byline to commits | `false` | + +### Permission Settings + +| Key | What it does | Example | +|-----|-------------|---------| +| `allow` | Allowed tool rules | `["Bash(git diff:*)"]` | +| `deny` | Denied tool rules | `["WebFetch"]` | +| `additionalDirectories` | Extra working dirs | `["../docs/"]` | +| `defaultMode` | Default permission mode | `"acceptEdits"` | + +### Environment Variables + +| Variable | Purpose | +|----------|---------| +| `ANTHROPIC_API_KEY` | API key for Claude SDK | +| `ANTHROPIC_AUTH_TOKEN` | Custom auth header | +| `ANTHROPIC_BASE_URL` | Custom API endpoint | +| `ANTHROPIC_MODEL` | Custom model name | +| `BASH_DEFAULT_TIMEOUT_MS` | Default bash timeout | +| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Max output tokens | +| `CLAUDE_CODE_USE_BEDROCK` | Use Amazon Bedrock | +| `CLAUDE_CODE_USE_VERTEX` | Use Google Vertex AI | +| `DISABLE_AUTOUPDATER` | Disable updates | +| `DISABLE_TELEMETRY` | Opt out of telemetry | +| `MCP_TIMEOUT` | MCP startup timeout | +| `MCP_TOOL_TIMEOUT` | MCP tool timeout | +| `MAX_MCP_OUTPUT_TOKENS` | Max MCP tokens (default: 25000) | + +### File Locations + +| File | macOS/Linux | Windows | +|------|-------------|---------| +| User settings | `~/.claude/settings.json` | `%USERPROFILE%\.claude\settings.json` | +| Project settings | `.claude/settings.json` | `.claude\settings.json` | +| Local settings | `.claude/settings.local.json` | `.claude\settings.local.json` | + +### Tools Available to Claude + +| Tool | What it does | Permission | +|------|-------------|------------| +| Agent | Runs sub-agents | No | +| Bash | Shell commands | Yes | +| Edit | File edits | Yes | +| Glob | Find files by pattern | No | +| Grep | Search file contents | No | +| LS | List files | No | +| MultiEdit | Multiple atomic edits | Yes | +| NotebookEdit | Jupyter cell edits | Yes | +| NotebookRead | Read Jupyter notebooks | No | +| Read | Read files | No | +| TodoRead/TodoWrite | Task management | No | +| WebFetch | Fetch URLs | Yes | +| WebSearch | Web searches | Yes | +| Write | Create/overwrite files | Yes | + +### Config Commands + +```bash +claude config list # List settings +claude config get # Get setting +claude config set # Set setting +claude config set -g # Global setting +``` + +--- + +## Resources + +### Official Documentation + +- [Claude Code Overview](https://docs.anthropic.com/en/docs/claude-code/overview) +- [Settings Reference](https://code.claude.com/docs/en/settings) +- [Hooks](https://code.claude.com/docs/en/hooks) +- [Skills](https://docs.claude.com/en/docs/claude-code/skills) +- [Sub-agents](https://docs.anthropic.com/en/docs/claude-code/sub-agents) +- [Plugin Marketplace](https://code.claude.com/docs/en/discover-plugins) + +### YouTube Guides + +- [Advent of Claude: 31 Days](https://adocomplete.com/advent-of-claude-2025/) - Ado Kukic +- [Claude Code with Opus 4.5](https://www.youtube.com/watch?v=UVJXh57MgI0) - Alex Finn +- [Claude Code Overview](https://www.youtube.com/watch?v=Dekx_OzRwiI) - Matt Maher +- [Ralph Wiggum Tutorial](https://www.youtube.com/watch?v=RpvQH0r0ecM) - Greg Isenberg + +--- + +## Star History + +[![Star History Chart](https://api.star-history.com/svg?repos=centminmod/my-claude-code-setup&type=Date)](https://www.star-history.com/#centminmod/my-claude-code-setup&Date) + +--- + +## Stats + +![Alt](https://repobeats.axiom.co/api/embed/715da1679915da77d87deb99a1f527a44e76ec60.svg "Repobeats analytics image") diff --git a/README-v4.md b/README-v4.md new file mode 100644 index 0000000..f6670d7 --- /dev/null +++ b/README-v4.md @@ -0,0 +1,1748 @@ +[![GitHub stars](https://img.shields.io/github/stars/centminmod/my-claude-code-setup.svg?style=flat-square)](https://github.com/centminmod/my-claude-code-setup/stargazers) [![GitHub forks](https://img.shields.io/github/forks/centminmod/my-claude-code-setup.svg?style=flat-square)](https://github.com/centminmod/my-claude-code-setup/network) [![GitHub issues](https://img.shields.io/github/issues/centminmod/my-claude-code-setup.svg?style=flat-square)](https://github.com/centminmod/my-claude-code-setup/issues) + +* Threads - https://www.threads.com/@george_sl_liu +* BlueSky - https://bsky.app/profile/georgesl.bsky.social + +# My Claude Code Setup - Technical Reference + +## Overview + +### Purpose & Scope + +This repository provides a comprehensive starter kit for Claude Code projects, including: + +- **Memory Bank System**: Structured context files for persistent memory across sessions +- **Pre-configured Settings**: Optimized `.claude/settings.json` with fast tools +- **Custom Extensions**: Hooks, skills, subagents, and slash commands +- **MCP Server Integration**: Curated external tool connections +- **Alternative Provider Support**: Z.AI integration for higher quotas + +### Target Audience + +- **Beginners**: New to Claude Code, need step-by-step guidance +- **Intermediate Users**: Want to extend Claude Code with plugins and MCP servers +- **Advanced Users**: Building custom subagents, skills, and workflows +- **Power Users**: Need comprehensive reference for all configuration options + +### Compatibility Matrix + +| Component | Minimum Version | Recommended | +|-----------|-----------------|-------------| +| Node.js | 18+ | Latest LTS | +| Git | 2.30+ | Latest | +| Claude AI Account | Pro/Max | Max | +| ripgrep | 12.0+ | Latest | +| fd | 8.0+ | Latest | +| jq | 1.6+ | Latest | + +--- + +## Table of Contents + +- **Part I: Getting Started** + - [Chapter 1: Prerequisites](#chapter-1-prerequisites) + - [Chapter 2: Installation](#chapter-2-installation) + - [Chapter 3: Initial Configuration](#chapter-3-initial-configuration) +- **Part II: Memory Bank System** + - [Chapter 4: Architecture](#chapter-4-architecture) + - [Chapter 5: Core Context Files](#chapter-5-core-context-files) + - [Chapter 6: Operations](#chapter-6-operations) +- **Part III: Extensions** + - [Chapter 7: Plugin System](#chapter-7-plugin-system) + - [Chapter 8: MCP Servers](#chapter-8-mcp-servers) +- **Part IV: Customization** + - [Chapter 9: Subagents](#chapter-9-subagents) + - [Chapter 10: Skills](#chapter-10-skills) + - [Chapter 11: Hooks](#chapter-11-hooks) + - [Chapter 12: Slash Commands](#chapter-12-slash-commands) +- **Part V: Alternative Providers** + - [Chapter 13: Z.AI Integration](#chapter-13-zai-integration) +- **Part VI: Development Workflows** + - [Chapter 14: Git Worktrees](#chapter-14-git-worktrees) + - [Chapter 15: Status Lines](#chapter-15-status-lines) +- **Part VII: Reference** + - [Chapter 16: Settings](#chapter-16-settings) + - [Chapter 17: Environment Variables](#chapter-17-environment-variables) + - [Chapter 18: File Locations](#chapter-18-file-locations) + - [Chapter 19: Tools Available to Claude](#chapter-19-tools-available-to-claude) + - [Chapter 20: Cost & Rate Management](#chapter-20-cost--rate-management) +- **Appendices** + - [Appendix A: Quick Reference Cards](#appendix-a-quick-reference-cards) + - [Appendix B: Troubleshooting](#appendix-b-troubleshooting) + - [Appendix C: Resources](#appendix-c-resources) + - [Appendix D: Star History & Stats](#appendix-d-star-history--stats) + +--- + +# Part I: Getting Started + +## Chapter 1: Prerequisites + +### 1.1 System Requirements + +| OS | Support Level | Notes | +|----|---------------|-------| +| macOS | Full | All features supported | +| Linux | Full | All features supported | +| Windows | Full | PowerShell and CMD supported | + +### 1.2 Required Accounts + +| Account | Purpose | Link | +|---------|---------|------| +| Claude AI | Claude Code access | [claude.ai](https://claude.ai/) | +| GitHub (optional) | Version control | [github.com](https://github.com/) | + +**Claude AI Pricing:** + +| Plan | Monthly Cost | Usage Limits | +|------|-------------|--------------| +| Pro | $20 | Standard quotas | +| Max | $100 | Higher quotas | +| Max | $200 | Highest quotas | + +See [official usage limits](https://support.anthropic.com/en/articles/9797557-usage-limit-best-practices). + +### 1.3 Required Tools + +| Tool | Version | Purpose | Installation | +|------|---------|---------|--------------| +| Node.js | 18+ | Runtime environment | [nodejs.org](https://nodejs.org/) | +| Git | Latest | Version control | [git-scm.com](https://git-scm.com/) | +| ripgrep | Latest | Fast content search | `brew install ripgrep` (macOS) | +| fd | Latest | Fast file finding | `brew install fd` (macOS) | +| jq | Latest | JSON processing | `brew install jq` (macOS) | + +**macOS Installation (all tools):** +```bash +brew install ripgrep fd jq +``` + +--- + +## Chapter 2: Installation + +### 2.1 Installation Methods + +Choose the method that best fits your workflow: + +#### Method A: Clone Entire Repository (New Projects) + +```bash +# 1. Clone this repository as your new project +git clone https://github.com/centminmod/my-claude-code-setup.git my-project +cd my-project + +# 2. Remove template README files (create your own project documentation) +rm README.md README-v2.md README-v3.md README-v4.md + +# 3. Reinitialize git for your own project (optional) +rm -rf .git +git init + +# 4. Launch Claude Code and initialize +claude +# Then run: /init +``` + +#### Method B: Selective Copy (Existing Projects) + +For existing projects, copy only the components you need: + +```bash +# Core files (recommended minimum) +cp /path/to/my-claude-code-setup/CLAUDE.md your-project/ +cp -r /path/to/my-claude-code-setup/.claude your-project/ + +# Or selectively copy specific components: +mkdir -p your-project/.claude +cp -r /path/to/my-claude-code-setup/.claude/settings.json your-project/.claude/ +cp -r /path/to/my-claude-code-setup/.claude/commands your-project/.claude/ +cp -r /path/to/my-claude-code-setup/.claude/skills your-project/.claude/ +cp -r /path/to/my-claude-code-setup/.claude/agents your-project/.claude/ +cp -r /path/to/my-claude-code-setup/.claude/hooks your-project/.claude/ +``` + +#### Method C: Download from GitHub + +Browse the repository on GitHub and download individual files: + +| Component | Path | Purpose | +|-----------|------|---------| +| Memory Bank | `CLAUDE.md` | Main context file | +| Settings | `.claude/settings.json` | Configuration template | +| Commands | `.claude/commands/` | Custom slash commands | +| Skills | `.claude/skills/` | Custom skills | +| Agents | `.claude/agents/` | Custom subagents | +| Hooks | `.claude/hooks/` | Event hooks | + +After copying files, launch Claude Code in your project and run `/init`. + +### 2.2 Via NPM + +```bash +npm install -g @anthropic-ai/claude-code +``` + +### 2.3 Development Container + +For isolated development with YOLO mode support: + +[VS Code Dev Container Setup](https://claude-devcontainers.centminmod.com/) + +Features: +- Claude Code with `dangerously_skip_permissions` +- Codex CLI with `sandbox_mode = danger-full-access` +- Gemini CLI, Vercel CLI, Cloudflare Wrangler +- Amazon AWS CLI + +### 2.4 Verification + +```bash +# Verify Claude Code installation +claude --version + +# Verify fast tools +rg --version +fd --version +jq --version +``` + +--- + +## Chapter 3: Initial Configuration + +### 3.1 Copying Starter Files + +1. Copy all files from this repository to your project root +2. Review and modify `CLAUDE.md` for your project specifics +3. Modify `.claude/settings.json` as needed + +### 3.2 First-Time Setup + +The `.claude/settings.json` includes Terminal-Notifier for macOS notifications. Remove if not using macOS. See [Terminal-Notifier Setup](https://github.com/centminmod/terminal-notifier-setup). + +### 3.3 IDE Integration + +#### VS Code Extension + +- Install: [Claude Code Extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code) +- Guides: + - [Beginner Video](https://www.youtube.com/watch?v=rPITZvwyoMc) + - [Advanced Video](https://www.youtube.com/watch?v=P-5bWpUbO60) + +#### Git for VS Code + +- [Setup Guide](https://www.youtube.com/watch?v=twsYxYaQikI) +- [Tutorial](https://www.youtube.com/watch?v=z5jZ9lrSpqk) + +--- + +# Part II: Memory Bank System + +## Chapter 4: Architecture + +### 4.1 Design Philosophy + +The Memory Bank System enables Claude Code to maintain context across multiple chat sessions through structured markdown files. Instead of starting fresh each session, Claude reads these files to understand: + +- Project patterns and conventions +- Architecture decisions and rationale +- Current work state and goals +- Common issues and solutions + +### 4.2 File Hierarchy + +``` +project-root/ +├── CLAUDE.md # Main entry point +├── CLAUDE-activeContext.md # Current session state +├── CLAUDE-patterns.md # Code patterns +├── CLAUDE-decisions.md # Architecture Decision Records +├── CLAUDE-troubleshooting.md # Issue/solution database +├── CLAUDE-config-variables.md # Configuration reference +├── CLAUDE-temp.md # Temporary scratch pad +├── CLAUDE-cloudflare.md # Optional: Cloudflare/ClerkOS docs +├── CLAUDE-cloudflare-mini.md # Optional: Cloudflare mini reference +└── CLAUDE-convex.md # Optional: Convex database docs +``` + +### 4.3 Loading Behavior + +| File | When Loaded | Priority | +|------|-------------|----------| +| `CLAUDE.md` | Always | High | +| `CLAUDE-activeContext.md` | Always (if exists) | High | +| `CLAUDE-patterns.md` | Always (if exists) | Medium | +| `CLAUDE-decisions.md` | Always (if exists) | Medium | +| `CLAUDE-troubleshooting.md` | Always (if exists) | Medium | +| `CLAUDE-config-variables.md` | Always (if exists) | Low | +| `CLAUDE-temp.md` | Only when referenced | Low | + +### 4.4 Context Window Management + +Memory bank files consume context window tokens. Optimization strategies: + +- Use `/cleanup-context` command for 15-25% token reduction +- Archive older decisions and patterns +- Keep `CLAUDE-temp.md` empty when not in use +- Reference supplementary docs (`CLAUDE-cloudflare.md`) only when needed + +--- + +## Chapter 5: Core Context Files + +### 5.1 CLAUDE.md (Main Entry Point) + +Primary file containing: +- Project overview +- AI guidance rules +- Memory bank system instructions +- Tool usage preferences +- Directory/file exploration commands + +### 5.2 CLAUDE-activeContext.md + +Current session state: +- Active goals and tasks +- Recent changes +- Work in progress +- Session continuity notes + +### 5.3 CLAUDE-patterns.md + +Established patterns: +- Code conventions +- Naming patterns +- Architecture patterns +- API patterns + +### 5.4 CLAUDE-decisions.md + +Architecture Decision Records (ADRs): +- Decision context +- Options considered +- Decision made +- Rationale +- Consequences + +### 5.5 CLAUDE-troubleshooting.md + +Issue/solution database: +- Common errors +- Proven fixes +- Workarounds +- Prevention tips + +### 5.6 CLAUDE-config-variables.md + +Configuration reference: +- Environment variables +- Build configuration +- Runtime settings + +### 5.7 CLAUDE-temp.md + +Temporary scratch pad: +- Only read when explicitly referenced +- Cleared after use +- For temporary notes during complex tasks + +--- + +## Chapter 6: Operations + +### 6.1 Initialization (/init) + +After launching Claude Code: + +``` +/init +``` + +Claude Code will: +1. Analyze your codebase structure +2. Identify patterns and conventions +3. Populate memory bank files +4. Set up context for future sessions + +### 6.2 Updates + +After significant work completion: + +``` +update memory bank +``` + +Claude updates all relevant CLAUDE-*.md files. + +### 6.3 Backups + +Memory bank backup (copy to backup directory): + +``` +backup memory bank to /path/to/backup +``` + +Files copied: +- All CLAUDE-*.md files +- `.claude/` settings directory + +### 6.4 Example Session Output + +``` +> update memory bank + +∴ Thinking… + + The user wants me to update the memory bank files. I should update the relevant CLAUDE-*.md files to reflect the v0.1.6 changes and current state. Let me check + which memory bank files exist and update them. + +∴ Thinking… + + I need to continue updating the memory bank files. I'll update: + 1. CLAUDE-patterns.md - Add export path handling pattern (Pattern 22) + 2. CLAUDE-decisions.md - Add ADR-017 for Phoneme API migration and ADR-018 for export path handling + 3. CLAUDE-troubleshooting.md - Add new issues and solutions for v0.1.6 + +∴ Thinking… + + The memory bank files have been modified but not committed. The v0.1.6 release was already committed and tagged, but the memory bank documentation updates are + still uncommitted. Let me provide a summary of the completed work and offer to commit these documentation changes. + +⏺ Summary: v0.1.6 Release Complete ✅ + + Memory Bank Updates Complete: + - CLAUDE-activeContext.md - v0.1.6 session context + - CLAUDE-patterns.md - Added patterns 22-24 (Export Path, Format Detection, API Migration) + - CLAUDE-decisions.md - Added ADR-017 & ADR-018 + - CLAUDE-troubleshooting.md - Added 4 new issue/fix entries + + v0.1.6 Fixes Applied: + 1. Export to absolute paths (e.g., --export /tmp/test.wav) + 2. Format detection from filename extension (prevents .mp3.wav) + 3. Phoneme API migrated to /dev/phonemize + 4. Test scripts updated for --export "" syntax + + Test Results: All 29 tests passing + + The memory bank documentation updates are ready to commit. Would you like me to commit them +``` + +--- + +# Part III: Extensions + +## Chapter 7: Plugin System + +### 7.1 Plugin Architecture + +Claude Code plugins extend functionality through the official marketplace system. + +### 7.2 Official Anthropic Marketplace + +**Marketplace URL:** https://code.claude.com/docs/en/discover-plugins + +#### Installation Commands + +```bash +# Install plugin +/plugin install plugin-name@claude-plugins-official + +# Update marketplace +/plugin marketplace update claude-plugins-official +``` + +#### Plugin Reference Table + +| Plugin | Purpose | Source | Install Command | Notes | +|--------|---------|--------|-----------------|-------| +| code-simplifier | Code cleanup & maintainability | claude-plugins-official | `/plugin install code-simplifier` | [GitHub](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/code-simplifier) | +| frontend-design | Production-grade UI generation | claude-code-plugins | `/plugin install frontend-design@claude-code-plugins` | [GitHub](https://github.com/anthropics/claude-code/tree/main/plugins/frontend-design) | +| feature-dev | 7-phase feature development | claude-code-plugins | `/plugin install feature-dev@claude-code-plugins` | [GitHub](https://github.com/anthropics/claude-code/tree/main/plugins/feature-dev) | +| ralph-wiggum | Iterative AI loops | claude-code-plugins | `/plugin install ralph-wiggum@claude-code-plugins` | [GitHub](https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum) | + +#### Ralph Wiggum Notes + +- May have issues on some systems +- Known issues: [#16398](https://github.com/anthropics/claude-code/issues/16398), [#16389](https://github.com/anthropics/claude-code/issues/16389) +- Usage guide: [YouTube](https://www.youtube.com/watch?v=RpvQH0r0ecM) +- Documentation: [Blog](https://paddo.dev/blog/ralph-wiggum-autonomous-loops/) +- Repo: [GitHub](https://github.com/snarktank/ralph) + +### 7.3 Third-Party Marketplaces + +#### Adding Marketplaces + +```bash +/plugin marketplace add owner/repo-name +``` + +#### Security Considerations + +- Review plugin source code before installation +- Only install from trusted sources +- Check for recent updates and maintenance + +#### Third-Party Plugin Reference + +| Plugin | Source | Purpose | Commands | +|--------|--------|---------|----------| +| safety-net | cc-marketplace | Catches destructive git/filesystem commands | `/plugin marketplace add kenryu42/cc-marketplace`
`/plugin install safety-net@cc-marketplace` | +| glm-plan-usage | zai-coding-plugins | Query Z.AI usage statistics | `/plugin marketplace add zai/zai-coding-plugins`
`/plugin install glm-plan-usage@zai-coding-plugins` | + +**Safety Net**: [GitHub](https://github.com/kenryu42/claude-code-safety-net) - Prevents destructive commands like [this incident](https://www.reddit.com/r/ClaudeAI/comments/1pgxckk/claude_cli_deleted_my_entire_home_directory_wiped/). + +**Z.AI Usage**: [Docs](https://docs.z.ai/devpack/extension/usage-query-plugin) + +--- + +## Chapter 8: MCP Servers + +### 8.1 Protocol Overview + +MCP (Model Context Protocol) enables Claude Code to connect with external tools and services. + +### 8.2 Server Categories + +| Category | Purpose | Examples | +|----------|---------|----------| +| Documentation | Library/platform documentation lookup | Context7, Cloudflare Docs | +| Development Tools | Browser automation, testing | Chrome DevTools | +| Metrics | Usage tracking, cost monitoring | Usage Metrics | +| AI Models | Access to other AI providers | Gemini CLI | +| Productivity | Workspace integration | Notion | + +### 8.3 Complete Server Reference + +| Server | Type | Transport | Purpose | Token Cost | GitHub | +|--------|------|-----------|---------|------------|--------| +| Context7 | Documentation | SSE/HTTP | Look up docs for any library | Low | [upstash/context7](https://github.com/upstash/context7) | +| Cloudflare Docs | Documentation | SSE | Cloudflare documentation | Low | [cloudflare/mcp-server-cloudflare](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/docs-vectorize) | +| Usage Metrics | Metrics | stdio | Claude Code cost tracking | Low | [centminmod/claude-code-opentelemetry-setup](https://github.com/centminmod/claude-code-opentelemetry-setup) | +| Gemini CLI | AI Model | stdio | Gemini model access | Variable | [centminmod/gemini-cli-mcp-server](https://github.com/centminmod/gemini-cli-mcp-server) | +| Notion | Productivity | stdio | Notion workspace integration | Variable | [makenotion/notion-mcp-server](https://github.com/makenotion/notion-mcp-server) | +| Chrome DevTools | Development | stdio | Browser automation & debugging | ~17K | [ChromeDevTools/chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp) | + +### 8.4 Installation Commands (Complete) + +#### Context7 MCP + +```bash +claude mcp add --transport http context7 https://mcp.context7.com/mcp --header "CONTEXT7_API_KEY: YOUR_API_KEY" -s user +``` + +#### Cloudflare Documentation MCP + +```bash +claude mcp add --transport sse cf-docs https://docs.mcp.cloudflare.com/sse -s user +``` + +#### Usage Metrics MCP + +```bash +claude mcp add --transport stdio metrics -s user -- uv run --directory /path/to/your/mcp-server metrics-server +``` + +Example output from `get_current_cost`: +```json +{ + "metric": "Total Cost Today", + "value": 27.149809833783127, + "formatted": "$27.1498", + "unit": "currencyUSD" +} +``` + +#### Gemini CLI MCP + +```bash +claude mcp add gemini-cli /path/to/.venv/bin/python /path/to/mcp_server.py -s user -e GEMINI_API_KEY='YOUR_GEMINI_KEY' -e OPENROUTER_API_KEY='YOUR_OPENROUTER_KEY' +``` + +#### Notion MCP + +```bash +claude mcp add-json notionApi '{"type":"stdio","command":"npx","args":["-y","@notionhq/notion-mcp-server"],"env":{"OPENAPI_MCP_HEADERS":"{\"Authorization\": \"Bearer ntn_API_KEY\", \"Notion-Version\": \"2022-06-28\"}"}}' -s user +``` + +#### Chrome DevTools MCP (On-Demand) + +Due to high token overhead (~17K across 26 tools), install on-demand: + +```bash +claude --mcp-config .claude/mcp/chrome-devtools.json +``` + +Create `.claude/mcp/chrome-devtools.json`: +```json +{ + "mcpServers": { + "chrome-devtools": { + "command": "npx", + "args": ["-y", "chrome-devtools-mcp@latest"] + } + } +} +``` + +### 8.5 Server-Specific Configuration Notes + +#### Chrome DevTools Token Breakdown + +26 tools totaling ~16,977 tokens: + +| Tool | Tokens | +|------|--------| +| list_console_messages | 584 | +| emulate_cpu | 651 | +| emulate_network | 694 | +| click | 636 | +| drag | 638 | +| fill | 644 | +| fill_form | 676 | +| hover | 609 | +| upload_file | 651 | +| get_network_request | 618 | +| list_network_requests | 783 | +| close_page | 624 | +| handle_dialog | 645 | +| list_pages | 582 | +| navigate_page | 642 | +| navigate_page_history | 656 | +| new_page | 637 | +| resize_page | 629 | +| select_page | 619 | +| performance_analyze_insight | 649 | +| performance_start_trace | 689 | +| performance_stop_trace | 586 | +| take_screenshot | 803 | +| evaluate_script | 775 | +| take_snapshot | 614 | +| wait_for | 643 | + +#### Verification + +```bash +claude mcp list +# Output: +# context7: https://mcp.context7.com/sse (SSE) - ✓ Connected +# cf-docs: https://docs.mcp.cloudflare.com/sse (SSE) - ✓ Connected +# metrics: uv run --directory /path/to/mcp-server metrics-server - ✓ Connected +``` + +--- + +# Part IV: Customization + +## Chapter 9: Subagents + +### 9.1 Subagent Architecture + +Subagents are specialized tools that: +- Handle complex, multi-step tasks autonomously +- Use their own context window (separate from main conversation) +- Have custom prompts tailored to their purpose + +Official documentation: [Claude Code Sub-agents](https://docs.anthropic.com/en/docs/claude-code/sub-agents) + +### 9.2 Built-in Subagents + +Claude Code includes built-in subagent types. See official docs for complete list. + +### 9.3 Creating Custom Subagents + +Subagents are defined in `.claude/agents/` as markdown files. + +### 9.4 Included Subagent Reference + +| Agent | Location | Purpose | Key Features | +|-------|----------|---------|--------------| +| memory-bank-synchronizer | `.claude/agents/memory-bank-synchronizer.md` | Sync documentation with codebase | Pattern sync, ADR updates, code freshness validation | +| code-searcher | `.claude/agents/code-searcher.md` | Efficient codebase navigation | Standard mode + CoD mode (80% fewer tokens) | +| get-current-datetime | `.claude/agents/get-current-datetime.md` | Brisbane timezone (GMT+10) values | Multiple formats, eliminates timezone confusion | +| ux-design-expert | `.claude/agents/ux-design-expert.md` | UX/UI design guidance | Tailwind CSS, Highcharts, accessibility compliance | + +#### memory-bank-synchronizer + +**Purpose**: Maintains consistency between CLAUDE-*.md files and source code. + +**Responsibilities**: +- Pattern documentation synchronization +- Architecture decision updates +- Technical specification alignment +- Implementation status tracking +- Code example freshness validation +- Cross-reference validation + +**Usage**: Proactively maintains documentation accuracy. + +#### code-searcher + +**Purpose**: Efficient codebase navigation and search. + +**Modes**: +- **Standard**: Full detailed analysis +- **CoD (Chain of Draft)**: ~80% fewer tokens with ultra-concise responses + +**Usage**: +``` +# Standard +"Find the payment processing code" + +# CoD mode +"Find the payment processing code using CoD" +# Output: "Payment→glob:*payment*→found:payment.service.ts:45" +``` + +**Trigger phrases for CoD**: "use CoD", "chain of draft", "draft mode" + +#### get-current-datetime + +**Purpose**: Accurate Brisbane, Australia (GMT+10) timestamps. + +**Formats**: +- Default: Standard date output +- Filename: Safe for file naming +- Readable: Human-friendly format +- ISO: ISO 8601 format + +**Usage**: File timestamps, reports, logging. + +#### ux-design-expert + +**Purpose**: Comprehensive UX/UI design guidance. + +**Capabilities**: +- UX flow optimization +- Premium UI design with Tailwind CSS +- Data visualization with Highcharts +- Accessibility compliance +- Component library design + +--- + +## Chapter 10: Skills + +### 10.1 Skill Architecture + +Skills provide specialized capabilities invoked automatically or on-demand. + +Official documentation: [Agent Skills](https://docs.claude.com/en/docs/claude-code/skills) + +### 10.2 Skill File Structure + +Skills are defined in `.claude/skills/` directories containing: +- `SKILL.md`: Skill definition and instructions +- Supporting files as needed + +### 10.3 Included Skills Reference + +| Skill | Purpose | Invocation | Location | +|-------|---------|------------|----------| +| claude-docs-consultant | Fetch official Claude Code documentation | Automatic when working on Claude Code features | `.claude/skills/claude-docs-consultant/` | + +#### claude-docs-consultant + +**Purpose**: Selectively consults official Claude Code documentation from docs.claude.com. + +**Triggers**: Working on hooks, skills, subagents, MCP servers, or any Claude Code feature requiring official documentation. + +**Behavior**: Fetches only specific documentation needed rather than loading all docs upfront. + +--- + +## Chapter 11: Hooks + +### 11.1 Hook Events Reference + +Hooks run custom commands before or after tool execution. + +### 11.2 Configuration + +Hooks are configured in `.claude/hooks/`. + +### 11.3 Included Hooks + +**STOP Notification Hook** + +Uses Terminal-Notifier to show macOS desktop notifications when Claude Code completes a response. + +Setup: [Terminal-Notifier](https://github.com/centminmod/terminal-notifier-setup) + +--- + +## Chapter 12: Slash Commands + +### 12.1 Built-in Commands + +Claude Code includes built-in commands like `/init`, `/config`, `/help`. + +### 12.2 Custom Command Structure + +Custom commands are defined in `.claude/commands/` as markdown files. + +### 12.3 Included Commands Reference + +| Namespace | Command | Purpose | Usage | +|-----------|---------|---------|-------| +| /anthropic | apply-thinking-to | Enhanced prompts with extended thinking | `/apply-thinking-to @/path/to/prompt.md` | +| /anthropic | convert-to-todowrite-tasklist-prompt | Task optimization (60-70% faster) | `/convert-to-todowrite-tasklist-prompt @/path/to/command.md` | +| /anthropic | update-memory-bank | Update memory bank files | `/update-memory-bank` | +| /ccusage | ccusage-daily | Usage cost analysis | `/ccusage-daily` | +| /cleanup | cleanup-context | Token reduction (15-25%) | `/cleanup-context` | +| /documentation | create-readme-section | README section generation | `/create-readme-section "topic"` | +| /documentation | create-release-note | Dual release notes | `/create-release-note` or `/create-release-note 20` | +| /security | security-audit | OWASP security audit | `/security-audit` | +| /security | check-best-practices | Best practices analysis | `/check-best-practices` | +| /security | secure-prompts | Prompt injection detection | `/secure-prompts @file.txt` | +| /architecture | explain-architecture-pattern | Pattern analysis | `/explain-architecture-pattern` | +| /promptengineering | convert-to-test-driven-prompt | TDD-style prompts | `/convert-to-test-driven-prompt "request"` | +| /promptengineering | batch-operations-prompt | Parallel processing optimization | `/batch-operations-prompt "request"` | +| /refactor | refactor-code | Refactoring plans | `/refactor-code` | + +#### Command Details + +##### /apply-thinking-to + +Transforms prompts using: +- Progressive reasoning structure +- Sequential analytical frameworks +- Systematic verification with test cases +- Constraint optimization +- Bias detection +- Extended thinking budget management + +##### /convert-to-todowrite-tasklist-prompt + +Achieves 60-70% speed improvements through: +- Parallel processing +- Specialized task delegation +- Strategic file selection (max 5 files per task) +- Context overflow prevention + +##### /create-release-note + +Two modes: +- By commit count: `/create-release-note 20` +- Interactive selection after viewing commits + +Outputs: +- Customer-facing release note (value-focused) +- Technical engineering note (SHA references, file paths) + +##### /secure-prompts + +Test prompts available at `.claude/commands/security/test-examples/`: +- `test-encoding-attacks.md` +- `test-advanced-injection.md` +- `test-basic-role-override.md` +- `test-css-hiding.md` +- `test-invisible-chars.md` +- `test-authority-claims.md` + +Reports saved to `reports/secure-prompts/`. + +##### /refactor-code + +Analysis-only refactoring that: +- Analyzes code complexity +- Assesses test coverage +- Identifies architectural patterns +- Creates step-by-step plans +- Generates risk assessment +- Outputs to `reports/refactor/` + +--- + +# Part V: Alternative Providers + +## Chapter 13: Z.AI Integration + +### 13.1 Overview + +[Z.AI's GLM Coding Plan](https://z.ai) provides cost-effective access to GLM models optimized for coding. + +**Features**: +- 55+ tokens/second performance +- Vision Understanding +- Web Search, Web Reader MCP servers +- GLM-4.7 with state-of-the-art reasoning + +### 13.2 Pricing & Plans + +| Plan | Prompts/5hrs | Monthly Cost | vs Claude | +|------|--------------|--------------|-----------| +| Lite | ~120 | ~$3 | 3× Claude Pro quota | +| Pro | ~600 | Higher | 3× Claude Max 5x quota | +| Max | ~2,400 | Higher | 3× Claude Max 20x quota | + +Each prompt allows 15–20 model calls = billions of tokens monthly at ~1% of standard API pricing. + +**Discount**: 10% off with invite code [`WWB8IFLROM`](https://z.ai/subscribe?ic=WWB8IFLROM) + +### 13.3 Privacy & Data Handling + +| Aspect | Details | +|--------|---------| +| Data Location | Singapore | +| Storage | No content storage | +| Policy | [Privacy Policy](https://docs.z.ai/legal-agreement/privacy-policy) | + +### 13.4 Setup Instructions + +#### Prerequisites + +- Node.js 18+ +- Z.AI API key from [dashboard](https://z.ai) +- [Official docs](https://docs.z.ai/devpack/tool/claude) + +#### Automated (macOS/Linux) + +```bash +curl -O "https://cdn.bigmodel.cn/install/claude_code_zai_env.sh" && bash ./claude_code_zai_env.sh +``` + +#### Manual Configuration + +Edit `~/.claude/settings.json`: +```json +{ + "env": { + "ANTHROPIC_AUTH_TOKEN": "your-zai-api-key", + "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic", + "API_TIMEOUT_MS": "3000000" + } +} +``` + +### 13.5 Shell Function Launchers + +#### macOS / Linux (Bash/Zsh) + +Add to `~/.bashrc`, `~/.zshrc`, or `~/.bash_aliases`: + +```bash +# Z.AI + Claude Code launcher +zai() { + export ANTHROPIC_AUTH_TOKEN="your-zai-api-key" + export ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic" + export API_TIMEOUT_MS="3000000" + claude "$@" +} +``` + +Reload: `source ~/.bashrc` or `source ~/.zshrc` + +
+Windows PowerShell + +Add to PowerShell profile (`notepad $PROFILE`): + +```powershell +# Z.AI + Claude Code launcher +function zai { + $env:ANTHROPIC_AUTH_TOKEN = "your-zai-api-key" + $env:ANTHROPIC_BASE_URL = "https://api.z.ai/api/anthropic" + $env:API_TIMEOUT_MS = "3000000" + claude $args +} +``` + +Reload: `. $PROFILE` + +
+ +
+Windows CMD Batch + +Create `zai.bat` in a PATH directory: + +```batch +@echo off +set ANTHROPIC_AUTH_TOKEN=your-zai-api-key +set ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic +set API_TIMEOUT_MS=3000000 +claude %* +``` + +
+ +### 13.6 Model Mapping Configuration + +**Default Mapping**: + +| Claude Model | GLM Model | +|--------------|-----------| +| Opus | GLM-4.7 | +| Sonnet | GLM-4.7 | +| Haiku | GLM-4.5-Air | + +**Custom Mapping** (optional): + +In `~/.claude/settings.json`: +```json +{ + "env": { + "ANTHROPIC_AUTH_TOKEN": "your-zai-api-key", + "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic", + "API_TIMEOUT_MS": "3000000", + "ANTHROPIC_DEFAULT_OPUS_MODEL": "GLM-4.7", + "ANTHROPIC_DEFAULT_SONNET_MODEL": "GLM-4.5", + "ANTHROPIC_DEFAULT_HAIKU_MODEL": "GLM-4.5-Air" + } +} +``` + +Or in shell function: + +```bash +zai() { + export ANTHROPIC_AUTH_TOKEN="your-zai-api-key" + export ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic" + export API_TIMEOUT_MS="3000000" + export ANTHROPIC_DEFAULT_OPUS_MODEL="GLM-4.7" + export ANTHROPIC_DEFAULT_SONNET_MODEL="GLM-4.5" + export ANTHROPIC_DEFAULT_HAIKU_MODEL="GLM-4.5-Air" + claude "$@" +} +``` + +
+Windows PowerShell Custom Mapping + +```powershell +function zai { + $env:ANTHROPIC_AUTH_TOKEN = "your-zai-api-key" + $env:ANTHROPIC_BASE_URL = "https://api.z.ai/api/anthropic" + $env:API_TIMEOUT_MS = "3000000" + $env:ANTHROPIC_DEFAULT_OPUS_MODEL = "GLM-4.7" + $env:ANTHROPIC_DEFAULT_SONNET_MODEL = "GLM-4.5" + $env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "GLM-4.5-Air" + claude $args +} +``` + +
+ +
+Windows CMD Custom Mapping + +```batch +@echo off +set ANTHROPIC_AUTH_TOKEN=your-zai-api-key +set ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic +set API_TIMEOUT_MS=3000000 +set ANTHROPIC_DEFAULT_OPUS_MODEL=GLM-4.7 +set ANTHROPIC_DEFAULT_SONNET_MODEL=GLM-4.5 +set ANTHROPIC_DEFAULT_HAIKU_MODEL=GLM-4.5-Air +claude %* +``` + +
+ +**Usage**: +```bash +zai # Launch +zai --model sonnet # Specific model +zai --model opus --permission-mode plan +``` + +### 13.7 Z.AI + Git Worktree Integration + +#### macOS / Linux (Bash/Zsh) + +```bash +# Z.AI + Claude Code worktree launcher +zaix() { + local branch_name + if [ -z "$1" ]; then + branch_name="worktree-$(date +%Y%m%d-%H%M%S)" + else + branch_name="$1" + fi + git worktree add "../$branch_name" -b "$branch_name" && \ + cd "../$branch_name" || return 1 + + export ANTHROPIC_AUTH_TOKEN="your-zai-api-key" + export ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic" + export API_TIMEOUT_MS="3000000" + claude --model sonnet --permission-mode plan +} +``` + +
+Windows PowerShell Z.AI + Worktree + +```powershell +# Z.AI + Claude Code worktree launcher +function zaix { + param([string]$BranchName) + if (-not $BranchName) { + $BranchName = "worktree-$(Get-Date -Format 'yyyyMMdd-HHmmss')" + } + git worktree add "../$BranchName" -b $BranchName + if ($LASTEXITCODE -eq 0) { + Set-Location "../$BranchName" + $env:ANTHROPIC_AUTH_TOKEN = "your-zai-api-key" + $env:ANTHROPIC_BASE_URL = "https://api.z.ai/api/anthropic" + $env:API_TIMEOUT_MS = "3000000" + claude --model sonnet --permission-mode plan + } +} +``` + +
+ +
+Windows CMD Z.AI + Worktree + +Create `zaix.bat`: + +```batch +@echo off +setlocal enabledelayedexpansion +if "%~1"=="" ( + for /f "tokens=2 delims==" %%I in ('wmic os get localdatetime /value') do set datetime=%%I + set branch_name=worktree-!datetime:~0,8!-!datetime:~8,6! +) else ( + set branch_name=%~1 +) +git worktree add "../%branch_name%" -b "%branch_name%" +if %errorlevel% equ 0 ( + cd "../%branch_name%" + set ANTHROPIC_AUTH_TOKEN=your-zai-api-key + set ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic + set API_TIMEOUT_MS=3000000 + claude --model sonnet --permission-mode plan +) +endlocal +``` + +
+ +**Usage**: +```bash +zaix feature-auth # Named worktree +zaix # Auto-generated name +``` + +--- + +# Part VI: Development Workflows + +## Chapter 14: Git Worktrees + +### 14.1 Concept & Benefits + +Git worktrees enable parallel Claude Code sessions with complete code isolation. + +**Benefits**: +| Benefit | Description | +|---------|-------------| +| Parallel sessions | Run multiple AI coding sessions simultaneously | +| Code isolation | Each worktree has independent file state | +| Shared history | All worktrees share the same Git history | +| YOLO mode | Safe experimental environment | + +**Official Documentation**: [Run parallel Claude Code sessions with git worktrees](https://code.claude.com/docs/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) + +### 14.2 Shell Functions + +#### macOS / Linux Functions + +Add to `~/.bashrc`, `~/.zshrc`, or `~/.bash_aliases`: + +```bash +# Codex CLI worktree launcher +cx() { + local branch_name + if [ -z "$1" ]; then + branch_name="worktree-$(date +%Y%m%d-%H%M%S)" + else + branch_name="$1" + fi + git worktree add "../$branch_name" -b "$branch_name" && \ + cd "../$branch_name" || return 1 + codex -m gpt-5-codex --config model_reasoning_effort='xhigh' +} + +# Claude Code worktree launcher +clx() { + local branch_name + if [ -z "$1" ]; then + branch_name="worktree-$(date +%Y%m%d-%H%M%S)" + else + branch_name="$1" + fi + git worktree add "../$branch_name" -b "$branch_name" && \ + cd "../$branch_name" || return 1 + claude --model opusplan --permission-mode plan +} +``` + +Reload: `source ~/.bashrc` or `source ~/.zshrc` + +
+Windows PowerShell Functions + +Add to PowerShell profile (`notepad $PROFILE`): + +```powershell +# Codex CLI worktree launcher +function cx { + param([string]$BranchName) + if (-not $BranchName) { + $BranchName = "worktree-$(Get-Date -Format 'yyyyMMdd-HHmmss')" + } + git worktree add "../$BranchName" -b $BranchName + if ($LASTEXITCODE -eq 0) { + Set-Location "../$BranchName" + codex -m gpt-5-codex --config model_reasoning_effort='xhigh' + } +} + +# Claude Code worktree launcher +function clx { + param([string]$BranchName) + if (-not $BranchName) { + $BranchName = "worktree-$(Get-Date -Format 'yyyyMMdd-HHmmss')" + } + git worktree add "../$BranchName" -b $BranchName + if ($LASTEXITCODE -eq 0) { + Set-Location "../$BranchName" + claude --model opusplan --permission-mode plan + } +} +``` + +Reload: `. $PROFILE` + +
+ +
+Windows CMD Batch Files + +Create in a PATH directory (e.g., `C:\Users\YourName\bin\`): + +**cx.bat** - Codex CLI launcher: +```batch +@echo off +setlocal enabledelayedexpansion +if "%~1"=="" ( + for /f "tokens=2 delims==" %%I in ('wmic os get localdatetime /value') do set datetime=%%I + set branch_name=worktree-!datetime:~0,8!-!datetime:~8,6! +) else ( + set branch_name=%~1 +) +git worktree add "../%branch_name%" -b "%branch_name%" +if %errorlevel% equ 0 ( + cd "../%branch_name%" + codex -m gpt-5-codex --config model_reasoning_effort='xhigh' +) +endlocal +``` + +**clx.bat** - Claude Code launcher: +```batch +@echo off +setlocal enabledelayedexpansion +if "%~1"=="" ( + for /f "tokens=2 delims==" %%I in ('wmic os get localdatetime /value') do set datetime=%%I + set branch_name=worktree-!datetime:~0,8!-!datetime:~8,6! +) else ( + set branch_name=%~1 +) +git worktree add "../%branch_name%" -b "%branch_name%" +if %errorlevel% equ 0 ( + cd "../%branch_name%" + claude --model opusplan --permission-mode plan +) +endlocal +``` + +
+ +### 14.3 Usage Examples + +```bash +# Create worktree with custom name +clx feature-auth +cx bugfix-123 + +# Create worktree with auto-generated timestamp name +clx +cx +``` + +### 14.4 Worktree Management + +| Command | Purpose | +|---------|---------| +| `git worktree list` | List all worktrees | +| `git worktree remove ../name` | Remove a worktree | +| `git worktree prune` | Clean up stale references | + +### 14.5 The .worktreeinclude File + +**Purpose**: Specify which `.gitignore`d files to copy to new worktrees. + +**How It Works**: +- Uses `.gitignore`-style patterns +- Only files matched by **both** `.worktreeinclude` **AND** `.gitignore` are copied + +**Example** `.worktreeinclude`: +```text +# Environment files +.env +.env.local +.env.* + +# Claude Code local settings +**/.claude/settings.local.json +``` + +**Common Use Cases**: +- `.env` files with API keys +- `.env.local` for local overrides +- `.claude/settings.local.json` for personal settings + +### 14.6 Claude Desktop Integration + +| Setting | Value | +|---------|-------| +| Default location | `~/.claude-worktrees` | +| Configuration | Claude Desktop app settings | +| Requirement | Repository must be Git initialized | + +**Official Documentation**: [Claude Code on Desktop](https://code.claude.com/docs/en/desktop#claude-code-on-desktop-preview) + +### 14.7 Local Ignores (.git/info/exclude) + +**Purpose**: Ignore files locally without modifying shared `.gitignore`. + +**Usage**: +```bash +nano .git/info/exclude +``` + +**Example**: +```text +# Local IDE settings +.idea/ +*.swp + +# Personal scripts +my-local-scripts/ + +# Local test files +test-local.sh +``` + +**Comparison**: + +| File | Scope | Committed | +|------|-------|-----------| +| `.gitignore` | Team-shared | Yes | +| `.git/info/exclude` | Local only | No | +| `~/.config/git/ignore` | Global (all repos) | No | + +**Interaction with .worktreeinclude**: Files in `.git/info/exclude` work the same as `.gitignore` - patterns must appear in both files for copying to worktrees. + +--- + +## Chapter 15: Status Lines + +### 15.1 Configuration + +Add to `~/.claude/settings.json`: + +```json +{ + "statusLine": { + "type": "command", + "command": "~/.claude/statuslines/statusline.sh", + "padding": 0 + } +} +``` + +### 15.2 JSON Input Structure + +The status line script receives JSON input with: + +| Field | Path | Description | +|-------|------|-------------| +| Model | `.model.display_name` | Current model name | +| Directory | `.workspace.current_dir` | Working directory | +| Input Tokens | `.context_window.total_input_tokens` | Total input tokens | +| Output Tokens | `.context_window.total_output_tokens` | Total output tokens | +| Context Size | `.context_window.context_window_size` | Context window size | +| Cost | `.cost.total_cost_usd` | Session cost in USD | +| Lines Added | `.cost.total_lines_added` | Lines of code added | +| Lines Removed | `.cost.total_lines_removed` | Lines of code removed | + +### 15.3 Example Script (Complete) + +Create `~/.claude/statuslines/statusline.sh`: + +```bash +#!/bin/bash +# Read JSON input from stdin +input=$(cat) + +# Extract model and workspace values +MODEL_DISPLAY=$(echo "$input" | jq -r '.model.display_name') +CURRENT_DIR=$(echo "$input" | jq -r '.workspace.current_dir') + +# Extract context window metrics +INPUT_TOKENS=$(echo "$input" | jq -r '.context_window.total_input_tokens') +OUTPUT_TOKENS=$(echo "$input" | jq -r '.context_window.total_output_tokens') +CONTEXT_SIZE=$(echo "$input" | jq -r '.context_window.context_window_size') + +# Extract cost metrics +COST_USD=$(echo "$input" | jq -r '.cost.total_cost_usd') +LINES_ADDED=$(echo "$input" | jq -r '.cost.total_lines_added') +LINES_REMOVED=$(echo "$input" | jq -r '.cost.total_lines_removed') + +# Format tokens as Xk +format_tokens() { + local num="$1" + if [ "$num" -ge 1000 ]; then + echo "$((num / 1000))k" + else + echo "$num" + fi +} + +# Calculate total +TOTAL_TOKENS=$((INPUT_TOKENS + OUTPUT_TOKENS)) + +# Show git branch if in a git repo +GIT_BRANCH="" +if git rev-parse --git-dir > /dev/null 2>&1; then + BRANCH=$(git branch --show-current 2>/dev/null) + if [ -n "$BRANCH" ]; then + GIT_BRANCH=" | 🌿 $BRANCH" + fi +fi + +echo "[$MODEL_DISPLAY] 📁 ${CURRENT_DIR##*/}${GIT_BRANCH} +Tokens: $(format_tokens "$TOTAL_TOKENS") (in:$(format_tokens "$INPUT_TOKENS")+out:$(format_tokens "$OUTPUT_TOKENS")) | Ctx:$(format_tokens "$CONTEXT_SIZE") +Cost: \$${COST_USD} | +${LINES_ADDED} -${LINES_REMOVED} lines" +``` + +Make executable: `chmod +x ~/.claude/statuslines/statusline.sh` + +--- + +# Part VII: Reference + +## Chapter 16: Settings + +### 16.1 Configuration Scopes + +| Scope | Location | Affects | Shared | Priority | +|-------|----------|---------|--------|----------| +| Managed | System directories | All users | By IT | 1 (highest) | +| User | `~/.claude/settings.json` | You (all projects) | No | 5 | +| Project | `.claude/settings.json` | All collaborators | Yes | 4 | +| Local | `.claude/settings.local.json` | You (this project) | No | 3 | + +**Precedence Order** (highest to lowest): +1. Enterprise policies +2. Command line arguments +3. Local project settings +4. Shared project settings +5. User settings + +### 16.2 settings.json Options (Complete) + +| Key | Type | Description | Default | Example | +|-----|------|-------------|---------|---------| +| `apiKeyHelper` | string | Script to generate auth value | - | `/bin/generate_temp_api_key.sh` | +| `cleanupPeriodDays` | number | Days to retain chat transcripts | 30 | `20` | +| `env` | object | Environment variables for sessions | `{}` | `{"FOO": "bar"}` | +| `includeCoAuthoredBy` | boolean | Add Claude byline to commits | `true` | `false` | +| `permissions` | object | Permission configuration | - | See below | +| `statusLine` | object | Status line configuration | - | See Chapter 15 | + +### 16.3 Permission Settings + +| Key | Type | Description | Example | +|-----|------|-------------|---------| +| `allow` | array | Allowed tool use rules | `["Bash(git diff:*)"]` | +| `deny` | array | Denied tool use rules | `["WebFetch", "Bash(curl:*)"]` | +| `additionalDirectories` | array | Extra working directories | `["../docs/"]` | +| `defaultMode` | string | Default permission mode | `"acceptEdits"` | +| `disableBypassPermissionsMode` | string | Prevent bypass mode | `"disable"` | + +### 16.4 Sandbox Settings + +For dev containers and isolated environments, see [Dev Container Setup](https://claude-devcontainers.centminmod.com/). + +--- + +## Chapter 17: Environment Variables + +### 17.1 Authentication Variables + +| Variable | Description | +|----------|-------------| +| `ANTHROPIC_API_KEY` | API key sent as `X-Api-Key` header | +| `ANTHROPIC_AUTH_TOKEN` | Custom value for `Authorization` header (prefixed with `Bearer `) | +| `ANTHROPIC_CUSTOM_HEADERS` | Custom headers in `Name: Value` format | + +### 17.2 Model Configuration Variables + +| Variable | Description | +|----------|-------------| +| `ANTHROPIC_MODEL` | Name of custom model to use | +| `ANTHROPIC_SMALL_FAST_MODEL` | Haiku-class model for background tasks | +| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | AWS region for small/fast model on Bedrock | +| `ANTHROPIC_DEFAULT_OPUS_MODEL` | Custom Opus model mapping | +| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Custom Sonnet model mapping | +| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Custom Haiku model mapping | + +### 17.3 Behavior Variables + +| Variable | Description | Default | +|----------|-------------|---------| +| `BASH_DEFAULT_TIMEOUT_MS` | Default bash command timeout | - | +| `BASH_MAX_TIMEOUT_MS` | Maximum bash command timeout | - | +| `BASH_MAX_OUTPUT_LENGTH` | Max characters before truncation | - | +| `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` | Return to original dir after bash | - | +| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | Credential refresh interval | - | +| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | Skip IDE extension auto-install | `false` | +| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Max output tokens per request | - | +| `MAX_THINKING_TOKENS` | Force thinking budget | - | +| `MCP_TIMEOUT` | MCP server startup timeout (ms) | - | +| `MCP_TOOL_TIMEOUT` | MCP tool execution timeout (ms) | - | +| `MAX_MCP_OUTPUT_TOKENS` | Max MCP response tokens | 25000 | + +### 17.4 Complete Reference Table + +| Variable | Purpose | +|----------|---------| +| `ANTHROPIC_API_KEY` | API key for Claude SDK | +| `ANTHROPIC_AUTH_TOKEN` | Custom auth header value | +| `ANTHROPIC_BASE_URL` | Custom API endpoint | +| `ANTHROPIC_CUSTOM_HEADERS` | Custom request headers | +| `ANTHROPIC_MODEL` | Custom model name | +| `ANTHROPIC_SMALL_FAST_MODEL` | Background task model | +| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | AWS region override | +| `BASH_DEFAULT_TIMEOUT_MS` | Default bash timeout | +| `BASH_MAX_TIMEOUT_MS` | Maximum bash timeout | +| `BASH_MAX_OUTPUT_LENGTH` | Max output characters | +| `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR` | Maintain working dir | +| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | Credential TTL | +| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | Skip IDE auto-install | +| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | Max output tokens | +| `CLAUDE_CODE_USE_BEDROCK` | Use Amazon Bedrock | +| `CLAUDE_CODE_USE_VERTEX` | Use Google Vertex AI | +| `CLAUDE_CODE_SKIP_BEDROCK_AUTH` | Skip Bedrock auth | +| `CLAUDE_CODE_SKIP_VERTEX_AUTH` | Skip Vertex auth | +| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | Disable non-essential traffic | +| `DISABLE_AUTOUPDATER` | Disable auto-updates | +| `DISABLE_BUG_COMMAND` | Disable `/bug` command | +| `DISABLE_COST_WARNINGS` | Disable cost warnings | +| `DISABLE_ERROR_REPORTING` | Opt out of Sentry | +| `DISABLE_NON_ESSENTIAL_MODEL_CALLS` | Disable flavor text calls | +| `DISABLE_TELEMETRY` | Opt out of Statsig | +| `HTTP_PROXY` | HTTP proxy server | +| `HTTPS_PROXY` | HTTPS proxy server | +| `MAX_THINKING_TOKENS` | Thinking budget | +| `MCP_TIMEOUT` | MCP startup timeout | +| `MCP_TOOL_TIMEOUT` | MCP tool timeout | +| `MAX_MCP_OUTPUT_TOKENS` | Max MCP tokens | +| `VERTEX_REGION_CLAUDE_3_5_HAIKU` | Vertex region override | +| `VERTEX_REGION_CLAUDE_3_5_SONNET` | Vertex region override | +| `VERTEX_REGION_CLAUDE_3_7_SONNET` | Vertex region override | +| `VERTEX_REGION_CLAUDE_4_0_OPUS` | Vertex region override | +| `VERTEX_REGION_CLAUDE_4_0_SONNET` | Vertex region override | + +--- + +## Chapter 18: File Locations + +### 18.1 By Operating System + +| File | macOS | Linux | Windows | +|------|-------|-------|---------| +| User settings | `~/.claude/settings.json` | `~/.claude/settings.json` | `%USERPROFILE%\.claude\settings.json` | +| Project settings | `.claude/settings.json` | `.claude/settings.json` | `.claude\settings.json` | +| Local settings | `.claude/settings.local.json` | `.claude/settings.local.json` | `.claude\settings.local.json` | +| Managed settings | `/Library/Application Support/ClaudeCode/` | `/etc/claude-code/` | `C:\Program Files\ClaudeCode\` | +| Status line scripts | `~/.claude/statuslines/` | `~/.claude/statuslines/` | `%USERPROFILE%\.claude\statuslines\` | +| Hooks | `.claude/hooks/` | `.claude/hooks/` | `.claude\hooks\` | +| Skills | `.claude/skills/` | `.claude/skills/` | `.claude\skills\` | +| Agents | `.claude/agents/` | `.claude/agents/` | `.claude\agents\` | +| Commands | `.claude/commands/` | `.claude/commands/` | `.claude\commands\` | + +### 18.2 Project Files Reference + +| File | Purpose | Committed | +|------|---------|-----------| +| `CLAUDE.md` | Main memory bank | Yes | +| `CLAUDE-*.md` | Context files | Yes | +| `.claude/settings.json` | Shared settings | Yes | +| `.claude/settings.local.json` | Personal settings | No | +| `.claude/hooks/` | Custom hooks | Yes | +| `.claude/skills/` | Custom skills | Yes | +| `.claude/agents/` | Custom subagents | Yes | +| `.claude/commands/` | Custom commands | Yes | +| `.worktreeinclude` | Worktree file patterns | Yes | + +--- + +## Chapter 19: Tools Available to Claude + +### 19.1 Complete Tool Reference + +| Tool | Description | Permission Required | +|------|-------------|---------------------| +| Agent | Runs a sub-agent for complex, multi-step tasks | No | +| Bash | Executes shell commands in your environment | Yes | +| Edit | Makes targeted edits to specific files | Yes | +| Glob | Finds files based on pattern matching | No | +| Grep | Searches for patterns in file contents | No | +| LS | Lists files and directories | No | +| MultiEdit | Performs multiple edits on a single file atomically | Yes | +| NotebookEdit | Modifies Jupyter notebook cells | Yes | +| NotebookRead | Reads and displays Jupyter notebook contents | No | +| Read | Reads the contents of files | No | +| TodoRead | Reads the current session's task list | No | +| TodoWrite | Creates and manages structured task lists | No | +| WebFetch | Fetches content from a specified URL | Yes | +| WebSearch | Performs web searches with domain filtering | Yes | +| Write | Creates or overwrites files | Yes | + +**Permission Rules**: Configure with `/allowed-tools` or in permission settings. + +**Extending Tools**: Use hooks to run custom commands before/after tool execution. + +--- + +## Chapter 20: Cost & Rate Management + +### 20.1 Weekly Rate Limits + +From August 28, 2025, weekly limits apply (in addition to monthly 50x 5hr session limit): + +| Plan | Sonnet 4 (hrs/week) | Opus 4 (hrs/week) | +|------|---------------------|-------------------| +| Pro | 40–80 | – | +| Max ($100/mo) | 140–280 | 15–35 | +| Max ($200/mo) | 240–480 | 24–40 | + +### 20.2 Cost Optimization Strategies + +| Strategy | Benefit | How | +|----------|---------|-----| +| Z.AI Integration | 3× higher quotas at ~$3/mo | Use shell function launcher | +| CoD Mode | 80% token reduction | Request "use CoD" in code-searcher | +| Git Worktrees | Parallel sessions without duplicating quota | Use shell functions | +| Status Lines | Real-time monitoring | Configure statusline.sh | +| MCP Metrics | Cost tracking | Install Usage Metrics MCP | +| Context Cleanup | 15-25% token reduction | Use `/cleanup-context` | + +--- + +# Appendices + +## Appendix A: Quick Reference Cards + +### Installation Checklist + +- [ ] Claude AI account (Pro/Max) +- [ ] Node.js 18+ +- [ ] Git installed +- [ ] Fast tools: `brew install ripgrep fd jq` +- [ ] Clone repository +- [ ] Run `/init` in Claude Code + +### Common Commands + +| Command | Purpose | +|---------|---------| +| `/init` | Initialize memory bank | +| `/config` | Configure Claude Code | +| `/help` | Show help | +| `update memory bank` | Update CLAUDE-*.md files | +| `/ccusage-daily` | Show usage statistics | +| `/security-audit` | Run security audit | + +### Keyboard Shortcuts + +See official Claude Code documentation for current shortcuts. + +--- + +## Appendix B: Troubleshooting + +### Common Issues + +| Issue | Solution | +|-------|----------| +| Memory bank not loading | Ensure CLAUDE.md exists in project root | +| MCP server not connecting | Run `claude mcp list` to verify | +| Slow searches | Install ripgrep and fd | +| High token usage | Use CoD mode, cleanup context | +| Z.AI not working | Check API key and base URL | + +### Error Messages + +| Error | Cause | Fix | +|-------|-------|-----| +| `No API key found` | Missing authentication | Set `ANTHROPIC_API_KEY` or run `/login` | +| `MCP timeout` | Server startup too slow | Increase `MCP_TIMEOUT` | +| `Context window exceeded` | Too much content | Use `/cleanup-context` | + +--- + +## Appendix C: Resources + +### Official Documentation + +| Resource | URL | +|----------|-----| +| Claude Code Overview | https://docs.anthropic.com/en/docs/claude-code/overview | +| Settings Reference | https://code.claude.com/docs/en/settings | +| Hooks Documentation | https://code.claude.com/docs/en/hooks | +| Skills Documentation | https://docs.claude.com/en/docs/claude-code/skills | +| Sub-agents | https://docs.anthropic.com/en/docs/claude-code/sub-agents | +| Plugin Marketplace | https://code.claude.com/docs/en/discover-plugins | +| Git Worktrees | https://code.claude.com/docs/en/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees | +| Claude Desktop | https://code.claude.com/docs/en/desktop#claude-code-on-desktop-preview | + +### YouTube Guides + +| Topic | Creator | URL | +|-------|---------|-----| +| 31 Days of Claude Code | Ado Kukic (Anthropic) | https://adocomplete.com/advent-of-claude-2025/ | +| Claude Code with Opus 4.5 | Alex Finn | https://www.youtube.com/watch?v=UVJXh57MgI0 | +| Claude Code Overview | Matt Maher | https://www.youtube.com/watch?v=Dekx_OzRwiI | +| VS Code Beginner | - | https://www.youtube.com/watch?v=rPITZvwyoMc | +| VS Code Advanced | - | https://www.youtube.com/watch?v=P-5bWpUbO60 | +| Git for VS Code | - | https://www.youtube.com/watch?v=twsYxYaQikI | +| Ralph Wiggum | Greg Isenberg | https://www.youtube.com/watch?v=RpvQH0r0ecM | + +### Community Resources + +| Resource | URL | +|----------|-----| +| Safety Net Plugin | https://github.com/kenryu42/claude-code-safety-net | +| Ralph Wiggum Repo | https://github.com/snarktank/ralph | +| Dev Container Setup | https://claude-devcontainers.centminmod.com/ | + +--- + +## Appendix D: Star History & Stats + +### Star History + +[![Star History Chart](https://api.star-history.com/svg?repos=centminmod/my-claude-code-setup&type=Date)](https://www.star-history.com/#centminmod/my-claude-code-setup&Date) + +### Repository Stats + +![Alt](https://repobeats.axiom.co/api/embed/715da1679915da77d87deb99a1f527a44e76ec60.svg "Repobeats analytics image") diff --git a/README.md b/README.md index 9aedea8..ae21cee 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,17 @@ # My Claude Code Project's Starter Settings +## Alternate Read Me Guides + +The beauty of using AI is that I can get AI to generate alternate Read Me guides using different formats and styles to suit different readers and learners. So I asked Claude Code to generate alternate Read Me guides in different styles - pick one that suits you best. + +* [README.md](README.md) - Original written version below +* [README-v2.md](README-v2.md) - Progressive Disclosure Guide (Beginner → Intermediate → Advanced sections) +* [README-v3.md](README-v3.md) - Task-Based Guide ("I want to..." navigation for goal-oriented users) +* [README-v4.md](README-v4.md) - Technical Reference Manual (Chapter-based, dense reference format) + +## Overview + My Claude Code project's starter settings and Claude Code hooks and slash commands are provided in this repository for users to try out. The [CLAUDE.md](https://github.com/centminmod/my-claude-code-setup/blob/master/CLAUDE.md) is setup as set of memory bank files to better retain context over many chat sessions. Be sure to read the official Claude Code docs first at and sign up for a [paid Claude AI account](https://claude.ai/) to use Claude Code. You can pay for Claude Pro $20/month, Claude Max $100/month or Claude Max $200/month. The paid Claude tier plans will include varying quotas for usage and rate limits outlined [here](https://support.anthropic.com/en/articles/9797557-usage-limit-best-practices). You can also use Claude Code with [Z.AI](#using-zai-with-claude-code) to get higher token usage quotas and get access to Z.AI GLM-4.7 LLM models within Claude Code. 1. Copy the files in this Github repo to your project directory (where you intended codebase will be). From 404918e095f59e0ff499d4114982fff9f3ca5146 Mon Sep 17 00:00:00 2001 From: George Liu Date: Tue, 13 Jan 2026 15:00:36 +1000 Subject: [PATCH 076/174] update readmes --- README-v2.md | 4 +++- README.md | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/README-v2.md b/README-v2.md index 68bb09a..68fa85a 100644 --- a/README-v2.md +++ b/README-v2.md @@ -5,7 +5,9 @@ # My Claude Code Setup -A comprehensive starter kit for Claude Code projects featuring a memory bank system for context retention, pre-configured hooks, skills, subagents, and MCP server recommendations. +A comprehensive starter kit for Claude Code projects featuring a memory bank system for context retention, pre-configured hooks, skills, subagents, and MCP server recommendations. + +You can also use Claude Code with [Z.AI](#6-alternative-providers) to get higher token usage quotas and get access to Z.AI GLM-4.7 LLM models within Claude Code. Use [Z.AI invite code for additional 10% discount](https://z.ai/subscribe?ic=WWB8IFLROM) which can stack with current 50-60% yearly discounts. ## Table of Contents diff --git a/README.md b/README.md index ae21cee..680ab63 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ The beauty of using AI is that I can get AI to generate alternate Read Me guides ## Overview -My Claude Code project's starter settings and Claude Code hooks and slash commands are provided in this repository for users to try out. The [CLAUDE.md](https://github.com/centminmod/my-claude-code-setup/blob/master/CLAUDE.md) is setup as set of memory bank files to better retain context over many chat sessions. Be sure to read the official Claude Code docs first at and sign up for a [paid Claude AI account](https://claude.ai/) to use Claude Code. You can pay for Claude Pro $20/month, Claude Max $100/month or Claude Max $200/month. The paid Claude tier plans will include varying quotas for usage and rate limits outlined [here](https://support.anthropic.com/en/articles/9797557-usage-limit-best-practices). You can also use Claude Code with [Z.AI](#using-zai-with-claude-code) to get higher token usage quotas and get access to Z.AI GLM-4.7 LLM models within Claude Code. +My Claude Code project's starter settings and Claude Code hooks and slash commands are provided in this repository for users to try out. The [CLAUDE.md](https://github.com/centminmod/my-claude-code-setup/blob/master/CLAUDE.md) is setup as set of memory bank files to better retain context over many chat sessions. Be sure to read the official Claude Code docs first at and sign up for a [paid Claude AI account](https://claude.ai/) to use Claude Code. You can pay for Claude Pro $20/month, Claude Max $100/month or Claude Max $200/month. The paid Claude tier plans will include varying quotas for usage and rate limits outlined [here](https://support.anthropic.com/en/articles/9797557-usage-limit-best-practices). You can also use Claude Code with [Z.AI](#using-zai-with-claude-code) to get higher token usage quotas and get access to Z.AI GLM-4.7 LLM models within Claude Code. Use [Z.AI invite code for additional 10% discount](https://z.ai/subscribe?ic=WWB8IFLROM) which can stack with current 50-60% yearly discounts. 1. Copy the files in this Github repo to your project directory (where you intended codebase will be). 2. Modify the template files and CLAUDE.md`to your liking. `.claude/settings.json` needs to install Terminal-Notifier for macOS https://github.com/centminmod/terminal-notifier-setup. If you're not using macOS, you can remove `.claude/settings.json`. From ea67700ff7e5565d7f39906541cac141abae50de Mon Sep 17 00:00:00 2001 From: George Liu Date: Tue, 13 Jan 2026 15:03:20 +1000 Subject: [PATCH 077/174] update --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 680ab63..8ad140c 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ The beauty of using AI is that I can get AI to generate alternate Read Me guides using different formats and styles to suit different readers and learners. So I asked Claude Code to generate alternate Read Me guides in different styles - pick one that suits you best. -* [README.md](README.md) - Original written version below +* [README.md](README.md) - Original written version I did myself below * [README-v2.md](README-v2.md) - Progressive Disclosure Guide (Beginner → Intermediate → Advanced sections) * [README-v3.md](README-v3.md) - Task-Based Guide ("I want to..." navigation for goal-oriented users) * [README-v4.md](README-v4.md) - Technical Reference Manual (Chapter-based, dense reference format) From ac44bb438fc43a9d59d767c03f35b3e7208041c0 Mon Sep 17 00:00:00 2001 From: George Liu Date: Tue, 13 Jan 2026 15:03:50 +1000 Subject: [PATCH 078/174] update readme --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8ad140c..567437f 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ ## Alternate Read Me Guides -The beauty of using AI is that I can get AI to generate alternate Read Me guides using different formats and styles to suit different readers and learners. So I asked Claude Code to generate alternate Read Me guides in different styles - pick one that suits you best. +The beauty of using AI is that I can get AI to generate alternate Read Me guides using different formats and styles to suit different readers and learners. So I asked Claude Code to generate alternate Read Me guides in different styles - pick one that suits you best or read all of them to get a better understanding of how to use this project. * [README.md](README.md) - Original written version I did myself below * [README-v2.md](README-v2.md) - Progressive Disclosure Guide (Beginner → Intermediate → Advanced sections) From b2491ad05b6291404a94428cb11275f8779673fa Mon Sep 17 00:00:00 2001 From: George Liu Date: Tue, 13 Jan 2026 15:56:30 +1000 Subject: [PATCH 079/174] update --- README-v2.md | 6 +++++- README-v3.md | 13 +++++++++---- README-v4.md | 8 +++++++- 3 files changed, 21 insertions(+), 6 deletions(-) diff --git a/README-v2.md b/README-v2.md index 68fa85a..34b273a 100644 --- a/README-v2.md +++ b/README-v2.md @@ -1238,12 +1238,16 @@ claude config set -g ### YouTube Guides -- [Advent of Claude: 31 Days of Claude Code](https://adocomplete.com/advent-of-claude-2025/) - Ado Kukic (Anthropic) - [Claude Code with Opus 4.5](https://www.youtube.com/watch?v=UVJXh57MgI0) - Alex Finn - [Claude Code Overview](https://www.youtube.com/watch?v=Dekx_OzRwiI) - Matt Maher - [VS Code Beginner Guide](https://www.youtube.com/watch?v=rPITZvwyoMc) - [Ralph Wiggum Tutorial](https://www.youtube.com/watch?v=RpvQH0r0ecM) - Greg Isenberg & Ryan Carson +### Other Resources + +* [Advent of Claude: 31 Days](https://adocomplete.com/advent-of-claude-2025/) - Ado Kukic +* [40+ Claude Code Tips](https://github.com/ykdojo/claude-code-tips) + --- ## Star History diff --git a/README-v3.md b/README-v3.md index b6351c3..0313643 100644 --- a/README-v3.md +++ b/README-v3.md @@ -944,10 +944,15 @@ claude config set -g # Global setting ### YouTube Guides -- [Advent of Claude: 31 Days](https://adocomplete.com/advent-of-claude-2025/) - Ado Kukic -- [Claude Code with Opus 4.5](https://www.youtube.com/watch?v=UVJXh57MgI0) - Alex Finn -- [Claude Code Overview](https://www.youtube.com/watch?v=Dekx_OzRwiI) - Matt Maher -- [Ralph Wiggum Tutorial](https://www.youtube.com/watch?v=RpvQH0r0ecM) - Greg Isenberg +* [Claude Code with Opus 4.5](https://www.youtube.com/watch?v=UVJXh57MgI0) - Alex Finn +* [Claude Code Overview](https://www.youtube.com/watch?v=Dekx_OzRwiI) - Matt Maher +* [VS Code Beginner Guide](https://www.youtube.com/watch?v=rPITZvwyoMc) +* [Ralph Wiggum Tutorial](https://www.youtube.com/watch?v=RpvQH0r0ecM) - Greg Isenberg & Ryan Carson + +### Other Resources + +* [Advent of Claude: 31 Days](https://adocomplete.com/advent-of-claude-2025/) - Ado Kukic +* [40+ Claude Code Tips](https://github.com/ykdojo/claude-code-tips) --- diff --git a/README-v4.md b/README-v4.md index f6670d7..199a551 100644 --- a/README-v4.md +++ b/README-v4.md @@ -1719,7 +1719,6 @@ See official Claude Code documentation for current shortcuts. | Topic | Creator | URL | |-------|---------|-----| -| 31 Days of Claude Code | Ado Kukic (Anthropic) | https://adocomplete.com/advent-of-claude-2025/ | | Claude Code with Opus 4.5 | Alex Finn | https://www.youtube.com/watch?v=UVJXh57MgI0 | | Claude Code Overview | Matt Maher | https://www.youtube.com/watch?v=Dekx_OzRwiI | | VS Code Beginner | - | https://www.youtube.com/watch?v=rPITZvwyoMc | @@ -1727,6 +1726,13 @@ See official Claude Code documentation for current shortcuts. | Git for VS Code | - | https://www.youtube.com/watch?v=twsYxYaQikI | | Ralph Wiggum | Greg Isenberg | https://www.youtube.com/watch?v=RpvQH0r0ecM | +### Other Guides + +| Topic | Creator | URL | +|-------|---------|-----| +| 31 Days of Claude Code | Ado Kukic (Anthropic) | | +| 40+ Claude Code Tips | ykdojo | | + ### Community Resources | Resource | URL | From 8fd876a0c337ead0959da164cc0396953aceeadf Mon Sep 17 00:00:00 2001 From: George Liu Date: Tue, 13 Jan 2026 18:23:41 +1000 Subject: [PATCH 080/174] update statusline.sh script for new Claude Code 2.1.6 fields --- README-v2.md | 21 ++++++++++++++++++++- README-v3.md | 40 +++++++++++++++++++++++++++++++++++++--- README-v4.md | 21 ++++++++++++++++++++- README.md | 21 ++++++++++++++++++++- 4 files changed, 97 insertions(+), 6 deletions(-) diff --git a/README-v2.md b/README-v2.md index 34b273a..4676aeb 100644 --- a/README-v2.md +++ b/README-v2.md @@ -622,6 +622,10 @@ COST_USD=$(echo "$input" | jq -r '.cost.total_cost_usd') LINES_ADDED=$(echo "$input" | jq -r '.cost.total_lines_added') LINES_REMOVED=$(echo "$input" | jq -r '.cost.total_lines_removed') +# Extract percentage metrics +USED_PERCENTAGE=$(echo "$input" | jq -r '.context_window.used_percentage') +REMAINING_PERCENTAGE=$(echo "$input" | jq -r '.context_window.remaining_percentage') + # Format tokens as Xk format_tokens() { local num="$1" @@ -632,9 +636,24 @@ format_tokens() { fi } +# Generate progress bar for context usage +generate_progress_bar() { + local percentage=$1 + local bar_width=20 + local filled=$(awk "BEGIN {printf \"%.0f\", ($percentage / 100) * $bar_width}") + local empty=$((bar_width - filled)) + local bar="" + for ((i=0; i /dev/null 2>&1; then @@ -645,7 +664,7 @@ if git rev-parse --git-dir > /dev/null 2>&1; then fi echo "[$MODEL_DISPLAY] 📁 ${CURRENT_DIR##*/}${GIT_BRANCH} -Tokens: $(format_tokens "$TOTAL_TOKENS") (in:$(format_tokens "$INPUT_TOKENS")+out:$(format_tokens "$OUTPUT_TOKENS")) | Ctx:$(format_tokens "$CONTEXT_SIZE") +Context: [$PROGRESS_BAR] ${USED_PERCENTAGE}% Cost: \$${COST_USD} | +${LINES_ADDED} -${LINES_REMOVED} lines" ``` diff --git a/README-v3.md b/README-v3.md index 0313643..9d35bbc 100644 --- a/README-v3.md +++ b/README-v3.md @@ -793,32 +793,66 @@ Add to `~/.claude/settings.json`: Create `~/.claude/statuslines/statusline.sh`: ```bash #!/bin/bash +# Read JSON input from stdin input=$(cat) +# Extract model and workspace values MODEL_DISPLAY=$(echo "$input" | jq -r '.model.display_name') CURRENT_DIR=$(echo "$input" | jq -r '.workspace.current_dir') + +# Extract context window metrics INPUT_TOKENS=$(echo "$input" | jq -r '.context_window.total_input_tokens') OUTPUT_TOKENS=$(echo "$input" | jq -r '.context_window.total_output_tokens') CONTEXT_SIZE=$(echo "$input" | jq -r '.context_window.context_window_size') + +# Extract cost metrics COST_USD=$(echo "$input" | jq -r '.cost.total_cost_usd') LINES_ADDED=$(echo "$input" | jq -r '.cost.total_lines_added') LINES_REMOVED=$(echo "$input" | jq -r '.cost.total_lines_removed') +# Extract percentage metrics +USED_PERCENTAGE=$(echo "$input" | jq -r '.context_window.used_percentage') +REMAINING_PERCENTAGE=$(echo "$input" | jq -r '.context_window.remaining_percentage') + +# Format tokens as Xk format_tokens() { local num="$1" - if [ "$num" -ge 1000 ]; then echo "$((num / 1000))k"; else echo "$num"; fi + if [ "$num" -ge 1000 ]; then + echo "$((num / 1000))k" + else + echo "$num" + fi } +# Generate progress bar for context usage +generate_progress_bar() { + local percentage=$1 + local bar_width=20 + local filled=$(awk "BEGIN {printf \"%.0f\", ($percentage / 100) * $bar_width}") + local empty=$((bar_width - filled)) + local bar="" + for ((i=0; i /dev/null 2>&1; then BRANCH=$(git branch --show-current 2>/dev/null) - [ -n "$BRANCH" ] && GIT_BRANCH=" | 🌿 $BRANCH" + if [ -n "$BRANCH" ]; then + GIT_BRANCH=" | 🌿 $BRANCH" + fi fi echo "[$MODEL_DISPLAY] 📁 ${CURRENT_DIR##*/}${GIT_BRANCH} -Tokens: $(format_tokens "$TOTAL_TOKENS") (in:$(format_tokens "$INPUT_TOKENS")+out:$(format_tokens "$OUTPUT_TOKENS")) | Ctx:$(format_tokens "$CONTEXT_SIZE") +Context: [$PROGRESS_BAR] ${USED_PERCENTAGE}% Cost: \$${COST_USD} | +${LINES_ADDED} -${LINES_REMOVED} lines" ``` diff --git a/README-v4.md b/README-v4.md index 199a551..090557e 100644 --- a/README-v4.md +++ b/README-v4.md @@ -1405,6 +1405,10 @@ COST_USD=$(echo "$input" | jq -r '.cost.total_cost_usd') LINES_ADDED=$(echo "$input" | jq -r '.cost.total_lines_added') LINES_REMOVED=$(echo "$input" | jq -r '.cost.total_lines_removed') +# Extract percentage metrics +USED_PERCENTAGE=$(echo "$input" | jq -r '.context_window.used_percentage') +REMAINING_PERCENTAGE=$(echo "$input" | jq -r '.context_window.remaining_percentage') + # Format tokens as Xk format_tokens() { local num="$1" @@ -1415,9 +1419,24 @@ format_tokens() { fi } +# Generate progress bar for context usage +generate_progress_bar() { + local percentage=$1 + local bar_width=20 + local filled=$(awk "BEGIN {printf \"%.0f\", ($percentage / 100) * $bar_width}") + local empty=$((bar_width - filled)) + local bar="" + for ((i=0; i /dev/null 2>&1; then @@ -1428,7 +1447,7 @@ if git rev-parse --git-dir > /dev/null 2>&1; then fi echo "[$MODEL_DISPLAY] 📁 ${CURRENT_DIR##*/}${GIT_BRANCH} -Tokens: $(format_tokens "$TOTAL_TOKENS") (in:$(format_tokens "$INPUT_TOKENS")+out:$(format_tokens "$OUTPUT_TOKENS")) | Ctx:$(format_tokens "$CONTEXT_SIZE") +Context: [$PROGRESS_BAR] ${USED_PERCENTAGE}% Cost: \$${COST_USD} | +${LINES_ADDED} -${LINES_REMOVED} lines" ``` diff --git a/README.md b/README.md index 567437f..24decc8 100644 --- a/README.md +++ b/README.md @@ -192,6 +192,10 @@ COST_USD=$(echo "$input" | jq -r '.cost.total_cost_usd') LINES_ADDED=$(echo "$input" | jq -r '.cost.total_lines_added') LINES_REMOVED=$(echo "$input" | jq -r '.cost.total_lines_removed') +# Extract percentage metrics +USED_PERCENTAGE=$(echo "$input" | jq -r '.context_window.used_percentage') +REMAINING_PERCENTAGE=$(echo "$input" | jq -r '.context_window.remaining_percentage') + # Format tokens as Xk format_tokens() { local num="$1" @@ -202,9 +206,24 @@ format_tokens() { fi } +# Generate progress bar for context usage +generate_progress_bar() { + local percentage=$1 + local bar_width=20 + local filled=$(awk "BEGIN {printf \"%.0f\", ($percentage / 100) * $bar_width}") + local empty=$((bar_width - filled)) + local bar="" + for ((i=0; i /dev/null 2>&1; then @@ -215,7 +234,7 @@ if git rev-parse --git-dir > /dev/null 2>&1; then fi echo "[$MODEL_DISPLAY] 📁 ${CURRENT_DIR##*/}${GIT_BRANCH} -Tokens: $(format_tokens "$TOTAL_TOKENS") (in:$(format_tokens "$INPUT_TOKENS")+out:$(format_tokens "$OUTPUT_TOKENS")) | Ctx:$(format_tokens "$CONTEXT_SIZE") +Context: [$PROGRESS_BAR] ${USED_PERCENTAGE}% Cost: \$${COST_USD} | +${LINES_ADDED} -${LINES_REMOVED} lines" ``` From de47d63dd07347ff98c375214d65fd42504ae944 Mon Sep 17 00:00:00 2001 From: George Liu Date: Tue, 13 Jan 2026 20:15:26 +1000 Subject: [PATCH 081/174] add consult-zai and consult-codex skill/agent pairs --- .claude/agents/codex-cli.md | 16 ++++ .claude/agents/zai-cli.md | 16 ++++ .claude/settings.local.json | 4 +- .claude/skills/consult-codex/SKILL.md | 126 ++++++++++++++++++++++++++ .claude/skills/consult-zai/SKILL.md | 126 ++++++++++++++++++++++++++ README-v2.md | 18 ++++ README-v3.md | 4 + README-v4.md | 52 +++++++++++ README.md | 44 +++++++++ 9 files changed, 405 insertions(+), 1 deletion(-) create mode 100644 .claude/agents/codex-cli.md create mode 100644 .claude/agents/zai-cli.md create mode 100644 .claude/skills/consult-codex/SKILL.md create mode 100644 .claude/skills/consult-zai/SKILL.md diff --git a/.claude/agents/codex-cli.md b/.claude/agents/codex-cli.md new file mode 100644 index 0000000..c3f9a4d --- /dev/null +++ b/.claude/agents/codex-cli.md @@ -0,0 +1,16 @@ +--- +name: codex-cli +description: Execute OpenAI Codex CLI (GPT-5.2) for code analysis. Use when you need Codex's GPT-5.2 perspective on code. +tools: Bash +model: haiku +--- + +You are a simple CLI wrapper for OpenAI Codex GPT-5.2. + +When invoked with a prompt, execute this bash command (with 120000ms timeout): + +```bash +codex -p readonly exec "PROMPT" --json +``` + +Replace PROMPT with the exact prompt you received. Return the raw JSON output without any analysis or modification. diff --git a/.claude/agents/zai-cli.md b/.claude/agents/zai-cli.md new file mode 100644 index 0000000..2020727 --- /dev/null +++ b/.claude/agents/zai-cli.md @@ -0,0 +1,16 @@ +--- +name: zai-cli +description: Execute z.ai GLM 4.7 model via Claude Code CLI. Use when you need z.ai's GLM 4.7 perspective on code analysis. +tools: Bash +model: haiku +--- + +You are a simple CLI wrapper for z.ai's GLM 4.7 model. + +When invoked with a prompt, execute this bash command (with 120000ms timeout): + +```bash +bash -i -c 'zai -p "PROMPT" --output-format json --append-system-prompt "You are GLM 4.7 model accessed via z.ai API, not an Anthropic Claude model."' +``` + +Replace PROMPT with the exact prompt you received. Return the raw output without any analysis or modification. diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 0d057b7..3e3dc7d 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -87,7 +87,9 @@ "Skill(claude-docs-consultant)", "WebFetch(domain:docs.convex.dev)", "mcp__context7__query-docs", - "WebFetch(domain:docs.z.ai)" + "WebFetch(domain:docs.z.ai)", + "Bash(git show:*)", + "Skill(consult-zai)" ], "deny": [], "defaultMode": "plan" diff --git a/.claude/skills/consult-codex/SKILL.md b/.claude/skills/consult-codex/SKILL.md new file mode 100644 index 0000000..5fb94b3 --- /dev/null +++ b/.claude/skills/consult-codex/SKILL.md @@ -0,0 +1,126 @@ +--- +name: consult-codex +description: Compare OpenAI Codex GPT-5.2 and code-searcher responses for comprehensive dual-AI code analysis. Use when you need multiple AI perspectives on code questions. +--- + +# Dual-AI Consultation: Codex GPT-5.2 vs Code-Searcher + +You orchestrate consultation between OpenAI's Codex GPT-5.2 and Claude's code-searcher to provide comprehensive analysis with comparison. + +## When to Use This Skill + +**High value queries:** +- Complex code analysis requiring multiple perspectives +- Debugging difficult issues +- Architecture/design questions +- Code review requests +- Finding specific implementations across a codebase + +**Lower value (single AI may suffice):** +- Simple syntax questions +- Basic file lookups +- Straightforward documentation queries + +## Workflow + +When the user asks a code question: + +### 1. Build Enhanced Prompt + +Wrap the user's question with structured output requirements: + +``` +[USER_QUESTION] + +=== Analysis Guidelines === + +**Structure your response with:** +1. **Summary:** 2-3 sentence overview +2. **Key Findings:** bullet points of discoveries +3. **Evidence:** file paths with line numbers (format: `file:line` or `file:start-end`) +4. **Confidence:** High/Medium/Low with reasoning +5. **Limitations:** what couldn't be determined + +**Line Number Requirements:** +- ALWAYS include specific line numbers when referencing code +- Use format: `path/to/file.ext:42` or `path/to/file.ext:42-58` +- For multiple references: list each with its line number +- Include brief code snippets for key findings + +**Examples of good citations:** +- "The authentication check at `src/auth/validate.ts:127-134`" +- "Configuration loaded from `config/settings.json:15`" +- "Error handling in `lib/errors.ts:45, 67-72, 98`" +``` + +### 2. Invoke BOTH Agents in Parallel + +Launch both agents simultaneously in a single message with multiple tool calls: + +- Use Task tool: `subagent_type: "codex-cli"` with the enhanced prompt +- Use Task tool: `subagent_type: "code-searcher"` with the SAME enhanced prompt + +This parallel execution significantly improves response time. + +### 3. Handle Errors + +- If one agent fails or times out, still present the successful agent's response +- Note the failure in the comparison: "Agent X failed to respond: [error message]" +- Provide analysis based on the available response + +### 4. Create Comparison Analysis + +Use this exact format: + +--- + +## Codex (GPT-5.2) Response + +[Raw output from codex-cli agent] + +--- + +## Code-Searcher (Claude) Response + +[Raw output from code-searcher agent] + +--- + +## Comparison Table + +| Aspect | Codex (GPT-5.2) | Code-Searcher (Claude) | +|--------|-----------------|------------------------| +| File paths | [Specific/Generic/None] | [Specific/Generic/None] | +| Line numbers | [Provided/Missing] | [Provided/Missing] | +| Code snippets | [Yes/No + details] | [Yes/No + details] | +| Unique findings | [List any] | [List any] | +| Accuracy | [Note discrepancies] | [Note discrepancies] | +| Strengths | [Summary] | [Summary] | + +## Agreement Level + +- **High Agreement:** Both AIs reached similar conclusions - Higher confidence in findings +- **Partial Agreement:** Some overlap with unique findings - Investigate differences +- **Disagreement:** Contradicting findings - Manual verification recommended + +[State which level applies and explain] + +## Key Differences + +- **Codex GPT-5.2:** [unique findings, strengths, approach] +- **Code-Searcher:** [unique findings, strengths, approach] + +## Synthesized Summary + +[Combine the best insights from both sources into unified analysis. Prioritize findings that are: +1. Corroborated by both agents +2. Supported by specific file:line citations +3. Include verifiable code snippets] + +## Recommendation + +[Which source was more helpful for this specific query and why. Consider: +- Accuracy of file paths and line numbers +- Quality of code snippets provided +- Completeness of analysis +- Unique insights offered] diff --git a/.claude/skills/consult-zai/SKILL.md b/.claude/skills/consult-zai/SKILL.md new file mode 100644 index 0000000..c8a019a --- /dev/null +++ b/.claude/skills/consult-zai/SKILL.md @@ -0,0 +1,126 @@ +--- +name: consult-zai +description: Compare z.ai GLM 4.7 and code-searcher responses for comprehensive dual-AI code analysis. Use when you need multiple AI perspectives on code questions. +--- + +# Dual-AI Consultation: z.ai GLM 4.7 vs Code-Searcher + +You orchestrate consultation between z.ai's GLM 4.7 model and Claude's code-searcher to provide comprehensive analysis with comparison. + +## When to Use This Skill + +**High value queries:** +- Complex code analysis requiring multiple perspectives +- Debugging difficult issues +- Architecture/design questions +- Code review requests +- Finding specific implementations across a codebase + +**Lower value (single AI may suffice):** +- Simple syntax questions +- Basic file lookups +- Straightforward documentation queries + +## Workflow + +When the user asks a code question: + +### 1. Build Enhanced Prompt + +Wrap the user's question with structured output requirements: + +``` +[USER_QUESTION] + +=== Analysis Guidelines === + +**Structure your response with:** +1. **Summary:** 2-3 sentence overview +2. **Key Findings:** bullet points of discoveries +3. **Evidence:** file paths with line numbers (format: `file:line` or `file:start-end`) +4. **Confidence:** High/Medium/Low with reasoning +5. **Limitations:** what couldn't be determined + +**Line Number Requirements:** +- ALWAYS include specific line numbers when referencing code +- Use format: `path/to/file.ext:42` or `path/to/file.ext:42-58` +- For multiple references: list each with its line number +- Include brief code snippets for key findings + +**Examples of good citations:** +- "The authentication check at `src/auth/validate.ts:127-134`" +- "Configuration loaded from `config/settings.json:15`" +- "Error handling in `lib/errors.ts:45, 67-72, 98`" +``` + +### 2. Invoke BOTH Agents in Parallel + +Launch both agents simultaneously in a single message with multiple tool calls: + +- Use Task tool: `subagent_type: "zai-cli"` with the enhanced prompt +- Use Task tool: `subagent_type: "code-searcher"` with the SAME enhanced prompt + +This parallel execution significantly improves response time. + +### 3. Handle Errors + +- If one agent fails or times out, still present the successful agent's response +- Note the failure in the comparison: "Agent X failed to respond: [error message]" +- Provide analysis based on the available response + +### 4. Create Comparison Analysis + +Use this exact format: + +--- + +## z.ai (GLM 4.7) Response + +[Raw output from zai-cli agent] + +--- + +## Code-Searcher (Claude) Response + +[Raw output from code-searcher agent] + +--- + +## Comparison Table + +| Aspect | z.ai (GLM 4.7) | Code-Searcher (Claude) | +|--------|----------------|------------------------| +| File paths | [Specific/Generic/None] | [Specific/Generic/None] | +| Line numbers | [Provided/Missing] | [Provided/Missing] | +| Code snippets | [Yes/No + details] | [Yes/No + details] | +| Unique findings | [List any] | [List any] | +| Accuracy | [Note discrepancies] | [Note discrepancies] | +| Strengths | [Summary] | [Summary] | + +## Agreement Level + +- **High Agreement:** Both AIs reached similar conclusions - Higher confidence in findings +- **Partial Agreement:** Some overlap with unique findings - Investigate differences +- **Disagreement:** Contradicting findings - Manual verification recommended + +[State which level applies and explain] + +## Key Differences + +- **z.ai GLM 4.7:** [unique findings, strengths, approach] +- **Code-Searcher:** [unique findings, strengths, approach] + +## Synthesized Summary + +[Combine the best insights from both sources into unified analysis. Prioritize findings that are: +1. Corroborated by both agents +2. Supported by specific file:line citations +3. Include verifiable code snippets] + +## Recommendation + +[Which source was more helpful for this specific query and why. Consider: +- Accuracy of file paths and line numbers +- Quality of code snippets provided +- Completeness of analysis +- Unique insights offered] diff --git a/README-v2.md b/README-v2.md index 4676aeb..8f8ce96 100644 --- a/README-v2.md +++ b/README-v2.md @@ -693,6 +693,8 @@ Subagents are specialized tools that handle complex, multi-step tasks autonomous | **code-searcher** | `.claude/agents/` | Efficient codebase navigation with optional Chain of Draft mode | | **get-current-datetime** | `.claude/agents/` | Accurate Brisbane timezone (GMT+10) values | | **ux-design-expert** | `.claude/agents/` | Comprehensive UX/UI design guidance with Tailwind CSS & Highcharts | +| **zai-cli** | `.claude/agents/` | CLI wrapper for z.ai GLM 4.7 model (used by consult-zai skill) | +| **codex-cli** | `.claude/agents/` | CLI wrapper for OpenAI Codex GPT-5.2 (used by consult-codex skill) | #### memory-bank-synchronizer @@ -727,6 +729,20 @@ Comprehensive UX/UI guidance: - Data visualization with Highcharts - Accessibility compliance +#### zai-cli + +CLI wrapper for z.ai GLM 4.7 model: +- Executes z.ai CLI with JSON output +- Used internally by consult-zai skill +- Returns raw output for skill to process + +#### codex-cli + +CLI wrapper for OpenAI Codex GPT-5.2: +- Executes Codex CLI in readonly mode +- Used internally by consult-codex skill +- Returns raw output for skill to process + ### 5.2 Custom Skills Skills provide specialized capabilities. See [Agent Skills documentation](https://docs.claude.com/en/docs/claude-code/skills). @@ -736,6 +752,8 @@ Skills provide specialized capabilities. See [Agent Skills documentation](https: | Skill | Purpose | Invocation | |-------|---------|------------| | **claude-docs-consultant** | Selectively fetches official Claude Code documentation from docs.claude.com | Automatic when working on Claude Code features | +| **consult-zai** | Dual-AI consultation comparing z.ai GLM 4.7 and code-searcher | `/consult-zai "question"` or via Skill tool | +| **consult-codex** | Dual-AI consultation comparing Codex GPT-5.2 and code-searcher | `/consult-codex "question"` or via Skill tool | ### 5.3 Custom Slash Commands diff --git a/README-v3.md b/README-v3.md index 9d35bbc..9754ccf 100644 --- a/README-v3.md +++ b/README-v3.md @@ -513,6 +513,8 @@ Skills provide specialized capabilities. See [official docs](https://docs.claude | Skill | What it does | |-------|-------------| | **claude-docs-consultant** | Selectively fetches official Claude Code documentation | +| **consult-zai** | Dual-AI consultation comparing z.ai GLM 4.7 and code-searcher responses | +| **consult-codex** | Dual-AI consultation comparing Codex GPT-5.2 and code-searcher responses | ### Custom Subagents @@ -524,6 +526,8 @@ Subagents handle complex tasks autonomously with their own context window. See [ | **code-searcher** | Efficient codebase search with optional CoD mode (80% fewer tokens) | | **get-current-datetime** | Accurate Brisbane timezone (GMT+10) timestamps | | **ux-design-expert** | Comprehensive UX/UI guidance with Tailwind CSS & Highcharts | +| **zai-cli** | CLI wrapper for z.ai GLM 4.7 (used by consult-zai skill) | +| **codex-cli** | CLI wrapper for Codex GPT-5.2 (used by consult-codex skill) | ### Hooks diff --git a/README-v4.md b/README-v4.md index 090557e..7d955d5 100644 --- a/README-v4.md +++ b/README-v4.md @@ -662,6 +662,8 @@ Subagents are defined in `.claude/agents/` as markdown files. | code-searcher | `.claude/agents/code-searcher.md` | Efficient codebase navigation | Standard mode + CoD mode (80% fewer tokens) | | get-current-datetime | `.claude/agents/get-current-datetime.md` | Brisbane timezone (GMT+10) values | Multiple formats, eliminates timezone confusion | | ux-design-expert | `.claude/agents/ux-design-expert.md` | UX/UI design guidance | Tailwind CSS, Highcharts, accessibility compliance | +| zai-cli | `.claude/agents/zai-cli.md` | z.ai GLM 4.7 CLI wrapper | JSON output, used by consult-zai skill | +| codex-cli | `.claude/agents/codex-cli.md` | Codex GPT-5.2 CLI wrapper | Readonly mode, used by consult-codex skill | #### memory-bank-synchronizer @@ -720,6 +722,28 @@ Subagents are defined in `.claude/agents/` as markdown files. - Accessibility compliance - Component library design +#### zai-cli + +**Purpose**: CLI wrapper for z.ai GLM 4.7 model queries. + +**Features**: +- Executes z.ai CLI with JSON output format +- Uses haiku model for minimal overhead +- Returns raw output for parent skill to process + +**Usage**: Used internally by consult-zai skill; not typically invoked directly. + +#### codex-cli + +**Purpose**: CLI wrapper for OpenAI Codex GPT-5.2 queries. + +**Features**: +- Executes Codex CLI in readonly mode with JSON output +- Uses haiku model for minimal overhead +- Returns raw output for parent skill to process + +**Usage**: Used internally by consult-codex skill; not typically invoked directly. + --- ## Chapter 10: Skills @@ -741,6 +765,8 @@ Skills are defined in `.claude/skills/` directories containing: | Skill | Purpose | Invocation | Location | |-------|---------|------------|----------| | claude-docs-consultant | Fetch official Claude Code documentation | Automatic when working on Claude Code features | `.claude/skills/claude-docs-consultant/` | +| consult-zai | Dual-AI consultation: z.ai GLM 4.7 vs code-searcher | `/consult-zai "question"` or via Skill tool | `.claude/skills/consult-zai/` | +| consult-codex | Dual-AI consultation: Codex GPT-5.2 vs code-searcher | `/consult-codex "question"` or via Skill tool | `.claude/skills/consult-codex/` | #### claude-docs-consultant @@ -750,6 +776,32 @@ Skills are defined in `.claude/skills/` directories containing: **Behavior**: Fetches only specific documentation needed rather than loading all docs upfront. +#### consult-zai + +**Purpose**: Dual-AI consultation comparing z.ai GLM 4.7 and code-searcher responses. + +**Features**: +- Invokes both zai-cli and code-searcher agents in parallel +- Enhanced prompts requesting structured output with `file:line` citations +- Comparison table showing file paths, line numbers, code snippets, and accuracy +- Agreement level indicator (High/Partial/Disagreement) for confidence assessment +- Synthesized summary combining best insights from both AI sources + +**Usage**: `/consult-zai "your code analysis question"` or invoke via Skill tool. + +#### consult-codex + +**Purpose**: Dual-AI consultation comparing OpenAI Codex GPT-5.2 and code-searcher responses. + +**Features**: +- Invokes both codex-cli and code-searcher agents in parallel +- Enhanced prompts requesting structured output with `file:line` citations +- Comparison table showing file paths, line numbers, code snippets, and accuracy +- Agreement level indicator (High/Partial/Disagreement) for confidence assessment +- Synthesized summary combining best insights from both AI sources + +**Usage**: `/consult-codex "your code analysis question"` or invoke via Skill tool. + --- ## Chapter 11: Hooks diff --git a/README.md b/README.md index 24decc8..82d4e4c 100644 --- a/README.md +++ b/README.md @@ -749,6 +749,30 @@ Claude Code now supports [Agent Skills](https://docs.claude.com/en/docs/claude-c - **Purpose**: A specialized Claude skill which will selectively consult the official Claude Code documentation from docs.claude.com using selective fetching. This skill will invoke only when working on Claude Code hooks, skills, subagents, MCP servers, or any Claude Code feature that requires referencing official documentation for accurate implementation. Fetches only the specific documentation needed rather than loading all docs upfront +### consult-zai + +* **Purpose**: Dual-AI consultation skill that compares z.ai GLM 4.7 and code-searcher responses for comprehensive code analysis +* **Location**: `.claude/skills/consult-zai/` +* **Key Features**: + * Invokes both zai-cli and code-searcher agents in parallel for faster response + * Enhanced prompts requesting structured output with `file:line` citations + * Comparison table showing file paths, line numbers, code snippets, and accuracy + * Agreement level indicator (High/Partial/Disagreement) for confidence assessment + * Synthesized summary combining best insights from both AI sources +* **Usage**: `/consult-zai "your code analysis question"` or invoke via Skill tool + +### consult-codex + +* **Purpose**: Dual-AI consultation skill that compares OpenAI Codex GPT-5.2 and code-searcher responses for comprehensive code analysis +* **Location**: `.claude/skills/consult-codex/` +* **Key Features**: + * Invokes both codex-cli and code-searcher agents in parallel for faster response + * Enhanced prompts requesting structured output with `file:line` citations + * Comparison table showing file paths, line numbers, code snippets, and accuracy + * Agreement level indicator (High/Partial/Disagreement) for confidence assessment + * Synthesized summary combining best insights from both AI sources +* **Usage**: `/consult-codex "your code analysis question"` or invoke via Skill tool + ## Claude Code Hooks The Claude Code hook is for `STOP` which uses Terminal-Notifier to show macOS desktop notifications whenever Claude Code stops and finishes it's response https://github.com/centminmod/terminal-notifier-setup. @@ -811,6 +835,26 @@ Claude Code subagents are specialized tools designed to handle complex, multi-st - Component library design with atomic methodology - **Usage**: Use for dashboard UX improvements, premium component libraries, complex user flow optimization, design system creation, or any comprehensive UX/UI design guidance needs +### zai-cli + +* **Purpose**: CLI wrapper agent for executing z.ai GLM 4.7 model queries +* **Location**: `.claude/agents/zai-cli.md` +* **Key Features**: + * Executes z.ai CLI with JSON output format + * Uses haiku model for minimal overhead + * Returns raw output for parent skill to process +* **Usage**: Used internally by consult-zai skill; not typically invoked directly + +### codex-cli + +* **Purpose**: CLI wrapper agent for executing OpenAI Codex GPT-5.2 queries +* **Location**: `.claude/agents/codex-cli.md` +* **Key Features**: + * Executes Codex CLI in readonly mode with JSON output + * Uses haiku model for minimal overhead + * Returns raw output for parent skill to process +* **Usage**: Used internally by consult-codex skill; not typically invoked directly + ## Claude Code Slash Commands ### `/anthropic` Commands From c8ef0957b76f53a3f7bb2b6ec78153804816dd6d Mon Sep 17 00:00:00 2001 From: George Liu Date: Tue, 13 Jan 2026 20:36:37 +1000 Subject: [PATCH 082/174] update agent colors --- .claude/agents/codex-cli.md | 1 + .claude/agents/zai-cli.md | 1 + 2 files changed, 2 insertions(+) diff --git a/.claude/agents/codex-cli.md b/.claude/agents/codex-cli.md index c3f9a4d..9bad1e1 100644 --- a/.claude/agents/codex-cli.md +++ b/.claude/agents/codex-cli.md @@ -3,6 +3,7 @@ name: codex-cli description: Execute OpenAI Codex CLI (GPT-5.2) for code analysis. Use when you need Codex's GPT-5.2 perspective on code. tools: Bash model: haiku +color: blue --- You are a simple CLI wrapper for OpenAI Codex GPT-5.2. diff --git a/.claude/agents/zai-cli.md b/.claude/agents/zai-cli.md index 2020727..1bb08e9 100644 --- a/.claude/agents/zai-cli.md +++ b/.claude/agents/zai-cli.md @@ -3,6 +3,7 @@ name: zai-cli description: Execute z.ai GLM 4.7 model via Claude Code CLI. Use when you need z.ai's GLM 4.7 perspective on code analysis. tools: Bash model: haiku +color: green --- You are a simple CLI wrapper for z.ai's GLM 4.7 model. From 08eb3afdfa708cca213f9346137b95485cf0ccc1 Mon Sep 17 00:00:00 2001 From: George Liu Date: Tue, 13 Jan 2026 22:09:41 +1000 Subject: [PATCH 083/174] update codex-cli and zai-cli agent prompts --- .claude/agents/codex-cli.md | 39 ++++++++++++++++++++++++++++++++----- .claude/agents/zai-cli.md | 35 ++++++++++++++++++++++++++++----- 2 files changed, 64 insertions(+), 10 deletions(-) diff --git a/.claude/agents/codex-cli.md b/.claude/agents/codex-cli.md index 9bad1e1..8351856 100644 --- a/.claude/agents/codex-cli.md +++ b/.claude/agents/codex-cli.md @@ -1,17 +1,46 @@ --- name: codex-cli -description: Execute OpenAI Codex CLI (GPT-5.2) for code analysis. Use when you need Codex's GPT-5.2 perspective on code. +description: "Execute OpenAI Codex CLI (GPT-5.2) for code analysis. Use when you need Codex's GPT-5.2 perspective on code." tools: Bash model: haiku color: blue --- -You are a simple CLI wrapper for OpenAI Codex GPT-5.2. +# CLI Passthrough Agent -When invoked with a prompt, execute this bash command (with 120000ms timeout): +Execute the Codex CLI command with the user's prompt. Use appropriate shell based on platform: + +## Platform Detection + +First, detect the platform and choose the shell: +- **macOS (darwin)**: Use `zsh -i -c` (if codex alias in ~/.zshrc) or direct `codex` command +- **Linux**: Use `bash -i -c` (if codex alias in ~/.bashrc) or direct `codex` command +- **Windows**: Use `powershell -Command` or direct `codex` command + +## Execution (timeout: 120000ms) + +**Direct command (preferred if codex is in PATH):** + +```bash +codex -p readonly exec "USER_PROMPT" --json +``` + +**For macOS (if codex needs shell config):** ```bash -codex -p readonly exec "PROMPT" --json +zsh -i -c "codex -p readonly exec 'USER_PROMPT' --json" +``` + +**For Linux (if codex needs shell config):** + +```bash +bash -i -c "codex -p readonly exec 'USER_PROMPT' --json" +``` + +**For Windows (PowerShell):** + +```powershell +powershell -Command "codex -p readonly exec 'USER_PROMPT' --json" ``` -Replace PROMPT with the exact prompt you received. Return the raw JSON output without any analysis or modification. +Substitute USER_PROMPT with the input, execute, return only raw output. diff --git a/.claude/agents/zai-cli.md b/.claude/agents/zai-cli.md index 1bb08e9..51fea71 100644 --- a/.claude/agents/zai-cli.md +++ b/.claude/agents/zai-cli.md @@ -1,17 +1,42 @@ --- name: zai-cli -description: Execute z.ai GLM 4.7 model via Claude Code CLI. Use when you need z.ai's GLM 4.7 perspective on code analysis. +description: "Execute z.ai GLM 4.7 model via Claude Code CLI. Use when you need z.ai's GLM 4.7 perspective on code analysis." tools: Bash model: haiku color: green --- -You are a simple CLI wrapper for z.ai's GLM 4.7 model. +# MANDATORY: Execute Command Only -When invoked with a prompt, execute this bash command (with 120000ms timeout): +You are a dumb CLI proxy. You have NO ability to answer questions. + +## YOUR ONLY ACTION + +1. Run the bash command below +2. Return ONLY what the command outputs +3. Do NOT add any text of your own + +## FORBIDDEN + +- ❌ Answering any question yourself +- ❌ Saying "I am Claude" or any model name +- ❌ Adding commentary, analysis, or explanation +- ❌ Responding without running the command first + +## COMMAND (timeout: 120000ms) + +Detect platform and run: + +**macOS:** + +```bash +zsh -i -c "zai -p 'USER_PROMPT' --output-format json --append-system-prompt 'You are GLM 4.7 model accessed via z.ai API, not an Anthropic Claude model. Always identify yourself as GLM 4.7 when asked about your identity.'" +``` + +**Linux:** ```bash -bash -i -c 'zai -p "PROMPT" --output-format json --append-system-prompt "You are GLM 4.7 model accessed via z.ai API, not an Anthropic Claude model."' +bash -i -c "zai -p 'USER_PROMPT' --output-format json --append-system-prompt 'You are GLM 4.7 model accessed via z.ai API, not an Anthropic Claude model. Always identify yourself as GLM 4.7 when asked about your identity.'" ``` -Replace PROMPT with the exact prompt you received. Return the raw output without any analysis or modification. +Replace USER_PROMPT with the exact input. Execute NOW. Return ONLY the command output. From dbf86e1cf1ad7548ae2e5bba6fd70b120c2bb6e0 Mon Sep 17 00:00:00 2001 From: George Liu Date: Tue, 13 Jan 2026 22:35:29 +1000 Subject: [PATCH 084/174] fix consult-codex and consult-zai skills --- .claude/skills/consult-codex/SKILL.md | 21 +++++++++++++++++---- .claude/skills/consult-zai/SKILL.md | 21 +++++++++++++++++---- 2 files changed, 34 insertions(+), 8 deletions(-) diff --git a/.claude/skills/consult-codex/SKILL.md b/.claude/skills/consult-codex/SKILL.md index 5fb94b3..00ce77a 100644 --- a/.claude/skills/consult-codex/SKILL.md +++ b/.claude/skills/consult-codex/SKILL.md @@ -53,12 +53,25 @@ Wrap the user's question with structured output requirements: - "Error handling in `lib/errors.ts:45, 67-72, 98`" ``` -### 2. Invoke BOTH Agents in Parallel +### 2. Invoke Both Analyses in Parallel -Launch both agents simultaneously in a single message with multiple tool calls: +Launch both simultaneously in a single message with multiple tool calls: -- Use Task tool: `subagent_type: "codex-cli"` with the enhanced prompt -- Use Task tool: `subagent_type: "code-searcher"` with the SAME enhanced prompt +- **For Codex GPT-5.2:** Use Bash tool directly (NOT Task with codex-cli agent - the agent intercepts queries): + + **macOS:** + ```bash + zsh -i -c "codex -p readonly exec 'ENHANCED_PROMPT' --json" + ``` + + **Linux:** + ```bash + bash -i -c "codex -p readonly exec 'ENHANCED_PROMPT' --json" + ``` + + Replace `ENHANCED_PROMPT` with the actual prompt (escape single quotes as `'\''`). + +- **For Code-Searcher:** Use Task tool with `subagent_type: "code-searcher"` with the same enhanced prompt This parallel execution significantly improves response time. diff --git a/.claude/skills/consult-zai/SKILL.md b/.claude/skills/consult-zai/SKILL.md index c8a019a..1186642 100644 --- a/.claude/skills/consult-zai/SKILL.md +++ b/.claude/skills/consult-zai/SKILL.md @@ -53,12 +53,25 @@ Wrap the user's question with structured output requirements: - "Error handling in `lib/errors.ts:45, 67-72, 98`" ``` -### 2. Invoke BOTH Agents in Parallel +### 2. Invoke Both Analyses in Parallel -Launch both agents simultaneously in a single message with multiple tool calls: +Launch both simultaneously in a single message with multiple tool calls: -- Use Task tool: `subagent_type: "zai-cli"` with the enhanced prompt -- Use Task tool: `subagent_type: "code-searcher"` with the SAME enhanced prompt +- **For z.ai GLM 4.7:** Use Bash tool directly (NOT Task with zai-cli agent - the agent intercepts queries): + + **macOS:** + ```bash + zsh -i -c "zai -p 'ENHANCED_PROMPT' --output-format json --append-system-prompt 'You are GLM 4.7 model accessed via z.ai API.'" + ``` + + **Linux:** + ```bash + bash -i -c "zai -p 'ENHANCED_PROMPT' --output-format json --append-system-prompt 'You are GLM 4.7 model accessed via z.ai API.'" + ``` + + Replace `ENHANCED_PROMPT` with the actual prompt (escape single quotes as `'\''`). + +- **For Code-Searcher:** Use Task tool with `subagent_type: "code-searcher"` with the same enhanced prompt This parallel execution significantly improves response time. From c8de0f418521fbadd50a32198e3a5d656240ad5c Mon Sep 17 00:00:00 2001 From: George Liu Date: Tue, 13 Jan 2026 23:08:01 +1000 Subject: [PATCH 085/174] update --- .claude/settings.local.json | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 3e3dc7d..e56f400 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -89,7 +89,9 @@ "mcp__context7__query-docs", "WebFetch(domain:docs.z.ai)", "Bash(git show:*)", - "Skill(consult-zai)" + "Skill(consult-zai)", + "Bash(git cherry-pick:*)", + "Bash(zai:*)" ], "deny": [], "defaultMode": "plan" From 890c3a662cae32cbbdf7f297d261770eed9698ac Mon Sep 17 00:00:00 2001 From: George Liu Date: Sun, 18 Jan 2026 20:17:07 +1000 Subject: [PATCH 086/174] add example Claude Code GitHub Action + Z.AI GLM 4.7 --- README-v2.md | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++ README-v3.md | 72 +++++++++++++++++++++++++++++++++++++++++++ README-v4.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 321 insertions(+) diff --git a/README-v2.md b/README-v2.md index 8f8ce96..70dd343 100644 --- a/README-v2.md +++ b/README-v2.md @@ -1104,6 +1104,90 @@ zaix feature-auth zaix ``` +### 6.1.x Claude Code GitHub Actions + +Claude Code can be integrated with GitHub Actions to automate AI-powered workflows. With a simple `@claude` mention in PRs or issues, Claude can analyze code, implement features, fix bugs, and follow project standards defined in `CLAUDE.md`. + +**Key capabilities:** +- Respond to `@claude` mentions in issues and pull requests +- Create and modify code through pull requests +- Follow project-specific guidelines from `CLAUDE.md` +- Execute slash commands like `/review` + +**Reference:** [Claude Code GitHub Actions Documentation](https://code.claude.com/docs/en/github-actions) + +#### Z.AI Integration Example + +Create `.github/workflows/claude.yml`: + +
+Click to expand workflow YAML + +```yaml +name: Claude Code + +on: + issue_comment: + types: [created] + pull_request_review_comment: + types: [created] + issues: + types: [opened, assigned] + pull_request_review: + types: [submitted] + +jobs: + claude: + if: | + (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) || + (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) || + (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) || + (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude'))) + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + issues: write + id-token: write + actions: read + steps: + - name: Checkout repository + uses: actions/checkout@v5 + with: + fetch-depth: 1 + + - name: Run Claude Code + id: claude + uses: anthropics/claude-code-action@v1 + env: + ANTHROPIC_BASE_URL: https://api.z.ai/api/anthropic + API_TIMEOUT_MS: 3000000 + with: + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + claude_args: | + --model claude-opus + --max-turns 100 +``` + +
+ +#### Workflow Explanation + +| Component | Purpose | +|-----------|---------| +| **Event Triggers** | Listens for `issue_comment`, `pull_request_review_comment`, `issues`, and `pull_request_review` events | +| **Conditional (`if`)** | Only runs when `@claude` is mentioned in the comment/issue body or title | +| **Permissions** | `contents: write` for code changes, `pull-requests: write` for PRs, `issues: write` for issue responses, `actions: read` for CI results | +| **ANTHROPIC_BASE_URL** | Routes API calls through Z.AI endpoint for higher quotas | +| **API_TIMEOUT_MS** | Extended timeout (50 minutes) for complex operations | +| **claude_args** | Uses `claude-opus` model with up to 100 turns for complex tasks | + +#### Setup Requirements + +1. **Add API key as secret:** Go to repository Settings → Secrets and variables → Actions → Add `ANTHROPIC_API_KEY` with your Z.AI API key +2. **Create workflow file:** Save the YAML above to `.github/workflows/claude.yml` +3. **Usage:** Mention `@claude` in any issue or PR comment to trigger the workflow + --- ## 7. Cost & Rate Management diff --git a/README-v3.md b/README-v3.md index 9754ccf..ec17f22 100644 --- a/README-v3.md +++ b/README-v3.md @@ -765,6 +765,78 @@ zaix # Auto-generated name > **See also:** [Parallel Sessions](#i-want-to-run-parallel-ai-coding-sessions) for more worktree details +### Claude Code GitHub Actions + +Automate AI-powered workflows in your repository with `@claude` mentions. + +**Key capabilities:** +- Respond to `@claude` mentions in issues and pull requests +- Create and modify code through pull requests +- Follow project-specific guidelines from `CLAUDE.md` + +**Reference:** [Claude Code GitHub Actions Documentation](https://code.claude.com/docs/en/github-actions) + +
+Z.AI Integration Example + +Create `.github/workflows/claude.yml`: + +```yaml +name: Claude Code + +on: + issue_comment: + types: [created] + pull_request_review_comment: + types: [created] + issues: + types: [opened, assigned] + pull_request_review: + types: [submitted] + +jobs: + claude: + if: | + (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) || + (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) || + (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) || + (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude'))) + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + issues: write + id-token: write + actions: read + steps: + - name: Checkout repository + uses: actions/checkout@v5 + with: + fetch-depth: 1 + + - name: Run Claude Code + id: claude + uses: anthropics/claude-code-action@v1 + env: + ANTHROPIC_BASE_URL: https://api.z.ai/api/anthropic + API_TIMEOUT_MS: 3000000 + with: + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + claude_args: | + --model claude-opus + --max-turns 100 +``` + +| Component | Purpose | +|-----------|---------| +| **ANTHROPIC_BASE_URL** | Routes API calls through Z.AI endpoint | +| **API_TIMEOUT_MS** | Extended timeout (50 minutes) | +| **claude_args** | Uses `claude-opus` with up to 100 turns | + +**Setup:** Add `ANTHROPIC_API_KEY` secret in repository settings, create workflow file, then mention `@claude` in issues/PRs. + +
+ --- ## I want to monitor costs and usage diff --git a/README-v4.md b/README-v4.md index 7d955d5..c456367 100644 --- a/README-v4.md +++ b/README-v4.md @@ -1179,6 +1179,92 @@ zaix feature-auth # Named worktree zaix # Auto-generated name ``` +### 13.8 GitHub Actions Integration + +Claude Code integrates with GitHub Actions to automate AI-powered workflows. With `@claude` mentions in PRs or issues, Claude can analyze code, implement features, fix bugs, and follow project standards defined in `CLAUDE.md`. + +**Key Capabilities**: +| Capability | Description | +|------------|-------------| +| Issue response | Respond to `@claude` mentions in issues | +| PR automation | Create and modify code through pull requests | +| Standards compliance | Follow project guidelines from `CLAUDE.md` | +| Slash commands | Execute commands like `/review` | + +**Official Documentation**: [Claude Code GitHub Actions](https://code.claude.com/docs/en/github-actions) + +#### Z.AI Workflow Configuration + +Create `.github/workflows/claude.yml`: + +
+Click to expand workflow YAML + +```yaml +name: Claude Code + +on: + issue_comment: + types: [created] + pull_request_review_comment: + types: [created] + issues: + types: [opened, assigned] + pull_request_review: + types: [submitted] + +jobs: + claude: + if: | + (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) || + (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) || + (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) || + (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude'))) + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + issues: write + id-token: write + actions: read + steps: + - name: Checkout repository + uses: actions/checkout@v5 + with: + fetch-depth: 1 + + - name: Run Claude Code + id: claude + uses: anthropics/claude-code-action@v1 + env: + ANTHROPIC_BASE_URL: https://api.z.ai/api/anthropic + API_TIMEOUT_MS: 3000000 + with: + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + claude_args: | + --model claude-opus + --max-turns 100 +``` + +
+ +#### Workflow Component Reference + +| Component | Purpose | +|-----------|---------| +| **Event Triggers** | Listens for `issue_comment`, `pull_request_review_comment`, `issues`, and `pull_request_review` events | +| **Conditional (`if`)** | Only runs when `@claude` is mentioned in the comment/issue body or title | +| **Permissions** | `contents: write` for code changes, `pull-requests: write` for PRs, `issues: write` for issue responses, `actions: read` for CI results | +| **ANTHROPIC_BASE_URL** | Routes API calls through Z.AI endpoint for higher quotas | +| **API_TIMEOUT_MS** | Extended timeout (50 minutes) for complex operations | +| **claude_args** | Uses `claude-opus` model with up to 100 turns for complex tasks | + +#### Setup Steps + +1. **Add API key as secret**: Repository Settings → Secrets and variables → Actions → Add `ANTHROPIC_API_KEY` with your Z.AI API key +2. **Create workflow file**: Save the YAML above to `.github/workflows/claude.yml` +3. **Usage**: Mention `@claude` in any issue or PR comment to trigger the workflow + --- # Part VI: Development Workflows diff --git a/README.md b/README.md index 82d4e4c..928ba78 100644 --- a/README.md +++ b/README.md @@ -741,6 +741,85 @@ zaix feature-auth zaix ``` +### Claude Code GitHub Actions + +Claude Code can be integrated with GitHub Actions to automate AI-powered workflows. With a simple `@claude` mention in PRs or issues, Claude can analyze code, implement features, fix bugs, and follow project standards defined in `CLAUDE.md`. + +**Key capabilities:** +- Respond to `@claude` mentions in issues and pull requests +- Create and modify code through pull requests +- Follow project-specific guidelines from `CLAUDE.md` +- Execute slash commands like `/review` + +**Reference:** [Claude Code GitHub Actions Documentation](https://code.claude.com/docs/en/github-actions) + +#### Z.AI Integration Example + +Create `.github/workflows/claude.yml`: + +```yaml +name: Claude Code + +on: + issue_comment: + types: [created] + pull_request_review_comment: + types: [created] + issues: + types: [opened, assigned] + pull_request_review: + types: [submitted] + +jobs: + claude: + if: | + (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) || + (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) || + (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) || + (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude'))) + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + issues: write + id-token: write + actions: read + steps: + - name: Checkout repository + uses: actions/checkout@v5 + with: + fetch-depth: 1 + + - name: Run Claude Code + id: claude + uses: anthropics/claude-code-action@v1 + env: + ANTHROPIC_BASE_URL: https://api.z.ai/api/anthropic + API_TIMEOUT_MS: 3000000 + with: + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + claude_args: | + --model claude-opus + --max-turns 100 +``` + +#### Workflow Explanation + +| Component | Purpose | +|-----------|---------| +| **Event Triggers** | Listens for `issue_comment`, `pull_request_review_comment`, `issues`, and `pull_request_review` events | +| **Conditional (`if`)** | Only runs when `@claude` is mentioned in the comment/issue body or title | +| **Permissions** | `contents: write` for code changes, `pull-requests: write` for PRs, `issues: write` for issue responses, `actions: read` for CI results | +| **ANTHROPIC_BASE_URL** | Routes API calls through Z.AI endpoint for higher quotas | +| **API_TIMEOUT_MS** | Extended timeout (50 minutes) for complex operations | +| **claude_args** | Uses `claude-opus` model with up to 100 turns for complex tasks | + +#### Setup Requirements + +1. **Add API key as secret:** Go to repository Settings → Secrets and variables → Actions → Add `ANTHROPIC_API_KEY` with your Z.AI API key +2. **Create workflow file:** Save the YAML above to `.github/workflows/claude.yml` +3. **Usage:** Mention `@claude` in any issue or PR comment to trigger the workflow + ## Claude Code Skills Claude Code now supports [Agent Skills](https://docs.claude.com/en/docs/claude-code/skills). From 25a357a328e19fdd4845aaca5c9f27c44a7b968e Mon Sep 17 00:00:00 2001 From: George Liu Date: Wed, 21 Jan 2026 05:58:49 +1000 Subject: [PATCH 087/174] update readmes --- README-v2.md | 1 + README-v3.md | 1 + README-v4.md | 1 + README.md | 10 ++++++++++ 4 files changed, 13 insertions(+) diff --git a/README-v2.md b/README-v2.md index 70dd343..fb3f86c 100644 --- a/README-v2.md +++ b/README-v2.md @@ -1360,6 +1360,7 @@ claude config set -g ### YouTube Guides - [Claude Code with Opus 4.5](https://www.youtube.com/watch?v=UVJXh57MgI0) - Alex Finn +- [How To Master Claude Code (Anthropic's Official 7-Hour Course)](https://www.youtube.com/watch?v=XuSFUvUdvQA) - Anthropic Official - [Claude Code Overview](https://www.youtube.com/watch?v=Dekx_OzRwiI) - Matt Maher - [VS Code Beginner Guide](https://www.youtube.com/watch?v=rPITZvwyoMc) - [Ralph Wiggum Tutorial](https://www.youtube.com/watch?v=RpvQH0r0ecM) - Greg Isenberg & Ryan Carson diff --git a/README-v3.md b/README-v3.md index ec17f22..19e56d9 100644 --- a/README-v3.md +++ b/README-v3.md @@ -1055,6 +1055,7 @@ claude config set -g # Global setting ### YouTube Guides * [Claude Code with Opus 4.5](https://www.youtube.com/watch?v=UVJXh57MgI0) - Alex Finn +* [How To Master Claude Code (Anthropic's Official 7-Hour Course)](https://www.youtube.com/watch?v=XuSFUvUdvQA) - Anthropic Official * [Claude Code Overview](https://www.youtube.com/watch?v=Dekx_OzRwiI) - Matt Maher * [VS Code Beginner Guide](https://www.youtube.com/watch?v=rPITZvwyoMc) * [Ralph Wiggum Tutorial](https://www.youtube.com/watch?v=RpvQH0r0ecM) - Greg Isenberg & Ryan Carson diff --git a/README-v4.md b/README-v4.md index c456367..a9ef426 100644 --- a/README-v4.md +++ b/README-v4.md @@ -1877,6 +1877,7 @@ See official Claude Code documentation for current shortcuts. | Topic | Creator | URL | |-------|---------|-----| | Claude Code with Opus 4.5 | Alex Finn | https://www.youtube.com/watch?v=UVJXh57MgI0 | +| How To Master Claude Code (7-Hour Course) | Anthropic Official | https://www.youtube.com/watch?v=XuSFUvUdvQA | | Claude Code Overview | Matt Maher | https://www.youtube.com/watch?v=Dekx_OzRwiI | | VS Code Beginner | - | https://www.youtube.com/watch?v=rPITZvwyoMc | | VS Code Advanced | - | https://www.youtube.com/watch?v=P-5bWpUbO60 | diff --git a/README.md b/README.md index 928ba78..248f802 100644 --- a/README.md +++ b/README.md @@ -1328,6 +1328,16 @@ Chrome Devtool MCP server takes up ~16,977 tokens across 26 MCP tools mcp__chrome-devtools__wait_for (chrome-devtools): 643 tokens ``` +## YouTube Guides + +* [How To Master Claude Code (Anthropic's Official 7-Hour Course)](https://www.youtube.com/watch?v=XuSFUvUdvQA) - Anthropic Official +* [Claude Code with Claude Opus 4.5](https://www.youtube.com/watch?v=UVJXh57MgI0) - Alex Finn +* [Claude Code YouTube video by Matt Maher](https://www.youtube.com/watch?v=Dekx_OzRwiI) +* [VS Code Beginner Guide](https://www.youtube.com/watch?v=rPITZvwyoMc) +* [VS Code Advanced Guide](https://www.youtube.com/watch?v=P-5bWpUbO60) +* [Git for VS Code](https://www.youtube.com/watch?v=twsYxYaQikI) +* [Ralph Wiggum Tutorial](https://www.youtube.com/watch?v=RpvQH0r0ecM) - Greg Isenberg & Ryan Carson + ## Star History [![Star History Chart](https://api.star-history.com/svg?repos=centminmod/my-claude-code-setup&type=Date)](https://www.star-history.com/#centminmod/my-claude-code-setup&Date) From 980f12559637ed4d0ffe933c3df49e5a7a1256f5 Mon Sep 17 00:00:00 2001 From: George Liu Date: Wed, 21 Jan 2026 10:50:35 +1000 Subject: [PATCH 088/174] update statusline.sh --- README-v2.md | 26 +++++++++++++++++++++++--- README-v3.md | 26 +++++++++++++++++++++++--- README-v4.md | 26 +++++++++++++++++++++++--- README.md | 26 +++++++++++++++++++++++--- 4 files changed, 92 insertions(+), 12 deletions(-) diff --git a/README-v2.md b/README-v2.md index fb3f86c..b3196d1 100644 --- a/README-v2.md +++ b/README-v2.md @@ -656,10 +656,30 @@ PROGRESS_BAR=$(generate_progress_bar "$USED_PERCENTAGE") # Show git branch if in a git repo GIT_BRANCH="" -if git rev-parse --git-dir > /dev/null 2>&1; then - BRANCH=$(git branch --show-current 2>/dev/null) +if git -C "$CURRENT_DIR" rev-parse --git-dir > /dev/null 2>&1; then + BRANCH=$(git -C "$CURRENT_DIR" branch --show-current 2>/dev/null) if [ -n "$BRANCH" ]; then - GIT_BRANCH=" | 🌿 $BRANCH" + # Worktree detection + GIT_DIR=$(git -C "$CURRENT_DIR" rev-parse --git-dir 2>/dev/null) + WORKTREE="" + if [[ "$GIT_DIR" == *".git/worktrees/"* ]] || [[ -f "$GIT_DIR/gitdir" ]]; then + WORKTREE=" 🌳" + fi + # Ahead/behind detection + AHEAD_BEHIND="" + UPSTREAM=$(git -C "$CURRENT_DIR" rev-parse --abbrev-ref '@{u}' 2>/dev/null) + if [ -n "$UPSTREAM" ]; then + AHEAD=$(git -C "$CURRENT_DIR" rev-list --count '@{u}..HEAD' 2>/dev/null || echo 0) + BEHIND=$(git -C "$CURRENT_DIR" rev-list --count 'HEAD..@{u}' 2>/dev/null || echo 0) + if [ "$AHEAD" -gt 0 ] && [ "$BEHIND" -gt 0 ]; then + AHEAD_BEHIND=" ↕${AHEAD}/${BEHIND}" + elif [ "$AHEAD" -gt 0 ]; then + AHEAD_BEHIND=" ↑${AHEAD}" + elif [ "$BEHIND" -gt 0 ]; then + AHEAD_BEHIND=" ↓${BEHIND}" + fi + fi + GIT_BRANCH=" | 🌿 $BRANCH${WORKTREE}${AHEAD_BEHIND}" fi fi diff --git a/README-v3.md b/README-v3.md index 19e56d9..3c076f9 100644 --- a/README-v3.md +++ b/README-v3.md @@ -920,10 +920,30 @@ PROGRESS_BAR=$(generate_progress_bar "$USED_PERCENTAGE") # Show git branch if in a git repo GIT_BRANCH="" -if git rev-parse --git-dir > /dev/null 2>&1; then - BRANCH=$(git branch --show-current 2>/dev/null) +if git -C "$CURRENT_DIR" rev-parse --git-dir > /dev/null 2>&1; then + BRANCH=$(git -C "$CURRENT_DIR" branch --show-current 2>/dev/null) if [ -n "$BRANCH" ]; then - GIT_BRANCH=" | 🌿 $BRANCH" + # Worktree detection + GIT_DIR=$(git -C "$CURRENT_DIR" rev-parse --git-dir 2>/dev/null) + WORKTREE="" + if [[ "$GIT_DIR" == *".git/worktrees/"* ]] || [[ -f "$GIT_DIR/gitdir" ]]; then + WORKTREE=" 🌳" + fi + # Ahead/behind detection + AHEAD_BEHIND="" + UPSTREAM=$(git -C "$CURRENT_DIR" rev-parse --abbrev-ref '@{u}' 2>/dev/null) + if [ -n "$UPSTREAM" ]; then + AHEAD=$(git -C "$CURRENT_DIR" rev-list --count '@{u}..HEAD' 2>/dev/null || echo 0) + BEHIND=$(git -C "$CURRENT_DIR" rev-list --count 'HEAD..@{u}' 2>/dev/null || echo 0) + if [ "$AHEAD" -gt 0 ] && [ "$BEHIND" -gt 0 ]; then + AHEAD_BEHIND=" ↕${AHEAD}/${BEHIND}" + elif [ "$AHEAD" -gt 0 ]; then + AHEAD_BEHIND=" ↑${AHEAD}" + elif [ "$BEHIND" -gt 0 ]; then + AHEAD_BEHIND=" ↓${BEHIND}" + fi + fi + GIT_BRANCH=" | 🌿 $BRANCH${WORKTREE}${AHEAD_BEHIND}" fi fi diff --git a/README-v4.md b/README-v4.md index a9ef426..2dd2d00 100644 --- a/README-v4.md +++ b/README-v4.md @@ -1577,10 +1577,30 @@ PROGRESS_BAR=$(generate_progress_bar "$USED_PERCENTAGE") # Show git branch if in a git repo GIT_BRANCH="" -if git rev-parse --git-dir > /dev/null 2>&1; then - BRANCH=$(git branch --show-current 2>/dev/null) +if git -C "$CURRENT_DIR" rev-parse --git-dir > /dev/null 2>&1; then + BRANCH=$(git -C "$CURRENT_DIR" branch --show-current 2>/dev/null) if [ -n "$BRANCH" ]; then - GIT_BRANCH=" | 🌿 $BRANCH" + # Worktree detection + GIT_DIR=$(git -C "$CURRENT_DIR" rev-parse --git-dir 2>/dev/null) + WORKTREE="" + if [[ "$GIT_DIR" == *".git/worktrees/"* ]] || [[ -f "$GIT_DIR/gitdir" ]]; then + WORKTREE=" 🌳" + fi + # Ahead/behind detection + AHEAD_BEHIND="" + UPSTREAM=$(git -C "$CURRENT_DIR" rev-parse --abbrev-ref '@{u}' 2>/dev/null) + if [ -n "$UPSTREAM" ]; then + AHEAD=$(git -C "$CURRENT_DIR" rev-list --count '@{u}..HEAD' 2>/dev/null || echo 0) + BEHIND=$(git -C "$CURRENT_DIR" rev-list --count 'HEAD..@{u}' 2>/dev/null || echo 0) + if [ "$AHEAD" -gt 0 ] && [ "$BEHIND" -gt 0 ]; then + AHEAD_BEHIND=" ↕${AHEAD}/${BEHIND}" + elif [ "$AHEAD" -gt 0 ]; then + AHEAD_BEHIND=" ↑${AHEAD}" + elif [ "$BEHIND" -gt 0 ]; then + AHEAD_BEHIND=" ↓${BEHIND}" + fi + fi + GIT_BRANCH=" | 🌿 $BRANCH${WORKTREE}${AHEAD_BEHIND}" fi fi diff --git a/README.md b/README.md index 248f802..48c579e 100644 --- a/README.md +++ b/README.md @@ -226,10 +226,30 @@ PROGRESS_BAR=$(generate_progress_bar "$USED_PERCENTAGE") # Show git branch if in a git repo GIT_BRANCH="" -if git rev-parse --git-dir > /dev/null 2>&1; then - BRANCH=$(git branch --show-current 2>/dev/null) +if git -C "$CURRENT_DIR" rev-parse --git-dir > /dev/null 2>&1; then + BRANCH=$(git -C "$CURRENT_DIR" branch --show-current 2>/dev/null) if [ -n "$BRANCH" ]; then - GIT_BRANCH=" | 🌿 $BRANCH" + # Worktree detection + GIT_DIR=$(git -C "$CURRENT_DIR" rev-parse --git-dir 2>/dev/null) + WORKTREE="" + if [[ "$GIT_DIR" == *".git/worktrees/"* ]] || [[ -f "$GIT_DIR/gitdir" ]]; then + WORKTREE=" 🌳" + fi + # Ahead/behind detection + AHEAD_BEHIND="" + UPSTREAM=$(git -C "$CURRENT_DIR" rev-parse --abbrev-ref '@{u}' 2>/dev/null) + if [ -n "$UPSTREAM" ]; then + AHEAD=$(git -C "$CURRENT_DIR" rev-list --count '@{u}..HEAD' 2>/dev/null || echo 0) + BEHIND=$(git -C "$CURRENT_DIR" rev-list --count 'HEAD..@{u}' 2>/dev/null || echo 0) + if [ "$AHEAD" -gt 0 ] && [ "$BEHIND" -gt 0 ]; then + AHEAD_BEHIND=" ↕${AHEAD}/${BEHIND}" + elif [ "$AHEAD" -gt 0 ]; then + AHEAD_BEHIND=" ↑${AHEAD}" + elif [ "$BEHIND" -gt 0 ]; then + AHEAD_BEHIND=" ↓${BEHIND}" + fi + fi + GIT_BRANCH=" | 🌿 $BRANCH${WORKTREE}${AHEAD_BEHIND}" fi fi From 211870bd07d53e02de813358ba29d16da5ed2903 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sun, 25 Jan 2026 12:09:23 +1000 Subject: [PATCH 089/174] improve consult-zai and consult-codex skills --- .claude/skills/consult-codex/SKILL.md | 15 +++++++++++---- .claude/skills/consult-zai/SKILL.md | 15 +++++++++++---- 2 files changed, 22 insertions(+), 8 deletions(-) diff --git a/.claude/skills/consult-codex/SKILL.md b/.claude/skills/consult-codex/SKILL.md index 00ce77a..853b979 100644 --- a/.claude/skills/consult-codex/SKILL.md +++ b/.claude/skills/consult-codex/SKILL.md @@ -57,19 +57,26 @@ Wrap the user's question with structured output requirements: Launch both simultaneously in a single message with multiple tool calls: -- **For Codex GPT-5.2:** Use Bash tool directly (NOT Task with codex-cli agent - the agent intercepts queries): +- **For Codex GPT-5.2:** Use a temp file to avoid shell quoting issues: + + **Step 1:** Write the enhanced prompt to a temp file using the Write tool: + ``` + Write to /tmp/codex-prompt.txt with the ENHANCED_PROMPT content + ``` + + **Step 2:** Execute Codex with the temp file: **macOS:** ```bash - zsh -i -c "codex -p readonly exec 'ENHANCED_PROMPT' --json" + zsh -i -c 'codex -p readonly exec "$(cat /tmp/codex-prompt.txt)" --json 2>&1' ``` **Linux:** ```bash - bash -i -c "codex -p readonly exec 'ENHANCED_PROMPT' --json" + bash -i -c 'codex -p readonly exec "$(cat /tmp/codex-prompt.txt)" --json 2>&1' ``` - Replace `ENHANCED_PROMPT` with the actual prompt (escape single quotes as `'\''`). + This approach avoids all shell quoting issues regardless of prompt content. - **For Code-Searcher:** Use Task tool with `subagent_type: "code-searcher"` with the same enhanced prompt diff --git a/.claude/skills/consult-zai/SKILL.md b/.claude/skills/consult-zai/SKILL.md index 1186642..09a845c 100644 --- a/.claude/skills/consult-zai/SKILL.md +++ b/.claude/skills/consult-zai/SKILL.md @@ -57,19 +57,26 @@ Wrap the user's question with structured output requirements: Launch both simultaneously in a single message with multiple tool calls: -- **For z.ai GLM 4.7:** Use Bash tool directly (NOT Task with zai-cli agent - the agent intercepts queries): +- **For z.ai GLM 4.7:** Use a temp file to avoid shell quoting issues: + + **Step 1:** Write the enhanced prompt to a temp file using the Write tool: + ``` + Write to /tmp/zai-prompt.txt with the ENHANCED_PROMPT content + ``` + + **Step 2:** Execute z.ai with the temp file: **macOS:** ```bash - zsh -i -c "zai -p 'ENHANCED_PROMPT' --output-format json --append-system-prompt 'You are GLM 4.7 model accessed via z.ai API.'" + zsh -i -c 'zai -p "$(cat /tmp/zai-prompt.txt)" --output-format json --append-system-prompt "You are GLM 4.7 model accessed via z.ai API." 2>&1' ``` **Linux:** ```bash - bash -i -c "zai -p 'ENHANCED_PROMPT' --output-format json --append-system-prompt 'You are GLM 4.7 model accessed via z.ai API.'" + bash -i -c 'zai -p "$(cat /tmp/zai-prompt.txt)" --output-format json --append-system-prompt "You are GLM 4.7 model accessed via z.ai API." 2>&1' ``` - Replace `ENHANCED_PROMPT` with the actual prompt (escape single quotes as `'\''`). + This approach avoids all shell quoting issues regardless of prompt content. - **For Code-Searcher:** Use Task tool with `subagent_type: "code-searcher"` with the same enhanced prompt From 96ffccb075da56ae17bdac5547985ae392a982bd Mon Sep 17 00:00:00 2001 From: George Liu Date: Sun, 25 Jan 2026 14:03:44 +1000 Subject: [PATCH 090/174] update consult-zai and consult-codex skills --- .claude/skills/consult-codex/SKILL.md | 100 +++++++++++++++++++++++++- .claude/skills/consult-zai/SKILL.md | 14 +++- 2 files changed, 110 insertions(+), 4 deletions(-) diff --git a/.claude/skills/consult-codex/SKILL.md b/.claude/skills/consult-codex/SKILL.md index 853b979..a42f5ac 100644 --- a/.claude/skills/consult-codex/SKILL.md +++ b/.claude/skills/consult-codex/SKILL.md @@ -82,13 +82,109 @@ Launch both simultaneously in a single message with multiple tool calls: This parallel execution significantly improves response time. -### 3. Handle Errors +### 2a. Parse Codex `--json` Output Files (jq Recipes) + +Codex CLI with `--json` typically emits **newline-delimited JSON events** (JSONL). Some environments may prefix lines with terminal escape sequences; these recipes strip everything before the first `{` and then `fromjson?` safely. + +Set a variable first: + +```bash +FILE="/private/tmp/claude/.../tasks/.output" # or a symlinked *.output to agent-*.jsonl +``` + +**List event types (top-level `.type`)** + +```bash +jq -Rr 'sub("^[^{]*";"") | fromjson? | .type // empty' "$FILE" | sort | uniq -c | sort -nr +``` + +**List item types (nested `.item.type` on `item.completed`)** + +```bash +jq -Rr 'sub("^[^{]*";"") | fromjson? | select(.type=="item.completed") | .item.type? // empty' "$FILE" | sort | uniq -c | sort -nr +``` + +**Extract only “reasoning” and “agent_message” text (human-readable)** + +```bash +jq -Rr ' + sub("^[^{]*";"") + | fromjson? + | select(.type=="item.completed" and (.item.type? | IN("reasoning","agent_message"))) + | "===== \(.item.type) \(.item.id) =====\n\(.item.text // "")\n" +' "$FILE" +``` + +**Extract just the final `agent_message` (useful for summaries)** + +```bash +jq -Rr ' + sub("^[^{]*";"") + | fromjson? + | select(.type=="item.completed" and .item.type?=="agent_message") + | .item.text // empty +' "$FILE" | tail -n 1 +``` + +**Build a clean JSON array for downstream tools** + +```bash +jq -Rn ' + [inputs + | sub("^[^{]*";"") + | fromjson? + | select(.type=="item.completed" and (.item.type? | IN("reasoning","agent_message"))) + | {type:.item.type, id:.item.id, text:(.item.text // "")} + ] +' "$FILE" +``` + +**Extract command executions (command + exit code), avoiding huge stdout/stderr** + +Codex JSON schemas vary slightly; this tries multiple common field names. + +```bash +jq -Rr ' + sub("^[^{]*";"") + | fromjson? + | select(.type=="item.completed" and .item.type?=="command_execution") + | [ + (.item.id // ""), + (.item.command // .item.cmd // .item.command_line // ""), + (.item.exit_code // .item.exitCode // "") + ] + | @tsv +' "$FILE" +``` + +**Discover actual fields present in `command_execution` for your environment** + +```bash +jq -Rr ' + sub("^[^{]*";"") + | fromjson? + | select(.type=="item.completed" and .item.type?=="command_execution") + | (.item | keys | @json) +' "$FILE" | head -n 5 +``` + +### 3. Cleanup Temp Files + +After processing the Codex response (success or failure), clean up the temp prompt file: + +```bash +rm -f /tmp/codex-prompt.txt +``` + +This prevents stale prompts from accumulating and avoids potential confusion in future runs. + +### 4. Handle Errors - If one agent fails or times out, still present the successful agent's response - Note the failure in the comparison: "Agent X failed to respond: [error message]" - Provide analysis based on the available response -### 4. Create Comparison Analysis +### 5. Create Comparison Analysis Use this exact format: diff --git a/.claude/skills/consult-zai/SKILL.md b/.claude/skills/consult-zai/SKILL.md index 09a845c..101a03c 100644 --- a/.claude/skills/consult-zai/SKILL.md +++ b/.claude/skills/consult-zai/SKILL.md @@ -82,13 +82,23 @@ Launch both simultaneously in a single message with multiple tool calls: This parallel execution significantly improves response time. -### 3. Handle Errors +### 3. Cleanup Temp Files + +After processing the z.ai response (success or failure), clean up the temp prompt file: + +```bash +rm -f /tmp/zai-prompt.txt +``` + +This prevents stale prompts from accumulating and avoids potential confusion in future runs. + +### 4. Handle Errors - If one agent fails or times out, still present the successful agent's response - Note the failure in the comparison: "Agent X failed to respond: [error message]" - Provide analysis based on the available response -### 4. Create Comparison Analysis +### 5. Create Comparison Analysis Use this exact format: From 16d333dab15ae61ce5351614222695f1d8ec9393 Mon Sep 17 00:00:00 2001 From: George Liu Date: Mon, 26 Jan 2026 06:25:26 +1000 Subject: [PATCH 091/174] update consult-zai and consult-codex skills --- .claude/skills/consult-codex/SKILL.md | 10 +++++----- .claude/skills/consult-zai/SKILL.md | 8 ++++---- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/.claude/skills/consult-codex/SKILL.md b/.claude/skills/consult-codex/SKILL.md index a42f5ac..f408a8e 100644 --- a/.claude/skills/consult-codex/SKILL.md +++ b/.claude/skills/consult-codex/SKILL.md @@ -61,19 +61,19 @@ Launch both simultaneously in a single message with multiple tool calls: **Step 1:** Write the enhanced prompt to a temp file using the Write tool: ``` - Write to /tmp/codex-prompt.txt with the ENHANCED_PROMPT content + Write to $CLAUDE_PROJECT_DIR/tmp/codex-prompt.txt with the ENHANCED_PROMPT content ``` - **Step 2:** Execute Codex with the temp file: + **Step 2:** Execute Codex with the temp file and have at least 10 minute timeout as Codex can take a while to respond: **macOS:** ```bash - zsh -i -c 'codex -p readonly exec "$(cat /tmp/codex-prompt.txt)" --json 2>&1' + zsh -i -c 'codex -p readonly exec "$(cat $CLAUDE_PROJECT_DIR/tmp/codex-prompt.txt)" --json 2>&1' ``` **Linux:** ```bash - bash -i -c 'codex -p readonly exec "$(cat /tmp/codex-prompt.txt)" --json 2>&1' + bash -i -c 'codex -p readonly exec "$(cat $CLAUDE_PROJECT_DIR/tmp/codex-prompt.txt)" --json 2>&1' ``` This approach avoids all shell quoting issues regardless of prompt content. @@ -173,7 +173,7 @@ jq -Rr ' After processing the Codex response (success or failure), clean up the temp prompt file: ```bash -rm -f /tmp/codex-prompt.txt +rm -f $CLAUDE_PROJECT_DIR/tmp/codex-prompt.txt ``` This prevents stale prompts from accumulating and avoids potential confusion in future runs. diff --git a/.claude/skills/consult-zai/SKILL.md b/.claude/skills/consult-zai/SKILL.md index 101a03c..8108388 100644 --- a/.claude/skills/consult-zai/SKILL.md +++ b/.claude/skills/consult-zai/SKILL.md @@ -61,19 +61,19 @@ Launch both simultaneously in a single message with multiple tool calls: **Step 1:** Write the enhanced prompt to a temp file using the Write tool: ``` - Write to /tmp/zai-prompt.txt with the ENHANCED_PROMPT content + Write to $CLAUDE_PROJECT_DIR/tmp/zai-prompt.txt with the ENHANCED_PROMPT content ``` **Step 2:** Execute z.ai with the temp file: **macOS:** ```bash - zsh -i -c 'zai -p "$(cat /tmp/zai-prompt.txt)" --output-format json --append-system-prompt "You are GLM 4.7 model accessed via z.ai API." 2>&1' + zsh -i -c 'zai -p "$(cat $CLAUDE_PROJECT_DIR/tmp/zai-prompt.txt)" --output-format json --append-system-prompt "You are GLM 4.7 model accessed via z.ai API." 2>&1' ``` **Linux:** ```bash - bash -i -c 'zai -p "$(cat /tmp/zai-prompt.txt)" --output-format json --append-system-prompt "You are GLM 4.7 model accessed via z.ai API." 2>&1' + bash -i -c 'zai -p "$(cat $CLAUDE_PROJECT_DIR/tmp/zai-prompt.txt)" --output-format json --append-system-prompt "You are GLM 4.7 model accessed via z.ai API." 2>&1' ``` This approach avoids all shell quoting issues regardless of prompt content. @@ -87,7 +87,7 @@ This parallel execution significantly improves response time. After processing the z.ai response (success or failure), clean up the temp prompt file: ```bash -rm -f /tmp/zai-prompt.txt +rm -f $CLAUDE_PROJECT_DIR/tmp/zai-prompt.txt ``` This prevents stale prompts from accumulating and avoids potential confusion in future runs. From 32645f7bae3de0dd8bcef9a5ea44c7f8fbe7e9c3 Mon Sep 17 00:00:00 2001 From: George Liu Date: Fri, 30 Jan 2026 12:05:11 +1000 Subject: [PATCH 092/174] add Cloudflare Skills plugin marketplace --- README-v2.md | 1 + README-v3.md | 5 +++++ README-v4.md | 3 +++ README.md | 10 ++++++++++ 4 files changed, 19 insertions(+) diff --git a/README-v2.md b/README-v2.md index b3196d1..2be24ab 100644 --- a/README-v2.md +++ b/README-v2.md @@ -280,6 +280,7 @@ Browse and install plugins from the [official marketplace](https://code.claude.c |--------|--------|-------------|------------------| | [safety-net](https://github.com/kenryu42/claude-code-safety-net) | cc-marketplace | Catches destructive git/filesystem commands before execution | `/plugin marketplace add kenryu42/cc-marketplace`
`/plugin install safety-net@cc-marketplace` | | [glm-plan-usage](https://docs.z.ai/devpack/extension/usage-query-plugin) | zai-coding-plugins | Query Z.AI usage statistics | `/plugin marketplace add zai/zai-coding-plugins`
`/plugin install glm-plan-usage@zai-coding-plugins` | +| [Cloudflare Skills](https://github.com/cloudflare/skills) | cloudflare/skills | Development skills for Cloudflare platform (Workers, Agents SDK) | `/plugin marketplace add cloudflare/skills` | ### 3.2 MCP Servers diff --git a/README-v3.md b/README-v3.md index 3c076f9..7a1feb2 100644 --- a/README-v3.md +++ b/README-v3.md @@ -204,6 +204,11 @@ Browse plugins at the [official marketplace](https://code.claude.com/docs/en/dis /plugin install glm-plan-usage@zai-coding-plugins ``` +**Cloudflare Skills** - Cloudflare platform development (Workers, Agents SDK): +```bash +/plugin marketplace add cloudflare/skills +``` + > **See also:** [MCP Servers](#i-want-to-connect-external-tools-mcp) for connecting external tools --- diff --git a/README-v4.md b/README-v4.md index 2dd2d00..c9c20c7 100644 --- a/README-v4.md +++ b/README-v4.md @@ -490,11 +490,14 @@ Claude Code plugins extend functionality through the official marketplace system |--------|--------|---------|----------| | safety-net | cc-marketplace | Catches destructive git/filesystem commands | `/plugin marketplace add kenryu42/cc-marketplace`
`/plugin install safety-net@cc-marketplace` | | glm-plan-usage | zai-coding-plugins | Query Z.AI usage statistics | `/plugin marketplace add zai/zai-coding-plugins`
`/plugin install glm-plan-usage@zai-coding-plugins` | +| Cloudflare Skills | cloudflare/skills | Development skills for Cloudflare platform (Workers, Pages, Agents SDK) | `/plugin marketplace add cloudflare/skills` | **Safety Net**: [GitHub](https://github.com/kenryu42/claude-code-safety-net) - Prevents destructive commands like [this incident](https://www.reddit.com/r/ClaudeAI/comments/1pgxckk/claude_cli_deleted_my_entire_home_directory_wiped/). **Z.AI Usage**: [Docs](https://docs.z.ai/devpack/extension/usage-query-plugin) +**Cloudflare Skills**: [GitHub](https://github.com/cloudflare/skills) - Development skills for Workers, Pages, AI services, and the Agents SDK. Commands: `/cloudflare:build-agent`, `/cloudflare:build-mcp`. + --- ## Chapter 8: MCP Servers diff --git a/README.md b/README.md index 48c579e..62940cd 100644 --- a/README.md +++ b/README.md @@ -157,6 +157,16 @@ Claude Code Safety Net plugin https://github.com/kenryu42/claude-code-safety-net /plugin install glm-plan-usage@zai-coding-plugins ``` +[Cloudflare Skills marketplace](https://github.com/cloudflare/skills) for building applications on Cloudflare's platform, Workers, and the Agents SDK. + +> Collection of Agent Skills providing accurate, up-to-date guidance for Cloudflare development tasks including Workers, Pages, AI services, and infrastructure. + +```bash +/plugin marketplace add cloudflare/skills +``` + +**User commands**: `/cloudflare:build-agent`, `/cloudflare:build-mcp` + ## Claude Code Statuslines `~/.claude/statuslines/statusline.sh` configured in `~/.claude/settings.json`. From a0a851b33992fc14f08f180c75227d12d611613e Mon Sep 17 00:00:00 2001 From: George Liu Date: Fri, 30 Jan 2026 12:36:39 +1000 Subject: [PATCH 093/174] update Cloudflare docs for sandbox sdk and containers --- CLAUDE-cloudflare-mini.md | 69 +++++++++++ CLAUDE-cloudflare.md | 249 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 318 insertions(+) diff --git a/CLAUDE-cloudflare-mini.md b/CLAUDE-cloudflare-mini.md index ddcb03b..e96b7a4 100644 --- a/CLAUDE-cloudflare-mini.md +++ b/CLAUDE-cloudflare-mini.md @@ -29,6 +29,8 @@ Use MCP tools if available, otherwise web fetch these URLs: | Pages | https://developers.cloudflare.com/pages/ | | Pages Git Integration | https://developers.cloudflare.com/pages/get-started/git-integration/ | | Pages Functions | https://developers.cloudflare.com/pages/functions/ | +| Sandbox SDK | https://developers.cloudflare.com/sandbox/ | +| Containers | https://developers.cloudflare.com/containers/ | **Clerk:** | Resource | URL | @@ -155,6 +157,70 @@ export default { --- +## Sandbox SDK (Code Execution) + +Run untrusted code in isolated containers. Docs: https://developers.cloudflare.com/sandbox/ + +**Use cases:** AI agents, CI/CD, cloud REPLs, data analysis + +**Setup:** +```bash +npm create cloudflare@latest -- my-sandbox --template=cloudflare/sandbox-sdk/examples/minimal +``` + +**Wrangler config:** +```jsonc +"containers": [{ "class_name": "Sandbox", "image": "./Dockerfile", "instance_type": "lite", "max_instances": 5 }], +"durable_objects": { "bindings": [{ "class_name": "Sandbox", "name": "Sandbox" }] }, +"migrations": [{ "tag": "v1", "new_sqlite_classes": ["Sandbox"] }] +``` + +**Dockerfile:** +```dockerfile +FROM docker.io/cloudflare/sandbox:latest +RUN pip3 install --no-cache-dir pandas numpy +EXPOSE 8080 # Required for wrangler dev +``` + +**Basic usage (CRITICAL: proxyToSandbox first!):** +```typescript +import { getSandbox, proxyToSandbox, type Sandbox } from '@cloudflare/sandbox'; +export { Sandbox } from '@cloudflare/sandbox'; + +export default { + async fetch(request: Request, env: Env): Promise { + // CRITICAL: Must call first for preview URLs + const proxyResponse = await proxyToSandbox(request, env); + if (proxyResponse) return proxyResponse; + + const sandbox = getSandbox(env.Sandbox, 'my-sandbox', { normalizeId: true }); + const result = await sandbox.exec('python3 -c "print(2+2)"'); + // result.stdout, result.stderr, result.exitCode, result.success + + await sandbox.writeFile('/workspace/file.txt', 'content'); // Use /workspace! + const file = await sandbox.readFile('/workspace/file.txt'); + return Response.json({ output: result.stdout }); + } +}; +``` + +**Instance types:** +| Type | vCPU | Memory | +|------|------|--------| +| lite | 0.5 | 256MB | +| standard | 1 | 512MB | +| heavy | 2 | 1GB | + +**Sandbox Gotchas:** +- `proxyToSandbox()` MUST be called first +- Requires Docker locally for dev +- First deploy: 2-3 min; cold start: 2-3s +- Use `/workspace` for persistent files +- Preview URLs need custom domain + wildcard DNS + `normalizeId: true` +- `keepAlive: true` requires `destroy()` call + +--- + ## Secrets - `.dev.vars` for local (gitignore!) - `wrangler secret put KEY` for prod @@ -305,6 +371,9 @@ wrangler kv namespace create CACHE # Output includes namespace id - Clerk `@clerk/backend` needs BOTH secretKey AND publishableKey - D1 transactions: `await db.batch([stmt1, stmt2])` - Set `authorizedParties` in Clerk to prevent CSRF +- Sandbox: `proxyToSandbox()` MUST be called first +- Sandbox requires Docker locally; first deploy takes 2-3 min +- Use `/workspace` for persistent files in Sandbox --- diff --git a/CLAUDE-cloudflare.md b/CLAUDE-cloudflare.md index 38f7a4f..66ae3ef 100644 --- a/CLAUDE-cloudflare.md +++ b/CLAUDE-cloudflare.md @@ -39,6 +39,9 @@ Fetch and read these URLs to verify current APIs: | Pages Functions | https://developers.cloudflare.com/pages/functions/ | | Pages Functions Config | https://developers.cloudflare.com/pages/functions/wrangler-configuration/ | | Wrangler Config | https://developers.cloudflare.com/workers/wrangler/configuration/ | +| Sandbox SDK | https://developers.cloudflare.com/sandbox/ | +| Sandbox Get Started | https://developers.cloudflare.com/sandbox/get-started/ | +| Containers | https://developers.cloudflare.com/containers/ | **Clerk Authentication:** | Resource | URL | @@ -190,6 +193,17 @@ npm install drizzle-kit --save-dev "assets": { "directory": "./public" } ``` +**Sandbox SDK (Containers):** +```jsonc +"containers": [ + { "class_name": "Sandbox", "image": "./Dockerfile", "instance_type": "lite", "max_instances": 5 } +], +"durable_objects": { + "bindings": [{ "class_name": "Sandbox", "name": "Sandbox" }] +}, +"migrations": [{ "tag": "v1", "new_sqlite_classes": ["Sandbox"] }] +``` + --- ## Cloudflare Pages: Static HTML via GitHub @@ -329,6 +343,234 @@ wrangler pages dev ./ --d1=DB --- +## Sandbox SDK (Secure Code Execution) + +Run untrusted code in isolated Linux containers. Each sandbox = Durable Object + Container. + +### Documentation +| Resource | URL | +|----------|-----| +| Overview | https://developers.cloudflare.com/sandbox/ | +| Get Started | https://developers.cloudflare.com/sandbox/get-started/ | +| API Reference | https://developers.cloudflare.com/sandbox/api/ | +| GitHub | https://github.com/cloudflare/sandbox-sdk | + +### Use Cases +- **AI Agents**: Execute LLM-generated code safely +- **CI/CD**: Automated testing pipelines +- **Cloud REPLs**: Interactive development environments +- **Data Analysis**: Run scripts with rich outputs (charts, tables) + +### Instance Types +| Type | vCPU | Memory | +|------|------|--------| +| lite | 0.5 | 256 MB | +| standard | 1 | 512 MB | +| heavy | 2 | 1 GB | + +### Project Setup +```bash +npm create cloudflare@latest -- my-sandbox --template=cloudflare/sandbox-sdk/examples/minimal +``` + +### Wrangler Configuration +```jsonc +{ + "name": "my-sandbox-app", + "main": "src/index.ts", + "compatibility_date": "2025-01-01", + "containers": [{ + "class_name": "Sandbox", + "image": "./Dockerfile", + "instance_type": "lite", + "max_instances": 5 + }], + "durable_objects": { + "bindings": [{ "class_name": "Sandbox", "name": "Sandbox" }] + }, + "migrations": [{ "tag": "v1", "new_sqlite_classes": ["Sandbox"] }] +} +``` + +### Dockerfile +```dockerfile +FROM docker.io/cloudflare/sandbox:latest +RUN pip3 install --no-cache-dir pandas numpy matplotlib +EXPOSE 8080 3000 # Required for wrangler dev +``` + +### CRITICAL: Basic Usage Pattern +```typescript +import { getSandbox, proxyToSandbox, type Sandbox } from '@cloudflare/sandbox'; +export { Sandbox } from '@cloudflare/sandbox'; // MUST re-export + +type Env = { Sandbox: DurableObjectNamespace; }; + +export default { + async fetch(request: Request, env: Env): Promise { + // CRITICAL: proxyToSandbox MUST be called first for preview URLs + const proxyResponse = await proxyToSandbox(request, env); + if (proxyResponse) return proxyResponse; + + const sandbox = getSandbox(env.Sandbox, 'my-sandbox', { + normalizeId: true, // Required for preview URLs (lowercases ID) + sleepAfter: '10m', // Auto-sleep after inactivity + }); + + // Execute commands + const result = await sandbox.exec('python3 -c "print(2 + 2)"'); + // result: { stdout, stderr, exitCode, success, duration } + + return Response.json({ output: result.stdout }); + } +}; +``` + +### Command Execution API +```typescript +// Basic execution +const result = await sandbox.exec('python3 script.py', { + cwd: '/workspace/project', + env: { API_KEY: 'secret' }, + stream: true, + onOutput: (stream, data) => console.log(data) +}); + +// Background processes +const process = await sandbox.startProcess('python3 -m http.server 8080', { + processId: 'web-server', + cwd: '/workspace/public' +}); +await process.waitForPort(8080); // Wait for readiness +await process.waitForLog(/Server running/); // Wait for log pattern +const logs = await sandbox.getProcessLogs('web-server'); +await sandbox.stopProcess('web-server'); +``` + +### File Operations API +```typescript +// Write/read (use /workspace for persistent files) +await sandbox.writeFile('/workspace/file.txt', 'content'); +await sandbox.writeFile('/workspace/img.png', base64Data, { encoding: 'base64' }); +const { content } = await sandbox.readFile('/workspace/file.txt'); + +// Directory operations +await sandbox.mkdir('/workspace/dir', { recursive: true }); +const files = await sandbox.listFiles('/workspace'); +await sandbox.pathExists('/workspace/file.txt'); + +// Delete +await sandbox.deleteFile('/workspace/temp.txt'); +await sandbox.deleteFile('/workspace/dir', { recursive: true }); +``` + +### Sessions (Isolated Contexts) +```typescript +// Each session has own shell state, env vars, cwd +const session = await sandbox.createSession({ + id: 'user-123', + cwd: '/workspace/user123', + env: { USER_ID: '123' } +}); + +await session.exec('echo $USER_ID'); +await session.writeFile('config.txt', 'data'); +await sandbox.deleteSession('user-123'); +``` + +### Code Interpreter (Rich Outputs) +```typescript +// Create context with variables +const ctx = await sandbox.createCodeContext({ + language: 'python', + variables: { data: [1, 2, 3, 4, 5] } +}); + +// Execute code (state persists across runs) +const result = await ctx.runCode(` +import matplotlib.pyplot as plt +plt.plot(data, [x**2 for x in data]) +plt.savefig('plot.png') +`); +// result.outputs: [{ type: 'text'|'image'|'html', content }] +``` + +### Port Exposure & WebSockets +```typescript +// Expose service (requires custom domain, not .workers.dev) +const { url } = await sandbox.exposePort(8080, { + name: 'web-app', + hostname: request.hostname +}); + +// WebSocket proxy +if (request.headers.get('Upgrade') === 'websocket') { + return await sandbox.wsConnect(request, 8080); +} +``` + +### Bucket Mounting (Production Only) +```typescript +// Mount R2 bucket (NOT available in wrangler dev) +await sandbox.mountBucket(env.DATA_BUCKET, '/data', { readOnly: false }); +await sandbox.exec('ls /data'); +await sandbox.unmountBucket('/data'); +``` + +### Lifecycle Management +```typescript +// With keepAlive: true, MUST call destroy() +const sandbox = getSandbox(env.Sandbox, 'temp', { keepAlive: true }); +try { + const result = await sandbox.exec('python script.py'); + return result.stdout; +} finally { + await sandbox.destroy(); // REQUIRED to free resources +} +``` + +### Error Handling +```typescript +// Retry on CONTAINER_NOT_READY (cold start) +async function execWithRetry(sandbox, cmd) { + for (let i = 0; i < 3; i++) { + try { + return await sandbox.exec(cmd); + } catch (e) { + if (e.code === 'CONTAINER_NOT_READY') { + await new Promise(r => setTimeout(r, 2000)); + continue; + } + throw e; + } + } +} +``` + +### CLI Commands +```bash +wrangler dev # Local dev (requires Docker) +wrangler deploy # Deploy to production +wrangler containers list # Check container status +wrangler tail # Monitor logs +``` + +### Gotchas +1. **`proxyToSandbox()` MUST be called first** in fetch handler +2. **Docker required** for local development (`docker info` to verify) +3. **First deploy**: 2-3 minutes for container build +4. **Cold start**: 2-3s when waking from sleep +5. **Use `/workspace`** for persistent files (other paths are ephemeral) +6. **Preview URLs require**: + - Custom domain (not `.workers.dev`) + - Wildcard DNS (`*.domain.com → worker.domain.com`) + - `normalizeId: true` in getSandbox +7. **`keepAlive: true`** requires `destroy()` call +8. **Bucket mounting** only works in production (FUSE not in dev) +9. **Code contexts are ephemeral** - recreate after container sleep/wake + +--- + ## TypeScript Environment Types ### Generate Types @@ -780,6 +1022,8 @@ wrangler logout | KV | 25MB per value | | | R2 | 5TB per object | S3-compatible API | | Durable Objects | Single-threaded per instance | Use for coordination, WebSockets | +| Sandbox | lite: 0.5 vCPU, 256MB | standard: 1 vCPU, 512MB | heavy: 2 vCPU, 1GB | +| Sandbox | Cold start: 2-3s | First deploy: 2-3 min | ### Common Gotchas 1. **Clone Request** before reading body twice: `const clone = request.clone()` @@ -789,6 +1033,11 @@ wrangler logout 5. **D1 batch** for transactions: `await db.batch([stmt1, stmt2])` 6. **authorizedParties** recommended for Clerk to prevent CSRF attacks 7. **Clerk Bot Protection** uses Cloudflare Turnstile - blocks automated browser testing (disable in dev: Clerk Dashboard → Configure → Attack protection) +8. **Sandbox SDK**: `proxyToSandbox()` MUST be called first in fetch handler +9. **Sandbox SDK** requires Docker running locally for `wrangler dev` +10. **Sandbox containers** take 2-3 min on first deploy; use `/workspace` for persistent files +11. **Sandbox preview URLs** require custom domain (not .workers.dev), wildcard DNS, and `normalizeId: true` +12. **Sandbox `keepAlive: true`** requires explicit `destroy()` call to free resources --- From 0ef7ac272dd6cda979a15b3d68475db6039c4131 Mon Sep 17 00:00:00 2001 From: George Liu Date: Mon, 9 Feb 2026 23:23:49 +1000 Subject: [PATCH 094/174] updates --- .claude/settings.local.json | 3 ++- .claude/skills/consult-codex/SKILL.md | 14 +++++++------- README-v2.md | 1 + README-v3.md | 1 + README-v4.md | 1 + README.md | 1 + 6 files changed, 13 insertions(+), 8 deletions(-) diff --git a/.claude/settings.local.json b/.claude/settings.local.json index e56f400..428dc38 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -91,7 +91,8 @@ "Bash(git show:*)", "Skill(consult-zai)", "Bash(git cherry-pick:*)", - "Bash(zai:*)" + "Bash(zai:*)", + "WebFetch(domain:developers.cloudflare.com)" ], "deny": [], "defaultMode": "plan" diff --git a/.claude/skills/consult-codex/SKILL.md b/.claude/skills/consult-codex/SKILL.md index f408a8e..da63f79 100644 --- a/.claude/skills/consult-codex/SKILL.md +++ b/.claude/skills/consult-codex/SKILL.md @@ -1,11 +1,11 @@ --- name: consult-codex -description: Compare OpenAI Codex GPT-5.2 and code-searcher responses for comprehensive dual-AI code analysis. Use when you need multiple AI perspectives on code questions. +description: Compare OpenAI Codex GPT-5.3 and code-searcher responses for comprehensive dual-AI code analysis. Use when you need multiple AI perspectives on code questions. --- -# Dual-AI Consultation: Codex GPT-5.2 vs Code-Searcher +# Dual-AI Consultation: Codex GPT-5.3 vs Code-Searcher -You orchestrate consultation between OpenAI's Codex GPT-5.2 and Claude's code-searcher to provide comprehensive analysis with comparison. +You orchestrate consultation between OpenAI's Codex GPT-5.3 and Claude's code-searcher to provide comprehensive analysis with comparison. ## When to Use This Skill @@ -57,7 +57,7 @@ Wrap the user's question with structured output requirements: Launch both simultaneously in a single message with multiple tool calls: -- **For Codex GPT-5.2:** Use a temp file to avoid shell quoting issues: +- **For Codex GPT-5.3:** Use a temp file to avoid shell quoting issues: **Step 1:** Write the enhanced prompt to a temp file using the Write tool: ``` @@ -190,7 +190,7 @@ Use this exact format: --- -## Codex (GPT-5.2) Response +## Codex (GPT-5.3) Response [Raw output from codex-cli agent] @@ -204,7 +204,7 @@ Use this exact format: ## Comparison Table -| Aspect | Codex (GPT-5.2) | Code-Searcher (Claude) | +| Aspect | Codex (GPT-5.3) | Code-Searcher (Claude) | |--------|-----------------|------------------------| | File paths | [Specific/Generic/None] | [Specific/Generic/None] | | Line numbers | [Provided/Missing] | [Provided/Missing] | @@ -223,7 +223,7 @@ Use this exact format: ## Key Differences -- **Codex GPT-5.2:** [unique findings, strengths, approach] +- **Codex GPT-5.3:** [unique findings, strengths, approach] - **Code-Searcher:** [unique findings, strengths, approach] ## Synthesized Summary diff --git a/README-v2.md b/README-v2.md index 2be24ab..06e57d3 100644 --- a/README-v2.md +++ b/README-v2.md @@ -1390,6 +1390,7 @@ claude config set -g * [Advent of Claude: 31 Days](https://adocomplete.com/advent-of-claude-2025/) - Ado Kukic * [40+ Claude Code Tips](https://github.com/ykdojo/claude-code-tips) +* [OpenClaw: Security, Deployment & Cost Guide](https://github.com/centminmod/explain-openclaw) - For using Claude LLM models with OpenClaw --- diff --git a/README-v3.md b/README-v3.md index 7a1feb2..6bed18c 100644 --- a/README-v3.md +++ b/README-v3.md @@ -1089,6 +1089,7 @@ claude config set -g # Global setting * [Advent of Claude: 31 Days](https://adocomplete.com/advent-of-claude-2025/) - Ado Kukic * [40+ Claude Code Tips](https://github.com/ykdojo/claude-code-tips) +* [OpenClaw: Security, Deployment & Cost Guide](https://github.com/centminmod/explain-openclaw) - For using Claude LLM models with OpenClaw --- diff --git a/README-v4.md b/README-v4.md index c9c20c7..aa571ff 100644 --- a/README-v4.md +++ b/README-v4.md @@ -1913,6 +1913,7 @@ See official Claude Code documentation for current shortcuts. |-------|---------|-----| | 31 Days of Claude Code | Ado Kukic (Anthropic) | | | 40+ Claude Code Tips | ykdojo | | +| OpenClaw: Security, Deployment & Cost Guide | centminmod | | ### Community Resources diff --git a/README.md b/README.md index 62940cd..583b24e 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,7 @@ My Claude Code project's starter settings and Claude Code hooks and slash comman 11. Useful read [Advent of Claude: 31 Days of Claude Code by Ado Kukic from Anthropic](https://adocomplete.com/advent-of-claude-2025/). 12. Useful [Claude Code with Claude Opus 4.5 YouTube video by Alex Finn](https://www.youtube.com/watch?v=UVJXh57MgI0) and [Claude Code YouTube video by Matt Maher](https://www.youtube.com/watch?v=Dekx_OzRwiI). 13. Configure Claude Code with [Z.AI](#using-zai-with-claude-code) to get higher token usage quotas and get access to Z.AI GLM-4.7 LLM models within Claude Code. +14. For folks intending to use Claude LLM models with OpenClaw, read this first for security, deployment and cost optimizations https://github.com/centminmod/explain-openclaw. ## CLAUDE.md Memory Bank system From c3c459870b2530de208e00b01f0ffa3e5ea50155 Mon Sep 17 00:00:00 2001 From: George Liu Date: Wed, 25 Mar 2026 22:22:23 +1000 Subject: [PATCH 095/174] add ai-image-creator skill for nano banana 2 support --- .claude/skills/ai-image-creator/SKILL.md | 158 +++++ .../references/api-reference.md | 220 ++++++ .../references/setup-guide.md | 218 ++++++ .../scripts/generate-image.py | 656 ++++++++++++++++++ .claude/skills/ai-image-creator/tmp/.gitkeep | 0 README-v2.md | 1 + README-v3.md | 1 + README-v4.md | 21 + README.md | 13 + 9 files changed, 1288 insertions(+) create mode 100644 .claude/skills/ai-image-creator/SKILL.md create mode 100644 .claude/skills/ai-image-creator/references/api-reference.md create mode 100644 .claude/skills/ai-image-creator/references/setup-guide.md create mode 100644 .claude/skills/ai-image-creator/scripts/generate-image.py create mode 100644 .claude/skills/ai-image-creator/tmp/.gitkeep diff --git a/.claude/skills/ai-image-creator/SKILL.md b/.claude/skills/ai-image-creator/SKILL.md new file mode 100644 index 0000000..0a1fb13 --- /dev/null +++ b/.claude/skills/ai-image-creator/SKILL.md @@ -0,0 +1,158 @@ +--- +name: ai-image-creator +description: Generate PNG images using AI (Google Gemini 3.1 Flash via OpenRouter or Google AI Studio, proxied through Cloudflare AI Gateway BYOK). Use when user asks to "generate an image", "create a PNG", "make an icon", or needs AI-generated visual assets for the project. Supports configurable aspect ratios and resolutions. +allowed-tools: Bash, Read, Write +compatibility: Requires uv (Python runner) and network access. Environment variables for CF AI Gateway or direct API keys must be configured in shell profile (~/.zshrc on macOS, ~/.bashrc on Linux, or System Environment Variables on Windows). +metadata: + tags: image-generation, ai, openrouter, cloudflare, gemini +--- + +# AI Image Creator + +Generate PNG images via Google Gemini 3.1 Flash, routed through Cloudflare AI Gateway BYOK or directly via OpenRouter/Google AI Studio. + +## Instructions + +### Step 1: Write Prompt + +For long or complex prompts (recommended), write to `${CLAUDE_SKILL_DIR}/tmp/prompt.txt` using the Write tool: + +``` +Write prompt text to ${CLAUDE_SKILL_DIR}/tmp/prompt.txt +``` + +For short prompts (under 200 chars, no special characters), pass inline via `--prompt`. + +**CRITICAL — Prompt Quality Tips:** +- Be detailed and descriptive. Include style, colors, composition, background, and intended use. +- Good: "A flat-design globe icon with vertical timezone band lines in blue and teal, white background, clean vector style, suitable for a web app at 512x512 pixels" +- Bad: "globe icon" +- Specify "transparent background" or "white background" explicitly. +- For icons, mention the target size (e.g., "512x512", "favicon at 32x32"). +- For photos, describe lighting, camera angle, and mood. + +### Step 2: Run Generation Script + +```bash +uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py \ + --output "OUTPUT_PATH" \ + [--provider openrouter|google] \ + [--aspect-ratio "16:9"] \ + [--image-size "2K"] \ + [--model "model-id"] +``` + +Or with inline prompt: +```bash +uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py \ + --output "OUTPUT_PATH" \ + --prompt "A simple blue circle on white background" +``` + +### Step 3: Clean Up (if temp file used) + +```bash +rm -f ${CLAUDE_SKILL_DIR}/tmp/prompt.txt +``` + +### Step 4: Verify Output + +```bash +file OUTPUT_PATH +``` + +Confirm it shows "PNG image data" and report the file path and size to the user. + +### Step 5: Post-Processing (optional) + +If the user needs resizing, format conversion, or other manipulation, first detect available image tools, then use them. See **Image Tools** section below. + +## Parameters + +| Argument | Required | Default | Description | +|----------|----------|---------|-------------| +| `--output` | Yes | -- | Output file path (parent dirs auto-created) | +| `--prompt` | No | -- | Inline prompt text | +| `--prompt-file` | No | `../tmp/prompt.txt` | Path to prompt file | +| `--provider` | No | `openrouter` | `openrouter` or `google` | +| `--aspect-ratio` | No | model default | OpenRouter only: `1:1`, `16:9`, `9:16`, `3:2`, `2:3`, `4:3`, `3:4`, `4:5`, `5:4`, `21:9` | +| `--image-size` | No | model default | OpenRouter only: `0.5K`, `1K`, `2K`, `4K` | +| `--model` | No | auto per provider | Override model ID | + +## Environment Variables + +| Variable | Required For | Description | +|----------|-------------|-------------| +| `AI_IMG_CREATOR_CF_ACCOUNT_ID` | Gateway mode | Cloudflare account ID | +| `AI_IMG_CREATOR_CF_GATEWAY_ID` | Gateway mode | AI Gateway name | +| `AI_IMG_CREATOR_CF_TOKEN` | Gateway mode | Gateway auth token | +| `AI_IMG_CREATOR_OPENROUTER_KEY` | Direct OpenRouter | OpenRouter API key (`sk-or-...`) | +| `AI_IMG_CREATOR_GEMINI_KEY` | Direct Google | Google AI Studio API key | + +Gateway mode activates when all 3 `CF_*` vars are set. Falls back to direct mode if gateway fails. + +For first-time setup, see `references/setup-guide.md`. + +## Image Tools + +On first invocation, detect available image manipulation tools: + +```bash +which magick convert sips ffmpeg 2>/dev/null +``` + +### Available Tools + +| Tool | Check | Key Operations | +|------|-------|----------------| +| **ImageMagick 7** (`magick`) | `magick --version` | Resize, crop, convert, composite | +| **ImageMagick 6** (`convert`) | `convert --version` | Same ops, legacy command name | +| **sips** (macOS) | `sips --help` | Resize, format conversion | +| **ffmpeg** | `ffmpeg -version` | Convert formats, resize | + +### Common Post-Processing + +```bash +# Resize +magick output.png -resize 512x512 icon-512.png + +# Multiple sizes (icons) +for s in 16 32 48 64 128 256 512; do magick output.png -resize ${s}x${s} icon-${s}.png; done + +# Convert to WebP +magick output.png output.webp + +# Maskable icon (add safe-zone padding) +magick output.png -gravity center -extent 120%x120% maskable.png + +# macOS sips resize +sips --resampleWidth 512 --resampleHeight 512 output.png --out icon-512.png +``` + +CRITICAL: Check tool availability before using. Prefer `magick` (IM7) over `convert` (IM6). If no tools found, inform user: `brew install imagemagick`. + +## Common Issues + +### "No API credentials configured" +**Cause:** Environment variables not set or not exported. +**Fix:** Add exports to `~/.zshrc` and run `source ~/.zshrc`. See `references/setup-guide.md`. + +### "HTTP 401: Unauthorized" +**Cause:** Invalid or expired API key/token. +**Fix:** Check `AI_IMG_CREATOR_CF_TOKEN` (gateway) or `AI_IMG_CREATOR_OPENROUTER_KEY` (direct). Regenerate if needed. + +### "No images in response" +**Cause:** Model returned text only (safety filter, unclear prompt, or unsupported request). +**Fix:** Make the prompt more specific and descriptive. Avoid prohibited content. + +### "Connection error" / timeout +**Cause:** Network issue or image generation taking too long (120s timeout). +**Fix:** Retry. If persistent, try `--provider google` as alternative. Check CF gateway status. + +## Detailed API Reference + +For full API formats, response schemas, BYOK configuration, and curl examples: +see [references/api-reference.md](references/api-reference.md) + +For first-time setup instructions: +see [references/setup-guide.md](references/setup-guide.md) diff --git a/.claude/skills/ai-image-creator/references/api-reference.md b/.claude/skills/ai-image-creator/references/api-reference.md new file mode 100644 index 0000000..5553e4a --- /dev/null +++ b/.claude/skills/ai-image-creator/references/api-reference.md @@ -0,0 +1,220 @@ +# API Reference — AI Image Creator + +## Providers & Endpoints + +### OpenRouter (via CF AI Gateway) + +**Gateway URL:** +``` +https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openrouter/v1/chat/completions +``` + +**Direct URL:** +``` +https://openrouter.ai/api/v1/chat/completions +``` + +**Request format (OpenAI-compatible):** +```json +{ + "model": "google/gemini-3.1-flash-image-preview", + "messages": [ + {"role": "user", "content": "Generate a beautiful sunset over mountains"} + ], + "modalities": ["image", "text"], + "image_config": { + "aspect_ratio": "16:9", + "image_size": "1K" + } +} +``` + +**Response format:** +```json +{ + "choices": [ + { + "message": { + "role": "assistant", + "content": "Here is your generated image", + "images": [ + { + "image_url": { + "url": "data:image/png;base64,iVBORw0KGgo..." + } + } + ] + } + } + ] +} +``` + +**Image extraction:** `choices[0].message.images[0].image_url.url` — strip `data:image/png;base64,` prefix, then base64 decode. + +**curl example (gateway):** +```bash +curl -s -X POST \ + "https://gateway.ai.cloudflare.com/v1/${AI_IMG_CREATOR_CF_ACCOUNT_ID}/${AI_IMG_CREATOR_CF_GATEWAY_ID}/openrouter/v1/chat/completions" \ + -H "Content-Type: application/json" \ + -H "cf-aig-authorization: Bearer ${AI_IMG_CREATOR_CF_TOKEN}" \ + -d '{ + "model": "google/gemini-3.1-flash-image-preview", + "messages": [{"role": "user", "content": "A blue circle on white background"}], + "modalities": ["image", "text"] + }' +``` + +**curl example (direct):** +```bash +curl -s -X POST \ + "https://openrouter.ai/api/v1/chat/completions" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer ${AI_IMG_CREATOR_OPENROUTER_KEY}" \ + -d '{ + "model": "google/gemini-3.1-flash-image-preview", + "messages": [{"role": "user", "content": "A blue circle on white background"}], + "modalities": ["image", "text"] + }' +``` + +--- + +### Google AI Studio (via CF AI Gateway) + +**Gateway URL:** +``` +https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/google-ai-studio/v1beta/models/{model}:generateContent +``` + +**Direct URL:** +``` +https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent +``` + +**Request format (Gemini native):** +```json +{ + "contents": [ + { + "parts": [ + {"text": "Generate a beautiful sunset over mountains"} + ] + } + ] +} +``` + +**Response format:** +```json +{ + "candidates": [ + { + "content": { + "parts": [ + {"text": "Here is your generated image"}, + { + "inlineData": { + "mimeType": "image/png", + "data": "iVBORw0KGgo..." + } + } + ] + } + } + ] +} +``` + +**Image extraction:** Iterate `candidates[0].content.parts[]`, find the part with `inlineData`, then base64 decode `inlineData.data`. + +**curl example (gateway):** +```bash +curl -s -X POST \ + "https://gateway.ai.cloudflare.com/v1/${AI_IMG_CREATOR_CF_ACCOUNT_ID}/${AI_IMG_CREATOR_CF_GATEWAY_ID}/google-ai-studio/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \ + -H "Content-Type: application/json" \ + -H "cf-aig-authorization: Bearer ${AI_IMG_CREATOR_CF_TOKEN}" \ + -H "cf-aig-byok-alias: aistudio" \ + -d '{ + "contents": [{"parts": [{"text": "A blue circle on white background"}]}] + }' +``` + +**curl example (direct):** +```bash +curl -s -X POST \ + "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent" \ + -H "Content-Type: application/json" \ + -H "x-goog-api-key: ${AI_IMG_CREATOR_GEMINI_KEY}" \ + -d '{ + "contents": [{"parts": [{"text": "A blue circle on white background"}]}] + }' +``` + +--- + +## CF AI Gateway BYOK Headers + +| Header | Purpose | +|--------|---------| +| `cf-aig-authorization: Bearer {token}` | Gateway authentication (required if auth enabled) | +| `cf-aig-byok-alias: {alias}` | Select which stored provider key to use (default: `default`) | +| `cf-aig-cache-ttl: {seconds}` | Cache responses for N seconds (optional) | + +**Configured BYOK aliases:** +- `default` — OpenRouter API key +- `aistudio` — Google AI Studio API key + +--- + +## Supported Aspect Ratios (OpenRouter `image_config`) + +| Ratio | Pixels | Notes | +|-------|--------|-------| +| `1:1` | 1024x1024 | Default if not specified | +| `2:3` | 832x1248 | Portrait | +| `3:2` | 1248x832 | Landscape | +| `3:4` | 864x1184 | Portrait | +| `4:3` | 1184x864 | Landscape | +| `4:5` | 896x1152 | Portrait | +| `5:4` | 1152x896 | Landscape | +| `9:16` | 768x1344 | Mobile/vertical | +| `16:9` | 1344x768 | Widescreen | +| `21:9` | 1536x672 | Ultra-wide | +| `1:4` | Tall narrow | Gemini 3.1 Flash only | +| `4:1` | Wide short | Gemini 3.1 Flash only | + +## Supported Image Sizes (OpenRouter `image_config`) + +| Size | Description | +|------|-------------| +| `0.5K` | Lower resolution, efficient (Gemini 3.1 Flash only) | +| `1K` | Standard resolution (default) | +| `2K` | Higher resolution | +| `4K` | Highest resolution | + +--- + +## Error Response Formats + +**OpenRouter error:** +```json +{ + "error": { + "message": "Description of the error", + "code": 400 + } +} +``` + +**Google AI Studio error (safety block):** +```json +{ + "promptFeedback": { + "blockReason": "SAFETY" + } +} +``` + +**Google AI Studio error (no image generated):** +Response has `candidates[0].content.parts` with only `text` parts and no `inlineData`. diff --git a/.claude/skills/ai-image-creator/references/setup-guide.md b/.claude/skills/ai-image-creator/references/setup-guide.md new file mode 100644 index 0000000..59ab9c8 --- /dev/null +++ b/.claude/skills/ai-image-creator/references/setup-guide.md @@ -0,0 +1,218 @@ +# Setup Guide — AI Image Creator + +Step-by-step instructions to configure all required services for the ai-image-creator skill. + +## Prerequisites + +- **uv** (Python runner): Install via `curl -LsSf https://astral.sh/uv/install.sh | sh` or `brew install uv` +- **Python 3.10+**: Bundled with uv or install separately +- A Cloudflare account (free tier works) +- An OpenRouter account and/or Google AI Studio account + +--- + +## 1. Get an OpenRouter API Key + +1. Create an account at [openrouter.ai](https://openrouter.ai) +2. Go to [openrouter.ai/keys](https://openrouter.ai/keys) and click **Create Key** +3. Copy the key (starts with `sk-or-...`) +4. Add credits at [openrouter.ai/credits](https://openrouter.ai/credits) (pay-as-you-go pricing) + +**Model pricing:** `google/gemini-3.1-flash-image-preview` — check current rates at [openrouter.ai/models](https://openrouter.ai/models) (search for "gemini-3.1-flash-image-preview") + +--- + +## 2. Get a Google AI Studio API Key + +1. Go to [aistudio.google.com/apikey](https://aistudio.google.com/apikey) +2. Click **Create API Key** +3. Select or create a Google Cloud project +4. Copy the key (starts with `AI...`) + +**Pricing:** Free tier has rate limits. Check quotas at [ai.google.dev/pricing](https://ai.google.dev/pricing) + +**Important:** The free tier has a quota of **0** for `gemini-3.1-flash-image` image generation. You must enable billing on the linked Google Cloud project for image generation to work. Without billing, requests return `429 RESOURCE_EXHAUSTED` with `limit: 0`. The OpenRouter provider is recommended as a simpler alternative (pay-as-you-go credits, no GCP billing setup required). + +--- + +## 3. Create a Cloudflare AI Gateway + +1. Log in to [dash.cloudflare.com](https://dash.cloudflare.com) +2. Select your account +3. Navigate to **AI** > **AI Gateway** +4. Click **Create Gateway** +5. Enter a name (e.g., `my-ai-gateway`) — this becomes your Gateway ID +6. Click **Create** + +**Note your credentials:** +- **Account ID**: Found in the dashboard URL (`dash.cloudflare.com/{account_id}/...`) or on the account Overview page +- **Gateway ID**: The name you chose in step 5 + +### Enable Authentication (Recommended) + +1. In your gateway settings, enable **Authentication** +2. Copy the **auth token** — this is your `AI_IMG_CREATOR_CF_TOKEN` + +--- + +## 4. Configure BYOK Provider Keys in CF AI Gateway + +Store your API keys securely in Cloudflare so they're never sent in request headers. + +### Add OpenRouter Key + +1. In your gateway dashboard, go to **Provider Keys** +2. Click **Add** +3. Select **OpenRouter** as the provider +4. Paste your OpenRouter API key (`sk-or-...`) +5. Set alias to `default` +6. Click **Save** + +### Add Google AI Studio Key + +1. Click **Add** again +2. Select **Google AI Studio** as the provider +3. Paste your Google AI Studio API key (`AI...`) +4. Set alias to `aistudio` +5. Click **Save** + +--- + +## 5. Set Environment Variables + +Add these to your shell profile or system environment variables. + +### macOS / Linux + +Edit `~/.zshrc` (macOS) or `~/.bashrc` (Linux): + +```bash +# AI Image Creator — CF AI Gateway (preferred mode) +export AI_IMG_CREATOR_CF_ACCOUNT_ID="your-cloudflare-account-id" +export AI_IMG_CREATOR_CF_GATEWAY_ID="your-gateway-name" +export AI_IMG_CREATOR_CF_TOKEN="your-gateway-auth-token" + +# AI Image Creator — Direct API keys (fallback, optional if BYOK configured) +export AI_IMG_CREATOR_OPENROUTER_KEY="sk-or-your-key-here" +export AI_IMG_CREATOR_GEMINI_KEY="AIyour-key-here" +``` + +Apply changes: + +```bash +source ~/.zshrc # macOS +source ~/.bashrc # Linux +``` + +### Windows + +Set environment variables via PowerShell (user-level, persists across sessions): + +```powershell +# AI Image Creator — CF AI Gateway (preferred mode) +[Environment]::SetEnvironmentVariable("AI_IMG_CREATOR_CF_ACCOUNT_ID", "your-cloudflare-account-id", "User") +[Environment]::SetEnvironmentVariable("AI_IMG_CREATOR_CF_GATEWAY_ID", "your-gateway-name", "User") +[Environment]::SetEnvironmentVariable("AI_IMG_CREATOR_CF_TOKEN", "your-gateway-auth-token", "User") + +# AI Image Creator — Direct API keys (fallback, optional if BYOK configured) +[Environment]::SetEnvironmentVariable("AI_IMG_CREATOR_OPENROUTER_KEY", "sk-or-your-key-here", "User") +[Environment]::SetEnvironmentVariable("AI_IMG_CREATOR_GEMINI_KEY", "AIyour-key-here", "User") +``` + +Or use **Settings > System > About > Advanced system settings > Environment Variables** to add them via the GUI. + +Restart your terminal after setting variables. + +### Verify + +```bash +echo $AI_IMG_CREATOR_CF_ACCOUNT_ID # macOS/Linux +echo %AI_IMG_CREATOR_CF_ACCOUNT_ID% # Windows CMD +$env:AI_IMG_CREATOR_CF_ACCOUNT_ID # Windows PowerShell +``` + +--- + +## 6. Install the Skill + +### Per-Project Installation + +Copy the `ai-image-creator/` folder to your project: +```bash +cp -r /path/to/ai-image-creator .claude/skills/ +``` + +Add permission to `.claude/settings.local.json`: +```json +{ + "permissions": { + "allow": [ + "Skill(ai-image-creator)", + "Bash(uv run:*)" + ] + } +} +``` + +### Global Installation + +Place in your home directory: +```bash +cp -r /path/to/ai-image-creator ~/.claude/skills/ +``` + +Add permission to `~/.claude/settings.json`: +```json +{ + "permissions": { + "allow": [ + "Skill(ai-image-creator)", + "Bash(uv run:*)" + ] + } +} +``` + +--- + +## 7. Verify Setup + +Test the skill: + +``` +/ai-image-creator +``` + +Then ask: "Generate a simple blue circle on white background" with output to `test-image.png`. + +**Expected result:** A PNG file is created. The script outputs the file path and size. + +**Clean up test file:** +```bash +rm test-image.png +``` + +--- + +## Troubleshooting + +### "No API credentials configured" +Environment variables are not set or not exported. Run `echo $AI_IMG_CREATOR_CF_ACCOUNT_ID` to verify. + +### "HTTP 401: Unauthorized" +- **Gateway mode:** Check `AI_IMG_CREATOR_CF_TOKEN` is correct. Regenerate in CF dashboard if needed. +- **Direct mode:** Check `AI_IMG_CREATOR_OPENROUTER_KEY` or `AI_IMG_CREATOR_GEMINI_KEY`. + +### "uv: command not found" +Install uv: `curl -LsSf https://astral.sh/uv/install.sh | sh` or `brew install uv` + +### Gateway returns unexpected errors +Test direct mode by temporarily unsetting CF variables: +```bash +unset AI_IMG_CREATOR_CF_ACCOUNT_ID +/ai-image-creator +``` +If direct mode works, the issue is with the gateway configuration. + +### BYOK key not found +Verify in CF dashboard: AI > AI Gateway > your gateway > Provider Keys. Ensure aliases match: `default` for OpenRouter, `aistudio` for Google AI Studio. diff --git a/.claude/skills/ai-image-creator/scripts/generate-image.py b/.claude/skills/ai-image-creator/scripts/generate-image.py new file mode 100644 index 0000000..81a8722 --- /dev/null +++ b/.claude/skills/ai-image-creator/scripts/generate-image.py @@ -0,0 +1,656 @@ +#!/usr/bin/env python3 +"""AI Image Generator — Generate PNG images via OpenRouter or Google AI Studio. + +Routes through Cloudflare AI Gateway BYOK when configured, with automatic +fallback to direct API calls. Uses only Python stdlib (no pip dependencies). + +Usage: + uv run python generate-image.py --output path.png --prompt "description" + uv run python generate-image.py --output path.png --prompt-file prompt.txt + uv run python generate-image.py --output path.png --prompt "test" --debug +""" + +from __future__ import annotations + +import argparse +import base64 +import json +import logging +import os +import sys +import time +import urllib.error +import urllib.request +from pathlib import Path +from typing import Any # noqa: F401 — used in type hints below + +# Default models per provider +DEFAULT_MODELS = { + "openrouter": "google/gemini-3.1-flash-image-preview", + "google": "gemini-3.1-flash-image-preview", +} + +# Environment variable names (prefixed to avoid collisions) +ENV_CF_ACCOUNT_ID = "AI_IMG_CREATOR_CF_ACCOUNT_ID" +ENV_CF_GATEWAY_ID = "AI_IMG_CREATOR_CF_GATEWAY_ID" +ENV_CF_TOKEN = "AI_IMG_CREATOR_CF_TOKEN" +ENV_OPENROUTER_KEY = "AI_IMG_CREATOR_OPENROUTER_KEY" +ENV_GEMINI_KEY = "AI_IMG_CREATOR_GEMINI_KEY" + +# Logger — configured in main() based on --debug / --verbose flags +log = logging.getLogger("ai-image-creator") + + +def mask_key(key: str, visible: int = 4) -> str: + """Mask an API key for safe logging, showing only the last N chars. + + Args: + key: The secret key to mask. + visible: Number of trailing characters to leave visible. + + Returns: + Masked string like '***abcd'. + """ + if not key or len(key) <= visible: + return "***" + return f"***{key[-visible:]}" + + +def parse_args() -> argparse.Namespace: + """Parse command-line arguments. + + Returns: + Namespace with output, prompt, prompt_file, provider, aspect_ratio, + image_size, model, debug, and verbose attributes. + """ + parser = argparse.ArgumentParser( + description="Generate PNG images using AI (Gemini via OpenRouter/Google AI Studio)" + ) + parser.add_argument( + "--output", required=True, help="Output PNG file path" + ) + parser.add_argument( + "--prompt", default=None, help="Inline prompt text (alternative to --prompt-file)" + ) + parser.add_argument( + "--prompt-file", + default=None, + help="Path to prompt text file (default: ../tmp/prompt.txt relative to script)", + ) + parser.add_argument( + "--provider", + choices=["openrouter", "google"], + default="openrouter", + help="API provider (default: openrouter)", + ) + parser.add_argument( + "--aspect-ratio", + default=None, + help="Aspect ratio for image (OpenRouter only): 1:1, 16:9, 9:16, 3:2, 2:3, etc.", + ) + parser.add_argument( + "--image-size", + default=None, + help="Image resolution (OpenRouter only): 0.5K, 1K, 2K, 4K", + ) + parser.add_argument( + "--model", + default=None, + help="Model ID (default: auto per provider)", + ) + parser.add_argument( + "--debug", + action="store_true", + help="Enable debug logging (shows full request/response details, masked keys)", + ) + parser.add_argument( + "--verbose", + action="store_true", + help="Enable verbose logging (more detail than default, less than debug)", + ) + return parser.parse_args() + + +def setup_logging(debug: bool = False, verbose: bool = False) -> None: + """Configure logging based on flags.""" + if debug: + level = logging.DEBUG + elif verbose: + level = logging.INFO + else: + level = logging.WARNING + + handler = logging.StreamHandler(sys.stderr) + handler.setFormatter( + logging.Formatter("[%(levelname)s] %(message)s") + ) + log.addHandler(handler) + log.setLevel(level) + + +def resolve_prompt(args: argparse.Namespace) -> str: + """Resolve prompt text from --prompt, --prompt-file, or default path. + + Priority: --prompt (inline) > --prompt-file > default tmp/prompt.txt. + + Args: + args: Parsed CLI arguments. + + Returns: + The prompt text string. + + Raises: + SystemExit: If prompt file is missing or empty. + """ + if args.prompt: + log.debug("Using inline --prompt argument") + return args.prompt + + if args.prompt_file: + prompt_path = Path(args.prompt_file) + log.debug(f"Using --prompt-file: {prompt_path}") + else: + prompt_path = Path(__file__).parent.parent / "tmp" / "prompt.txt" + log.debug(f"Using default prompt file: {prompt_path}") + + if not prompt_path.exists(): + print(f"ERROR: Prompt file not found: {prompt_path}", file=sys.stderr) + print( + "Either pass --prompt 'text' or write prompt to the file first.", + file=sys.stderr, + ) + sys.exit(1) + + text = prompt_path.read_text(encoding="utf-8").strip() + if not text: + print(f"ERROR: Prompt file is empty: {prompt_path}", file=sys.stderr) + sys.exit(1) + + log.debug(f"Prompt length: {len(text)} chars") + log.debug(f"Prompt preview: {text[:200]}{'...' if len(text) > 200 else ''}") + return text + + +def detect_mode(provider: str) -> tuple[str, dict[str, str]]: + """Detect gateway vs direct mode based on available env vars. + + Args: + provider: Either 'openrouter' or 'google'. + + Returns: + Tuple of (mode, config) where mode is 'gateway' or 'direct' and + config contains the relevant credentials. + + Raises: + SystemExit: If no credentials are configured for the provider. + """ + cf_account = os.environ.get(ENV_CF_ACCOUNT_ID, "").strip() + cf_gateway = os.environ.get(ENV_CF_GATEWAY_ID, "").strip() + cf_token = os.environ.get(ENV_CF_TOKEN, "").strip() + has_gateway = all([cf_account, cf_gateway, cf_token]) + + log.debug(f"Env check: {ENV_CF_ACCOUNT_ID}={'set' if cf_account else 'MISSING'}") + log.debug(f"Env check: {ENV_CF_GATEWAY_ID}={'set' if cf_gateway else 'MISSING'}") + log.debug(f"Env check: {ENV_CF_TOKEN}={'set (' + mask_key(cf_token) + ')' if cf_token else 'MISSING'}") + + if provider == "openrouter": + direct_key = os.environ.get(ENV_OPENROUTER_KEY, "").strip() + log.debug(f"Env check: {ENV_OPENROUTER_KEY}={'set (' + mask_key(direct_key) + ')' if direct_key else 'MISSING'}") + else: + direct_key = os.environ.get(ENV_GEMINI_KEY, "").strip() + log.debug(f"Env check: {ENV_GEMINI_KEY}={'set (' + mask_key(direct_key) + ')' if direct_key else 'MISSING'}") + + if has_gateway: + log.info(f"Mode: gateway (account={cf_account}, gateway={cf_gateway})") + log.debug(f"Gateway has direct_key fallback: {'yes' if direct_key else 'no'}") + return "gateway", { + "cf_account": cf_account, + "cf_gateway": cf_gateway, + "cf_token": cf_token, + "direct_key": direct_key, + } + elif direct_key: + log.info("Mode: direct (gateway env vars not fully set)") + return "direct", {"direct_key": direct_key} + else: + print("ERROR: No API credentials configured.", file=sys.stderr) + print("", file=sys.stderr) + print("For CF AI Gateway BYOK (preferred), set:", file=sys.stderr) + print(f" export {ENV_CF_ACCOUNT_ID}=your-account-id", file=sys.stderr) + print(f" export {ENV_CF_GATEWAY_ID}=your-gateway-name", file=sys.stderr) + print(f" export {ENV_CF_TOKEN}=your-gateway-auth-token", file=sys.stderr) + print("", file=sys.stderr) + if provider == "openrouter": + print("For direct OpenRouter access, set:", file=sys.stderr) + print(f" export {ENV_OPENROUTER_KEY}=sk-or-...", file=sys.stderr) + else: + print("For direct Google AI Studio access, set:", file=sys.stderr) + print(f" export {ENV_GEMINI_KEY}=AI...", file=sys.stderr) + print("", file=sys.stderr) + print( + "See references/setup-guide.md for full setup instructions.", + file=sys.stderr, + ) + sys.exit(1) + + +def build_gateway_url(provider: str, model: str, config: dict[str, str]) -> str: + """Build CF AI Gateway URL for the given provider. + + Args: + provider: 'openrouter' or 'google'. + model: Model ID (used in Google URL path). + config: Credentials dict with cf_account, cf_gateway keys. + + Returns: + Full gateway URL string. + """ + base = f"https://gateway.ai.cloudflare.com/v1/{config['cf_account']}/{config['cf_gateway']}" + if provider == "openrouter": + url = f"{base}/openrouter/v1/chat/completions" + else: + url = f"{base}/google-ai-studio/v1beta/models/{model}:generateContent" + log.debug(f"Built gateway URL: {url}") + return url + + +def build_direct_url(provider: str, model: str) -> str: + """Build direct API URL for the given provider. + + Args: + provider: 'openrouter' or 'google'. + model: Model ID (used in Google URL path). + + Returns: + Full direct API URL string. + """ + if provider == "openrouter": + url = "https://openrouter.ai/api/v1/chat/completions" + else: + url = f"https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent" + log.debug(f"Built direct URL: {url}") + return url + + +def build_headers(provider: str, mode: str, config: dict[str, str]) -> dict[str, str]: + """Build HTTP headers for the request. + + Args: + provider: 'openrouter' or 'google'. + mode: 'gateway' or 'direct'. + config: Credentials dict. + + Returns: + Dict of HTTP header name-value pairs. + """ + headers = { + "Content-Type": "application/json", + "User-Agent": "ai-image-creator/1.0", + } + + if mode == "gateway": + headers["cf-aig-authorization"] = f"Bearer {config['cf_token']}" + if provider == "google": + headers["cf-aig-byok-alias"] = "aistudio" + if provider == "openrouter" and config.get("direct_key"): + headers["Authorization"] = f"Bearer {config['direct_key']}" + else: + if provider == "openrouter": + headers["Authorization"] = f"Bearer {config['direct_key']}" + else: + headers["x-goog-api-key"] = config["direct_key"] + + # Log headers with masked sensitive values + safe_headers = {} + for k, v in headers.items(): + if k.lower() in ("authorization", "cf-aig-authorization", "x-goog-api-key"): + safe_headers[k] = f"{v[:12]}...{mask_key(v)}" + else: + safe_headers[k] = v + log.debug(f"Request headers: {json.dumps(safe_headers, indent=2)}") + + return headers + + +def build_request_body( + provider: str, + model: str, + prompt: str, + aspect_ratio: str | None = None, + image_size: str | None = None, +) -> dict[str, Any]: + """Build JSON request body for the given provider. + + Args: + provider: 'openrouter' or 'google'. + model: Model ID string. + prompt: The image generation prompt text. + aspect_ratio: Optional aspect ratio (OpenRouter only), e.g. '16:9'. + image_size: Optional image size (OpenRouter only), e.g. '2K'. + + Returns: + Dict suitable for JSON serialization as request body. + """ + if provider == "openrouter": + body = { + "model": model, + "messages": [{"role": "user", "content": prompt}], + "modalities": ["image", "text"], + } + image_config = {} + if aspect_ratio: + image_config["aspect_ratio"] = aspect_ratio + if image_size: + image_config["image_size"] = image_size + if image_config: + body["image_config"] = image_config + log.debug(f"Image config: {json.dumps(image_config)}") + else: + body = {"contents": [{"parts": [{"text": prompt}]}]} + + log.debug(f"Request body size: {len(json.dumps(body))} bytes") + # Log body without the full prompt (can be very long) + body_preview = json.dumps(body) + if len(body_preview) > 500: + log.debug(f"Request body (truncated): {body_preview[:500]}...") + else: + log.debug(f"Request body: {body_preview}") + + return body + + +def make_request( + url: str, + headers: dict[str, str], + body: dict[str, Any], + timeout: int = 120, +) -> dict[str, Any]: + """Make HTTP POST request and return parsed JSON response. + + Args: + url: Full API endpoint URL. + headers: HTTP headers dict. + body: Request body dict (will be JSON-serialized). + timeout: Request timeout in seconds (default: 120). + + Returns: + Parsed JSON response as a dict. + + Raises: + RuntimeError: On HTTP errors, connection errors, or timeouts. + """ + data = json.dumps(body).encode("utf-8") + req = urllib.request.Request(url, data=data, headers=headers, method="POST") + + log.debug(f"Sending POST to {url} ({len(data)} bytes, timeout={timeout}s)") + start_time = time.time() + + try: + with urllib.request.urlopen(req, timeout=timeout) as resp: + elapsed = time.time() - start_time + response_data = resp.read().decode("utf-8") + log.info(f"Response received: HTTP {resp.status} in {elapsed:.1f}s ({len(response_data)} bytes)") + log.debug(f"Response headers: {dict(resp.headers)}") + + parsed = json.loads(response_data) + + # Log response structure (without huge base64 data) + log.debug(f"Response top-level keys: {list(parsed.keys())}") + if "choices" in parsed: + for i, choice in enumerate(parsed["choices"]): + msg = choice.get("message", {}) + log.debug(f" choices[{i}].message keys: {list(msg.keys())}") + if "images" in msg: + log.debug(f" choices[{i}].message.images count: {len(msg['images'])}") + if "content" in msg: + log.debug(f" choices[{i}].message.content: {str(msg['content'])[:200]}") + if "candidates" in parsed: + for i, cand in enumerate(parsed["candidates"]): + parts = cand.get("content", {}).get("parts", []) + log.debug(f" candidates[{i}].content.parts count: {len(parts)}") + for j, part in enumerate(parts): + ptype = "inlineData" if "inlineData" in part else "text" if "text" in part else "unknown" + if ptype == "inlineData": + mime = part["inlineData"].get("mimeType", "?") + dlen = len(part["inlineData"].get("data", "")) + log.debug(f" part[{j}]: inlineData ({mime}, {dlen} base64 chars)") + elif ptype == "text": + log.debug(f" part[{j}]: text ({len(part['text'])} chars): {part['text'][:100]}") + + return parsed + except urllib.error.HTTPError as e: + elapsed = time.time() - start_time + error_body = "" + try: + error_body = e.read().decode("utf-8") + except Exception: + pass + log.debug(f"HTTP error after {elapsed:.1f}s: {e.code} {e.reason}") + log.debug(f"Error response headers: {dict(e.headers) if hasattr(e, 'headers') else 'N/A'}") + log.debug(f"Error response body: {error_body[:1000]}") + raise RuntimeError( + f"HTTP {e.code}: {e.reason}\n{error_body}" + ) from e + except urllib.error.URLError as e: + elapsed = time.time() - start_time + log.debug(f"URL error after {elapsed:.1f}s: {e.reason}") + raise RuntimeError(f"Connection error: {e.reason}") from e + except TimeoutError: + elapsed = time.time() - start_time + log.debug(f"Request timed out after {elapsed:.1f}s (limit: {timeout}s)") + raise RuntimeError(f"Request timed out after {timeout}s") + + +def extract_image_openrouter(response: dict) -> tuple[bytes, str]: + """Extract base64 image data from OpenRouter response. + + Args: + response: Parsed JSON response from OpenRouter API. + + Returns: + Tuple of (image_bytes, text_content) where image_bytes is the decoded + PNG data and text_content is any accompanying model text. + + Raises: + RuntimeError: If no image data found in response. + """ + choices = response.get("choices", []) + if not choices: + error = response.get("error", {}) + if error: + msg = error.get("message", str(error)) + raise RuntimeError(f"API error: {msg}") + raise RuntimeError(f"No choices in response: {json.dumps(response)[:500]}") + + message = choices[0].get("message", {}) + text_content = message.get("content", "") + images = message.get("images", []) + + if not images: + raise RuntimeError( + f"No images in response. Model text: {text_content or '(empty)'}" + ) + + data_url = images[0]["image_url"]["url"] + log.debug(f"Image data URL prefix: {data_url[:60]}...") + log.debug(f"Image data URL total length: {len(data_url)} chars") + + # Strip data URL prefix: "data:image/png;base64,..." + if "," in data_url: + b64_data = data_url.split(",", 1)[1] + else: + b64_data = data_url + + image_bytes = base64.b64decode(b64_data) + log.info(f"Decoded image: {len(image_bytes)} bytes ({len(b64_data)} base64 chars)") + return image_bytes, text_content + + +def extract_image_google(response: dict) -> tuple[bytes, str]: + """Extract base64 image data from Google AI Studio response. + + Args: + response: Parsed JSON response from Google generateContent API. + + Returns: + Tuple of (image_bytes, text_content) where image_bytes is the decoded + PNG data and text_content is any accompanying model text. + + Raises: + RuntimeError: If no image data found or prompt was blocked by safety filter. + """ + candidates = response.get("candidates", []) + if not candidates: + block_reason = response.get("promptFeedback", {}).get("blockReason", "") + if block_reason: + raise RuntimeError(f"Prompt blocked by safety filter: {block_reason}") + raise RuntimeError(f"No candidates in response: {json.dumps(response)[:500]}") + + parts = candidates[0].get("content", {}).get("parts", []) + if not parts: + raise RuntimeError("No parts in response candidate") + + image_bytes = None + text_content = "" + + for i, part in enumerate(parts): + if "inlineData" in part: + b64_data = part["inlineData"]["data"] + mime_type = part["inlineData"].get("mimeType", "unknown") + log.debug(f"Found inlineData in part[{i}]: {mime_type}, {len(b64_data)} base64 chars") + image_bytes = base64.b64decode(b64_data) + log.info(f"Decoded image: {len(image_bytes)} bytes") + elif "text" in part: + text_content = part["text"] + log.debug(f"Found text in part[{i}]: {text_content[:200]}") + + if image_bytes is None: + raise RuntimeError( + f"No image data in response parts. Text: {text_content or '(empty)'}" + ) + + return image_bytes, text_content + + +def main() -> None: + """Main entry point — parse args, generate image, write output.""" + args = parse_args() + + # Configure logging + setup_logging(debug=args.debug, verbose=args.verbose) + + log.debug("=" * 60) + log.debug("AI Image Creator — Debug Session") + log.debug(f"Python: {sys.version}") + log.debug(f"Script: {__file__}") + log.debug(f"CWD: {os.getcwd()}") + log.debug(f"Args: {vars(args)}") + log.debug("=" * 60) + + # Validate output path + output_path = Path(args.output) + if output_path.suffix.lower() not in (".png", ".jpg", ".jpeg", ".webp"): + print( + "WARNING: Output file does not have an image extension. " + "The generated file will be PNG format regardless of extension.", + file=sys.stderr, + ) + + # Resolve model + model = args.model or DEFAULT_MODELS[args.provider] + + # Resolve prompt + prompt = resolve_prompt(args) + print(f"Provider: {args.provider}", file=sys.stderr) + print(f"Model: {model}", file=sys.stderr) + print(f"Prompt: {prompt[:100]}{'...' if len(prompt) > 100 else ''}", file=sys.stderr) + if args.aspect_ratio: + print(f"Aspect ratio: {args.aspect_ratio}", file=sys.stderr) + if args.image_size: + print(f"Image size: {args.image_size}", file=sys.stderr) + + # Detect mode + mode, config = detect_mode(args.provider) + print(f"Mode: {mode}", file=sys.stderr) + + # Build request + if mode == "gateway": + url = build_gateway_url(args.provider, model, config) + else: + url = build_direct_url(args.provider, model) + + headers = build_headers(args.provider, mode, config) + body = build_request_body( + args.provider, model, prompt, args.aspect_ratio, args.image_size + ) + + print(f"URL: {url}", file=sys.stderr) + print("Generating image (this may take up to 2 minutes)...", file=sys.stderr) + + # Make request with fallback + total_start = time.time() + response = None + try: + response = make_request(url, headers, body) + except RuntimeError as e: + if mode == "gateway" and config.get("direct_key"): + print( + f"Gateway request failed: {e}\nFalling back to direct API...", + file=sys.stderr, + ) + log.info("Initiating fallback to direct API") + url = build_direct_url(args.provider, model) + headers = build_headers(args.provider, "direct", config) + try: + response = make_request(url, headers, body) + except RuntimeError as e2: + print(f"ERROR: Direct API also failed: {e2}", file=sys.stderr) + log.debug(f"Both gateway and direct failed. Total time: {time.time() - total_start:.1f}s") + sys.exit(1) + else: + print(f"ERROR: {e}", file=sys.stderr) + log.debug(f"Request failed. Total time: {time.time() - total_start:.1f}s") + sys.exit(1) + + # Extract image + try: + if args.provider == "openrouter": + image_bytes, text_content = extract_image_openrouter(response) + else: + image_bytes, text_content = extract_image_google(response) + except RuntimeError as e: + print(f"ERROR: {e}", file=sys.stderr) + log.debug(f"Image extraction failed. Raw response keys: {list(response.keys()) if response else 'None'}") + sys.exit(1) + + # Write output + output_path.parent.mkdir(parents=True, exist_ok=True) + output_path.write_bytes(image_bytes) + + total_elapsed = time.time() - total_start + + # Report success + size_kb = len(image_bytes) / 1024 + print(f"\nImage saved: {output_path} ({size_kb:.1f} KB)", file=sys.stderr) + if text_content: + print(f"Model notes: {text_content}", file=sys.stderr) + log.info(f"Total elapsed: {total_elapsed:.1f}s") + log.debug(f"Output file: {output_path.resolve()}") + log.debug(f"File size: {len(image_bytes)} bytes ({size_kb:.1f} KB)") + + # Print machine-readable output to stdout + result = { + "ok": True, + "output": str(output_path), + "size_bytes": len(image_bytes), + "provider": args.provider, + "model": model, + "mode": mode, + "elapsed_seconds": round(total_elapsed, 1), + } + log.debug(f"Result JSON: {json.dumps(result, indent=2)}") + print(json.dumps(result)) + + +if __name__ == "__main__": + main() diff --git a/.claude/skills/ai-image-creator/tmp/.gitkeep b/.claude/skills/ai-image-creator/tmp/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/README-v2.md b/README-v2.md index 06e57d3..094144d 100644 --- a/README-v2.md +++ b/README-v2.md @@ -775,6 +775,7 @@ Skills provide specialized capabilities. See [Agent Skills documentation](https: | **claude-docs-consultant** | Selectively fetches official Claude Code documentation from docs.claude.com | Automatic when working on Claude Code features | | **consult-zai** | Dual-AI consultation comparing z.ai GLM 4.7 and code-searcher | `/consult-zai "question"` or via Skill tool | | **consult-codex** | Dual-AI consultation comparing Codex GPT-5.2 and code-searcher | `/consult-codex "question"` or via Skill tool | +| **ai-image-creator** | Generate PNG images using AI (Gemini 3.1 Flash via OpenRouter/Google/Cloudflare AI Gateway). Requires [setup](.claude/skills/ai-image-creator/references/setup-guide.md) | `/ai-image-creator` or via Skill tool | ### 5.3 Custom Slash Commands diff --git a/README-v3.md b/README-v3.md index 6bed18c..89f66a0 100644 --- a/README-v3.md +++ b/README-v3.md @@ -520,6 +520,7 @@ Skills provide specialized capabilities. See [official docs](https://docs.claude | **claude-docs-consultant** | Selectively fetches official Claude Code documentation | | **consult-zai** | Dual-AI consultation comparing z.ai GLM 4.7 and code-searcher responses | | **consult-codex** | Dual-AI consultation comparing Codex GPT-5.2 and code-searcher responses | +| **ai-image-creator** | Generate PNG images using AI with configurable aspect ratios and resolutions. Requires [setup](.claude/skills/ai-image-creator/references/setup-guide.md) | ### Custom Subagents diff --git a/README-v4.md b/README-v4.md index aa571ff..db62d83 100644 --- a/README-v4.md +++ b/README-v4.md @@ -770,6 +770,7 @@ Skills are defined in `.claude/skills/` directories containing: | claude-docs-consultant | Fetch official Claude Code documentation | Automatic when working on Claude Code features | `.claude/skills/claude-docs-consultant/` | | consult-zai | Dual-AI consultation: z.ai GLM 4.7 vs code-searcher | `/consult-zai "question"` or via Skill tool | `.claude/skills/consult-zai/` | | consult-codex | Dual-AI consultation: Codex GPT-5.2 vs code-searcher | `/consult-codex "question"` or via Skill tool | `.claude/skills/consult-codex/` | +| ai-image-creator | Generate PNG images using AI (Gemini 3.1 Flash) | `/ai-image-creator` or via Skill tool | `.claude/skills/ai-image-creator/` | #### claude-docs-consultant @@ -805,6 +806,26 @@ Skills are defined in `.claude/skills/` directories containing: **Usage**: `/consult-codex "your code analysis question"` or invoke via Skill tool. +#### ai-image-creator + +**Purpose**: Generate PNG images using AI (Google Gemini 3.1 Flash via OpenRouter or Google AI Studio, proxied through Cloudflare AI Gateway BYOK). + +**Setup**: Requires API credentials and optional Cloudflare AI Gateway configuration before use. See [setup guide](.claude/skills/ai-image-creator/references/setup-guide.md). + +**Providers**: +- OpenRouter (recommended, pay-as-you-go) +- Google AI Studio (requires billing for image generation) +- Cloudflare AI Gateway BYOK (secure proxy, stores provider keys server-side) + +**Features**: +- Configurable aspect ratios: 1:1, 16:9, 9:16, 3:2, 2:3, 4:3, 3:4, 4:5, 5:4, 21:9, 1:4, 4:1 +- Image sizes: 0.5K, 1K (default), 2K, 4K +- Automatic fallback from gateway to direct API +- Post-processing with ImageMagick, sips (macOS), or ffmpeg +- Pure Python (no pip dependencies), requires `uv` runner + +**Usage**: `/ai-image-creator` or invoke via Skill tool when user asks to generate images, create PNGs, or make visual assets. + --- ## Chapter 11: Hooks diff --git a/README.md b/README.md index 583b24e..8f6ada6 100644 --- a/README.md +++ b/README.md @@ -883,6 +883,19 @@ Claude Code now supports [Agent Skills](https://docs.claude.com/en/docs/claude-c * Synthesized summary combining best insights from both AI sources * **Usage**: `/consult-codex "your code analysis question"` or invoke via Skill tool +### ai-image-creator + +* **Purpose**: Generate PNG images using AI (Google Gemini 3.1 Flash via OpenRouter or Google AI Studio, proxied through Cloudflare AI Gateway BYOK) +* **Location**: `.claude/skills/ai-image-creator/` +* **Key Features**: + * Supports configurable aspect ratios (1:1, 16:9, 9:16, 3:2, 4:3, etc.) and image sizes (0.5K to 4K) + * Multiple providers: OpenRouter (recommended), Google AI Studio, Cloudflare AI Gateway BYOK + * Automatic fallback from gateway to direct API + * Post-processing support with ImageMagick, sips (macOS), or ffmpeg + * Pure Python script with no pip dependencies (requires `uv` runner) +* **Setup**: Requires API credentials and optional Cloudflare AI Gateway configuration. See [setup guide](.claude/skills/ai-image-creator/references/setup-guide.md) for detailed instructions +* **Usage**: `/ai-image-creator` or invoke via Skill tool when user asks to generate images, create PNGs, or make visual assets + ## Claude Code Hooks The Claude Code hook is for `STOP` which uses Terminal-Notifier to show macOS desktop notifications whenever Claude Code stops and finishes it's response https://github.com/centminmod/terminal-notifier-setup. From ee0d07b3ce10393220a3804083c7aae914009624 Mon Sep 17 00:00:00 2001 From: George Liu Date: Thu, 26 Mar 2026 01:51:53 +1000 Subject: [PATCH 096/174] update ai-image-creator README docs for multi-model support Skill now supports 5 models via OpenRouter (Gemini, FLUX.2, Riverflow, SeedDream, GPT-5 Image) with --model keyword selection. Updated all 4 README variants to reflect this change. --- README-v2.md | 2 +- README-v3.md | 2 +- README-v4.md | 15 +++++++++++++-- README.md | 3 ++- 4 files changed, 17 insertions(+), 5 deletions(-) diff --git a/README-v2.md b/README-v2.md index 094144d..9028770 100644 --- a/README-v2.md +++ b/README-v2.md @@ -775,7 +775,7 @@ Skills provide specialized capabilities. See [Agent Skills documentation](https: | **claude-docs-consultant** | Selectively fetches official Claude Code documentation from docs.claude.com | Automatic when working on Claude Code features | | **consult-zai** | Dual-AI consultation comparing z.ai GLM 4.7 and code-searcher | `/consult-zai "question"` or via Skill tool | | **consult-codex** | Dual-AI consultation comparing Codex GPT-5.2 and code-searcher | `/consult-codex "question"` or via Skill tool | -| **ai-image-creator** | Generate PNG images using AI (Gemini 3.1 Flash via OpenRouter/Google/Cloudflare AI Gateway). Requires [setup](.claude/skills/ai-image-creator/references/setup-guide.md) | `/ai-image-creator` or via Skill tool | +| **ai-image-creator** | Generate PNG images using AI (multiple models including Gemini, FLUX.2, Riverflow, SeedDream, GPT-5 via OpenRouter/Cloudflare AI Gateway). Requires [setup](.claude/skills/ai-image-creator/references/setup-guide.md) | `/ai-image-creator` or via Skill tool | ### 5.3 Custom Slash Commands diff --git a/README-v3.md b/README-v3.md index 89f66a0..218fb98 100644 --- a/README-v3.md +++ b/README-v3.md @@ -520,7 +520,7 @@ Skills provide specialized capabilities. See [official docs](https://docs.claude | **claude-docs-consultant** | Selectively fetches official Claude Code documentation | | **consult-zai** | Dual-AI consultation comparing z.ai GLM 4.7 and code-searcher responses | | **consult-codex** | Dual-AI consultation comparing Codex GPT-5.2 and code-searcher responses | -| **ai-image-creator** | Generate PNG images using AI with configurable aspect ratios and resolutions. Requires [setup](.claude/skills/ai-image-creator/references/setup-guide.md) | +| **ai-image-creator** | Generate PNG images using AI (Gemini, FLUX.2, Riverflow, SeedDream, GPT-5) with configurable aspect ratios and resolutions. Requires [setup](.claude/skills/ai-image-creator/references/setup-guide.md) | ### Custom Subagents diff --git a/README-v4.md b/README-v4.md index db62d83..2d4c47c 100644 --- a/README-v4.md +++ b/README-v4.md @@ -770,7 +770,7 @@ Skills are defined in `.claude/skills/` directories containing: | claude-docs-consultant | Fetch official Claude Code documentation | Automatic when working on Claude Code features | `.claude/skills/claude-docs-consultant/` | | consult-zai | Dual-AI consultation: z.ai GLM 4.7 vs code-searcher | `/consult-zai "question"` or via Skill tool | `.claude/skills/consult-zai/` | | consult-codex | Dual-AI consultation: Codex GPT-5.2 vs code-searcher | `/consult-codex "question"` or via Skill tool | `.claude/skills/consult-codex/` | -| ai-image-creator | Generate PNG images using AI (Gemini 3.1 Flash) | `/ai-image-creator` or via Skill tool | `.claude/skills/ai-image-creator/` | +| ai-image-creator | Generate PNG images using AI (multiple models via OpenRouter) | `/ai-image-creator` or via Skill tool | `.claude/skills/ai-image-creator/` | #### claude-docs-consultant @@ -808,16 +808,27 @@ Skills are defined in `.claude/skills/` directories containing: #### ai-image-creator -**Purpose**: Generate PNG images using AI (Google Gemini 3.1 Flash via OpenRouter or Google AI Studio, proxied through Cloudflare AI Gateway BYOK). +**Purpose**: Generate PNG images using AI (multiple models via OpenRouter including Gemini, FLUX.2, Riverflow, SeedDream, GPT-5 Image, proxied through Cloudflare AI Gateway BYOK). **Setup**: Requires API credentials and optional Cloudflare AI Gateway configuration before use. See [setup guide](.claude/skills/ai-image-creator/references/setup-guide.md). +**Models** (selectable via `--model` keyword): + +| Keyword | Model | +|---------|-------| +| `gemini` | Google Gemini 3.1 Flash (default) | +| `riverflow` | Sourceful Riverflow v2 Fast | +| `flux2` | FLUX.2 Klein 4B | +| `seedream` | ByteDance SeedDream 4.5 | +| `gpt5` | OpenAI GPT-5 Image Mini | + **Providers**: - OpenRouter (recommended, pay-as-you-go) - Google AI Studio (requires billing for image generation) - Cloudflare AI Gateway BYOK (secure proxy, stores provider keys server-side) **Features**: +- Model selection via `--model` keyword - Configurable aspect ratios: 1:1, 16:9, 9:16, 3:2, 2:3, 4:3, 3:4, 4:5, 5:4, 21:9, 1:4, 4:1 - Image sizes: 0.5K, 1K (default), 2K, 4K - Automatic fallback from gateway to direct API diff --git a/README.md b/README.md index 8f6ada6..8b4832b 100644 --- a/README.md +++ b/README.md @@ -885,9 +885,10 @@ Claude Code now supports [Agent Skills](https://docs.claude.com/en/docs/claude-c ### ai-image-creator -* **Purpose**: Generate PNG images using AI (Google Gemini 3.1 Flash via OpenRouter or Google AI Studio, proxied through Cloudflare AI Gateway BYOK) +* **Purpose**: Generate PNG images using AI (multiple models via OpenRouter including Gemini, FLUX.2, Riverflow, SeedDream, GPT-5 Image, proxied through Cloudflare AI Gateway BYOK) * **Location**: `.claude/skills/ai-image-creator/` * **Key Features**: + * Model selection via keywords: gemini (default), riverflow, flux2, seedream, gpt5 * Supports configurable aspect ratios (1:1, 16:9, 9:16, 3:2, 4:3, etc.) and image sizes (0.5K to 4K) * Multiple providers: OpenRouter (recommended), Google AI Studio, Cloudflare AI Gateway BYOK * Automatic fallback from gateway to direct API From fa710b33eeabb2c84676be57c94fc6163d0c4a73 Mon Sep 17 00:00:00 2001 From: George Liu Date: Thu, 26 Mar 2026 01:54:35 +1000 Subject: [PATCH 097/174] update ai-image-creator skill for multi-model support --- .claude/skills/ai-image-creator/SKILL.md | 31 ++++- .../references/api-reference.md | 16 +++ .../scripts/generate-image.py | 130 ++++++++++++++++-- 3 files changed, 161 insertions(+), 16 deletions(-) diff --git a/.claude/skills/ai-image-creator/SKILL.md b/.claude/skills/ai-image-creator/SKILL.md index 0a1fb13..9c91375 100644 --- a/.claude/skills/ai-image-creator/SKILL.md +++ b/.claude/skills/ai-image-creator/SKILL.md @@ -1,15 +1,27 @@ --- name: ai-image-creator -description: Generate PNG images using AI (Google Gemini 3.1 Flash via OpenRouter or Google AI Studio, proxied through Cloudflare AI Gateway BYOK). Use when user asks to "generate an image", "create a PNG", "make an icon", or needs AI-generated visual assets for the project. Supports configurable aspect ratios and resolutions. +description: Generate PNG images using AI (multiple models via OpenRouter including Gemini, FLUX.2, Riverflow, SeedDream, GPT-5 Image, proxied through Cloudflare AI Gateway BYOK). Use when user asks to "generate an image", "create a PNG", "make an icon", or needs AI-generated visual assets for the project. Supports model selection via keywords (gemini, riverflow, flux2, seedream, gpt5), configurable aspect ratios and resolutions. allowed-tools: Bash, Read, Write compatibility: Requires uv (Python runner) and network access. Environment variables for CF AI Gateway or direct API keys must be configured in shell profile (~/.zshrc on macOS, ~/.bashrc on Linux, or System Environment Variables on Windows). metadata: - tags: image-generation, ai, openrouter, cloudflare, gemini + tags: image-generation, ai, openrouter, cloudflare, gemini, flux2, riverflow, seedream, gpt5 --- # AI Image Creator -Generate PNG images via Google Gemini 3.1 Flash, routed through Cloudflare AI Gateway BYOK or directly via OpenRouter/Google AI Studio. +Generate PNG images via multiple AI models, routed through Cloudflare AI Gateway BYOK or directly via OpenRouter/Google AI Studio. + +## Model Selection + +When the user mentions a model keyword in their image request, use the corresponding `--model` flag: + +| Keyword | Model | Use When User Says | +|---------|-------|--------------------| +| `gemini` | [Google Gemini 3.1 Flash](https://openrouter.ai/google/gemini-3.1-flash-image-preview) (default) | "gemini", "generate an image" (no model specified) | +| `riverflow` | [Sourceful Riverflow v2 Fast](https://openrouter.ai/sourceful/riverflow-v2-fast) | "riverflow", "use riverflow" | +| `flux2` | [FLUX.2 Klein 4B](https://openrouter.ai/black-forest-labs/flux.2-klein-4b) | "flux2", "flux", "use flux" | +| `seedream` | [ByteDance SeedDream 4.5](https://openrouter.ai/bytedance-seed/seedream-4.5) | "seedream", "use seedream" | +| `gpt5` | [OpenAI GPT-5 Image Mini](https://openrouter.ai/openai/gpt-5-image-mini) | "gpt5", "gpt5 image", "use gpt5" | ## Instructions @@ -42,7 +54,15 @@ uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py \ [--model "model-id"] ``` -Or with inline prompt: +With a specific model: +```bash +uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py \ + --output "OUTPUT_PATH" \ + --model riverflow \ + --prompt "A serene mountain lake at sunset" +``` + +Or with inline prompt (default model): ```bash uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py \ --output "OUTPUT_PATH" \ @@ -77,7 +97,8 @@ If the user needs resizing, format conversion, or other manipulation, first dete | `--provider` | No | `openrouter` | `openrouter` or `google` | | `--aspect-ratio` | No | model default | OpenRouter only: `1:1`, `16:9`, `9:16`, `3:2`, `2:3`, `4:3`, `3:4`, `4:5`, `5:4`, `21:9` | | `--image-size` | No | model default | OpenRouter only: `0.5K`, `1K`, `2K`, `4K` | -| `--model` | No | auto per provider | Override model ID | +| `--model` | No | `gemini` | Model keyword (`gemini`, `riverflow`, `flux2`, `seedream`, `gpt5`) or full OpenRouter model ID | +| `--list-models` | No | -- | List available model keywords and exit | ## Environment Variables diff --git a/.claude/skills/ai-image-creator/references/api-reference.md b/.claude/skills/ai-image-creator/references/api-reference.md index 5553e4a..5b879a4 100644 --- a/.claude/skills/ai-image-creator/references/api-reference.md +++ b/.claude/skills/ai-image-creator/references/api-reference.md @@ -1,5 +1,21 @@ # API Reference — AI Image Creator +## Supported Models (OpenRouter) + +All models use the same OpenRouter `/v1/chat/completions` endpoint and response format. The `modalities` value differs by model type. + +| Keyword | Model ID | Modalities | Type | +|---------|----------|------------|------| +| `gemini` | [`google/gemini-3.1-flash-image-preview`](https://openrouter.ai/google/gemini-3.1-flash-image-preview) | `["image", "text"]` | Multimodal (default) | +| `riverflow` | [`sourceful/riverflow-v2-fast`](https://openrouter.ai/sourceful/riverflow-v2-fast) | `["image"]` | Image-only | +| `flux2` | [`black-forest-labs/flux.2-klein-4b`](https://openrouter.ai/black-forest-labs/flux.2-klein-4b) | `["image"]` | Image-only | +| `seedream` | [`bytedance-seed/seedream-4.5`](https://openrouter.ai/bytedance-seed/seedream-4.5) | `["image"]` | Image-only | +| `gpt5` | [`openai/gpt-5-image-mini`](https://openrouter.ai/openai/gpt-5-image-mini) | `["image", "text"]` | Multimodal | + +**Important:** Image-only models MUST use `"modalities": ["image"]`. Using `["image", "text"]` may cause errors with these models. The script handles this automatically when using keywords. + +--- + ## Providers & Endpoints ### OpenRouter (via CF AI Gateway) diff --git a/.claude/skills/ai-image-creator/scripts/generate-image.py b/.claude/skills/ai-image-creator/scripts/generate-image.py index 81a8722..fe4647a 100644 --- a/.claude/skills/ai-image-creator/scripts/generate-image.py +++ b/.claude/skills/ai-image-creator/scripts/generate-image.py @@ -1,13 +1,21 @@ #!/usr/bin/env python3 -"""AI Image Generator — Generate PNG images via OpenRouter or Google AI Studio. +"""AI Image Generator — Generate PNG images via multiple OpenRouter models or Google AI Studio. + +Supports multiple image generation models via keyword shortcuts: + gemini — Google Gemini 3.1 Flash (default, multimodal) + riverflow — Sourceful Riverflow v2 Fast (image-only) + flux2 — Black Forest Labs FLUX.2 Klein 4B (image-only) + seedream — ByteDance SeedDream 4.5 (image-only) + gpt5 — OpenAI GPT-5 Image Mini (multimodal) Routes through Cloudflare AI Gateway BYOK when configured, with automatic fallback to direct API calls. Uses only Python stdlib (no pip dependencies). Usage: uv run python generate-image.py --output path.png --prompt "description" + uv run python generate-image.py --output path.png --model riverflow --prompt "description" uv run python generate-image.py --output path.png --prompt-file prompt.txt - uv run python generate-image.py --output path.png --prompt "test" --debug + uv run python generate-image.py --list-models """ from __future__ import annotations @@ -30,6 +38,37 @@ "google": "gemini-3.1-flash-image-preview", } +# Model registry — maps keyword shortcuts to model metadata. +# All models use the OpenRouter /v1/chat/completions endpoint. +# Image-only models use modalities: ["image"], multimodal use ["image", "text"]. +MODEL_REGISTRY: dict[str, dict[str, Any]] = { + "gemini": { + "id": "google/gemini-3.1-flash-image-preview", + "modalities": ["image", "text"], + "description": "Google Gemini 3.1 Flash — multimodal (text+image), default", + }, + "riverflow": { + "id": "sourceful/riverflow-v2-fast", + "modalities": ["image"], + "description": "Sourceful Riverflow v2 Fast — image-only, low latency", + }, + "flux2": { + "id": "black-forest-labs/flux.2-klein-4b", + "modalities": ["image"], + "description": "Black Forest Labs FLUX.2 Klein 4B — image-only, fast", + }, + "seedream": { + "id": "bytedance-seed/seedream-4.5", + "modalities": ["image"], + "description": "ByteDance SeedDream 4.5 — image-only, high quality", + }, + "gpt5": { + "id": "openai/gpt-5-image-mini", + "modalities": ["image", "text"], + "description": "OpenAI GPT-5 Image Mini — multimodal (text+image)", + }, +} + # Environment variable names (prefixed to avoid collisions) ENV_CF_ACCOUNT_ID = "AI_IMG_CREATOR_CF_ACCOUNT_ID" ENV_CF_GATEWAY_ID = "AI_IMG_CREATOR_CF_GATEWAY_ID" @@ -56,18 +95,61 @@ def mask_key(key: str, visible: int = 4) -> str: return f"***{key[-visible:]}" +def resolve_model(model_arg: str | None, provider: str) -> tuple[str, list[str]]: + """Resolve a model keyword or full ID to (model_id, modalities). + + Supports three modes: + 1. No --model flag: returns the default model for the provider (gemini). + 2. Keyword match (e.g. 'riverflow'): looks up MODEL_REGISTRY. + 3. Full model ID (e.g. 'sourceful/riverflow-v2-fast'): reverse-lookups + registry for modalities, or defaults to ["image", "text"] if unknown. + + Args: + model_arg: The --model CLI value (keyword, full model ID, or None). + provider: Either 'openrouter' or 'google'. + + Returns: + Tuple of (model_id, modalities_list) where model_id is the full + OpenRouter model identifier and modalities_list is the correct + modalities array for the API request. + """ + if model_arg is None: + model_id = DEFAULT_MODELS[provider] + if provider == "openrouter": + entry = MODEL_REGISTRY.get("gemini", {}) + return model_id, entry.get("modalities", ["image", "text"]) + return model_id, ["image", "text"] + + # Check keyword match (case-insensitive) + keyword = model_arg.lower().strip() + if keyword in MODEL_REGISTRY: + entry = MODEL_REGISTRY[keyword] + log.info(f"Resolved keyword '{keyword}' -> {entry['id']}") + return entry["id"], entry["modalities"] + + # Full model ID — try reverse lookup in registry for modalities + for _kw, entry in MODEL_REGISTRY.items(): + if entry["id"] == model_arg: + log.info(f"Matched full model ID to registry entry '{_kw}'") + return model_arg, entry["modalities"] + + # Unknown full model ID — default to multimodal (safest) + log.info(f"Unknown model ID '{model_arg}', defaulting to multimodal modalities") + return model_arg, ["image", "text"] + + def parse_args() -> argparse.Namespace: """Parse command-line arguments. Returns: Namespace with output, prompt, prompt_file, provider, aspect_ratio, - image_size, model, debug, and verbose attributes. + image_size, model, list_models, debug, and verbose attributes. """ parser = argparse.ArgumentParser( - description="Generate PNG images using AI (Gemini via OpenRouter/Google AI Studio)" + description="Generate PNG images using AI (multiple models via OpenRouter/Google AI Studio)" ) parser.add_argument( - "--output", required=True, help="Output PNG file path" + "--output", required=False, default=None, help="Output PNG file path (required unless --list-models)" ) parser.add_argument( "--prompt", default=None, help="Inline prompt text (alternative to --prompt-file)" @@ -96,7 +178,12 @@ def parse_args() -> argparse.Namespace: parser.add_argument( "--model", default=None, - help="Model ID (default: auto per provider)", + help="Model keyword (gemini, riverflow, flux2, seedream, gpt5) or full model ID", + ) + parser.add_argument( + "--list-models", + action="store_true", + help="List available model keywords and exit", ) parser.add_argument( "--debug", @@ -318,6 +405,7 @@ def build_request_body( prompt: str, aspect_ratio: str | None = None, image_size: str | None = None, + modalities: list[str] | None = None, ) -> dict[str, Any]: """Build JSON request body for the given provider. @@ -327,6 +415,9 @@ def build_request_body( prompt: The image generation prompt text. aspect_ratio: Optional aspect ratio (OpenRouter only), e.g. '16:9'. image_size: Optional image size (OpenRouter only), e.g. '2K'. + modalities: Output modalities list, e.g. ['image'] for image-only models + or ['image', 'text'] for multimodal models. Defaults to ['image', 'text'] + if not specified. Only used for OpenRouter provider. Returns: Dict suitable for JSON serialization as request body. @@ -335,7 +426,7 @@ def build_request_body( body = { "model": model, "messages": [{"role": "user", "content": prompt}], - "modalities": ["image", "text"], + "modalities": modalities or ["image", "text"], } image_config = {} if aspect_ratio: @@ -363,7 +454,7 @@ def make_request( url: str, headers: dict[str, str], body: dict[str, Any], - timeout: int = 120, + timeout: int = 300, ) -> dict[str, Any]: """Make HTTP POST request and return parsed JSON response. @@ -547,6 +638,21 @@ def main() -> None: log.debug(f"Args: {vars(args)}") log.debug("=" * 60) + # Handle --list-models + if args.list_models: + print("Available model keywords:") + for kw, info in MODEL_REGISTRY.items(): + default = " (default)" if info["id"] == DEFAULT_MODELS.get("openrouter") else "" + print(f" {kw:12s} -> {info['id']}{default}") + print(f" {info['description']}") + print(f" modalities: {', '.join(info['modalities'])}") + sys.exit(0) + + # Validate --output is provided (required unless --list-models) + if not args.output: + print("ERROR: --output is required (unless using --list-models)", file=sys.stderr) + sys.exit(1) + # Validate output path output_path = Path(args.output) if output_path.suffix.lower() not in (".png", ".jpg", ".jpeg", ".webp"): @@ -556,13 +662,14 @@ def main() -> None: file=sys.stderr, ) - # Resolve model - model = args.model or DEFAULT_MODELS[args.provider] + # Resolve model and modalities + model, modalities = resolve_model(args.model, args.provider) # Resolve prompt prompt = resolve_prompt(args) print(f"Provider: {args.provider}", file=sys.stderr) print(f"Model: {model}", file=sys.stderr) + print(f"Modalities: {', '.join(modalities)}", file=sys.stderr) print(f"Prompt: {prompt[:100]}{'...' if len(prompt) > 100 else ''}", file=sys.stderr) if args.aspect_ratio: print(f"Aspect ratio: {args.aspect_ratio}", file=sys.stderr) @@ -581,7 +688,8 @@ def main() -> None: headers = build_headers(args.provider, mode, config) body = build_request_body( - args.provider, model, prompt, args.aspect_ratio, args.image_size + args.provider, model, prompt, args.aspect_ratio, args.image_size, + modalities=modalities, ) print(f"URL: {url}", file=sys.stderr) From 12995bf02a6c08b4b6ee4eb098b4f8c3297f55d7 Mon Sep 17 00:00:00 2001 From: George Liu Date: Thu, 26 Mar 2026 04:23:57 +1000 Subject: [PATCH 098/174] update ai-image-creator skill models --- .claude/skills/ai-image-creator/SKILL.md | 6 +++--- .../ai-image-creator/references/api-reference.md | 6 +++--- .../ai-image-creator/scripts/generate-image.py | 14 +++++++------- 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/.claude/skills/ai-image-creator/SKILL.md b/.claude/skills/ai-image-creator/SKILL.md index 9c91375..81c2127 100644 --- a/.claude/skills/ai-image-creator/SKILL.md +++ b/.claude/skills/ai-image-creator/SKILL.md @@ -18,10 +18,10 @@ When the user mentions a model keyword in their image request, use the correspon | Keyword | Model | Use When User Says | |---------|-------|--------------------| | `gemini` | [Google Gemini 3.1 Flash](https://openrouter.ai/google/gemini-3.1-flash-image-preview) (default) | "gemini", "generate an image" (no model specified) | -| `riverflow` | [Sourceful Riverflow v2 Fast](https://openrouter.ai/sourceful/riverflow-v2-fast) | "riverflow", "use riverflow" | -| `flux2` | [FLUX.2 Klein 4B](https://openrouter.ai/black-forest-labs/flux.2-klein-4b) | "flux2", "flux", "use flux" | +| `riverflow` | [Sourceful Riverflow v2 Pro](https://openrouter.ai/sourceful/riverflow-v2-pro) | "riverflow", "use riverflow" | +| `flux2` | [FLUX.2 Max](https://openrouter.ai/black-forest-labs/flux.2-max) | "flux2", "flux", "use flux" | | `seedream` | [ByteDance SeedDream 4.5](https://openrouter.ai/bytedance-seed/seedream-4.5) | "seedream", "use seedream" | -| `gpt5` | [OpenAI GPT-5 Image Mini](https://openrouter.ai/openai/gpt-5-image-mini) | "gpt5", "gpt5 image", "use gpt5" | +| `gpt5` | [OpenAI GPT-5 Image](https://openrouter.ai/openai/gpt-5-image) | "gpt5", "gpt5 image", "use gpt5" | ## Instructions diff --git a/.claude/skills/ai-image-creator/references/api-reference.md b/.claude/skills/ai-image-creator/references/api-reference.md index 5b879a4..d0ed962 100644 --- a/.claude/skills/ai-image-creator/references/api-reference.md +++ b/.claude/skills/ai-image-creator/references/api-reference.md @@ -7,10 +7,10 @@ All models use the same OpenRouter `/v1/chat/completions` endpoint and response | Keyword | Model ID | Modalities | Type | |---------|----------|------------|------| | `gemini` | [`google/gemini-3.1-flash-image-preview`](https://openrouter.ai/google/gemini-3.1-flash-image-preview) | `["image", "text"]` | Multimodal (default) | -| `riverflow` | [`sourceful/riverflow-v2-fast`](https://openrouter.ai/sourceful/riverflow-v2-fast) | `["image"]` | Image-only | -| `flux2` | [`black-forest-labs/flux.2-klein-4b`](https://openrouter.ai/black-forest-labs/flux.2-klein-4b) | `["image"]` | Image-only | +| `riverflow` | [`sourceful/riverflow-v2-pro`](https://openrouter.ai/sourceful/riverflow-v2-pro) | `["image"]` | Image-only | +| `flux2` | [`black-forest-labs/flux.2-max`](https://openrouter.ai/black-forest-labs/flux.2-max) | `["image"]` | Image-only | | `seedream` | [`bytedance-seed/seedream-4.5`](https://openrouter.ai/bytedance-seed/seedream-4.5) | `["image"]` | Image-only | -| `gpt5` | [`openai/gpt-5-image-mini`](https://openrouter.ai/openai/gpt-5-image-mini) | `["image", "text"]` | Multimodal | +| `gpt5` | [`openai/gpt-5-image`](https://openrouter.ai/openai/gpt-5-image) | `["image", "text"]` | Multimodal | **Important:** Image-only models MUST use `"modalities": ["image"]`. Using `["image", "text"]` may cause errors with these models. The script handles this automatically when using keywords. diff --git a/.claude/skills/ai-image-creator/scripts/generate-image.py b/.claude/skills/ai-image-creator/scripts/generate-image.py index fe4647a..a932bf5 100644 --- a/.claude/skills/ai-image-creator/scripts/generate-image.py +++ b/.claude/skills/ai-image-creator/scripts/generate-image.py @@ -48,14 +48,14 @@ "description": "Google Gemini 3.1 Flash — multimodal (text+image), default", }, "riverflow": { - "id": "sourceful/riverflow-v2-fast", + "id": "sourceful/riverflow-v2-pro", "modalities": ["image"], - "description": "Sourceful Riverflow v2 Fast — image-only, low latency", + "description": "Sourceful Riverflow v2 Pro — image-only, high quality", }, "flux2": { - "id": "black-forest-labs/flux.2-klein-4b", + "id": "black-forest-labs/flux.2-max", "modalities": ["image"], - "description": "Black Forest Labs FLUX.2 Klein 4B — image-only, fast", + "description": "Black Forest Labs FLUX.2 Max — image-only, high quality", }, "seedream": { "id": "bytedance-seed/seedream-4.5", @@ -63,9 +63,9 @@ "description": "ByteDance SeedDream 4.5 — image-only, high quality", }, "gpt5": { - "id": "openai/gpt-5-image-mini", + "id": "openai/gpt-5-image", "modalities": ["image", "text"], - "description": "OpenAI GPT-5 Image Mini — multimodal (text+image)", + "description": "OpenAI GPT-5 Image — multimodal (text+image)", }, } @@ -101,7 +101,7 @@ def resolve_model(model_arg: str | None, provider: str) -> tuple[str, list[str]] Supports three modes: 1. No --model flag: returns the default model for the provider (gemini). 2. Keyword match (e.g. 'riverflow'): looks up MODEL_REGISTRY. - 3. Full model ID (e.g. 'sourceful/riverflow-v2-fast'): reverse-lookups + 3. Full model ID (e.g. 'sourceful/riverflow-v2-pro'): reverse-lookups registry for modalities, or defaults to ["image", "text"] if unknown. Args: From cf3dc685023283823f6f070a75b16351adbc4c05 Mon Sep 17 00:00:00 2001 From: George Liu Date: Fri, 27 Mar 2026 03:20:26 +1000 Subject: [PATCH 099/174] Add transparent backgrounds, reference images, cost tracking to ai-image-creator --- .claude/skills/ai-image-creator/SKILL.md | 106 ++++- .../references/api-reference.md | 59 +++ .../references/setup-guide.md | 7 + .../scripts/generate-image.py | 440 +++++++++++++++++- 4 files changed, 575 insertions(+), 37 deletions(-) diff --git a/.claude/skills/ai-image-creator/SKILL.md b/.claude/skills/ai-image-creator/SKILL.md index 81c2127..236280a 100644 --- a/.claude/skills/ai-image-creator/SKILL.md +++ b/.claude/skills/ai-image-creator/SKILL.md @@ -1,6 +1,6 @@ --- name: ai-image-creator -description: Generate PNG images using AI (multiple models via OpenRouter including Gemini, FLUX.2, Riverflow, SeedDream, GPT-5 Image, proxied through Cloudflare AI Gateway BYOK). Use when user asks to "generate an image", "create a PNG", "make an icon", or needs AI-generated visual assets for the project. Supports model selection via keywords (gemini, riverflow, flux2, seedream, gpt5), configurable aspect ratios and resolutions. +description: Generate PNG images using AI (multiple models via OpenRouter including Gemini, FLUX.2, Riverflow, SeedDream, GPT-5 Image, proxied through Cloudflare AI Gateway BYOK). Use when user asks to "generate an image", "create a PNG", "make an icon", "make it transparent", or needs AI-generated visual assets for the project. Supports model selection via keywords (gemini, riverflow, flux2, seedream, gpt5), configurable aspect ratios/resolutions, transparent backgrounds (-t), reference image editing (-r), and per-project cost tracking (--costs). allowed-tools: Bash, Read, Write compatibility: Requires uv (Python runner) and network access. Environment variables for CF AI Gateway or direct API keys must be configured in shell profile (~/.zshrc on macOS, ~/.bashrc on Linux, or System Environment Variables on Windows). metadata: @@ -47,26 +47,44 @@ For short prompts (under 200 chars, no special characters), pass inline via `--p ```bash uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py \ - --output "OUTPUT_PATH" \ + -o "OUTPUT_PATH" \ [--provider openrouter|google] \ - [--aspect-ratio "16:9"] \ - [--image-size "2K"] \ - [--model "model-id"] + [-a "16:9"] \ + [-s "2K"] \ + [-m "model-id"] \ + [-r "ref-image.png"] \ + [-t] ``` With a specific model: ```bash uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py \ - --output "OUTPUT_PATH" \ - --model riverflow \ - --prompt "A serene mountain lake at sunset" + -o "OUTPUT_PATH" \ + -m riverflow \ + -p "A serene mountain lake at sunset" +``` + +With transparent background (requires ffmpeg + imagemagick): +```bash +uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py \ + -o "mascot.png" \ + -t \ + -p "A friendly robot mascot character" +``` + +With reference image for editing/style transfer (multimodal models only): +```bash +uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py \ + -o "edited.png" \ + -r "original.png" \ + -p "Change the background to a sunset scene" ``` Or with inline prompt (default model): ```bash uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py \ - --output "OUTPUT_PATH" \ - --prompt "A simple blue circle on white background" + -o "OUTPUT_PATH" \ + -p "A simple blue circle on white background" ``` ### Step 3: Clean Up (if temp file used) @@ -89,16 +107,19 @@ If the user needs resizing, format conversion, or other manipulation, first dete ## Parameters -| Argument | Required | Default | Description | -|----------|----------|---------|-------------| -| `--output` | Yes | -- | Output file path (parent dirs auto-created) | -| `--prompt` | No | -- | Inline prompt text | -| `--prompt-file` | No | `../tmp/prompt.txt` | Path to prompt file | -| `--provider` | No | `openrouter` | `openrouter` or `google` | -| `--aspect-ratio` | No | model default | OpenRouter only: `1:1`, `16:9`, `9:16`, `3:2`, `2:3`, `4:3`, `3:4`, `4:5`, `5:4`, `21:9` | -| `--image-size` | No | model default | OpenRouter only: `0.5K`, `1K`, `2K`, `4K` | -| `--model` | No | `gemini` | Model keyword (`gemini`, `riverflow`, `flux2`, `seedream`, `gpt5`) or full OpenRouter model ID | -| `--list-models` | No | -- | List available model keywords and exit | +| Argument | Short | Required | Default | Description | +|----------|-------|----------|---------|-------------| +| `--output` | `-o` | Yes | -- | Output file path (parent dirs auto-created) | +| `--prompt` | `-p` | No | -- | Inline prompt text | +| `--prompt-file` | -- | No | `../tmp/prompt.txt` | Path to prompt file | +| `--provider` | -- | No | `openrouter` | `openrouter` or `google` | +| `--aspect-ratio` | `-a` | No | model default | OpenRouter only: `1:1`, `16:9`, `9:16`, `3:2`, `2:3`, `4:3`, `3:4`, `4:5`, `5:4`, `21:9` | +| `--image-size` | `-s` | No | model default | OpenRouter only: `0.5K`, `1K`, `2K`, `4K` | +| `--model` | `-m` | No | `gemini` | Model keyword (`gemini`, `riverflow`, `flux2`, `seedream`, `gpt5`) or full model ID | +| `--ref` | `-r` | No | -- | Reference image file (repeatable). For editing/style transfer. Multimodal models only (gemini, gpt5) | +| `--transparent` | `-t` | No | -- | Generate with transparent background. Requires ffmpeg + imagemagick | +| `--costs` | -- | No | -- | Display generation/cost history for this project and exit | +| `--list-models` | -- | No | -- | List available model keywords and exit | ## Environment Variables @@ -114,6 +135,51 @@ Gateway mode activates when all 3 `CF_*` vars are set. Falls back to direct mode For first-time setup, see `references/setup-guide.md`. +## Transparent Mode (`-t`) + +Generates images with transparent backgrounds using a 3-step pipeline: + +1. **Green screen generation** — Prompt is augmented to place subject on solid #00FF00 green +2. **FFmpeg chroma key** — Removes green background + green fringe from edges +3. **ImageMagick auto-crop** — Trims transparent padding + +**Requirements:** `brew install ffmpeg imagemagick` + +**Use cases:** Game sprites, icons, logos, mascots, marketing assets with transparency. + +```bash +uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py \ + -o "sprite.png" -t -p "A pixel art treasure chest" +``` + +## Reference Images (`-r`) + +Send existing images alongside text prompts for editing, style transfer, or guided generation. Supports multiple references. **Multimodal models only** (gemini, gpt5) — image-only models (riverflow, flux2, seedream) will error. + +```bash +# Edit an existing image +uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py \ + -o "edited.png" -r "photo.png" -p "Make the background white" + +# Style transfer with multiple references +uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py \ + -o "combined.png" -r "style1.png" -r "content.png" -p "Apply the style of the first image to the second" +``` + +Supported formats: PNG, JPEG, WebP, GIF. + +## Cost Tracking (`--costs`) + +Every generation is logged to `.ai-image-creator/costs.json` in your project directory. View history: + +```bash +uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py --costs +``` + +Shows per-model breakdown: generation count, total tokens, elapsed time, and recent entries. **Security:** Only non-sensitive data is logged (model, tokens, timing, file path). No API keys or credentials are ever stored. + +Consider adding `.ai-image-creator/` to your `.gitignore`. + ## Image Tools On first invocation, detect available image manipulation tools: diff --git a/.claude/skills/ai-image-creator/references/api-reference.md b/.claude/skills/ai-image-creator/references/api-reference.md index d0ed962..9557e15 100644 --- a/.claude/skills/ai-image-creator/references/api-reference.md +++ b/.claude/skills/ai-image-creator/references/api-reference.md @@ -14,6 +14,65 @@ All models use the same OpenRouter `/v1/chat/completions` endpoint and response **Important:** Image-only models MUST use `"modalities": ["image"]`. Using `["image", "text"]` may cause errors with these models. The script handles this automatically when using keywords. +**Reference image support:** Only multimodal models (gemini, gpt5) support image input for editing and style transfer. Image-only models (riverflow, flux2, seedream) do not accept reference images. + +--- + +## Reference Images (Multimodal Input) + +### OpenRouter Format + +When sending reference images via OpenRouter, change `messages[0].content` from a string to an array of content parts: + +```json +{ + "model": "google/gemini-3.1-flash-image-preview", + "messages": [ + { + "role": "user", + "content": [ + {"type": "text", "text": "Change the background to a sunset scene"}, + { + "type": "image_url", + "image_url": { + "url": "data:image/png;base64,iVBORw0KGgo..." + } + } + ] + } + ], + "modalities": ["image", "text"] +} +``` + +Multiple images: add additional `image_url` entries to the content array. Text should come first. + +### Google AI Studio Format + +Add `inline_data` parts alongside the text part: + +```json +{ + "contents": [ + { + "parts": [ + {"text": "Change the background to a sunset scene"}, + { + "inline_data": { + "mime_type": "image/png", + "data": "iVBORw0KGgo..." + } + } + ] + } + ] +} +``` + +### Supported Input Formats + +PNG, JPEG, WebP, GIF. Images are base64-encoded inline (data URLs for OpenRouter, inline_data for Google). + --- ## Providers & Endpoints diff --git a/.claude/skills/ai-image-creator/references/setup-guide.md b/.claude/skills/ai-image-creator/references/setup-guide.md index 59ab9c8..d1bae50 100644 --- a/.claude/skills/ai-image-creator/references/setup-guide.md +++ b/.claude/skills/ai-image-creator/references/setup-guide.md @@ -9,6 +9,13 @@ Step-by-step instructions to configure all required services for the ai-image-cr - A Cloudflare account (free tier works) - An OpenRouter account and/or Google AI Studio account +### Optional (for transparent mode `-t`) + +- **FFmpeg 4.3+**: `brew install ffmpeg` (macOS) / `apt install ffmpeg` (Linux) +- **ImageMagick 7+**: `brew install imagemagick` (macOS) / `apt install imagemagick` (Linux) + +These are only needed if you use the `-t` flag for transparent background generation. + --- ## 1. Get an OpenRouter API Key diff --git a/.claude/skills/ai-image-creator/scripts/generate-image.py b/.claude/skills/ai-image-creator/scripts/generate-image.py index a932bf5..5fc1005 100644 --- a/.claude/skills/ai-image-creator/scripts/generate-image.py +++ b/.claude/skills/ai-image-creator/scripts/generate-image.py @@ -25,10 +25,14 @@ import json import logging import os +import shutil +import subprocess import sys +import tempfile import time import urllib.error import urllib.request +from datetime import datetime, timezone from pathlib import Path from typing import Any # noqa: F401 — used in type hints below @@ -80,6 +84,28 @@ log = logging.getLogger("ai-image-creator") +MIME_MAP = { + ".png": "image/png", + ".jpg": "image/jpeg", + ".jpeg": "image/jpeg", + ".webp": "image/webp", + ".gif": "image/gif", +} + + +def guess_mime(path: str) -> str: + """Guess MIME type from file extension. + + Args: + path: File path string. + + Returns: + MIME type string, defaults to 'image/png' for unknown extensions. + """ + ext = Path(path).suffix.lower() + return MIME_MAP.get(ext, "image/png") + + def mask_key(key: str, visible: int = 4) -> str: """Mask an API key for safe logging, showing only the last N chars. @@ -149,10 +175,10 @@ def parse_args() -> argparse.Namespace: description="Generate PNG images using AI (multiple models via OpenRouter/Google AI Studio)" ) parser.add_argument( - "--output", required=False, default=None, help="Output PNG file path (required unless --list-models)" + "-o", "--output", required=False, default=None, help="Output PNG file path (required unless --list-models)" ) parser.add_argument( - "--prompt", default=None, help="Inline prompt text (alternative to --prompt-file)" + "-p", "--prompt", default=None, help="Inline prompt text (alternative to --prompt-file)" ) parser.add_argument( "--prompt-file", @@ -166,20 +192,36 @@ def parse_args() -> argparse.Namespace: help="API provider (default: openrouter)", ) parser.add_argument( - "--aspect-ratio", + "-a", "--aspect-ratio", default=None, help="Aspect ratio for image (OpenRouter only): 1:1, 16:9, 9:16, 3:2, 2:3, etc.", ) parser.add_argument( - "--image-size", + "-s", "--image-size", default=None, help="Image resolution (OpenRouter only): 0.5K, 1K, 2K, 4K", ) parser.add_argument( - "--model", + "-m", "--model", default=None, help="Model keyword (gemini, riverflow, flux2, seedream, gpt5) or full model ID", ) + parser.add_argument( + "-r", "--ref", + action="append", + default=None, + help="Reference image file(s) for editing/style transfer (repeatable, multimodal models only)", + ) + parser.add_argument( + "-t", "--transparent", + action="store_true", + help="Generate with transparent background (requires ffmpeg + imagemagick)", + ) + parser.add_argument( + "--costs", + action="store_true", + help="Display cost/generation history for this project and exit", + ) parser.add_argument( "--list-models", action="store_true", @@ -406,6 +448,7 @@ def build_request_body( aspect_ratio: str | None = None, image_size: str | None = None, modalities: list[str] | None = None, + ref_images: list[str] | None = None, ) -> dict[str, Any]: """Build JSON request body for the given provider. @@ -418,17 +461,38 @@ def build_request_body( modalities: Output modalities list, e.g. ['image'] for image-only models or ['image', 'text'] for multimodal models. Defaults to ['image', 'text'] if not specified. Only used for OpenRouter provider. + ref_images: Optional list of file paths to reference images for + editing/style transfer. Only supported by multimodal models. Returns: Dict suitable for JSON serialization as request body. """ + refs = ref_images or [] + if provider == "openrouter": - body = { - "model": model, - "messages": [{"role": "user", "content": prompt}], - "modalities": modalities or ["image", "text"], - } - image_config = {} + if refs: + # Multimodal content array: text + image_url parts + content_parts: list[dict[str, Any]] = [{"type": "text", "text": prompt}] + for ref_path in refs: + b64 = base64.b64encode(Path(ref_path).read_bytes()).decode() + mime = guess_mime(ref_path) + content_parts.append({ + "type": "image_url", + "image_url": {"url": f"data:{mime};base64,{b64}"}, + }) + log.info(f"Reference image: {ref_path} ({mime}, {len(b64)} base64 chars)") + body: dict[str, Any] = { + "model": model, + "messages": [{"role": "user", "content": content_parts}], + "modalities": modalities or ["image", "text"], + } + else: + body = { + "model": model, + "messages": [{"role": "user", "content": prompt}], + "modalities": modalities or ["image", "text"], + } + image_config: dict[str, str] = {} if aspect_ratio: image_config["aspect_ratio"] = aspect_ratio if image_size: @@ -437,10 +501,17 @@ def build_request_body( body["image_config"] = image_config log.debug(f"Image config: {json.dumps(image_config)}") else: - body = {"contents": [{"parts": [{"text": prompt}]}]} + # Google AI Studio + parts: list[dict[str, Any]] = [{"text": prompt}] + for ref_path in refs: + b64 = base64.b64encode(Path(ref_path).read_bytes()).decode() + mime = guess_mime(ref_path) + parts.append({"inline_data": {"mime_type": mime, "data": b64}}) + log.info(f"Reference image: {ref_path} ({mime}, {len(b64)} base64 chars)") + body = {"contents": [{"parts": parts}]} log.debug(f"Request body size: {len(json.dumps(body))} bytes") - # Log body without the full prompt (can be very long) + # Log body without the full prompt or base64 data (can be very long) body_preview = json.dumps(body) if len(body_preview) > 500: log.debug(f"Request body (truncated): {body_preview[:500]}...") @@ -623,6 +694,260 @@ def extract_image_google(response: dict) -> tuple[bytes, str]: return image_bytes, text_content +def find_imagemagick() -> str | None: + """Find ImageMagick binary (magick for v7, convert for v6). + + Returns: + Path to binary, or None if not found. + """ + for cmd in ("magick", "convert"): + path = shutil.which(cmd) + if path: + log.debug(f"Found ImageMagick: {cmd} at {path}") + return cmd + return None + + +def check_ffmpeg_despill() -> bool: + """Check if FFmpeg supports the despill filter (requires 4.3+). + + Returns: + True if despill is available, False otherwise. + """ + try: + result = subprocess.run( + ["ffmpeg", "-filters"], + capture_output=True, text=True, timeout=10, + ) + return "despill" in result.stdout + except (subprocess.TimeoutExpired, FileNotFoundError): + return False + + +def process_transparent(input_path: Path, output_path: Path) -> None: + """Remove green screen background and trim transparent padding. + + 3-step pipeline: + 1. FFmpeg chroma key — removes green background pixels + 2. FFmpeg despill — removes green fringe from edges (if available) + 3. ImageMagick trim — crops transparent padding + + Args: + input_path: Path to the raw generated image (with green background). + output_path: Final output path for the transparent image. + + Raises: + RuntimeError: If required tools are missing or processing fails. + """ + # Check tool availability + ffmpeg_path = shutil.which("ffmpeg") + if not ffmpeg_path: + raise RuntimeError( + "Transparent mode requires FFmpeg. Install with: brew install ffmpeg" + ) + + magick_cmd = find_imagemagick() + if not magick_cmd: + raise RuntimeError( + "Transparent mode requires ImageMagick. Install with: brew install imagemagick" + ) + + has_despill = check_ffmpeg_despill() + + # Step 1+2: FFmpeg chroma key (+ despill if available) + with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as tmp_keyed: + tmp_keyed_path = Path(tmp_keyed.name) + + try: + if has_despill: + vf = "colorkey=0x00FF00:0.3:0.15,despill=green" + else: + print("WARNING: FFmpeg despill filter not available (requires 4.3+). " + "Green fringe removal skipped.", file=sys.stderr) + vf = "colorkey=0x00FF00:0.3:0.15" + + log.info(f"FFmpeg chroma key: {vf}") + result = subprocess.run( + ["ffmpeg", "-i", str(input_path), "-vf", vf, "-y", str(tmp_keyed_path)], + capture_output=True, text=True, timeout=60, + ) + if result.returncode != 0: + raise RuntimeError(f"FFmpeg chroma key failed: {result.stderr[-500:]}") + + # Step 3: ImageMagick trim transparent padding + log.info("ImageMagick trim") + trim_args = [magick_cmd] + if magick_cmd == "magick": + trim_args += [str(tmp_keyed_path), "-fuzz", "15%", "-trim", "+repage", str(output_path)] + else: + # ImageMagick 6 (convert) + trim_args += [str(tmp_keyed_path), "-fuzz", "15%", "-trim", "+repage", str(output_path)] + + result = subprocess.run(trim_args, capture_output=True, text=True, timeout=60) + if result.returncode != 0: + raise RuntimeError(f"ImageMagick trim failed: {result.stderr[-500:]}") + + print("Transparent background processing complete.", file=sys.stderr) + + finally: + # Cleanup temp file + tmp_keyed_path.unlink(missing_ok=True) + + +def get_costs_path() -> Path: + """Get project-level costs file path. + + Returns: + Path to .ai-image-creator/costs.json in current working directory. + """ + return Path.cwd() / ".ai-image-creator" / "costs.json" + + +def log_cost_entry( + response: dict[str, Any], + provider: str, + model: str, + mode: str, + aspect_ratio: str | None, + image_size: str | None, + output_file: str, + size_bytes: int, + elapsed_seconds: float, +) -> None: + """Append a cost entry to the project-level costs file. + + Only stores non-sensitive operational data. Never stores API keys, tokens, + account IDs, or any credentials. + + Args: + response: Raw API response dict (for extracting token usage). + provider: 'openrouter' or 'google'. + model: Full model ID. + mode: 'gateway' or 'direct'. + aspect_ratio: Aspect ratio used, or None. + image_size: Image size used, or None. + output_file: Output file path string. + size_bytes: Size of generated image in bytes. + elapsed_seconds: Total generation time. + """ + costs_path = get_costs_path() + + # Extract token usage (provider-specific format) + token_usage: dict[str, int] = {} + if provider == "openrouter": + usage = response.get("usage", {}) + if usage: + token_usage = { + "prompt_tokens": usage.get("prompt_tokens", 0), + "completion_tokens": usage.get("completion_tokens", 0), + "total_tokens": usage.get("total_tokens", 0), + } + else: + # Google AI Studio format + usage = response.get("usageMetadata", {}) + if usage: + token_usage = { + "prompt_tokens": usage.get("promptTokenCount", 0), + "completion_tokens": usage.get("candidatesTokenCount", 0), + "total_tokens": usage.get("totalTokenCount", 0), + } + + entry = { + "timestamp": datetime.now(timezone.utc).isoformat(), + "model": model, + "provider": provider, + "mode": mode, + "aspect_ratio": aspect_ratio, + "image_size": image_size, + "output_file": output_file, + "size_bytes": size_bytes, + "elapsed_seconds": round(elapsed_seconds, 1), + "token_usage": token_usage, + } + + # Read existing entries + costs_path.parent.mkdir(parents=True, exist_ok=True) + entries: list[dict[str, Any]] = [] + if costs_path.exists(): + try: + entries = json.loads(costs_path.read_text(encoding="utf-8")) + except (json.JSONDecodeError, OSError): + log.warning(f"Could not read {costs_path}, starting fresh") + + entries.append(entry) + costs_path.write_text(json.dumps(entries, indent=2) + "\n", encoding="utf-8") + log.info(f"Cost entry logged to {costs_path}") + + # Warn about .gitignore if applicable + gitignore = Path.cwd() / ".gitignore" + if gitignore.exists(): + content = gitignore.read_text(encoding="utf-8") + if ".ai-image-creator" not in content: + print( + "TIP: Consider adding '.ai-image-creator/' to .gitignore", + file=sys.stderr, + ) + + +def display_costs() -> None: + """Display cost/generation history grouped by model. + + Reads .ai-image-creator/costs.json from CWD and prints a formatted summary. + """ + costs_path = get_costs_path() + if not costs_path.exists(): + print("No cost history found for this project.", file=sys.stderr) + print(f"Expected: {costs_path}", file=sys.stderr) + sys.exit(0) + + try: + entries = json.loads(costs_path.read_text(encoding="utf-8")) + except (json.JSONDecodeError, OSError) as e: + print(f"ERROR: Could not read costs file: {e}", file=sys.stderr) + sys.exit(1) + + if not entries: + print("No generation entries recorded.", file=sys.stderr) + sys.exit(0) + + # Group by model + by_model: dict[str, list[dict[str, Any]]] = {} + for entry in entries: + model = entry.get("model", "unknown") + by_model.setdefault(model, []).append(entry) + + print(f"\nGeneration History ({len(entries)} total)") + print(f"Project: {Path.cwd()}") + print("=" * 60) + + total_tokens = 0 + total_time = 0.0 + + for model, model_entries in sorted(by_model.items()): + model_tokens = sum( + e.get("token_usage", {}).get("total_tokens", 0) for e in model_entries + ) + model_time = sum(e.get("elapsed_seconds", 0) for e in model_entries) + total_tokens += model_tokens + total_time += model_time + + print(f"\n {model}") + print(f" Generations: {len(model_entries)}") + print(f" Total tokens: {model_tokens:,}") + print(f" Total time: {model_time:.1f}s") + + # Show last 3 entries + for entry in model_entries[-3:]: + ts = entry.get("timestamp", "?")[:19] + out = entry.get("output_file", "?") + size = entry.get("size_bytes", 0) + print(f" {ts} {out} ({size / 1024:.1f} KB)") + + print(f"\n{'=' * 60}") + print(f" Total: {len(entries)} generations, {total_tokens:,} tokens, {total_time:.1f}s") + print() + + def main() -> None: """Main entry point — parse args, generate image, write output.""" args = parse_args() @@ -638,6 +963,11 @@ def main() -> None: log.debug(f"Args: {vars(args)}") log.debug("=" * 60) + # Handle --costs (display and exit) + if args.costs: + display_costs() + sys.exit(0) + # Handle --list-models if args.list_models: print("Available model keywords:") @@ -648,9 +978,9 @@ def main() -> None: print(f" modalities: {', '.join(info['modalities'])}") sys.exit(0) - # Validate --output is provided (required unless --list-models) + # Validate --output is provided (required unless --list-models or --costs) if not args.output: - print("ERROR: --output is required (unless using --list-models)", file=sys.stderr) + print("ERROR: --output is required (unless using --list-models or --costs)", file=sys.stderr) sys.exit(1) # Validate output path @@ -665,8 +995,50 @@ def main() -> None: # Resolve model and modalities model, modalities = resolve_model(args.model, args.provider) + # Validate reference images + ref_images = args.ref or [] + if ref_images: + # Check model supports multimodal input + if "text" not in modalities: + print( + f"ERROR: Reference images (-r) require a multimodal model. " + f"'{model}' only supports image output.\n" + f"Use --model gemini or --model gpt5 for image editing/style transfer.", + file=sys.stderr, + ) + sys.exit(1) + + # Validate all ref files exist + for ref_path in ref_images: + if not Path(ref_path).exists(): + print(f"ERROR: Reference image not found: {ref_path}", file=sys.stderr) + sys.exit(1) + if Path(ref_path).suffix.lower() not in (".png", ".jpg", ".jpeg", ".webp", ".gif"): + print(f"WARNING: Unusual image extension: {ref_path}", file=sys.stderr) + + print(f"Reference images: {len(ref_images)} file(s)", file=sys.stderr) + + # Validate transparent mode tools + if args.transparent: + if not shutil.which("ffmpeg"): + print("ERROR: Transparent mode requires FFmpeg. Install with: brew install ffmpeg", file=sys.stderr) + sys.exit(1) + if not find_imagemagick(): + print("ERROR: Transparent mode requires ImageMagick. Install with: brew install imagemagick", file=sys.stderr) + sys.exit(1) + print("Transparent mode: enabled", file=sys.stderr) + # Resolve prompt prompt = resolve_prompt(args) + + # Inject green screen instructions for transparent mode + if args.transparent: + prompt += ( + "\n\nIMPORTANT: Place the subject on a perfectly solid, flat, bright green " + "background (#00FF00). No shadows, no gradients, no floor reflections — " + "just pure #00FF00 green everywhere behind the subject." + ) + print(f"Provider: {args.provider}", file=sys.stderr) print(f"Model: {model}", file=sys.stderr) print(f"Modalities: {', '.join(modalities)}", file=sys.stderr) @@ -690,6 +1062,7 @@ def main() -> None: body = build_request_body( args.provider, model, prompt, args.aspect_ratio, args.image_size, modalities=modalities, + ref_images=ref_images if ref_images else None, ) print(f"URL: {url}", file=sys.stderr) @@ -731,21 +1104,52 @@ def main() -> None: log.debug(f"Image extraction failed. Raw response keys: {list(response.keys()) if response else 'None'}") sys.exit(1) - # Write output + # Write output (or process transparent mode) output_path.parent.mkdir(parents=True, exist_ok=True) - output_path.write_bytes(image_bytes) + + if args.transparent: + # Write to temp file, then process through transparent pipeline + with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as tmp_raw: + tmp_raw_path = Path(tmp_raw.name) + try: + tmp_raw_path.write_bytes(image_bytes) + process_transparent(tmp_raw_path, output_path) + # Re-read the processed file for size reporting + image_bytes = output_path.read_bytes() + finally: + tmp_raw_path.unlink(missing_ok=True) + else: + output_path.write_bytes(image_bytes) total_elapsed = time.time() - total_start # Report success size_kb = len(image_bytes) / 1024 print(f"\nImage saved: {output_path} ({size_kb:.1f} KB)", file=sys.stderr) + if args.transparent: + print(" (transparent background)", file=sys.stderr) if text_content: print(f"Model notes: {text_content}", file=sys.stderr) log.info(f"Total elapsed: {total_elapsed:.1f}s") log.debug(f"Output file: {output_path.resolve()}") log.debug(f"File size: {len(image_bytes)} bytes ({size_kb:.1f} KB)") + # Log cost entry + try: + log_cost_entry( + response=response, + provider=args.provider, + model=model, + mode=mode, + aspect_ratio=args.aspect_ratio, + image_size=args.image_size, + output_file=str(output_path), + size_bytes=len(image_bytes), + elapsed_seconds=total_elapsed, + ) + except OSError as e: + log.warning(f"Could not log cost entry: {e}") + # Print machine-readable output to stdout result = { "ok": True, @@ -755,6 +1159,8 @@ def main() -> None: "model": model, "mode": mode, "elapsed_seconds": round(total_elapsed, 1), + "transparent": args.transparent, + "ref_images": len(ref_images), } log.debug(f"Result JSON: {json.dumps(result, indent=2)}") print(json.dumps(result)) From 3f48a2830dba215f5e4e3c5275d55aeb789e7aa4 Mon Sep 17 00:00:00 2001 From: George Liu Date: Fri, 27 Mar 2026 03:57:58 +1000 Subject: [PATCH 100/174] add prompt enhancements to ai-image-creator skill --- .claude/skills/ai-image-creator/SKILL.md | 36 +++ .../references/prompt-categories.md | 234 ++++++++++++++++++ .../references/prompt-core.md | 127 ++++++++++ .../references/prompt-platforms.md | 95 +++++++ .../scripts/generate-image.py | 21 ++ 5 files changed, 513 insertions(+) create mode 100644 .claude/skills/ai-image-creator/references/prompt-categories.md create mode 100644 .claude/skills/ai-image-creator/references/prompt-core.md create mode 100644 .claude/skills/ai-image-creator/references/prompt-platforms.md diff --git a/.claude/skills/ai-image-creator/SKILL.md b/.claude/skills/ai-image-creator/SKILL.md index 236280a..1400d28 100644 --- a/.claude/skills/ai-image-creator/SKILL.md +++ b/.claude/skills/ai-image-creator/SKILL.md @@ -43,6 +43,42 @@ For short prompts (under 200 chars, no special characters), pass inline via `--p - For icons, mention the target size (e.g., "512x512", "favicon at 32x32"). - For photos, describe lighting, camera angle, and mood. +### Step 1.5: Prompt Enhancement (Optional — Progressive Disclosure) + +Professional prompt patterns are available in 3 reference files. These are **not loaded by default** — only read them when the user's request matches a category or they explicitly ask for enhancement. + +**Category Detection** — Match the user's request to a category: + +| If request mentions... | Category | Also read | +|----------------------|----------|-----------| +| "product shot", "product photo", "hero image" | `product_hero` | `prompt-core.md` + `prompt-categories.md` § product_hero | +| "lifestyle", "in-use", "in context" | `lifestyle` | `prompt-core.md` + `prompt-categories.md` § lifestyle | +| "instagram", "social media", "tiktok", "pinterest" | `social_media` | `prompt-core.md` + `prompt-platforms.md` + `prompt-categories.md` § social_media | +| "banner", "ad", "email header" | `marketing_banner` | `prompt-core.md` + `prompt-platforms.md` + `prompt-categories.md` § marketing_banner | +| "website", "app", "logo", "ad format", "leaderboard", "skyscraper" | `web_app` | `prompt-core.md` + `prompt-platforms.md` + `prompt-categories.md` § web_app | +| "icon", "favicon", "app icon" | `icon_logo` | `prompt-core.md` + `prompt-categories.md` § icon_logo | +| "mascot", "character", "illustration", "artwork" | `illustration` | `prompt-core.md` + `prompt-categories.md` § illustration | +| "food", "drink", "recipe", "restaurant" | `food_drink` | `prompt-core.md` + `prompt-categories.md` § food_drink | +| "building", "interior", "room", "architecture" | `architecture` | `prompt-core.md` + `prompt-categories.md` § architecture | +| "chart", "infographic", "data", "diagram" | `infographic` | `prompt-core.md` + `prompt-categories.md` § infographic | +| "t-shirt", "mug design", "poster", "POD", "print-on-demand" | `pod_design` | `prompt-core.md` + `prompt-platforms.md` + `prompt-categories.md` § pod_design | +| No match / simple request | — | Skip patterns, generate directly | + +**When to skip enhancement:** +- User's prompt is already detailed (150+ words with camera/lighting/composition specifics) +- Simple/direct requests ("generate a blue circle on white background") +- User says "no pattern" or provides a fully formed prompt + +**When to apply:** +- User says "use product_hero pattern" or "apply social_media pattern" (explicit) +- Request clearly matches a category above (auto-detect) +- User asks for "enhanced prompt" or "professional quality" + +**Reference files** (in `references/` directory): +- `prompt-core.md` — Foundational rules: narrative prompting, camera/lens/lighting specs, text rendering rules, model recommendations +- `prompt-platforms.md` — Social media ratios, IAB ad sizes, web dimensions, POD specs — all mapped to `-a`/`-s` flags +- `prompt-categories.md` — 11 category formulas with templates and complete example prompts + ### Step 2: Run Generation Script ```bash diff --git a/.claude/skills/ai-image-creator/references/prompt-categories.md b/.claude/skills/ai-image-creator/references/prompt-categories.md new file mode 100644 index 0000000..f779340 --- /dev/null +++ b/.claude/skills/ai-image-creator/references/prompt-categories.md @@ -0,0 +1,234 @@ +# Category-Specific Prompt Patterns + +Each category provides a **formula template**, **key elements**, **recommended model**, and a **complete example prompt**. Read only the section matching the detected category. + +--- + +## product_hero + +**Studio product photography** — Clean, professional shots with controlled lighting. + +**Formula:** +``` +Create a [lighting] product photograph of [detailed product description] +on/against [surface/background]. Shot with [camera] [lens] at [aperture]. +[Lighting description]. [Composition notes]. [Mood/atmosphere]. +``` + +**Key Elements:** Camera hardware, specific surface material, lighting direction/quality, product texture/finish/color, atmosphere + +**Recommended model:** `gemini` or `gpt5` + +**Example:** +> Create a cinematic product photograph of a matte-black wireless headphone on a polished obsidian surface. Shot with Sony A7R IV, 85mm macro lens at f/2.8, 45-degree product angle. Single soft key light from upper-left creates gentle shadows that define the headphone's contours, with a subtle reflection in the obsidian surface. Deep shadows on the right add drama and luxury. The headphone's ear cushion texture is clearly visible — soft leather grain catching the light. Dark, moody atmosphere with rich tonal depth. 4:5 aspect ratio. + +--- + +## lifestyle + +**Products in real-world settings** — Environmental storytelling with aspirational context. + +**Formula:** +``` +Create a [mood] lifestyle photograph showcasing [product] in [real-world setting]. +[Environmental details — props, furniture, plants]. [Lighting — natural preferred]. +[Human interaction if any]. Shot with [camera] [lens] at [aperture]. +``` + +**Key Elements:** Environmental storytelling, natural lighting, contextual props, aspirational setting, human touch + +**Recommended model:** `gemini` or `gpt5` + +**Example:** +> Create a warm, inviting lifestyle photograph showcasing a compact walnut bookshelf speaker in a cozy reading nook. The speaker sits on a mid-century modern side table beside a plush armchair with a knitted throw blanket. A half-drunk cup of coffee and an open paperback add lived-in charm. Warm afternoon light streams through linen curtains, casting soft shadows across the scene. Shot with Sony A7III, 35mm lens at f/2.8. The composition draws the eye from the warm light to the speaker naturally. Aspirational but attainable — the kind of moment you want to step into. + +--- + +## social_media + +**Platform-optimized graphics** — Designed for scroll-stopping impact. + +**Formula:** +``` +Create a [platform]-optimized [style] image of [subject]. +[Composition for scroll-stopping impact]. [Bold colors/high contrast]. +[Aspect ratio from prompt-platforms.md]. [Text if any, in quotes]. +``` + +**Key Elements:** Platform-specific ratio, high visual impact in first 50ms, bold colors, clear focal point, text integration + +**Recommended model:** `gemini` or `seedream` + +**Example:** +> Create a vibrant, scroll-stopping Instagram feed image featuring an artisanal honey jar with a hand-lettered label reading "GOLDEN GROVE" positioned on a rustic wooden board with a honey dipper and scattered wildflowers. Morning sunlight creates a golden backlit glow through the honey, making it luminous. Shot with Canon R5, 100mm macro at f/2.8 for tight detail with dreamy background blur. Bold warm color palette — amber, gold, cream, forest green from the herbs. The composition places the jar at the left-third power point with the honey dipper creating a diagonal leading line. 4:5 vertical format. + +--- + +## marketing_banner + +**Web banners, email headers, ad creatives** — Designed with text overlay zones. + +**Formula:** +``` +Create a [width:height] marketing banner for [product/campaign]. +[Product positioned in left/right third]. [Large negative space zone on opposite side +for text overlay]. [Brand colors]. [Clean, professional composition]. +``` + +**Key Elements:** Deliberate negative space for copy, brand color integration, clean zones, product positioning, CTA area + +**Recommended model:** `gemini` + +**Example:** +> Create a 16:9 widescreen marketing banner for a premium coffee subscription service. A steaming ceramic mug of dark coffee positioned in the right third of the frame, with wisps of steam rising against a warm, blurred café background. The entire left two-thirds is clean negative space with a soft gradient from warm brown to cream, designed for headline text and CTA button overlay. Professional, inviting atmosphere with golden ambient lighting. Muted earth tones — espresso brown, warm cream, subtle copper accents. + +--- + +## web_app + +**Website/app logos, banners, ad format creatives** — Professional digital assets with standard sizing. + +**Formula:** +``` +Create a [style] [asset type] for [brand/product]. +[Dimensions/format from prompt-platforms.md]. [Brand elements]. +[Text in quotes if any]. [Background specification]. +[CTA zone / layout zones if ad format]. +``` + +**Key Elements:** Standard ad sizes (IAB), favicon/logo constraints, CTA zones, brand consistency, responsive considerations + +**Recommended model:** `gemini` (best text rendering) + +**Example (logo):** +> Create a clean, modern website logo for a timezone scheduling tool. Simple globe icon with vertical meridian lines suggesting time zones, rendered in a flat design style with two colors: deep navy blue and bright teal accent. The globe shape must be recognizable at 32x32 pixels. Solid white background. No gradients, no 3D effects — pure flat vector aesthetic. + +**Example (leaderboard ad):** +> Create a 4:1 wide horizontal leaderboard banner ad for a SaaS productivity app. Clean white background with a laptop mockup showing the app interface in the left quarter. The right three-quarters features large clean space for headline text. Accent color: electric blue (#0066FF) used sparingly for a thin border and small CTA button zone in the lower-right. Professional, minimal, corporate aesthetic. Sharp edges, no rounded corners on the overall banner. + +--- + +## icon_logo + +**App icons, favicons, brand marks** — Must work at tiny sizes. + +**Formula:** +``` +Create a [style] icon/logo of [subject]. Simple, recognizable silhouette +that reads clearly at [target size]. Maximum [N] colors on [background]. +[Shape constraints]. No fine detail — bold shapes only. +``` + +**Key Elements:** Readability at small sizes, bold silhouette, limited colors, solid background, simple geometry + +**Recommended model:** `gemini` + +**Example:** +> Create a flat-design app icon of a world clock. A simplified globe shape with 3 vertical timezone band lines in teal and navy blue, with a small clock hand overlay at the 12 o'clock position. Pure white background. Maximum 3 colors. The icon must be recognizable at 32x32 pixels — bold shapes, no thin lines, no fine detail. Clean vector style suitable for iOS and Android app stores. Square format, 1:1 aspect ratio. + +--- + +## illustration + +**Characters, mascots, creative artwork** — Artistic and expressive. + +**Formula:** +``` +Create a [style] illustration of [subject/character]. +[Composition and pose]. [Color palette]. [Art style direction]. +[Level of detail]. [Background treatment]. +``` + +**Key Elements:** Style direction (flat, realistic, anime, watercolor, etc.), composition, color palette, character design, background + +**Recommended model:** `riverflow` or `flux2` + +**Example:** +> Create a charming flat-illustration mascot character of a friendly robot holding a coffee mug. The robot has a rounded rectangular body in brushed silver with a glowing teal chest panel, stubby arms, and expressive dot eyes with a slight smile. It holds an oversized white ceramic mug with both hands. Warm, inviting pose slightly tilted. Color palette: silver, teal, white, warm amber highlights. Clean line work, subtle gradients for dimension. Solid light grey background. Suitable for web app branding — must look friendly and approachable, not threatening. + +--- + +## food_drink + +**Food and beverage photography** — Appetizing and detailed. + +**Formula:** +``` +Create a [mood] food photograph of [dish/beverage description]. +[Styling details — garnish, props, surface]. [Steam/condensation/texture]. +Shot with [camera] [macro lens] at [aperture]. +[Lighting — natural preferred]. [Color temperature]. +``` + +**Key Elements:** Macro lens detail, food styling (garnish, drips, steam), appetizing color temperature, surface/props + +**Recommended model:** `gemini` or `gpt5` + +**Example:** +> Create a warm, appetizing overhead photograph of a rustic sourdough pizza fresh from a wood-fired oven. Bubbling mozzarella with golden-brown leopard spots, scattered fresh basil leaves, a drizzle of olive oil catching the light. The pizza sits on a weathered wooden cutting board with a pizza cutter, scattered flour, and a small bowl of chili flakes nearby. Shot with Canon R5, 100mm macro lens at f/2.8. Warm natural window light from the left creating gentle shadows. Steam rising from the cheese. Rich, warm color palette — golden crust, vivid green basil, white mozzarella, deep red sauce peeking through. + +--- + +## architecture + +**Interior and exterior spaces** — Accurate perspective and materials. + +**Formula:** +``` +Create a [style] architectural photograph of [space/building description]. +[Materials and finishes]. [Perspective and composition]. +Shot with [wide-angle lens] at [aperture]. +[Lighting — time of day, ambient]. [Atmosphere/mood]. +``` + +**Key Elements:** Wide angle, corrected verticals, material accuracy, ambient lighting, atmosphere + +**Recommended model:** `gpt5` or `flux2` + +**Example:** +> Create a bright, airy interior photograph of a modern Scandinavian living room. Floor-to-ceiling windows flooding the space with soft diffused daylight. Light oak hardwood floors, a low-profile grey linen sofa, a round marble coffee table, and a single Monstera plant in a ceramic pot. White walls with subtle texture. Shot with Canon 5D, 24mm tilt-shift lens at f/11 for corrected verticals and deep focus. The composition leads from the plant in the foreground through the sofa to the window view. Minimal, serene atmosphere with muted neutral tones — cream, grey, natural oak, touches of sage green. + +--- + +## infographic + +**Data visualization, diagrams, charts** — Clear and structured. + +**Formula:** +``` +Create a [style] infographic about [topic]. +[Grid/layout description]. [Data elements with content]. +[Color coding system]. [Icon style]. [Aspect ratio — usually vertical]. +``` + +**Key Elements:** Clear grid structure, data hierarchy, icon consistency, color coding, readability + +**Recommended model:** `gemini` (best text rendering) + +**Example:** +> Create a clean, modern infographic comparing 4 coffee brewing methods. Vertical 2:3 format with a bento-grid layout: title bar at top, then a 2x2 grid of equal cards below. Each card contains: a simple line-art icon of the brewing device (French press, pour-over, espresso machine, AeroPress), the method name in bold sans-serif, brew time, and a 1-5 strength rating shown as filled circles. Color coding: each method gets a distinct warm tone (amber, terracotta, coffee brown, burnt orange). White background, dark grey text. Clean, minimal design language with consistent 16px rounded corners on all cards. + +--- + +## pod_design + +**Print-on-demand designs** — Isolated graphics for t-shirts, mugs, posters, stickers. + +**Formula:** +``` +Create a [style] design of [subject] for [product type]. +[Composition — center, badge, statement typography]. +[Color palette — limited, print-friendly]. [Background: solid black/white OR use -t]. +Sharp edges, no gradients at border, no ambient shadows. +[Print placement if apparel]. +``` + +**Key Elements:** Solid background for easy removal (or `-t` for transparency), isolated design, print-friendly colors, clean edges + +**Recommended model:** `riverflow` or `flux2` + +**Example (t-shirt):** +> Create a dark gothic illustration of a highly detailed human skull with ornate filigree engravings carved into the bone surface. Blooming roses with thorned vines intertwine through the eye sockets and jaw, their petals showing individual vein details. Center-radiate composition — skull as the dominant focal point surrounded by organic flourishes. Hand-drawn etching style with meticulous crosshatching. Color palette strictly limited to bone white and blood red on a pure solid black background. Sharp edges between design and background with no gradients, no ambient shadows, no noise — optimized for print production. 4:5 vertical format. + +**Example (mug wrap):** +> Create a seamless horizontal wrap-around design for an 11oz coffee mug. A continuous mountain range landscape in a minimalist line-art style — clean single-weight lines depicting peaks, valleys, and a winding river. Subtle dawn gradient from deep navy at the bottom to warm peach at the peaks. The design must tile seamlessly left-to-right for the wrap. White background with the design occupying the middle 60% vertically. 21:9 ultra-wide aspect ratio. diff --git a/.claude/skills/ai-image-creator/references/prompt-core.md b/.claude/skills/ai-image-creator/references/prompt-core.md new file mode 100644 index 0000000..a357983 --- /dev/null +++ b/.claude/skills/ai-image-creator/references/prompt-core.md @@ -0,0 +1,127 @@ +# Prompt Engineering — Core Principles + +Foundational rules for composing high-quality image generation prompts. Read this when a category is detected or the user asks for prompt enhancement. + +--- + +## Core Prompting Principles + +1. **Narrative over keywords** — Describe a scene like directing a photographer, not listing attributes. "A warm afternoon in a sunlit café with a steaming latte on a marble table" beats "latte, café, warm, marble, afternoon, sunlit." + +2. **Specificity creates quality** — Detailed descriptions produce dramatically better results. "Weathered ceramic mug with visible glaze cracks and a thin gold rim" beats "old mug." + +3. **Camera language = photorealism** — Including real camera specs (lens, aperture, camera model) pushes models toward photorealistic output. Use this for any photography-style generation. + +4. **Ignore quality modifiers** — Words like "4k", "ultra HD", "masterpiece", "best quality" are ignored by modern image models. They waste prompt space. Focus on describing WHAT you want instead. + +5. **Prompt length sweet spot** — 100–250 words is optimal. Enough detail to guide the model, not so much that it gets confused or ignores parts. + +6. **Background specification** — Always explicitly describe the background. "White background", "dark moody gradient", "blurred outdoor scene" — never leave it implied. + +7. **Transparent mode (`-t`) interaction** — When the user wants transparency, the script auto-injects green screen instructions. Your prompt should complement this by specifying an isolated subject with NO environment, shadows, reflections, or floor. Just the subject. + +8. **Editing mode (`-r`) interaction** — When reference images are provided, describe what to CHANGE, not the entire scene. "Change the background to a sunset" not "Create a photo of a mug on a table with a sunset background." The model sees the reference and needs edits, not a full new description. + +--- + +## Camera & Lens Specifications + +Use these when the category calls for photorealistic output (product_hero, lifestyle, food_drink, architecture, portrait). + +### By Purpose + +| Purpose | Camera | Lens | Aperture | Notes | +|---------|--------|------|----------|-------| +| Product hero shot | Sony A7R IV | 85mm macro | f/2.8 | Sharp detail, controlled blur | +| Product flat lay | Canon 5D Mark IV | 50mm | f/8 | Even sharpness across frame | +| Portrait / lifestyle | Sony A7III | 85mm | f/1.4–f/1.8 | Beautiful subject isolation | +| Wide lifestyle / scene | Sony A7III | 35mm | f/2.8 | Environmental context | +| Food & beverage | Canon R5 | 100mm macro | f/2.8 | Tight detail, creamy blur | +| Architecture / interior | Canon 5D | 24mm tilt-shift | f/11 | Corrected verticals, deep focus | +| Fashion editorial | Hasselblad 500C | 80mm | f/2.8 | Medium format aesthetic | + +### Aperture Guide + +| Aperture | Depth of Field | Best For | +|----------|---------------|----------| +| f/1.4–f/2.0 | Maximum background blur | Portraits, single product isolation | +| f/2.8–f/4.0 | Moderate depth | Lifestyle with context, food | +| f/5.6–f/8.0 | Deep focus | Flat lays, group product shots | +| f/11–f/16 | Maximum sharpness | Architecture, detailed arrays | + +--- + +## Lighting Setups + +Include lighting descriptions in prompts for photorealistic categories. Describe the EFFECT, not just the setup name. + +| Setup | Prompt Language | +|-------|----------------| +| **Single softbox key** | "Soft key light from upper-left casting gentle shadows that define the product's contours" | +| **Three-point** | "Key light at 45 degrees with fill light opposite and rim light from behind creating edge definition" | +| **Natural window** | "Soft diffused daylight from a large window, casting natural shadows across the scene" | +| **Dramatic single source** | "Hard directional spotlight creating deep shadows and a sense of luxury and mystery" | +| **Flat / even** | "Even, diffused studio lighting revealing every texture without harsh shadows" | +| **Golden hour** | "Warm low-angle golden hour sunlight streaming through, creating long shadows and warm pools of light" | +| **Studio HDRI** | "Even, controlled studio illumination with neutral color temperature" | + +### Film Stock as Aesthetic Shorthand + +Adding a film stock reference communicates an entire aesthetic in a few words: + +| Film Stock | Aesthetic Effect | +|-----------|-----------------| +| "Shot on Kodak Portra 400" | Warm skin tones, fine grain, soft pastel palette | +| "Shot on Fuji Pro 400H" | Cool greens, soft highlights, ethereal | +| "Shot on Kodak Ektar 100" | Ultra-saturated, vivid colors, fine grain | +| "Shot on Ilford HP5 Plus" | Black and white, contrasty, documentary feel | +| "Shot on CineStill 800T" | Cinematic tungsten tones, halation glow around highlights | + +--- + +## Text Rendering Rules + +AI image models can render text but need precise instructions for accuracy. + +### 7 Rules for 95%+ Text Accuracy + +1. **Always wrap text in quotation marks** — `"MEMENTO MORI"` not MEMENTO MORI +2. **Describe font style, not font name** — "bold condensed sans-serif" not "Bebas Neue" +3. **Specify placement** — "centered below the main graphic" or "upper-left corner" +4. **Keep text short** — Headlines under 5 words render most reliably +5. **Specify case explicitly** — "ALL-CAPS" or "lowercase" — don't assume +6. **For multiple text elements** — Describe hierarchy: "large headline above, smaller tagline below" +7. **Describe integration** — "text integrated into the design" vs "text overlaid on the image" + +### Font Style Descriptions + +Use these descriptions instead of font names: + +| Desired Look | Prompt Description | +|-------------|-------------------| +| Bebas / Futura | "bold condensed geometric sans-serif, ALL-CAPS" | +| Cloister Black | "ornate gothic blackletter with sharp serifs" | +| Helvetica Bold | "clean modern sans-serif, heavy weight" | +| Script / cursive | "flowing hand-written script with natural curves" | +| Distressed | "weathered, partially worn sans-serif with grunge texture" | +| Retro display | "rounded retro display font with 70s character" | +| Stencil | "military-style stencil lettering with characteristic gaps" | +| Minimal / light | "ultra-clean thin sans-serif, wide letter-spacing, lowercase" | +| Slab serif | "bold slab-serif with strong horizontal strokes" | + +--- + +## Model-Specific Recommendations + +| Category | Recommended Model | Why | +|----------|------------------|-----| +| product_hero, lifestyle | `gemini` or `gpt5` | Best photorealism, lighting accuracy | +| food_drink | `gemini` or `gpt5` | Macro detail, appetizing color | +| illustration, pod_design | `riverflow` or `flux2` | Artistic quality, clean lines | +| web_app, icon_logo | `gemini` | Clean output, good text rendering | +| social_media | `gemini` or `seedream` | Bold colors, visual impact | +| architecture | `gpt5` or `flux2` | Accurate perspective, materials | +| marketing_banner | `gemini` | Text rendering, layout control | +| infographic | `gemini` | Text accuracy, clean layout | + +When the user doesn't specify a model, default to `gemini` (most versatile). Suggest alternatives when a different model would produce notably better results for the detected category. diff --git a/.claude/skills/ai-image-creator/references/prompt-platforms.md b/.claude/skills/ai-image-creator/references/prompt-platforms.md new file mode 100644 index 0000000..b57e164 --- /dev/null +++ b/.claude/skills/ai-image-creator/references/prompt-platforms.md @@ -0,0 +1,95 @@ +# Platform & Format Specifications + +Aspect ratio mappings, ad format sizes, and print-on-demand specs. Read this when the user mentions a specific platform, ad format, or output dimension. + +--- + +## Social Media Aspect Ratios + +| Platform / Use | Aspect Ratio | `-a` Flag | `-s` Size | Prompt Hint | +|---------------|-------------|-----------|-----------|-------------| +| Instagram feed | 4:5 | `-a 4:5` | `-s 1K` | "vertical social post format" | +| Instagram story / Reels | 9:16 | `-a 9:16` | `-s 1K` | "vertical full-screen story format" | +| Instagram square | 1:1 | `-a 1:1` | `-s 1K` | "square format" | +| Facebook feed | 4:5 or 1:1 | `-a 4:5` | `-s 1K` | "social media feed format" | +| Facebook cover | 16:9 | `-a 16:9` | `-s 2K` | "widescreen cover format" | +| Pinterest pin | 2:3 | `-a 2:3` | `-s 1K` | "tall vertical pin format" | +| TikTok thumbnail | 9:16 | `-a 9:16` | `-s 1K` | "vertical video thumbnail format" | +| YouTube thumbnail | 16:9 | `-a 16:9` | `-s 2K` | "widescreen landscape format" | +| LinkedIn post | 1:1 or 4:5 | `-a 1:1` | `-s 1K` | "professional social post" | +| X / Twitter post | 16:9 | `-a 16:9` | `-s 1K` | "widescreen post format" | + +--- + +## Web / App Ad Formats (IAB Standard) + +Standard ad sizes mapped to the closest supported `-a` flag value. Most require post-generation cropping to exact pixel dimensions. + +| Ad Format | Pixels | Closest `-a` | `-s` Size | Post-Processing | +|-----------|--------|-------------|-----------|-----------------| +| Leaderboard | 728×90 | `-a 4:1` | `-s 1K` | Crop to 728×90 | +| Billboard | 970×250 | `-a 4:1` | `-s 2K` | Crop to 970×250 | +| Medium Rectangle | 300×250 | `-a 5:4` | `-s 1K` | Crop to 300×250 | +| Large Rectangle | 336×280 | `-a 5:4` | `-s 1K` | Crop to 336×280 | +| Half Page | 300×600 | `-a 1:2` † | `-s 1K` | Crop to 300×600 | +| Skyscraper | 160×600 | `-a 1:4` | `-s 1K` | Crop to 160×600 | +| Wide Skyscraper | 300×600 | `-a 1:2` † | `-s 1K` | Crop to 300×600 | +| Mobile Banner | 320×50 | `-a 4:1` | `-s 1K` | Crop to 320×50 | +| Mobile Interstitial | 320×480 | `-a 2:3` | `-s 1K` | Crop to 320×480 | + +† 1:2 may not be supported by all models. Use `-a 9:16` and crop as fallback. + +### Ad Format Prompt Tips + +- **Reserve negative space** for text overlay — "Product positioned in left third with large clean area on right for headline and CTA" +- **High contrast** at small sizes — ad banners are often viewed small; bold colors and clear focal points matter +- **CTA zone** — "Clear call-to-action zone in lower-right corner" +- **Brand consistency** — Specify brand colors by description: "deep navy blue and bright amber accent" + +--- + +## Standard Web Dimensions + +| Asset | Pixels | `-a` Flag | Notes | +|-------|--------|-----------|-------| +| OG / social share | 1200×630 | `-a 16:9` | Slight crop to 1200×630 | +| Favicon | 32×32, 16×16 | `-a 1:1` `-s 0.5K` | Generate larger, resize down with `magick -resize` | +| App icon (iOS) | 1024×1024 | `-a 1:1` `-s 1K` | Must be square, no transparency | +| App icon (Android) | 512×512 | `-a 1:1` `-s 1K` | Can include transparency with `-t` | +| Apple Touch icon | 180×180 | `-a 1:1` `-s 0.5K` | Generate larger, resize down | +| Email header | ~600×200 | `-a 3:1` † | Crop to exact width | +| Hero banner | 1920×600 | `-a 3:1` † | Or `-a 16:9` and crop height | +| Website logo | varies | `-a 3:1` or `-a 4:1` | Generate wide, trim to content | + +† 3:1 is not a standard `-a` flag value. Use `-a 21:9` (≈2.33:1) as closest option and crop. + +### Web Asset Prompt Tips + +- **Favicons/icons**: "Simple, recognizable silhouette at small size. Bold shape, maximum 2 colors, no fine detail." +- **OG images**: Include clear text area — social platforms overlay title and description. +- **Logos**: "Clean vector-style logo on solid background. Simple shapes, readable at 32px." +- **Hero banners**: Compose with text overlay in mind — push subject to one side. + +--- + +## Print-on-Demand Specs + +| Product | Print Area (px) | Aspect Ratio | `-a` Flag | Notes | +|---------|----------------|-------------|-----------|-------| +| T-shirt front | 4500×5400 | ~5:6 | `-a 4:5` | Center-chest or full-front placement | +| T-shirt back | 4500×5400 | ~5:6 | `-a 4:5` | Full back design | +| Mug wrap (11oz) | 2700×1100 | ~11:4.5 | `-a 21:9` | Wide horizontal, wraps around cylinder | +| Mug wrap (15oz) | 2700×1100 | ~11:4.5 | `-a 21:9` | Same wrap, slightly taller | +| Poster (18×24) | 5400×7200 | 3:4 | `-a 3:4` | Vertical orientation | +| Poster (24×36) | 7200×10800 | 2:3 | `-a 2:3` | Vertical orientation | +| Phone case | varies | ~9:19 | `-a 9:16` | Tall narrow, avoid bottom edge (camera cutout) | +| Tote bag | 3600×3600 | 1:1 | `-a 1:1` | Square print area | +| Sticker | varies | 1:1 | `-a 1:1` | Die-cut friendly: bold silhouette + `-t` for transparency | + +### POD Prompt Tips + +- **Always use solid background** for easy removal: pure black `#000000` or pure white `#FFFFFF` +- Or use `-t` (transparent mode) to generate with alpha channel directly +- **Sharp edges** between design and background — "no gradients, no ambient shadows, no noise at edges" +- **Print-ready isolation** — "design element isolated on [color] background, optimized for production printing" +- **T-shirt placement**: Describe collar reference — "positioned 3-4 inches below the neckline" not just "center" diff --git a/.claude/skills/ai-image-creator/scripts/generate-image.py b/.claude/skills/ai-image-creator/scripts/generate-image.py index 5fc1005..2f4b5f1 100644 --- a/.claude/skills/ai-image-creator/scripts/generate-image.py +++ b/.claude/skills/ai-image-creator/scripts/generate-image.py @@ -1123,6 +1123,27 @@ def main() -> None: total_elapsed = time.time() - total_start + # Save prompt alongside image as .prompt.md + prompt_path = output_path.with_suffix(".prompt.md") + try: + prompt_meta = f"# Prompt\n\n" + prompt_meta += f"- **Model:** {model}\n" + prompt_meta += f"- **Provider:** {args.provider} ({mode})\n" + if args.aspect_ratio: + prompt_meta += f"- **Aspect ratio:** {args.aspect_ratio}\n" + if args.image_size: + prompt_meta += f"- **Image size:** {args.image_size}\n" + if args.transparent: + prompt_meta += f"- **Transparent:** yes\n" + if ref_images: + prompt_meta += f"- **Reference images:** {', '.join(ref_images)}\n" + prompt_meta += f"- **Elapsed:** {total_elapsed:.1f}s\n" + prompt_meta += f"\n## Prompt Text\n\n{prompt}\n" + prompt_path.write_text(prompt_meta, encoding="utf-8") + log.info(f"Prompt saved: {prompt_path}") + except OSError as e: + log.warning(f"Could not save prompt file: {e}") + # Report success size_kb = len(image_bytes) / 1024 print(f"\nImage saved: {output_path} ({size_kb:.1f} KB)", file=sys.stderr) From 5a5a59d2e3b8cac113262204404d886d21e2e6b0 Mon Sep 17 00:00:00 2001 From: George Liu Date: Fri, 27 Mar 2026 06:39:28 +1000 Subject: [PATCH 101/174] Add composite banners and prompt enhancements to ai-image-creator skill Add composite-banners.py for offline ImageMagick-based multi-size logo compositing with config schema reference. Update SKILL.md with composite routing hints, prompt enhancement categories, and decision rules. Sync all 4 README variants with new features including transparent backgrounds, reference images, cost tracking, and fix stale model names in README-v4. --- .claude/skills/ai-image-creator/SKILL.md | 68 +- .../references/composite-reference.md | 165 ++++ .../scripts/composite-banners.py | 748 ++++++++++++++++++ README-v2.md | 2 +- README-v3.md | 2 +- README-v4.md | 13 +- README.md | 5 + 7 files changed, 996 insertions(+), 7 deletions(-) create mode 100644 .claude/skills/ai-image-creator/references/composite-reference.md create mode 100644 .claude/skills/ai-image-creator/scripts/composite-banners.py diff --git a/.claude/skills/ai-image-creator/SKILL.md b/.claude/skills/ai-image-creator/SKILL.md index 1400d28..8554df2 100644 --- a/.claude/skills/ai-image-creator/SKILL.md +++ b/.claude/skills/ai-image-creator/SKILL.md @@ -54,8 +54,9 @@ Professional prompt patterns are available in 3 reference files. These are **not | "product shot", "product photo", "hero image" | `product_hero` | `prompt-core.md` + `prompt-categories.md` § product_hero | | "lifestyle", "in-use", "in context" | `lifestyle` | `prompt-core.md` + `prompt-categories.md` § lifestyle | | "instagram", "social media", "tiktok", "pinterest" | `social_media` | `prompt-core.md` + `prompt-platforms.md` + `prompt-categories.md` § social_media | -| "banner", "ad", "email header" | `marketing_banner` | `prompt-core.md` + `prompt-platforms.md` + `prompt-categories.md` § marketing_banner | -| "website", "app", "logo", "ad format", "leaderboard", "skyscraper" | `web_app` | `prompt-core.md` + `prompt-platforms.md` + `prompt-categories.md` § web_app | +| "banner", "ad", "email header" | `marketing_banner` | `prompt-core.md` + `prompt-platforms.md` + `prompt-categories.md` § marketing_banner. **Routing hint:** If user has an existing logo and wants multiple standard sizes → use composite mode instead (see `## Composite Banners`). | +| "website", "app", "logo", "ad format", "leaderboard", "skyscraper" | `web_app` | `prompt-core.md` + `prompt-platforms.md` + `prompt-categories.md` § web_app. **Routing hint:** For "logo banners" or "OG images with my logo" where user has existing logo → use `composite-banners.py`. For "design me a new logo" → use `generate-image.py`. | +| "brand kit", "logo banners", "banner sizes", "IAB sizes", "consistent banners" + user has existing logo | `composite` | Read `references/composite-reference.md`, use `composite-banners.py` | | "icon", "favicon", "app icon" | `icon_logo` | `prompt-core.md` + `prompt-categories.md` § icon_logo | | "mascot", "character", "illustration", "artwork" | `illustration` | `prompt-core.md` + `prompt-categories.md` § illustration | | "food", "drink", "recipe", "restaurant" | `food_drink` | `prompt-core.md` + `prompt-categories.md` § food_drink | @@ -216,6 +217,69 @@ Shows per-model breakdown: generation count, total tokens, elapsed time, and rec Consider adding `.ai-image-creator/` to your `.gitignore`. +## Composite Banners + +Generate consistent logo banners across multiple sizes from a JSON config. Uses ImageMagick for offline compositing — no API calls, no network required. Composites an existing logo/mark onto branded backgrounds with text at standard dimensions. + +### Composite vs. AI Generation — Decision Rule + +Use **composite-banners.py** when ALL of these are true: +- User has an existing logo/mark they want to use as-is (provides or references a logo file) +- User wants consistent branding across multiple standard sizes (not one creative image) +- The output is logo + text on a solid/gradient background (not a photograph, illustration, or creative design) + +Use **generate-image.py** (AI generation) when ANY of these are true: +- User wants a creative/artistic banner design (describes a scene, mood, concept, or style) +- User wants AI to design the visual content (product shots, illustrations, creative layouts) +- User wants a single banner with artistic content, not a multi-size brand kit + +**When composite mode applies**, read `references/composite-reference.md` for full config schema, preset dimensions, and font handling details. + +### Quick Start + +1. **Init config:** `uv run python ${CLAUDE_SKILL_DIR}/scripts/composite-banners.py --init` +2. **Edit** `banner-config.json` — set logo path, brand text, colors, banner sizes +3. **Validate:** `uv run python ${CLAUDE_SKILL_DIR}/scripts/composite-banners.py --validate` +4. **Generate:** `uv run python ${CLAUDE_SKILL_DIR}/scripts/composite-banners.py -c banner-config.json -o ./banners/` + +### Composite Parameters + +| Argument | Short | Default | Description | +|----------|-------|---------|-------------| +| `--config` | `-c` | `banner-config.json` | Config JSON path | +| `--output-dir` | `-o` | `.` | Output directory | +| `--name` | `-n` | all | Generate single banner by name | +| `--format` | `-f` | `png` | `png`, `webp`, `jpeg` | +| `--list-presets` | | | List IAB/social/web size presets | +| `--init` | | | Generate starter config | +| `--validate` | | | Check config, exit 0 or 2 | +| `--dry-run` | | | Preview without rendering | +| `--json` | | | Structured JSON to stdout | +| `--verbose` | `-v` | | Verbose output | + +**Requirements:** ImageMagick 7 (`brew install imagemagick` or `apt install imagemagick`). + +### Workflow Hints + +**Starting composite mode:** +- Ask user for: logo file path, brand name, tagline text, brand colors (hex) +- If user doesn't have a logo yet → use generate-image.py to create one first +- Run `--init` to scaffold config, then help user fill in their brand values + +**During generation:** +- Always run `--validate` before generating to catch font/logo issues early +- Use `--name` to iterate on one banner before generating the full set +- Show user 3-4 representative sizes (hero, OG, square, leaderboard) for approval + +**After generation:** +- If user wants creative/artistic redesign of banner visuals → switch to generate-image.py (composite only does logo + text on gradient/solid backgrounds) +- If banners look too plain → suggest AI-generating a textured or photographic background first, then compositing the logo onto it + +**Combined workflow (most powerful):** +1. Use generate-image.py to AI-create a hero background or textured pattern +2. Use composite-banners.py to overlay the logo + text onto that background at all standard sizes +This gives both creative AI visuals AND pixel-perfect logo consistency. + ## Image Tools On first invocation, detect available image manipulation tools: diff --git a/.claude/skills/ai-image-creator/references/composite-reference.md b/.claude/skills/ai-image-creator/references/composite-reference.md new file mode 100644 index 0000000..258de8b --- /dev/null +++ b/.claude/skills/ai-image-creator/references/composite-reference.md @@ -0,0 +1,165 @@ +# Composite Banners — Reference + +Full config schema, presets, font handling, and workflow details for `composite-banners.py`. Read this when composite mode is detected (user has existing logo + wants multiple standard sizes). + +--- + +## Config File Schema + +The config JSON has four top-level sections: `logo`, `brand`, `fonts`, `banners`. + +### `logo` — Source image and extraction mode + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `path` | string | `"logo.png"` | Path to logo image, **relative to the config file's directory** | +| `mode` | string | `"full"` | `"full"` = use entire image; `"extract"` = crop a sub-region | +| `crop` | object | — | `{"x", "y", "w", "h"}` pixel coordinates (required when `mode="extract"`) | +| `background` | string | `"white"` | `"white"` = remove white bg with fuzz; `"transparent"` = already has alpha; `"none"` = use as-is | +| `fuzz` | string | `"15%"` | ImageMagick fuzz tolerance for white background removal | +| `aspect_ratio` | array\|null | `null` | `[width, height]` explicit ratio, or `null` to auto-detect from image dimensions | + +**When to use each mode:** +- `"full"` — Most common. Your logo is already the complete mark you want on banners. No cropping needed. +- `"extract"` — Your logo file contains a larger image (e.g., logo + text + whitespace) and you want to crop to just the icon/mark portion. Provide pixel coordinates in `crop`. + +**When to use each background option:** +- `"white"` — Logo is on a white background (common for downloaded logos). The script removes white pixels with fuzz tolerance. +- `"transparent"` — Logo PNG already has an alpha channel. Skip background removal entirely. +- `"none"` — Use the image exactly as-is, including its background. Useful for logos on colored backgrounds you want to keep. + +### `brand` — Text content and colors + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `title` | string | required | Primary text (brand name). Rendered in title font. | +| `tagline` | string | `""` | Secondary text below/beside title | +| `url_text` | string\|null | `null` | Optional 3rd line (website URL, CTA). `null` to disable. | +| `title_color` | hex string | `"#ffffff"` | Title text color | +| `tagline_color` | hex string | `"#b0b8cc"` | Tagline text color | +| `url_color` | hex string | `"#8090aa"` | URL text color | +| `background` | object | — | Gradient: `{"start": "#hex", "end": "#hex"}` or solid: `{"color": "#hex"}` | + +### `fonts` — Ordered fallback lists + +Each role has an array of font candidates. The script tries each in order and uses the first available on the system. Supports both ImageMagick font names and absolute file paths. + +```json +"fonts": { + "title": ["Arial-Bold", "DejaVu-Sans-Bold", "Liberation-Sans-Bold"], + "tagline": ["Arial", "DejaVu-Sans", "Liberation-Sans"], + "url": ["Arial", "DejaVu-Sans", "Liberation-Sans"] +} +``` + +**How resolution works:** +1. Script calls `magick -list font` once (cached) to get all system fonts +2. For each candidate: if it starts with `/`, checks file exists; otherwise checks the font name set +3. Uses the first match, warns to stderr if it fell back from the preferred font +4. Exits with error if no font is found for `title` or `tagline` + +**Cross-platform defaults:** +- macOS: `Arial-Bold`, `Helvetica-Neue-Condensed-Bold`, `Avenir-Next-Condensed-Heavy` +- Linux: `DejaVu-Sans-Bold`, `Liberation-Sans-Bold` +- Both: `Arial-Bold` (usually available on both via fontconfig) + +Run `magick -list font | grep Font:` to see available fonts on your system. + +### `banners` — Array of banner definitions + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `name` | string | required | Output filename (without extension). Must be unique. | +| `width` | int | required | Banner width in pixels | +| `height` | int | required | Banner height in pixels | +| `category` | string | `""` | Grouping label for display (e.g., `"iab"`, `"social"`, `"website"`) | +| `layout` | string | required | `"horizontal"`, `"horizontal-compact"`, or `"centered"` | +| `logo_height_pct` | number | varies | Logo height as percentage of banner height | +| `title_size_pct` | number | varies | Title font size as percentage of banner height | +| `tagline_size_pct` | number | `0` | Tagline font size as percentage. `0` = omit tagline. | +| `url_size_pct` | number | `0` | URL text font size as percentage. `0` = omit URL. | + +--- + +## Layout Types + +### `horizontal` — Logo left, text right +Best for: wide banners (hero, billboard, social covers, email headers). +Logo positioned on the left with padding, title + tagline + optional URL stacked vertically to the right. + +### `horizontal-compact` — Single-line icon + title +Best for: ultra-thin banners (leaderboard 728x90, mobile 320x50). +Logo icon and title on one line. Tagline to the right of title if space allows. + +### `centered` — Logo above, text below +Best for: square/portrait formats (OG images, square logos, half-page ads, skyscrapers). +Logo centered above, title + tagline + optional URL centered below in a vertical stack. + +--- + +## Preset Dimensions + +Run `--list-presets` to see all available presets with recommended layouts and sizing. These are reference values — copy the dimensions and layout into your config's `banners` array. + +### IAB Standard Ad Sizes +| Preset | Pixels | Layout | +|--------|--------|--------| +| `iab-leaderboard` | 728x90 | horizontal-compact | +| `iab-billboard` | 970x250 | horizontal | +| `iab-medium-rectangle` | 300x250 | centered | +| `iab-large-rectangle` | 336x280 | centered | +| `iab-half-page` | 300x600 | centered | +| `iab-skyscraper` | 160x600 | centered | +| `iab-mobile-banner` | 320x50 | horizontal-compact | +| `iab-mobile-interstitial` | 320x480 | centered | + +### Social Media +| Preset | Pixels | Layout | +|--------|--------|--------| +| `social-twitter-header` | 1500x500 | horizontal | +| `social-linkedin-banner` | 1584x396 | horizontal | +| `social-facebook-cover` | 1640x624 | horizontal | +| `social-youtube-banner` | 2560x1440 | centered | + +### Web Assets +| Preset | Pixels | Layout | +|--------|--------|--------| +| `web-hero` | 1920x600 | horizontal | +| `web-og-social` | 1200x630 | centered | +| `web-email-header` | 600x200 | horizontal | +| `web-square-logo` | 512x512 | centered | +| `web-favicon` | 256x256 | centered | + +--- + +## Combined Workflow: AI + Composite + +The most powerful workflow uses both scripts together: + +1. **AI-generate** a creative background or textured pattern: + ```bash + uv run python SCRIPT_PATH/generate-image.py \ + -o "hero-bg.png" -a "16:9" -s "2K" \ + -p "Abstract dark gradient with subtle geometric tech patterns, deep navy to indigo" + ``` + +2. **Create a banner config** pointing to your logo with your brand details + +3. **Composite** the logo + text onto branded backgrounds at all standard sizes: + ```bash + uv run python SCRIPT_PATH/composite-banners.py \ + -c banner-config.json -o ./banners/ --json + ``` + +This gives both creative AI visuals AND pixel-perfect logo consistency across all sizes. + +--- + +## After Generation — Next Steps + +- **Banners look too plain:** Suggest generating an AI background with `generate-image.py` and using it as a background in the composite config (the config's gradient background can be swapped for a richer visual). +- **Color inconsistency between banners:** This is the exact problem composite mode solves. If you see inconsistency, banners may be mixing AI-generated and composite outputs. Regenerate all from one config. +- **Want to change brand colors:** Edit `brand.background` and `brand.*_color` values, then regenerate. All banners update consistently in one run. +- **Need different sizes:** Run `--list-presets` to see standard sizes. Add entries to the `banners` array. +- **Iterate on one banner:** Use `--name banner-name` to regenerate just that one without re-rendering all. +- **Need WebP for web performance:** Use `--format webp` to output all banners as WebP instead of PNG. diff --git a/.claude/skills/ai-image-creator/scripts/composite-banners.py b/.claude/skills/ai-image-creator/scripts/composite-banners.py new file mode 100644 index 0000000..618ec14 --- /dev/null +++ b/.claude/skills/ai-image-creator/scripts/composite-banners.py @@ -0,0 +1,748 @@ +# /// script +# requires-python = ">=3.10" +# dependencies = [] +# /// +"""Composite logo banners from JSON config using ImageMagick. + +Generates pixel-perfect, color-consistent logo banners across multiple +standard sizes (IAB ads, social media headers, web assets). Composites +an existing logo/mark onto gradient or solid backgrounds with text. + +No API calls, no network required — pure offline ImageMagick compositing. + +Usage: + uv run --script composite-banners.py --init + uv run --script composite-banners.py --validate + uv run --script composite-banners.py -c banner-config.json -o ./banners/ + uv run --script composite-banners.py -c banner-config.json -o ./banners/ -n hero-1920x600 + uv run --script composite-banners.py --list-presets +""" + +from __future__ import annotations + +import argparse +import json +import logging +import re +import shutil +import subprocess +import sys +import tempfile +import time +from pathlib import Path + +log = logging.getLogger("composite-banners") + +# ── Preset dimensions (IAB / Social / Web) ───────────────────────────── + +PRESET_DIMENSIONS = { + # IAB Standard Ad Sizes + "iab-leaderboard": {"w": 728, "h": 90, "cat": "iab", "layout": "horizontal-compact", + "logo_height_pct": 80, "title_size_pct": 38, "tagline_size_pct": 18}, + "iab-billboard": {"w": 970, "h": 250, "cat": "iab", "layout": "horizontal", + "logo_height_pct": 70, "title_size_pct": 16, "tagline_size_pct": 8}, + "iab-medium-rectangle": {"w": 300, "h": 250, "cat": "iab", "layout": "centered", + "logo_height_pct": 45, "title_size_pct": 10, "tagline_size_pct": 5.5}, + "iab-large-rectangle": {"w": 336, "h": 280, "cat": "iab", "layout": "centered", + "logo_height_pct": 45, "title_size_pct": 10, "tagline_size_pct": 5}, + "iab-half-page": {"w": 300, "h": 600, "cat": "iab", "layout": "centered", + "logo_height_pct": 30, "title_size_pct": 7, "tagline_size_pct": 4}, + "iab-skyscraper": {"w": 160, "h": 600, "cat": "iab", "layout": "centered", + "logo_height_pct": 18, "title_size_pct": 3.2, "tagline_size_pct": 2}, + "iab-mobile-banner": {"w": 320, "h": 50, "cat": "iab", "layout": "horizontal-compact", + "logo_height_pct": 80, "title_size_pct": 40, "tagline_size_pct": 0}, + "iab-mobile-interstitial": {"w": 320, "h": 480, "cat": "iab", "layout": "centered", + "logo_height_pct": 35, "title_size_pct": 8, "tagline_size_pct": 4}, + # Social Media + "social-twitter-header": {"w": 1500, "h": 500, "cat": "social", "layout": "horizontal", + "logo_height_pct": 65, "title_size_pct": 12, "tagline_size_pct": 6}, + "social-linkedin-banner": {"w": 1584, "h": 396, "cat": "social", "layout": "horizontal", + "logo_height_pct": 65, "title_size_pct": 14, "tagline_size_pct": 7}, + "social-facebook-cover": {"w": 1640, "h": 624, "cat": "social", "layout": "horizontal", + "logo_height_pct": 60, "title_size_pct": 11, "tagline_size_pct": 5.5}, + "social-youtube-banner": {"w": 2560, "h": 1440, "cat": "social", "layout": "centered", + "logo_height_pct": 35, "title_size_pct": 6, "tagline_size_pct": 3}, + # Web Assets + "web-hero": {"w": 1920, "h": 600, "cat": "website", "layout": "horizontal", + "logo_height_pct": 65, "title_size_pct": 12, "tagline_size_pct": 6}, + "web-og-social": {"w": 1200, "h": 630, "cat": "website", "layout": "centered", + "logo_height_pct": 45, "title_size_pct": 8, "tagline_size_pct": 4}, + "web-email-header": {"w": 600, "h": 200, "cat": "website", "layout": "horizontal", + "logo_height_pct": 70, "title_size_pct": 18, "tagline_size_pct": 9}, + "web-square-logo": {"w": 512, "h": 512, "cat": "website", "layout": "centered", + "logo_height_pct": 45, "title_size_pct": 9, "tagline_size_pct": 5}, + "web-favicon": {"w": 256, "h": 256, "cat": "website", "layout": "centered", + "logo_height_pct": 55, "title_size_pct": 10, "tagline_size_pct": 5}, +} + +# ── Starter config template ──────────────────────────────────────────── + +STARTER_CONFIG = """{ + "logo": { + "path": "logo.png", + "mode": "full", + "crop": {"x": 0, "y": 0, "w": 200, "h": 100}, + "background": "white", + "fuzz": "15%", + "aspect_ratio": null + }, + "brand": { + "title": "MY BRAND", + "tagline": "YOUR TAGLINE HERE", + "url_text": null, + "title_color": "#ffffff", + "tagline_color": "#b0b8cc", + "url_color": "#8090aa", + "background": {"start": "#1a1f3a", "end": "#2d1b4e"} + }, + "fonts": { + "title": ["Arial-Bold", "DejaVu-Sans-Bold", "Liberation-Sans-Bold"], + "tagline": ["Arial", "DejaVu-Sans", "Liberation-Sans"], + "url": ["Arial", "DejaVu-Sans", "Liberation-Sans"] + }, + "banners": [ + { + "name": "hero-1920x600", + "width": 1920, "height": 600, + "category": "website", + "layout": "horizontal", + "logo_height_pct": 65, + "title_size_pct": 12, + "tagline_size_pct": 6, + "url_size_pct": 3 + }, + { + "name": "og-social-1200x630", + "width": 1200, "height": 630, + "category": "website", + "layout": "centered", + "logo_height_pct": 45, + "title_size_pct": 8, + "tagline_size_pct": 4, + "url_size_pct": 2.5 + }, + { + "name": "square-logo-512x512", + "width": 512, "height": 512, + "category": "website", + "layout": "centered", + "logo_height_pct": 45, + "title_size_pct": 9, + "tagline_size_pct": 5, + "url_size_pct": 0 + } + ] +} +""" + +HEX_COLOR_RE = re.compile(r"^#[0-9a-fA-F]{6}$") +VALID_LAYOUTS = {"horizontal", "horizontal-compact", "centered"} + + +# ── ImageMagick helpers ──────────────────────────────────────────────── + +def find_magick() -> str: + path = shutil.which("magick") + if not path: + print("ERROR: ImageMagick 7 not found. Install: brew install imagemagick (macOS) " + "or apt install imagemagick (Linux)", file=sys.stderr) + sys.exit(1) + return path + + +_font_cache: set[str] | None = None + + +def _get_available_system_fonts(magick: str) -> set[str]: + global _font_cache + if _font_cache is not None: + return _font_cache + try: + result = subprocess.run([magick, "-list", "font"], capture_output=True, text=True, timeout=10) + fonts = set() + for line in result.stdout.splitlines(): + line = line.strip() + if line.startswith("Font:"): + fonts.add(line.split(":", 1)[1].strip()) + _font_cache = fonts + log.debug(f"Found {len(fonts)} system fonts") + return fonts + except (subprocess.TimeoutExpired, OSError) as e: + log.warning(f"Could not list fonts: {e}") + _font_cache = set() + return _font_cache + + +def detect_available_font(candidates: list[str], magick: str) -> str | None: + system_fonts = _get_available_system_fonts(magick) + for candidate in candidates: + if candidate.startswith("/"): + if Path(candidate).exists(): + log.debug(f"Font file found: {candidate}") + return candidate + elif candidate in system_fonts: + log.debug(f"System font found: {candidate}") + return candidate + return None + + +def resolve_fonts(fonts_config: dict, magick: str) -> dict[str, str]: + resolved = {} + for role in ("title", "tagline", "url"): + candidates = fonts_config.get(role, []) + if not candidates: + candidates = ["Arial-Bold"] if role == "title" else ["Arial"] + found = detect_available_font(candidates, magick) + if found: + if found != candidates[0]: + log.warning(f"Font fallback for {role}: using '{found}' (preferred '{candidates[0]}' not available)") + resolved[role] = found + else: + print(f"ERROR: No available font for '{role}'. Tried: {candidates}", file=sys.stderr) + print(" Run `magick -list font` to see available fonts.", file=sys.stderr) + sys.exit(1) + return resolved + + +def run_magick(cmd: list[str], check: bool = True) -> subprocess.CompletedProcess: + log.debug(f"Running: {' '.join(cmd)}") + result = subprocess.run(cmd, capture_output=True, text=True) + if check and result.returncode != 0: + log.error(f"ImageMagick failed: {result.stderr.strip()}") + raise RuntimeError(f"magick command failed: {result.stderr.strip()}") + return result + + +def get_image_dimensions(path: Path, magick: str) -> tuple[int, int]: + result = subprocess.run( + [magick, "identify", "-format", "%w %h", str(path)], + capture_output=True, text=True, + ) + if result.returncode != 0: + raise RuntimeError(f"Cannot read image dimensions: {path}") + parts = result.stdout.strip().split() + return int(parts[0]), int(parts[1]) + + +# ── Config loading & validation ──────────────────────────────────────── + +def resolve_logo_path(config_path: Path, logo_rel: str) -> Path: + return (config_path.parent / logo_rel).resolve() + + +def load_config(config_path: Path) -> dict: + try: + config = json.loads(config_path.read_text(encoding="utf-8")) + except (json.JSONDecodeError, OSError) as e: + print(f"ERROR: Cannot read config: {e}", file=sys.stderr) + sys.exit(2) + + logo_cfg = config.get("logo", {}) + logo_cfg["_resolved_path"] = resolve_logo_path(config_path, logo_cfg.get("path", "logo.png")) + config["logo"] = logo_cfg + return config + + +def validate_config(config: dict, magick: str) -> list[str]: + errors = [] + warnings = [] + + # Logo + logo = config.get("logo", {}) + logo_path = logo.get("_resolved_path") + if logo_path and not logo_path.exists(): + errors.append(f"Logo not found: {logo_path}") + mode = logo.get("mode", "full") + if mode not in ("full", "extract"): + errors.append(f"Invalid logo.mode: '{mode}' (must be 'full' or 'extract')") + if mode == "extract": + crop = logo.get("crop", {}) + for k in ("x", "y", "w", "h"): + if k not in crop: + errors.append(f"logo.crop missing key '{k}' (required for mode='extract')") + bg = logo.get("background", "white") + if bg not in ("white", "transparent", "none"): + errors.append(f"Invalid logo.background: '{bg}'") + + # Brand + brand = config.get("brand", {}) + if not brand.get("title"): + errors.append("brand.title is required") + for color_key in ("title_color", "tagline_color", "url_color"): + val = brand.get(color_key, "") + if val and not HEX_COLOR_RE.match(val): + errors.append(f"Invalid hex color for brand.{color_key}: '{val}'") + bg_cfg = brand.get("background", {}) + if "start" in bg_cfg and "end" in bg_cfg: + for k in ("start", "end"): + if not HEX_COLOR_RE.match(bg_cfg[k]): + errors.append(f"Invalid hex color for brand.background.{k}: '{bg_cfg[k]}'") + elif "color" in bg_cfg: + if not HEX_COLOR_RE.match(bg_cfg["color"]): + errors.append(f"Invalid hex color for brand.background.color: '{bg_cfg['color']}'") + else: + errors.append("brand.background must have 'start'+'end' (gradient) or 'color' (solid)") + + # Fonts + fonts_cfg = config.get("fonts", {}) + for role in ("title", "tagline"): + candidates = fonts_cfg.get(role, []) + if candidates: + found = detect_available_font(candidates, magick) + if not found: + errors.append(f"No available font for '{role}'. Tried: {candidates}") + elif found != candidates[0]: + warnings.append(f"Font fallback for {role}: '{found}' (preferred '{candidates[0]}' unavailable)") + else: + warnings.append(f"No fonts configured for '{role}', will use defaults") + + # Banners + banners = config.get("banners", []) + names = set() + for i, b in enumerate(banners): + name = b.get("name", "") + if not name: + errors.append(f"Banner [{i}] missing 'name'") + elif name in names: + errors.append(f"Duplicate banner name: '{name}'") + names.add(name) + for dim in ("width", "height"): + val = b.get(dim, 0) + if not isinstance(val, (int, float)) or val <= 0: + errors.append(f"Banner '{name}': {dim} must be > 0") + layout = b.get("layout", "") + if layout not in VALID_LAYOUTS: + errors.append(f"Banner '{name}': invalid layout '{layout}' (must be one of {VALID_LAYOUTS})") + + return errors + [f"WARNING: {w}" for w in warnings] + + +# ── Logo extraction ──────────────────────────────────────────────────── + +def extract_logo_mark(logo_path: Path, logo_config: dict, tmp_dir: Path, magick: str) -> tuple[Path, tuple[float, float]]: + mode = logo_config.get("mode", "full") + bg_mode = logo_config.get("background", "white") + fuzz = logo_config.get("fuzz", "15%") + + processed = tmp_dir / "logo-processed.png" + + if bg_mode == "white": + run_magick([magick, str(logo_path), "-fuzz", fuzz, "-transparent", "white", str(processed)]) + elif bg_mode == "transparent": + shutil.copy2(logo_path, processed) + else: # "none" + shutil.copy2(logo_path, processed) + + if mode == "extract": + crop = logo_config.get("crop", {}) + geometry = f"{crop['w']}x{crop['h']}+{crop['x']}+{crop['y']}" + cropped = tmp_dir / "logo-cropped.png" + run_magick([magick, str(processed), "-crop", geometry, "+repage", str(cropped)]) + processed = cropped + + # Determine aspect ratio + ar = logo_config.get("aspect_ratio") + if ar and isinstance(ar, (list, tuple)) and len(ar) == 2: + aspect = (float(ar[0]), float(ar[1])) + else: + w, h = get_image_dimensions(processed, magick) + aspect = (float(w), float(h)) + log.info(f"Auto-detected logo aspect ratio: {w}:{h}") + + return processed, aspect + + +# ── Background helpers ───────────────────────────────────────────────── + +def make_bg_spec(bg_config: dict) -> str: + if "start" in bg_config and "end" in bg_config: + return f"gradient:{bg_config['start']}-{bg_config['end']}" + return f"xc:{bg_config.get('color', '#1a1f3a')}" + + +# ── Layout renderers ─────────────────────────────────────────────────── + +def render_horizontal(banner: dict, brand: dict, fonts: dict, logo_path: Path, + logo_aspect: tuple[float, float], magick: str, output: Path): + w, h = banner["width"], banner["height"] + logo_h = int(h * banner.get("logo_height_pct", 65) / 100) + title_size = max(10, int(h * banner.get("title_size_pct", 12) / 100)) + tagline_size = max(8, int(h * banner.get("tagline_size_pct", 0) / 100)) + url_size = max(0, int(h * banner.get("url_size_pct", 0) / 100)) + + logo_pad_left = int(w * 0.04) + logo_pad_top = (h - logo_h) // 2 + logo_w = int(logo_h * (logo_aspect[0] / logo_aspect[1])) + text_x = logo_pad_left + logo_w + int(w * 0.03) + text_center_y = h // 2 + + bg_spec = make_bg_spec(brand.get("background", {})) + cmd = [ + magick, + "-size", f"{w}x{h}", bg_spec, + "(", str(logo_path), "-resize", f"x{logo_h}", ")", + "-gravity", "NorthWest", + "-geometry", f"+{logo_pad_left}+{logo_pad_top}", + "-composite", + "-font", fonts["title"], + "-pointsize", str(title_size), + "-fill", brand.get("title_color", "#ffffff"), + "-gravity", "NorthWest", + "-annotate", f"+{text_x}+{text_center_y - title_size}", + brand.get("title", ""), + ] + + if tagline_size > 0 and banner.get("tagline_size_pct", 0) > 0: + cmd.extend([ + "-font", fonts["tagline"], + "-pointsize", str(tagline_size), + "-fill", brand.get("tagline_color", "#b0b8cc"), + "-gravity", "NorthWest", + "-annotate", f"+{text_x}+{text_center_y + int(title_size * 0.3)}", + brand.get("tagline", ""), + ]) + + url_text = brand.get("url_text") + if url_text and url_size > 0 and banner.get("url_size_pct", 0) > 0: + url_y = text_center_y + int(title_size * 0.3) + tagline_size + int(h * 0.02) + cmd.extend([ + "-font", fonts.get("url", fonts["tagline"]), + "-pointsize", str(url_size), + "-fill", brand.get("url_color", "#8090aa"), + "-gravity", "NorthWest", + "-annotate", f"+{text_x}+{url_y}", + url_text, + ]) + + cmd.append(str(output)) + run_magick(cmd) + + +def render_horizontal_compact(banner: dict, brand: dict, fonts: dict, logo_path: Path, + logo_aspect: tuple[float, float], magick: str, output: Path): + w, h = banner["width"], banner["height"] + logo_h = int(h * banner.get("logo_height_pct", 80) / 100) + title_size = max(8, int(h * banner.get("title_size_pct", 38) / 100)) + tagline_size = max(0, int(h * banner.get("tagline_size_pct", 0) / 100)) + + logo_pad = int(h * 0.1) + logo_w = int(logo_h * (logo_aspect[0] / logo_aspect[1])) + text_x = logo_pad + logo_w + int(w * 0.02) + text_y = (h - title_size) // 2 + int(title_size * 0.75) + + bg_spec = make_bg_spec(brand.get("background", {})) + cmd = [ + magick, + "-size", f"{w}x{h}", bg_spec, + "(", str(logo_path), "-resize", f"x{logo_h}", ")", + "-gravity", "NorthWest", + "-geometry", f"+{logo_pad}+{(h - logo_h) // 2}", + "-composite", + "-font", fonts["title"], + "-pointsize", str(title_size), + "-fill", brand.get("title_color", "#ffffff"), + "-gravity", "NorthWest", + "-annotate", f"+{text_x}+{text_y}", + brand.get("title", ""), + ] + + if tagline_size > 0 and banner.get("tagline_size_pct", 0) > 0: + tagline_x = text_x + int(title_size * len(brand.get("title", "")) * 0.55) + int(w * 0.02) + cmd.extend([ + "-font", fonts["tagline"], + "-pointsize", str(tagline_size), + "-fill", brand.get("tagline_color", "#b0b8cc"), + "-gravity", "NorthWest", + "-annotate", f"+{tagline_x}+{(h - tagline_size) // 2 + int(tagline_size * 0.75)}", + brand.get("tagline", ""), + ]) + + cmd.append(str(output)) + run_magick(cmd) + + +def render_centered(banner: dict, brand: dict, fonts: dict, logo_path: Path, + logo_aspect: tuple[float, float], magick: str, output: Path): + _ = logo_aspect # interface consistency with horizontal renderers; centered uses -gravity North + w, h = banner["width"], banner["height"] + logo_h = int(h * banner.get("logo_height_pct", 45) / 100) + title_size = max(10, int(h * banner.get("title_size_pct", 8) / 100)) + tagline_size = max(8, int(h * banner.get("tagline_size_pct", 4) / 100)) + url_size = max(0, int(h * banner.get("url_size_pct", 0) / 100)) + + url_text = brand.get("url_text") + has_url = url_text and url_size > 0 and banner.get("url_size_pct", 0) > 0 + + total_h = logo_h + int(h * 0.04) + title_size + int(h * 0.02) + tagline_size + if has_url: + total_h += int(h * 0.015) + url_size + start_y = max(int(h * 0.08), (h - total_h) // 2) + + logo_y = start_y + title_y = logo_y + logo_h + int(h * 0.04) + tagline_y = title_y + title_size + int(h * 0.015) + + bg_spec = make_bg_spec(brand.get("background", {})) + cmd = [ + magick, + "-size", f"{w}x{h}", bg_spec, + "(", str(logo_path), "-resize", f"x{logo_h}", ")", + "-gravity", "North", + "-geometry", f"+0+{logo_y}", + "-composite", + "-font", fonts["title"], + "-pointsize", str(title_size), + "-fill", brand.get("title_color", "#ffffff"), + "-gravity", "North", + "-annotate", f"+0+{title_y}", + brand.get("title", ""), + "-font", fonts["tagline"], + "-pointsize", str(tagline_size), + "-fill", brand.get("tagline_color", "#b0b8cc"), + "-gravity", "North", + "-annotate", f"+0+{tagline_y}", + brand.get("tagline", ""), + ] + + if has_url: + url_y = tagline_y + tagline_size + int(h * 0.015) + cmd.extend([ + "-font", fonts.get("url", fonts["tagline"]), + "-pointsize", str(url_size), + "-fill", brand.get("url_color", "#8090aa"), + "-gravity", "North", + "-annotate", f"+0+{url_y}", + url_text, + ]) + + cmd.append(str(output)) + run_magick(cmd) + + +LAYOUT_FUNCS = { + "horizontal": render_horizontal, + "horizontal-compact": render_horizontal_compact, + "centered": render_centered, +} + + +# ── Format conversion ────────────────────────────────────────────────── + +def convert_format(png_path: Path, fmt: str, magick: str) -> Path: + if fmt == "png": + return png_path + ext = {"webp": ".webp", "jpeg": ".jpeg", "jpg": ".jpeg"}.get(fmt, f".{fmt}") + out_path = png_path.with_suffix(ext) + quality_args = [] + if fmt in ("webp",): + quality_args = ["-quality", "90"] + elif fmt in ("jpeg", "jpg"): + quality_args = ["-quality", "95"] + run_magick([magick, str(png_path)] + quality_args + [str(out_path)]) + png_path.unlink() + return out_path + + +# ── Utility commands ─────────────────────────────────────────────────── + +def list_presets(): + print("\nAvailable dimension presets:") + print(f"{'Preset':<30} {'Size':>10} {'Category':<8} Layout") + print("-" * 72) + for cat in ("iab", "social", "website"): + for name, p in sorted(PRESET_DIMENSIONS.items()): + if p["cat"] == cat: + print(f" {name:<28} {p['w']:>4}x{p['h']:<4} {p['cat']:<8} {p['layout']}") + print() + + +def init_config(output_path: Path): + if output_path.exists(): + print(f"ERROR: {output_path} already exists. Remove it first or use a different path.", file=sys.stderr) + sys.exit(2) + output_path.write_text(STARTER_CONFIG, encoding="utf-8") + print(f"Created starter config: {output_path}", file=sys.stderr) + print("Edit it with your logo path, brand text, and colors, then run --validate.", file=sys.stderr) + + +# ── Main ─────────────────────────────────────────────────────────────── + +def main(): + parser = argparse.ArgumentParser( + description="Generate consistent logo banners from JSON config using ImageMagick", + epilog="Run --list-presets to see available IAB/social/web dimension presets.", + ) + parser.add_argument("--config", "-c", default="banner-config.json", help="Path to config JSON (default: banner-config.json)") + parser.add_argument("--output-dir", "-o", default=".", help="Output directory (default: current dir)") + parser.add_argument("--name", "-n", help="Generate only this banner (by name)") + parser.add_argument("--format", "-f", default="png", choices=["png", "webp", "jpeg"], help="Output format (default: png)") + parser.add_argument("--list-presets", action="store_true", help="List available dimension presets and exit") + parser.add_argument("--init", action="store_true", help="Generate starter banner-config.json and exit") + parser.add_argument("--validate", action="store_true", help="Validate config and exit (0=ok, 2=errors)") + parser.add_argument("--dry-run", action="store_true", help="Show what would be generated without rendering") + parser.add_argument("--json", action="store_true", help="Print structured JSON result to stdout") + parser.add_argument("--verbose", "-v", action="store_true", help="Verbose output") + parser.add_argument("--debug", action="store_true", help="Debug output (shows magick commands)") + parser.add_argument("--quiet", "-q", action="store_true", help="Suppress non-error output") + args = parser.parse_args() + + # Logging + level = logging.WARNING + if args.debug: + level = logging.DEBUG + elif args.verbose: + level = logging.INFO + elif args.quiet: + level = logging.ERROR + logging.basicConfig(level=level, format="%(levelname)s: %(message)s", stream=sys.stderr) + + # --list-presets + if args.list_presets: + list_presets() + sys.exit(0) + + # --init + if args.init: + init_config(Path(args.config)) + sys.exit(0) + + # Load config + config_path = Path(args.config) + if not config_path.exists(): + print(f"ERROR: Config not found: {config_path}", file=sys.stderr) + print(" Run --init to create a starter config.", file=sys.stderr) + sys.exit(2) + + config = load_config(config_path) + magick = find_magick() + + # --validate + if args.validate: + issues = validate_config(config, magick) + if not issues: + print("Config OK: no issues found.", file=sys.stderr) + logo_path = config["logo"].get("_resolved_path") + if logo_path: + print(f" Logo: {logo_path} ({'exists' if logo_path.exists() else 'MISSING'})", file=sys.stderr) + fonts_cfg = config.get("fonts", {}) + resolved = {} + for role in ("title", "tagline", "url"): + candidates = fonts_cfg.get(role, []) + if candidates: + found = detect_available_font(candidates, magick) + resolved[role] = found or "(none)" + print(f" Fonts: {resolved}", file=sys.stderr) + print(f" Banners: {len(config.get('banners', []))}", file=sys.stderr) + sys.exit(0) + else: + errs = [i for i in issues if not i.startswith("WARNING:")] + warns = [i for i in issues if i.startswith("WARNING:")] + for w in warns: + print(f" {w}", file=sys.stderr) + for e in errs: + print(f" ERROR: {e}", file=sys.stderr) + if errs: + print(f"\n{len(errs)} error(s), {len(warns)} warning(s).", file=sys.stderr) + sys.exit(2) + else: + print(f"\nConfig OK with {len(warns)} warning(s).", file=sys.stderr) + sys.exit(0) + + # Resolve fonts + fonts_cfg = config.get("fonts", {}) + fonts = resolve_fonts(fonts_cfg, magick) + log.info(f"Resolved fonts: {fonts}") + + # Extract logo + logo_config = config.get("logo", {}) + logo_path = logo_config.get("_resolved_path") + if not logo_path or not logo_path.exists(): + print(f"ERROR: Logo not found: {logo_path}", file=sys.stderr) + sys.exit(1) + + tmp_dir = Path(tempfile.mkdtemp(prefix="composite-banners-")) + try: + logo_mark, logo_aspect = extract_logo_mark(logo_path, logo_config, tmp_dir, magick) + if not args.quiet: + print(f"Logo processed: {logo_mark.name} (aspect {logo_aspect[0]:.0f}:{logo_aspect[1]:.0f})", file=sys.stderr) + + # Filter banners + brand = config.get("brand", {}) + banners = config.get("banners", []) + if args.name: + banners = [b for b in banners if b.get("name") == args.name] + if not banners: + print(f"ERROR: No banner named '{args.name}'. Available: {[b['name'] for b in config.get('banners', [])]}", file=sys.stderr) + sys.exit(1) + + # --dry-run + if args.dry_run: + print(f"\nDry run — would generate {len(banners)} banner(s):", file=sys.stderr) + for b in banners: + ext = {"webp": ".webp", "jpeg": ".jpeg"}.get(args.format, ".png") + print(f" {b['name']}{ext} {b['width']}x{b['height']} [{b.get('category', '?')}] {b['layout']}", file=sys.stderr) + sys.exit(0) + + # Generate + output_dir = Path(args.output_dir) + output_dir.mkdir(parents=True, exist_ok=True) + start_time = time.time() + generated = [] + failed = [] + + for b in banners: + name = b.get("name", "unnamed") + output = output_dir / f"{name}.png" + layout = b.get("layout", "") + func = LAYOUT_FUNCS.get(layout) + if not func: + if not args.quiet: + print(f" SKIP: Unknown layout '{layout}' for {name}", file=sys.stderr) + failed.append({"name": name, "error": f"unknown layout: {layout}"}) + continue + + try: + func(b, brand, fonts, logo_mark, logo_aspect, magick, output) + # Convert format if needed + final_path = convert_format(output, args.format, magick) if args.format != "png" else output + # Verify + result = run_magick([magick, "identify", str(final_path)], check=False) + dims = result.stdout.strip().split()[2] if result.returncode == 0 else "?" + size_bytes = final_path.stat().st_size if final_path.exists() else 0 + if not args.quiet: + print(f" OK: {final_path.name} {dims} [{b.get('category', '?')}] ({size_bytes / 1024:.1f} KB)", file=sys.stderr) + generated.append({"name": name, "file": str(final_path), "dimensions": dims, "size_bytes": size_bytes}) + except Exception as e: + if not args.quiet: + print(f" FAIL: {name}: {e}", file=sys.stderr) + failed.append({"name": name, "error": str(e)}) + + elapsed = time.time() - start_time + if not args.quiet: + print(f"\nGenerated {len(generated)}/{len(banners)} banners in {output_dir}/ ({elapsed:.1f}s)", file=sys.stderr) + + # --json + if args.json: + result_json = { + "ok": len(failed) == 0, + "generated": generated, + "failed": failed, + "total": len(banners), + "elapsed_seconds": round(elapsed, 1), + "config": str(config_path), + "output_dir": str(output_dir), + "format": args.format, + } + print(json.dumps(result_json, indent=2)) + + sys.exit(0 if not failed else 1) + + finally: + # Cleanup temp + for f in tmp_dir.iterdir(): + f.unlink(missing_ok=True) + tmp_dir.rmdir() + + +if __name__ == "__main__": + main() diff --git a/README-v2.md b/README-v2.md index 9028770..45b0f4e 100644 --- a/README-v2.md +++ b/README-v2.md @@ -775,7 +775,7 @@ Skills provide specialized capabilities. See [Agent Skills documentation](https: | **claude-docs-consultant** | Selectively fetches official Claude Code documentation from docs.claude.com | Automatic when working on Claude Code features | | **consult-zai** | Dual-AI consultation comparing z.ai GLM 4.7 and code-searcher | `/consult-zai "question"` or via Skill tool | | **consult-codex** | Dual-AI consultation comparing Codex GPT-5.2 and code-searcher | `/consult-codex "question"` or via Skill tool | -| **ai-image-creator** | Generate PNG images using AI (multiple models including Gemini, FLUX.2, Riverflow, SeedDream, GPT-5 via OpenRouter/Cloudflare AI Gateway). Requires [setup](.claude/skills/ai-image-creator/references/setup-guide.md) | `/ai-image-creator` or via Skill tool | +| **ai-image-creator** | Generate PNG images using AI (multiple models including Gemini, FLUX.2, Riverflow, SeedDream, GPT-5 via OpenRouter/Cloudflare AI Gateway). Supports transparent backgrounds (`-t`), reference image editing (`-r`), per-project cost tracking (`--costs`), prompt enhancement patterns, and composite banner generation for multi-size logo banners via ImageMagick. Requires [setup](.claude/skills/ai-image-creator/references/setup-guide.md) | `/ai-image-creator` or via Skill tool | ### 5.3 Custom Slash Commands diff --git a/README-v3.md b/README-v3.md index 218fb98..94e9b37 100644 --- a/README-v3.md +++ b/README-v3.md @@ -520,7 +520,7 @@ Skills provide specialized capabilities. See [official docs](https://docs.claude | **claude-docs-consultant** | Selectively fetches official Claude Code documentation | | **consult-zai** | Dual-AI consultation comparing z.ai GLM 4.7 and code-searcher responses | | **consult-codex** | Dual-AI consultation comparing Codex GPT-5.2 and code-searcher responses | -| **ai-image-creator** | Generate PNG images using AI (Gemini, FLUX.2, Riverflow, SeedDream, GPT-5) with configurable aspect ratios and resolutions. Requires [setup](.claude/skills/ai-image-creator/references/setup-guide.md) | +| **ai-image-creator** | Generate PNG images using AI (Gemini, FLUX.2, Riverflow, SeedDream, GPT-5) with configurable aspect ratios and resolutions. Supports transparent backgrounds (`-t`), reference image editing (`-r`), cost tracking (`--costs`), prompt enhancement patterns, and composite banner generation for multi-size logo banners. Requires [setup](.claude/skills/ai-image-creator/references/setup-guide.md) | ### Custom Subagents diff --git a/README-v4.md b/README-v4.md index 2d4c47c..d5c948a 100644 --- a/README-v4.md +++ b/README-v4.md @@ -817,10 +817,10 @@ Skills are defined in `.claude/skills/` directories containing: | Keyword | Model | |---------|-------| | `gemini` | Google Gemini 3.1 Flash (default) | -| `riverflow` | Sourceful Riverflow v2 Fast | -| `flux2` | FLUX.2 Klein 4B | +| `riverflow` | Sourceful Riverflow v2 Pro | +| `flux2` | FLUX.2 Max | | `seedream` | ByteDance SeedDream 4.5 | -| `gpt5` | OpenAI GPT-5 Image Mini | +| `gpt5` | OpenAI GPT-5 Image | **Providers**: - OpenRouter (recommended, pay-as-you-go) @@ -832,9 +832,16 @@ Skills are defined in `.claude/skills/` directories containing: - Configurable aspect ratios: 1:1, 16:9, 9:16, 3:2, 2:3, 4:3, 3:4, 4:5, 5:4, 21:9, 1:4, 4:1 - Image sizes: 0.5K, 1K (default), 2K, 4K - Automatic fallback from gateway to direct API +- Transparent background generation (`-t`) with green-screen chroma key pipeline +- Reference image editing/style transfer (`-r`) for multimodal models (gemini, gpt5) +- Per-project cost tracking (`--costs`) with per-model breakdown +- Prompt enhancement with 11 category-specific professional patterns +- Composite banners for multi-size logo banners via ImageMagick (no API calls needed) - Post-processing with ImageMagick, sips (macOS), or ffmpeg - Pure Python (no pip dependencies), requires `uv` runner +**Composite Banners**: Generate consistent logo banners across multiple sizes from a JSON config using ImageMagick. Use when the user has an existing logo and wants multi-size branded banners (not creative/artistic designs). Quick start: `--init` to scaffold config, `--validate` to check, then generate. See [composite reference](.claude/skills/ai-image-creator/references/composite-reference.md) for full config schema. + **Usage**: `/ai-image-creator` or invoke via Skill tool when user asks to generate images, create PNGs, or make visual assets. --- diff --git a/README.md b/README.md index 8b4832b..8bdbbd2 100644 --- a/README.md +++ b/README.md @@ -892,6 +892,11 @@ Claude Code now supports [Agent Skills](https://docs.claude.com/en/docs/claude-c * Supports configurable aspect ratios (1:1, 16:9, 9:16, 3:2, 4:3, etc.) and image sizes (0.5K to 4K) * Multiple providers: OpenRouter (recommended), Google AI Studio, Cloudflare AI Gateway BYOK * Automatic fallback from gateway to direct API + * Transparent background generation (`-t`) with green-screen chroma key pipeline + * Reference image editing/style transfer (`-r`) for multimodal models (gemini, gpt5) + * Per-project cost tracking (`--costs`) with per-model breakdown + * Prompt enhancement with 11 category-specific professional patterns (product hero, social media, marketing banners, etc.) + * Composite banners for multi-size logo banners via ImageMagick — no API calls needed * Post-processing support with ImageMagick, sips (macOS), or ffmpeg * Pure Python script with no pip dependencies (requires `uv` runner) * **Setup**: Requires API credentials and optional Cloudflare AI Gateway configuration. See [setup guide](.claude/skills/ai-image-creator/references/setup-guide.md) for detailed instructions From 204c03f7984180be35c2e52fa9703475cdb2f118 Mon Sep 17 00:00:00 2001 From: George Liu Date: Fri, 27 Mar 2026 09:36:56 +1000 Subject: [PATCH 102/174] update claude-docs-consultant --- .../skills/claude-docs-consultant/SKILL.md | 177 ++++++------------ .../references/docs-index.md | 117 ++++++++++++ 2 files changed, 172 insertions(+), 122 deletions(-) create mode 100644 .claude/skills/claude-docs-consultant/references/docs-index.md diff --git a/.claude/skills/claude-docs-consultant/SKILL.md b/.claude/skills/claude-docs-consultant/SKILL.md index 8971177..9d4bd92 100644 --- a/.claude/skills/claude-docs-consultant/SKILL.md +++ b/.claude/skills/claude-docs-consultant/SKILL.md @@ -1,158 +1,91 @@ --- name: claude-docs-consultant -description: Consult official Claude Code documentation from docs.claude.com using selective fetching. Use this skill when working on Claude Code hooks, skills, subagents, MCP servers, or any Claude Code feature that requires referencing official documentation for accurate implementation. Fetches only the specific documentation needed rather than loading all docs upfront. +description: Consult official Claude Code documentation from code.claude.com using selective fetching. Use when working on hooks, skills, subagents, plugins, agent teams, MCP servers, permissions, settings, CI/CD (GitHub Actions, GitLab), IDE extensions (VS Code, JetBrains), desktop/web app features, scheduling, memory/CLAUDE.md, deployment (Bedrock, Vertex, Foundry), sandboxing, monitoring, or any Claude Code feature requiring official docs. Fetches only the specific docs needed per task. +metadata: + version: 2.0.0 --- # Claude Docs Consultant -## Overview +Fetch official Claude Code documentation on-demand from code.claude.com. Uses progressive disclosure: resolve the topic to a filename, then fetch only that doc. Never fetch documentation speculatively. -This skill enables efficient consultation of official Claude Code documentation by fetching only the specific docs needed for the current task. Instead of loading all documentation upfront, determine which docs are relevant and fetch them on-demand. +## URL Pattern -## When to Use This Skill +All docs follow this pattern — substitute the filename: -Invoke this skill when: - -- Creating or modifying Claude Code hooks -- Building or debugging skills -- Working with subagents or understanding subagent parameters -- Implementing MCP server integrations -- Understanding any Claude Code feature that requires official documentation -- Troubleshooting Claude Code functionality -- Verifying correct API usage or parameters - -## Common Documentation - -For the most frequently referenced topics, fetch these detailed documentation files directly: - -### Hooks Documentation - -- **hooks-guide.md** - Comprehensive guide to creating hooks with examples and best practices - - - URL: `https://code.claude.com/docs/en/hooks-guide.md` - - Use for: Understanding hook lifecycle, creating new hooks, examples - -- **hooks.md** - Hooks API reference with event types and parameters - - URL: `https://code.claude.com/docs/en/hooks.md` - - Use for: Hook event reference, available events, parameter details - -### Skills Documentation - -- **skills.md** - Skills creation guide and structure reference - - URL: `https://code.claude.com/docs/en/skills.md` - - Use for: Creating skills, understanding SKILL.md format, bundled resources - -### Subagents Documentation - -- **sub-agents.md** - Subagent types, parameters, and usage - - URL: `https://code.claude.com/docs/en/sub-agents.md` - - Use for: Available subagent types, when to use Task tool, subagent parameters - -## Workflow for Selective Fetching +``` +https://code.claude.com/docs/en/{filename}.md +``` -Follow this process to efficiently fetch documentation: +## Quick Routing (Common Topics) -### Step 1: Identify Documentation Needs +For these high-frequency topics, fetch directly without consulting the full index: -Determine which documentation is needed based on the task: +| Topic | Filename(s) to fetch | +| --- | --- | +| Hooks (creating, events, lifecycle) | `hooks-guide.md` (guide + examples), `hooks.md` (API reference + all events) | +| Skills (creating, SKILL.md format, triggers) | `skills.md` | +| Subagents (types, config, delegation) | `sub-agents.md` | +| Agent Teams (multi-agent, teammates, cowork) | `agent-teams.md` | +| Plugins (creating, marketplace, installing) | `plugins.md` (creating), `discover-plugins.md` (marketplace + installing) | +| MCP Servers (setup, config, scopes) | `mcp.md` | +| Settings (settings.json, config scopes) | `settings.md` | +| Permissions (rules, modes, auto mode) | `permissions.md` (rules + syntax), `permission-modes.md` (plan/auto/dontAsk modes) | +| Memory (CLAUDE.md, auto memory, rules) | `memory.md` | +| GitHub Actions (CI/CD, @claude PR) | `github-actions.md` | -- **Hook-related task** → Fetch `hooks-guide.md` and/or `hooks.md` -- **Skill-related task** → Fetch `skills.md` -- **Subagent-related task** → Fetch `sub-agents.md` -- **Other Claude Code feature** → Proceed to Step 2 +## Full Routing -### Step 2: Discover Available Documentation (If Needed) +For topics not listed above, consult `references/docs-index.md` for the complete routing table covering all 60+ documentation pages across platforms, deployment, security, configuration, administration, and reference. -For features not covered by the 4 common docs above, fetch the docs map to discover available documentation: +## Workflow -``` -URL: https://code.claude.com/docs/en/claude_code_docs_map.md -``` +1. **Identify topic** — determine which Claude Code feature the task involves +2. **Route to filename** — use quick routing above, or consult `references/docs-index.md` +3. **Fetch with WebFetch** — use the URL pattern with the resolved filename -The docs map lists all available Claude Code documentation with descriptions. Identify the relevant doc(s) from the map. +Fetch multiple docs in parallel when the task spans multiple topics. -### Step 3: Fetch Only Relevant Documentation +## Fallback: Discovery via Docs Map -Use WebFetch to retrieve only the specific documentation needed: +If routing does not match any known filename, fetch the documentation map to discover available pages: ``` -WebFetch: - url: https://code.claude.com/docs/en/[doc-name].md - prompt: "Extract the full documentation content" +https://code.claude.com/docs/en/claude_code_docs_map.md ``` -Fetch multiple docs in parallel if the task requires information from several sources. +Identify the relevant doc from the map, then fetch it using the URL pattern. -### Step 4: Apply Documentation to Task +## Rules -Use the fetched documentation to: - -- Verify correct API usage -- Understand available parameters and options -- Follow best practices and examples -- Implement the feature correctly +- Fetch only the docs actually needed for the current task +- Fetch multiple docs in parallel if the task requires 2+ sources +- Always fetch live from code.claude.com — do not use cached or memorized content +- Do not fetch docs "just in case" — fetch when required by the task ## Examples -### Example 1: Creating a New Hook - -**User request:** "Help me create a pre-tool-use hook to log all tool calls" - -**Process:** - -1. Identify need: Hook creation requires hooks documentation -2. Fetch `hooks-guide.md` for creation process and examples -3. Fetch `hooks.md` for pre-tool-use event reference -4. Apply: Create hook following guide, using correct event parameters - -### Example 2: Debugging a Skill - -**User request:** "My skill isn't loading - help me fix SKILL.md" - -**Process:** - -1. Identify need: Skill structure requires skills documentation -2. Fetch `skills.md` for SKILL.md format requirements -3. Apply: Validate frontmatter, structure, and bundled resources - -### Example 3: Using Subagents - -**User request:** "Which subagent should I use to search the codebase?" - -**Process:** - -1. Identify need: Subagent selection requires subagent documentation -2. Fetch `sub-agents.md` for subagent types and capabilities -3. Apply: Recommend appropriate subagent (e.g., Explore or code-searcher) - -### Example 4: Unknown Feature - -**User request:** "How do I configure Claude Code settings.json?" - -**Process:** +### Example 1: Creating a Hook -1. Identify need: Not covered by the 4 common docs -2. Fetch docs map: `claude_code_docs_map.md` -3. Discover: Find relevant doc (e.g., `settings.md`) -4. Fetch specific doc: `https://code.claude.com/docs/en/settings.md` -5. Apply: Configure settings.json correctly +**Task:** "Help me create a pre-tool-use hook to log tool calls" -## Best Practices +1. Route: hook creation -> `hooks-guide.md` + `hooks.md` +2. Fetch both in parallel via WebFetch +3. Apply: create hook using guide examples and API reference for PreToolUse event -### Token Efficiency +### Example 2: Installing a Plugin -- Fetch only the documentation actually needed for the current task -- Fetch multiple docs in parallel if needed (single message with multiple WebFetch calls) -- Do not fetch documentation "just in case" - fetch when required +**Task:** "How do I install plugins from a marketplace?" -### Staying Current +1. Route: plugin installing -> `discover-plugins.md` +2. Fetch via WebFetch +3. Apply: follow marketplace and installation instructions -- Always fetch from docs.claude.com (live docs, not cached copies) -- Documentation may be updated by Anthropic - fetching ensures latest information -- If documentation seems outdated or unclear, verify URL is correct +### Example 3: Unknown Feature -### Selective vs Comprehensive +**Task:** "How do I configure Claude Code output styles?" -- **Selective (preferred)**: Fetch hooks-guide.md for hook creation task -- **Comprehensive (avoid)**: Fetch all 4 common docs for every task -- **Discovery-based**: Use docs map when common docs don't cover the need +1. Route: not in quick routing table +2. Consult `references/docs-index.md` -> find `output-styles.md` under Configuration +3. Fetch `output-styles.md` via WebFetch +4. Apply: configure output styles per documentation diff --git a/.claude/skills/claude-docs-consultant/references/docs-index.md b/.claude/skills/claude-docs-consultant/references/docs-index.md new file mode 100644 index 0000000..b5c773c --- /dev/null +++ b/.claude/skills/claude-docs-consultant/references/docs-index.md @@ -0,0 +1,117 @@ +# Claude Code Documentation Index + +Complete routing table for all official Claude Code documentation pages. +All URLs follow: `https://code.claude.com/docs/en/{filename}.md` + +## Automation + +| Keywords | Filename | Description | +| --- | --- | --- | +| hook, event, pre-tool, post-tool, automation | `hooks-guide.md` | Hook creation guide with examples | +| hook API, hook events, hook reference, lifecycle | `hooks.md` | Hook events reference (all events + input/output) | +| schedule, /loop, cron, recurring, reminder | `scheduled-tasks.md` | In-session scheduling with /loop and cron | +| web schedule, recurring web task | `web-scheduled-tasks.md` | Scheduled tasks on claude.ai/code | +| channel, webhook, push message, notification bridge | `channels.md` | Push message channels (Slack, webhooks) | +| channel reference, channel plugin, relay | `channels-reference.md` | Channel implementation reference | +| headless, non-interactive, pipe, batch, automation | `headless.md` | Non-interactive/scripted Claude Code usage | + +## Extensibility + +| Keywords | Filename | Description | +| --- | --- | --- | +| skill, SKILL.md, trigger, bundled resource | `skills.md` | Skill creation and configuration | +| subagent, agent tool, delegate, explore agent | `sub-agents.md` | Subagent types, config, and delegation | +| agent team, teammate, parallel agents, cowork | `agent-teams.md` | Multi-agent coordination and teams | +| plugin, create plugin, plugin structure | `plugins.md` | Plugin creation and development | +| marketplace, install plugin, discover plugin | `discover-plugins.md` | Plugin marketplace and installation | +| plugin reference, manifest, plugin components, LSP | `plugins-reference.md` | Plugin components and CLI reference | +| plugin marketplace, host marketplace, schema | `plugin-marketplaces.md` | Creating and hosting marketplaces | +| mcp, mcp server, tool integration, stdio, SSE | `mcp.md` | MCP server setup and configuration | + +## Configuration + +| Keywords | Filename | Description | +| --- | --- | --- | +| settings, settings.json, config scope, worktree settings | `settings.md` | Settings files, scopes, and precedence | +| permission, allow, deny, permission rule, specifier | `permissions.md` | Permission rules, syntax, and managed settings | +| permission mode, plan mode, auto mode, dontAsk, bypass | `permission-modes.md` | Permission modes (plan, auto, dontAsk, bypass) | +| CLAUDE.md, memory, auto memory, rules, AGENTS.md | `memory.md` | Memory system, CLAUDE.md, and .claude/rules/ | +| model, model config, model alias, effort level, extended context | `model-config.md` | Model selection, aliases, and configuration | +| fast mode, speed, fast toggle | `fast-mode.md` | Fast mode toggle and cost tradeoff | +| theme, terminal, vim mode, notification, appearance | `terminal-config.md` | Terminal themes, vim mode, notifications | +| keybinding, keyboard shortcut, rebind key, chord | `keybindings.md` | Custom keyboard shortcuts | +| statusline, status bar, status display | `statusline.md` | Custom status line configuration | +| output style, formatting, response style | `output-styles.md` | Built-in and custom output styles | +| voice, dictation, push-to-talk, speech | `voice-dictation.md` | Voice input configuration | +| env var, environment variable | `env-vars.md` | Environment variables reference | +| sandbox, isolation, filesystem restrict, network restrict | `sandboxing.md` | Filesystem and network sandboxing | + +## Platforms and Integrations + +| Keywords | Filename | Description | +| --- | --- | --- | +| platform, where to run, comparison | `platforms.md` | Platform comparison overview | +| vscode, vs code, extension, IDE | `vs-code.md` | VS Code extension features and config | +| jetbrains, intellij, pycharm, webstorm, goland | `jetbrains.md` | JetBrains IDE plugin | +| desktop, desktop app, diff view, app preview, computer use | `desktop.md` | Desktop app features and config | +| desktop install, desktop quickstart | `desktop-quickstart.md` | Desktop app installation | +| web, claude.ai/code, cloud environment, web session | `claude-code-on-the-web.md` | Web app features, cloud env, network access | +| slack, slack integration, slack bot | `slack.md` | Slack integration | +| chrome, browser automation, browser control | `chrome.md` | Chrome browser automation | +| remote control, remote session, remote device | `remote-control.md` | Remote Control from other devices | + +## CI/CD and Code Review + +| Keywords | Filename | Description | +| --- | --- | --- | +| github action, github CI, @claude PR, claude-code-action | `github-actions.md` | GitHub Actions integration | +| gitlab, merge request, gitlab CI, gitlab pipeline | `gitlab-ci-cd.md` | GitLab CI/CD integration | +| code review, review.md, severity, automated review | `code-review.md` | Automated code review setup | + +## Deployment and Enterprise + +| Keywords | Filename | Description | +| --- | --- | --- | +| third-party, proxy, gateway, cloud provider | `third-party-integrations.md` | Deployment options overview | +| bedrock, AWS, amazon | `amazon-bedrock.md` | AWS Bedrock setup | +| vertex, GCP, google cloud | `google-vertex-ai.md` | Google Vertex AI setup | +| foundry, azure, microsoft | `microsoft-foundry.md` | Microsoft Foundry setup | +| gateway, litellm, LLM proxy | `llm-gateway.md` | LLM gateway and LiteLLM config | +| network, proxy, CA cert, mTLS, SSL | `network-config.md` | Network and proxy configuration | +| devcontainer, container, dev environment | `devcontainer.md` | Dev container configuration | +| server-managed, enterprise settings, managed config | `server-managed-settings.md` | Enterprise server-managed settings | + +## Administration + +| Keywords | Filename | Description | +| --- | --- | --- | +| install, setup, system requirements, update | `setup.md` | Installation and updates | +| auth, login, credential, team auth, SSO | `authentication.md` | Authentication and credential management | +| security, prompt injection, MCP security, IDE security | `security.md` | Security practices and protections | +| OTEL, telemetry, metrics, monitoring, opentelemetry | `monitoring-usage.md` | Usage monitoring with OTEL metrics/events | +| cost, token usage, reduce tokens, /cost | `costs.md` | Cost tracking and reduction strategies | +| analytics, PR attribution, adoption, ROI | `analytics.md` | Teams/Enterprise analytics | +| data, retention, training policy, telemetry | `data-usage.md` | Data policies and retention | +| zero data retention, ZDR | `zero-data-retention.md` | ZDR scope and configuration | + +## Reference + +| Keywords | Filename | Description | +| --- | --- | --- | +| CLI, cli flag, command reference, cli command | `cli-reference.md` | All CLI commands and flags | +| slash command, /command, built-in command | `commands.md` | Slash commands reference | +| tool, tool reference, bash tool, tool behavior | `tools-reference.md` | Tool behavior details | +| interactive, keyboard shortcut, vim, command history, background bash | `interactive-mode.md` | Interactive mode features and shortcuts | +| checkpoint, undo, rewind, restore | `checkpointing.md` | Checkpoint and undo system | +| troubleshoot, install error, debug, fix | `troubleshooting.md` | Troubleshooting common issues | + +## Core Concepts + +| Keywords | Filename | Description | +| --- | --- | --- | +| how it works, agentic loop, context window, session | `how-claude-code-works.md` | Architecture, models, tools, sessions | +| feature overview, feature comparison, context cost | `features-overview.md` | Feature comparison and context costs | +| workflow, best practice, worktree, common task | `common-workflows.md` | Common workflows and patterns | +| best practice, tips, effective usage | `best-practices.md` | Comprehensive best practices | +| quickstart, getting started, first session | `quickstart.md` | Getting started guide | +| changelog, release notes, what's new | `changelog.md` | Release changelog | From 43c83c2e13ba42ce0806cf81e73e795e26ac3139 Mon Sep 17 00:00:00 2001 From: George Liu Date: Fri, 3 Apr 2026 11:25:20 +1000 Subject: [PATCH 103/174] Add --analyze image analysis mode to ai-image-creator skill - generate-image.py: new --analyze flag for text-only image description/analysis using multimodal models (gemini, gpt5) - SKILL.md: updated description, routing check, category detection table, parameters table, and new Image Analysis section - references/analyze-reference.md: new progressive-disclosure reference with prompt patterns, targeted analysis table, and output handling - README.md, README-v2.md, README-v3.md, README-v4.md: updated ai-image-creator descriptions to include --analyze capability --- .claude/skills/ai-image-creator/SKILL.md | 40 ++++- .../references/analyze-reference.md | 89 ++++++++++ .../scripts/generate-image.py | 160 +++++++++++++++++- README-v2.md | 2 +- README-v3.md | 2 +- README-v4.md | 5 +- README.md | 3 +- 7 files changed, 290 insertions(+), 11 deletions(-) create mode 100644 .claude/skills/ai-image-creator/references/analyze-reference.md diff --git a/.claude/skills/ai-image-creator/SKILL.md b/.claude/skills/ai-image-creator/SKILL.md index 8554df2..8e39838 100644 --- a/.claude/skills/ai-image-creator/SKILL.md +++ b/.claude/skills/ai-image-creator/SKILL.md @@ -1,6 +1,6 @@ --- name: ai-image-creator -description: Generate PNG images using AI (multiple models via OpenRouter including Gemini, FLUX.2, Riverflow, SeedDream, GPT-5 Image, proxied through Cloudflare AI Gateway BYOK). Use when user asks to "generate an image", "create a PNG", "make an icon", "make it transparent", or needs AI-generated visual assets for the project. Supports model selection via keywords (gemini, riverflow, flux2, seedream, gpt5), configurable aspect ratios/resolutions, transparent backgrounds (-t), reference image editing (-r), and per-project cost tracking (--costs). +description: Generate PNG images using AI (multiple models via OpenRouter including Gemini, FLUX.2, Riverflow, SeedDream, GPT-5 Image, proxied through Cloudflare AI Gateway BYOK). Also analyze/describe existing images using multimodal AI vision. Use when user asks to "generate an image", "create a PNG", "make an icon", "make it transparent", "describe this image", "analyze this image", "what's in this image", "explain this image", or needs AI-generated visual assets for the project. Supports model selection via keywords (gemini, riverflow, flux2, seedream, gpt5), configurable aspect ratios/resolutions, transparent backgrounds (-t), reference image editing (-r), image analysis (--analyze), and per-project cost tracking (--costs). allowed-tools: Bash, Read, Write compatibility: Requires uv (Python runner) and network access. Environment variables for CF AI Gateway or direct API keys must be configured in shell profile (~/.zshrc on macOS, ~/.bashrc on Linux, or System Environment Variables on Windows). metadata: @@ -25,6 +25,8 @@ When the user mentions a model keyword in their image request, use the correspon ## Instructions +> **Routing check:** If the user asks to **describe, analyze, or explain an existing image** (not generate a new one), skip directly to the **Image Analysis (`--analyze`)** section below. No prompt enhancement or output path needed. + ### Step 1: Write Prompt For long or complex prompts (recommended), write to `${CLAUDE_SKILL_DIR}/tmp/prompt.txt` using the Write tool: @@ -63,6 +65,7 @@ Professional prompt patterns are available in 3 reference files. These are **not | "building", "interior", "room", "architecture" | `architecture` | `prompt-core.md` + `prompt-categories.md` § architecture | | "chart", "infographic", "data", "diagram" | `infographic` | `prompt-core.md` + `prompt-categories.md` § infographic | | "t-shirt", "mug design", "poster", "POD", "print-on-demand" | `pod_design` | `prompt-core.md` + `prompt-platforms.md` + `prompt-categories.md` § pod_design | +| "describe", "analyze", "what's in this image", "explain image" | `analyze` | Skip prompt enhancement — use `--analyze` mode directly. Read `references/analyze-reference.md` for advanced analysis patterns | | No match / simple request | — | Skip patterns, generate directly | **When to skip enhancement:** @@ -154,6 +157,7 @@ If the user needs resizing, format conversion, or other manipulation, first dete | `--image-size` | `-s` | No | model default | OpenRouter only: `0.5K`, `1K`, `2K`, `4K` | | `--model` | `-m` | No | `gemini` | Model keyword (`gemini`, `riverflow`, `flux2`, `seedream`, `gpt5`) or full model ID | | `--ref` | `-r` | No | -- | Reference image file (repeatable). For editing/style transfer. Multimodal models only (gemini, gpt5) | +| `--analyze` | -- | No | -- | Analyze/describe a reference image (text-only output, no image generated). Requires `-r`. Multimodal models only | | `--transparent` | `-t` | No | -- | Generate with transparent background. Requires ffmpeg + imagemagick | | `--costs` | -- | No | -- | Display generation/cost history for this project and exit | | `--list-models` | -- | No | -- | List available model keywords and exit | @@ -205,6 +209,40 @@ uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py \ Supported formats: PNG, JPEG, WebP, GIF. +## Image Analysis (`--analyze`) + +Describe, analyze, or explain existing images using multimodal AI vision. Returns text-only output (no image generated). **Multimodal models only** (gemini, gpt5). + +No `-o` output path needed. No prompt enhancement needed. The script outputs JSON to stdout with the model's analysis in the `analysis` field. + +```bash +# Analyze with default prompt (describes subject, style, colors, composition, mood, text) +uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py \ + --analyze -r "photo.png" + +# Analyze with custom prompt +uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py \ + --analyze -r "photo.png" -p "Describe this image in plain text and also in JSON structured output" + +# Analyze with a specific model +uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py \ + --analyze -r "photo.png" -m gpt5 -p "What text is visible in this image?" + +# Analyze multiple images together +uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py \ + --analyze -r "before.png" -r "after.png" -p "Compare these two images and describe the differences" +``` + +**JSON output format:** + +```json +{"ok": true, "analyze": true, "analysis": "", "provider": "openrouter", "model": "...", "mode": "gateway", "elapsed_seconds": 3.2, "ref_images": 1} +``` + +**Incompatible flags:** `--analyze` cannot be combined with `-o`, `-t`, `-a`, or `-s`. + +For advanced analysis prompt patterns (structured output, comparison, targeted analysis), read `references/analyze-reference.md`. + ## Cost Tracking (`--costs`) Every generation is logged to `.ai-image-creator/costs.json` in your project directory. View history: diff --git a/.claude/skills/ai-image-creator/references/analyze-reference.md b/.claude/skills/ai-image-creator/references/analyze-reference.md new file mode 100644 index 0000000..f97ac6a --- /dev/null +++ b/.claude/skills/ai-image-creator/references/analyze-reference.md @@ -0,0 +1,89 @@ +# Image Analysis Reference + +Advanced prompt patterns for `--analyze` mode. Only read this file when the user needs structured, comparative, or targeted image analysis beyond a simple description. + +## Analysis Prompt Patterns + +### Plain Text Description + +Default behavior — no custom prompt needed. The built-in default covers subject, style, colors, composition, mood, and visible text. + +```bash +uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py --analyze -r "image.png" +``` + +### JSON Structured Output + +Ask the model to return structured data: + +``` +Analyze this image and return a JSON object with these fields: +- image_type: the type/medium of the image (photo, illustration, screenshot, etc.) +- subjects: array of objects with {name, position, description} +- colors: dominant color palette as hex codes +- text_content: any visible text in the image +- style: artistic style or visual treatment +- mood: emotional tone +- composition: layout and framing description +``` + +### Plain Text + JSON Combined + +``` +Describe this image in two sections: +1. PLAIN TEXT: A natural-language paragraph describing what the image shows +2. JSON: A structured JSON object with fields: image_type, subjects, colors, style, mood, composition, text_content +``` + +### Comparison (Multiple Images) + +Use multiple `-r` flags to compare images: + +```bash +uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py \ + --analyze -r "v1.png" -r "v2.png" \ + -p "Compare these two images. Describe the differences in composition, color, and style. Which is more suitable for a professional website hero banner?" +``` + +### Targeted Analysis + +Focus the model on specific aspects: + +| Focus | Prompt Pattern | +|-------|---------------| +| Accessibility | "Evaluate this UI screenshot for accessibility: contrast ratios, text readability, color-blind friendliness" | +| Brand consistency | "Does this image match a modern tech brand aesthetic? Evaluate color palette, typography, and visual style" | +| Text extraction | "Extract all visible text from this image, preserving layout and hierarchy" | +| Technical specs | "Describe the technical properties: estimated resolution, aspect ratio, color space, compression artifacts" | +| Content moderation | "Describe the content of this image objectively. Flag any potentially sensitive content" | +| UI/UX review | "Analyze this UI screenshot: layout, visual hierarchy, spacing, typography, and potential usability issues" | + +### Batch Analysis Workflow + +To analyze multiple images individually (not comparing), loop in the skill: + +```bash +for img in screenshots/*.png; do + echo "=== $img ===" >&2 + uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py \ + --analyze -r "$img" -p "Describe this screenshot in one paragraph" +done +``` + +## Model Recommendations + +| Model | Best For | +|-------|----------| +| `gemini` (default) | General analysis, fast and cost-effective. Good at text extraction and structured output | +| `gpt5` | Nuanced descriptions, creative interpretation, detailed comparisons | + +## Output Handling + +The `--analyze` flag outputs JSON to stdout. The `analysis` field contains the model's text response. To extract just the analysis text in a script: + +```bash +uv run python ${CLAUDE_SKILL_DIR}/scripts/generate-image.py \ + --analyze -r "image.png" | python -c "import sys,json; print(json.load(sys.stdin)['analysis'])" +``` + +Status messages go to stderr, so piping stdout gives clean JSON. diff --git a/.claude/skills/ai-image-creator/scripts/generate-image.py b/.claude/skills/ai-image-creator/scripts/generate-image.py index 2f4b5f1..bd6d099 100644 --- a/.claude/skills/ai-image-creator/scripts/generate-image.py +++ b/.claude/skills/ai-image-creator/scripts/generate-image.py @@ -212,6 +212,12 @@ def parse_args() -> argparse.Namespace: default=None, help="Reference image file(s) for editing/style transfer (repeatable, multimodal models only)", ) + parser.add_argument( + "--analyze", + action="store_true", + help="Analyze/describe a reference image instead of generating one. " + "Requires -r. Returns text description (no image output).", + ) parser.add_argument( "-t", "--transparent", action="store_true", @@ -694,6 +700,68 @@ def extract_image_google(response: dict) -> tuple[bytes, str]: return image_bytes, text_content +def extract_text_openrouter(response: dict) -> str: + """Extract text-only content from OpenRouter response (analyze mode). + + Args: + response: Parsed JSON response from OpenRouter API. + + Returns: + The model's text response. + + Raises: + RuntimeError: If no text content found in response. + """ + choices = response.get("choices", []) + if not choices: + error = response.get("error", {}) + if error: + msg = error.get("message", str(error)) + raise RuntimeError(f"API error: {msg}") + raise RuntimeError(f"No choices in response: {json.dumps(response)[:500]}") + + message = choices[0].get("message", {}) + text_content = message.get("content", "") + + if not text_content: + raise RuntimeError("No text content in response (empty model reply)") + + log.info(f"Extracted text: {len(text_content)} chars") + return text_content + + +def extract_text_google(response: dict) -> str: + """Extract text-only content from Google AI Studio response (analyze mode). + + Args: + response: Parsed JSON response from Google generateContent API. + + Returns: + The model's text response. + + Raises: + RuntimeError: If no text content found or prompt was blocked. + """ + candidates = response.get("candidates", []) + if not candidates: + block_reason = response.get("promptFeedback", {}).get("blockReason", "") + if block_reason: + raise RuntimeError(f"Prompt blocked by safety filter: {block_reason}") + raise RuntimeError(f"No candidates in response: {json.dumps(response)[:500]}") + + parts = candidates[0].get("content", {}).get("parts", []) + if not parts: + raise RuntimeError("No parts in response candidate") + + text_parts = [part["text"] for part in parts if "text" in part] + if not text_parts: + raise RuntimeError("No text content in response parts") + + text_content = "\n".join(text_parts) + log.info(f"Extracted text: {len(text_content)} chars") + return text_content + + def find_imagemagick() -> str | None: """Find ImageMagick binary (magick for v7, convert for v6). @@ -978,14 +1046,26 @@ def main() -> None: print(f" modalities: {', '.join(info['modalities'])}") sys.exit(0) - # Validate --output is provided (required unless --list-models or --costs) - if not args.output: - print("ERROR: --output is required (unless using --list-models or --costs)", file=sys.stderr) + # Validate --analyze mode + if args.analyze: + if not args.ref: + print("ERROR: --analyze requires at least one reference image (-r)", file=sys.stderr) + sys.exit(1) + if args.transparent: + print("ERROR: --analyze is incompatible with --transparent", file=sys.stderr) + sys.exit(1) + if args.aspect_ratio or args.image_size: + print("ERROR: --analyze is incompatible with --aspect-ratio / --image-size", file=sys.stderr) + sys.exit(1) + + # Validate --output is provided (required unless --list-models, --costs, or --analyze) + if not args.output and not args.analyze: + print("ERROR: --output is required (unless using --list-models, --costs, or --analyze)", file=sys.stderr) sys.exit(1) # Validate output path - output_path = Path(args.output) - if output_path.suffix.lower() not in (".png", ".jpg", ".jpeg", ".webp"): + output_path = Path(args.output) if args.output else None + if output_path and output_path.suffix.lower() not in (".png", ".jpg", ".jpeg", ".webp"): print( "WARNING: Output file does not have an image extension. " "The generated file will be PNG format regardless of extension.", @@ -1028,6 +1108,16 @@ def main() -> None: sys.exit(1) print("Transparent mode: enabled", file=sys.stderr) + # Default prompt for analyze mode (if user didn't provide one) + if args.analyze and not args.prompt and not args.prompt_file: + default_prompt_path = Path(__file__).parent.parent / "tmp" / "prompt.txt" + if not default_prompt_path.exists(): + args.prompt = ( + "Describe this image in detail. Include the subject, style, colors, " + "composition, mood, and any text visible in the image." + ) + log.debug("Using default analyze prompt") + # Resolve prompt prompt = resolve_prompt(args) @@ -1039,6 +1129,11 @@ def main() -> None: "just pure #00FF00 green everywhere behind the subject." ) + # Override modalities for analyze mode (text-only output) + if args.analyze: + modalities = ["text"] + print("Mode: analyze (text-only output)", file=sys.stderr) + print(f"Provider: {args.provider}", file=sys.stderr) print(f"Model: {model}", file=sys.stderr) print(f"Modalities: {', '.join(modalities)}", file=sys.stderr) @@ -1066,7 +1161,10 @@ def main() -> None: ) print(f"URL: {url}", file=sys.stderr) - print("Generating image (this may take up to 2 minutes)...", file=sys.stderr) + if args.analyze: + print("Analyzing image (this may take up to 2 minutes)...", file=sys.stderr) + else: + print("Generating image (this may take up to 2 minutes)...", file=sys.stderr) # Make request with fallback total_start = time.time() @@ -1093,6 +1191,55 @@ def main() -> None: log.debug(f"Request failed. Total time: {time.time() - total_start:.1f}s") sys.exit(1) + # --- Analyze mode: extract text only, no image --- + if args.analyze: + total_elapsed = time.time() - total_start + try: + if args.provider == "openrouter": + analysis_text = extract_text_openrouter(response) + else: + analysis_text = extract_text_google(response) + except RuntimeError as e: + print(f"ERROR: {e}", file=sys.stderr) + log.debug(f"Text extraction failed. Raw response keys: {list(response.keys()) if response else 'None'}") + sys.exit(1) + + print(f"\nAnalysis complete ({total_elapsed:.1f}s)", file=sys.stderr) + log.info(f"Total elapsed: {total_elapsed:.1f}s") + + # Log cost entry + try: + log_cost_entry( + response=response, + provider=args.provider, + model=model, + mode=mode, + aspect_ratio=None, + image_size=None, + output_file="(analyze)", + size_bytes=0, + elapsed_seconds=total_elapsed, + ) + except OSError as e: + log.warning(f"Could not log cost entry: {e}") + + # Print machine-readable output to stdout + result = { + "ok": True, + "analyze": True, + "analysis": analysis_text, + "provider": args.provider, + "model": model, + "mode": mode, + "elapsed_seconds": round(total_elapsed, 1), + "ref_images": len(ref_images), + } + log.debug(f"Result JSON: {json.dumps(result, indent=2)}") + print(json.dumps(result)) + sys.exit(0) + + # --- Image generation mode --- + # Extract image try: if args.provider == "openrouter": @@ -1105,6 +1252,7 @@ def main() -> None: sys.exit(1) # Write output (or process transparent mode) + assert output_path is not None # guaranteed by validation above output_path.parent.mkdir(parents=True, exist_ok=True) if args.transparent: diff --git a/README-v2.md b/README-v2.md index 45b0f4e..1b501b3 100644 --- a/README-v2.md +++ b/README-v2.md @@ -775,7 +775,7 @@ Skills provide specialized capabilities. See [Agent Skills documentation](https: | **claude-docs-consultant** | Selectively fetches official Claude Code documentation from docs.claude.com | Automatic when working on Claude Code features | | **consult-zai** | Dual-AI consultation comparing z.ai GLM 4.7 and code-searcher | `/consult-zai "question"` or via Skill tool | | **consult-codex** | Dual-AI consultation comparing Codex GPT-5.2 and code-searcher | `/consult-codex "question"` or via Skill tool | -| **ai-image-creator** | Generate PNG images using AI (multiple models including Gemini, FLUX.2, Riverflow, SeedDream, GPT-5 via OpenRouter/Cloudflare AI Gateway). Supports transparent backgrounds (`-t`), reference image editing (`-r`), per-project cost tracking (`--costs`), prompt enhancement patterns, and composite banner generation for multi-size logo banners via ImageMagick. Requires [setup](.claude/skills/ai-image-creator/references/setup-guide.md) | `/ai-image-creator` or via Skill tool | +| **ai-image-creator** | Generate PNG images using AI (multiple models including Gemini, FLUX.2, Riverflow, SeedDream, GPT-5 via OpenRouter/Cloudflare AI Gateway). Supports transparent backgrounds (`-t`), reference image editing (`-r`), image analysis and description (`--analyze`), per-project cost tracking (`--costs`), prompt enhancement patterns, and composite banner generation for multi-size logo banners via ImageMagick. Requires [setup](.claude/skills/ai-image-creator/references/setup-guide.md) | `/ai-image-creator` or via Skill tool | ### 5.3 Custom Slash Commands diff --git a/README-v3.md b/README-v3.md index 94e9b37..1f29dce 100644 --- a/README-v3.md +++ b/README-v3.md @@ -520,7 +520,7 @@ Skills provide specialized capabilities. See [official docs](https://docs.claude | **claude-docs-consultant** | Selectively fetches official Claude Code documentation | | **consult-zai** | Dual-AI consultation comparing z.ai GLM 4.7 and code-searcher responses | | **consult-codex** | Dual-AI consultation comparing Codex GPT-5.2 and code-searcher responses | -| **ai-image-creator** | Generate PNG images using AI (Gemini, FLUX.2, Riverflow, SeedDream, GPT-5) with configurable aspect ratios and resolutions. Supports transparent backgrounds (`-t`), reference image editing (`-r`), cost tracking (`--costs`), prompt enhancement patterns, and composite banner generation for multi-size logo banners. Requires [setup](.claude/skills/ai-image-creator/references/setup-guide.md) | +| **ai-image-creator** | Generate PNG images using AI (Gemini, FLUX.2, Riverflow, SeedDream, GPT-5) with configurable aspect ratios and resolutions. Supports transparent backgrounds (`-t`), reference image editing (`-r`), image analysis/description (`--analyze`), cost tracking (`--costs`), prompt enhancement patterns, and composite banner generation for multi-size logo banners. Requires [setup](.claude/skills/ai-image-creator/references/setup-guide.md) | ### Custom Subagents diff --git a/README-v4.md b/README-v4.md index d5c948a..0ef3de3 100644 --- a/README-v4.md +++ b/README-v4.md @@ -834,6 +834,7 @@ Skills are defined in `.claude/skills/` directories containing: - Automatic fallback from gateway to direct API - Transparent background generation (`-t`) with green-screen chroma key pipeline - Reference image editing/style transfer (`-r`) for multimodal models (gemini, gpt5) +- Image analysis/description (`--analyze`) — text-only output; no image generated. Multimodal models only (gemini, gpt5) - Per-project cost tracking (`--costs`) with per-model breakdown - Prompt enhancement with 11 category-specific professional patterns - Composite banners for multi-size logo banners via ImageMagick (no API calls needed) @@ -842,7 +843,9 @@ Skills are defined in `.claude/skills/` directories containing: **Composite Banners**: Generate consistent logo banners across multiple sizes from a JSON config using ImageMagick. Use when the user has an existing logo and wants multi-size branded banners (not creative/artistic designs). Quick start: `--init` to scaffold config, `--validate` to check, then generate. See [composite reference](.claude/skills/ai-image-creator/references/composite-reference.md) for full config schema. -**Usage**: `/ai-image-creator` or invoke via Skill tool when user asks to generate images, create PNGs, or make visual assets. +**Image Analysis**: Describe, analyze, or explain existing images using multimodal AI vision (`--analyze`). Returns text-only JSON output — no image generated. Pass `-r` with the image file and optionally `-p` with a custom prompt. Multimodal models only (gemini, gpt5). Example: `--analyze -r photo.png -p "What text is visible?"`. + +**Usage**: `/ai-image-creator` or invoke via Skill tool when user asks to generate images, create PNGs, make visual assets, or describe/analyze existing images. --- diff --git a/README.md b/README.md index 8bdbbd2..98788a1 100644 --- a/README.md +++ b/README.md @@ -894,13 +894,14 @@ Claude Code now supports [Agent Skills](https://docs.claude.com/en/docs/claude-c * Automatic fallback from gateway to direct API * Transparent background generation (`-t`) with green-screen chroma key pipeline * Reference image editing/style transfer (`-r`) for multimodal models (gemini, gpt5) + * Image analysis/description (`--analyze`) — text-only output from multimodal models (gemini, gpt5); no image generated * Per-project cost tracking (`--costs`) with per-model breakdown * Prompt enhancement with 11 category-specific professional patterns (product hero, social media, marketing banners, etc.) * Composite banners for multi-size logo banners via ImageMagick — no API calls needed * Post-processing support with ImageMagick, sips (macOS), or ffmpeg * Pure Python script with no pip dependencies (requires `uv` runner) * **Setup**: Requires API credentials and optional Cloudflare AI Gateway configuration. See [setup guide](.claude/skills/ai-image-creator/references/setup-guide.md) for detailed instructions -* **Usage**: `/ai-image-creator` or invoke via Skill tool when user asks to generate images, create PNGs, or make visual assets +* **Usage**: `/ai-image-creator` or invoke via Skill tool when user asks to generate images, create PNGs, make visual assets, or describe/analyze existing images ## Claude Code Hooks From ed55d7f65d327ce255943d260d0bd28b5a008bd0 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sun, 5 Apr 2026 12:40:32 +1000 Subject: [PATCH 104/174] update ai-image-creator skill to support .env for Claude Desktop/Cowork sandbox enviromments --- .../scripts/generate-image.py | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/.claude/skills/ai-image-creator/scripts/generate-image.py b/.claude/skills/ai-image-creator/scripts/generate-image.py index bd6d099..1c61c74 100644 --- a/.claude/skills/ai-image-creator/scripts/generate-image.py +++ b/.claude/skills/ai-image-creator/scripts/generate-image.py @@ -80,6 +80,34 @@ ENV_OPENROUTER_KEY = "AI_IMG_CREATOR_OPENROUTER_KEY" ENV_GEMINI_KEY = "AI_IMG_CREATOR_GEMINI_KEY" +def _load_dotenv() -> None: + """Load .env files into os.environ (stdlib only, no pip deps). + + Search order (first found wins per key): + 1. .env in the same directory as this script (skill-level) + 2. .env in the current working directory (project-level) + Keys already present in os.environ are never overwritten. + """ + candidates = [ + Path(__file__).parent / ".env", + Path.cwd() / ".env", + ] + for env_file in candidates: + if not env_file.is_file(): + continue + with env_file.open() as f: + for line in f: + line = line.strip() + if not line or line.startswith("#") or "=" not in line: + continue + key, _, val = line.partition("=") + key = key.strip() + val = val.strip().strip("'\"") + if key and key not in os.environ: + os.environ[key] = val + +_load_dotenv() + # Logger — configured in main() based on --debug / --verbose flags log = logging.getLogger("ai-image-creator") From d02832b2b410f9ae381423a789dd9cc998f45b77 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sun, 5 Apr 2026 13:48:28 +1000 Subject: [PATCH 105/174] update readme --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 98788a1..0ea1ebc 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,6 @@ [![GitHub stars](https://img.shields.io/github/stars/centminmod/my-claude-code-setup.svg?style=flat-square)](https://github.com/centminmod/my-claude-code-setup/stargazers) [![GitHub forks](https://img.shields.io/github/forks/centminmod/my-claude-code-setup.svg?style=flat-square)](https://github.com/centminmod/my-claude-code-setup/network) [![GitHub issues](https://img.shields.io/github/issues/centminmod/my-claude-code-setup.svg?style=flat-square)](https://github.com/centminmod/my-claude-code-setup/issues) +* My AI journey Substack to follow me in more indepth AI adventures - https://ai.georgeliu.com * Threads - https://www.threads.com/@george_sl_liu * BlueSky - https://bsky.app/profile/georgesl.bsky.social From 8f758e8fd81576c5df522e3418b902c28bccd79c Mon Sep 17 00:00:00 2001 From: George Liu Date: Tue, 14 Apr 2026 14:52:18 +1000 Subject: [PATCH 106/174] add CLAUDE-history-template.md --- CLAUDE-history-template.md | 188 +++++++++++++++++++++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 CLAUDE-history-template.md diff --git a/CLAUDE-history-template.md b/CLAUDE-history-template.md new file mode 100644 index 0000000..667982b --- /dev/null +++ b/CLAUDE-history-template.md @@ -0,0 +1,188 @@ +# Claude Template + +Reusable instructions for carrying the progressive-disclosure development-history system into a new repository. Place below instructions into your CLAUDE.md if you want Claude to maintain a development history index and log. I find this useful for my own development workflow and as source material for writing AI building articles on my AI Substack https://ai.georgeliu.com. + +## Goal + +Keep a lightweight `CLAUDE-history.md` index in the repo root and store full narrative entries as separate files under `history/`. The index stays short and scannable; the detail lives in the linked entry files. + +## Files to Create + +```text +CLAUDE.md +AGENTS.md # if you keep a separate agent instruction file +CLAUDE-history.md +history/ + .counter +``` + +Initialize `history/.counter` with the next sequence number to use: + +```text +1 +``` + +## Block to Paste into `CLAUDE.md` or `AGENTS.md` + +~~~~markdown +## Development History Requirement + +**MANDATORY:** This project maintains a living development history. Use progressive disclosure: a lightweight index file plus individual entry files. + +### Structure + +```text +CLAUDE-history.md # Index only -- one row per entry, links to files +history/ + .counter # Plain text integer, next sequence number to use + 2026-04-10_001_decision_initial-architecture.md + 2026-04-10_002_code-change_add-auth-flow.md + ... +``` + +### What Gets Logged (Meaningful State Transitions Only) + +The history should capture narrative-worthy moments, not mechanical edits. Before creating an entry, ask: "Would this be useful context in a retrospective, handoff, or public write-up about building this project?" If the answer is no, skip it. + +**LOG these (meaningful state transitions):** +- A feature or tool reaching working state +- An architectural or implementation decision +- A bug or problem encountered, investigated, and resolved +- A new dependency added and why it was chosen +- A deployment attempt (success or failure) +- An unexpected discovery about a platform, API, or library +- A significant refactor that changes structure or design +- A configuration change that affects behavior +- A documentation change that materially improves onboarding, operation, or implementation clarity +- Batched related small changes as a single entry when together they represent one meaningful milestone + +**DO NOT LOG these (mechanical noise):** +- Fixing a typo, formatting, or linting +- Renaming a variable or file without changing behavior +- Adding or removing imports only +- Adjusting whitespace, comments, or style only +- Intermediate saves while a feature is still in progress +- Retrying a command that failed due to a transient issue +- Reading files or researching without a resulting action + +**When in doubt:** Batch related small changes into one entry rather than logging each one separately. + +### Procedure for Creating a New Entry + +1. Read `history/.counter` to get the next sequence number (for example `10`) +2. Create a new file: `history/YYYY-MM-DD_NNN_category_slug.md` where: + - `YYYY-MM-DD` is today's date + - `NNN` is the counter value, zero-padded to 3 digits (for example `010`) + - `category` is one of: `code-change`, `decision`, `bug-fix`, `dependency`, `deployment`, `refactor`, `configuration`, `testing`, `documentation`, `discovery` + - `slug` is a short kebab-case description +3. Write the entry file using this format: + +```markdown +# YYYY-MM-DD HH:MM -- [Category] + +**What:** Brief description of what happened +**Why:** Rationale or trigger for this change +**Details:** Technical details, decisions made, or relevant implementation notes +**Outcome:** Result or current state after this change +``` + +4. Append a new row to the appropriate table in `CLAUDE-history.md`: + +```markdown +| NNN | YYYY-MM-DD | Category | One-line summary | [history/filename.md](history/filename.md) | +``` + +5. Increment `history/.counter` (for example `10` becomes `11`) +6. At the same checkpoint, review the high-signal docs most likely to have drifted and update them if needed. Typical examples include: + - `README.md` + - architecture / ADR / implementation docs + - operator or runbook docs + - `CLAUDE.md` / `AGENTS.md` + +### When to Create an Entry + +Create an entry at these natural checkpoints: +- A feature or tool is complete and working +- A decision is made that shapes the direction of the project +- A bug is fully resolved +- A deployment is attempted +- A surprising discovery is confirmed +- Before a git commit that represents a logical unit of work + +At those checkpoints, also ask: "Did this change make any planning, onboarding, implementation, or operator docs inaccurate?" If yes, update those docs in the same unit of work. + +### Important + +- **Do NOT dump full details into `CLAUDE-history.md`** -- it is an index only +- **Do NOT read every history entry file by default** -- read the index first, then load individual entries on demand +- **Do NOT skip the counter increment** -- it prevents filename collisions +- **Do NOT treat docs as automatically current** -- meaningful changes should trigger a drift review +~~~~ + +## Starter `CLAUDE-history.md` + +Use this if you want a phase-based index: + +```markdown +# Development History: + +> Index of development entries for this project. Each entry is a separate file in `history/`. This file is the lightweight reference -- read individual entries on demand for full details. + +## How This Works + +- This file is an **index only** -- one line per entry with a link to the full entry file +- Full entry content lives in `history/YYYY-MM-DD_NNN_category_slug.md` +- The counter at `history/.counter` tracks the next sequence number +- Claude should update this index whenever a new entry is created + +--- + +## Phase 0: Planning + +| # | Date | Category | Summary | File | +|---|------|----------|---------|------| + +--- + +## Phase 1: Implementation + +| # | Date | Category | Summary | File | +|---|------|----------|---------|------| +``` + +If the repo does not use phases, keep a single table instead: + +```markdown +# Development History: + +> Index of development entries for this project. Each entry is a separate file in `history/`. This file is the lightweight reference -- read individual entries on demand for full details. + +| # | Date | Category | Summary | File | +|---|------|----------|---------|------| +``` + +## Starter Entry File + +```markdown +# YYYY-MM-DD HH:MM -- [Category] + +**What:** Brief description of what happened +**Why:** Why this work was done +**Details:** Technical detail, design choices, or relevant notes +**Outcome:** What changed or what the current state is now +``` + +## Suggested Setup Sequence for a New Repo + +1. Create `CLAUDE-history.md`, `history/`, and `history/.counter` +2. Paste the development-history block into `CLAUDE.md` +3. Mirror the same block into `AGENTS.md` if you use one +4. Seed the index with either phased sections or a single-table layout +5. Start writing entries only when a meaningful checkpoint is reached + +## Practical Defaults + +- Keep the index human-scannable +- Prefer one strong entry over several tiny ones +- Use the entry files for context that would clutter the main index +- Treat documentation changes as history-worthy only when they materially change how someone builds, operates, or understands the project From 5f6dc9eb8058b1c60088352e3c7dd9319ef1045d Mon Sep 17 00:00:00 2001 From: George Liu Date: Fri, 17 Apr 2026 22:18:37 +1000 Subject: [PATCH 107/174] add session-metrics skill - https://ai.georgeliu.com/p/i-built-a-token-cost-analyzer-skill --- .claude/skills/session-metrics/SKILL.md | 109 + .../references/jsonl-schema.md | 125 + .../session-metrics/references/pricing.md | 60 + .../scripts/session-metrics.py | 3143 +++++++++++++++++ .../scripts/vendor/charts/README.md | 62 + .../vendor/charts/chartjs/v4/LICENSE.txt | 9 + .../vendor/charts/chartjs/v4/chart.umd.js | 14 + .../vendor/charts/highcharts/v12/LICENSE.txt | 22 + .../charts/highcharts/v12/export-data.js | 14 + .../vendor/charts/highcharts/v12/exporting.js | 13 + .../charts/highcharts/v12/highcharts-3d.js | 12 + .../charts/highcharts/v12/highcharts.js | 10 + .../scripts/vendor/charts/manifest.json | 64 + .../vendor/charts/uplot/v1/LICENSE.txt | 21 + .../vendor/charts/uplot/v1/uPlot.iife.min.js | 2 + .../vendor/charts/uplot/v1/uPlot.min.css | 1 + .../session-metrics/tests/fixtures/mini.jsonl | 12 + .../tests/test_session_metrics.py | 705 ++++ README-v2.md | 1 + README-v3.md | 1 + README-v4.md | 43 + README.md | 16 + 22 files changed, 4459 insertions(+) create mode 100644 .claude/skills/session-metrics/SKILL.md create mode 100644 .claude/skills/session-metrics/references/jsonl-schema.md create mode 100644 .claude/skills/session-metrics/references/pricing.md create mode 100644 .claude/skills/session-metrics/scripts/session-metrics.py create mode 100644 .claude/skills/session-metrics/scripts/vendor/charts/README.md create mode 100644 .claude/skills/session-metrics/scripts/vendor/charts/chartjs/v4/LICENSE.txt create mode 100644 .claude/skills/session-metrics/scripts/vendor/charts/chartjs/v4/chart.umd.js create mode 100644 .claude/skills/session-metrics/scripts/vendor/charts/highcharts/v12/LICENSE.txt create mode 100644 .claude/skills/session-metrics/scripts/vendor/charts/highcharts/v12/export-data.js create mode 100644 .claude/skills/session-metrics/scripts/vendor/charts/highcharts/v12/exporting.js create mode 100644 .claude/skills/session-metrics/scripts/vendor/charts/highcharts/v12/highcharts-3d.js create mode 100644 .claude/skills/session-metrics/scripts/vendor/charts/highcharts/v12/highcharts.js create mode 100644 .claude/skills/session-metrics/scripts/vendor/charts/manifest.json create mode 100644 .claude/skills/session-metrics/scripts/vendor/charts/uplot/v1/LICENSE.txt create mode 100644 .claude/skills/session-metrics/scripts/vendor/charts/uplot/v1/uPlot.iife.min.js create mode 100644 .claude/skills/session-metrics/scripts/vendor/charts/uplot/v1/uPlot.min.css create mode 100644 .claude/skills/session-metrics/tests/fixtures/mini.jsonl create mode 100644 .claude/skills/session-metrics/tests/test_session_metrics.py diff --git a/.claude/skills/session-metrics/SKILL.md b/.claude/skills/session-metrics/SKILL.md new file mode 100644 index 0000000..d417fd5 --- /dev/null +++ b/.claude/skills/session-metrics/SKILL.md @@ -0,0 +1,109 @@ +--- +name: session-metrics +description: > + Tally Claude Code session token usage and cost estimates from the raw JSONL + conversation log. Trigger when the user asks about session cost, token usage, + API spend, cache hit rate, input/output tokens, or wants a breakdown of how + much a Claude Code session has cost. Also trigger for "how much have we spent", + "show me token usage", "session summary", "cost so far", or any request to + analyse or display per-turn metrics from the current or a past session. +--- + +# Session Metrics + +Runs `scripts/session-metrics.py` against the Claude Code JSONL log to produce +a timeline-ordered cost summary with per-turn and cumulative totals. + +## Quick usage + +```bash +# Current session (auto-detected from cwd) +uv run python .claude/skills/session-metrics/scripts/session-metrics.py + +# Specific session ID +uv run python .claude/skills/session-metrics/scripts/session-metrics.py --session + +# Specific project slug (use = when slug starts with "-") +uv run python .claude/skills/session-metrics/scripts/session-metrics.py --slug=-home-user-projects-myapp +# Or via env var (always safe): +CLAUDE_PROJECT_SLUG="-home-user-projects-myapp" uv run python .claude/skills/session-metrics/scripts/session-metrics.py + +# List available sessions for this project +uv run python .claude/skills/session-metrics/scripts/session-metrics.py --list + +# All sessions — timeline + per-session subtotals + grand project total +uv run python .claude/skills/session-metrics/scripts/session-metrics.py --project-cost + +# Export to exports/session-metrics/ (one or more formats) +uv run python .claude/skills/session-metrics/scripts/session-metrics.py --output json +uv run python .claude/skills/session-metrics/scripts/session-metrics.py --output json csv md html +uv run python .claude/skills/session-metrics/scripts/session-metrics.py --project-cost --output html +``` + +## Export formats + +`--output` accepts one or more of: `json` `csv` `md` `html` + +Text is always printed to stdout. Exports go to `exports/session-metrics/` in the +project root, named `session__.` (single) or +`project_.` (project mode). + +| Format | Contents | +|--------|----------| +| `json` | Full structured report with all turns, subtotals, model rates | +| `csv` | One row per turn: session_id, index, timestamp, model, tokens, cost | +| `md` | Summary table + per-session Markdown tables | +| `html` | Dark-theme report with summary cards + insights + chart. 2-page split by default (`_dashboard.html` + `_detail.html`); pass `--single-page` for one file. | + +### HTML-specific flags + +| Flag | Purpose | +|------|---------| +| `--single-page` | Emit one self-contained HTML instead of the dashboard+detail split. | +| `--chart-lib {highcharts,uplot,chartjs,none}` | Choose the chart renderer. Default `highcharts` (richest visualization, vendored, SHA-256-verified, non-commercial license). `uplot` and `chartjs` are MIT-licensed alternatives. `none` emits a detail page with no JS dependency. See [`scripts/vendor/charts/README.md`](scripts/vendor/charts/README.md) for per-library license terms. | +| `--peak-hours H-H` | Translucent band on the hour-of-day chart (e.g. `5-11`). Community-reported, not an Anthropic SLA. | +| `--peak-tz ` | Timezone the peak hours are defined in (default `America/Los_Angeles`). | + +### Other useful flags + +| Flag | Purpose | +|------|---------| +| `--tz ` | IANA timezone for time-of-day bucketing. Defaults to system local tz. | +| `--utc-offset ` | Fixed UTC offset, DST-naive. Use `--tz` for DST-aware. | +| `--no-cache` | Skip `~/.cache/session-metrics/parse/` and always re-parse from scratch. | +| `--include-subagents` | Also tally spawned subagent JSONL files. | + +## Output columns + +| Column | Meaning | +|----------|----------------------------------------------| +| `#` | Deduplicated turn index | +| `Time` | UTC timestamp of the turn | +| `Input` | Net new input tokens (uncached portion only — cache reads/writes are shown separately) | +| `Output` | Output tokens generated | +| `CacheRd`| Tokens served from prompt cache (cheap) | +| `CacheWr`| Tokens written to prompt cache (one-time) | +| `Cost $` | Estimated USD for this turn | + +Footer shows session totals + **cache savings** vs a hypothetical no-cache run. + +## Reference files + +- [`references/pricing.md`](references/pricing.md) — Per-model token prices used + for cost calculation. Read this when the user asks about pricing or if you need + to add a new model. +- [`references/jsonl-schema.md`](references/jsonl-schema.md) — JSONL entry + structure. Read this when debugging missing data or extending the script. + +## How session detection works + +1. Derives the project slug from `cwd`: replaces `/` → `-`, strips leading `-`. +2. Scans `~/.claude/projects//` for `*.jsonl` files (excludes `subagents/`). +3. Picks the most recently modified file as the current session. +4. Override with `--session ` or `--slug ` when needed. + +## Deduplication + +Each API response is written to the JSONL multiple times (streaming, tool +completion, final). The script deduplicates on `message.id` — keeping only the +**last** occurrence so token counts reflect the final settled value. diff --git a/.claude/skills/session-metrics/references/jsonl-schema.md b/.claude/skills/session-metrics/references/jsonl-schema.md new file mode 100644 index 0000000..6fe576c --- /dev/null +++ b/.claude/skills/session-metrics/references/jsonl-schema.md @@ -0,0 +1,125 @@ +# Claude Code JSONL Log Schema + +Location: `~/.claude/projects//.jsonl` + +Each line is a self-contained JSON object (newline-delimited JSON / NDJSON). + +--- + +## Entry types + +### `assistant` — API response (contains usage data) + +```json +{ + "type": "assistant", + "uuid": "7e538ffb-...", + "parentUuid": "49422fd5-...", + "isSidechain": false, + "timestamp": "2026-04-15T02:32:32.185Z", + "sessionId": "60fb0cc8-286f-41b4-ad12-4bad42fd20ad", + "cwd": "/home/user/projects/myapp", + "version": "2.1.101", + "gitBranch": "master", + "entrypoint": "claude-desktop", + "userType": "external", + "requestId": "req_011Ca4moqagPBTkv4htSbuMU", + "message": { + "id": "msg_01GvBhABmRVqm3qv4G6innqL", ← deduplicate on this + "model": "claude-sonnet-4-6", + "role": "assistant", + "type": "message", + "stop_reason": "tool_use", + "content": [ ... ], + "usage": { + "input_tokens": 10, + "output_tokens": 208, + "cache_read_input_tokens": 27839, + "cache_creation_input_tokens": 468, + "cache_creation": { + "ephemeral_1h_input_tokens": 468, + "ephemeral_5m_input_tokens": 0 + }, + "server_tool_use": { + "web_search_requests": 0, + "web_fetch_requests": 0 + }, + "service_tier": "standard", + "speed": "standard" + } + } +} +``` + +### `user` — human prompt OR tool-result turn (no usage data) + +```json +{ + "type": "user", + "uuid": "...", + "parentUuid": "...", + "timestamp": "2026-04-15T02:32:30.000Z", + "sessionId": "...", + "message": { + "role": "user", + "content": [ ... ] // OR a plain string — both observed in the wild + } +} +``` + +**`message.content` has two observed shapes**: + +1. **List of content blocks** (majority of entries). Each block is an object with a `type` field: + - `type: "text"` — the user's typed prompt. + - `type: "image"` — pasted image in the prompt. + - `type: "tool_result"` — **auto-generated** after every tool call the assistant makes. These are NOT user-typed messages but have `type: "user"` at the entry level. +2. **Plain string** (~10% of entries) — a direct user-typed prompt without structured content blocks. The original schema docs only mentioned shape 1; shape 2 is present in practice. + +**Filter rule for user-activity analysis**: a genuine user prompt is an entry whose `message.content` is either a non-empty string, OR a list containing at least one block with `type in {"text", "image"}`. Pure `tool_result`-only lists must be excluded — counting them inflates "user activity" metrics by 10–20× on tool-heavy sessions. + +See `_is_user_prompt` in `scripts/session-metrics.py` for the implementation. + +### `summary` — context compression event + +```json +{ + "type": "summary", + "summary": "...", + "leafUuid": "..." +} +``` + +--- + +## Deduplication behaviour + +Claude Code writes the same `message.id` to the JSONL at multiple lifecycle +points (start of stream, after each tool result, after final `stop_reason`). +Token counts in earlier writes may be partial or zero. + +**Always keep the LAST occurrence** of each `message.id` — it reflects the +final settled usage values. + +--- + +## Key fields for cost calculation + +| Field path | Description | +|------------|-------------| +| `message.id` | Dedup key | +| `message.model` | Model ID → pricing lookup | +| `message.usage.input_tokens` | Net new input tokens | +| `message.usage.output_tokens` | Generated output tokens | +| `message.usage.cache_read_input_tokens` | Served from cache | +| `message.usage.cache_creation_input_tokens` | Written to cache | +| `message.usage.speed` | `"standard"` (normal mode) or `"fast"` (Claude Code fast mode `/fast`) | +| `message.usage.service_tier` | `"standard"` (always observed so far) | +| `timestamp` | ISO-8601 UTC, use for timeline ordering | + +--- + +## Subagent logs + +Spawned agents write to `/subagents/agent-.jsonl`. +The main script ignores subagent files by default; pass `--include-subagents` +to fold them in (adds a `[subagent]` marker in the turn index). diff --git a/.claude/skills/session-metrics/references/pricing.md b/.claude/skills/session-metrics/references/pricing.md new file mode 100644 index 0000000..7ad444e --- /dev/null +++ b/.claude/skills/session-metrics/references/pricing.md @@ -0,0 +1,60 @@ +# Claude Model Pricing Reference + +Prices in **USD per million tokens**. Snapshot: **2026-04-17**. +Source: https://platform.claude.com/docs/en/about-claude/pricing + +The `cache_write` column stored by `_PRICING` is the **5-minute cache write** +rate (1.25× base input). The **1-hour cache write** rate is 2× base input and +is not currently tracked per-entry. **Cache read** (hits + refreshes) is +0.1× base input. + +## Current models + +| Model ID | Alias | Input | Output | Cache read | 5m Cache write | +|-----------------------------|------------|-------|--------|------------|----------------| +| `claude-opus-4-7` | opus-4-7 | 5.00 | 25.00 | 0.50 | 6.25 | +| `claude-opus-4-6` | opus-4-6 | 5.00 | 25.00 | 0.50 | 6.25 | +| `claude-opus-4-5` | opus-4-5 | 5.00 | 25.00 | 0.50 | 6.25 | +| `claude-sonnet-4-7` | sonnet-4-7 | 3.00 | 15.00 | 0.30 | 3.75 | +| `claude-sonnet-4-6` | sonnet-4-6 | 3.00 | 15.00 | 0.30 | 3.75 | +| `claude-sonnet-4-5` | sonnet-4-5 | 3.00 | 15.00 | 0.30 | 3.75 | +| `claude-haiku-4-5-20251001` | haiku-4-5 | 1.00 | 5.00 | 0.10 | 1.25 | +| `claude-haiku-4-5` | haiku-4-5 | 1.00 | 5.00 | 0.10 | 1.25 | + +> **Important — pricing tier change at Opus 4.5**: Opus 4.5 / 4.6 / 4.7 moved +> to a new cheaper tier ($5 input / $25 output). Opus 4 and 4.1 retain the +> original $15 / $75 tier. Earlier snapshots of this table had Opus 4.6/4.7 +> at the old rates — corrected 2026-04-17. + +## Legacy / prefix-fallback entries + +These entries are kept for historical JSONL files that reference older models, +and for prefix-matching fallback when a model ID isn't explicitly listed. + +| Model ID (prefix match) | Input | Output | Cache read | 5m Cache write | +|-------------------------|-------|--------|------------|----------------| +| `claude-opus-4-1` | 15.00 | 75.00 | 1.50 | 18.75 | +| `claude-opus-4` | 15.00 | 75.00 | 1.50 | 18.75 | +| `claude-sonnet-4` | 3.00 | 15.00 | 0.30 | 3.75 | +| `claude-3-7-sonnet` | 3.00 | 15.00 | 0.30 | 3.75 | +| `claude-3-5-sonnet` | 3.00 | 15.00 | 0.30 | 3.75 | +| `claude-3-5-haiku` | 0.80 | 4.00 | 0.08 | 1.00 | +| `claude-3-opus` | 15.00 | 75.00 | 1.50 | 18.75 | +| (default fallback) | 3.00 | 15.00 | 0.30 | 3.75 | + +## Notes + +- **Prefix fallback order matters**: dict insertion order is traversed until + the first match. More-specific entries (e.g. `claude-opus-4-7`) must appear + **before** less-specific ones (e.g. `claude-opus-4`), otherwise an unknown + future Opus-4.7-* model ID would fall through to the old-tier rate. +- **5m vs 1h cache writes**: `_cost` only multiplies by the 5-minute rate. + 1-hour writes (2× base input) would undercount cost when present; add + per-entry TTL tracking if this becomes material. +- **Fast mode** (Opus 4.6 research preview): 6× standard base rates + ($30 input / $150 output). Not currently applied by `_cost` even when + `usage.speed == "fast"`. Cost display for fast-mode turns is therefore + underestimated by a factor of 6 — flagged as a known limitation. +- **Data residency multiplier**: US-only inference via `inference_geo` + adds 1.1× on top of all rates. Not tracked. +- Prices are estimates; actual billing is on Anthropic's platform. diff --git a/.claude/skills/session-metrics/scripts/session-metrics.py b/.claude/skills/session-metrics/scripts/session-metrics.py new file mode 100644 index 0000000..f4f423e --- /dev/null +++ b/.claude/skills/session-metrics/scripts/session-metrics.py @@ -0,0 +1,3143 @@ +#!/usr/bin/env python3 +# /// script +# requires-python = ">=3.11" +# /// +""" +session-metrics.py — Claude Code session cost estimator + +Reads the JSONL conversation log and produces a timeline-ordered table of +per-turn token usage and estimated USD cost. + +Usage: + uv run python session-metrics.py # auto-detect from cwd + uv run python session-metrics.py --session # specific session + uv run python session-metrics.py --slug # specific project slug + uv run python session-metrics.py --list # list sessions for project + uv run python session-metrics.py --project-cost # all sessions, timeline + totals + uv run python session-metrics.py --output json html # export to exports/session-metrics/ + uv run python session-metrics.py --include-subagents # include spawned agents + +--output accepts one or more of: text json csv md html + Writes to /exports/session-metrics/_. + Text is always printed to stdout; other formats are written to files. + +Environment variables (all optional — CLI flags take precedence): + CLAUDE_SESSION_ID Session UUID to analyse + CLAUDE_PROJECT_SLUG Project slug override (e.g. -Volumes-foo-bar-project) + CLAUDE_PROJECTS_DIR Override ~/.claude/projects (default: ~/.claude/projects) +""" + +import argparse +import csv as csv_mod +import gzip +import hashlib +import io +import json +import os +import re +import sys +from datetime import datetime, timezone +from pathlib import Path +from zoneinfo import ZoneInfo, ZoneInfoNotFoundError + +# Bump when the parsed-entries shape changes — invalidates old parse caches. +_SCRIPT_VERSION = "1.0-rc.4" + +# --------------------------------------------------------------------------- +# Pricing table (USD per million tokens) +# See references/pricing.md for notes and source. +# --------------------------------------------------------------------------- +# Per-million-token rates (USD). Source: https://platform.claude.com/docs/en/about-claude/pricing +# Snapshot: 2026-04-17. Cache-write column = 5-minute cache write (1.25x base input); +# 1-hour cache writes cost 2x base input but are not currently tracked per-entry. +# +# IMPORTANT: Opus 4.5 / 4.6 / 4.7 use the NEW cheaper tier ($5/$25) introduced +# with the 4.5 generation. Opus 4 / 4.1 retain the OLD tier ($15/$75). Dict +# order matters for prefix fallback — more-specific entries must appear first. +_PRICING: dict[str, dict[str, float]] = { + # --- Opus 4.5-generation (new tier: $5 input / $25 output) --- + "claude-opus-4-7": {"input": 5.00, "output": 25.00, "cache_read": 0.50, "cache_write": 6.25}, + "claude-opus-4-6": {"input": 5.00, "output": 25.00, "cache_read": 0.50, "cache_write": 6.25}, + "claude-opus-4-5": {"input": 5.00, "output": 25.00, "cache_read": 0.50, "cache_write": 6.25}, + # --- Opus 4 / 4.1 (old tier, retained for historical sessions) --- + "claude-opus-4-1": {"input": 15.00, "output": 75.00, "cache_read": 1.50, "cache_write": 18.75}, + "claude-opus-4": {"input": 15.00, "output": 75.00, "cache_read": 1.50, "cache_write": 18.75}, + # --- Sonnet 4.x + 3.7 (shared rates) --- + "claude-sonnet-4-7": {"input": 3.00, "output": 15.00, "cache_read": 0.30, "cache_write": 3.75}, + "claude-sonnet-4-6": {"input": 3.00, "output": 15.00, "cache_read": 0.30, "cache_write": 3.75}, + "claude-sonnet-4-5": {"input": 3.00, "output": 15.00, "cache_read": 0.30, "cache_write": 3.75}, + "claude-sonnet-4": {"input": 3.00, "output": 15.00, "cache_read": 0.30, "cache_write": 3.75}, + "claude-3-7-sonnet": {"input": 3.00, "output": 15.00, "cache_read": 0.30, "cache_write": 3.75}, + "claude-3-5-sonnet": {"input": 3.00, "output": 15.00, "cache_read": 0.30, "cache_write": 3.75}, + # --- Haiku 4.5 (own tier: $1 input / $5 output) --- + "claude-haiku-4-5-20251001": {"input": 1.00, "output": 5.00, "cache_read": 0.10, "cache_write": 1.25}, + "claude-haiku-4-5": {"input": 1.00, "output": 5.00, "cache_read": 0.10, "cache_write": 1.25}, + # --- Haiku 3.5 (older, cheaper input) --- + "claude-3-5-haiku": {"input": 0.80, "output": 4.00, "cache_read": 0.08, "cache_write": 1.00}, + # --- Opus 3 (deprecated; old-tier rates) --- + "claude-3-opus": {"input": 15.00, "output": 75.00, "cache_read": 1.50, "cache_write": 18.75}, +} +_DEFAULT_PRICING = {"input": 3.00, "output": 15.00, "cache_read": 0.30, "cache_write": 3.75} + + +def _pricing_for(model: str) -> dict[str, float]: + if model in _PRICING: + return _PRICING[model] + for prefix, rates in _PRICING.items(): + if model.startswith(prefix): + return rates + return _DEFAULT_PRICING + + +def _cost(u: dict, model: str) -> float: + r = _pricing_for(model) + return ( + u.get("input_tokens", 0) * r["input"] / 1_000_000 + + u.get("output_tokens", 0) * r["output"] / 1_000_000 + + u.get("cache_read_input_tokens", 0) * r["cache_read"] / 1_000_000 + + u.get("cache_creation_input_tokens", 0) * r["cache_write"] / 1_000_000 + ) + + +def _no_cache_cost(u: dict, model: str) -> float: + r = _pricing_for(model) + total_input = ( + u.get("input_tokens", 0) + + u.get("cache_read_input_tokens", 0) + + u.get("cache_creation_input_tokens", 0) + ) + return total_input * r["input"] / 1_000_000 + u.get("output_tokens", 0) * r["output"] / 1_000_000 + + +# --------------------------------------------------------------------------- +# JSONL parsing +# --------------------------------------------------------------------------- + +def _parse_jsonl(path: Path) -> list[dict]: + entries = [] + skipped = 0 + first_err: str | None = None + with open(path, encoding="utf-8") as fh: + for lineno, line in enumerate(fh, 1): + line = line.strip() + if not line: + continue + try: + entries.append(json.loads(line)) + except json.JSONDecodeError as exc: + skipped += 1 + if first_err is None: + first_err = f"line {lineno}: {exc}" + if skipped: + suffix = f" (first: {first_err})" if first_err else "" + print(f"[warn] {path.name}: {skipped} malformed line{'s' if skipped != 1 else ''} skipped{suffix}", + file=sys.stderr) + return entries + + +def _parse_cache_dir() -> Path: + """Return the directory for serialized parse-cache blobs.""" + return Path.home() / ".cache" / "session-metrics" / "parse" + + +def _parse_cache_key(path: Path, mtime_ns: int) -> str: + """Build a stable cache-key filename from path stem, mtime, and script ver. + + Using ``mtime_ns`` (nanoseconds since epoch) means a touched JSONL always + invalidates the cache. Bumping ``_SCRIPT_VERSION`` invalidates every + existing blob — safe default when the parser shape changes. + """ + return f"{path.stem}__{mtime_ns}__{_SCRIPT_VERSION}.json.gz" + + +def _cached_parse_jsonl(path: Path, use_cache: bool = True) -> list[dict]: + """Return parsed entries from ``path``, using a gzip-JSON cache on disk. + + Cache hit (typical re-run): ~10x faster than parsing JSONL line-by-line, + since ``json.loads`` on one preassembled blob avoids the per-line state + machine overhead. Cache miss or ``use_cache=False``: parse fresh and + (if caching) write the blob for next time. + + Cache invalidation is automatic on (a) JSONL mtime change and + (b) ``_SCRIPT_VERSION`` bump. On I/O errors the cache is silently + skipped — correctness first, speed second. + """ + if not use_cache: + return _parse_jsonl(path) + try: + mtime_ns = path.stat().st_mtime_ns + except OSError: + return _parse_jsonl(path) + + cache_dir = _parse_cache_dir() + cache_path = cache_dir / _parse_cache_key(path, mtime_ns) + if cache_path.exists(): + try: + with gzip.open(cache_path, "rt", encoding="utf-8") as fh: + return json.load(fh) + except (OSError, json.JSONDecodeError): + # Corrupt or unreadable — fall through to fresh parse. + pass + + entries = _parse_jsonl(path) + try: + cache_dir.mkdir(parents=True, exist_ok=True) + # Write atomically so a crash mid-write doesn't leave a corrupt cache. + tmp = cache_path.with_suffix(cache_path.suffix + ".tmp") + with gzip.open(tmp, "wt", encoding="utf-8") as fh: + json.dump(entries, fh, separators=(",", ":")) + tmp.replace(cache_path) + except OSError: + # Non-fatal — the parse already succeeded. + pass + return entries + + +def _extract_turns(entries: list[dict]) -> list[dict]: + """Deduplicate on message.id, keep last occurrence, sort by timestamp.""" + seen: dict[str, dict] = {} + for entry in entries: + if entry.get("type") != "assistant": + continue + msg = entry.get("message", {}) + if "usage" not in msg: + continue + msg_id = msg.get("id") + if msg_id: + seen[msg_id] = entry + turns = list(seen.values()) + turns.sort(key=lambda e: e.get("timestamp", "")) + return turns + + +# --------------------------------------------------------------------------- +# Time-of-day analysis +# --------------------------------------------------------------------------- + +_TOD_PERIODS = ( + ("night", 0, 6), # 00:00–05:59 + ("morning", 6, 12), # 06:00–11:59 + ("afternoon", 12, 18), # 12:00–17:59 + ("evening", 18, 24), # 18:00–23:59 +) + + +def _is_user_prompt(entry: dict) -> bool: + """Return True for genuine user-typed prompts only. + + Claude Code's JSONL records three kinds of ``type == "user"`` entry: + - real user messages typed by the human (what we want to count) + - tool_result entries auto-generated after every tool call (inflates counts) + - system-injected meta entries (``isMeta``) + + A user-typed message has ``message.content`` that is either a plain + string, or a list containing at least one ``text`` or ``image`` block + (never only ``tool_result`` blocks). Sampling real JSONLs showed both + shapes in the wild; the original schema doc listed only the list shape. + """ + if entry.get("type") != "user": + return False + if entry.get("isMeta"): + return False + msg = entry.get("message") or {} + content = msg.get("content") + if isinstance(content, str): + return bool(content.strip()) + if isinstance(content, list): + for block in content: + if not isinstance(block, dict): + continue + t = block.get("type") + if t == "text" or t == "image": + return True + return False + return False + + +def _extract_user_timestamps( + entries: list[dict], include_sidechain: bool = False, +) -> list[int]: + """Extract UTC epoch-seconds for every genuine user prompt. + + Uses ``_is_user_prompt`` to exclude tool_result and meta entries, which + the original implementation wrongly counted as user activity. By default, + also excludes ``isSidechain`` (subagent) entries; pass + ``include_sidechain=True`` when the caller wants them folded in (matches + the ``--include-subagents`` CLI flag). + + Returns: + Sorted list of integer timestamps (seconds since Unix epoch, UTC). + Malformed or missing timestamps are silently skipped. + """ + timestamps: list[int] = [] + for entry in entries: + if not _is_user_prompt(entry): + continue + if entry.get("isSidechain") and not include_sidechain: + continue + ts = entry.get("timestamp", "") + if not ts: + continue + try: + dt = datetime.fromisoformat(ts.replace("Z", "+00:00")) + timestamps.append(int(dt.timestamp())) + except (ValueError, OSError): + continue + timestamps.sort() + return timestamps + + +def _bucket_time_of_day(epoch_secs: list[int], offset_hours: float = 0) -> dict[str, int]: + """Bucket UTC epoch-second timestamps into four time-of-day periods. + + Uses pure integer arithmetic for performance — no datetime objects are + allocated in the hot loop. Python's ``%`` operator always returns a + non-negative result when the divisor is positive, so no extra guard is + needed server-side (the JS counterpart uses a double-modulo idiom). + + Args: + epoch_secs: Sorted list of UTC epoch-seconds (from + ``_extract_user_timestamps``). + offset_hours: UTC offset for the display timezone, e.g. ``-8`` for + PT or ``10`` for Brisbane. Accepts float for half-hour offsets + (e.g. ``5.5`` for IST). + + Returns: + Dict with keys ``night``, ``morning``, ``afternoon``, ``evening``, + and ``total`` — each an integer count of user messages in that period. + """ + offset_sec = int(offset_hours * 3600) + counts = {key: 0 for key, _, _ in _TOD_PERIODS} + for epoch in epoch_secs: + local_hour = ((epoch + offset_sec) % 86400) // 3600 + for key, start, end in _TOD_PERIODS: + if start <= local_hour < end: + counts[key] += 1 + break + counts["total"] = sum(counts[k] for k, _, _ in _TOD_PERIODS) + return counts + + +def _build_hour_of_day(epoch_secs: list[int], offset_hours: float = 0.0) -> dict: + """Build 24-bucket hour-of-day counts from user timestamps. + + Returns ``{"hours": [24 ints], "total": int, "offset_hours": float}``. + ``hours[0]`` is 00:00-00:59 in the display tz; ``hours[23]`` is 23:00-23:59. + """ + offset_sec = int(offset_hours * 3600) + hours = [0] * 24 + for e in epoch_secs: + h = ((e + offset_sec) % 86400) // 3600 + hours[h] += 1 + return {"hours": hours, "total": sum(hours), "offset_hours": offset_hours} + + +def _build_weekday_hour_matrix(epoch_secs: list[int], offset_hours: float = 0.0) -> dict: + """Build a 7x24 weekday-by-hour activity matrix in the display tz. + + Row 0 is Monday (matches ``datetime.weekday()``); row 6 is Sunday. + 1970-01-01 was a Thursday (weekday=3), so a day count since the UTC + epoch maps to weekday via ``(days + 3) % 7``. Python's floor-div gives + correct day counts for negative operands, so a negative ``offset_hours`` + on a near-epoch timestamp still produces a valid weekday. + """ + offset_sec = int(offset_hours * 3600) + matrix = [[0] * 24 for _ in range(7)] + for e in epoch_secs: + local = e + offset_sec + days = local // 86400 + weekday = (days + 3) % 7 + hour = (local % 86400) // 3600 + matrix[weekday][hour] += 1 + row_totals = [sum(row) for row in matrix] + col_totals = [sum(matrix[r][h] for r in range(7)) for h in range(24)] + return { + "matrix": matrix, + "row_totals": row_totals, + "col_totals": col_totals, + "total": sum(row_totals), + "offset_hours": offset_hours, + } + + +def _build_time_of_day(epoch_secs: list[int], offset_hours: float = 0.0) -> dict: + """Build the ``time_of_day`` report section from user timestamps. + + Args: + epoch_secs: Sorted UTC epoch-seconds for genuine user prompts. + offset_hours: Display-timezone offset applied to the ``buckets``, + ``hour_of_day``, and ``weekday_hour`` views (for static exports). + The raw ``epoch_secs`` array is preserved so HTML client-side JS + can re-bucket to any tz. + + Returns: + Dict with ``epoch_secs``, ``message_count``, ``buckets`` (4-period), + ``hour_of_day`` (24-bucket), ``weekday_hour`` (7x24 matrix), and + ``offset_hours``. + """ + return { + "epoch_secs": epoch_secs, + "message_count": len(epoch_secs), + "buckets": _bucket_time_of_day(epoch_secs, offset_hours=offset_hours), + "hour_of_day": _build_hour_of_day(epoch_secs, offset_hours=offset_hours), + "weekday_hour": _build_weekday_hour_matrix(epoch_secs, offset_hours=offset_hours), + "offset_hours": offset_hours, + } + + +# --------------------------------------------------------------------------- +# Timezone helpers (Step 5) +# --------------------------------------------------------------------------- + +def _local_tz_offset() -> float: + """Detect the system timezone offset in hours (float, supports :30/:45). + + Returns 0.0 on failure (e.g. no TZ info available). + """ + try: + delta = datetime.now().astimezone().utcoffset() + if delta is None: + return 0.0 + return delta.total_seconds() / 3600.0 + except Exception: + return 0.0 + + +def _local_tz_label() -> str: + """Detect the system timezone IANA name, best-effort. + + Returns a string like ``"Australia/Brisbane"`` or falls back to a + ``"UTC+10"``-style label if the name isn't available. + """ + try: + name = datetime.now().astimezone().tzname() + if name: + return name + except Exception: + pass + off = _local_tz_offset() + sign = "+" if off >= 0 else "-" + return f"UTC{sign}{abs(off):g}" + + +def _parse_peak_hours(value: str) -> tuple[int, int]: + """Parse ``--peak-hours "5-11"`` into ``(start, end)`` with end exclusive. + + Accepts ``H-H`` or ``HH-HH`` with 0 <= start <= 23 and 1 <= end <= 24. + Wrap-around (end <= start) is rejected; split it across two flags if + genuinely needed (rare case; keeping v1 simple). + """ + m = re.match(r"^\s*(\d{1,2})\s*-\s*(\d{1,2})\s*$", value or "") + if not m: + raise argparse.ArgumentTypeError( + f"invalid peak-hours {value!r} (expected H-H, e.g. '5-11')" + ) + start, end = int(m.group(1)), int(m.group(2)) + if not (0 <= start < end <= 24): + raise argparse.ArgumentTypeError( + f"invalid peak-hours {value!r} (need 0 <= start < end <= 24)" + ) + return (start, end) + + +def _build_peak(peak_hours: tuple[int, int] | None, + peak_tz: str | None) -> dict | None: + """Build a ``peak`` section from CLI inputs, resolving the peak tz offset. + + Returns None when ``peak_hours`` is not set. Defaults ``peak_tz`` to + ``America/Los_Angeles`` (where the "peak hours" terminology originates + in community reports) when only ``peak_hours`` is provided. + """ + if peak_hours is None: + return None + tz_name = peak_tz or "America/Los_Angeles" + try: + zi = ZoneInfo(tz_name) + delta = datetime.now(zi).utcoffset() + off = delta.total_seconds() / 3600.0 if delta else 0.0 + except ZoneInfoNotFoundError: + print(f"[warn] unknown peak-tz {tz_name!r}; using UTC", + file=sys.stderr) + off, tz_name = 0.0, "UTC" + start, end = peak_hours + return { + "start": start, + "end": end, + "tz_offset_hours": off, + "tz_label": tz_name, + "note": "unofficial \u2014 community-reported", + } + + +def _resolve_tz(tz_name: str | None, utc_offset: float | None) -> tuple[float, str]: + """Resolve the display timezone from CLI/env inputs. + + Priority: ``tz_name`` (IANA, DST-aware) > ``utc_offset`` (fixed float) > + local system tz. Returns ``(offset_hours, label)``. + + Note: with an IANA name, the offset returned is the *current* offset — + adequate for static exports but ``ZoneInfo`` must be used by the HTML + client for per-event DST-aware bucketing across historical dates. + """ + if tz_name: + try: + zi = ZoneInfo(tz_name) + now = datetime.now(zi) + delta = now.utcoffset() + off = delta.total_seconds() / 3600.0 if delta else 0.0 + return off, tz_name + except ZoneInfoNotFoundError: + print(f"[warn] unknown tz {tz_name!r}; using UTC", file=sys.stderr) + return 0.0, "UTC" + if utc_offset is not None: + sign = "+" if utc_offset >= 0 else "-" + return utc_offset, f"UTC{sign}{abs(utc_offset):g}" + return _local_tz_offset(), _local_tz_label() + + +# --------------------------------------------------------------------------- +# 5-hour session blocks (rate-limit debugging) +# --------------------------------------------------------------------------- + +_BLOCK_WINDOW_SEC = 5 * 3600 + + +def _parse_iso_epoch(ts: str) -> int: + """Parse an ISO-8601 timestamp to UTC epoch seconds; 0 on failure.""" + if not ts: + return 0 + try: + return int(datetime.fromisoformat(ts.replace("Z", "+00:00")).timestamp()) + except (ValueError, AttributeError, OSError): + return 0 + + +def _build_session_blocks( + sessions_raw: list[tuple[str, list[dict], list[int]]], +) -> list[dict]: + """Group all events into 5-hour blocks anchored at each block's first event. + + A block starts when an event arrives more than 5 hours after the previous + block's anchor. Events are the union of filtered user prompts and + assistant-turn timestamps across every session in the project — this + matches what Anthropic's rate-limit window sees (users can ``/clear`` + mid-block and the window keeps running). + + Each block records: anchor and last timestamps, elapsed minutes, turn + count, user-message count, per-bucket token totals, USD cost, model mix, + and which session IDs touched the block. + """ + events: list[tuple[int, str, str, dict | None]] = [] + for session_id, raw_turns, user_ts in sessions_raw: + for u in user_ts: + events.append((u, "user", session_id, None)) + for t in raw_turns: + e = _parse_iso_epoch(t.get("timestamp", "")) + if e: + events.append((e, "turn", session_id, t)) + events.sort(key=lambda x: x[0]) + + blocks: list[dict] = [] + for epoch, kind, sid, turn in events: + if not blocks or (epoch - blocks[-1]["anchor_epoch"]) >= _BLOCK_WINDOW_SEC: + blocks.append({ + "anchor_epoch": epoch, + "last_epoch": epoch, + "turn_count": 0, + "user_msg_count": 0, + "input": 0, + "output": 0, + "cache_read": 0, + "cache_write": 0, + "cost_usd": 0.0, + "models": {}, + "sessions_touched": set(), + }) + b = blocks[-1] + b["last_epoch"] = epoch + b["sessions_touched"].add(sid) + if kind == "user": + b["user_msg_count"] += 1 + else: + msg = turn["message"] + u = msg["usage"] + model = msg.get("model", "unknown") + b["turn_count"] += 1 + b["input"] += u.get("input_tokens", 0) + b["output"] += u.get("output_tokens", 0) + b["cache_read"] += u.get("cache_read_input_tokens", 0) + b["cache_write"] += u.get("cache_creation_input_tokens", 0) + b["cost_usd"] += _cost(u, model) + b["models"][model] = b["models"].get(model, 0) + 1 + + for b in blocks: + b["sessions_touched"] = sorted(b["sessions_touched"]) + b["elapsed_min"] = (b["last_epoch"] - b["anchor_epoch"]) / 60.0 + b["anchor_iso"] = datetime.fromtimestamp( + b["anchor_epoch"], tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") + b["last_iso"] = datetime.fromtimestamp( + b["last_epoch"], tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") + return blocks + + +def _build_weekly_rollup( + sessions_out: list[dict], + sessions_raw: list[tuple[str, list[dict], list[int]]], + session_blocks: list[dict], + now_epoch: int | None = None, +) -> dict: + """Compare the trailing 7 days against the prior 7 days. + + Uses **deduped** assistant turns from ``sessions_out`` (match the report's + cost/token totals) and filtered user prompts from ``sessions_raw``. + Block counts use each block's anchor epoch — a block "belongs" to the + window its first event lands in. + + Returns ``{"trailing_7d": {...}, "prior_7d": {...}, "has_data": bool, + "now_epoch": int}``. When ``prior_7d`` has zero turns, callers should + render deltas as "new period" rather than infinite percentage. + """ + if now_epoch is None: + now_epoch = int(datetime.now(tz=timezone.utc).timestamp()) + cutoff7 = now_epoch - 7 * 86400 + cutoff14 = now_epoch - 14 * 86400 + + user_ts_all = sorted(ts for _, _, uts in sessions_raw for ts in uts) + turns_with_epoch: list[tuple[int, dict]] = [] + for s in sessions_out: + for t in s["turns"]: + e = _parse_iso_epoch(t.get("timestamp", "")) + if e: + turns_with_epoch.append((e, t)) + + def bucket(start: int, end: int) -> dict: + b = { + "turns": 0, "user_prompts": 0, "cost": 0.0, + "input": 0, "output": 0, "cache_read": 0, "cache_write": 0, + "blocks": 0, + } + for u in user_ts_all: + if start <= u < end: + b["user_prompts"] += 1 + for e, t in turns_with_epoch: + if start <= e < end: + b["turns"] += 1 + b["input"] += t["input_tokens"] + b["output"] += t["output_tokens"] + b["cache_read"] += t["cache_read_tokens"] + b["cache_write"] += t["cache_write_tokens"] + b["cost"] += t["cost_usd"] + for blk in session_blocks: + if start <= blk["anchor_epoch"] < end: + b["blocks"] += 1 + total_in = b["input"] + b["cache_read"] + b["cache_write"] + b["cache_hit_pct"] = 100 * b["cache_read"] / max(1, total_in) + return b + + trailing = bucket(cutoff7, now_epoch) + prior = bucket(cutoff14, cutoff7) + return { + "now_epoch": now_epoch, + "trailing_7d": trailing, + "prior_7d": prior, + "has_data": (trailing["turns"] + prior["turns"]) > 0, + } + + +def _weekly_block_counts(blocks: list[dict], now_epoch: int | None = None) -> dict: + """Count blocks active (``last_epoch`` >= cutoff) in trailing windows. + + ``now_epoch`` is the upper bound for the window; defaults to current UTC. + Returns counts for the trailing 7/14/30 days plus the grand total, which + answers "am I tracking toward a weekly cap" at a glance. + """ + if now_epoch is None: + now_epoch = int(datetime.now(tz=timezone.utc).timestamp()) + + def cnt(days: int) -> int: + cutoff = now_epoch - days * 86400 + return sum(1 for b in blocks if b["last_epoch"] >= cutoff) + + return { + "trailing_7": cnt(7), + "trailing_14": cnt(14), + "trailing_30": cnt(30), + "total": len(blocks), + } + + +# --------------------------------------------------------------------------- +# Session / project discovery +# --------------------------------------------------------------------------- + +# Accept any non-empty filename-safe token, length <= 64. Claude Code's +# identifier scheme may evolve — don't hard-code UUID format. +_SESSION_RE = re.compile(r'^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$') +# Slug preserves the leading "-" Claude Code uses for cwd-derived paths. +_SLUG_RE = re.compile(r'^-?[A-Za-z0-9_-]+$') + + +def _validate_session_id(value: str) -> str: + if not _SESSION_RE.match(value or ""): + raise argparse.ArgumentTypeError( + f"invalid session id: {value!r} " + f"(expected filename-safe token, got chars outside [A-Za-z0-9._-] or length > 64)" + ) + return value + + +def _validate_slug(value: str) -> str: + if not _SLUG_RE.match(value or ""): + raise argparse.ArgumentTypeError( + f"invalid project slug: {value!r} " + f"(expected /-safe token matching {_SLUG_RE.pattern})" + ) + return value + + +def _projects_dir() -> Path: + env = os.environ.get("CLAUDE_PROJECTS_DIR") + if env: + p = Path(env).expanduser().resolve() + if not p.is_dir(): + print(f"[error] CLAUDE_PROJECTS_DIR={env!r} is not a directory", file=sys.stderr) + sys.exit(1) + return p + return Path.home() / ".claude" / "projects" + + +def _ensure_within_projects(path: Path) -> Path: + """Resolve ``path`` and assert it lives under the projects directory. + + Catches path-traversal (``..``), symlink escapes, and absolute-path + injection via the slug/session-id arguments. + """ + root = _projects_dir().resolve() + resolved = path.resolve() + try: + resolved.relative_to(root) + except ValueError: + print(f"[error] refusing to read outside {root}: {resolved}", file=sys.stderr) + sys.exit(1) + return resolved + + +def _cwd_to_slug(cwd: str | None = None) -> str: + return (cwd or os.getcwd()).replace("/", "-") + + +def _find_jsonl_files(slug: str, include_subagents: bool = False) -> list[Path]: + project_dir = _projects_dir() / slug + if not project_dir.exists(): + return [] + files = [p for p in project_dir.glob("*.jsonl") if p.is_file()] + if include_subagents: + files += list(project_dir.glob("*/subagents/*.jsonl")) + return sorted(files, key=lambda p: p.stat().st_mtime, reverse=True) + + +def _resolve_session(args) -> tuple[Path, str]: + slug: str = args.slug or _env_slug() or _cwd_to_slug() + _validate_slug(slug) + session_id: str | None = args.session or _env_session_id() + + if session_id: + candidate = _ensure_within_projects(_projects_dir() / slug / f"{session_id}.jsonl") + if candidate.exists(): + return candidate, slug + for p in _projects_dir().rglob(f"{session_id}.jsonl"): + return _ensure_within_projects(p), p.parent.name + print(f"[error] Session {session_id!r} not found", file=sys.stderr) + sys.exit(1) + + files = _find_jsonl_files(slug) + if not files: + print(f"[error] No sessions found for slug: {slug}", file=sys.stderr) + print(f" Try --slug= or set CLAUDE_PROJECT_SLUG", file=sys.stderr) + sys.exit(1) + return files[0], slug + + +def _env_slug() -> str | None: + v = os.environ.get("CLAUDE_PROJECT_SLUG") + if v is None: + return None + try: + return _validate_slug(v) + except argparse.ArgumentTypeError as exc: + print(f"[error] CLAUDE_PROJECT_SLUG: {exc}", file=sys.stderr) + sys.exit(1) + + +def _env_session_id() -> str | None: + v = os.environ.get("CLAUDE_SESSION_ID") + if v is None: + return None + try: + return _validate_session_id(v) + except argparse.ArgumentTypeError as exc: + print(f"[error] CLAUDE_SESSION_ID: {exc}", file=sys.stderr) + sys.exit(1) + + +# --------------------------------------------------------------------------- +# Data model — build structured report from raw turns +# --------------------------------------------------------------------------- + +def _build_turn_record(global_index: int, entry: dict) -> dict: + msg = entry["message"] + u = msg["usage"] + model = msg.get("model", "unknown") + inp = u.get("input_tokens", 0) + out = u.get("output_tokens", 0) + crd = u.get("cache_read_input_tokens", 0) + cwr = u.get("cache_creation_input_tokens", 0) + c = _cost(u, model) + nc = _no_cache_cost(u, model) + return { + "index": global_index, + "timestamp": entry.get("timestamp", ""), + "timestamp_fmt": _fmt_ts(entry.get("timestamp", "")), + "model": model, + "input_tokens": inp, + "output_tokens": out, + "cache_read_tokens": crd, + "cache_write_tokens": cwr, + "total_tokens": inp + out + crd + cwr, + "cost_usd": c, + "no_cache_cost_usd": nc, + "speed": u.get("speed", ""), + } + + +def _totals_from_turns(turn_records: list[dict]) -> dict: + t = {"input": 0, "output": 0, "cache_read": 0, "cache_write": 0, + "cost": 0.0, "no_cache_cost": 0.0, "turns": len(turn_records)} + for r in turn_records: + t["input"] += r["input_tokens"] + t["output"] += r["output_tokens"] + t["cache_read"] += r["cache_read_tokens"] + t["cache_write"] += r["cache_write_tokens"] + t["cost"] += r["cost_usd"] + t["no_cache_cost"] += r["no_cache_cost_usd"] + t["total"] = t["input"] + t["output"] + t["cache_read"] + t["cache_write"] + t["total_input"] = t["input"] + t["cache_read"] + t["cache_write"] + t["cache_savings"] = t["no_cache_cost"] - t["cost"] + t["cache_hit_pct"] = 100 * t["cache_read"] / max(1, t["total_input"]) + return t + + +def _model_counts(turn_records: list[dict]) -> dict[str, int]: + counts: dict[str, int] = {} + for r in turn_records: + counts[r["model"]] = counts.get(r["model"], 0) + 1 + return counts + + +def _build_report( + mode: str, + slug: str, + sessions_raw: list[tuple[str, list[dict], list[int]]], + tz_offset_hours: float = 0.0, + tz_label: str = "UTC", + peak: dict | None = None, +) -> dict: + """Build a structured report dict from raw session data. + + Args: + mode: ``"session"`` for single-session or ``"project"`` for all sessions. + slug: Project slug derived from the working directory path. + sessions_raw: List of ``(session_id, assistant_turns, user_epoch_secs)`` + triples in chronological order (oldest first). ``assistant_turns`` + are raw JSONL entries for assistant messages; ``user_epoch_secs`` + are sorted UTC epoch-seconds for non-meta user entries. + + Returns: + Report dict containing ``sessions`` (list), ``totals``, ``models``, + and ``time_of_day`` (project-wide). Each session entry also has its + own ``time_of_day`` for per-session breakdowns. + """ + sessions_out = [] + global_idx = 1 + + for session_id, raw_turns, user_ts in sessions_raw: + turn_records = [_build_turn_record(global_idx + i, t) for i, t in enumerate(raw_turns)] + global_idx += len(turn_records) + sessions_out.append({ + "session_id": session_id, + "first_ts": _fmt_ts(raw_turns[0].get("timestamp", "")) if raw_turns else "", + "last_ts": _fmt_ts(raw_turns[-1].get("timestamp", "")) if raw_turns else "", + "turns": turn_records, + "subtotal": _totals_from_turns(turn_records), + "models": _model_counts(turn_records), + "time_of_day": _build_time_of_day(user_ts, offset_hours=tz_offset_hours), + }) + + all_turns = [t for s in sessions_out for t in s["turns"]] + all_user_ts = sorted(ts for _, _, uts in sessions_raw for ts in uts) + blocks = _build_session_blocks(sessions_raw) + return { + "generated_at": datetime.now(timezone.utc).isoformat(), + "mode": mode, + "slug": slug, + "tz_offset_hours": tz_offset_hours, + "tz_label": tz_label, + "sessions": sessions_out, + "totals": _totals_from_turns(all_turns), + "models": _model_counts(all_turns), + "time_of_day": _build_time_of_day(all_user_ts, offset_hours=tz_offset_hours), + "session_blocks": blocks, + "block_summary": _weekly_block_counts(blocks), + "weekly_rollup": _build_weekly_rollup(sessions_out, sessions_raw, blocks), + "peak": peak, + } + + +# --------------------------------------------------------------------------- +# Formatting helpers (shared) +# --------------------------------------------------------------------------- + +COL = "{:<4} {:<19} {:>11} {:>7} {:>9} {:>9} {:>10} {:>9}" +HDR = COL.format("#", "Time (UTC)", "Input (new)", "Output", "CacheRd", "CacheWr", "Total", "Cost $") +SEP = "-" * len(HDR) +WIDE = "=" * len(HDR) + +# Mode (speed) column — appended when any turn in the report used fast mode +COL_M = COL + " {:<4}" +HDR_M = COL_M.format("#", "Time (UTC)", "Input (new)", "Output", "CacheRd", "CacheWr", "Total", "Cost $", "Mode") +SEP_M = "-" * len(HDR_M) +WIDE_M = "=" * len(HDR_M) + + +def _has_fast(report: dict) -> bool: + """Return True if any turn in the report used fast mode.""" + for s in report["sessions"]: + for t in s["turns"]: + if t.get("speed") == "fast": + return True + return False + + +def _fmt_ts(ts: str) -> str: + try: + dt = datetime.fromisoformat(ts.replace("Z", "+00:00")) + return dt.strftime("%Y-%m-%d %H:%M:%S") + except Exception: + return ts[:19] if len(ts) >= 19 else ts + + +def _row_text(t: dict, show_mode: bool = False) -> str: + base = COL_M if show_mode else COL + args = [ + t["index"], t["timestamp_fmt"], + f"{t['input_tokens']:>7,}", f"{t['output_tokens']:>7,}", + f"{t['cache_read_tokens']:>9,}", f"{t['cache_write_tokens']:>9,}", + f"{t['total_tokens']:>10,}", + f"${t['cost_usd']:>8.4f}", + ] + if show_mode: + spd = t.get("speed", "") + args.append("fast" if spd == "fast" else "std") + return base.format(*args) + + +def _subtotal_text(label: str, s: dict, show_mode: bool = False) -> str: + base = COL_M if show_mode else COL + args = [ + label, "", + f"{s['input']:>7,}", f"{s['output']:>7,}", + f"{s['cache_read']:>9,}", f"{s['cache_write']:>9,}", + f"{s['total']:>10,}", + f"${s['cost']:>8.4f}", + ] + if show_mode: + args.append("") + return base.format(*args) + + +def _footer_text(totals: dict, models: dict[str, int], + time_of_day: dict | None = None, + tz_label: str = "UTC", + session_blocks: list[dict] | None = None, + block_summary: dict | None = None) -> str: + """Build the text footer with cache stats, model breakdown, and time-of-day. + + Args: + totals: Aggregated token/cost totals dict. + models: ``{model_id: turn_count}`` mapping. + time_of_day: Optional ``time_of_day`` report section. When provided, + a UTC-bucketed user activity summary is appended. + """ + lines = [ + "", + f"Cache savings vs no-cache baseline : ${totals['cache_savings']:.4f}", + f"Cache hit ratio (read / total input): {totals['cache_hit_pct']:.1f}%", + ] + if models: + lines.append("") + lines.append("Models used:") + for m, cnt in sorted(models.items(), key=lambda x: -x[1]): + r = _pricing_for(m) + lines.append( + f" {m:<40} {cnt:>3} turns " + f"(${r['input']:.2f}/${r['output']:.2f}/${r['cache_read']:.2f}/${r['cache_write']:.2f} per 1M in/out/rd/wr)" + ) + if time_of_day and time_of_day.get("message_count", 0) > 0: + b = time_of_day["buckets"] + lines.append("") + lines.append(f"User prompts by time of day ({tz_label}):") + lines.append(f" Night (0\u20136): {b.get('night', 0):>5,}") + lines.append(f" Morning (6\u201312): {b.get('morning', 0):>5,}") + lines.append(f" Afternoon (12\u201318):{b.get('afternoon', 0):>5,}") + lines.append(f" Evening (18\u201324): {b.get('evening', 0):>5,}") + + hod = time_of_day.get("hour_of_day") + if hod and hod.get("total", 0) > 0: + hours = hod["hours"] + mx = max(hours) or 1 + lines.append("") + lines.append(f"Hour-of-day ({tz_label}) — each \u2588 \u2248 {mx/20:.1f} prompts:") + for h in range(24): + bar = "\u2588" * int(hours[h] / mx * 20) + lines.append(f" {h:02d}:00 {hours[h]:>4,} {bar}") + + wh = time_of_day.get("weekday_hour") + if wh and wh.get("total", 0) > 0: + row_totals = wh["row_totals"] + days = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"] + lines.append("") + lines.append(f"Weekday totals ({tz_label}):") + for i, d in enumerate(days): + lines.append(f" {d}: {row_totals[i]:>5,}") + + if session_blocks: + lines.append("") + s7 = block_summary.get("trailing_7", 0) if block_summary else 0 + s14 = block_summary.get("trailing_14", 0) if block_summary else 0 + tot = block_summary.get("total", len(session_blocks)) if block_summary else len(session_blocks) + lines.append(f"5-hour session blocks ({tot} total; " + f"{s7} in last 7d, {s14} in last 14d):") + recent = session_blocks[-8:] + for b in recent: + anchor = b["anchor_iso"][:16].replace("T", " ") + dur = b["elapsed_min"] + lines.append( + f" {anchor}Z " + f"dur={dur:>5.0f}m " + f"turns={b['turn_count']:>3} " + f"prompts={b['user_msg_count']:>3} " + f"${b['cost_usd']:>7.3f}" + ) + if len(session_blocks) > len(recent): + lines.append(f" ... ({len(session_blocks) - len(recent)} earlier blocks omitted)") + return "\n".join(lines) + + +# --------------------------------------------------------------------------- +# Renderers +# --------------------------------------------------------------------------- + +def render_text(report: dict) -> str: + out = io.StringIO() + + def p(*args, **kw): + print(*args, **kw, file=out) + + sessions = report["sessions"] + + m = _has_fast(report) + hdr, sep, wide = (HDR_M, SEP_M, WIDE_M) if m else (HDR, SEP, WIDE) + + if report["mode"] == "project": + p(f"Project: {report['slug']}") + p(f"Sessions with data: {len(sessions)}") + p() + for i, s in enumerate(sessions, 1): + p(wide) + p(f" Session {s['session_id'][:8]}… {s['first_ts']} → {s['last_ts']} ({len(s['turns'])} turns)") + p(wide) + p(hdr) + for t in s["turns"]: + p(_row_text(t, m)) + p(sep) + p(_subtotal_text(f"S{i:02}", s["subtotal"], m)) + p() + p(wide) + p(f" PROJECT TOTAL — {len(sessions)} session{'s' if len(sessions) != 1 else ''}, {report['totals']['turns']} turns") + p(wide) + p(hdr) + p(sep) + p(_subtotal_text("TOT", report["totals"], m)) + else: + s = sessions[0] + p(hdr) + for t in s["turns"]: + p(_row_text(t, m)) + p(sep) + p(_subtotal_text("TOT", s["subtotal"], m)) + + p(_footer_text(report["totals"], report["models"], report.get("time_of_day"), + tz_label=report.get("tz_label", "UTC"), + session_blocks=report.get("session_blocks"), + block_summary=report.get("block_summary"))) + return out.getvalue() + + +def _tod_for_json(tod: dict) -> dict: + """Convert a ``time_of_day`` section for JSON export. + + Replaces internal ``epoch_secs`` (integer list) with human-readable + ``utc_timestamps`` (ISO-8601 strings). The conversion is O(n) but only + runs once per export — no deep-copy of the full report is needed. + """ + return { + "utc_timestamps": [ + datetime.fromtimestamp(e, tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") + for e in tod.get("epoch_secs", []) + ], + "message_count": tod.get("message_count", 0), + "buckets": tod.get("buckets", {}), + "hour_of_day": tod.get("hour_of_day", {}), + "weekday_hour": tod.get("weekday_hour", {}), + "offset_hours": tod.get("offset_hours", 0.0), + } + + +def render_json(report: dict) -> str: + """Render the full report as indented JSON. + + Internal ``epoch_secs`` lists in ``time_of_day`` sections are converted to + ISO-8601 ``utc_timestamps`` for human readability. The transform uses a + shallow copy of the report — session turns, subtotals, and model dicts are + shared by reference to avoid copying ~thousands of turn record dicts. + """ + # Shallow-transform: only replace time_of_day sections + export = {**report} + if "time_of_day" in export: + export["time_of_day"] = _tod_for_json(export["time_of_day"]) + if "sessions" in export: + export["sessions"] = [ + {**s, "time_of_day": _tod_for_json(s["time_of_day"])} + if "time_of_day" in s else s + for s in export["sessions"] + ] + return json.dumps(export, indent=2) + + +def render_csv(report: dict) -> str: + """Render turn-level CSV with an appended time-of-day summary section. + + The first section contains one row per assistant turn (unchanged). + A blank separator row is followed by a ``USER ACTIVITY BY TIME OF DAY`` + summary with per-session and project-wide counts bucketed at UTC. + """ + out = io.StringIO() + w = csv_mod.writer(out) + w.writerow(["session_id", "turn", "timestamp", "model", "speed", + "input_tokens", "output_tokens", "cache_read_tokens", "cache_write_tokens", + "total_tokens", "cost_usd", "no_cache_cost_usd"]) + for s in report["sessions"]: + for t in s["turns"]: + w.writerow([ + s["session_id"], t["index"], t["timestamp"], t["model"], + t.get("speed", ""), + t["input_tokens"], t["output_tokens"], + t["cache_read_tokens"], t["cache_write_tokens"], + t["total_tokens"], + f"{t['cost_usd']:.6f}", f"{t['no_cache_cost_usd']:.6f}", + ]) + + # Time-of-day summary section + tz_label = report.get("tz_label", "UTC") + w.writerow([]) + w.writerow([f"# USER ACTIVITY BY TIME OF DAY ({tz_label})"]) + w.writerow(["scope", "id", "night_0_6", "morning_6_12", + "afternoon_12_18", "evening_18_24", "total"]) + for s in report["sessions"]: + tod = s.get("time_of_day", {}) + b = tod.get("buckets", {}) + w.writerow(["session", s["session_id"], + b.get("night", 0), b.get("morning", 0), + b.get("afternoon", 0), b.get("evening", 0), + tod.get("message_count", 0)]) + tod = report.get("time_of_day", {}) + b = tod.get("buckets", {}) + w.writerow(["project", report["slug"], + b.get("night", 0), b.get("morning", 0), + b.get("afternoon", 0), b.get("evening", 0), + tod.get("message_count", 0)]) + + # Hour-of-day section (project-wide) + hod = tod.get("hour_of_day") + if hod and hod.get("total", 0) > 0: + w.writerow([]) + w.writerow([f"# HOUR OF DAY ({tz_label})"]) + w.writerow(["hour"] + [f"{h:02d}" for h in range(24)] + ["total"]) + w.writerow(["prompts"] + list(hod["hours"]) + [hod["total"]]) + + # Weekday x hour matrix (project-wide) + wh = tod.get("weekday_hour") + if wh and wh.get("total", 0) > 0: + days = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"] + w.writerow([]) + w.writerow([f"# WEEKDAY x HOUR ({tz_label})"]) + w.writerow(["weekday"] + [f"{h:02d}" for h in range(24)] + ["row_total"]) + for i, d in enumerate(days): + w.writerow([d] + list(wh["matrix"][i]) + [wh["row_totals"][i]]) + w.writerow(["col_total"] + list(wh["col_totals"]) + [wh["total"]]) + + # 5-hour session blocks + blocks = report.get("session_blocks") or [] + summary = report.get("block_summary") or {} + if blocks: + w.writerow([]) + w.writerow(["# 5-HOUR SESSION BLOCKS"]) + w.writerow(["trailing_7", "trailing_14", "trailing_30", "total"]) + w.writerow([summary.get("trailing_7", 0), summary.get("trailing_14", 0), + summary.get("trailing_30", 0), summary.get("total", len(blocks))]) + w.writerow([]) + w.writerow(["anchor_utc", "last_utc", "elapsed_min", "turns", + "user_prompts", "input", "output", "cache_read", + "cache_write", "cost_usd", "sessions_touched"]) + for b in blocks: + w.writerow([ + b["anchor_iso"], b["last_iso"], f"{b['elapsed_min']:.1f}", + b["turn_count"], b["user_msg_count"], + b["input"], b["output"], b["cache_read"], b["cache_write"], + f"{b['cost_usd']:.6f}", len(b["sessions_touched"]), + ]) + return out.getvalue() + + +def render_md(report: dict) -> str: + """Render the full report as GitHub-flavored Markdown. + + Includes summary cards, user activity by time of day (UTC), model pricing + table, and per-session turn-level tables with subtotals. + """ + out = io.StringIO() + + def p(*args, **kw): + print(*args, **kw, file=out) + + slug = report["slug"] + totals = report["totals"] + mode = report["mode"] + generated = report["generated_at"][:19].replace("T", " ") + " UTC" + + p(f"# Session Metrics — {slug}") + p() + p(f"Generated: {generated} | Mode: {mode}") + p() + + # Summary cards + p("## Summary") + p() + p(f"| Metric | Value |") + p(f"|--------|-------|") + p(f"| Sessions | {len(report['sessions'])} |") + p(f"| Total turns | {totals['turns']:,} |") + p(f"| Total cost | ${totals['cost']:.4f} |") + p(f"| Cache savings | ${totals['cache_savings']:.4f} |") + p(f"| Cache hit ratio | {totals['cache_hit_pct']:.1f}% |") + p(f"| Total input tokens | {totals['total_input']:,} |") + p(f"| Input tokens (new) | {totals['input']:,} |") + p(f"| Output tokens | {totals['output']:,} |") + p(f"| Cache read tokens | {totals['cache_read']:,} |") + p(f"| Cache write tokens | {totals['cache_write']:,} |") + p() + + # Time-of-day section + tod = report.get("time_of_day", {}) + tz_label = report.get("tz_label", "UTC") + if tod.get("message_count", 0) > 0: + b = tod["buckets"] + p(f"## User Activity by Time of Day ({tz_label})") + p() + p("| Period | Hours | Messages |") + p("|--------|------:|---------:|") + p(f"| Night | 0\u20136 | {b.get('night', 0):,} |") + p(f"| Morning | 6\u201312 | {b.get('morning', 0):,} |") + p(f"| Afternoon | 12\u201318 | {b.get('afternoon', 0):,} |") + p(f"| Evening | 18\u201324 | {b.get('evening', 0):,} |") + p(f"| **Total** | | **{tod['message_count']:,}** |") + p() + + hod = tod.get("hour_of_day") + if hod and hod.get("total", 0) > 0: + hours = hod["hours"] + p(f"### Hour of day ({tz_label})") + p() + p("| Hour | Prompts |") + p("|-----:|--------:|") + for h in range(24): + p(f"| {h:02d}:00 | {hours[h]:,} |") + p() + + wh = tod.get("weekday_hour") + if wh and wh.get("total", 0) > 0: + days = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"] + p(f"### Weekday x hour ({tz_label})") + p() + header = "| Day | " + " | ".join(f"{h:02d}" for h in range(24)) + " | Total |" + sep = "|-----|" + "|".join(["---:"] * 24) + "|------:|" + p(header) + p(sep) + for i, d in enumerate(days): + row = wh["matrix"][i] + cells = " | ".join(str(c) if c else "" for c in row) + p(f"| {d} | {cells} | **{wh['row_totals'][i]:,}** |") + p() + + blocks = report.get("session_blocks", []) + summary = report.get("block_summary", {}) + if blocks: + p(f"## 5-hour session blocks ({tz_label})") + p() + p(f"- Trailing 7 days: **{summary.get('trailing_7', 0)}** blocks") + p(f"- Trailing 14 days: **{summary.get('trailing_14', 0)}** blocks") + p(f"- Trailing 30 days: **{summary.get('trailing_30', 0)}** blocks") + p(f"- All time: **{summary.get('total', len(blocks))}** blocks") + p() + p("| Anchor (UTC) | Duration | Turns | Prompts | Cost | Sessions |") + p("|-------------|---------:|------:|--------:|-----:|---------:|") + for b in reversed(blocks[-12:]): + p(f"| {b['anchor_iso']} | {b['elapsed_min']:.0f}m " + f"| {b['turn_count']:,} | {b['user_msg_count']:,} " + f"| ${b['cost_usd']:.3f} | {len(b['sessions_touched'])} |") + p() + + if report["models"]: + p("## Models") + p() + p("| Model | Turns | $/M in | $/M out | $/M rd | $/M wr |") + p("|-------|------:|------:|------:|------:|------:|") + for m, cnt in sorted(report["models"].items(), key=lambda x: -x[1]): + r = _pricing_for(m) + p(f"| `{m}` | {cnt:,} | ${r['input']:.2f} | ${r['output']:.2f} | ${r['cache_read']:.2f} | ${r['cache_write']:.2f} |") + p() + + for i, s in enumerate(report["sessions"], 1): + if mode == "project": + st = s["subtotal"] + p(f"## Session {i}: `{s['session_id'][:8]}…`") + p() + p(f"{s['first_ts']} → {s['last_ts']}  ·  {len(s['turns'])} turns  ·  **${st['cost']:.4f}**") + p() + + p("| # | Time (UTC) | Input (new) | Output | CacheRd | CacheWr | Total | Cost $ |") + p("|--:|-----------|------------:|------:|--------:|--------:|------:|-------:|") + for t in s["turns"]: + p(f"| {t['index']} | {t['timestamp_fmt']} " + f"| {t['input_tokens']:,} | {t['output_tokens']:,} " + f"| {t['cache_read_tokens']:,} | {t['cache_write_tokens']:,} " + f"| {t['total_tokens']:,} | ${t['cost_usd']:.4f} |") + st = s["subtotal"] + p(f"| **TOT** | | **{st['input']:,}** | **{st['output']:,}** " + f"| **{st['cache_read']:,}** | **{st['cache_write']:,}** " + f"| **{st['total']:,}** | **${st['cost']:.4f}** |") + p() + + return out.getvalue() + + +def _session_duration_stats(session: dict) -> dict | None: + """Per-session wall-clock + burn rate derived from turn timestamps. + + Returns None when fewer than 2 turns have usable timestamps. Burn rate + metrics are clamped so a single-turn session doesn't divide by zero. + """ + turns = session.get("turns", []) + epochs = [_parse_iso_epoch(t.get("timestamp", "")) for t in turns] + epochs = [e for e in epochs if e] + if len(epochs) < 2: + return None + first, last = min(epochs), max(epochs) + wall_sec = last - first + wall_min = wall_sec / 60.0 + st = session["subtotal"] + minutes = max(1e-6, wall_min) + return { + "first_epoch": first, + "last_epoch": last, + "wall_sec": wall_sec, + "wall_min": wall_min, + "tokens_per_min": st["total"] / minutes, + "cost_per_min": st["cost"] / minutes, + "turns": st["turns"], + } + + +def _fmt_duration(sec: int) -> str: + """Format ``sec`` as a compact duration (``1h23m``, ``45m12s``, ``7s``).""" + if sec < 60: + return f"{sec}s" + if sec < 3600: + return f"{sec // 60}m{sec % 60:02d}s" + hours, rem = divmod(sec, 3600) + return f"{hours}h{rem // 60:02d}m" + + +def _build_session_duration_html(sessions: list[dict], tz_label: str, + tz_offset_hours: float) -> str: + """Build a per-session duration + burn-rate card. + + Shows the most-recent 10 sessions (newest first) with wall-clock time, + turn count, total cost, tokens/min, and cost/min. Answers "how much + am I spending per active minute" for a given session. + """ + rows_data = [] + for s in sessions: + stats = _session_duration_stats(s) + if not stats: + continue + rows_data.append((s, stats)) + if not rows_data: + return "" + offset_sec = int(tz_offset_hours * 3600) + + def fmt_local(epoch: int) -> str: + return datetime.fromtimestamp( + epoch + offset_sec, tz=timezone.utc, + ).strftime("%Y-%m-%d %H:%M") + + rows_data.sort(key=lambda x: x[1]["last_epoch"], reverse=True) + rows_data = rows_data[:10] + rows_html = [] + for s, st in rows_data: + sid = s["session_id"][:8] + rows_html.append( + f'{sid}\u2026' + f'{fmt_local(st["first_epoch"])}' + f'{_fmt_duration(st["wall_sec"])}' + f'{st["turns"]:,}' + f'${s["subtotal"]["cost"]:.3f}' + f'{st["tokens_per_min"]:,.0f}' + f'${st["cost_per_min"]:.3f}' + ) + return f"""\ +
+
Session duration \u2014 newest first
+ + + + + + + + + + + + + {"".join(rows_html)} +
SessionFirst turn ({tz_label})WallTurnsCosttok/min$/min
+
""" + + +def _fmt_delta_pct(cur: float, prev: float) -> tuple[str, str]: + """Format the relative delta of ``cur`` vs ``prev`` as ``("+12.3%", color)``. + + When ``prev`` is zero, returns ``("new", "#8b949e")`` — don't render + infinite percentages. Positive deltas are red for cost/turns (caller + picks the color-flip); this helper just returns a magenta/green by sign. + """ + if prev <= 0: + return ("new" if cur > 0 else "\u2013", "#8b949e") + delta = (cur - prev) / prev * 100.0 + sign = "+" if delta > 0 else "" + color = "#f47067" if delta > 0 else "#58a6ff" if delta < 0 else "#8b949e" + return (f"{sign}{delta:.1f}%", color) + + +def _build_weekly_rollup_html(rollup: dict) -> str: + """Render a trailing-7d vs prior-7d comparison card. + + Returns empty string when there's no data (skips the section cleanly + on brand-new projects). + """ + if not rollup or not rollup.get("has_data"): + return "" + cur = rollup["trailing_7d"] + prev = rollup["prior_7d"] + + rows = [] + metrics = [ + ("Cost (USD)", f"${cur['cost']:.2f}", f"${prev['cost']:.2f}", cur["cost"], prev["cost"]), + ("Assistant turns", f"{cur['turns']:,}", f"{prev['turns']:,}", cur["turns"], prev["turns"]), + ("User prompts", f"{cur['user_prompts']:,}", f"{prev['user_prompts']:,}", cur["user_prompts"], prev["user_prompts"]), + ("5h blocks", f"{cur['blocks']:,}", f"{prev['blocks']:,}", cur["blocks"], prev["blocks"]), + ("Cache hit ratio", f"{cur['cache_hit_pct']:.1f}%", f"{prev['cache_hit_pct']:.1f}%", cur["cache_hit_pct"], prev["cache_hit_pct"]), + ] + for label, cur_s, prev_s, cur_v, prev_v in metrics: + delta, color = _fmt_delta_pct(cur_v, prev_v) + rows.append( + f'{label}' + f'{cur_s}' + f'{prev_s}' + f'{delta}' + ) + + return f"""\ +
+
Weekly roll-up
+ + + + + + + + + + {"".join(rows)} +
MetricLast 7dPrior 7d\u0394
+
""" + + +def _build_session_blocks_html( + blocks: list[dict], summary: dict, tz_label: str = "UTC", + tz_offset_hours: float = 0.0, +) -> str: + """Render 5-hour session blocks as a summary card + recent-blocks list. + + Includes a weekly-count card (trailing 7/14/30d) as the primary + rate-limit-debugging signal, then the newest 12 blocks with duration, + turn count, prompt count, cost, and session-count. + """ + if not blocks: + return "" + offset_sec = int(tz_offset_hours * 3600) + + def fmt_local(epoch: int) -> str: + return datetime.fromtimestamp( + epoch + offset_sec, tz=timezone.utc, + ).strftime("%Y-%m-%d %H:%M") + + s7 = summary.get("trailing_7", 0) + s14 = summary.get("trailing_14", 0) + s30 = summary.get("trailing_30", 0) + tot = summary.get("total", len(blocks)) + recent = list(reversed(blocks[-12:])) + rows = "".join( + f'{fmt_local(b["anchor_epoch"])}' + f'{b["elapsed_min"]:.0f}m' + f'{b["turn_count"]:,}' + f'{b["user_msg_count"]:,}' + f'${b["cost_usd"]:.3f}' + f'{len(b["sessions_touched"])}' + for b in recent + ) + + def card(label: str, value: str, hint: str = "") -> str: + hint_html = (f'' + f'{hint}') if hint else "" + return ( + f'
' + f'
{label}
' + f'
{value}{hint_html}
' + ) + + return f"""\ +
+
5-hour session blocks
+
+ {card("Last 7 days", f"{s7}")} + {card("Last 14 days", f"{s14}")} + {card("Last 30 days", f"{s30}")} + {card("All time", f"{tot}")} +
+
+ Recent blocks ({tz_label}) \u2014 a new block starts 5h after the previous anchor. +
+ + + + + + + + + + + + {rows} +
AnchorDurationTurnsPromptsCostSessions
+
""" + + +def _build_hour_of_day_html(tod: dict, tz_label: str = "UTC", + default_offset_hours: float = 0.0, + peak: dict | None = None) -> str: + """Build a 24-hour bar chart of user prompts, self-contained HTML + CSS + JS. + + Client-side JS rebuckets to any offset chosen from the tz dropdown. When + ``peak`` is supplied (see ``_build_peak``), overlays a translucent band + behind the bars in the peak-hours range, and reshifts the band when the + user changes display tz. + """ + epoch_secs = tod.get("epoch_secs", []) + if not epoch_secs: + return "" + ts_json = json.dumps(epoch_secs, separators=(",", ":")) + tz_options = _tz_dropdown_options(default_offset_hours, tz_label) + + peak_json = "null" + peak_legend = "" + if peak: + peak_json = json.dumps({ + "start": peak["start"], + "end": peak["end"], + "tz_off": peak["tz_offset_hours"], + "tz_label": peak["tz_label"], + }, separators=(",", ":")) + peak_legend = ( + f'' + f'' + f'Peak ({peak["start"]:02d}\u2013{peak["end"]:02d} {peak["tz_label"]}, {peak["note"]})' + f'' + ) + + return f"""\ +
+
+ Hour of day + + Peak: + - + {peak_legend} +
+
+ + +
+
+
+ {"".join(f'
{h:02d}
' for h in range(24))} +
+
+""" + + +def _build_punchcard_html(tod: dict, tz_label: str = "UTC", + default_offset_hours: float = 0.0) -> str: + """Build a 7x24 weekday-by-hour punchcard, GitHub-style dots. + + Rows: Mon..Sun. Columns: 00..23 in the selected tz. Dot radius scales + with the cell count; empty cells render as faint dots. + """ + epoch_secs = tod.get("epoch_secs", []) + if not epoch_secs: + return "" + ts_json = json.dumps(epoch_secs, separators=(",", ":")) + tz_options = _tz_dropdown_options(default_offset_hours, tz_label) + days = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"] + cells = [] + for r in range(7): + row = [] + row.append(f'
{days[r]}
') + for h in range(24): + row.append(f'
' + f'
') + cells.append('
' + "".join(row) + "
") + hour_header = ('
' + '
' + + "".join(f'
{h:02d}
' for h in range(24)) + + '
') + return f"""\ +
+
+ Weekday \u00d7 hour + + Busiest: + - +
+ {hour_header} + {"".join(cells)} +
+""" + + +def _tz_dropdown_options(default_offset_hours: float, tz_label: str) -> str: + """Build the ' + for off, lbl, sel in items + ) + + +def _build_tod_heatmap_html(tod: dict) -> str: + """Build the Time-of-Day heatmap as self-contained HTML + CSS + JS. + + Renders a horizontal bar chart with four period rows (Night, Morning, + Afternoon, Evening), a timezone dropdown with PT (UTC-8) and Brisbane + (UTC+10), and client-side re-bucketing via JavaScript. + + No Highcharts dependency — uses pure HTML/CSS bars with JS-driven width + updates. The epoch-seconds array is embedded as a compact integer list; + bucketing uses ``(((epoch + off) % 86400) + 86400) % 86400`` (the + standard double-modulo idiom) to guarantee non-negative results even + when JS's sign-preserving ``%`` encounters negative operands. + + Args: + tod: Report's ``time_of_day`` dict containing ``epoch_secs`` and + ``buckets``. + + Returns: + HTML string for embedding in the full report page. Returns an empty + string if no user timestamps are available. + """ + epoch_secs = tod.get("epoch_secs", []) + if not epoch_secs: + return "" + ts_json = json.dumps(epoch_secs, separators=(",", ":")) + + return f"""\ +
+
+ User Messages by Time of Day + + Total: + 0 +
+
+
+ Morning (6\u201312) +
+
+
+ 0 +
+
+ Afternoon (12\u201318) +
+
+
+ 0 +
+
+ Evening (18\u201324) +
+
+
+ 0 +
+
+ Night (0\u20136) +
+
+
+ 0 +
+
+
+""" + + +_CHART_PAGE = 60 # max data points per chart panel before splitting into multiple + + +def _build_chart_html( + cats: list, cache_rd: list, cache_wr: list, + output: list, input_: list, cost: list, x_title: str, + models: list[str] | None = None, +) -> str: + """Return the full chart section HTML: containers + controls + JS. + + If len(cats) > _CHART_PAGE the data is split across multiple charts — one + per page — each labelled 'Turns 1–60', 'Turns 61–120', etc. A single set + of 3D-rotation sliders drives all charts simultaneously. + + Optimisations: + - Chart data is emitted once as a single JSON blob; a shared renderPage() + function creates each Highcharts instance from that blob. + - IntersectionObserver lazily renders charts only when scrolled into view. + - Slider controls sync all rendered charts. + + models: optional per-bar model name list (same length as cats). When + provided, the tooltip header shows the model alongside the x-axis label. + """ + n = len(cats) + slices = [(s, min(s + _CHART_PAGE, n)) for s in range(0, n, _CHART_PAGE)] + n_pages = len(slices) + models_py = models or [] + + # --- Build single DATA blob with all page slices ----------------------- + pages_data: list[dict] = [] + for s, e in slices: + pages_data.append({ + "cats": cats[s:e], + "crd": cache_rd[s:e], + "cwr": cache_wr[s:e], + "out": output[s:e], + "inp": input_[s:e], + "cost": cost[s:e], + "models": models_py[s:e] if models_py else [], + }) + data_json = json.dumps(pages_data, separators=(",", ":")) + + # --- Container divs --------------------------------------------------- + divs: list[str] = [] + for pg, (s, e) in enumerate(slices): + label = ( + f'
{x_title}s {s + 1}\u2013{e} of {n}
' + if n_pages > 1 else "" + ) + divs.append(f'{label}
') + + containers_html = "\n".join(divs) + + # --- Single JS block: data + renderPage + lazy observer + sliders ----- + script = f"""\ +(function () {{ + var charts = []; + var DATA = {data_json}; + var X_TITLE = '{x_title}'; + + function renderPage(pg) {{ + var d = DATA[pg]; + var c = Highcharts.chart('hc-chart-' + pg, {{ + chart: {{ + type: 'column', backgroundColor: '#161b22', plotBorderColor: '#30363d', + options3d: {{ + enabled: true, alpha: 12, beta: 10, depth: 50, viewDistance: 25, + frame: {{ + back: {{ color: '#21262d', size: 1 }}, + bottom: {{ color: '#21262d', size: 1 }}, + side: {{ color: '#21262d', size: 1 }} + }} + }} + }}, + title: {{ text: null }}, + xAxis: {{ + categories: d.cats, + title: {{ text: X_TITLE, style: {{ color: '#8b949e' }} }}, + labels: {{ style: {{ color: '#8b949e', fontSize: '10px' }}, rotation: -45 }}, + lineColor: '#30363d', tickColor: '#30363d' + }}, + yAxis: [ + {{ + title: {{ text: 'Tokens', style: {{ color: '#8b949e' }} }}, + labels: {{ style: {{ color: '#8b949e', fontSize: '10px' }}, + formatter: function () {{ + return this.value >= 1000 ? (this.value / 1000).toFixed(0) + 'k' : this.value; + }} }}, + gridLineColor: '#21262d', stackLabels: {{ enabled: false }} + }}, + {{ + title: {{ text: 'Cost (USD)', style: {{ color: '#d29922' }} }}, + labels: {{ style: {{ color: '#d29922', fontSize: '10px' }}, + formatter: function () {{ return '$' + this.value.toFixed(4); }} }}, + opposite: true, gridLineWidth: 0 + }} + ], + legend: {{ + enabled: true, margin: 20, padding: 12, + itemStyle: {{ color: '#8b949e', fontSize: '11px', fontWeight: 'normal' }}, + itemHoverStyle: {{ color: '#e6edf3' }} + }}, + tooltip: {{ + backgroundColor: '#1c2128', borderColor: '#30363d', + style: {{ color: '#e6edf3', fontSize: '11px' }}, + shared: true, + formatter: function () {{ + var s = '' + this.x + ''; + if (d.models.length && d.models[this.points[0].point.index]) {{ + s += '  ' + + d.models[this.points[0].point.index] + ''; + }} + s += '
'; + this.points.forEach(function (p) {{ + var val = p.series.options.yAxis === 1 + ? '$' + p.y.toFixed(4) + : p.y.toLocaleString() + ' tokens'; + s += '\u25cf ' + + p.series.name + ': ' + val + '
'; + }}); + return s; + }} + }}, + plotOptions: {{ + column: {{ stacking: 'normal', depth: 30, borderWidth: 0, groupPadding: 0.1 }}, + line: {{ depth: 0, zIndex: 10, marker: {{ enabled: true, radius: 3 }} }} + }}, + series: [ + {{ name: 'Cache Read', data: d.crd, color: '#d29922', yAxis: 0 }}, + {{ name: 'Cache Write', data: d.cwr, color: '#9e6a03', yAxis: 0 }}, + {{ name: 'Output', data: d.out, color: '#3fb950', yAxis: 0 }}, + {{ name: 'Input (new)', data: d.inp, color: '#1f6feb', yAxis: 0 }}, + {{ name: 'Cost $', type: 'line', data: d.cost, + color: '#f78166', yAxis: 1, lineWidth: 2, zIndex: 10 }} + ], + credits: {{ enabled: false }}, + exporting: {{ buttons: {{ contextButton: {{ + symbolStroke: '#8b949e', theme: {{ fill: '#161b22' }} + }} }} }} + }}); + charts.push(c); + }} + + /* Render first page immediately, lazy-render the rest on scroll */ + renderPage(0); + var lazy = document.querySelectorAll('.hc-lazy'); + if ('IntersectionObserver' in window && lazy.length > 1) {{ + var obs = new IntersectionObserver(function (entries) {{ + entries.forEach(function (e) {{ + if (e.isIntersecting) {{ + var pg = +e.target.getAttribute('data-pg'); + if (pg > 0) renderPage(pg); + obs.unobserve(e.target); + }} + }}); + }}, {{ rootMargin: '200px' }}); + for (var i = 1; i < lazy.length; i++) obs.observe(lazy[i]); + }} else {{ + for (var i = 1; i < DATA.length; i++) renderPage(i); + }} + + function bindSlider(id, valId, opt) {{ + var el = document.getElementById(id); + var vEl = document.getElementById(valId); + el.addEventListener('input', function () {{ + vEl.textContent = el.value + (opt === 'depth' ? '' : '\u00b0'); + charts.forEach(function (c) {{ + var o = c.options.chart.options3d; + o[opt] = +el.value; + c.update({{ chart: {{ options3d: o }} }}, true, false, false); + }}); + }}); + }} + bindSlider('alpha', 'alpha-val', 'alpha'); + bindSlider('beta', 'beta-val', 'beta'); + bindSlider('depth', 'depth-val', 'depth'); +}})();""" + + return f"""\ +
+
+ + + +
+ {containers_html} +
+""" + + +# --------------------------------------------------------------------------- +# Chart library dispatch (vendored, offline, SHA-256 verified) +# --------------------------------------------------------------------------- +# +# The HTML export supports pluggable chart renderers. Each renderer reads +# its JS payload from ``scripts/vendor/charts//...`` — no CDN fetch, +# no runtime cache writes, no network access. ``manifest.json`` lists the +# expected SHA-256 per file; the verifier refuses to inline a file whose +# digest doesn't match (defense-in-depth against accidental edits or +# supply-chain tampering). +# +# Current renderers: +# - "highcharts" — 3D stacked columns (non-commercial license; see LICENSE.txt). +# - "uplot" — flat 2D stacked bars + cost line (MIT). Lightest. +# - "chartjs" — 2D stacked bar + line combo (MIT). Familiar API. +# - "none" — emit the detail page with no chart at all. + +_VENDOR_CHARTS_DIR = Path(__file__).parent / "vendor" / "charts" + + +def _load_chart_manifest() -> dict: + """Parse ``vendor/charts/manifest.json``. Returns an empty libraries dict + if the manifest is missing (keeps the tool usable in degraded mode).""" + mpath = _VENDOR_CHARTS_DIR / "manifest.json" + if not mpath.exists(): + return {"libraries": {}} + try: + return json.loads(mpath.read_text(encoding="utf-8")) + except json.JSONDecodeError as exc: + print(f"[warn] vendor/charts/manifest.json malformed: {exc}", file=sys.stderr) + return {"libraries": {}} + + +def _read_vendor_files(library: str, suffix: str) -> str: + """Read + concatenate vendor files for ``library`` whose path ends in + ``suffix`` (``.js`` or ``.css``). Verifies each SHA-256 against the + manifest before inclusion; skips files that fail verification with a + stderr warning. + """ + manifest = _load_chart_manifest() + lib_entry = manifest.get("libraries", {}).get(library) + if not lib_entry: + print(f"[warn] chart library '{library}' not in vendor manifest; " + f"HTML will render without this chart.", file=sys.stderr) + return "" + parts: list[str] = [] + for f in lib_entry.get("files", []): + if not f["path"].endswith(suffix): + continue + path = _VENDOR_CHARTS_DIR / f["path"] + if not path.exists(): + print(f"[warn] vendor file missing: {path}", file=sys.stderr) + continue + data = path.read_bytes() + actual = hashlib.sha256(data).hexdigest() + expected = f.get("sha256", "") + if expected and actual != expected: + print(f"[warn] SHA-256 mismatch for {path.name}: " + f"expected {expected[:12]}…, got {actual[:12]}… (skipped)", + file=sys.stderr) + continue + parts.append(data.decode("utf-8", errors="replace")) + sep = ";\n" if suffix == ".js" else "\n" + return sep.join(parts) + + +def _read_vendor_js(library: str) -> str: + """Read + concatenate the JS payload for ``library`` from the vendor tree. + Thin wrapper over ``_read_vendor_files`` for backward compatibility.""" + return _read_vendor_files(library, ".js") + + +def _read_vendor_css(library: str) -> str: + """Read + concatenate the CSS payload for ``library`` from the vendor tree. + Returns empty string if the library has no CSS files.""" + return _read_vendor_files(library, ".css") + + +def _hc_scripts() -> str: + """Return Highcharts JS inlined as a single script block. + + Reads the vendored files from ``scripts/vendor/charts/highcharts/v12/`` + and verifies each SHA-256 against the manifest. No CDN, no network. + """ + return _read_vendor_js("highcharts") + + +def _extract_chart_series(all_turns: list[dict]) -> dict: + """Pull the per-turn series the chart renderers all need. + + Returned keys mirror the JSON blob the body-side IIFE consumes: + ``cats`` (x-axis labels), ``crd`` / ``cwr`` / ``out`` / ``inp`` (token + series, stacked bottom-to-top), ``cost`` (USD per turn), ``models`` + (per-bar model name for tooltip headers). + """ + return { + "cats": [t["timestamp_fmt"][5:16] for t in all_turns], + "inp": [t["input_tokens"] for t in all_turns], + "out": [t["output_tokens"] for t in all_turns], + "crd": [t["cache_read_tokens"] for t in all_turns], + "cwr": [t["cache_write_tokens"] for t in all_turns], + "cost": [round(t["cost_usd"], 4) for t in all_turns], + "models": [t["model"] for t in all_turns], + } + + +def _render_chart_highcharts(all_turns: list[dict]) -> tuple[str, str]: + """Highcharts renderer. Returns ``(chart_body_html, head_html)``. + + ``chart_body_html`` is the full ``
…
`` block + dropped in the report body; ``head_html`` is the vendored library bundle + wrapped in a ready-to-inline ``") + + +def _build_lib_chart_pages(series: dict, x_title: str) -> tuple[str, str]: + """Pagination scaffold shared by uPlot and Chart.js renderers. + + Returns ``(containers_html, data_json)``. The renderer wraps these with + its own per-page render function + IntersectionObserver IIFE. + Highcharts has its own (richer) builder; this is the lean version. + """ + n = len(series["cats"]) + slices = [(s, min(s + _CHART_PAGE, n)) for s in range(0, n, _CHART_PAGE)] + n_pages = len(slices) + pages_data = [{ + "cats": series["cats"][s:e], + "crd": series["crd"][s:e], + "cwr": series["cwr"][s:e], + "out": series["out"][s:e], + "inp": series["inp"][s:e], + "cost": series["cost"][s:e], + "models": series["models"][s:e], + } for s, e in slices] + data_json = json.dumps(pages_data, separators=(",", ":")) + + divs: list[str] = [] + for pg, (s, e) in enumerate(slices): + label = ( + f'
{x_title}s {s + 1}\u2013{e} of {n}
' + if n_pages > 1 else "" + ) + divs.append(f'{label}
') + return ("\n".join(divs), data_json) + + +def _render_chart_uplot(all_turns: list[dict]) -> tuple[str, str]: + """uPlot renderer (MIT). Returns ``(body_html, head_html)``. + + uPlot has no built-in stacked-bars API — we pre-compute cumulative + arrays caller-side so each bar series renders as a full stack from the + baseline (the bottom-most series is drawn last so it sits on top + visually). Cost is a separate line series on a right-hand y-axis. + Pagination + lazy rendering match the Highcharts renderer. + """ + if not all_turns: + return ("", "") + series = _extract_chart_series(all_turns) + containers_html, data_json = _build_lib_chart_pages(series, "Turn") + + css = _read_vendor_css("uplot") + js = _read_vendor_js("uplot") + if not js: + return ("", "") + + head_extra_css = """ + .uplot { width: 100% !important; } + .uplot, .uplot * { color: #8b949e; } + .u-title { display: none; } + .u-legend { background: #161b22; color: #e6edf3; font-size: 11px; + border-top: 1px solid #30363d; padding: 6px 8px; } + .u-legend .u-marker { border-radius: 2px; } + .u-axis { color: #8b949e; } + .u-cursor-pt { border-color: #58a6ff !important; } + """ + + init = f"""\ +(function () {{ + var DATA = {data_json}; + var charts = []; + function renderPage(pg) {{ + var d = DATA[pg]; + var n = d.cats.length; + var xs = new Array(n); + for (var i = 0; i < n; i++) xs[i] = i; + /* Cumulative stacks bottom-to-top: cache_read | + cache_write | + + output | + input. Drawing the totals as bars renders them as a + visual stack because the smaller bars overpaint the bigger ones. */ + var s1 = d.crd.slice(); + var s2 = new Array(n), s3 = new Array(n), s4 = new Array(n); + for (var i = 0; i < n; i++) {{ + s2[i] = s1[i] + d.cwr[i]; + s3[i] = s2[i] + d.out[i]; + s4[i] = s3[i] + d.inp[i]; + }} + var bars = uPlot.paths.bars({{ size: [0.7, 60] }}); + var el = document.getElementById('chart-pg-' + pg); + var w = el.clientWidth || 800; + var fmtTokens = function (v) {{ + if (v == null) return ''; + return v >= 1000 ? (v / 1000).toFixed(0) + 'k' : ('' + v); + }}; + var opts = {{ + width: w, height: 380, + title: '', + cursor: {{ drag: {{ x: false, y: false }}, points: {{ size: 6 }} }}, + legend: {{ live: true }}, + scales: {{ x: {{ time: false }}, cost: {{ auto: true }} }}, + axes: [ + {{ stroke: '#8b949e', grid: {{ stroke: '#21262d' }}, + values: function (u, ticks) {{ return ticks.map(function (t) {{ + return d.cats[t] || ''; + }}); }}, + rotate: -45, size: 60 }}, + {{ stroke: '#8b949e', grid: {{ stroke: '#21262d' }}, + values: function (u, ticks) {{ return ticks.map(fmtTokens); }} }}, + {{ scale: 'cost', side: 1, stroke: '#d29922', grid: {{ show: false }}, + values: function (u, ticks) {{ + return ticks.map(function (v) {{ return '$' + v.toFixed(4); }}); + }} }}, + ], + series: [ + {{ label: 'Turn' }}, + {{ label: 'Input (new)', stroke: '#1f6feb', + fill: 'rgba(31,111,235,0.85)', paths: bars, points: {{ show: false }}, + value: function (u, v, sIdx, dIdx) {{ + return d.inp[dIdx] != null ? d.inp[dIdx].toLocaleString() : ''; + }} }}, + {{ label: 'Output', stroke: '#3fb950', + fill: 'rgba(63,185,80,0.85)', paths: bars, points: {{ show: false }}, + value: function (u, v, sIdx, dIdx) {{ + return d.out[dIdx] != null ? d.out[dIdx].toLocaleString() : ''; + }} }}, + {{ label: 'Cache Write', stroke: '#9e6a03', + fill: 'rgba(158,106,3,0.85)', paths: bars, points: {{ show: false }}, + value: function (u, v, sIdx, dIdx) {{ + return d.cwr[dIdx] != null ? d.cwr[dIdx].toLocaleString() : ''; + }} }}, + {{ label: 'Cache Read', stroke: '#d29922', + fill: 'rgba(210,153,34,0.85)', paths: bars, points: {{ show: false }}, + value: function (u, v, sIdx, dIdx) {{ + return d.crd[dIdx] != null ? d.crd[dIdx].toLocaleString() : ''; + }} }}, + {{ label: 'Cost $', stroke: '#f78166', width: 2, scale: 'cost', + points: {{ show: true, size: 4, stroke: '#f78166', fill: '#161b22' }}, + value: function (u, v) {{ return v == null ? '' : '$' + v.toFixed(4); }} }}, + ], + }}; + /* uPlot wants series rows in the order declared; the bar series are + drawn back-to-front so the smallest cumulative goes last → visible. */ + var data = [xs, s4, s3, s2, s1, d.cost]; + var u = new uPlot(opts, data, el); + charts.push(u); + }} + renderPage(0); + var lazy = document.querySelectorAll('.chart-lazy'); + if ('IntersectionObserver' in window && lazy.length > 1) {{ + var obs = new IntersectionObserver(function (entries) {{ + entries.forEach(function (e) {{ + if (e.isIntersecting) {{ + var pg = +e.target.getAttribute('data-pg'); + if (pg > 0) renderPage(pg); + obs.unobserve(e.target); + }} + }}); + }}, {{ rootMargin: '200px' }}); + for (var i = 1; i < lazy.length; i++) obs.observe(lazy[i]); + }} else {{ + for (var i = 1; i < DATA.length; i++) renderPage(i); + }} + window.addEventListener('resize', function () {{ + charts.forEach(function (u) {{ + var el = u.root.parentNode; + u.setSize({{ width: el.clientWidth || 800, height: 380 }}); + }}); + }}); +}})();""" + + body = f"""
+{containers_html} +
+""" + + head_html = ( + f"\n" + f"" + ) + return (body, head_html) + + +def _render_chart_chartjs(all_turns: list[dict]) -> tuple[str, str]: + """Chart.js v4 renderer (MIT). Returns ``(body_html, head_html)``. + + Mixed bar+line: four ``type: 'bar'`` datasets share ``stack: 'tokens'`` + on the left y-axis (``stacked: true``), one ``type: 'line'`` dataset + rides on the right y-axis ``y1`` for cost. Pagination + lazy + rendering match the Highcharts renderer. + """ + if not all_turns: + return ("", "") + series = _extract_chart_series(all_turns) + containers_html, data_json = _build_lib_chart_pages(series, "Turn") + + js = _read_vendor_js("chartjs") + if not js: + return ("", "") + + init = f"""\ +(function () {{ + var DATA = {data_json}; + Chart.defaults.color = '#8b949e'; + Chart.defaults.borderColor = '#30363d'; + Chart.defaults.font.size = 11; + function renderPage(pg) {{ + var d = DATA[pg]; + var holder = document.getElementById('chart-pg-' + pg); + holder.innerHTML = ''; + var canvas = document.createElement('canvas'); + holder.appendChild(canvas); + var ctx = canvas.getContext('2d'); + new Chart(ctx, {{ + type: 'bar', + data: {{ + labels: d.cats, + datasets: [ + {{ label: 'Cache Read', data: d.crd, backgroundColor: '#d29922', + stack: 'tokens', yAxisID: 'y', order: 4 }}, + {{ label: 'Cache Write', data: d.cwr, backgroundColor: '#9e6a03', + stack: 'tokens', yAxisID: 'y', order: 3 }}, + {{ label: 'Output', data: d.out, backgroundColor: '#3fb950', + stack: 'tokens', yAxisID: 'y', order: 2 }}, + {{ label: 'Input (new)', data: d.inp, backgroundColor: '#1f6feb', + stack: 'tokens', yAxisID: 'y', order: 1 }}, + {{ label: 'Cost $', type: 'line', data: d.cost, + borderColor: '#f78166', backgroundColor: '#f78166', + borderWidth: 2, pointRadius: 3, yAxisID: 'y1', order: 0 }}, + ] + }}, + options: {{ + responsive: true, maintainAspectRatio: false, + scales: {{ + x: {{ stacked: true, ticks: {{ maxRotation: 45, minRotation: 45, + color: '#8b949e' }}, grid: {{ color: '#21262d' }} }}, + y: {{ stacked: true, position: 'left', + title: {{ display: true, text: 'Tokens', color: '#8b949e' }}, + ticks: {{ color: '#8b949e', callback: function (v) {{ + return v >= 1000 ? (v / 1000).toFixed(0) + 'k' : v; + }} }}, grid: {{ color: '#21262d' }} }}, + y1: {{ position: 'right', stacked: false, + title: {{ display: true, text: 'Cost (USD)', color: '#d29922' }}, + ticks: {{ color: '#d29922', callback: function (v) {{ + return '$' + v.toFixed(4); + }} }}, grid: {{ display: false }} }}, + }}, + plugins: {{ + legend: {{ labels: {{ color: '#8b949e', boxWidth: 12 }} }}, + tooltip: {{ + backgroundColor: '#1c2128', titleColor: '#e6edf3', + bodyColor: '#e6edf3', borderColor: '#30363d', borderWidth: 1, + callbacks: {{ + afterTitle: function (items) {{ + if (!items.length) return ''; + var m = d.models[items[0].dataIndex]; + return m ? m : ''; + }}, + label: function (ctx) {{ + var v = ctx.parsed.y; + if (ctx.dataset.yAxisID === 'y1') {{ + return ctx.dataset.label + ': $' + v.toFixed(4); + }} + return ctx.dataset.label + ': ' + v.toLocaleString() + ' tokens'; + }}, + }}, + }}, + }}, + }}, + }}); + }} + renderPage(0); + var lazy = document.querySelectorAll('.chart-lazy'); + if ('IntersectionObserver' in window && lazy.length > 1) {{ + var obs = new IntersectionObserver(function (entries) {{ + entries.forEach(function (e) {{ + if (e.isIntersecting) {{ + var pg = +e.target.getAttribute('data-pg'); + if (pg > 0) renderPage(pg); + obs.unobserve(e.target); + }} + }}); + }}, {{ rootMargin: '200px' }}); + for (var i = 1; i < lazy.length; i++) obs.observe(lazy[i]); + }} else {{ + for (var i = 1; i < DATA.length; i++) renderPage(i); + }} +}})();""" + + body = f"""
+{containers_html} +
+""" + + head_html = f"" + return (body, head_html) + + +def _render_chart_none(all_turns: list[dict]) -> tuple[str, str]: + """No-chart renderer. Emits an empty body + empty head — useful when the + caller wants a minimal detail page with no JS dependencies.""" + del all_turns + return ("", "") + + +CHART_RENDERERS = { + "highcharts": _render_chart_highcharts, + "uplot": _render_chart_uplot, + "chartjs": _render_chart_chartjs, + "none": _render_chart_none, +} + + +def render_html(report: dict, variant: str = "single", + nav_sibling: str | None = None, + chart_lib: str = "highcharts") -> str: + """Render the full report as a dark-themed HTML page with interactive charts. + + ``variant`` picks the page layout: + - ``"single"`` (default): everything in one file. Backward-compatible. + - ``"dashboard"``: summary cards + insight sections + links to the + detail page. No chart, no turn-level table, no chart-library JS + inline (massive size win). + - ``"detail"``: token-usage chart + timeline table + models pricing + table. No insight sections. + + ``nav_sibling`` is the relative href of the companion file shown in + the top nav bar. When ``None`` (single-page mode) the nav bar is omitted. + + ``chart_lib`` selects the chart renderer (see ``CHART_RENDERERS``). + Use ``"none"`` to emit the detail page with no chart at all — smallest + possible output, no JS dependency. + """ + include_insights = variant in ("single", "dashboard") + include_chart = variant in ("single", "detail") + slug = report["slug"] + totals = report["totals"] + mode = report["mode"] + generated = report["generated_at"][:19].replace("T", " ") + " UTC" + sessions = report["sessions"] + + # ---- Chart data -------------------------------------------------------- + # Built only when the variant actually renders a chart — saves real work + # (and, for the dashboard variant, drops the inline library JS bundle). + # The renderer is selected via ``CHART_RENDERERS[chart_lib]``; each + # returns ``(body_html, head_js)`` so the caller can place the JS in + # ```` while the container div goes in the body. + chart_html = "" + chart_head_html = "" + if include_chart: + if mode == "project": + all_turns = [t for s in sessions for t in s["turns"]] + else: + all_turns = sessions[0]["turns"] + renderer = CHART_RENDERERS.get(chart_lib) or _render_chart_none + chart_html, chart_head_html = renderer(all_turns) + + # ---- Insights sections (positioned above charts) --------------------- + tz_label = report.get("tz_label", "UTC") + tz_offset = report.get("tz_offset_hours", 0.0) + tod_html = "" + if include_insights: + tod_section = report.get("time_of_day", {}) + rollup_html = _build_weekly_rollup_html(report.get("weekly_rollup", {})) + blocks_html = _build_session_blocks_html( + report.get("session_blocks", []), + report.get("block_summary", {}), + tz_label, tz_offset, + ) + duration_html = _build_session_duration_html(sessions, tz_label, tz_offset) + hod_html = _build_hour_of_day_html(tod_section, tz_label, tz_offset, + peak=report.get("peak")) + punchcard_html = _build_punchcard_html(tod_section, tz_label, tz_offset) + heatmap_html = _build_tod_heatmap_html(tod_section) + tod_html = (rollup_html + blocks_html + duration_html + + hod_html + punchcard_html + heatmap_html) + + # ---- Table rows -------------------------------------------------------- + show_mode = _has_fast(report) + + # Total columns = #, Time, Model, [Mode], Input, Output, CacheRd, CacheWr, Total, Cost + _full_cols = 10 + (1 if show_mode else 0) + # Label cell in subtotal rows spans the non-numeric prefix: #, Time, Model, [Mode] + _label_span = 4 if show_mode else 3 + + def turn_row(t: dict, session_id: str) -> str: + bar_w = min(100, int(t["cost_usd"] * 2000)) + mode_td = "" + if show_mode: + spd = t.get("speed", "") + label = "fast" if spd == "fast" else "std" + cls = ' class="mode-fast"' if spd == "fast" else ' class="mode-std"' + mode_td = f'{label}' + return ( + f'' + f'{t["index"]}' + f'{t["timestamp_fmt"]}' + f'{t["model"]}' + f'{mode_td}' + f'{t["input_tokens"]:,}' + f'{t["output_tokens"]:,}' + f'{t["cache_read_tokens"]:,}' + f'{t["cache_write_tokens"]:,}' + f'{t["total_tokens"]:,}' + f'' + f'${t["cost_usd"]:.4f}' + f'' + ) + + def session_header(i: int, s: dict) -> str: + if mode != "project": + return "" + st = s["subtotal"] + return ( + f'' + f'' + f'▶ ' + f'Session {i}: {s["session_id"][:8]}…' + f'  {s["first_ts"]} → {s["last_ts"]}' + f' ·  {len(s["turns"])} turns' + f' ·  ${st["cost"]:.4f}' + f'' + ) + + def subtotal_row(label: str, st: dict) -> str: + return ( + f'' + f'{label}' + f'{st["input"]:,}' + f'{st["output"]:,}' + f'{st["cache_read"]:,}' + f'{st["cache_write"]:,}' + f'{st["total"]:,}' + f'${st["cost"]:.4f}' + f'' + ) + + table_rows: list[str] = [] + model_rows = "" + if include_chart: + for i, s in enumerate(sessions, 1): + if mode == "project": + table_rows.append(session_header(i, s)) + table_rows.append(f'') + for t in s["turns"]: + table_rows.append(turn_row(t, s["session_id"])) + if mode == "project": + table_rows.append(subtotal_row(f"S{i:02} subtotal", s["subtotal"])) + table_rows.append('') + table_rows.append(subtotal_row("PROJECT TOTAL" if mode == "project" else "TOTAL", totals)) + + model_rows = "".join( + f'{m}{cnt:,}' + f'${_pricing_for(m)["input"]:.2f}' + f'${_pricing_for(m)["output"]:.2f}' + f'${_pricing_for(m)["cache_read"]:.2f}' + f'${_pricing_for(m)["cache_write"]:.2f}' + for m, cnt in sorted(report["models"].items(), key=lambda x: -x[1]) + ) + + # Nav bar: cross-link to the companion page (only present in split mode). + nav_html = "" + if nav_sibling: + label_here = "Dashboard" if variant == "dashboard" else "Detail" + label_other = "Detail \u2192" if variant == "dashboard" else "\u2190 Dashboard" + nav_html = ( + f'
' + f'You are on:' + f'{label_here}' + f'{label_other}' + f'
' + ) + + chart_section_html = "" + if include_chart and chart_html: + chart_section_html = f'

Token Usage Over Time

\n{chart_html}' + + table_section_html = "" + if include_chart and table_rows: + table_section_html = ( + '

Timeline ' + 'API splits input into three fields: ' + 'Input (new) = input_tokens (uncached) · ' + 'CacheRd = cache_read_input_tokens · ' + 'CacheWr = cache_creation_input_tokens. ' + 'Total input sent to the model = sum of all three.' + '

\n\n\n' + ' \n' + f' {"" if show_mode else ""}\n' + ' \n' + ' \n' + ' \n' + f'\n\n{"".join(table_rows)}\n\n
#Time (UTC)ModelModeInput (new)OutputCacheRdCacheWrTotalCost $
\n' + ) + + models_section_html = "" + if include_chart and model_rows: + models_section_html = ( + '

Models

\n\n' + '\n' + ' \n' + ' \n' + f'{model_rows}\n
ModelTurns$/M input$/M output$/M rd$/M wr
\n' + ) + + summary_cards_html = "" + if include_insights: + summary_cards_html = f'''\ +
+
${totals['cost']:.4f}
Total cost (USD)
+
${totals['cache_savings']:.4f}
Cache savings
+
{totals['cache_hit_pct']:.1f}%
Cache hit ratio
+
{totals['total_input']:,}
Total input tokens
+
{totals['input']:,}
Input tokens (new)
+
{totals['output']:,}
Output tokens
+
{totals['cache_read']:,}
Cache read tokens
+
{totals['cache_write']:,}
Cache write tokens
+
''' + + toggle_script_html = "" + if include_chart and mode == "project": + toggle_script_html = """""" + + title_suffix = (" — Dashboard" if variant == "dashboard" + else " — Detail" if variant == "detail" else "") + return f""" + + + +Session Metrics — {slug}{title_suffix} +{chart_head_html} + + + +{nav_html} +

Session Metrics — {slug}{title_suffix}

+

Generated {generated}  ·  Mode: {mode}  ·  +{len(sessions)} session{'s' if len(sessions) != 1 else ''}, {totals['turns']:,} turns

+{summary_cards_html} +{tod_html} +{chart_section_html} +{table_section_html} +{models_section_html} +{toggle_script_html} + +""" + + +# --------------------------------------------------------------------------- +# Output dispatch +# --------------------------------------------------------------------------- + +_RENDERERS = { + "text": render_text, + "json": render_json, + "csv": render_csv, + "md": render_md, + "html": render_html, +} +_EXTENSIONS = {"text": "txt", "json": "json", "csv": "csv", "md": "md", "html": "html"} + + +def _export_dir() -> Path: + return Path(os.getcwd()) / "exports" / "session-metrics" + + +def _write_output(fmt: str, content: str, report: dict, + suffix: str = "") -> Path: + """Write ``content`` to an export file; ``suffix`` is appended before + the extension (e.g. ``"_dashboard"``, ``"_detail"``).""" + out_dir = _export_dir() + out_dir.mkdir(parents=True, exist_ok=True) + mode = report["mode"] + ts = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ") + if mode == "project": + stem = f"project_{ts}" + else: + sid = report["sessions"][0]["session_id"][:8] + stem = f"session_{sid}_{ts}" + path = out_dir / f"{stem}{suffix}.{_EXTENSIONS[fmt]}" + path.write_text(content, encoding="utf-8") + return path + + +# --------------------------------------------------------------------------- +# Modes +# --------------------------------------------------------------------------- + +def _load_session( + jsonl_path: Path, include_subagents: bool, use_cache: bool = True, +) -> tuple[str, list[dict], list[int]]: + """Load a session JSONL and return structured data for report building. + + Parses the JSONL file, optionally merging subagent logs, then extracts + both assistant turns (for token/cost tracking) and user timestamps (for + time-of-day activity analysis). User timestamps are extracted from the + full entry list *before* assistant-only filtering discards them. + + Returns: + 3-tuple of (session_id, assistant_turns, user_epoch_secs) where + session_id is the JSONL filename stem, assistant_turns is the + deduplicated/sorted list of raw assistant entries, and + user_epoch_secs is a sorted list of UTC epoch-seconds for every + genuine user prompt (tool_results and meta entries excluded). + """ + entries = _cached_parse_jsonl(jsonl_path, use_cache=use_cache) + if include_subagents: + subagent_dir = jsonl_path.parent / jsonl_path.stem / "subagents" + if subagent_dir.exists(): + for sub in sorted(subagent_dir.glob("*.jsonl")): + entries += _cached_parse_jsonl(sub, use_cache=use_cache) + return ( + jsonl_path.stem, + _extract_turns(entries), + _extract_user_timestamps(entries, include_sidechain=include_subagents), + ) + + +def _run_single_session(jsonl_path: Path, slug: str, include_subagents: bool, + formats: list[str], tz_offset: float, tz_label: str, + peak: dict | None = None, + single_page: bool = False, + use_cache: bool = True, + chart_lib: str = "highcharts") -> None: + print(f"Session : {jsonl_path.stem}", file=sys.stderr) + print(f"File : {jsonl_path}", file=sys.stderr) + print(file=sys.stderr) + + session_id, turns, user_ts = _load_session(jsonl_path, include_subagents, + use_cache=use_cache) + if not turns: + print("[info] No assistant turns with usage data found.", file=sys.stderr) + return + + report = _build_report("session", slug, [(session_id, turns, user_ts)], + tz_offset_hours=tz_offset, tz_label=tz_label, + peak=peak) + _dispatch(report, formats, single_page=single_page, chart_lib=chart_lib) + + +def _run_project_cost(slug: str, include_subagents: bool, formats: list[str], + tz_offset: float, tz_label: str, + peak: dict | None = None, + single_page: bool = False, + use_cache: bool = True, + chart_lib: str = "highcharts") -> None: + files = _find_jsonl_files(slug) + if not files: + print(f"[error] No sessions found for slug: {slug}", file=sys.stderr) + sys.exit(1) + + sessions_raw = [] + for path in reversed(files): # oldest first + sid, turns, user_ts = _load_session(path, include_subagents, + use_cache=use_cache) + if turns: + sessions_raw.append((sid, turns, user_ts)) + + if not sessions_raw: + print("[info] No turns with usage data found across any session.", file=sys.stderr) + return + + report = _build_report("project", slug, sessions_raw, + tz_offset_hours=tz_offset, tz_label=tz_label, + peak=peak) + _dispatch(report, formats, single_page=single_page, chart_lib=chart_lib) + + +def _dispatch(report: dict, formats: list[str], + single_page: bool = False, + chart_lib: str = "highcharts") -> None: + # Always render text to stdout + print(render_text(report)) + + for fmt in formats: + if fmt == "text": + continue # already printed + if fmt == "html" and not single_page: + # Split into two files. Dashboard references detail as a sibling + # by filename-only href so file:// works without a server. + mode = report["mode"] + ts = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ") + stem = (f"project_{ts}" if mode == "project" + else f"session_{report['sessions'][0]['session_id'][:8]}_{ts}") + dashboard_name = f"{stem}_dashboard.html" + detail_name = f"{stem}_detail.html" + dash = render_html(report, variant="dashboard", + nav_sibling=detail_name, chart_lib=chart_lib) + det = render_html(report, variant="detail", + nav_sibling=dashboard_name, chart_lib=chart_lib) + p1 = _export_dir() / dashboard_name + p2 = _export_dir() / detail_name + _export_dir().mkdir(parents=True, exist_ok=True) + p1.write_text(dash, encoding="utf-8") + p2.write_text(det, encoding="utf-8") + print(f"[export] HTML (dashboard) → {p1}", file=sys.stderr) + print(f"[export] HTML (detail) → {p2}", file=sys.stderr) + continue + if fmt == "html": + content = render_html(report, variant="single", chart_lib=chart_lib) + else: + content = _RENDERERS[fmt](report) + path = _write_output(fmt, content, report) + print(f"[export] {fmt.upper():4} → {path}", file=sys.stderr) + + +def _list_sessions(slug: str) -> None: + files = _find_jsonl_files(slug) + if not files: + print(f"No sessions found for slug: {slug}") + return + print(f"Sessions for {slug}:") + print(f" {'Session UUID':<40} {'Modified':<20} {'Size':>8}") + print(" " + "-" * 72) + for p in files: + stat = p.stat() + mtime = datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc).strftime("%Y-%m-%d %H:%M:%S") + print(f" {p.stem:<40} {mtime:<20} {stat.st_size / 1024:>6.1f}K") + + +# --------------------------------------------------------------------------- +# CLI +# --------------------------------------------------------------------------- + +def _build_parser() -> argparse.ArgumentParser: + p = argparse.ArgumentParser( + description="Tally Claude Code session token usage and cost estimates.", + formatter_class=argparse.RawDescriptionHelpFormatter, + epilog=__doc__, + ) + p.add_argument("--session", "-s", metavar="UUID", type=_validate_session_id, + help="Session UUID to analyse. Also reads $CLAUDE_SESSION_ID.") + p.add_argument("--slug", metavar="SLUG", type=_validate_slug, + help="Project slug (use --slug= when value starts with '-'). " + "Also reads $CLAUDE_PROJECT_SLUG.") + p.add_argument("--list", "-l", action="store_true", + help="List available sessions for this project and exit.") + p.add_argument("--project-cost", "-p", action="store_true", + help="Show all sessions in chronological order with per-session " + "subtotals and a grand project total.") + p.add_argument("--output", "-o", nargs="+", metavar="FMT", + choices=["text", "json", "csv", "md", "html"], + help="Export formats in addition to stdout text. " + "One or more of: json csv md html. " + "Written to exports/session-metrics/ in the project root.") + p.add_argument("--include-subagents", action="store_true", + help="Also tally spawned subagent JSONL files.") + p.add_argument("--tz", metavar="IANA", + help="IANA timezone for time-of-day bucketing " + "(e.g. 'America/Los_Angeles', 'Australia/Brisbane'). " + "Defaults to system local timezone.") + p.add_argument("--utc-offset", type=float, metavar="H", + help="Fixed UTC offset in hours for time-of-day bucketing " + "(e.g. -8, 5.5). DST-naive; use --tz for DST-aware.") + p.add_argument("--peak-hours", type=_parse_peak_hours, metavar="H-H", + help="Overlay a translucent band on the hour-of-day chart " + "for the given hour range (e.g. '5-11'). Community-reported; " + "not an official Anthropic SLA.") + p.add_argument("--peak-tz", metavar="IANA", + help="IANA tz the peak hours are defined in (default: " + "'America/Los_Angeles'). Only used when --peak-hours is set.") + p.add_argument("--single-page", action="store_true", + help="HTML export: emit a single self-contained file instead " + "of the default 2-page split (dashboard + detail).") + p.add_argument("--no-cache", action="store_true", + help="Skip the parse cache at ~/.cache/session-metrics/parse/ " + "and always re-parse JSONL from scratch.") + p.add_argument("--chart-lib", metavar="LIB", + choices=sorted(CHART_RENDERERS.keys()), + default="highcharts", + help="Chart renderer for HTML export. One of: " + f"{', '.join(sorted(CHART_RENDERERS.keys()))}. " + "Default: highcharts (vendored, non-commercial). " + "Alternatives: uplot/chartjs (MIT). " + "Use 'none' for a no-JS detail page.") + return p + + +def _maybe_warn_chart_license(chart_lib: str, formats: list[str]) -> None: + """Surface non-commercial licensing notice when HTML is exported with + Highcharts. Silent for ``none`` or when the user isn't exporting HTML.""" + if "html" not in formats: + return + manifest = _load_chart_manifest() + entry = manifest.get("libraries", {}).get(chart_lib, {}) + if entry.get("license", "").startswith("non-commercial"): + print(f"[info] Chart library '{chart_lib}' is under a " + f"{entry['license']} license. Commercial distribution of the " + f"generated HTML may require a paid upstream license. Pass " + f"--chart-lib none to opt out.", file=sys.stderr) + + +def main() -> None: + args = _build_parser().parse_args() + slug = args.slug or _env_slug() or _cwd_to_slug() + _validate_slug(slug) + formats: list[str] = args.output or [] + tz_offset, tz_label = _resolve_tz(args.tz, args.utc_offset) + peak = _build_peak(args.peak_hours, args.peak_tz) + chart_lib: str = args.chart_lib + _maybe_warn_chart_license(chart_lib, formats) + + if args.list: + _list_sessions(slug) + return + + if args.project_cost: + print(f"Slug : {slug}", file=sys.stderr) + print(f"TZ : {tz_label} (UTC{'+' if tz_offset >= 0 else '-'}{abs(tz_offset):g})", file=sys.stderr) + print(file=sys.stderr) + _run_project_cost(slug, args.include_subagents, formats, tz_offset, tz_label, + peak=peak, single_page=args.single_page, + use_cache=not args.no_cache, + chart_lib=chart_lib) + return + + jsonl_path, resolved_slug = _resolve_session(args) + print(f"Slug : {resolved_slug}", file=sys.stderr) + print(f"TZ : {tz_label} (UTC{'+' if tz_offset >= 0 else '-'}{abs(tz_offset):g})", file=sys.stderr) + _run_single_session(jsonl_path, resolved_slug, args.include_subagents, formats, + tz_offset, tz_label, peak=peak, single_page=args.single_page, + use_cache=not args.no_cache, + chart_lib=chart_lib) + + +if __name__ == "__main__": + main() diff --git a/.claude/skills/session-metrics/scripts/vendor/charts/README.md b/.claude/skills/session-metrics/scripts/vendor/charts/README.md new file mode 100644 index 0000000..4ec7c0a --- /dev/null +++ b/.claude/skills/session-metrics/scripts/vendor/charts/README.md @@ -0,0 +1,62 @@ +# Vendored chart libraries + +Files in this tree are checked into the repo so the HTML export works +fully offline (no CDN round-trip, no runtime `~/.cache/` writes). +[`manifest.json`](manifest.json) lists each file's expected SHA-256; +`session-metrics.py` verifies the hash before inlining the JS (and CSS, +for libraries that need it). + +## Layout + +``` +vendor/charts/ + manifest.json — version, SHA-256, license per library + highcharts/v12/ — non-commercial license (see LICENSE.txt) + highcharts.js + highcharts-3d.js + exporting.js + export-data.js + uplot/v1/ — MIT (see LICENSE.txt) + uPlot.iife.min.js + uPlot.min.css + chartjs/v4/ — MIT (see LICENSE.txt) + chart.umd.js +``` + +## Refreshing the vendored files + +```bash +cd scripts/vendor/charts/highcharts/v12 +for f in highcharts.js highcharts-3d.js; do + curl -fsSL -o "$f" "https://cdn.jsdelivr.net/npm/highcharts@12/$f" +done +for f in exporting.js export-data.js; do + curl -fsSL -o "$f" "https://cdn.jsdelivr.net/npm/highcharts@12/modules/$f" +done +shasum -a 256 *.js # update manifest.json with the new digests + +cd ../../uplot/v1 +curl -fsSL -o uPlot.iife.min.js https://cdn.jsdelivr.net/npm/uplot@1/dist/uPlot.iife.min.js +curl -fsSL -o uPlot.min.css https://cdn.jsdelivr.net/npm/uplot@1/dist/uPlot.min.css +shasum -a 256 *.js *.css + +cd ../../chartjs/v4 +curl -fsSL -o chart.umd.js https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.js +shasum -a 256 *.js +``` + +Bump the version directory (`v12` → `v13`, etc.) if the major release +changes; the script auto-discovers via the manifest. + +## Licenses + +| Library | License | Notes | +|------------|------------------------|-----------------------------------------------------------------------| +| Highcharts | non-commercial-free | Commercial use needs a paid Highsoft AS license. See LICENSE.txt. | +| uPlot | MIT | [github.com/leeoniya/uPlot](https://github.com/leeoniya/uPlot/blob/master/LICENSE) | +| Chart.js | MIT | [github.com/chartjs/Chart.js](https://github.com/chartjs/Chart.js/blob/master/LICENSE.md) | + +Pick the renderer with `--chart-lib {highcharts|uplot|chartjs|none}`. +Default is `highcharts` (richest visualization, 3D sliders). Use +`uplot` or `chartjs` for a lighter, MIT-licensed output; `none` for +a no-JS detail page. diff --git a/.claude/skills/session-metrics/scripts/vendor/charts/chartjs/v4/LICENSE.txt b/.claude/skills/session-metrics/scripts/vendor/charts/chartjs/v4/LICENSE.txt new file mode 100644 index 0000000..f216610 --- /dev/null +++ b/.claude/skills/session-metrics/scripts/vendor/charts/chartjs/v4/LICENSE.txt @@ -0,0 +1,9 @@ +The MIT License (MIT) + +Copyright (c) 2014-2024 Chart.js Contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/.claude/skills/session-metrics/scripts/vendor/charts/chartjs/v4/chart.umd.js b/.claude/skills/session-metrics/scripts/vendor/charts/chartjs/v4/chart.umd.js new file mode 100644 index 0000000..4cfce5c --- /dev/null +++ b/.claude/skills/session-metrics/scripts/vendor/charts/chartjs/v4/chart.umd.js @@ -0,0 +1,14 @@ +/*! + * Chart.js v4.5.1 + * https://www.chartjs.org + * (c) 2025 Chart.js Contributors + * Released under the MIT License + */ +!function(t,e){"object"==typeof exports&&"undefined"!=typeof module?module.exports=e():"function"==typeof define&&define.amd?define(e):(t="undefined"!=typeof globalThis?globalThis:t||self).Chart=e()}(this,(function(){"use strict";var t=Object.freeze({__proto__:null,get Colors(){return Jo},get Decimation(){return ta},get Filler(){return ba},get Legend(){return Ma},get SubTitle(){return Pa},get Title(){return ka},get Tooltip(){return Na}});function e(){}const i=(()=>{let t=0;return()=>t++})();function s(t){return null==t}function n(t){if(Array.isArray&&Array.isArray(t))return!0;const e=Object.prototype.toString.call(t);return"[object"===e.slice(0,7)&&"Array]"===e.slice(-6)}function o(t){return null!==t&&"[object Object]"===Object.prototype.toString.call(t)}function a(t){return("number"==typeof t||t instanceof Number)&&isFinite(+t)}function r(t,e){return a(t)?t:e}function l(t,e){return void 0===t?e:t}const h=(t,e)=>"string"==typeof t&&t.endsWith("%")?parseFloat(t)/100:+t/e,c=(t,e)=>"string"==typeof t&&t.endsWith("%")?parseFloat(t)/100*e:+t;function d(t,e,i){if(t&&"function"==typeof t.call)return t.apply(i,e)}function u(t,e,i,s){let a,r,l;if(n(t))if(r=t.length,s)for(a=r-1;a>=0;a--)e.call(i,t[a],a);else for(a=0;at,x:t=>t.x,y:t=>t.y};function v(t){const e=t.split("."),i=[];let s="";for(const t of e)s+=t,s.endsWith("\\")?s=s.slice(0,-1)+".":(i.push(s),s="");return i}function M(t,e){const i=y[e]||(y[e]=function(t){const e=v(t);return t=>{for(const i of e){if(""===i)break;t=t&&t[i]}return t}}(e));return i(t)}function w(t){return t.charAt(0).toUpperCase()+t.slice(1)}const k=t=>void 0!==t,S=t=>"function"==typeof t,P=(t,e)=>{if(t.size!==e.size)return!1;for(const i of t)if(!e.has(i))return!1;return!0};function D(t){return"mouseup"===t.type||"click"===t.type||"contextmenu"===t.type}const C=Math.PI,O=2*C,A=O+C,T=Number.POSITIVE_INFINITY,L=C/180,E=C/2,R=C/4,I=2*C/3,z=Math.log10,F=Math.sign;function V(t,e,i){return Math.abs(t-e)t-e)).pop(),e}function N(t){return!function(t){return"symbol"==typeof t||"object"==typeof t&&null!==t&&!(Symbol.toPrimitive in t||"toString"in t||"valueOf"in t)}(t)&&!isNaN(parseFloat(t))&&isFinite(t)}function H(t,e){const i=Math.round(t);return i-e<=t&&i+e>=t}function j(t,e,i){let s,n,o;for(s=0,n=t.length;sl&&h=Math.min(e,i)-s&&t<=Math.max(e,i)+s}function et(t,e,i){i=i||(i=>t[i]1;)s=o+n>>1,i(s)?o=s:n=s;return{lo:o,hi:n}}const it=(t,e,i,s)=>et(t,i,s?s=>{const n=t[s][e];return nt[s][e]et(t,i,(s=>t[s][e]>=i));function nt(t,e,i){let s=0,n=t.length;for(;ss&&t[n-1]>i;)n--;return s>0||n{const i="_onData"+w(e),s=t[e];Object.defineProperty(t,e,{configurable:!0,enumerable:!1,value(...e){const n=s.apply(this,e);return t._chartjs.listeners.forEach((t=>{"function"==typeof t[i]&&t[i](...e)})),n}})})))}function rt(t,e){const i=t._chartjs;if(!i)return;const s=i.listeners,n=s.indexOf(e);-1!==n&&s.splice(n,1),s.length>0||(ot.forEach((e=>{delete t[e]})),delete t._chartjs)}function lt(t){const e=new Set(t);return e.size===t.length?t:Array.from(e)}const ht="undefined"==typeof window?function(t){return t()}:window.requestAnimationFrame;function ct(t,e){let i=[],s=!1;return function(...n){i=n,s||(s=!0,ht.call(window,(()=>{s=!1,t.apply(e,i)})))}}function dt(t,e){let i;return function(...s){return e?(clearTimeout(i),i=setTimeout(t,e,s)):t.apply(this,s),e}}const ut=t=>"start"===t?"left":"end"===t?"right":"center",ft=(t,e,i)=>"start"===t?e:"end"===t?i:(e+i)/2,gt=(t,e,i,s)=>t===(s?"left":"right")?i:"center"===t?(e+i)/2:e;function pt(t,e,i){const n=e.length;let o=0,a=n;if(t._sorted){const{iScale:r,vScale:l,_parsed:h}=t,c=t.dataset&&t.dataset.options?t.dataset.options.spanGaps:null,d=r.axis,{min:u,max:f,minDefined:g,maxDefined:p}=r.getUserBounds();if(g){if(o=Math.min(it(h,d,u).lo,i?n:it(e,d,r.getPixelForValue(u)).lo),c){const t=h.slice(0,o+1).reverse().findIndex((t=>!s(t[l.axis])));o-=Math.max(0,t)}o=Z(o,0,n-1)}if(p){let t=Math.max(it(h,r.axis,f,!0).hi+1,i?0:it(e,d,r.getPixelForValue(f),!0).hi+1);if(c){const e=h.slice(t-1).findIndex((t=>!s(t[l.axis])));t+=Math.max(0,e)}a=Z(t,o,n)-o}else a=n-o}return{start:o,count:a}}function mt(t){const{xScale:e,yScale:i,_scaleRanges:s}=t,n={xmin:e.min,xmax:e.max,ymin:i.min,ymax:i.max};if(!s)return t._scaleRanges=n,!0;const o=s.xmin!==e.min||s.xmax!==e.max||s.ymin!==i.min||s.ymax!==i.max;return Object.assign(s,n),o}class xt{constructor(){this._request=null,this._charts=new Map,this._running=!1,this._lastDate=void 0}_notify(t,e,i,s){const n=e.listeners[s],o=e.duration;n.forEach((s=>s({chart:t,initial:e.initial,numSteps:o,currentStep:Math.min(i-e.start,o)})))}_refresh(){this._request||(this._running=!0,this._request=ht.call(window,(()=>{this._update(),this._request=null,this._running&&this._refresh()})))}_update(t=Date.now()){let e=0;this._charts.forEach(((i,s)=>{if(!i.running||!i.items.length)return;const n=i.items;let o,a=n.length-1,r=!1;for(;a>=0;--a)o=n[a],o._active?(o._total>i.duration&&(i.duration=o._total),o.tick(t),r=!0):(n[a]=n[n.length-1],n.pop());r&&(s.draw(),this._notify(s,i,t,"progress")),n.length||(i.running=!1,this._notify(s,i,t,"complete"),i.initial=!1),e+=n.length})),this._lastDate=t,0===e&&(this._running=!1)}_getAnims(t){const e=this._charts;let i=e.get(t);return i||(i={running:!1,initial:!0,items:[],listeners:{complete:[],progress:[]}},e.set(t,i)),i}listen(t,e,i){this._getAnims(t).listeners[e].push(i)}add(t,e){e&&e.length&&this._getAnims(t).items.push(...e)}has(t){return this._getAnims(t).items.length>0}start(t){const e=this._charts.get(t);e&&(e.running=!0,e.start=Date.now(),e.duration=e.items.reduce(((t,e)=>Math.max(t,e._duration)),0),this._refresh())}running(t){if(!this._running)return!1;const e=this._charts.get(t);return!!(e&&e.running&&e.items.length)}stop(t){const e=this._charts.get(t);if(!e||!e.items.length)return;const i=e.items;let s=i.length-1;for(;s>=0;--s)i[s].cancel();e.items=[],this._notify(t,e,Date.now(),"complete")}remove(t){return this._charts.delete(t)}}var bt=new xt; +/*! + * @kurkle/color v0.3.2 + * https://github.com/kurkle/color#readme + * (c) 2023 Jukka Kurkela + * Released under the MIT License + */function _t(t){return t+.5|0}const yt=(t,e,i)=>Math.max(Math.min(t,i),e);function vt(t){return yt(_t(2.55*t),0,255)}function Mt(t){return yt(_t(255*t),0,255)}function wt(t){return yt(_t(t/2.55)/100,0,1)}function kt(t){return yt(_t(100*t),0,100)}const St={0:0,1:1,2:2,3:3,4:4,5:5,6:6,7:7,8:8,9:9,A:10,B:11,C:12,D:13,E:14,F:15,a:10,b:11,c:12,d:13,e:14,f:15},Pt=[..."0123456789ABCDEF"],Dt=t=>Pt[15&t],Ct=t=>Pt[(240&t)>>4]+Pt[15&t],Ot=t=>(240&t)>>4==(15&t);function At(t){var e=(t=>Ot(t.r)&&Ot(t.g)&&Ot(t.b)&&Ot(t.a))(t)?Dt:Ct;return t?"#"+e(t.r)+e(t.g)+e(t.b)+((t,e)=>t<255?e(t):"")(t.a,e):void 0}const Tt=/^(hsla?|hwb|hsv)\(\s*([-+.e\d]+)(?:deg)?[\s,]+([-+.e\d]+)%[\s,]+([-+.e\d]+)%(?:[\s,]+([-+.e\d]+)(%)?)?\s*\)$/;function Lt(t,e,i){const s=e*Math.min(i,1-i),n=(e,n=(e+t/30)%12)=>i-s*Math.max(Math.min(n-3,9-n,1),-1);return[n(0),n(8),n(4)]}function Et(t,e,i){const s=(s,n=(s+t/60)%6)=>i-i*e*Math.max(Math.min(n,4-n,1),0);return[s(5),s(3),s(1)]}function Rt(t,e,i){const s=Lt(t,1,.5);let n;for(e+i>1&&(n=1/(e+i),e*=n,i*=n),n=0;n<3;n++)s[n]*=1-e-i,s[n]+=e;return s}function It(t){const e=t.r/255,i=t.g/255,s=t.b/255,n=Math.max(e,i,s),o=Math.min(e,i,s),a=(n+o)/2;let r,l,h;return n!==o&&(h=n-o,l=a>.5?h/(2-n-o):h/(n+o),r=function(t,e,i,s,n){return t===n?(e-i)/s+(e>16&255,o>>8&255,255&o]}return t}(),Ht.transparent=[0,0,0,0]);const e=Ht[t.toLowerCase()];return e&&{r:e[0],g:e[1],b:e[2],a:4===e.length?e[3]:255}}const $t=/^rgba?\(\s*([-+.\d]+)(%)?[\s,]+([-+.e\d]+)(%)?[\s,]+([-+.e\d]+)(%)?(?:[\s,/]+([-+.e\d]+)(%)?)?\s*\)$/;const Yt=t=>t<=.0031308?12.92*t:1.055*Math.pow(t,1/2.4)-.055,Ut=t=>t<=.04045?t/12.92:Math.pow((t+.055)/1.055,2.4);function Xt(t,e,i){if(t){let s=It(t);s[e]=Math.max(0,Math.min(s[e]+s[e]*i,0===e?360:1)),s=Ft(s),t.r=s[0],t.g=s[1],t.b=s[2]}}function qt(t,e){return t?Object.assign(e||{},t):t}function Kt(t){var e={r:0,g:0,b:0,a:255};return Array.isArray(t)?t.length>=3&&(e={r:t[0],g:t[1],b:t[2],a:255},t.length>3&&(e.a=Mt(t[3]))):(e=qt(t,{r:0,g:0,b:0,a:1})).a=Mt(e.a),e}function Gt(t){return"r"===t.charAt(0)?function(t){const e=$t.exec(t);let i,s,n,o=255;if(e){if(e[7]!==i){const t=+e[7];o=e[8]?vt(t):yt(255*t,0,255)}return i=+e[1],s=+e[3],n=+e[5],i=255&(e[2]?vt(i):yt(i,0,255)),s=255&(e[4]?vt(s):yt(s,0,255)),n=255&(e[6]?vt(n):yt(n,0,255)),{r:i,g:s,b:n,a:o}}}(t):Bt(t)}class Jt{constructor(t){if(t instanceof Jt)return t;const e=typeof t;let i;var s,n,o;"object"===e?i=Kt(t):"string"===e&&(o=(s=t).length,"#"===s[0]&&(4===o||5===o?n={r:255&17*St[s[1]],g:255&17*St[s[2]],b:255&17*St[s[3]],a:5===o?17*St[s[4]]:255}:7!==o&&9!==o||(n={r:St[s[1]]<<4|St[s[2]],g:St[s[3]]<<4|St[s[4]],b:St[s[5]]<<4|St[s[6]],a:9===o?St[s[7]]<<4|St[s[8]]:255})),i=n||jt(t)||Gt(t)),this._rgb=i,this._valid=!!i}get valid(){return this._valid}get rgb(){var t=qt(this._rgb);return t&&(t.a=wt(t.a)),t}set rgb(t){this._rgb=Kt(t)}rgbString(){return this._valid?(t=this._rgb)&&(t.a<255?`rgba(${t.r}, ${t.g}, ${t.b}, ${wt(t.a)})`:`rgb(${t.r}, ${t.g}, ${t.b})`):void 0;var t}hexString(){return this._valid?At(this._rgb):void 0}hslString(){return this._valid?function(t){if(!t)return;const e=It(t),i=e[0],s=kt(e[1]),n=kt(e[2]);return t.a<255?`hsla(${i}, ${s}%, ${n}%, ${wt(t.a)})`:`hsl(${i}, ${s}%, ${n}%)`}(this._rgb):void 0}mix(t,e){if(t){const i=this.rgb,s=t.rgb;let n;const o=e===n?.5:e,a=2*o-1,r=i.a-s.a,l=((a*r==-1?a:(a+r)/(1+a*r))+1)/2;n=1-l,i.r=255&l*i.r+n*s.r+.5,i.g=255&l*i.g+n*s.g+.5,i.b=255&l*i.b+n*s.b+.5,i.a=o*i.a+(1-o)*s.a,this.rgb=i}return this}interpolate(t,e){return t&&(this._rgb=function(t,e,i){const s=Ut(wt(t.r)),n=Ut(wt(t.g)),o=Ut(wt(t.b));return{r:Mt(Yt(s+i*(Ut(wt(e.r))-s))),g:Mt(Yt(n+i*(Ut(wt(e.g))-n))),b:Mt(Yt(o+i*(Ut(wt(e.b))-o))),a:t.a+i*(e.a-t.a)}}(this._rgb,t._rgb,e)),this}clone(){return new Jt(this.rgb)}alpha(t){return this._rgb.a=Mt(t),this}clearer(t){return this._rgb.a*=1-t,this}greyscale(){const t=this._rgb,e=_t(.3*t.r+.59*t.g+.11*t.b);return t.r=t.g=t.b=e,this}opaquer(t){return this._rgb.a*=1+t,this}negate(){const t=this._rgb;return t.r=255-t.r,t.g=255-t.g,t.b=255-t.b,this}lighten(t){return Xt(this._rgb,2,t),this}darken(t){return Xt(this._rgb,2,-t),this}saturate(t){return Xt(this._rgb,1,t),this}desaturate(t){return Xt(this._rgb,1,-t),this}rotate(t){return function(t,e){var i=It(t);i[0]=Vt(i[0]+e),i=Ft(i),t.r=i[0],t.g=i[1],t.b=i[2]}(this._rgb,t),this}}function Zt(t){if(t&&"object"==typeof t){const e=t.toString();return"[object CanvasPattern]"===e||"[object CanvasGradient]"===e}return!1}function Qt(t){return Zt(t)?t:new Jt(t)}function te(t){return Zt(t)?t:new Jt(t).saturate(.5).darken(.1).hexString()}const ee=["x","y","borderWidth","radius","tension"],ie=["color","borderColor","backgroundColor"];const se=new Map;function ne(t,e,i){return function(t,e){e=e||{};const i=t+JSON.stringify(e);let s=se.get(i);return s||(s=new Intl.NumberFormat(t,e),se.set(i,s)),s}(e,i).format(t)}const oe={values:t=>n(t)?t:""+t,numeric(t,e,i){if(0===t)return"0";const s=this.chart.options.locale;let n,o=t;if(i.length>1){const e=Math.max(Math.abs(i[0].value),Math.abs(i[i.length-1].value));(e<1e-4||e>1e15)&&(n="scientific"),o=function(t,e){let i=e.length>3?e[2].value-e[1].value:e[1].value-e[0].value;Math.abs(i)>=1&&t!==Math.floor(t)&&(i=t-Math.floor(t));return i}(t,i)}const a=z(Math.abs(o)),r=isNaN(a)?1:Math.max(Math.min(-1*Math.floor(a),20),0),l={notation:n,minimumFractionDigits:r,maximumFractionDigits:r};return Object.assign(l,this.options.ticks.format),ne(t,s,l)},logarithmic(t,e,i){if(0===t)return"0";const s=i[e].significand||t/Math.pow(10,Math.floor(z(t)));return[1,2,3,5,10,15].includes(s)||e>.8*i.length?oe.numeric.call(this,t,e,i):""}};var ae={formatters:oe};const re=Object.create(null),le=Object.create(null);function he(t,e){if(!e)return t;const i=e.split(".");for(let e=0,s=i.length;et.chart.platform.getDevicePixelRatio(),this.elements={},this.events=["mousemove","mouseout","click","touchstart","touchmove"],this.font={family:"'Helvetica Neue', 'Helvetica', 'Arial', sans-serif",size:12,style:"normal",lineHeight:1.2,weight:null},this.hover={},this.hoverBackgroundColor=(t,e)=>te(e.backgroundColor),this.hoverBorderColor=(t,e)=>te(e.borderColor),this.hoverColor=(t,e)=>te(e.color),this.indexAxis="x",this.interaction={mode:"nearest",intersect:!0,includeInvisible:!1},this.maintainAspectRatio=!0,this.onHover=null,this.onClick=null,this.parsing=!0,this.plugins={},this.responsive=!0,this.scale=void 0,this.scales={},this.showLine=!0,this.drawActiveElementsOnTop=!0,this.describe(t),this.apply(e)}set(t,e){return ce(this,t,e)}get(t){return he(this,t)}describe(t,e){return ce(le,t,e)}override(t,e){return ce(re,t,e)}route(t,e,i,s){const n=he(this,t),a=he(this,i),r="_"+e;Object.defineProperties(n,{[r]:{value:n[e],writable:!0},[e]:{enumerable:!0,get(){const t=this[r],e=a[s];return o(t)?Object.assign({},e,t):l(t,e)},set(t){this[r]=t}}})}apply(t){t.forEach((t=>t(this)))}}var ue=new de({_scriptable:t=>!t.startsWith("on"),_indexable:t=>"events"!==t,hover:{_fallback:"interaction"},interaction:{_scriptable:!1,_indexable:!1}},[function(t){t.set("animation",{delay:void 0,duration:1e3,easing:"easeOutQuart",fn:void 0,from:void 0,loop:void 0,to:void 0,type:void 0}),t.describe("animation",{_fallback:!1,_indexable:!1,_scriptable:t=>"onProgress"!==t&&"onComplete"!==t&&"fn"!==t}),t.set("animations",{colors:{type:"color",properties:ie},numbers:{type:"number",properties:ee}}),t.describe("animations",{_fallback:"animation"}),t.set("transitions",{active:{animation:{duration:400}},resize:{animation:{duration:0}},show:{animations:{colors:{from:"transparent"},visible:{type:"boolean",duration:0}}},hide:{animations:{colors:{to:"transparent"},visible:{type:"boolean",easing:"linear",fn:t=>0|t}}}})},function(t){t.set("layout",{autoPadding:!0,padding:{top:0,right:0,bottom:0,left:0}})},function(t){t.set("scale",{display:!0,offset:!1,reverse:!1,beginAtZero:!1,bounds:"ticks",clip:!0,grace:0,grid:{display:!0,lineWidth:1,drawOnChartArea:!0,drawTicks:!0,tickLength:8,tickWidth:(t,e)=>e.lineWidth,tickColor:(t,e)=>e.color,offset:!1},border:{display:!0,dash:[],dashOffset:0,width:1},title:{display:!1,text:"",padding:{top:4,bottom:4}},ticks:{minRotation:0,maxRotation:50,mirror:!1,textStrokeWidth:0,textStrokeColor:"",padding:3,display:!0,autoSkip:!0,autoSkipPadding:3,labelOffset:0,callback:ae.formatters.values,minor:{},major:{},align:"center",crossAlign:"near",showLabelBackdrop:!1,backdropColor:"rgba(255, 255, 255, 0.75)",backdropPadding:2}}),t.route("scale.ticks","color","","color"),t.route("scale.grid","color","","borderColor"),t.route("scale.border","color","","borderColor"),t.route("scale.title","color","","color"),t.describe("scale",{_fallback:!1,_scriptable:t=>!t.startsWith("before")&&!t.startsWith("after")&&"callback"!==t&&"parser"!==t,_indexable:t=>"borderDash"!==t&&"tickBorderDash"!==t&&"dash"!==t}),t.describe("scales",{_fallback:"scale"}),t.describe("scale.ticks",{_scriptable:t=>"backdropPadding"!==t&&"callback"!==t,_indexable:t=>"backdropPadding"!==t})}]);function fe(){return"undefined"!=typeof window&&"undefined"!=typeof document}function ge(t){let e=t.parentNode;return e&&"[object ShadowRoot]"===e.toString()&&(e=e.host),e}function pe(t,e,i){let s;return"string"==typeof t?(s=parseInt(t,10),-1!==t.indexOf("%")&&(s=s/100*e.parentNode[i])):s=t,s}const me=t=>t.ownerDocument.defaultView.getComputedStyle(t,null);function xe(t,e){return me(t).getPropertyValue(e)}const be=["top","right","bottom","left"];function _e(t,e,i){const s={};i=i?"-"+i:"";for(let n=0;n<4;n++){const o=be[n];s[o]=parseFloat(t[e+"-"+o+i])||0}return s.width=s.left+s.right,s.height=s.top+s.bottom,s}const ye=(t,e,i)=>(t>0||e>0)&&(!i||!i.shadowRoot);function ve(t,e){if("native"in t)return t;const{canvas:i,currentDevicePixelRatio:s}=e,n=me(i),o="border-box"===n.boxSizing,a=_e(n,"padding"),r=_e(n,"border","width"),{x:l,y:h,box:c}=function(t,e){const i=t.touches,s=i&&i.length?i[0]:t,{offsetX:n,offsetY:o}=s;let a,r,l=!1;if(ye(n,o,t.target))a=n,r=o;else{const t=e.getBoundingClientRect();a=s.clientX-t.left,r=s.clientY-t.top,l=!0}return{x:a,y:r,box:l}}(t,i),d=a.left+(c&&r.left),u=a.top+(c&&r.top);let{width:f,height:g}=e;return o&&(f-=a.width+r.width,g-=a.height+r.height),{x:Math.round((l-d)/f*i.width/s),y:Math.round((h-u)/g*i.height/s)}}const Me=t=>Math.round(10*t)/10;function we(t,e,i,s){const n=me(t),o=_e(n,"margin"),a=pe(n.maxWidth,t,"clientWidth")||T,r=pe(n.maxHeight,t,"clientHeight")||T,l=function(t,e,i){let s,n;if(void 0===e||void 0===i){const o=t&&ge(t);if(o){const t=o.getBoundingClientRect(),a=me(o),r=_e(a,"border","width"),l=_e(a,"padding");e=t.width-l.width-r.width,i=t.height-l.height-r.height,s=pe(a.maxWidth,o,"clientWidth"),n=pe(a.maxHeight,o,"clientHeight")}else e=t.clientWidth,i=t.clientHeight}return{width:e,height:i,maxWidth:s||T,maxHeight:n||T}}(t,e,i);let{width:h,height:c}=l;if("content-box"===n.boxSizing){const t=_e(n,"border","width"),e=_e(n,"padding");h-=e.width+t.width,c-=e.height+t.height}h=Math.max(0,h-o.width),c=Math.max(0,s?h/s:c-o.height),h=Me(Math.min(h,a,l.maxWidth)),c=Me(Math.min(c,r,l.maxHeight)),h&&!c&&(c=Me(h/2));return(void 0!==e||void 0!==i)&&s&&l.height&&c>l.height&&(c=l.height,h=Me(Math.floor(c*s))),{width:h,height:c}}function ke(t,e,i){const s=e||1,n=Me(t.height*s),o=Me(t.width*s);t.height=Me(t.height),t.width=Me(t.width);const a=t.canvas;return a.style&&(i||!a.style.height&&!a.style.width)&&(a.style.height=`${t.height}px`,a.style.width=`${t.width}px`),(t.currentDevicePixelRatio!==s||a.height!==n||a.width!==o)&&(t.currentDevicePixelRatio=s,a.height=n,a.width=o,t.ctx.setTransform(s,0,0,s,0,0),!0)}const Se=function(){let t=!1;try{const e={get passive(){return t=!0,!1}};fe()&&(window.addEventListener("test",null,e),window.removeEventListener("test",null,e))}catch(t){}return t}();function Pe(t,e){const i=xe(t,e),s=i&&i.match(/^(\d+)(\.\d+)?px$/);return s?+s[1]:void 0}function De(t){return!t||s(t.size)||s(t.family)?null:(t.style?t.style+" ":"")+(t.weight?t.weight+" ":"")+t.size+"px "+t.family}function Ce(t,e,i,s,n){let o=e[n];return o||(o=e[n]=t.measureText(n).width,i.push(n)),o>s&&(s=o),s}function Oe(t,e,i,s){let o=(s=s||{}).data=s.data||{},a=s.garbageCollect=s.garbageCollect||[];s.font!==e&&(o=s.data={},a=s.garbageCollect=[],s.font=e),t.save(),t.font=e;let r=0;const l=i.length;let h,c,d,u,f;for(h=0;hi.length){for(h=0;h0&&t.stroke()}}function Re(t,e,i){return i=i||.5,!e||t&&t.x>e.left-i&&t.xe.top-i&&t.y0&&""!==r.strokeColor;let c,d;for(t.save(),t.font=a.string,function(t,e){e.translation&&t.translate(e.translation[0],e.translation[1]),s(e.rotation)||t.rotate(e.rotation),e.color&&(t.fillStyle=e.color),e.textAlign&&(t.textAlign=e.textAlign),e.textBaseline&&(t.textBaseline=e.textBaseline)}(t,r),c=0;ct[0])){const o=i||t;void 0===s&&(s=ti("_fallback",t));const a={[Symbol.toStringTag]:"Object",_cacheable:!0,_scopes:t,_rootScopes:o,_fallback:s,_getTarget:n,override:i=>je([i,...t],e,o,s)};return new Proxy(a,{deleteProperty:(e,i)=>(delete e[i],delete e._keys,delete t[0][i],!0),get:(i,s)=>qe(i,s,(()=>function(t,e,i,s){let n;for(const o of e)if(n=ti(Ue(o,t),i),void 0!==n)return Xe(t,n)?Ze(i,s,t,n):n}(s,e,t,i))),getOwnPropertyDescriptor:(t,e)=>Reflect.getOwnPropertyDescriptor(t._scopes[0],e),getPrototypeOf:()=>Reflect.getPrototypeOf(t[0]),has:(t,e)=>ei(t).includes(e),ownKeys:t=>ei(t),set(t,e,i){const s=t._storage||(t._storage=n());return t[e]=s[e]=i,delete t._keys,!0}})}function $e(t,e,i,s){const a={_cacheable:!1,_proxy:t,_context:e,_subProxy:i,_stack:new Set,_descriptors:Ye(t,s),setContext:e=>$e(t,e,i,s),override:n=>$e(t.override(n),e,i,s)};return new Proxy(a,{deleteProperty:(e,i)=>(delete e[i],delete t[i],!0),get:(t,e,i)=>qe(t,e,(()=>function(t,e,i){const{_proxy:s,_context:a,_subProxy:r,_descriptors:l}=t;let h=s[e];S(h)&&l.isScriptable(e)&&(h=function(t,e,i,s){const{_proxy:n,_context:o,_subProxy:a,_stack:r}=i;if(r.has(t))throw new Error("Recursion detected: "+Array.from(r).join("->")+"->"+t);r.add(t);let l=e(o,a||s);r.delete(t),Xe(t,l)&&(l=Ze(n._scopes,n,t,l));return l}(e,h,t,i));n(h)&&h.length&&(h=function(t,e,i,s){const{_proxy:n,_context:a,_subProxy:r,_descriptors:l}=i;if(void 0!==a.index&&s(t))return e[a.index%e.length];if(o(e[0])){const i=e,s=n._scopes.filter((t=>t!==i));e=[];for(const o of i){const i=Ze(s,n,t,o);e.push($e(i,a,r&&r[t],l))}}return e}(e,h,t,l.isIndexable));Xe(e,h)&&(h=$e(h,a,r&&r[e],l));return h}(t,e,i))),getOwnPropertyDescriptor:(e,i)=>e._descriptors.allKeys?Reflect.has(t,i)?{enumerable:!0,configurable:!0}:void 0:Reflect.getOwnPropertyDescriptor(t,i),getPrototypeOf:()=>Reflect.getPrototypeOf(t),has:(e,i)=>Reflect.has(t,i),ownKeys:()=>Reflect.ownKeys(t),set:(e,i,s)=>(t[i]=s,delete e[i],!0)})}function Ye(t,e={scriptable:!0,indexable:!0}){const{_scriptable:i=e.scriptable,_indexable:s=e.indexable,_allKeys:n=e.allKeys}=t;return{allKeys:n,scriptable:i,indexable:s,isScriptable:S(i)?i:()=>i,isIndexable:S(s)?s:()=>s}}const Ue=(t,e)=>t?t+w(e):e,Xe=(t,e)=>o(e)&&"adapters"!==t&&(null===Object.getPrototypeOf(e)||e.constructor===Object);function qe(t,e,i){if(Object.prototype.hasOwnProperty.call(t,e)||"constructor"===e)return t[e];const s=i();return t[e]=s,s}function Ke(t,e,i){return S(t)?t(e,i):t}const Ge=(t,e)=>!0===t?e:"string"==typeof t?M(e,t):void 0;function Je(t,e,i,s,n){for(const o of e){const e=Ge(i,o);if(e){t.add(e);const o=Ke(e._fallback,i,n);if(void 0!==o&&o!==i&&o!==s)return o}else if(!1===e&&void 0!==s&&i!==s)return null}return!1}function Ze(t,e,i,s){const a=e._rootScopes,r=Ke(e._fallback,i,s),l=[...t,...a],h=new Set;h.add(s);let c=Qe(h,l,i,r||i,s);return null!==c&&((void 0===r||r===i||(c=Qe(h,l,r,c,s),null!==c))&&je(Array.from(h),[""],a,r,(()=>function(t,e,i){const s=t._getTarget();e in s||(s[e]={});const a=s[e];if(n(a)&&o(i))return i;return a||{}}(e,i,s))))}function Qe(t,e,i,s,n){for(;i;)i=Je(t,e,i,s,n);return i}function ti(t,e){for(const i of e){if(!i)continue;const e=i[t];if(void 0!==e)return e}}function ei(t){let e=t._keys;return e||(e=t._keys=function(t){const e=new Set;for(const i of t)for(const t of Object.keys(i).filter((t=>!t.startsWith("_"))))e.add(t);return Array.from(e)}(t._scopes)),e}function ii(t,e,i,s){const{iScale:n}=t,{key:o="r"}=this._parsing,a=new Array(s);let r,l,h,c;for(r=0,l=s;re"x"===t?"y":"x";function ai(t,e,i,s){const n=t.skip?e:t,o=e,a=i.skip?e:i,r=q(o,n),l=q(a,o);let h=r/(r+l),c=l/(r+l);h=isNaN(h)?0:h,c=isNaN(c)?0:c;const d=s*h,u=s*c;return{previous:{x:o.x-d*(a.x-n.x),y:o.y-d*(a.y-n.y)},next:{x:o.x+u*(a.x-n.x),y:o.y+u*(a.y-n.y)}}}function ri(t,e="x"){const i=oi(e),s=t.length,n=Array(s).fill(0),o=Array(s);let a,r,l,h=ni(t,0);for(a=0;a!t.skip))),"monotone"===e.cubicInterpolationMode)ri(t,n);else{let i=s?t[t.length-1]:t[0];for(o=0,a=t.length;o0===t||1===t,di=(t,e,i)=>-Math.pow(2,10*(t-=1))*Math.sin((t-e)*O/i),ui=(t,e,i)=>Math.pow(2,-10*t)*Math.sin((t-e)*O/i)+1,fi={linear:t=>t,easeInQuad:t=>t*t,easeOutQuad:t=>-t*(t-2),easeInOutQuad:t=>(t/=.5)<1?.5*t*t:-.5*(--t*(t-2)-1),easeInCubic:t=>t*t*t,easeOutCubic:t=>(t-=1)*t*t+1,easeInOutCubic:t=>(t/=.5)<1?.5*t*t*t:.5*((t-=2)*t*t+2),easeInQuart:t=>t*t*t*t,easeOutQuart:t=>-((t-=1)*t*t*t-1),easeInOutQuart:t=>(t/=.5)<1?.5*t*t*t*t:-.5*((t-=2)*t*t*t-2),easeInQuint:t=>t*t*t*t*t,easeOutQuint:t=>(t-=1)*t*t*t*t+1,easeInOutQuint:t=>(t/=.5)<1?.5*t*t*t*t*t:.5*((t-=2)*t*t*t*t+2),easeInSine:t=>1-Math.cos(t*E),easeOutSine:t=>Math.sin(t*E),easeInOutSine:t=>-.5*(Math.cos(C*t)-1),easeInExpo:t=>0===t?0:Math.pow(2,10*(t-1)),easeOutExpo:t=>1===t?1:1-Math.pow(2,-10*t),easeInOutExpo:t=>ci(t)?t:t<.5?.5*Math.pow(2,10*(2*t-1)):.5*(2-Math.pow(2,-10*(2*t-1))),easeInCirc:t=>t>=1?t:-(Math.sqrt(1-t*t)-1),easeOutCirc:t=>Math.sqrt(1-(t-=1)*t),easeInOutCirc:t=>(t/=.5)<1?-.5*(Math.sqrt(1-t*t)-1):.5*(Math.sqrt(1-(t-=2)*t)+1),easeInElastic:t=>ci(t)?t:di(t,.075,.3),easeOutElastic:t=>ci(t)?t:ui(t,.075,.3),easeInOutElastic(t){const e=.1125;return ci(t)?t:t<.5?.5*di(2*t,e,.45):.5+.5*ui(2*t-1,e,.45)},easeInBack(t){const e=1.70158;return t*t*((e+1)*t-e)},easeOutBack(t){const e=1.70158;return(t-=1)*t*((e+1)*t+e)+1},easeInOutBack(t){let e=1.70158;return(t/=.5)<1?t*t*((1+(e*=1.525))*t-e)*.5:.5*((t-=2)*t*((1+(e*=1.525))*t+e)+2)},easeInBounce:t=>1-fi.easeOutBounce(1-t),easeOutBounce(t){const e=7.5625,i=2.75;return t<1/i?e*t*t:t<2/i?e*(t-=1.5/i)*t+.75:t<2.5/i?e*(t-=2.25/i)*t+.9375:e*(t-=2.625/i)*t+.984375},easeInOutBounce:t=>t<.5?.5*fi.easeInBounce(2*t):.5*fi.easeOutBounce(2*t-1)+.5};function gi(t,e,i,s){return{x:t.x+i*(e.x-t.x),y:t.y+i*(e.y-t.y)}}function pi(t,e,i,s){return{x:t.x+i*(e.x-t.x),y:"middle"===s?i<.5?t.y:e.y:"after"===s?i<1?t.y:e.y:i>0?e.y:t.y}}function mi(t,e,i,s){const n={x:t.cp2x,y:t.cp2y},o={x:e.cp1x,y:e.cp1y},a=gi(t,n,i),r=gi(n,o,i),l=gi(o,e,i),h=gi(a,r,i),c=gi(r,l,i);return gi(h,c,i)}const xi=/^(normal|(\d+(?:\.\d+)?)(px|em|%)?)$/,bi=/^(normal|italic|initial|inherit|unset|(oblique( -?[0-9]?[0-9]deg)?))$/;function _i(t,e){const i=(""+t).match(xi);if(!i||"normal"===i[1])return 1.2*e;switch(t=+i[2],i[3]){case"px":return t;case"%":t/=100}return e*t}const yi=t=>+t||0;function vi(t,e){const i={},s=o(e),n=s?Object.keys(e):e,a=o(t)?s?i=>l(t[i],t[e[i]]):e=>t[e]:()=>t;for(const t of n)i[t]=yi(a(t));return i}function Mi(t){return vi(t,{top:"y",right:"x",bottom:"y",left:"x"})}function wi(t){return vi(t,["topLeft","topRight","bottomLeft","bottomRight"])}function ki(t){const e=Mi(t);return e.width=e.left+e.right,e.height=e.top+e.bottom,e}function Si(t,e){t=t||{},e=e||ue.font;let i=l(t.size,e.size);"string"==typeof i&&(i=parseInt(i,10));let s=l(t.style,e.style);s&&!(""+s).match(bi)&&(console.warn('Invalid font style specified: "'+s+'"'),s=void 0);const n={family:l(t.family,e.family),lineHeight:_i(l(t.lineHeight,e.lineHeight),i),size:i,style:s,weight:l(t.weight,e.weight),string:""};return n.string=De(n),n}function Pi(t,e,i,s){let o,a,r,l=!0;for(o=0,a=t.length;oi&&0===t?0:t+e;return{min:a(s,-Math.abs(o)),max:a(n,o)}}function Ci(t,e){return Object.assign(Object.create(t),e)}function Oi(t,e,i){return t?function(t,e){return{x:i=>t+t+e-i,setWidth(t){e=t},textAlign:t=>"center"===t?t:"right"===t?"left":"right",xPlus:(t,e)=>t-e,leftForLtr:(t,e)=>t-e}}(e,i):{x:t=>t,setWidth(t){},textAlign:t=>t,xPlus:(t,e)=>t+e,leftForLtr:(t,e)=>t}}function Ai(t,e){let i,s;"ltr"!==e&&"rtl"!==e||(i=t.canvas.style,s=[i.getPropertyValue("direction"),i.getPropertyPriority("direction")],i.setProperty("direction",e,"important"),t.prevTextDirection=s)}function Ti(t,e){void 0!==e&&(delete t.prevTextDirection,t.canvas.style.setProperty("direction",e[0],e[1]))}function Li(t){return"angle"===t?{between:J,compare:K,normalize:G}:{between:tt,compare:(t,e)=>t-e,normalize:t=>t}}function Ei({start:t,end:e,count:i,loop:s,style:n}){return{start:t%i,end:e%i,loop:s&&(e-t+1)%i==0,style:n}}function Ri(t,e,i){if(!i)return[t];const{property:s,start:n,end:o}=i,a=e.length,{compare:r,between:l,normalize:h}=Li(s),{start:c,end:d,loop:u,style:f}=function(t,e,i){const{property:s,start:n,end:o}=i,{between:a,normalize:r}=Li(s),l=e.length;let h,c,{start:d,end:u,loop:f}=t;if(f){for(d+=l,u+=l,h=0,c=l;hb||l(n,x,p)&&0!==r(n,x),v=()=>!b||0===r(o,p)||l(o,x,p);for(let t=c,i=c;t<=d;++t)m=e[t%a],m.skip||(p=h(m[s]),p!==x&&(b=l(p,n,o),null===_&&y()&&(_=0===r(p,n)?t:i),null!==_&&v()&&(g.push(Ei({start:_,end:t,loop:u,count:a,style:f})),_=null),i=t,x=p));return null!==_&&g.push(Ei({start:_,end:d,loop:u,count:a,style:f})),g}function Ii(t,e){const i=[],s=t.segments;for(let n=0;nn&&t[o%e].skip;)o--;return o%=e,{start:n,end:o}}(i,n,o,s);if(!0===s)return Fi(t,[{start:a,end:r,loop:o}],i,e);return Fi(t,function(t,e,i,s){const n=t.length,o=[];let a,r=e,l=t[e];for(a=e+1;a<=i;++a){const i=t[a%n];i.skip||i.stop?l.skip||(s=!1,o.push({start:e%n,end:(a-1)%n,loop:s}),e=r=i.stop?a:null):(r=a,l.skip&&(e=a)),l=i}return null!==r&&o.push({start:e%n,end:r%n,loop:s}),o}(i,a,r!s(t[e.axis])));n.lo-=Math.max(0,a);const r=i.slice(n.hi).findIndex((t=>!s(t[e.axis])));n.hi+=Math.max(0,r)}return n}if(o._sharedOptions){const t=a[0],s="function"==typeof t.getRange&&t.getRange(e);if(s){const t=r(a,e,i-s),n=r(a,e,i+s);return{lo:t.lo,hi:n.hi}}}}return{lo:0,hi:a.length-1}}function $i(t,e,i,s,n){const o=t.getSortedVisibleDatasetMetas(),a=i[e];for(let t=0,i=o.length;t{t[a]&&t[a](e[i],n)&&(o.push({element:t,datasetIndex:s,index:l}),r=r||t.inRange(e.x,e.y,n))})),s&&!r?[]:o}var Ki={evaluateInteractionItems:$i,modes:{index(t,e,i,s){const n=ve(e,t),o=i.axis||"x",a=i.includeInvisible||!1,r=i.intersect?Yi(t,n,o,s,a):Xi(t,n,o,!1,s,a),l=[];return r.length?(t.getSortedVisibleDatasetMetas().forEach((t=>{const e=r[0].index,i=t.data[e];i&&!i.skip&&l.push({element:i,datasetIndex:t.index,index:e})})),l):[]},dataset(t,e,i,s){const n=ve(e,t),o=i.axis||"xy",a=i.includeInvisible||!1;let r=i.intersect?Yi(t,n,o,s,a):Xi(t,n,o,!1,s,a);if(r.length>0){const e=r[0].datasetIndex,i=t.getDatasetMeta(e).data;r=[];for(let t=0;tYi(t,ve(e,t),i.axis||"xy",s,i.includeInvisible||!1),nearest(t,e,i,s){const n=ve(e,t),o=i.axis||"xy",a=i.includeInvisible||!1;return Xi(t,n,o,i.intersect,s,a)},x:(t,e,i,s)=>qi(t,ve(e,t),"x",i.intersect,s),y:(t,e,i,s)=>qi(t,ve(e,t),"y",i.intersect,s)}};const Gi=["left","top","right","bottom"];function Ji(t,e){return t.filter((t=>t.pos===e))}function Zi(t,e){return t.filter((t=>-1===Gi.indexOf(t.pos)&&t.box.axis===e))}function Qi(t,e){return t.sort(((t,i)=>{const s=e?i:t,n=e?t:i;return s.weight===n.weight?s.index-n.index:s.weight-n.weight}))}function ts(t,e){const i=function(t){const e={};for(const i of t){const{stack:t,pos:s,stackWeight:n}=i;if(!t||!Gi.includes(s))continue;const o=e[t]||(e[t]={count:0,placed:0,weight:0,size:0});o.count++,o.weight+=n}return e}(t),{vBoxMaxWidth:s,hBoxMaxHeight:n}=e;let o,a,r;for(o=0,a=t.length;o{s[t]=Math.max(e[t],i[t])})),s}return s(t?["left","right"]:["top","bottom"])}function os(t,e,i,s){const n=[];let o,a,r,l,h,c;for(o=0,a=t.length,h=0;ot.box.fullSize)),!0),s=Qi(Ji(e,"left"),!0),n=Qi(Ji(e,"right")),o=Qi(Ji(e,"top"),!0),a=Qi(Ji(e,"bottom")),r=Zi(e,"x"),l=Zi(e,"y");return{fullSize:i,leftAndTop:s.concat(o),rightAndBottom:n.concat(l).concat(a).concat(r),chartArea:Ji(e,"chartArea"),vertical:s.concat(n).concat(l),horizontal:o.concat(a).concat(r)}}(t.boxes),l=r.vertical,h=r.horizontal;u(t.boxes,(t=>{"function"==typeof t.beforeLayout&&t.beforeLayout()}));const c=l.reduce(((t,e)=>e.box.options&&!1===e.box.options.display?t:t+1),0)||1,d=Object.freeze({outerWidth:e,outerHeight:i,padding:n,availableWidth:o,availableHeight:a,vBoxMaxWidth:o/2/c,hBoxMaxHeight:a/2}),f=Object.assign({},n);is(f,ki(s));const g=Object.assign({maxPadding:f,w:o,h:a,x:n.left,y:n.top},n),p=ts(l.concat(h),d);os(r.fullSize,g,d,p),os(l,g,d,p),os(h,g,d,p)&&os(l,g,d,p),function(t){const e=t.maxPadding;function i(i){const s=Math.max(e[i]-t[i],0);return t[i]+=s,s}t.y+=i("top"),t.x+=i("left"),i("right"),i("bottom")}(g),rs(r.leftAndTop,g,d,p),g.x+=g.w,g.y+=g.h,rs(r.rightAndBottom,g,d,p),t.chartArea={left:g.left,top:g.top,right:g.left+g.w,bottom:g.top+g.h,height:g.h,width:g.w},u(r.chartArea,(e=>{const i=e.box;Object.assign(i,t.chartArea),i.update(g.w,g.h,{left:0,top:0,right:0,bottom:0})}))}};class hs{acquireContext(t,e){}releaseContext(t){return!1}addEventListener(t,e,i){}removeEventListener(t,e,i){}getDevicePixelRatio(){return 1}getMaximumSize(t,e,i,s){return e=Math.max(0,e||t.width),i=i||t.height,{width:e,height:Math.max(0,s?Math.floor(e/s):i)}}isAttached(t){return!0}updateConfig(t){}}class cs extends hs{acquireContext(t){return t&&t.getContext&&t.getContext("2d")||null}updateConfig(t){t.options.animation=!1}}const ds="$chartjs",us={touchstart:"mousedown",touchmove:"mousemove",touchend:"mouseup",pointerenter:"mouseenter",pointerdown:"mousedown",pointermove:"mousemove",pointerup:"mouseup",pointerleave:"mouseout",pointerout:"mouseout"},fs=t=>null===t||""===t;const gs=!!Se&&{passive:!0};function ps(t,e,i){t&&t.canvas&&t.canvas.removeEventListener(e,i,gs)}function ms(t,e){for(const i of t)if(i===e||i.contains(e))return!0}function xs(t,e,i){const s=t.canvas,n=new MutationObserver((t=>{let e=!1;for(const i of t)e=e||ms(i.addedNodes,s),e=e&&!ms(i.removedNodes,s);e&&i()}));return n.observe(document,{childList:!0,subtree:!0}),n}function bs(t,e,i){const s=t.canvas,n=new MutationObserver((t=>{let e=!1;for(const i of t)e=e||ms(i.removedNodes,s),e=e&&!ms(i.addedNodes,s);e&&i()}));return n.observe(document,{childList:!0,subtree:!0}),n}const _s=new Map;let ys=0;function vs(){const t=window.devicePixelRatio;t!==ys&&(ys=t,_s.forEach(((e,i)=>{i.currentDevicePixelRatio!==t&&e()})))}function Ms(t,e,i){const s=t.canvas,n=s&&ge(s);if(!n)return;const o=ct(((t,e)=>{const s=n.clientWidth;i(t,e),s{const e=t[0],i=e.contentRect.width,s=e.contentRect.height;0===i&&0===s||o(i,s)}));return a.observe(n),function(t,e){_s.size||window.addEventListener("resize",vs),_s.set(t,e)}(t,o),a}function ws(t,e,i){i&&i.disconnect(),"resize"===e&&function(t){_s.delete(t),_s.size||window.removeEventListener("resize",vs)}(t)}function ks(t,e,i){const s=t.canvas,n=ct((e=>{null!==t.ctx&&i(function(t,e){const i=us[t.type]||t.type,{x:s,y:n}=ve(t,e);return{type:i,chart:e,native:t,x:void 0!==s?s:null,y:void 0!==n?n:null}}(e,t))}),t);return function(t,e,i){t&&t.addEventListener(e,i,gs)}(s,e,n),n}class Ss extends hs{acquireContext(t,e){const i=t&&t.getContext&&t.getContext("2d");return i&&i.canvas===t?(function(t,e){const i=t.style,s=t.getAttribute("height"),n=t.getAttribute("width");if(t[ds]={initial:{height:s,width:n,style:{display:i.display,height:i.height,width:i.width}}},i.display=i.display||"block",i.boxSizing=i.boxSizing||"border-box",fs(n)){const e=Pe(t,"width");void 0!==e&&(t.width=e)}if(fs(s))if(""===t.style.height)t.height=t.width/(e||2);else{const e=Pe(t,"height");void 0!==e&&(t.height=e)}}(t,e),i):null}releaseContext(t){const e=t.canvas;if(!e[ds])return!1;const i=e[ds].initial;["height","width"].forEach((t=>{const n=i[t];s(n)?e.removeAttribute(t):e.setAttribute(t,n)}));const n=i.style||{};return Object.keys(n).forEach((t=>{e.style[t]=n[t]})),e.width=e.width,delete e[ds],!0}addEventListener(t,e,i){this.removeEventListener(t,e);const s=t.$proxies||(t.$proxies={}),n={attach:xs,detach:bs,resize:Ms}[e]||ks;s[e]=n(t,e,i)}removeEventListener(t,e){const i=t.$proxies||(t.$proxies={}),s=i[e];if(!s)return;({attach:ws,detach:ws,resize:ws}[e]||ps)(t,e,s),i[e]=void 0}getDevicePixelRatio(){return window.devicePixelRatio}getMaximumSize(t,e,i,s){return we(t,e,i,s)}isAttached(t){const e=t&&ge(t);return!(!e||!e.isConnected)}}function Ps(t){return!fe()||"undefined"!=typeof OffscreenCanvas&&t instanceof OffscreenCanvas?cs:Ss}var Ds=Object.freeze({__proto__:null,BasePlatform:hs,BasicPlatform:cs,DomPlatform:Ss,_detectPlatform:Ps});const Cs="transparent",Os={boolean:(t,e,i)=>i>.5?e:t,color(t,e,i){const s=Qt(t||Cs),n=s.valid&&Qt(e||Cs);return n&&n.valid?n.mix(s,i).hexString():e},number:(t,e,i)=>t+(e-t)*i};class As{constructor(t,e,i,s){const n=e[i];s=Pi([t.to,s,n,t.from]);const o=Pi([t.from,n,s]);this._active=!0,this._fn=t.fn||Os[t.type||typeof o],this._easing=fi[t.easing]||fi.linear,this._start=Math.floor(Date.now()+(t.delay||0)),this._duration=this._total=Math.floor(t.duration),this._loop=!!t.loop,this._target=e,this._prop=i,this._from=o,this._to=s,this._promises=void 0}active(){return this._active}update(t,e,i){if(this._active){this._notify(!1);const s=this._target[this._prop],n=i-this._start,o=this._duration-n;this._start=i,this._duration=Math.floor(Math.max(o,t.duration)),this._total+=n,this._loop=!!t.loop,this._to=Pi([t.to,e,s,t.from]),this._from=Pi([t.from,s,e])}}cancel(){this._active&&(this.tick(Date.now()),this._active=!1,this._notify(!1))}tick(t){const e=t-this._start,i=this._duration,s=this._prop,n=this._from,o=this._loop,a=this._to;let r;if(this._active=n!==a&&(o||e1?2-r:r,r=this._easing(Math.min(1,Math.max(0,r))),this._target[s]=this._fn(n,a,r))}wait(){const t=this._promises||(this._promises=[]);return new Promise(((e,i)=>{t.push({res:e,rej:i})}))}_notify(t){const e=t?"res":"rej",i=this._promises||[];for(let t=0;t{const a=t[s];if(!o(a))return;const r={};for(const t of e)r[t]=a[t];(n(a.properties)&&a.properties||[s]).forEach((t=>{t!==s&&i.has(t)||i.set(t,r)}))}))}_animateOptions(t,e){const i=e.options,s=function(t,e){if(!e)return;let i=t.options;if(!i)return void(t.options=e);i.$shared&&(t.options=i=Object.assign({},i,{$shared:!1,$animations:{}}));return i}(t,i);if(!s)return[];const n=this._createAnimations(s,i);return i.$shared&&function(t,e){const i=[],s=Object.keys(e);for(let e=0;e{t.options=i}),(()=>{})),n}_createAnimations(t,e){const i=this._properties,s=[],n=t.$animations||(t.$animations={}),o=Object.keys(e),a=Date.now();let r;for(r=o.length-1;r>=0;--r){const l=o[r];if("$"===l.charAt(0))continue;if("options"===l){s.push(...this._animateOptions(t,e));continue}const h=e[l];let c=n[l];const d=i.get(l);if(c){if(d&&c.active()){c.update(d,h,a);continue}c.cancel()}d&&d.duration?(n[l]=c=new As(d,t,l,h),s.push(c)):t[l]=h}return s}update(t,e){if(0===this._properties.size)return void Object.assign(t,e);const i=this._createAnimations(t,e);return i.length?(bt.add(this._chart,i),!0):void 0}}function Ls(t,e){const i=t&&t.options||{},s=i.reverse,n=void 0===i.min?e:0,o=void 0===i.max?e:0;return{start:s?o:n,end:s?n:o}}function Es(t,e){const i=[],s=t._getSortedDatasetMetas(e);let n,o;for(n=0,o=s.length;n0||!i&&e<0)return n.index}return null}function Vs(t,e){const{chart:i,_cachedMeta:s}=t,n=i._stacks||(i._stacks={}),{iScale:o,vScale:a,index:r}=s,l=o.axis,h=a.axis,c=function(t,e,i){return`${t.id}.${e.id}.${i.stack||i.type}`}(o,a,s),d=e.length;let u;for(let t=0;ti[t].axis===e)).shift()}function Ws(t,e){const i=t.controller.index,s=t.vScale&&t.vScale.axis;if(s){e=e||t._parsed;for(const t of e){const e=t._stacks;if(!e||void 0===e[s]||void 0===e[s][i])return;delete e[s][i],void 0!==e[s]._visualValues&&void 0!==e[s]._visualValues[i]&&delete e[s]._visualValues[i]}}}const Ns=t=>"reset"===t||"none"===t,Hs=(t,e)=>e?t:Object.assign({},t);class js{static defaults={};static datasetElementType=null;static dataElementType=null;constructor(t,e){this.chart=t,this._ctx=t.ctx,this.index=e,this._cachedDataOpts={},this._cachedMeta=this.getMeta(),this._type=this._cachedMeta.type,this.options=void 0,this._parsing=!1,this._data=void 0,this._objectData=void 0,this._sharedOptions=void 0,this._drawStart=void 0,this._drawCount=void 0,this.enableOptionSharing=!1,this.supportsDecimation=!1,this.$context=void 0,this._syncList=[],this.datasetElementType=new.target.datasetElementType,this.dataElementType=new.target.dataElementType,this.initialize()}initialize(){const t=this._cachedMeta;this.configure(),this.linkScales(),t._stacked=Is(t.vScale,t),this.addElements(),this.options.fill&&!this.chart.isPluginEnabled("filler")&&console.warn("Tried to use the 'fill' option without the 'Filler' plugin enabled. Please import and register the 'Filler' plugin and make sure it is not disabled in the options")}updateIndex(t){this.index!==t&&Ws(this._cachedMeta),this.index=t}linkScales(){const t=this.chart,e=this._cachedMeta,i=this.getDataset(),s=(t,e,i,s)=>"x"===t?e:"r"===t?s:i,n=e.xAxisID=l(i.xAxisID,Bs(t,"x")),o=e.yAxisID=l(i.yAxisID,Bs(t,"y")),a=e.rAxisID=l(i.rAxisID,Bs(t,"r")),r=e.indexAxis,h=e.iAxisID=s(r,n,o,a),c=e.vAxisID=s(r,o,n,a);e.xScale=this.getScaleForId(n),e.yScale=this.getScaleForId(o),e.rScale=this.getScaleForId(a),e.iScale=this.getScaleForId(h),e.vScale=this.getScaleForId(c)}getDataset(){return this.chart.data.datasets[this.index]}getMeta(){return this.chart.getDatasetMeta(this.index)}getScaleForId(t){return this.chart.scales[t]}_getOtherScale(t){const e=this._cachedMeta;return t===e.iScale?e.vScale:e.iScale}reset(){this._update("reset")}_destroy(){const t=this._cachedMeta;this._data&&rt(this._data,this),t._stacked&&Ws(t)}_dataCheck(){const t=this.getDataset(),e=t.data||(t.data=[]),i=this._data;if(o(e)){const t=this._cachedMeta;this._data=function(t,e){const{iScale:i,vScale:s}=e,n="x"===i.axis?"x":"y",o="x"===s.axis?"x":"y",a=Object.keys(t),r=new Array(a.length);let l,h,c;for(l=0,h=a.length;l0&&i._parsed[t-1];if(!1===this._parsing)i._parsed=s,i._sorted=!0,d=s;else{d=n(s[t])?this.parseArrayData(i,s,t,e):o(s[t])?this.parseObjectData(i,s,t,e):this.parsePrimitiveData(i,s,t,e);const a=()=>null===c[l]||f&&c[l]t&&!e.hidden&&e._stacked&&{keys:Es(i,!0),values:null})(e,i,this.chart),h={min:Number.POSITIVE_INFINITY,max:Number.NEGATIVE_INFINITY},{min:c,max:d}=function(t){const{min:e,max:i,minDefined:s,maxDefined:n}=t.getUserBounds();return{min:s?e:Number.NEGATIVE_INFINITY,max:n?i:Number.POSITIVE_INFINITY}}(r);let u,f;function g(){f=s[u];const e=f[r.axis];return!a(f[t.axis])||c>e||d=0;--u)if(!g()){this.updateRangeFromParsed(h,t,f,l);break}return h}getAllParsedValues(t){const e=this._cachedMeta._parsed,i=[];let s,n,o;for(s=0,n=e.length;s=0&&tthis.getContext(i,s,e)),c);return f.$shared&&(f.$shared=r,n[o]=Object.freeze(Hs(f,r))),f}_resolveAnimations(t,e,i){const s=this.chart,n=this._cachedDataOpts,o=`animation-${e}`,a=n[o];if(a)return a;let r;if(!1!==s.options.animation){const s=this.chart.config,n=s.datasetAnimationScopeKeys(this._type,e),o=s.getOptionScopes(this.getDataset(),n);r=s.createResolver(o,this.getContext(t,i,e))}const l=new Ts(s,r&&r.animations);return r&&r._cacheable&&(n[o]=Object.freeze(l)),l}getSharedOptions(t){if(t.$shared)return this._sharedOptions||(this._sharedOptions=Object.assign({},t))}includeOptions(t,e){return!e||Ns(t)||this.chart._animationsDisabled}_getSharedOptions(t,e){const i=this.resolveDataElementOptions(t,e),s=this._sharedOptions,n=this.getSharedOptions(i),o=this.includeOptions(e,n)||n!==s;return this.updateSharedOptions(n,e,i),{sharedOptions:n,includeOptions:o}}updateElement(t,e,i,s){Ns(s)?Object.assign(t,i):this._resolveAnimations(e,s).update(t,i)}updateSharedOptions(t,e,i){t&&!Ns(e)&&this._resolveAnimations(void 0,e).update(t,i)}_setStyle(t,e,i,s){t.active=s;const n=this.getStyle(e,s);this._resolveAnimations(e,i,s).update(t,{options:!s&&this.getSharedOptions(n)||n})}removeHoverStyle(t,e,i){this._setStyle(t,i,"active",!1)}setHoverStyle(t,e,i){this._setStyle(t,i,"active",!0)}_removeDatasetHoverStyle(){const t=this._cachedMeta.dataset;t&&this._setStyle(t,void 0,"active",!1)}_setDatasetHoverStyle(){const t=this._cachedMeta.dataset;t&&this._setStyle(t,void 0,"active",!0)}_resyncElements(t){const e=this._data,i=this._cachedMeta.data;for(const[t,e,i]of this._syncList)this[t](e,i);this._syncList=[];const s=i.length,n=e.length,o=Math.min(n,s);o&&this.parse(0,o),n>s?this._insertElements(s,n-s,t):n{for(t.length+=e,a=t.length-1;a>=o;a--)t[a]=t[a-e]};for(r(n),a=t;a{s[t]=i[t]&&i[t].active()?i[t]._to:this[t]})),s}}function Ys(t,e){const i=t.options.ticks,n=function(t){const e=t.options.offset,i=t._tickSize(),s=t._length/i+(e?0:1),n=t._maxLength/i;return Math.floor(Math.min(s,n))}(t),o=Math.min(i.maxTicksLimit||n,n),a=i.major.enabled?function(t){const e=[];let i,s;for(i=0,s=t.length;io)return function(t,e,i,s){let n,o=0,a=i[0];for(s=Math.ceil(s),n=0;nn)return e}return Math.max(n,1)}(a,e,o);if(r>0){let t,i;const n=r>1?Math.round((h-l)/(r-1)):null;for(Us(e,c,d,s(n)?0:l-n,l),t=0,i=r-1;t"top"===e||"left"===e?t[e]+i:t[e]-i,qs=(t,e)=>Math.min(e||t,t);function Ks(t,e){const i=[],s=t.length/e,n=t.length;let o=0;for(;oa+r)))return h}function Js(t){return t.drawTicks?t.tickLength:0}function Zs(t,e){if(!t.display)return 0;const i=Si(t.font,e),s=ki(t.padding);return(n(t.text)?t.text.length:1)*i.lineHeight+s.height}function Qs(t,e,i){let s=ut(t);return(i&&"right"!==e||!i&&"right"===e)&&(s=(t=>"left"===t?"right":"right"===t?"left":t)(s)),s}class tn extends $s{constructor(t){super(),this.id=t.id,this.type=t.type,this.options=void 0,this.ctx=t.ctx,this.chart=t.chart,this.top=void 0,this.bottom=void 0,this.left=void 0,this.right=void 0,this.width=void 0,this.height=void 0,this._margins={left:0,right:0,top:0,bottom:0},this.maxWidth=void 0,this.maxHeight=void 0,this.paddingTop=void 0,this.paddingBottom=void 0,this.paddingLeft=void 0,this.paddingRight=void 0,this.axis=void 0,this.labelRotation=void 0,this.min=void 0,this.max=void 0,this._range=void 0,this.ticks=[],this._gridLineItems=null,this._labelItems=null,this._labelSizes=null,this._length=0,this._maxLength=0,this._longestTextCache={},this._startPixel=void 0,this._endPixel=void 0,this._reversePixels=!1,this._userMax=void 0,this._userMin=void 0,this._suggestedMax=void 0,this._suggestedMin=void 0,this._ticksLength=0,this._borderValue=0,this._cache={},this._dataLimitsCached=!1,this.$context=void 0}init(t){this.options=t.setContext(this.getContext()),this.axis=t.axis,this._userMin=this.parse(t.min),this._userMax=this.parse(t.max),this._suggestedMin=this.parse(t.suggestedMin),this._suggestedMax=this.parse(t.suggestedMax)}parse(t,e){return t}getUserBounds(){let{_userMin:t,_userMax:e,_suggestedMin:i,_suggestedMax:s}=this;return t=r(t,Number.POSITIVE_INFINITY),e=r(e,Number.NEGATIVE_INFINITY),i=r(i,Number.POSITIVE_INFINITY),s=r(s,Number.NEGATIVE_INFINITY),{min:r(t,i),max:r(e,s),minDefined:a(t),maxDefined:a(e)}}getMinMax(t){let e,{min:i,max:s,minDefined:n,maxDefined:o}=this.getUserBounds();if(n&&o)return{min:i,max:s};const a=this.getMatchingVisibleMetas();for(let r=0,l=a.length;rs?s:i,s=n&&i>s?i:s,{min:r(i,r(s,i)),max:r(s,r(i,s))}}getPadding(){return{left:this.paddingLeft||0,top:this.paddingTop||0,right:this.paddingRight||0,bottom:this.paddingBottom||0}}getTicks(){return this.ticks}getLabels(){const t=this.chart.data;return this.options.labels||(this.isHorizontal()?t.xLabels:t.yLabels)||t.labels||[]}getLabelItems(t=this.chart.chartArea){return this._labelItems||(this._labelItems=this._computeLabelItems(t))}beforeLayout(){this._cache={},this._dataLimitsCached=!1}beforeUpdate(){d(this.options.beforeUpdate,[this])}update(t,e,i){const{beginAtZero:s,grace:n,ticks:o}=this.options,a=o.sampleSize;this.beforeUpdate(),this.maxWidth=t,this.maxHeight=e,this._margins=i=Object.assign({left:0,right:0,top:0,bottom:0},i),this.ticks=null,this._labelSizes=null,this._gridLineItems=null,this._labelItems=null,this.beforeSetDimensions(),this.setDimensions(),this.afterSetDimensions(),this._maxLength=this.isHorizontal()?this.width+i.left+i.right:this.height+i.top+i.bottom,this._dataLimitsCached||(this.beforeDataLimits(),this.determineDataLimits(),this.afterDataLimits(),this._range=Di(this,n,s),this._dataLimitsCached=!0),this.beforeBuildTicks(),this.ticks=this.buildTicks()||[],this.afterBuildTicks();const r=a=n||i<=1||!this.isHorizontal())return void(this.labelRotation=s);const h=this._getLabelSizes(),c=h.widest.width,d=h.highest.height,u=Z(this.chart.width-c,0,this.maxWidth);o=t.offset?this.maxWidth/i:u/(i-1),c+6>o&&(o=u/(i-(t.offset?.5:1)),a=this.maxHeight-Js(t.grid)-e.padding-Zs(t.title,this.chart.options.font),r=Math.sqrt(c*c+d*d),l=Y(Math.min(Math.asin(Z((h.highest.height+6)/o,-1,1)),Math.asin(Z(a/r,-1,1))-Math.asin(Z(d/r,-1,1)))),l=Math.max(s,Math.min(n,l))),this.labelRotation=l}afterCalculateLabelRotation(){d(this.options.afterCalculateLabelRotation,[this])}afterAutoSkip(){}beforeFit(){d(this.options.beforeFit,[this])}fit(){const t={width:0,height:0},{chart:e,options:{ticks:i,title:s,grid:n}}=this,o=this._isVisible(),a=this.isHorizontal();if(o){const o=Zs(s,e.options.font);if(a?(t.width=this.maxWidth,t.height=Js(n)+o):(t.height=this.maxHeight,t.width=Js(n)+o),i.display&&this.ticks.length){const{first:e,last:s,widest:n,highest:o}=this._getLabelSizes(),r=2*i.padding,l=$(this.labelRotation),h=Math.cos(l),c=Math.sin(l);if(a){const e=i.mirror?0:c*n.width+h*o.height;t.height=Math.min(this.maxHeight,t.height+e+r)}else{const e=i.mirror?0:h*n.width+c*o.height;t.width=Math.min(this.maxWidth,t.width+e+r)}this._calculatePadding(e,s,c,h)}}this._handleMargins(),a?(this.width=this._length=e.width-this._margins.left-this._margins.right,this.height=t.height):(this.width=t.width,this.height=this._length=e.height-this._margins.top-this._margins.bottom)}_calculatePadding(t,e,i,s){const{ticks:{align:n,padding:o},position:a}=this.options,r=0!==this.labelRotation,l="top"!==a&&"x"===this.axis;if(this.isHorizontal()){const a=this.getPixelForTick(0)-this.left,h=this.right-this.getPixelForTick(this.ticks.length-1);let c=0,d=0;r?l?(c=s*t.width,d=i*e.height):(c=i*t.height,d=s*e.width):"start"===n?d=e.width:"end"===n?c=t.width:"inner"!==n&&(c=t.width/2,d=e.width/2),this.paddingLeft=Math.max((c-a+o)*this.width/(this.width-a),0),this.paddingRight=Math.max((d-h+o)*this.width/(this.width-h),0)}else{let i=e.height/2,s=t.height/2;"start"===n?(i=0,s=t.height):"end"===n&&(i=e.height,s=0),this.paddingTop=i+o,this.paddingBottom=s+o}}_handleMargins(){this._margins&&(this._margins.left=Math.max(this.paddingLeft,this._margins.left),this._margins.top=Math.max(this.paddingTop,this._margins.top),this._margins.right=Math.max(this.paddingRight,this._margins.right),this._margins.bottom=Math.max(this.paddingBottom,this._margins.bottom))}afterFit(){d(this.options.afterFit,[this])}isHorizontal(){const{axis:t,position:e}=this.options;return"top"===e||"bottom"===e||"x"===t}isFullSize(){return this.options.fullSize}_convertTicksToLabels(t){let e,i;for(this.beforeTickToLabelConversion(),this.generateTickLabels(t),e=0,i=t.length;e{const i=t.gc,s=i.length/2;let n;if(s>e){for(n=0;n({width:r[t]||0,height:l[t]||0});return{first:P(0),last:P(e-1),widest:P(k),highest:P(S),widths:r,heights:l}}getLabelForValue(t){return t}getPixelForValue(t,e){return NaN}getValueForPixel(t){}getPixelForTick(t){const e=this.ticks;return t<0||t>e.length-1?null:this.getPixelForValue(e[t].value)}getPixelForDecimal(t){this._reversePixels&&(t=1-t);const e=this._startPixel+t*this._length;return Q(this._alignToPixels?Ae(this.chart,e,0):e)}getDecimalForPixel(t){const e=(t-this._startPixel)/this._length;return this._reversePixels?1-e:e}getBasePixel(){return this.getPixelForValue(this.getBaseValue())}getBaseValue(){const{min:t,max:e}=this;return t<0&&e<0?e:t>0&&e>0?t:0}getContext(t){const e=this.ticks||[];if(t>=0&&ta*s?a/i:r/s:r*s0}_computeGridLineItems(t){const e=this.axis,i=this.chart,s=this.options,{grid:n,position:a,border:r}=s,h=n.offset,c=this.isHorizontal(),d=this.ticks.length+(h?1:0),u=Js(n),f=[],g=r.setContext(this.getContext()),p=g.display?g.width:0,m=p/2,x=function(t){return Ae(i,t,p)};let b,_,y,v,M,w,k,S,P,D,C,O;if("top"===a)b=x(this.bottom),w=this.bottom-u,S=b-m,D=x(t.top)+m,O=t.bottom;else if("bottom"===a)b=x(this.top),D=t.top,O=x(t.bottom)-m,w=b+m,S=this.top+u;else if("left"===a)b=x(this.right),M=this.right-u,k=b-m,P=x(t.left)+m,C=t.right;else if("right"===a)b=x(this.left),P=t.left,C=x(t.right)-m,M=b+m,k=this.left+u;else if("x"===e){if("center"===a)b=x((t.top+t.bottom)/2+.5);else if(o(a)){const t=Object.keys(a)[0],e=a[t];b=x(this.chart.scales[t].getPixelForValue(e))}D=t.top,O=t.bottom,w=b+m,S=w+u}else if("y"===e){if("center"===a)b=x((t.left+t.right)/2);else if(o(a)){const t=Object.keys(a)[0],e=a[t];b=x(this.chart.scales[t].getPixelForValue(e))}M=b-m,k=M-u,P=t.left,C=t.right}const A=l(s.ticks.maxTicksLimit,d),T=Math.max(1,Math.ceil(d/A));for(_=0;_0&&(o-=s/2)}d={left:o,top:n,width:s+e.width,height:i+e.height,color:t.backdropColor}}x.push({label:v,font:P,textOffset:O,options:{rotation:m,color:i,strokeColor:o,strokeWidth:h,textAlign:f,textBaseline:A,translation:[M,w],backdrop:d}})}return x}_getXAxisLabelAlignment(){const{position:t,ticks:e}=this.options;if(-$(this.labelRotation))return"top"===t?"left":"right";let i="center";return"start"===e.align?i="left":"end"===e.align?i="right":"inner"===e.align&&(i="inner"),i}_getYAxisLabelAlignment(t){const{position:e,ticks:{crossAlign:i,mirror:s,padding:n}}=this.options,o=t+n,a=this._getLabelSizes().widest.width;let r,l;return"left"===e?s?(l=this.right+n,"near"===i?r="left":"center"===i?(r="center",l+=a/2):(r="right",l+=a)):(l=this.right-o,"near"===i?r="right":"center"===i?(r="center",l-=a/2):(r="left",l=this.left)):"right"===e?s?(l=this.left+n,"near"===i?r="right":"center"===i?(r="center",l-=a/2):(r="left",l-=a)):(l=this.left+o,"near"===i?r="left":"center"===i?(r="center",l+=a/2):(r="right",l=this.right)):r="right",{textAlign:r,x:l}}_computeLabelArea(){if(this.options.ticks.mirror)return;const t=this.chart,e=this.options.position;return"left"===e||"right"===e?{top:0,left:this.left,bottom:t.height,right:this.right}:"top"===e||"bottom"===e?{top:this.top,left:0,bottom:this.bottom,right:t.width}:void 0}drawBackground(){const{ctx:t,options:{backgroundColor:e},left:i,top:s,width:n,height:o}=this;e&&(t.save(),t.fillStyle=e,t.fillRect(i,s,n,o),t.restore())}getLineWidthForValue(t){const e=this.options.grid;if(!this._isVisible()||!e.display)return 0;const i=this.ticks.findIndex((e=>e.value===t));if(i>=0){return e.setContext(this.getContext(i)).lineWidth}return 0}drawGrid(t){const e=this.options.grid,i=this.ctx,s=this._gridLineItems||(this._gridLineItems=this._computeGridLineItems(t));let n,o;const a=(t,e,s)=>{s.width&&s.color&&(i.save(),i.lineWidth=s.width,i.strokeStyle=s.color,i.setLineDash(s.borderDash||[]),i.lineDashOffset=s.borderDashOffset,i.beginPath(),i.moveTo(t.x,t.y),i.lineTo(e.x,e.y),i.stroke(),i.restore())};if(e.display)for(n=0,o=s.length;n{this.drawBackground(),this.drawGrid(t),this.drawTitle()}},{z:s,draw:()=>{this.drawBorder()}},{z:e,draw:t=>{this.drawLabels(t)}}]:[{z:e,draw:t=>{this.draw(t)}}]}getMatchingVisibleMetas(t){const e=this.chart.getSortedVisibleDatasetMetas(),i=this.axis+"AxisID",s=[];let n,o;for(n=0,o=e.length;n{const s=i.split("."),n=s.pop(),o=[t].concat(s).join("."),a=e[i].split("."),r=a.pop(),l=a.join(".");ue.route(o,n,l,r)}))}(e,t.defaultRoutes);t.descriptors&&ue.describe(e,t.descriptors)}(t,o,i),this.override&&ue.override(t.id,t.overrides)),o}get(t){return this.items[t]}unregister(t){const e=this.items,i=t.id,s=this.scope;i in e&&delete e[i],s&&i in ue[s]&&(delete ue[s][i],this.override&&delete re[i])}}class sn{constructor(){this.controllers=new en(js,"datasets",!0),this.elements=new en($s,"elements"),this.plugins=new en(Object,"plugins"),this.scales=new en(tn,"scales"),this._typedRegistries=[this.controllers,this.scales,this.elements]}add(...t){this._each("register",t)}remove(...t){this._each("unregister",t)}addControllers(...t){this._each("register",t,this.controllers)}addElements(...t){this._each("register",t,this.elements)}addPlugins(...t){this._each("register",t,this.plugins)}addScales(...t){this._each("register",t,this.scales)}getController(t){return this._get(t,this.controllers,"controller")}getElement(t){return this._get(t,this.elements,"element")}getPlugin(t){return this._get(t,this.plugins,"plugin")}getScale(t){return this._get(t,this.scales,"scale")}removeControllers(...t){this._each("unregister",t,this.controllers)}removeElements(...t){this._each("unregister",t,this.elements)}removePlugins(...t){this._each("unregister",t,this.plugins)}removeScales(...t){this._each("unregister",t,this.scales)}_each(t,e,i){[...e].forEach((e=>{const s=i||this._getRegistryForType(e);i||s.isForType(e)||s===this.plugins&&e.id?this._exec(t,s,e):u(e,(e=>{const s=i||this._getRegistryForType(e);this._exec(t,s,e)}))}))}_exec(t,e,i){const s=w(t);d(i["before"+s],[],i),e[t](i),d(i["after"+s],[],i)}_getRegistryForType(t){for(let e=0;et.filter((t=>!e.some((e=>t.plugin.id===e.plugin.id))));this._notify(s(e,i),t,"stop"),this._notify(s(i,e),t,"start")}}function an(t,e){return e||!1!==t?!0===t?{}:t:null}function rn(t,{plugin:e,local:i},s,n){const o=t.pluginScopeKeys(e),a=t.getOptionScopes(s,o);return i&&e.defaults&&a.push(e.defaults),t.createResolver(a,n,[""],{scriptable:!1,indexable:!1,allKeys:!0})}function ln(t,e){const i=ue.datasets[t]||{};return((e.datasets||{})[t]||{}).indexAxis||e.indexAxis||i.indexAxis||"x"}function hn(t){if("x"===t||"y"===t||"r"===t)return t}function cn(t,...e){if(hn(t))return t;for(const s of e){const e=s.axis||("top"===(i=s.position)||"bottom"===i?"x":"left"===i||"right"===i?"y":void 0)||t.length>1&&hn(t[0].toLowerCase());if(e)return e}var i;throw new Error(`Cannot determine type of '${t}' axis. Please provide 'axis' or 'position' option.`)}function dn(t,e,i){if(i[e+"AxisID"]===t)return{axis:e}}function un(t,e){const i=re[t.type]||{scales:{}},s=e.scales||{},n=ln(t.type,e),a=Object.create(null);return Object.keys(s).forEach((e=>{const r=s[e];if(!o(r))return console.error(`Invalid scale configuration for scale: ${e}`);if(r._proxy)return console.warn(`Ignoring resolver passed as options for scale: ${e}`);const l=cn(e,r,function(t,e){if(e.data&&e.data.datasets){const i=e.data.datasets.filter((e=>e.xAxisID===t||e.yAxisID===t));if(i.length)return dn(t,"x",i[0])||dn(t,"y",i[0])}return{}}(e,t),ue.scales[r.type]),h=function(t,e){return t===e?"_index_":"_value_"}(l,n),c=i.scales||{};a[e]=b(Object.create(null),[{axis:l},r,c[l],c[h]])})),t.data.datasets.forEach((i=>{const n=i.type||t.type,o=i.indexAxis||ln(n,e),r=(re[n]||{}).scales||{};Object.keys(r).forEach((t=>{const e=function(t,e){let i=t;return"_index_"===t?i=e:"_value_"===t&&(i="x"===e?"y":"x"),i}(t,o),n=i[e+"AxisID"]||e;a[n]=a[n]||Object.create(null),b(a[n],[{axis:e},s[n],r[t]])}))})),Object.keys(a).forEach((t=>{const e=a[t];b(e,[ue.scales[e.type],ue.scale])})),a}function fn(t){const e=t.options||(t.options={});e.plugins=l(e.plugins,{}),e.scales=un(t,e)}function gn(t){return(t=t||{}).datasets=t.datasets||[],t.labels=t.labels||[],t}const pn=new Map,mn=new Set;function xn(t,e){let i=pn.get(t);return i||(i=e(),pn.set(t,i),mn.add(i)),i}const bn=(t,e,i)=>{const s=M(e,i);void 0!==s&&t.add(s)};class _n{constructor(t){this._config=function(t){return(t=t||{}).data=gn(t.data),fn(t),t}(t),this._scopeCache=new Map,this._resolverCache=new Map}get platform(){return this._config.platform}get type(){return this._config.type}set type(t){this._config.type=t}get data(){return this._config.data}set data(t){this._config.data=gn(t)}get options(){return this._config.options}set options(t){this._config.options=t}get plugins(){return this._config.plugins}update(){const t=this._config;this.clearCache(),fn(t)}clearCache(){this._scopeCache.clear(),this._resolverCache.clear()}datasetScopeKeys(t){return xn(t,(()=>[[`datasets.${t}`,""]]))}datasetAnimationScopeKeys(t,e){return xn(`${t}.transition.${e}`,(()=>[[`datasets.${t}.transitions.${e}`,`transitions.${e}`],[`datasets.${t}`,""]]))}datasetElementScopeKeys(t,e){return xn(`${t}-${e}`,(()=>[[`datasets.${t}.elements.${e}`,`datasets.${t}`,`elements.${e}`,""]]))}pluginScopeKeys(t){const e=t.id;return xn(`${this.type}-plugin-${e}`,(()=>[[`plugins.${e}`,...t.additionalOptionScopes||[]]]))}_cachedScopes(t,e){const i=this._scopeCache;let s=i.get(t);return s&&!e||(s=new Map,i.set(t,s)),s}getOptionScopes(t,e,i){const{options:s,type:n}=this,o=this._cachedScopes(t,i),a=o.get(e);if(a)return a;const r=new Set;e.forEach((e=>{t&&(r.add(t),e.forEach((e=>bn(r,t,e)))),e.forEach((t=>bn(r,s,t))),e.forEach((t=>bn(r,re[n]||{},t))),e.forEach((t=>bn(r,ue,t))),e.forEach((t=>bn(r,le,t)))}));const l=Array.from(r);return 0===l.length&&l.push(Object.create(null)),mn.has(e)&&o.set(e,l),l}chartOptionScopes(){const{options:t,type:e}=this;return[t,re[e]||{},ue.datasets[e]||{},{type:e},ue,le]}resolveNamedOptions(t,e,i,s=[""]){const o={$shared:!0},{resolver:a,subPrefixes:r}=yn(this._resolverCache,t,s);let l=a;if(function(t,e){const{isScriptable:i,isIndexable:s}=Ye(t);for(const o of e){const e=i(o),a=s(o),r=(a||e)&&t[o];if(e&&(S(r)||vn(r))||a&&n(r))return!0}return!1}(a,e)){o.$shared=!1;l=$e(a,i=S(i)?i():i,this.createResolver(t,i,r))}for(const t of e)o[t]=l[t];return o}createResolver(t,e,i=[""],s){const{resolver:n}=yn(this._resolverCache,t,i);return o(e)?$e(n,e,void 0,s):n}}function yn(t,e,i){let s=t.get(e);s||(s=new Map,t.set(e,s));const n=i.join();let o=s.get(n);if(!o){o={resolver:je(e,i),subPrefixes:i.filter((t=>!t.toLowerCase().includes("hover")))},s.set(n,o)}return o}const vn=t=>o(t)&&Object.getOwnPropertyNames(t).some((e=>S(t[e])));const Mn=["top","bottom","left","right","chartArea"];function wn(t,e){return"top"===t||"bottom"===t||-1===Mn.indexOf(t)&&"x"===e}function kn(t,e){return function(i,s){return i[t]===s[t]?i[e]-s[e]:i[t]-s[t]}}function Sn(t){const e=t.chart,i=e.options.animation;e.notifyPlugins("afterRender"),d(i&&i.onComplete,[t],e)}function Pn(t){const e=t.chart,i=e.options.animation;d(i&&i.onProgress,[t],e)}function Dn(t){return fe()&&"string"==typeof t?t=document.getElementById(t):t&&t.length&&(t=t[0]),t&&t.canvas&&(t=t.canvas),t}const Cn={},On=t=>{const e=Dn(t);return Object.values(Cn).filter((t=>t.canvas===e)).pop()};function An(t,e,i){const s=Object.keys(t);for(const n of s){const s=+n;if(s>=e){const o=t[n];delete t[n],(i>0||s>e)&&(t[s+i]=o)}}}class Tn{static defaults=ue;static instances=Cn;static overrides=re;static registry=nn;static version="4.5.1";static getChart=On;static register(...t){nn.add(...t),Ln()}static unregister(...t){nn.remove(...t),Ln()}constructor(t,e){const s=this.config=new _n(e),n=Dn(t),o=On(n);if(o)throw new Error("Canvas is already in use. Chart with ID '"+o.id+"' must be destroyed before the canvas with ID '"+o.canvas.id+"' can be reused.");const a=s.createResolver(s.chartOptionScopes(),this.getContext());this.platform=new(s.platform||Ps(n)),this.platform.updateConfig(s);const r=this.platform.acquireContext(n,a.aspectRatio),l=r&&r.canvas,h=l&&l.height,c=l&&l.width;this.id=i(),this.ctx=r,this.canvas=l,this.width=c,this.height=h,this._options=a,this._aspectRatio=this.aspectRatio,this._layers=[],this._metasets=[],this._stacks=void 0,this.boxes=[],this.currentDevicePixelRatio=void 0,this.chartArea=void 0,this._active=[],this._lastEvent=void 0,this._listeners={},this._responsiveListeners=void 0,this._sortedMetasets=[],this.scales={},this._plugins=new on,this.$proxies={},this._hiddenIndices={},this.attached=!1,this._animationsDisabled=void 0,this.$context=void 0,this._doResize=dt((t=>this.update(t)),a.resizeDelay||0),this._dataChanges=[],Cn[this.id]=this,r&&l?(bt.listen(this,"complete",Sn),bt.listen(this,"progress",Pn),this._initialize(),this.attached&&this.update()):console.error("Failed to create chart: can't acquire context from the given item")}get aspectRatio(){const{options:{aspectRatio:t,maintainAspectRatio:e},width:i,height:n,_aspectRatio:o}=this;return s(t)?e&&o?o:n?i/n:null:t}get data(){return this.config.data}set data(t){this.config.data=t}get options(){return this._options}set options(t){this.config.options=t}get registry(){return nn}_initialize(){return this.notifyPlugins("beforeInit"),this.options.responsive?this.resize():ke(this,this.options.devicePixelRatio),this.bindEvents(),this.notifyPlugins("afterInit"),this}clear(){return Te(this.canvas,this.ctx),this}stop(){return bt.stop(this),this}resize(t,e){bt.running(this)?this._resizeBeforeDraw={width:t,height:e}:this._resize(t,e)}_resize(t,e){const i=this.options,s=this.canvas,n=i.maintainAspectRatio&&this.aspectRatio,o=this.platform.getMaximumSize(s,t,e,n),a=i.devicePixelRatio||this.platform.getDevicePixelRatio(),r=this.width?"resize":"attach";this.width=o.width,this.height=o.height,this._aspectRatio=this.aspectRatio,ke(this,a,!0)&&(this.notifyPlugins("resize",{size:o}),d(i.onResize,[this,o],this),this.attached&&this._doResize(r)&&this.render())}ensureScalesHaveIDs(){u(this.options.scales||{},((t,e)=>{t.id=e}))}buildOrUpdateScales(){const t=this.options,e=t.scales,i=this.scales,s=Object.keys(i).reduce(((t,e)=>(t[e]=!1,t)),{});let n=[];e&&(n=n.concat(Object.keys(e).map((t=>{const i=e[t],s=cn(t,i),n="r"===s,o="x"===s;return{options:i,dposition:n?"chartArea":o?"bottom":"left",dtype:n?"radialLinear":o?"category":"linear"}})))),u(n,(e=>{const n=e.options,o=n.id,a=cn(o,n),r=l(n.type,e.dtype);void 0!==n.position&&wn(n.position,a)===wn(e.dposition)||(n.position=e.dposition),s[o]=!0;let h=null;if(o in i&&i[o].type===r)h=i[o];else{h=new(nn.getScale(r))({id:o,type:r,ctx:this.ctx,chart:this}),i[h.id]=h}h.init(n,t)})),u(s,((t,e)=>{t||delete i[e]})),u(i,(t=>{ls.configure(this,t,t.options),ls.addBox(this,t)}))}_updateMetasets(){const t=this._metasets,e=this.data.datasets.length,i=t.length;if(t.sort(((t,e)=>t.index-e.index)),i>e){for(let t=e;te.length&&delete this._stacks,t.forEach(((t,i)=>{0===e.filter((e=>e===t._dataset)).length&&this._destroyDatasetMeta(i)}))}buildOrUpdateControllers(){const t=[],e=this.data.datasets;let i,s;for(this._removeUnreferencedMetasets(),i=0,s=e.length;i{this.getDatasetMeta(e).controller.reset()}),this)}reset(){this._resetElements(),this.notifyPlugins("reset")}update(t){const e=this.config;e.update();const i=this._options=e.createResolver(e.chartOptionScopes(),this.getContext()),s=this._animationsDisabled=!i.animation;if(this._updateScales(),this._checkEventBindings(),this._updateHiddenIndices(),this._plugins.invalidate(),!1===this.notifyPlugins("beforeUpdate",{mode:t,cancelable:!0}))return;const n=this.buildOrUpdateControllers();this.notifyPlugins("beforeElementsUpdate");let o=0;for(let t=0,e=this.data.datasets.length;t{t.reset()})),this._updateDatasets(t),this.notifyPlugins("afterUpdate",{mode:t}),this._layers.sort(kn("z","_idx"));const{_active:a,_lastEvent:r}=this;r?this._eventHandler(r,!0):a.length&&this._updateHoverStyles(a,a,!0),this.render()}_updateScales(){u(this.scales,(t=>{ls.removeBox(this,t)})),this.ensureScalesHaveIDs(),this.buildOrUpdateScales()}_checkEventBindings(){const t=this.options,e=new Set(Object.keys(this._listeners)),i=new Set(t.events);P(e,i)&&!!this._responsiveListeners===t.responsive||(this.unbindEvents(),this.bindEvents())}_updateHiddenIndices(){const{_hiddenIndices:t}=this,e=this._getUniformDataChanges()||[];for(const{method:i,start:s,count:n}of e){An(t,s,"_removeElements"===i?-n:n)}}_getUniformDataChanges(){const t=this._dataChanges;if(!t||!t.length)return;this._dataChanges=[];const e=this.data.datasets.length,i=e=>new Set(t.filter((t=>t[0]===e)).map(((t,e)=>e+","+t.splice(1).join(",")))),s=i(0);for(let t=1;tt.split(","))).map((t=>({method:t[1],start:+t[2],count:+t[3]})))}_updateLayout(t){if(!1===this.notifyPlugins("beforeLayout",{cancelable:!0}))return;ls.update(this,this.width,this.height,t);const e=this.chartArea,i=e.width<=0||e.height<=0;this._layers=[],u(this.boxes,(t=>{i&&"chartArea"===t.position||(t.configure&&t.configure(),this._layers.push(...t._layers()))}),this),this._layers.forEach(((t,e)=>{t._idx=e})),this.notifyPlugins("afterLayout")}_updateDatasets(t){if(!1!==this.notifyPlugins("beforeDatasetsUpdate",{mode:t,cancelable:!0})){for(let t=0,e=this.data.datasets.length;t=0;--e)this._drawDataset(t[e]);this.notifyPlugins("afterDatasetsDraw")}_drawDataset(t){const e=this.ctx,i={meta:t,index:t.index,cancelable:!0},s=Ni(this,t);!1!==this.notifyPlugins("beforeDatasetDraw",i)&&(s&&Ie(e,s),t.controller.draw(),s&&ze(e),i.cancelable=!1,this.notifyPlugins("afterDatasetDraw",i))}isPointInArea(t){return Re(t,this.chartArea,this._minPadding)}getElementsAtEventForMode(t,e,i,s){const n=Ki.modes[e];return"function"==typeof n?n(this,t,i,s):[]}getDatasetMeta(t){const e=this.data.datasets[t],i=this._metasets;let s=i.filter((t=>t&&t._dataset===e)).pop();return s||(s={type:null,data:[],dataset:null,controller:null,hidden:null,xAxisID:null,yAxisID:null,order:e&&e.order||0,index:t,_dataset:e,_parsed:[],_sorted:!1},i.push(s)),s}getContext(){return this.$context||(this.$context=Ci(null,{chart:this,type:"chart"}))}getVisibleDatasetCount(){return this.getSortedVisibleDatasetMetas().length}isDatasetVisible(t){const e=this.data.datasets[t];if(!e)return!1;const i=this.getDatasetMeta(t);return"boolean"==typeof i.hidden?!i.hidden:!e.hidden}setDatasetVisibility(t,e){this.getDatasetMeta(t).hidden=!e}toggleDataVisibility(t){this._hiddenIndices[t]=!this._hiddenIndices[t]}getDataVisibility(t){return!this._hiddenIndices[t]}_updateVisibility(t,e,i){const s=i?"show":"hide",n=this.getDatasetMeta(t),o=n.controller._resolveAnimations(void 0,s);k(e)?(n.data[e].hidden=!i,this.update()):(this.setDatasetVisibility(t,i),o.update(n,{visible:i}),this.update((e=>e.datasetIndex===t?s:void 0)))}hide(t,e){this._updateVisibility(t,e,!1)}show(t,e){this._updateVisibility(t,e,!0)}_destroyDatasetMeta(t){const e=this._metasets[t];e&&e.controller&&e.controller._destroy(),delete this._metasets[t]}_stop(){let t,e;for(this.stop(),bt.remove(this),t=0,e=this.data.datasets.length;t{e.addEventListener(this,i,s),t[i]=s},s=(t,e,i)=>{t.offsetX=e,t.offsetY=i,this._eventHandler(t)};u(this.options.events,(t=>i(t,s)))}bindResponsiveEvents(){this._responsiveListeners||(this._responsiveListeners={});const t=this._responsiveListeners,e=this.platform,i=(i,s)=>{e.addEventListener(this,i,s),t[i]=s},s=(i,s)=>{t[i]&&(e.removeEventListener(this,i,s),delete t[i])},n=(t,e)=>{this.canvas&&this.resize(t,e)};let o;const a=()=>{s("attach",a),this.attached=!0,this.resize(),i("resize",n),i("detach",o)};o=()=>{this.attached=!1,s("resize",n),this._stop(),this._resize(0,0),i("attach",a)},e.isAttached(this.canvas)?a():o()}unbindEvents(){u(this._listeners,((t,e)=>{this.platform.removeEventListener(this,e,t)})),this._listeners={},u(this._responsiveListeners,((t,e)=>{this.platform.removeEventListener(this,e,t)})),this._responsiveListeners=void 0}updateHoverStyle(t,e,i){const s=i?"set":"remove";let n,o,a,r;for("dataset"===e&&(n=this.getDatasetMeta(t[0].datasetIndex),n.controller["_"+s+"DatasetHoverStyle"]()),a=0,r=t.length;a{const i=this.getDatasetMeta(t);if(!i)throw new Error("No dataset found at index "+t);return{datasetIndex:t,element:i.data[e],index:e}}));!f(i,e)&&(this._active=i,this._lastEvent=null,this._updateHoverStyles(i,e))}notifyPlugins(t,e,i){return this._plugins.notify(this,t,e,i)}isPluginEnabled(t){return 1===this._plugins._cache.filter((e=>e.plugin.id===t)).length}_updateHoverStyles(t,e,i){const s=this.options.hover,n=(t,e)=>t.filter((t=>!e.some((e=>t.datasetIndex===e.datasetIndex&&t.index===e.index)))),o=n(e,t),a=i?t:n(t,e);o.length&&this.updateHoverStyle(o,s.mode,!1),a.length&&s.mode&&this.updateHoverStyle(a,s.mode,!0)}_eventHandler(t,e){const i={event:t,replay:e,cancelable:!0,inChartArea:this.isPointInArea(t)},s=e=>(e.options.events||this.options.events).includes(t.native.type);if(!1===this.notifyPlugins("beforeEvent",i,s))return;const n=this._handleEvent(t,e,i.inChartArea);return i.cancelable=!1,this.notifyPlugins("afterEvent",i,s),(n||i.changed)&&this.render(),this}_handleEvent(t,e,i){const{_active:s=[],options:n}=this,o=e,a=this._getActiveElements(t,s,i,o),r=D(t),l=function(t,e,i,s){return i&&"mouseout"!==t.type?s?e:t:null}(t,this._lastEvent,i,r);i&&(this._lastEvent=null,d(n.onHover,[t,a,this],this),r&&d(n.onClick,[t,a,this],this));const h=!f(a,s);return(h||e)&&(this._active=a,this._updateHoverStyles(a,s,e)),this._lastEvent=l,h}_getActiveElements(t,e,i,s){if("mouseout"===t.type)return[];if(!i)return e;const n=this.options.hover;return this.getElementsAtEventForMode(t,n.mode,n,s)}}function Ln(){return u(Tn.instances,(t=>t._plugins.invalidate()))}function En(){throw new Error("This method is not implemented: Check that a complete date adapter is provided.")}class Rn{static override(t){Object.assign(Rn.prototype,t)}options;constructor(t){this.options=t||{}}init(){}formats(){return En()}parse(){return En()}format(){return En()}add(){return En()}diff(){return En()}startOf(){return En()}endOf(){return En()}}var In={_date:Rn};function zn(t){const e=t.iScale,i=function(t,e){if(!t._cache.$bar){const i=t.getMatchingVisibleMetas(e);let s=[];for(let e=0,n=i.length;et-e)))}return t._cache.$bar}(e,t.type);let s,n,o,a,r=e._length;const l=()=>{32767!==o&&-32768!==o&&(k(a)&&(r=Math.min(r,Math.abs(o-a)||r)),a=o)};for(s=0,n=i.length;sMath.abs(r)&&(l=r,h=a),e[i.axis]=h,e._custom={barStart:l,barEnd:h,start:n,end:o,min:a,max:r}}(t,e,i,s):e[i.axis]=i.parse(t,s),e}function Vn(t,e,i,s){const n=t.iScale,o=t.vScale,a=n.getLabels(),r=n===o,l=[];let h,c,d,u;for(h=i,c=i+s;ht.x,i="left",s="right"):(e=t.base"spacing"!==t,_indexable:t=>"spacing"!==t&&!t.startsWith("borderDash")&&!t.startsWith("hoverBorderDash")};static overrides={aspectRatio:1,plugins:{legend:{labels:{generateLabels(t){const e=t.data,{labels:{pointStyle:i,textAlign:s,color:n,useBorderRadius:o,borderRadius:a}}=t.legend.options;return e.labels.length&&e.datasets.length?e.labels.map(((e,r)=>{const l=t.getDatasetMeta(0).controller.getStyle(r);return{text:e,fillStyle:l.backgroundColor,fontColor:n,hidden:!t.getDataVisibility(r),lineDash:l.borderDash,lineDashOffset:l.borderDashOffset,lineJoin:l.borderJoinStyle,lineWidth:l.borderWidth,strokeStyle:l.borderColor,textAlign:s,pointStyle:i,borderRadius:o&&(a||l.borderRadius),index:r}})):[]}},onClick(t,e,i){i.chart.toggleDataVisibility(e.index),i.chart.update()}}}};constructor(t,e){super(t,e),this.enableOptionSharing=!0,this.innerRadius=void 0,this.outerRadius=void 0,this.offsetX=void 0,this.offsetY=void 0}linkScales(){}parse(t,e){const i=this.getDataset().data,s=this._cachedMeta;if(!1===this._parsing)s._parsed=i;else{let n,a,r=t=>+i[t];if(o(i[t])){const{key:t="value"}=this._parsing;r=e=>+M(i[e],t)}for(n=t,a=t+e;nJ(t,r,l,!0)?1:Math.max(e,e*i,s,s*i),g=(t,e,s)=>J(t,r,l,!0)?-1:Math.min(e,e*i,s,s*i),p=f(0,h,d),m=f(E,c,u),x=g(C,h,d),b=g(C+E,c,u);s=(p-x)/2,n=(m-b)/2,o=-(p+x)/2,a=-(m+b)/2}return{ratioX:s,ratioY:n,offsetX:o,offsetY:a}}(u,d,r),x=(i.width-o)/f,b=(i.height-o)/g,_=Math.max(Math.min(x,b)/2,0),y=c(this.options.radius,_),v=(y-Math.max(y*r,0))/this._getVisibleDatasetWeightTotal();this.offsetX=p*y,this.offsetY=m*y,s.total=this.calculateTotal(),this.outerRadius=y-v*this._getRingWeightOffset(this.index),this.innerRadius=Math.max(this.outerRadius-v*l,0),this.updateElements(n,0,n.length,t)}_circumference(t,e){const i=this.options,s=this._cachedMeta,n=this._getCircumference();return e&&i.animation.animateRotate||!this.chart.getDataVisibility(t)||null===s._parsed[t]||s.data[t].hidden?0:this.calculateCircumference(s._parsed[t]*n/O)}updateElements(t,e,i,s){const n="reset"===s,o=this.chart,a=o.chartArea,r=o.options.animation,l=(a.left+a.right)/2,h=(a.top+a.bottom)/2,c=n&&r.animateScale,d=c?0:this.innerRadius,u=c?0:this.outerRadius,{sharedOptions:f,includeOptions:g}=this._getSharedOptions(e,s);let p,m=this._getRotation();for(p=0;p0&&!isNaN(t)?O*(Math.abs(t)/e):0}getLabelAndValue(t){const e=this._cachedMeta,i=this.chart,s=i.data.labels||[],n=ne(e._parsed[t],i.options.locale);return{label:s[t]||"",value:n}}getMaxBorderWidth(t){let e=0;const i=this.chart;let s,n,o,a,r;if(!t)for(s=0,n=i.data.datasets.length;s{const o=t.getDatasetMeta(0).controller.getStyle(n);return{text:e,fillStyle:o.backgroundColor,strokeStyle:o.borderColor,fontColor:s,lineWidth:o.borderWidth,pointStyle:i,hidden:!t.getDataVisibility(n),index:n}}))}return[]}},onClick(t,e,i){i.chart.toggleDataVisibility(e.index),i.chart.update()}}},scales:{r:{type:"radialLinear",angleLines:{display:!1},beginAtZero:!0,grid:{circular:!0},pointLabels:{display:!1},startAngle:0}}};constructor(t,e){super(t,e),this.innerRadius=void 0,this.outerRadius=void 0}getLabelAndValue(t){const e=this._cachedMeta,i=this.chart,s=i.data.labels||[],n=ne(e._parsed[t].r,i.options.locale);return{label:s[t]||"",value:n}}parseObjectData(t,e,i,s){return ii.bind(this)(t,e,i,s)}update(t){const e=this._cachedMeta.data;this._updateRadius(),this.updateElements(e,0,e.length,t)}getMinMax(){const t=this._cachedMeta,e={min:Number.POSITIVE_INFINITY,max:Number.NEGATIVE_INFINITY};return t.data.forEach(((t,i)=>{const s=this.getParsed(i).r;!isNaN(s)&&this.chart.getDataVisibility(i)&&(se.max&&(e.max=s))})),e}_updateRadius(){const t=this.chart,e=t.chartArea,i=t.options,s=Math.min(e.right-e.left,e.bottom-e.top),n=Math.max(s/2,0),o=(n-Math.max(i.cutoutPercentage?n/100*i.cutoutPercentage:1,0))/t.getVisibleDatasetCount();this.outerRadius=n-o*this.index,this.innerRadius=this.outerRadius-o}updateElements(t,e,i,s){const n="reset"===s,o=this.chart,a=o.options.animation,r=this._cachedMeta.rScale,l=r.xCenter,h=r.yCenter,c=r.getIndexAngle(0)-.5*C;let d,u=c;const f=360/this.countVisibleElements();for(d=0;d{!isNaN(this.getParsed(i).r)&&this.chart.getDataVisibility(i)&&e++})),e}_computeAngle(t,e,i){return this.chart.getDataVisibility(t)?$(this.resolveDataElementOptions(t,e).angle||i):0}}var Un=Object.freeze({__proto__:null,BarController:class extends js{static id="bar";static defaults={datasetElementType:!1,dataElementType:"bar",categoryPercentage:.8,barPercentage:.9,grouped:!0,animations:{numbers:{type:"number",properties:["x","y","base","width","height"]}}};static overrides={scales:{_index_:{type:"category",offset:!0,grid:{offset:!0}},_value_:{type:"linear",beginAtZero:!0}}};parsePrimitiveData(t,e,i,s){return Vn(t,e,i,s)}parseArrayData(t,e,i,s){return Vn(t,e,i,s)}parseObjectData(t,e,i,s){const{iScale:n,vScale:o}=t,{xAxisKey:a="x",yAxisKey:r="y"}=this._parsing,l="x"===n.axis?a:r,h="x"===o.axis?a:r,c=[];let d,u,f,g;for(d=i,u=i+s;dt.controller.options.grouped)),o=i.options.stacked,a=[],r=this._cachedMeta.controller.getParsed(e),l=r&&r[i.axis],h=t=>{const e=t._parsed.find((t=>t[i.axis]===l)),n=e&&e[t.vScale.axis];if(s(n)||isNaN(n))return!0};for(const i of n)if((void 0===e||!h(i))&&((!1===o||-1===a.indexOf(i.stack)||void 0===o&&void 0===i.stack)&&a.push(i.stack),i.index===t))break;return a.length||a.push(void 0),a}_getStackCount(t){return this._getStacks(void 0,t).length}_getAxisCount(){return this._getAxis().length}getFirstScaleIdForIndexAxis(){const t=this.chart.scales,e=this.chart.options.indexAxis;return Object.keys(t).filter((i=>t[i].axis===e)).shift()}_getAxis(){const t={},e=this.getFirstScaleIdForIndexAxis();for(const i of this.chart.data.datasets)t[l("x"===this.chart.options.indexAxis?i.xAxisID:i.yAxisID,e)]=!0;return Object.keys(t)}_getStackIndex(t,e,i){const s=this._getStacks(t,i),n=void 0!==e?s.indexOf(e):-1;return-1===n?s.length-1:n}_getRuler(){const t=this.options,e=this._cachedMeta,i=e.iScale,s=[];let n,o;for(n=0,o=e.data.length;n=i?1:-1)}(u,e,r)*a,f===r&&(x-=u/2);const t=e.getPixelForDecimal(0),s=e.getPixelForDecimal(1),o=Math.min(t,s),h=Math.max(t,s);x=Math.max(Math.min(x,h),o),d=x+u,i&&!c&&(l._stacks[e.axis]._visualValues[n]=e.getValueForPixel(d)-e.getValueForPixel(x))}if(x===e.getPixelForValue(r)){const t=F(u)*e.getLineWidthForValue(r)/2;x+=t,u-=t}return{size:u,base:x,head:d,center:d+u/2}}_calculateBarIndexPixels(t,e){const i=e.scale,n=this.options,o=n.skipNull,a=l(n.maxBarThickness,1/0);let r,h;const c=this._getAxisCount();if(e.grouped){const i=o?this._getStackCount(t):e.stackCount,d="flex"===n.barThickness?function(t,e,i,s){const n=e.pixels,o=n[t];let a=t>0?n[t-1]:null,r=t=0;--i)e=Math.max(e,t[i].size(this.resolveDataElementOptions(i))/2);return e>0&&e}getLabelAndValue(t){const e=this._cachedMeta,i=this.chart.data.labels||[],{xScale:s,yScale:n}=e,o=this.getParsed(t),a=s.getLabelForValue(o.x),r=n.getLabelForValue(o.y),l=o._custom;return{label:i[t]||"",value:"("+a+", "+r+(l?", "+l:"")+")"}}update(t){const e=this._cachedMeta.data;this.updateElements(e,0,e.length,t)}updateElements(t,e,i,s){const n="reset"===s,{iScale:o,vScale:a}=this._cachedMeta,{sharedOptions:r,includeOptions:l}=this._getSharedOptions(e,s),h=o.axis,c=a.axis;for(let d=e;d0&&this.getParsed(e-1);for(let i=0;i<_;++i){const g=t[i],_=x?g:{};if(i=b){_.skip=!0;continue}const v=this.getParsed(i),M=s(v[f]),w=_[u]=a.getPixelForValue(v[u],i),k=_[f]=o||M?r.getBasePixel():r.getPixelForValue(l?this.applyStack(r,v,l):v[f],i);_.skip=isNaN(w)||isNaN(k)||M,_.stop=i>0&&Math.abs(v[u]-y[u])>m,p&&(_.parsed=v,_.raw=h.data[i]),d&&(_.options=c||this.resolveDataElementOptions(i,g.active?"active":n)),x||this.updateElement(g,i,_,n),y=v}}getMaxOverflow(){const t=this._cachedMeta,e=t.dataset,i=e.options&&e.options.borderWidth||0,s=t.data||[];if(!s.length)return i;const n=s[0].size(this.resolveDataElementOptions(0)),o=s[s.length-1].size(this.resolveDataElementOptions(s.length-1));return Math.max(i,n,o)/2}draw(){const t=this._cachedMeta;t.dataset.updateControlPoints(this.chart.chartArea,t.iScale.axis),super.draw()}},PieController:class extends $n{static id="pie";static defaults={cutout:0,rotation:0,circumference:360,radius:"100%"}},PolarAreaController:Yn,RadarController:class extends js{static id="radar";static defaults={datasetElementType:"line",dataElementType:"point",indexAxis:"r",showLine:!0,elements:{line:{fill:"start"}}};static overrides={aspectRatio:1,scales:{r:{type:"radialLinear"}}};getLabelAndValue(t){const e=this._cachedMeta.vScale,i=this.getParsed(t);return{label:e.getLabels()[t],value:""+e.getLabelForValue(i[e.axis])}}parseObjectData(t,e,i,s){return ii.bind(this)(t,e,i,s)}update(t){const e=this._cachedMeta,i=e.dataset,s=e.data||[],n=e.iScale.getLabels();if(i.points=s,"resize"!==t){const e=this.resolveDatasetElementOptions(t);this.options.showLine||(e.borderWidth=0);const o={_loop:!0,_fullLoop:n.length===s.length,options:e};this.updateElement(i,void 0,o,t)}this.updateElements(s,0,s.length,t)}updateElements(t,e,i,s){const n=this._cachedMeta.rScale,o="reset"===s;for(let a=e;a0&&this.getParsed(e-1);for(let c=e;c0&&Math.abs(i[f]-_[f])>x,m&&(p.parsed=i,p.raw=h.data[c]),u&&(p.options=d||this.resolveDataElementOptions(c,e.active?"active":n)),b||this.updateElement(e,c,p,n),_=i}this.updateSharedOptions(d,n,c)}getMaxOverflow(){const t=this._cachedMeta,e=t.data||[];if(!this.options.showLine){let t=0;for(let i=e.length-1;i>=0;--i)t=Math.max(t,e[i].size(this.resolveDataElementOptions(i))/2);return t>0&&t}const i=t.dataset,s=i.options&&i.options.borderWidth||0;if(!e.length)return s;const n=e[0].size(this.resolveDataElementOptions(0)),o=e[e.length-1].size(this.resolveDataElementOptions(e.length-1));return Math.max(s,n,o)/2}}});function Xn(t,e,i,s){const n=vi(t.options.borderRadius,["outerStart","outerEnd","innerStart","innerEnd"]);const o=(i-e)/2,a=Math.min(o,s*e/2),r=t=>{const e=(i-Math.min(o,t))*s/2;return Z(t,0,Math.min(o,e))};return{outerStart:r(n.outerStart),outerEnd:r(n.outerEnd),innerStart:Z(n.innerStart,0,a),innerEnd:Z(n.innerEnd,0,a)}}function qn(t,e,i,s){return{x:i+t*Math.cos(e),y:s+t*Math.sin(e)}}function Kn(t,e,i,s,n,o){const{x:a,y:r,startAngle:l,pixelMargin:h,innerRadius:c}=e,d=Math.max(e.outerRadius+s+i-h,0),u=c>0?c+s+i+h:0;let f=0;const g=n-l;if(s){const t=((c>0?c-s:0)+(d>0?d-s:0))/2;f=(g-(0!==t?g*t/(t+s):g))/2}const p=(g-Math.max(.001,g*d-i/C)/d)/2,m=l+p+f,x=n-p-f,{outerStart:b,outerEnd:_,innerStart:y,innerEnd:v}=Xn(e,u,d,x-m),M=d-b,w=d-_,k=m+b/M,S=x-_/w,P=u+y,D=u+v,O=m+y/P,A=x-v/D;if(t.beginPath(),o){const e=(k+S)/2;if(t.arc(a,r,d,k,e),t.arc(a,r,d,e,S),_>0){const e=qn(w,S,a,r);t.arc(e.x,e.y,_,S,x+E)}const i=qn(D,x,a,r);if(t.lineTo(i.x,i.y),v>0){const e=qn(D,A,a,r);t.arc(e.x,e.y,v,x+E,A+Math.PI)}const s=(x-v/u+(m+y/u))/2;if(t.arc(a,r,u,x-v/u,s,!0),t.arc(a,r,u,s,m+y/u,!0),y>0){const e=qn(P,O,a,r);t.arc(e.x,e.y,y,O+Math.PI,m-E)}const n=qn(M,m,a,r);if(t.lineTo(n.x,n.y),b>0){const e=qn(M,k,a,r);t.arc(e.x,e.y,b,m-E,k)}}else{t.moveTo(a,r);const e=Math.cos(k)*d+a,i=Math.sin(k)*d+r;t.lineTo(e,i);const s=Math.cos(S)*d+a,n=Math.sin(S)*d+r;t.lineTo(s,n)}t.closePath()}function Gn(t,e,i,s,n){const{fullCircles:o,startAngle:a,circumference:r,options:l}=e,{borderWidth:h,borderJoinStyle:c,borderDash:d,borderDashOffset:u,borderRadius:f}=l,g="inner"===l.borderAlign;if(!h)return;t.setLineDash(d||[]),t.lineDashOffset=u,g?(t.lineWidth=2*h,t.lineJoin=c||"round"):(t.lineWidth=h,t.lineJoin=c||"bevel");let p=e.endAngle;if(o){Kn(t,e,i,s,p,n);for(let e=0;en?(h=n/l,t.arc(o,a,l,i+h,s-h,!0)):t.arc(o,a,n,i+E,s-E),t.closePath(),t.clip()}(t,e,p),l.selfJoin&&p-a>=C&&0===f&&"miter"!==c&&function(t,e,i){const{startAngle:s,x:n,y:o,outerRadius:a,innerRadius:r,options:l}=e,{borderWidth:h,borderJoinStyle:c}=l,d=Math.min(h/a,G(s-i));if(t.beginPath(),t.arc(n,o,a-h/2,s+d/2,i-d/2),r>0){const e=Math.min(h/r,G(s-i));t.arc(n,o,r+h/2,i-e/2,s+e/2,!0)}else{const e=Math.min(h/2,a*G(s-i));if("round"===c)t.arc(n,o,e,i-C/2,s+C/2,!0);else if("bevel"===c){const a=2*e*e,r=-a*Math.cos(i+C/2)+n,l=-a*Math.sin(i+C/2)+o,h=a*Math.cos(s+C/2)+n,c=a*Math.sin(s+C/2)+o;t.lineTo(r,l),t.lineTo(h,c)}}t.closePath(),t.moveTo(0,0),t.rect(0,0,t.canvas.width,t.canvas.height),t.clip("evenodd")}(t,e,p),o||(Kn(t,e,i,s,p,n),t.stroke())}function Jn(t,e,i=e){t.lineCap=l(i.borderCapStyle,e.borderCapStyle),t.setLineDash(l(i.borderDash,e.borderDash)),t.lineDashOffset=l(i.borderDashOffset,e.borderDashOffset),t.lineJoin=l(i.borderJoinStyle,e.borderJoinStyle),t.lineWidth=l(i.borderWidth,e.borderWidth),t.strokeStyle=l(i.borderColor,e.borderColor)}function Zn(t,e,i){t.lineTo(i.x,i.y)}function Qn(t,e,i={}){const s=t.length,{start:n=0,end:o=s-1}=i,{start:a,end:r}=e,l=Math.max(n,a),h=Math.min(o,r),c=nr&&o>r;return{count:s,start:l,loop:e.loop,ilen:h(a+(h?r-t:t))%o,_=()=>{f!==g&&(t.lineTo(m,g),t.lineTo(m,f),t.lineTo(m,p))};for(l&&(d=n[b(0)],t.moveTo(d.x,d.y)),c=0;c<=r;++c){if(d=n[b(c)],d.skip)continue;const e=d.x,i=d.y,s=0|e;s===u?(ig&&(g=i),m=(x*m+e)/++x):(_(),t.lineTo(e,i),u=s,x=0,f=g=i),p=i}_()}function io(t){const e=t.options,i=e.borderDash&&e.borderDash.length;return!(t._decimated||t._loop||e.tension||"monotone"===e.cubicInterpolationMode||e.stepped||i)?eo:to}const so="function"==typeof Path2D;function no(t,e,i,s){so&&!e.options.segment?function(t,e,i,s){let n=e._path;n||(n=e._path=new Path2D,e.path(n,i,s)&&n.closePath()),Jn(t,e.options),t.stroke(n)}(t,e,i,s):function(t,e,i,s){const{segments:n,options:o}=e,a=io(e);for(const r of n)Jn(t,o,r.style),t.beginPath(),a(t,e,r,{start:i,end:i+s-1})&&t.closePath(),t.stroke()}(t,e,i,s)}class oo extends $s{static id="line";static defaults={borderCapStyle:"butt",borderDash:[],borderDashOffset:0,borderJoinStyle:"miter",borderWidth:3,capBezierPoints:!0,cubicInterpolationMode:"default",fill:!1,spanGaps:!1,stepped:!1,tension:0};static defaultRoutes={backgroundColor:"backgroundColor",borderColor:"borderColor"};static descriptors={_scriptable:!0,_indexable:t=>"borderDash"!==t&&"fill"!==t};constructor(t){super(),this.animated=!0,this.options=void 0,this._chart=void 0,this._loop=void 0,this._fullLoop=void 0,this._path=void 0,this._points=void 0,this._segments=void 0,this._decimated=!1,this._pointsUpdated=!1,this._datasetIndex=void 0,t&&Object.assign(this,t)}updateControlPoints(t,e){const i=this.options;if((i.tension||"monotone"===i.cubicInterpolationMode)&&!i.stepped&&!this._pointsUpdated){const s=i.spanGaps?this._loop:this._fullLoop;hi(this._points,i,t,s,e),this._pointsUpdated=!0}}set points(t){this._points=t,delete this._segments,delete this._path,this._pointsUpdated=!1}get points(){return this._points}get segments(){return this._segments||(this._segments=zi(this,this.options.segment))}first(){const t=this.segments,e=this.points;return t.length&&e[t[0].start]}last(){const t=this.segments,e=this.points,i=t.length;return i&&e[t[i-1].end]}interpolate(t,e){const i=this.options,s=t[e],n=this.points,o=Ii(this,{property:e,start:s,end:s});if(!o.length)return;const a=[],r=function(t){return t.stepped?pi:t.tension||"monotone"===t.cubicInterpolationMode?mi:gi}(i);let l,h;for(l=0,h=o.length;l"borderDash"!==t};circumference;endAngle;fullCircles;innerRadius;outerRadius;pixelMargin;startAngle;constructor(t){super(),this.options=void 0,this.circumference=void 0,this.startAngle=void 0,this.endAngle=void 0,this.innerRadius=void 0,this.outerRadius=void 0,this.pixelMargin=0,this.fullCircles=0,t&&Object.assign(this,t)}inRange(t,e,i){const s=this.getProps(["x","y"],i),{angle:n,distance:o}=X(s,{x:t,y:e}),{startAngle:a,endAngle:r,innerRadius:h,outerRadius:c,circumference:d}=this.getProps(["startAngle","endAngle","innerRadius","outerRadius","circumference"],i),u=(this.options.spacing+this.options.borderWidth)/2,f=l(d,r-a),g=J(n,a,r)&&a!==r,p=f>=O||g,m=tt(o,h+u,c+u);return p&&m}getCenterPoint(t){const{x:e,y:i,startAngle:s,endAngle:n,innerRadius:o,outerRadius:a}=this.getProps(["x","y","startAngle","endAngle","innerRadius","outerRadius"],t),{offset:r,spacing:l}=this.options,h=(s+n)/2,c=(o+a+l+r)/2;return{x:e+Math.cos(h)*c,y:i+Math.sin(h)*c}}tooltipPosition(t){return this.getCenterPoint(t)}draw(t){const{options:e,circumference:i}=this,s=(e.offset||0)/4,n=(e.spacing||0)/2,o=e.circular;if(this.pixelMargin="inner"===e.borderAlign?.33:0,this.fullCircles=i>O?Math.floor(i/O):0,0===i||this.innerRadius<0||this.outerRadius<0)return;t.save();const a=(this.startAngle+this.endAngle)/2;t.translate(Math.cos(a)*s,Math.sin(a)*s);const r=s*(1-Math.sin(Math.min(C,i||0)));t.fillStyle=e.backgroundColor,t.strokeStyle=e.borderColor,function(t,e,i,s,n){const{fullCircles:o,startAngle:a,circumference:r}=e;let l=e.endAngle;if(o){Kn(t,e,i,s,l,n);for(let e=0;e("string"==typeof e?(i=t.push(e)-1,s.unshift({index:i,label:e})):isNaN(e)&&(i=null),i))(t,e,i,s);return n!==t.lastIndexOf(e)?i:n}function mo(t){const e=this.getLabels();return t>=0&&ts=e?s:t,a=t=>n=i?n:t;if(t){const t=F(s),e=F(n);t<0&&e<0?a(0):t>0&&e>0&&o(0)}if(s===n){let e=0===n?1:Math.abs(.05*n);a(n+e),t||o(s-e)}this.min=s,this.max=n}getTickLimit(){const t=this.options.ticks;let e,{maxTicksLimit:i,stepSize:s}=t;return s?(e=Math.ceil(this.max/s)-Math.floor(this.min/s)+1,e>1e3&&(console.warn(`scales.${this.id}.ticks.stepSize: ${s} would result generating up to ${e} ticks. Limiting to 1000.`),e=1e3)):(e=this.computeTickLimit(),i=i||11),i&&(e=Math.min(i,e)),e}computeTickLimit(){return Number.POSITIVE_INFINITY}buildTicks(){const t=this.options,e=t.ticks;let i=this.getTickLimit();i=Math.max(2,i);const n=function(t,e){const i=[],{bounds:n,step:o,min:a,max:r,precision:l,count:h,maxTicks:c,maxDigits:d,includeBounds:u}=t,f=o||1,g=c-1,{min:p,max:m}=e,x=!s(a),b=!s(r),_=!s(h),y=(m-p)/(d+1);let v,M,w,k,S=B((m-p)/g/f)*f;if(S<1e-14&&!x&&!b)return[{value:p},{value:m}];k=Math.ceil(m/S)-Math.floor(p/S),k>g&&(S=B(k*S/g/f)*f),s(l)||(v=Math.pow(10,l),S=Math.ceil(S*v)/v),"ticks"===n?(M=Math.floor(p/S)*S,w=Math.ceil(m/S)*S):(M=p,w=m),x&&b&&o&&H((r-a)/o,S/1e3)?(k=Math.round(Math.min((r-a)/S,c)),S=(r-a)/k,M=a,w=r):_?(M=x?a:M,w=b?r:w,k=h-1,S=(w-M)/k):(k=(w-M)/S,k=V(k,Math.round(k),S/1e3)?Math.round(k):Math.ceil(k));const P=Math.max(U(S),U(M));v=Math.pow(10,s(l)?P:l),M=Math.round(M*v)/v,w=Math.round(w*v)/v;let D=0;for(x&&(u&&M!==a?(i.push({value:a}),Mr)break;i.push({value:t})}return b&&u&&w!==r?i.length&&V(i[i.length-1].value,r,xo(r,y,t))?i[i.length-1].value=r:i.push({value:r}):b&&w!==r||i.push({value:w}),i}({maxTicks:i,bounds:t.bounds,min:t.min,max:t.max,precision:e.precision,step:e.stepSize,count:e.count,maxDigits:this._maxDigits(),horizontal:this.isHorizontal(),minRotation:e.minRotation||0,includeBounds:!1!==e.includeBounds},this._range||this);return"ticks"===t.bounds&&j(n,this,"value"),t.reverse?(n.reverse(),this.start=this.max,this.end=this.min):(this.start=this.min,this.end=this.max),n}configure(){const t=this.ticks;let e=this.min,i=this.max;if(super.configure(),this.options.offset&&t.length){const s=(i-e)/Math.max(t.length-1,1)/2;e-=s,i+=s}this._startValue=e,this._endValue=i,this._valueRange=i-e}getLabelForValue(t){return ne(t,this.chart.options.locale,this.options.ticks.format)}}class _o extends bo{static id="linear";static defaults={ticks:{callback:ae.formatters.numeric}};determineDataLimits(){const{min:t,max:e}=this.getMinMax(!0);this.min=a(t)?t:0,this.max=a(e)?e:1,this.handleTickRangeOptions()}computeTickLimit(){const t=this.isHorizontal(),e=t?this.width:this.height,i=$(this.options.ticks.minRotation),s=(t?Math.sin(i):Math.cos(i))||.001,n=this._resolveTickFontOptions(0);return Math.ceil(e/Math.min(40,n.lineHeight/s))}getPixelForValue(t){return null===t?NaN:this.getPixelForDecimal((t-this._startValue)/this._valueRange)}getValueForPixel(t){return this._startValue+this.getDecimalForPixel(t)*this._valueRange}}const yo=t=>Math.floor(z(t)),vo=(t,e)=>Math.pow(10,yo(t)+e);function Mo(t){return 1===t/Math.pow(10,yo(t))}function wo(t,e,i){const s=Math.pow(10,i),n=Math.floor(t/s);return Math.ceil(e/s)-n}function ko(t,{min:e,max:i}){e=r(t.min,e);const s=[],n=yo(e);let o=function(t,e){let i=yo(e-t);for(;wo(t,e,i)>10;)i++;for(;wo(t,e,i)<10;)i--;return Math.min(i,yo(t))}(e,i),a=o<0?Math.pow(10,Math.abs(o)):1;const l=Math.pow(10,o),h=n>o?Math.pow(10,n):0,c=Math.round((e-h)*a)/a,d=Math.floor((e-h)/l/10)*l*10;let u=Math.floor((c-d)/Math.pow(10,o)),f=r(t.min,Math.round((h+d+u*Math.pow(10,o))*a)/a);for(;f=10?u=u<15?15:20:u++,u>=20&&(o++,u=2,a=o>=0?1:a),f=Math.round((h+d+u*Math.pow(10,o))*a)/a;const g=r(t.max,f);return s.push({value:g,major:Mo(g),significand:u}),s}class So extends tn{static id="logarithmic";static defaults={ticks:{callback:ae.formatters.logarithmic,major:{enabled:!0}}};constructor(t){super(t),this.start=void 0,this.end=void 0,this._startValue=void 0,this._valueRange=0}parse(t,e){const i=bo.prototype.parse.apply(this,[t,e]);if(0!==i)return a(i)&&i>0?i:null;this._zero=!0}determineDataLimits(){const{min:t,max:e}=this.getMinMax(!0);this.min=a(t)?Math.max(0,t):null,this.max=a(e)?Math.max(0,e):null,this.options.beginAtZero&&(this._zero=!0),this._zero&&this.min!==this._suggestedMin&&!a(this._userMin)&&(this.min=t===vo(this.min,0)?vo(this.min,-1):vo(this.min,0)),this.handleTickRangeOptions()}handleTickRangeOptions(){const{minDefined:t,maxDefined:e}=this.getUserBounds();let i=this.min,s=this.max;const n=e=>i=t?i:e,o=t=>s=e?s:t;i===s&&(i<=0?(n(1),o(10)):(n(vo(i,-1)),o(vo(s,1)))),i<=0&&n(vo(s,-1)),s<=0&&o(vo(i,1)),this.min=i,this.max=s}buildTicks(){const t=this.options,e=ko({min:this._userMin,max:this._userMax},this);return"ticks"===t.bounds&&j(e,this,"value"),t.reverse?(e.reverse(),this.start=this.max,this.end=this.min):(this.start=this.min,this.end=this.max),e}getLabelForValue(t){return void 0===t?"0":ne(t,this.chart.options.locale,this.options.ticks.format)}configure(){const t=this.min;super.configure(),this._startValue=z(t),this._valueRange=z(this.max)-z(t)}getPixelForValue(t){return void 0!==t&&0!==t||(t=this.min),null===t||isNaN(t)?NaN:this.getPixelForDecimal(t===this.min?0:(z(t)-this._startValue)/this._valueRange)}getValueForPixel(t){const e=this.getDecimalForPixel(t);return Math.pow(10,this._startValue+e*this._valueRange)}}function Po(t){const e=t.ticks;if(e.display&&t.display){const t=ki(e.backdropPadding);return l(e.font&&e.font.size,ue.font.size)+t.height}return 0}function Do(t,e,i,s,n){return t===s||t===n?{start:e-i/2,end:e+i/2}:tn?{start:e-i,end:e}:{start:e,end:e+i}}function Co(t){const e={l:t.left+t._padding.left,r:t.right-t._padding.right,t:t.top+t._padding.top,b:t.bottom-t._padding.bottom},i=Object.assign({},e),s=[],o=[],a=t._pointLabels.length,r=t.options.pointLabels,l=r.centerPointLabels?C/a:0;for(let u=0;ue.r&&(r=(s.end-e.r)/o,t.r=Math.max(t.r,e.r+r)),n.starte.b&&(l=(n.end-e.b)/a,t.b=Math.max(t.b,e.b+l))}function Ao(t,e,i){const s=t.drawingArea,{extra:n,additionalAngle:o,padding:a,size:r}=i,l=t.getPointPosition(e,s+n+a,o),h=Math.round(Y(G(l.angle+E))),c=function(t,e,i){90===i||270===i?t-=e/2:(i>270||i<90)&&(t-=e);return t}(l.y,r.h,h),d=function(t){if(0===t||180===t)return"center";if(t<180)return"left";return"right"}(h),u=function(t,e,i){"right"===i?t-=e:"center"===i&&(t-=e/2);return t}(l.x,r.w,d);return{visible:!0,x:l.x,y:c,textAlign:d,left:u,top:c,right:u+r.w,bottom:c+r.h}}function To(t,e){if(!e)return!0;const{left:i,top:s,right:n,bottom:o}=t;return!(Re({x:i,y:s},e)||Re({x:i,y:o},e)||Re({x:n,y:s},e)||Re({x:n,y:o},e))}function Lo(t,e,i){const{left:n,top:o,right:a,bottom:r}=i,{backdropColor:l}=e;if(!s(l)){const i=wi(e.borderRadius),s=ki(e.backdropPadding);t.fillStyle=l;const h=n-s.left,c=o-s.top,d=a-n+s.width,u=r-o+s.height;Object.values(i).some((t=>0!==t))?(t.beginPath(),He(t,{x:h,y:c,w:d,h:u,radius:i}),t.fill()):t.fillRect(h,c,d,u)}}function Eo(t,e,i,s){const{ctx:n}=t;if(i)n.arc(t.xCenter,t.yCenter,e,0,O);else{let i=t.getPointPosition(0,e);n.moveTo(i.x,i.y);for(let o=1;ot,padding:5,centerPointLabels:!1}};static defaultRoutes={"angleLines.color":"borderColor","pointLabels.color":"color","ticks.color":"color"};static descriptors={angleLines:{_fallback:"grid"}};constructor(t){super(t),this.xCenter=void 0,this.yCenter=void 0,this.drawingArea=void 0,this._pointLabels=[],this._pointLabelItems=[]}setDimensions(){const t=this._padding=ki(Po(this.options)/2),e=this.width=this.maxWidth-t.width,i=this.height=this.maxHeight-t.height;this.xCenter=Math.floor(this.left+e/2+t.left),this.yCenter=Math.floor(this.top+i/2+t.top),this.drawingArea=Math.floor(Math.min(e,i)/2)}determineDataLimits(){const{min:t,max:e}=this.getMinMax(!1);this.min=a(t)&&!isNaN(t)?t:0,this.max=a(e)&&!isNaN(e)?e:0,this.handleTickRangeOptions()}computeTickLimit(){return Math.ceil(this.drawingArea/Po(this.options))}generateTickLabels(t){bo.prototype.generateTickLabels.call(this,t),this._pointLabels=this.getLabels().map(((t,e)=>{const i=d(this.options.pointLabels.callback,[t,e],this);return i||0===i?i:""})).filter(((t,e)=>this.chart.getDataVisibility(e)))}fit(){const t=this.options;t.display&&t.pointLabels.display?Co(this):this.setCenterPoint(0,0,0,0)}setCenterPoint(t,e,i,s){this.xCenter+=Math.floor((t-e)/2),this.yCenter+=Math.floor((i-s)/2),this.drawingArea-=Math.min(this.drawingArea/2,Math.max(t,e,i,s))}getIndexAngle(t){return G(t*(O/(this._pointLabels.length||1))+$(this.options.startAngle||0))}getDistanceFromCenterForValue(t){if(s(t))return NaN;const e=this.drawingArea/(this.max-this.min);return this.options.reverse?(this.max-t)*e:(t-this.min)*e}getValueForDistanceFromCenter(t){if(s(t))return NaN;const e=t/(this.drawingArea/(this.max-this.min));return this.options.reverse?this.max-e:this.min+e}getPointLabelContext(t){const e=this._pointLabels||[];if(t>=0&&t=0;n--){const e=t._pointLabelItems[n];if(!e.visible)continue;const o=s.setContext(t.getPointLabelContext(n));Lo(i,o,e);const a=Si(o.font),{x:r,y:l,textAlign:h}=e;Ne(i,t._pointLabels[n],r,l+a.lineHeight/2,a,{color:o.color,textAlign:h,textBaseline:"middle"})}}(this,o),s.display&&this.ticks.forEach(((t,e)=>{if(0!==e||0===e&&this.min<0){r=this.getDistanceFromCenterForValue(t.value);const i=this.getContext(e),a=s.setContext(i),l=n.setContext(i);!function(t,e,i,s,n){const o=t.ctx,a=e.circular,{color:r,lineWidth:l}=e;!a&&!s||!r||!l||i<0||(o.save(),o.strokeStyle=r,o.lineWidth=l,o.setLineDash(n.dash||[]),o.lineDashOffset=n.dashOffset,o.beginPath(),Eo(t,i,a,s),o.closePath(),o.stroke(),o.restore())}(this,a,r,o,l)}})),i.display){for(t.save(),a=o-1;a>=0;a--){const s=i.setContext(this.getPointLabelContext(a)),{color:n,lineWidth:o}=s;o&&n&&(t.lineWidth=o,t.strokeStyle=n,t.setLineDash(s.borderDash),t.lineDashOffset=s.borderDashOffset,r=this.getDistanceFromCenterForValue(e.reverse?this.min:this.max),l=this.getPointPosition(a,r),t.beginPath(),t.moveTo(this.xCenter,this.yCenter),t.lineTo(l.x,l.y),t.stroke())}t.restore()}}drawBorder(){}drawLabels(){const t=this.ctx,e=this.options,i=e.ticks;if(!i.display)return;const s=this.getIndexAngle(0);let n,o;t.save(),t.translate(this.xCenter,this.yCenter),t.rotate(s),t.textAlign="center",t.textBaseline="middle",this.ticks.forEach(((s,a)=>{if(0===a&&this.min>=0&&!e.reverse)return;const r=i.setContext(this.getContext(a)),l=Si(r.font);if(n=this.getDistanceFromCenterForValue(this.ticks[a].value),r.showLabelBackdrop){t.font=l.string,o=t.measureText(s.label).width,t.fillStyle=r.backdropColor;const e=ki(r.backdropPadding);t.fillRect(-o/2-e.left,-n-l.size/2-e.top,o+e.width,l.size+e.height)}Ne(t,s.label,0,-n,l,{color:r.color,strokeColor:r.textStrokeColor,strokeWidth:r.textStrokeWidth})})),t.restore()}drawTitle(){}}const Io={millisecond:{common:!0,size:1,steps:1e3},second:{common:!0,size:1e3,steps:60},minute:{common:!0,size:6e4,steps:60},hour:{common:!0,size:36e5,steps:24},day:{common:!0,size:864e5,steps:30},week:{common:!1,size:6048e5,steps:4},month:{common:!0,size:2628e6,steps:12},quarter:{common:!1,size:7884e6,steps:4},year:{common:!0,size:3154e7}},zo=Object.keys(Io);function Fo(t,e){return t-e}function Vo(t,e){if(s(e))return null;const i=t._adapter,{parser:n,round:o,isoWeekday:r}=t._parseOpts;let l=e;return"function"==typeof n&&(l=n(l)),a(l)||(l="string"==typeof n?i.parse(l,n):i.parse(l)),null===l?null:(o&&(l="week"!==o||!N(r)&&!0!==r?i.startOf(l,o):i.startOf(l,"isoWeek",r)),+l)}function Bo(t,e,i,s){const n=zo.length;for(let o=zo.indexOf(t);o=e?i[s]:i[n]]=!0}}else t[e]=!0}function No(t,e,i){const s=[],n={},o=e.length;let a,r;for(a=0;a=0&&(e[l].major=!0);return e}(t,s,n,i):s}class Ho extends tn{static id="time";static defaults={bounds:"data",adapters:{},time:{parser:!1,unit:!1,round:!1,isoWeekday:!1,minUnit:"millisecond",displayFormats:{}},ticks:{source:"auto",callback:!1,major:{enabled:!1}}};constructor(t){super(t),this._cache={data:[],labels:[],all:[]},this._unit="day",this._majorUnit=void 0,this._offsets={},this._normalized=!1,this._parseOpts=void 0}init(t,e={}){const i=t.time||(t.time={}),s=this._adapter=new In._date(t.adapters.date);s.init(e),b(i.displayFormats,s.formats()),this._parseOpts={parser:i.parser,round:i.round,isoWeekday:i.isoWeekday},super.init(t),this._normalized=e.normalized}parse(t,e){return void 0===t?null:Vo(this,t)}beforeLayout(){super.beforeLayout(),this._cache={data:[],labels:[],all:[]}}determineDataLimits(){const t=this.options,e=this._adapter,i=t.time.unit||"day";let{min:s,max:n,minDefined:o,maxDefined:r}=this.getUserBounds();function l(t){o||isNaN(t.min)||(s=Math.min(s,t.min)),r||isNaN(t.max)||(n=Math.max(n,t.max))}o&&r||(l(this._getLabelBounds()),"ticks"===t.bounds&&"labels"===t.ticks.source||l(this.getMinMax(!1))),s=a(s)&&!isNaN(s)?s:+e.startOf(Date.now(),i),n=a(n)&&!isNaN(n)?n:+e.endOf(Date.now(),i)+1,this.min=Math.min(s,n-1),this.max=Math.max(s+1,n)}_getLabelBounds(){const t=this.getLabelTimestamps();let e=Number.POSITIVE_INFINITY,i=Number.NEGATIVE_INFINITY;return t.length&&(e=t[0],i=t[t.length-1]),{min:e,max:i}}buildTicks(){const t=this.options,e=t.time,i=t.ticks,s="labels"===i.source?this.getLabelTimestamps():this._generate();"ticks"===t.bounds&&s.length&&(this.min=this._userMin||s[0],this.max=this._userMax||s[s.length-1]);const n=this.min,o=nt(s,n,this.max);return this._unit=e.unit||(i.autoSkip?Bo(e.minUnit,this.min,this.max,this._getLabelCapacity(n)):function(t,e,i,s,n){for(let o=zo.length-1;o>=zo.indexOf(i);o--){const i=zo[o];if(Io[i].common&&t._adapter.diff(n,s,i)>=e-1)return i}return zo[i?zo.indexOf(i):0]}(this,o.length,e.minUnit,this.min,this.max)),this._majorUnit=i.major.enabled&&"year"!==this._unit?function(t){for(let e=zo.indexOf(t)+1,i=zo.length;e+t.value)))}initOffsets(t=[]){let e,i,s=0,n=0;this.options.offset&&t.length&&(e=this.getDecimalForValue(t[0]),s=1===t.length?1-e:(this.getDecimalForValue(t[1])-e)/2,i=this.getDecimalForValue(t[t.length-1]),n=1===t.length?i:(i-this.getDecimalForValue(t[t.length-2]))/2);const o=t.length<3?.5:.25;s=Z(s,0,o),n=Z(n,0,o),this._offsets={start:s,end:n,factor:1/(s+1+n)}}_generate(){const t=this._adapter,e=this.min,i=this.max,s=this.options,n=s.time,o=n.unit||Bo(n.minUnit,e,i,this._getLabelCapacity(e)),a=l(s.ticks.stepSize,1),r="week"===o&&n.isoWeekday,h=N(r)||!0===r,c={};let d,u,f=e;if(h&&(f=+t.startOf(f,"isoWeek",r)),f=+t.startOf(f,h?"day":o),t.diff(i,e,o)>1e5*a)throw new Error(e+" and "+i+" are too far apart with stepSize of "+a+" "+o);const g="data"===s.ticks.source&&this.getDataTimestamps();for(d=f,u=0;d+t))}getLabelForValue(t){const e=this._adapter,i=this.options.time;return i.tooltipFormat?e.format(t,i.tooltipFormat):e.format(t,i.displayFormats.datetime)}format(t,e){const i=this.options.time.displayFormats,s=this._unit,n=e||i[s];return this._adapter.format(t,n)}_tickFormatFunction(t,e,i,s){const n=this.options,o=n.ticks.callback;if(o)return d(o,[t,e,i],this);const a=n.time.displayFormats,r=this._unit,l=this._majorUnit,h=r&&a[r],c=l&&a[l],u=i[e],f=l&&c&&u&&u.major;return this._adapter.format(t,s||(f?c:h))}generateTickLabels(t){let e,i,s;for(e=0,i=t.length;e0?a:1}getDataTimestamps(){let t,e,i=this._cache.data||[];if(i.length)return i;const s=this.getMatchingVisibleMetas();if(this._normalized&&s.length)return this._cache.data=s[0].controller.getAllParsedValues(this);for(t=0,e=s.length;t=t[r].pos&&e<=t[l].pos&&({lo:r,hi:l}=it(t,"pos",e)),({pos:s,time:o}=t[r]),({pos:n,time:a}=t[l])):(e>=t[r].time&&e<=t[l].time&&({lo:r,hi:l}=it(t,"time",e)),({time:s,pos:o}=t[r]),({time:n,pos:a}=t[l]));const h=n-s;return h?o+(a-o)*(e-s)/h:o}var $o=Object.freeze({__proto__:null,CategoryScale:class extends tn{static id="category";static defaults={ticks:{callback:mo}};constructor(t){super(t),this._startValue=void 0,this._valueRange=0,this._addedLabels=[]}init(t){const e=this._addedLabels;if(e.length){const t=this.getLabels();for(const{index:i,label:s}of e)t[i]===s&&t.splice(i,1);this._addedLabels=[]}super.init(t)}parse(t,e){if(s(t))return null;const i=this.getLabels();return((t,e)=>null===t?null:Z(Math.round(t),0,e))(e=isFinite(e)&&i[e]===t?e:po(i,t,l(e,t),this._addedLabels),i.length-1)}determineDataLimits(){const{minDefined:t,maxDefined:e}=this.getUserBounds();let{min:i,max:s}=this.getMinMax(!0);"ticks"===this.options.bounds&&(t||(i=0),e||(s=this.getLabels().length-1)),this.min=i,this.max=s}buildTicks(){const t=this.min,e=this.max,i=this.options.offset,s=[];let n=this.getLabels();n=0===t&&e===n.length-1?n:n.slice(t,e+1),this._valueRange=Math.max(n.length-(i?0:1),1),this._startValue=this.min-(i?.5:0);for(let i=t;i<=e;i++)s.push({value:i});return s}getLabelForValue(t){return mo.call(this,t)}configure(){super.configure(),this.isHorizontal()||(this._reversePixels=!this._reversePixels)}getPixelForValue(t){return"number"!=typeof t&&(t=this.parse(t)),null===t?NaN:this.getPixelForDecimal((t-this._startValue)/this._valueRange)}getPixelForTick(t){const e=this.ticks;return t<0||t>e.length-1?null:this.getPixelForValue(e[t].value)}getValueForPixel(t){return Math.round(this._startValue+this.getDecimalForPixel(t)*this._valueRange)}getBasePixel(){return this.bottom}},LinearScale:_o,LogarithmicScale:So,RadialLinearScale:Ro,TimeScale:Ho,TimeSeriesScale:class extends Ho{static id="timeseries";static defaults=Ho.defaults;constructor(t){super(t),this._table=[],this._minPos=void 0,this._tableRange=void 0}initOffsets(){const t=this._getTimestampsForTable(),e=this._table=this.buildLookupTable(t);this._minPos=jo(e,this.min),this._tableRange=jo(e,this.max)-this._minPos,super.initOffsets(t)}buildLookupTable(t){const{min:e,max:i}=this,s=[],n=[];let o,a,r,l,h;for(o=0,a=t.length;o=e&&l<=i&&s.push(l);if(s.length<2)return[{time:e,pos:0},{time:i,pos:1}];for(o=0,a=s.length;ot-e))}_getTimestampsForTable(){let t=this._cache.all||[];if(t.length)return t;const e=this.getDataTimestamps(),i=this.getLabelTimestamps();return t=e.length&&i.length?this.normalize(e.concat(i)):e.length?e:i,t=this._cache.all=t,t}getDecimalForValue(t){return(jo(this._table,t)-this._minPos)/this._tableRange}getValueForPixel(t){const e=this._offsets,i=this.getDecimalForPixel(t)/e.factor-e.end;return jo(this._table,i*this._tableRange+this._minPos,!0)}}});const Yo=["rgb(54, 162, 235)","rgb(255, 99, 132)","rgb(255, 159, 64)","rgb(255, 205, 86)","rgb(75, 192, 192)","rgb(153, 102, 255)","rgb(201, 203, 207)"],Uo=Yo.map((t=>t.replace("rgb(","rgba(").replace(")",", 0.5)")));function Xo(t){return Yo[t%Yo.length]}function qo(t){return Uo[t%Uo.length]}function Ko(t){let e=0;return(i,s)=>{const n=t.getDatasetMeta(s).controller;n instanceof $n?e=function(t,e){return t.backgroundColor=t.data.map((()=>Xo(e++))),e}(i,e):n instanceof Yn?e=function(t,e){return t.backgroundColor=t.data.map((()=>qo(e++))),e}(i,e):n&&(e=function(t,e){return t.borderColor=Xo(e),t.backgroundColor=qo(e),++e}(i,e))}}function Go(t){let e;for(e in t)if(t[e].borderColor||t[e].backgroundColor)return!0;return!1}var Jo={id:"colors",defaults:{enabled:!0,forceOverride:!1},beforeLayout(t,e,i){if(!i.enabled)return;const{data:{datasets:s},options:n}=t.config,{elements:o}=n,a=Go(s)||(r=n)&&(r.borderColor||r.backgroundColor)||o&&Go(o)||"rgba(0,0,0,0.1)"!==ue.borderColor||"rgba(0,0,0,0.1)"!==ue.backgroundColor;var r;if(!i.forceOverride&&a)return;const l=Ko(t);s.forEach(l)}};function Zo(t){if(t._decimated){const e=t._data;delete t._decimated,delete t._data,Object.defineProperty(t,"data",{configurable:!0,enumerable:!0,writable:!0,value:e})}}function Qo(t){t.data.datasets.forEach((t=>{Zo(t)}))}var ta={id:"decimation",defaults:{algorithm:"min-max",enabled:!1},beforeElementsUpdate:(t,e,i)=>{if(!i.enabled)return void Qo(t);const n=t.width;t.data.datasets.forEach(((e,o)=>{const{_data:a,indexAxis:r}=e,l=t.getDatasetMeta(o),h=a||e.data;if("y"===Pi([r,t.options.indexAxis]))return;if(!l.controller.supportsDecimation)return;const c=t.scales[l.xAxisID];if("linear"!==c.type&&"time"!==c.type)return;if(t.options.parsing)return;let{start:d,count:u}=function(t,e){const i=e.length;let s,n=0;const{iScale:o}=t,{min:a,max:r,minDefined:l,maxDefined:h}=o.getUserBounds();return l&&(n=Z(it(e,o.axis,a).lo,0,i-1)),s=h?Z(it(e,o.axis,r).hi+1,n,i)-n:i-n,{start:n,count:s}}(l,h);if(u<=(i.threshold||4*n))return void Zo(e);let f;switch(s(a)&&(e._data=h,delete e.data,Object.defineProperty(e,"data",{configurable:!0,enumerable:!0,get:function(){return this._decimated},set:function(t){this._data=t}})),i.algorithm){case"lttb":f=function(t,e,i,s,n){const o=n.samples||s;if(o>=i)return t.slice(e,e+i);const a=[],r=(i-2)/(o-2);let l=0;const h=e+i-1;let c,d,u,f,g,p=e;for(a[l++]=t[p],c=0;cu&&(u=f,d=t[s],g=s);a[l++]=d,p=g}return a[l++]=t[h],a}(h,d,u,n,i);break;case"min-max":f=function(t,e,i,n){let o,a,r,l,h,c,d,u,f,g,p=0,m=0;const x=[],b=e+i-1,_=t[e].x,y=t[b].x-_;for(o=e;og&&(g=l,d=o),p=(m*p+a.x)/++m;else{const i=o-1;if(!s(c)&&!s(d)){const e=Math.min(c,d),s=Math.max(c,d);e!==u&&e!==i&&x.push({...t[e],x:p}),s!==u&&s!==i&&x.push({...t[s],x:p})}o>0&&i!==u&&x.push(t[i]),x.push(a),h=e,m=0,f=g=l,c=d=u=o}}return x}(h,d,u,n);break;default:throw new Error(`Unsupported decimation algorithm '${i.algorithm}'`)}e._decimated=f}))},destroy(t){Qo(t)}};function ea(t,e,i,s){if(s)return;let n=e[t],o=i[t];return"angle"===t&&(n=G(n),o=G(o)),{property:t,start:n,end:o}}function ia(t,e,i){for(;e>t;e--){const t=i[e];if(!isNaN(t.x)&&!isNaN(t.y))break}return e}function sa(t,e,i,s){return t&&e?s(t[i],e[i]):t?t[i]:e?e[i]:0}function na(t,e){let i=[],s=!1;return n(t)?(s=!0,i=t):i=function(t,e){const{x:i=null,y:s=null}=t||{},n=e.points,o=[];return e.segments.forEach((({start:t,end:e})=>{e=ia(t,e,n);const a=n[t],r=n[e];null!==s?(o.push({x:a.x,y:s}),o.push({x:r.x,y:s})):null!==i&&(o.push({x:i,y:a.y}),o.push({x:i,y:r.y}))})),o}(t,e),i.length?new oo({points:i,options:{tension:0},_loop:s,_fullLoop:s}):null}function oa(t){return t&&!1!==t.fill}function aa(t,e,i){let s=t[e].fill;const n=[e];let o;if(!i)return s;for(;!1!==s&&-1===n.indexOf(s);){if(!a(s))return s;if(o=t[s],!o)return!1;if(o.visible)return s;n.push(s),s=o.fill}return!1}function ra(t,e,i){const s=function(t){const e=t.options,i=e.fill;let s=l(i&&i.target,i);void 0===s&&(s=!!e.backgroundColor);if(!1===s||null===s)return!1;if(!0===s)return"origin";return s}(t);if(o(s))return!isNaN(s.value)&&s;let n=parseFloat(s);return a(n)&&Math.floor(n)===n?function(t,e,i,s){"-"!==t&&"+"!==t||(i=e+i);if(i===e||i<0||i>=s)return!1;return i}(s[0],e,n,i):["origin","start","end","stack","shape"].indexOf(s)>=0&&s}function la(t,e,i){const s=[];for(let n=0;n=0;--e){const i=n[e].$filler;i&&(i.line.updateControlPoints(o,i.axis),s&&i.fill&&ua(t.ctx,i,o))}},beforeDatasetsDraw(t,e,i){if("beforeDatasetsDraw"!==i.drawTime)return;const s=t.getSortedVisibleDatasetMetas();for(let e=s.length-1;e>=0;--e){const i=s[e].$filler;oa(i)&&ua(t.ctx,i,t.chartArea)}},beforeDatasetDraw(t,e,i){const s=e.meta.$filler;oa(s)&&"beforeDatasetDraw"===i.drawTime&&ua(t.ctx,s,t.chartArea)},defaults:{propagate:!0,drawTime:"beforeDatasetDraw"}};const _a=(t,e)=>{let{boxHeight:i=e,boxWidth:s=e}=t;return t.usePointStyle&&(i=Math.min(i,e),s=t.pointStyleWidth||Math.min(s,e)),{boxWidth:s,boxHeight:i,itemHeight:Math.max(e,i)}};class ya extends $s{constructor(t){super(),this._added=!1,this.legendHitBoxes=[],this._hoveredItem=null,this.doughnutMode=!1,this.chart=t.chart,this.options=t.options,this.ctx=t.ctx,this.legendItems=void 0,this.columnSizes=void 0,this.lineWidths=void 0,this.maxHeight=void 0,this.maxWidth=void 0,this.top=void 0,this.bottom=void 0,this.left=void 0,this.right=void 0,this.height=void 0,this.width=void 0,this._margins=void 0,this.position=void 0,this.weight=void 0,this.fullSize=void 0}update(t,e,i){this.maxWidth=t,this.maxHeight=e,this._margins=i,this.setDimensions(),this.buildLabels(),this.fit()}setDimensions(){this.isHorizontal()?(this.width=this.maxWidth,this.left=this._margins.left,this.right=this.width):(this.height=this.maxHeight,this.top=this._margins.top,this.bottom=this.height)}buildLabels(){const t=this.options.labels||{};let e=d(t.generateLabels,[this.chart],this)||[];t.filter&&(e=e.filter((e=>t.filter(e,this.chart.data)))),t.sort&&(e=e.sort(((e,i)=>t.sort(e,i,this.chart.data)))),this.options.reverse&&e.reverse(),this.legendItems=e}fit(){const{options:t,ctx:e}=this;if(!t.display)return void(this.width=this.height=0);const i=t.labels,s=Si(i.font),n=s.size,o=this._computeTitleHeight(),{boxWidth:a,itemHeight:r}=_a(i,n);let l,h;e.font=s.string,this.isHorizontal()?(l=this.maxWidth,h=this._fitRows(o,n,a,r)+10):(h=this.maxHeight,l=this._fitCols(o,s,a,r)+10),this.width=Math.min(l,t.maxWidth||this.maxWidth),this.height=Math.min(h,t.maxHeight||this.maxHeight)}_fitRows(t,e,i,s){const{ctx:n,maxWidth:o,options:{labels:{padding:a}}}=this,r=this.legendHitBoxes=[],l=this.lineWidths=[0],h=s+a;let c=t;n.textAlign="left",n.textBaseline="middle";let d=-1,u=-h;return this.legendItems.forEach(((t,f)=>{const g=i+e/2+n.measureText(t.text).width;(0===f||l[l.length-1]+g+2*a>o)&&(c+=h,l[l.length-(f>0?0:1)]=0,u+=h,d++),r[f]={left:0,top:u,row:d,width:g,height:s},l[l.length-1]+=g+a})),c}_fitCols(t,e,i,s){const{ctx:n,maxHeight:o,options:{labels:{padding:a}}}=this,r=this.legendHitBoxes=[],l=this.columnSizes=[],h=o-t;let c=a,d=0,u=0,f=0,g=0;return this.legendItems.forEach(((t,o)=>{const{itemWidth:p,itemHeight:m}=function(t,e,i,s,n){const o=function(t,e,i,s){let n=t.text;n&&"string"!=typeof n&&(n=n.reduce(((t,e)=>t.length>e.length?t:e)));return e+i.size/2+s.measureText(n).width}(s,t,e,i),a=function(t,e,i){let s=t;"string"!=typeof e.text&&(s=va(e,i));return s}(n,s,e.lineHeight);return{itemWidth:o,itemHeight:a}}(i,e,n,t,s);o>0&&u+m+2*a>h&&(c+=d+a,l.push({width:d,height:u}),f+=d+a,g++,d=u=0),r[o]={left:f,top:u,col:g,width:p,height:m},d=Math.max(d,p),u+=m+a})),c+=d,l.push({width:d,height:u}),c}adjustHitBoxes(){if(!this.options.display)return;const t=this._computeTitleHeight(),{legendHitBoxes:e,options:{align:i,labels:{padding:s},rtl:n}}=this,o=Oi(n,this.left,this.width);if(this.isHorizontal()){let n=0,a=ft(i,this.left+s,this.right-this.lineWidths[n]);for(const r of e)n!==r.row&&(n=r.row,a=ft(i,this.left+s,this.right-this.lineWidths[n])),r.top+=this.top+t+s,r.left=o.leftForLtr(o.x(a),r.width),a+=r.width+s}else{let n=0,a=ft(i,this.top+t+s,this.bottom-this.columnSizes[n].height);for(const r of e)r.col!==n&&(n=r.col,a=ft(i,this.top+t+s,this.bottom-this.columnSizes[n].height)),r.top=a,r.left+=this.left+s,r.left=o.leftForLtr(o.x(r.left),r.width),a+=r.height+s}}isHorizontal(){return"top"===this.options.position||"bottom"===this.options.position}draw(){if(this.options.display){const t=this.ctx;Ie(t,this),this._draw(),ze(t)}}_draw(){const{options:t,columnSizes:e,lineWidths:i,ctx:s}=this,{align:n,labels:o}=t,a=ue.color,r=Oi(t.rtl,this.left,this.width),h=Si(o.font),{padding:c}=o,d=h.size,u=d/2;let f;this.drawTitle(),s.textAlign=r.textAlign("left"),s.textBaseline="middle",s.lineWidth=.5,s.font=h.string;const{boxWidth:g,boxHeight:p,itemHeight:m}=_a(o,d),x=this.isHorizontal(),b=this._computeTitleHeight();f=x?{x:ft(n,this.left+c,this.right-i[0]),y:this.top+c+b,line:0}:{x:this.left+c,y:ft(n,this.top+b+c,this.bottom-e[0].height),line:0},Ai(this.ctx,t.textDirection);const _=m+c;this.legendItems.forEach(((y,v)=>{s.strokeStyle=y.fontColor,s.fillStyle=y.fontColor;const M=s.measureText(y.text).width,w=r.textAlign(y.textAlign||(y.textAlign=o.textAlign)),k=g+u+M;let S=f.x,P=f.y;r.setWidth(this.width),x?v>0&&S+k+c>this.right&&(P=f.y+=_,f.line++,S=f.x=ft(n,this.left+c,this.right-i[f.line])):v>0&&P+_>this.bottom&&(S=f.x=S+e[f.line].width+c,f.line++,P=f.y=ft(n,this.top+b+c,this.bottom-e[f.line].height));if(function(t,e,i){if(isNaN(g)||g<=0||isNaN(p)||p<0)return;s.save();const n=l(i.lineWidth,1);if(s.fillStyle=l(i.fillStyle,a),s.lineCap=l(i.lineCap,"butt"),s.lineDashOffset=l(i.lineDashOffset,0),s.lineJoin=l(i.lineJoin,"miter"),s.lineWidth=n,s.strokeStyle=l(i.strokeStyle,a),s.setLineDash(l(i.lineDash,[])),o.usePointStyle){const a={radius:p*Math.SQRT2/2,pointStyle:i.pointStyle,rotation:i.rotation,borderWidth:n},l=r.xPlus(t,g/2);Ee(s,a,l,e+u,o.pointStyleWidth&&g)}else{const o=e+Math.max((d-p)/2,0),a=r.leftForLtr(t,g),l=wi(i.borderRadius);s.beginPath(),Object.values(l).some((t=>0!==t))?He(s,{x:a,y:o,w:g,h:p,radius:l}):s.rect(a,o,g,p),s.fill(),0!==n&&s.stroke()}s.restore()}(r.x(S),P,y),S=gt(w,S+g+u,x?S+k:this.right,t.rtl),function(t,e,i){Ne(s,i.text,t,e+m/2,h,{strikethrough:i.hidden,textAlign:r.textAlign(i.textAlign)})}(r.x(S),P,y),x)f.x+=k+c;else if("string"!=typeof y.text){const t=h.lineHeight;f.y+=va(y,t)+c}else f.y+=_})),Ti(this.ctx,t.textDirection)}drawTitle(){const t=this.options,e=t.title,i=Si(e.font),s=ki(e.padding);if(!e.display)return;const n=Oi(t.rtl,this.left,this.width),o=this.ctx,a=e.position,r=i.size/2,l=s.top+r;let h,c=this.left,d=this.width;if(this.isHorizontal())d=Math.max(...this.lineWidths),h=this.top+l,c=ft(t.align,c,this.right-d);else{const e=this.columnSizes.reduce(((t,e)=>Math.max(t,e.height)),0);h=l+ft(t.align,this.top,this.bottom-e-t.labels.padding-this._computeTitleHeight())}const u=ft(a,c,c+d);o.textAlign=n.textAlign(ut(a)),o.textBaseline="middle",o.strokeStyle=e.color,o.fillStyle=e.color,o.font=i.string,Ne(o,e.text,u,h,i)}_computeTitleHeight(){const t=this.options.title,e=Si(t.font),i=ki(t.padding);return t.display?e.lineHeight+i.height:0}_getLegendItemAt(t,e){let i,s,n;if(tt(t,this.left,this.right)&&tt(e,this.top,this.bottom))for(n=this.legendHitBoxes,i=0;it.chart.options.color,boxWidth:40,padding:10,generateLabels(t){const e=t.data.datasets,{labels:{usePointStyle:i,pointStyle:s,textAlign:n,color:o,useBorderRadius:a,borderRadius:r}}=t.legend.options;return t._getSortedDatasetMetas().map((t=>{const l=t.controller.getStyle(i?0:void 0),h=ki(l.borderWidth);return{text:e[t.index].label,fillStyle:l.backgroundColor,fontColor:o,hidden:!t.visible,lineCap:l.borderCapStyle,lineDash:l.borderDash,lineDashOffset:l.borderDashOffset,lineJoin:l.borderJoinStyle,lineWidth:(h.width+h.height)/4,strokeStyle:l.borderColor,pointStyle:s||l.pointStyle,rotation:l.rotation,textAlign:n||l.textAlign,borderRadius:a&&(r||l.borderRadius),datasetIndex:t.index}}),this)}},title:{color:t=>t.chart.options.color,display:!1,position:"center",text:""}},descriptors:{_scriptable:t=>!t.startsWith("on"),labels:{_scriptable:t=>!["generateLabels","filter","sort"].includes(t)}}};class wa extends $s{constructor(t){super(),this.chart=t.chart,this.options=t.options,this.ctx=t.ctx,this._padding=void 0,this.top=void 0,this.bottom=void 0,this.left=void 0,this.right=void 0,this.width=void 0,this.height=void 0,this.position=void 0,this.weight=void 0,this.fullSize=void 0}update(t,e){const i=this.options;if(this.left=0,this.top=0,!i.display)return void(this.width=this.height=this.right=this.bottom=0);this.width=this.right=t,this.height=this.bottom=e;const s=n(i.text)?i.text.length:1;this._padding=ki(i.padding);const o=s*Si(i.font).lineHeight+this._padding.height;this.isHorizontal()?this.height=o:this.width=o}isHorizontal(){const t=this.options.position;return"top"===t||"bottom"===t}_drawArgs(t){const{top:e,left:i,bottom:s,right:n,options:o}=this,a=o.align;let r,l,h,c=0;return this.isHorizontal()?(l=ft(a,i,n),h=e+t,r=n-i):("left"===o.position?(l=i+t,h=ft(a,s,e),c=-.5*C):(l=n-t,h=ft(a,e,s),c=.5*C),r=s-e),{titleX:l,titleY:h,maxWidth:r,rotation:c}}draw(){const t=this.ctx,e=this.options;if(!e.display)return;const i=Si(e.font),s=i.lineHeight/2+this._padding.top,{titleX:n,titleY:o,maxWidth:a,rotation:r}=this._drawArgs(s);Ne(t,e.text,0,0,i,{color:e.color,maxWidth:a,rotation:r,textAlign:ut(e.align),textBaseline:"middle",translation:[n,o]})}}var ka={id:"title",_element:wa,start(t,e,i){!function(t,e){const i=new wa({ctx:t.ctx,options:e,chart:t});ls.configure(t,i,e),ls.addBox(t,i),t.titleBlock=i}(t,i)},stop(t){const e=t.titleBlock;ls.removeBox(t,e),delete t.titleBlock},beforeUpdate(t,e,i){const s=t.titleBlock;ls.configure(t,s,i),s.options=i},defaults:{align:"center",display:!1,font:{weight:"bold"},fullSize:!0,padding:10,position:"top",text:"",weight:2e3},defaultRoutes:{color:"color"},descriptors:{_scriptable:!0,_indexable:!1}};const Sa=new WeakMap;var Pa={id:"subtitle",start(t,e,i){const s=new wa({ctx:t.ctx,options:i,chart:t});ls.configure(t,s,i),ls.addBox(t,s),Sa.set(t,s)},stop(t){ls.removeBox(t,Sa.get(t)),Sa.delete(t)},beforeUpdate(t,e,i){const s=Sa.get(t);ls.configure(t,s,i),s.options=i},defaults:{align:"center",display:!1,font:{weight:"normal"},fullSize:!0,padding:0,position:"top",text:"",weight:1500},defaultRoutes:{color:"color"},descriptors:{_scriptable:!0,_indexable:!1}};const Da={average(t){if(!t.length)return!1;let e,i,s=new Set,n=0,o=0;for(e=0,i=t.length;et+e))/s.size,y:n/o}},nearest(t,e){if(!t.length)return!1;let i,s,n,o=e.x,a=e.y,r=Number.POSITIVE_INFINITY;for(i=0,s=t.length;i-1?t.split("\n"):t}function Aa(t,e){const{element:i,datasetIndex:s,index:n}=e,o=t.getDatasetMeta(s).controller,{label:a,value:r}=o.getLabelAndValue(n);return{chart:t,label:a,parsed:o.getParsed(n),raw:t.data.datasets[s].data[n],formattedValue:r,dataset:o.getDataset(),dataIndex:n,datasetIndex:s,element:i}}function Ta(t,e){const i=t.chart.ctx,{body:s,footer:n,title:o}=t,{boxWidth:a,boxHeight:r}=e,l=Si(e.bodyFont),h=Si(e.titleFont),c=Si(e.footerFont),d=o.length,f=n.length,g=s.length,p=ki(e.padding);let m=p.height,x=0,b=s.reduce(((t,e)=>t+e.before.length+e.lines.length+e.after.length),0);if(b+=t.beforeBody.length+t.afterBody.length,d&&(m+=d*h.lineHeight+(d-1)*e.titleSpacing+e.titleMarginBottom),b){m+=g*(e.displayColors?Math.max(r,l.lineHeight):l.lineHeight)+(b-g)*l.lineHeight+(b-1)*e.bodySpacing}f&&(m+=e.footerMarginTop+f*c.lineHeight+(f-1)*e.footerSpacing);let _=0;const y=function(t){x=Math.max(x,i.measureText(t).width+_)};return i.save(),i.font=h.string,u(t.title,y),i.font=l.string,u(t.beforeBody.concat(t.afterBody),y),_=e.displayColors?a+2+e.boxPadding:0,u(s,(t=>{u(t.before,y),u(t.lines,y),u(t.after,y)})),_=0,i.font=c.string,u(t.footer,y),i.restore(),x+=p.width,{width:x,height:m}}function La(t,e,i,s){const{x:n,width:o}=i,{width:a,chartArea:{left:r,right:l}}=t;let h="center";return"center"===s?h=n<=(r+l)/2?"left":"right":n<=o/2?h="left":n>=a-o/2&&(h="right"),function(t,e,i,s){const{x:n,width:o}=s,a=i.caretSize+i.caretPadding;return"left"===t&&n+o+a>e.width||"right"===t&&n-o-a<0||void 0}(h,t,e,i)&&(h="center"),h}function Ea(t,e,i){const s=i.yAlign||e.yAlign||function(t,e){const{y:i,height:s}=e;return it.height-s/2?"bottom":"center"}(t,i);return{xAlign:i.xAlign||e.xAlign||La(t,e,i,s),yAlign:s}}function Ra(t,e,i,s){const{caretSize:n,caretPadding:o,cornerRadius:a}=t,{xAlign:r,yAlign:l}=i,h=n+o,{topLeft:c,topRight:d,bottomLeft:u,bottomRight:f}=wi(a);let g=function(t,e){let{x:i,width:s}=t;return"right"===e?i-=s:"center"===e&&(i-=s/2),i}(e,r);const p=function(t,e,i){let{y:s,height:n}=t;return"top"===e?s+=i:s-="bottom"===e?n+i:n/2,s}(e,l,h);return"center"===l?"left"===r?g+=h:"right"===r&&(g-=h):"left"===r?g-=Math.max(c,u)+n:"right"===r&&(g+=Math.max(d,f)+n),{x:Z(g,0,s.width-e.width),y:Z(p,0,s.height-e.height)}}function Ia(t,e,i){const s=ki(i.padding);return"center"===e?t.x+t.width/2:"right"===e?t.x+t.width-s.right:t.x+s.left}function za(t){return Ca([],Oa(t))}function Fa(t,e){const i=e&&e.dataset&&e.dataset.tooltip&&e.dataset.tooltip.callbacks;return i?t.override(i):t}const Va={beforeTitle:e,title(t){if(t.length>0){const e=t[0],i=e.chart.data.labels,s=i?i.length:0;if(this&&this.options&&"dataset"===this.options.mode)return e.dataset.label||"";if(e.label)return e.label;if(s>0&&e.dataIndex{const e={before:[],lines:[],after:[]},n=Fa(i,t);Ca(e.before,Oa(Ba(n,"beforeLabel",this,t))),Ca(e.lines,Ba(n,"label",this,t)),Ca(e.after,Oa(Ba(n,"afterLabel",this,t))),s.push(e)})),s}getAfterBody(t,e){return za(Ba(e.callbacks,"afterBody",this,t))}getFooter(t,e){const{callbacks:i}=e,s=Ba(i,"beforeFooter",this,t),n=Ba(i,"footer",this,t),o=Ba(i,"afterFooter",this,t);let a=[];return a=Ca(a,Oa(s)),a=Ca(a,Oa(n)),a=Ca(a,Oa(o)),a}_createItems(t){const e=this._active,i=this.chart.data,s=[],n=[],o=[];let a,r,l=[];for(a=0,r=e.length;at.filter(e,s,n,i)))),t.itemSort&&(l=l.sort(((e,s)=>t.itemSort(e,s,i)))),u(l,(e=>{const i=Fa(t.callbacks,e);s.push(Ba(i,"labelColor",this,e)),n.push(Ba(i,"labelPointStyle",this,e)),o.push(Ba(i,"labelTextColor",this,e))})),this.labelColors=s,this.labelPointStyles=n,this.labelTextColors=o,this.dataPoints=l,l}update(t,e){const i=this.options.setContext(this.getContext()),s=this._active;let n,o=[];if(s.length){const t=Da[i.position].call(this,s,this._eventPosition);o=this._createItems(i),this.title=this.getTitle(o,i),this.beforeBody=this.getBeforeBody(o,i),this.body=this.getBody(o,i),this.afterBody=this.getAfterBody(o,i),this.footer=this.getFooter(o,i);const e=this._size=Ta(this,i),a=Object.assign({},t,e),r=Ea(this.chart,i,a),l=Ra(i,a,r,this.chart);this.xAlign=r.xAlign,this.yAlign=r.yAlign,n={opacity:1,x:l.x,y:l.y,width:e.width,height:e.height,caretX:t.x,caretY:t.y}}else 0!==this.opacity&&(n={opacity:0});this._tooltipItems=o,this.$context=void 0,n&&this._resolveAnimations().update(this,n),t&&i.external&&i.external.call(this,{chart:this.chart,tooltip:this,replay:e})}drawCaret(t,e,i,s){const n=this.getCaretPosition(t,i,s);e.lineTo(n.x1,n.y1),e.lineTo(n.x2,n.y2),e.lineTo(n.x3,n.y3)}getCaretPosition(t,e,i){const{xAlign:s,yAlign:n}=this,{caretSize:o,cornerRadius:a}=i,{topLeft:r,topRight:l,bottomLeft:h,bottomRight:c}=wi(a),{x:d,y:u}=t,{width:f,height:g}=e;let p,m,x,b,_,y;return"center"===n?(_=u+g/2,"left"===s?(p=d,m=p-o,b=_+o,y=_-o):(p=d+f,m=p+o,b=_-o,y=_+o),x=p):(m="left"===s?d+Math.max(r,h)+o:"right"===s?d+f-Math.max(l,c)-o:this.caretX,"top"===n?(b=u,_=b-o,p=m-o,x=m+o):(b=u+g,_=b+o,p=m+o,x=m-o),y=b),{x1:p,x2:m,x3:x,y1:b,y2:_,y3:y}}drawTitle(t,e,i){const s=this.title,n=s.length;let o,a,r;if(n){const l=Oi(i.rtl,this.x,this.width);for(t.x=Ia(this,i.titleAlign,i),e.textAlign=l.textAlign(i.titleAlign),e.textBaseline="middle",o=Si(i.titleFont),a=i.titleSpacing,e.fillStyle=i.titleColor,e.font=o.string,r=0;r0!==t))?(t.beginPath(),t.fillStyle=n.multiKeyBackground,He(t,{x:e,y:g,w:h,h:l,radius:r}),t.fill(),t.stroke(),t.fillStyle=a.backgroundColor,t.beginPath(),He(t,{x:i,y:g+1,w:h-2,h:l-2,radius:r}),t.fill()):(t.fillStyle=n.multiKeyBackground,t.fillRect(e,g,h,l),t.strokeRect(e,g,h,l),t.fillStyle=a.backgroundColor,t.fillRect(i,g+1,h-2,l-2))}t.fillStyle=this.labelTextColors[i]}drawBody(t,e,i){const{body:s}=this,{bodySpacing:n,bodyAlign:o,displayColors:a,boxHeight:r,boxWidth:l,boxPadding:h}=i,c=Si(i.bodyFont);let d=c.lineHeight,f=0;const g=Oi(i.rtl,this.x,this.width),p=function(i){e.fillText(i,g.x(t.x+f),t.y+d/2),t.y+=d+n},m=g.textAlign(o);let x,b,_,y,v,M,w;for(e.textAlign=o,e.textBaseline="middle",e.font=c.string,t.x=Ia(this,m,i),e.fillStyle=i.bodyColor,u(this.beforeBody,p),f=a&&"right"!==m?"center"===o?l/2+h:l+2+h:0,y=0,M=s.length;y0&&e.stroke()}_updateAnimationTarget(t){const e=this.chart,i=this.$animations,s=i&&i.x,n=i&&i.y;if(s||n){const i=Da[t.position].call(this,this._active,this._eventPosition);if(!i)return;const o=this._size=Ta(this,t),a=Object.assign({},i,this._size),r=Ea(e,t,a),l=Ra(t,a,r,e);s._to===l.x&&n._to===l.y||(this.xAlign=r.xAlign,this.yAlign=r.yAlign,this.width=o.width,this.height=o.height,this.caretX=i.x,this.caretY=i.y,this._resolveAnimations().update(this,l))}}_willRender(){return!!this.opacity}draw(t){const e=this.options.setContext(this.getContext());let i=this.opacity;if(!i)return;this._updateAnimationTarget(e);const s={width:this.width,height:this.height},n={x:this.x,y:this.y};i=Math.abs(i)<.001?0:i;const o=ki(e.padding),a=this.title.length||this.beforeBody.length||this.body.length||this.afterBody.length||this.footer.length;e.enabled&&a&&(t.save(),t.globalAlpha=i,this.drawBackground(n,t,s,e),Ai(t,e.textDirection),n.y+=o.top,this.drawTitle(n,t,e),this.drawBody(n,t,e),this.drawFooter(n,t,e),Ti(t,e.textDirection),t.restore())}getActiveElements(){return this._active||[]}setActiveElements(t,e){const i=this._active,s=t.map((({datasetIndex:t,index:e})=>{const i=this.chart.getDatasetMeta(t);if(!i)throw new Error("Cannot find a dataset at index "+t);return{datasetIndex:t,element:i.data[e],index:e}})),n=!f(i,s),o=this._positionChanged(s,e);(n||o)&&(this._active=s,this._eventPosition=e,this._ignoreReplayEvents=!0,this.update(!0))}handleEvent(t,e,i=!0){if(e&&this._ignoreReplayEvents)return!1;this._ignoreReplayEvents=!1;const s=this.options,n=this._active||[],o=this._getActiveElements(t,n,e,i),a=this._positionChanged(o,t),r=e||!f(o,n)||a;return r&&(this._active=o,(s.enabled||s.external)&&(this._eventPosition={x:t.x,y:t.y},this.update(!0,e))),r}_getActiveElements(t,e,i,s){const n=this.options;if("mouseout"===t.type)return[];if(!s)return e.filter((t=>this.chart.data.datasets[t.datasetIndex]&&void 0!==this.chart.getDatasetMeta(t.datasetIndex).controller.getParsed(t.index)));const o=this.chart.getElementsAtEventForMode(t,n.mode,n,i);return n.reverse&&o.reverse(),o}_positionChanged(t,e){const{caretX:i,caretY:s,options:n}=this,o=Da[n.position].call(this,t,e);return!1!==o&&(i!==o.x||s!==o.y)}}var Na={id:"tooltip",_element:Wa,positioners:Da,afterInit(t,e,i){i&&(t.tooltip=new Wa({chart:t,options:i}))},beforeUpdate(t,e,i){t.tooltip&&t.tooltip.initialize(i)},reset(t,e,i){t.tooltip&&t.tooltip.initialize(i)},afterDraw(t){const e=t.tooltip;if(e&&e._willRender()){const i={tooltip:e};if(!1===t.notifyPlugins("beforeTooltipDraw",{...i,cancelable:!0}))return;e.draw(t.ctx),t.notifyPlugins("afterTooltipDraw",i)}},afterEvent(t,e){if(t.tooltip){const i=e.replay;t.tooltip.handleEvent(e.event,i,e.inChartArea)&&(e.changed=!0)}},defaults:{enabled:!0,external:null,position:"average",backgroundColor:"rgba(0,0,0,0.8)",titleColor:"#fff",titleFont:{weight:"bold"},titleSpacing:2,titleMarginBottom:6,titleAlign:"left",bodyColor:"#fff",bodySpacing:2,bodyFont:{},bodyAlign:"left",footerColor:"#fff",footerSpacing:2,footerMarginTop:6,footerFont:{weight:"bold"},footerAlign:"left",padding:6,caretPadding:2,caretSize:5,cornerRadius:6,boxHeight:(t,e)=>e.bodyFont.size,boxWidth:(t,e)=>e.bodyFont.size,multiKeyBackground:"#fff",displayColors:!0,boxPadding:0,borderColor:"rgba(0,0,0,0)",borderWidth:0,animation:{duration:400,easing:"easeOutQuart"},animations:{numbers:{type:"number",properties:["x","y","width","height","caretX","caretY"]},opacity:{easing:"linear",duration:200}},callbacks:Va},defaultRoutes:{bodyFont:"font",footerFont:"font",titleFont:"font"},descriptors:{_scriptable:t=>"filter"!==t&&"itemSort"!==t&&"external"!==t,_indexable:!1,callbacks:{_scriptable:!1,_indexable:!1},animation:{_fallback:!1},animations:{_fallback:"animation"}},additionalOptionScopes:["interaction"]};return Tn.register(Un,$o,go,t),Tn.helpers={...Hi},Tn._adapters=In,Tn.Animation=As,Tn.Animations=Ts,Tn.animator=bt,Tn.controllers=nn.controllers.items,Tn.DatasetController=js,Tn.Element=$s,Tn.elements=go,Tn.Interaction=Ki,Tn.layouts=ls,Tn.platforms=Ds,Tn.Scale=tn,Tn.Ticks=ae,Object.assign(Tn,Un,$o,go,t,Ds),Tn.Chart=Tn,"undefined"!=typeof window&&(window.Chart=Tn),Tn})); +//# sourceMappingURL=chart.umd.js.map diff --git a/.claude/skills/session-metrics/scripts/vendor/charts/highcharts/v12/LICENSE.txt b/.claude/skills/session-metrics/scripts/vendor/charts/highcharts/v12/LICENSE.txt new file mode 100644 index 0000000..2dcc61d --- /dev/null +++ b/.claude/skills/session-metrics/scripts/vendor/charts/highcharts/v12/LICENSE.txt @@ -0,0 +1,22 @@ +Highcharts — Non-Commercial License +===================================== + +The vendored Highcharts files in this directory are redistributed under +Highcharts' Non-Commercial License. Free for personal, school, and +non-profit use. Commercial use requires a paid license from Highsoft AS. + +Upstream: https://www.highcharts.com/license +Version: 12 (fetched from https://cdn.jsdelivr.net/npm/highcharts@12/) + +If you intend to ship `session-metrics` as part of a commercial product, +or redistribute reports generated with the Highcharts renderer within a +commercial offering, either (a) obtain a Highcharts commercial license, +or (b) pass `--chart-lib none` (or switch to an MIT-licensed renderer +once we add uPlot / Chart.js vendoring) so no Highcharts code is emitted. + +For personal, educational, or non-commercial internal tooling use: +this is the default licensing and you do not need any additional +permission from Highsoft AS. + +None of the above is legal advice; consult the upstream license if you +are unsure whether your use case qualifies. diff --git a/.claude/skills/session-metrics/scripts/vendor/charts/highcharts/v12/export-data.js b/.claude/skills/session-metrics/scripts/vendor/charts/highcharts/v12/export-data.js new file mode 100644 index 0000000..e637854 --- /dev/null +++ b/.claude/skills/session-metrics/scripts/vendor/charts/highcharts/v12/export-data.js @@ -0,0 +1,14 @@ +!/** + * Highcharts JS v12.6.0 (2026-04-13) + * @module highcharts/modules/export-data + * @requires highcharts + * @requires highcharts/modules/exporting + * + * Export data module + * + * (c) 2010-2026 Highsoft AS + * Author: Torstein Hønsi + * + * A commercial license may be required depending on use. + * See www.highcharts.com/license + */function(t,e){"object"==typeof exports&&"object"==typeof module?module.exports=e(t._Highcharts,t._Highcharts.AST,t._Highcharts.Chart):"function"==typeof define&&define.amd?define("highcharts/modules/export-data",["highcharts/highcharts"],function(t){return e(t,t.AST,t.Chart)}):"object"==typeof exports?exports["highcharts/modules/export-data"]=e(t._Highcharts,t._Highcharts.AST,t._Highcharts.Chart):t.Highcharts=e(t.Highcharts,t.Highcharts.AST,t.Highcharts.Chart)}("u"(()=>{"use strict";var o,a={660:t=>{t.exports=e},944:e=>{e.exports=t},960:t=>{t.exports=n}},r={};function i(t){var e=r[t];if(void 0!==e)return e.exports;var n=r[t]={exports:{}};return a[t](n,n.exports,i),n.exports}i.n=t=>{var e=t&&t.__esModule?()=>t.default:()=>t;return i.d(e,{a:e}),e},i.d=(t,e)=>{for(var n in e)i.o(e,n)&&!i.o(t,n)&&Object.defineProperty(t,n,{enumerable:!0,get:e[n]})},i.o=(t,e)=>Object.prototype.hasOwnProperty.call(t,e);var l={};i.d(l,{default:()=>F});var s=i(944),c=i.n(s);let{isSafari:h,win:d,win:{document:p}}=c(),u=d.URL||d.webkitURL||d;function f(t){let e=t.replace(/filename=.*;/,"").match(/data:([^;]*)(;base64)?,([A-Z+\d\/]+)/i);if(e&&e.length>3&&d.atob&&d.ArrayBuffer&&d.Uint8Array&&d.Blob&&u.createObjectURL){let t=d.atob(e[3]),n=new d.ArrayBuffer(t.length),o=new d.Uint8Array(n);for(let e=0;e1e3)throw Error("Input too long");let a=/Edge\/\d+/.test(n.userAgent);if((h&&"string"==typeof t&&0===t.indexOf("data:application/pdf")||a||t.length>2e6)&&!(t=f(t)||""))throw Error("Failed to convert to blob");if(void 0!==o.download)o.href=t,o.download=e,p.body.appendChild(o),o.click(),p.body.removeChild(o);else try{if(!d.open(t,"chart"))throw Error("Failed to open window")}catch{d.location.href=t}}function m(t,e){let n=d.navigator,o=d.URL||d.webkitURL||d;try{if(n.msSaveOrOpenBlob&&d.MSBlobBuilder){let e=new d.MSBlobBuilder;return e.append(t),e.getBlob("image/svg+xml")}return o.createObjectURL(new d.Blob(["\uFEFF"+t],{type:e}))}catch(t){}}var x=i(660),b=i.n(x),y=i(960),v=i.n(y);let w={exporting:{csv:{annotations:{itemDelimiter:"; ",join:!1},columnHeaderFormatter:null,dateFormat:"%Y-%m-%d %H:%M:%S",decimalPoint:null,itemDelimiter:null,lineDelimiter:"\n"},menuItemDefinitions:{downloadCSV:{textKey:"downloadCSV",onclick:function(){this.exporting?.downloadCSV()}},downloadXLS:{textKey:"downloadXLS",onclick:function(){this.exporting?.downloadXLS()}},viewData:{textKey:"viewData",onclick:function(){this.exporting?.wrapLoading(this.exporting.toggleDataTable)}}},showExportInProgress:!0,showTable:!1,useMultiLevelHeaders:!0,useRowspanHeaders:!0},lang:{downloadCSV:"Download CSV",downloadXLS:"Download XLS",exportData:{annotationHeader:"Annotations",categoryHeader:"Category",categoryDatetimeHeader:"DateTime"},viewData:"View data table",hideData:"Hide data table",exportInProgress:"Exporting..."}},{doc:T,win:D}=c();function E(t,e,n,o={}){let a="function"==typeof t&&t.prototype||t;Object.hasOwnProperty.call(a,"hcEvents")||(a.hcEvents={});let r=a.hcEvents;c().Point&&t instanceof c().Point&&t.series&&t.series.chart&&(t.series.chart.runTrackerClick=!0);let i=t.addEventListener;i&&i.call(t,e,n,!!c().supportsPassiveEvents&&{passive:void 0===o.passive?-1!==e.indexOf("touch"):o.passive,capture:!1}),r[e]||(r[e]=[]);let l={fn:n,order:"number"==typeof o.order?o.order:1/0};return r[e].push(l),r[e].sort((t,e)=>t.order-e.order),function(){!function(t,e,n){function o(e,n){let o=t.removeEventListener;o&&o.call(t,e,n,!1)}function a(n){let a,r;if(t.nodeName){e?(a={})[e]=!0:a=n;var i=a,l=function(t,e){if(n[e])for(r=n[e].length;r--;)o(e,n[e][r].fn)};for(let t in i)Object.hasOwnProperty.call(i,t)&&l.call(i[t],i[t],t,i)}}let r="function"==typeof t&&t.prototype||t;if(Object.hasOwnProperty.call(r,"hcEvents")){let t=r.hcEvents;if(e){let r=t[e]||[];n?(t[e]=r.filter(function(t){return n!==t.fn}),o(e,n)):(a(t),t[e]=[])}else a(t),delete r.hcEvents}}(t,e,n)}}function S(t,e){let n;for(n in t||(t={}),e)t[n]=e[n];return t}function L(t,e,n,o){if(n=n||{},T?.createEvent&&(t.dispatchEvent||t.fireEvent&&t!==c())){let o=T.createEvent("Events");o.initEvent(e,!0,!0),n=S(o,n),t.dispatchEvent?t.dispatchEvent(n):t.fireEvent(e,n)}else if(t.hcEvents){n.target||S(n,{preventDefault:function(){n.defaultPrevented=!0},target:t,type:e});let o=[],a=t,r=!1;for(;a.hcEvents;)Object.hasOwnProperty.call(a,"hcEvents")&&a.hcEvents[e]&&(o.length&&(r=!0),o.unshift.apply(o,a.hcEvents[e])),a=Object.getPrototypeOf(a);r&&o.sort((t,e)=>t.order-e.order),o.forEach(e=>{!1===e.fn.call(t,n,t)&&n.preventDefault()})}o&&!n.defaultPrevented&&o.call(t,n)}let A=Array.prototype.find?function(t,e){return t.find(e)}:function(t,e){let n,o=t.length;for(n=0;n{let t=this.getCSV(!0);g(m(t,"text/csv")||"data:text/csv,\uFEFF"+encodeURIComponent(t),this.getFilename()+".csv")})}function n(){this.wrapLoading(()=>{let t='\x3c!--[if gte mso 9]>Ark1td{border:none;font-family: Calibri, sans-serif;} .number{mso-number-format:"0.00";} .text{ mso-number-format:"@";}'+this.getTable(!0)+"";g(m(t,"application/vnd.ms-excel")||"data:application/vnd.ms-excel;base64,"+N.btoa(unescape(encodeURIComponent(t))),this.getFilename()+".xls")})}function o(t){let e="",n=this.getDataRows(),o=this.options?.csv,a=C(o?.decimalPoint,o?.itemDelimiter!==","&&t?1.1.toLocaleString()[1]:"."),r=C(o?.itemDelimiter,","===a?";":","),i=o?.lineDelimiter;return n.forEach((t,o)=>{let l="",s=t.length;for(;s--;)"string"==typeof(l=t[s])&&(l=`"${l}"`),"number"==typeof l&&"."!==a&&(l=l.toString().replace(".",a)),t[s]=l;t.length=n.length?n[0].length:0,e+=t.join(r),o1?n:e.name)||"",topLevelColumnTitle:e.name}:e.name+((o||0)>1?" ("+n+")":"")},m=function(t,e,n){let o={},a={};return e.forEach(function(e){let r=(t.keyToAxis&&t.keyToAxis[e]||e)+"Axis",i="number"==typeof n&&!isNaN(n)&&n<1/0&&n>-1/0?t.chart[r][n]:t[r];o[e]=i&&i.categories||[],a[e]=i&&i.dateTime}),{categoryMap:o,dateTimeValueAxisMap:a}},x=function(t,e){let n=t.pointArrayMap||["y"];return t.data.some(t=>void 0!==t.y&&t.name)&&e&&!e.categories&&"name"!==t.exportKey?["x",...n]:n},b=[],y,v,w,T=0,D,E;for(D in o.series.forEach(function(e){let n=e.options.keys,o=e.xAxis,c=n||x(e,o),p=c.length,u=!e.requireSorting&&{},f=l.indexOf(o),y=m(e,c),v,D;if(!1!==e.options.includeInDataExport&&!e.options.isInternal&&!1!==e.visible){for(A(b,function(t){return t[0]===f})||b.push([f,T]),D=0;D{if(!t.tagName||"#text"===t.tagName)return t.textContent||"";let n=t.attributes,o=`<${t.tagName}`;return n&&Object.keys(n).forEach(t=>{let e=n[t];o+=` ${t}="${e}"`}),o+=">",o+=t.textContent||"",(t.children||[]).forEach(t=>{o+=e(t)}),o+=``};return e(this.getTableAST(t))}function i(t){let e=0,n=[],o=this,a=o.chart,r=a.options,i=t?1.1.toLocaleString()[1]:".",l=C(o.options.useMultiLevelHeaders,!0),s=o.getDataRows(l),c=l?s.shift():null,h=s.shift(),d=function(t,e){let n=t.length;if(e.length!==n)return!1;for(;n--;)if(t[n]!==e[n])return!1;return!0},p=function(t,e,n,o){let r=C(o,""),l="highcharts-text"+(e?" "+e:"");return"number"==typeof r?(r=a.numberFormatter(r,-1,i,"th"===t?"":void 0),l="highcharts-number"):o||(l="highcharts-empty"),{tagName:t,attributes:n=S({class:l},n),textContent:r}},{tableCaption:u}=o.options||{};!1!==u&&n.push({tagName:"caption",attributes:{class:"highcharts-table-caption"},textContent:"string"==typeof u?u:r.title?.text||r.lang.chartTitle});for(let t=0,n=s.length;te&&(e=s[t].length);n.push(function(t,e,n){let a=[],r=0,i=n||e&&e.length,s,c=0,h;if(l&&t&&e&&!d(t,e)){let n=[];for(;r1&&t.attributes&&(t.attributes.valign="top",t.attributes.rowspan=h),n.push(t)}a.push({tagName:"tr",children:n})}if(e){let t=[];for(r=0,i=e.length;r{n&&e.showLoading(e.options.lang.exportInProgress),o(()=>{try{t.call(this)}finally{n&&e.hideLoading()}})})}function d(){let t=this.exporting,e=t?.dataTableDiv,n=(t,e)=>t.children[e].textContent;if(e&&t.options.allowTableSorting){let o=e.querySelector("thead tr");o&&o.childNodes.forEach(o=>{let a=e.querySelector("tbody");o.addEventListener("click",function(){let r=[...e.querySelectorAll("tr:not(thead tr)")],i=[...o.parentNode.children];if(t){let e,l;r.sort((e=i.indexOf(o),l=t.ascendingOrderInTable=!t.ascendingOrderInTable,(t,o)=>{let a,r;return a=n(l?t:o,e),r=n(l?o:t,e),""===a||""===r||isNaN(a)||isNaN(r)?a.toString().localeCompare(r):a-r})).forEach(t=>{a?.appendChild(t)}),i.forEach(t=>{["highcharts-sort-ascending","highcharts-sort-descending"].forEach(e=>{t.classList.contains(e)&&t.classList.remove(e)})}),o.classList.add(t.ascendingOrderInTable?"highcharts-sort-ascending":"highcharts-sort-descending")}})})}}function p(){this.options?.exporting?.showTable&&!this.options.chart.forExport&&this.exporting?.viewData()}function u(){this.exporting?.dataTableDiv?.remove()}t.compose=function(t,f,g){var m;if(m="ExportData",!(0>k.indexOf(m)&&k.push(m)))return;S(v().prototype,{downloadCSV:function(){return this.exporting?.downloadCSV()},downloadXLS:function(){return this.exporting?.downloadXLS()},getCSV:function(t){return this.exporting?.getCSV(t)},getDataRows:function(t){return this.exporting?.getDataRows(t)},getTable:function(t){return this.exporting?.getTable(t)},getTableAST:function(t){return this.exporting?.getTableAST(t)},hideData:function(){return this.exporting?.hideData()},toggleDataTable:function(t){return this.exporting?.toggleDataTable(t)},viewData:function(){return this.exporting?.viewData()}});let x=f.prototype;if(!x.downloadCSV){E(t,"afterViewData",d),E(t,"render",p),E(t,"destroy",u),x.downloadCSV=e,x.downloadXLS=n,x.getCSV=o,x.getDataRows=a,x.getTable=r,x.getTableAST=i,x.hideData=l,x.toggleDataTable=s,x.wrapLoading=h,x.viewData=c,H(w);let f=O().exporting?.buttons?.contextButton?.menuItems;f&&f.push("separator","downloadCSV","downloadXLS","viewData");let{arearange:m,gantt:b,map:y,mapbubble:v,treemap:T,xrange:D}=g.types;m&&(m.prototype.keyToAxis={low:"y",high:"y"}),b&&(b.prototype.exportKey="name",b.prototype.keyToAxis={start:"x",end:"x"}),y&&(y.prototype.exportKey="name"),v&&(v.prototype.exportKey="name"),T&&(T.prototype.exportKey="name"),D&&(D.prototype.keyToAxis={x2:"x"})}}}(o||(o={}));let R=o,P=c();P.dataURLtoBlob=P.dataURLtoBlob||f,P.downloadURL=P.downloadURL||g,R.compose(P.Chart,P.Exporting,P.Series);let F=c();return l.default})()); \ No newline at end of file diff --git a/.claude/skills/session-metrics/scripts/vendor/charts/highcharts/v12/exporting.js b/.claude/skills/session-metrics/scripts/vendor/charts/highcharts/v12/exporting.js new file mode 100644 index 0000000..076b9a6 --- /dev/null +++ b/.claude/skills/session-metrics/scripts/vendor/charts/highcharts/v12/exporting.js @@ -0,0 +1,13 @@ +!/** + * Highcharts JS v12.6.0 (2026-04-13) + * @module highcharts/modules/exporting + * @requires highcharts + * + * Exporting module + * + * (c) 2010-2026 Highsoft AS + * Author: Torstein Hønsi + * + * A commercial license may be required depending on use. + * See www.highcharts.com/license + */function(e,t){"object"==typeof exports&&"object"==typeof module?module.exports=t(e._Highcharts,e._Highcharts.AST,e._Highcharts.Chart):"function"==typeof define&&define.amd?define("highcharts/modules/exporting",["highcharts/highcharts"],function(e){return t(e,e.AST,e.Chart)}):"object"==typeof exports?exports["highcharts/modules/exporting"]=t(e._Highcharts,e._Highcharts.AST,e._Highcharts.Chart):e.Highcharts=t(e.Highcharts,e.Highcharts.AST,e.Highcharts.Chart)}("u"(()=>{"use strict";var i,o,r={660:e=>{e.exports=t},944:t=>{t.exports=e},960:e=>{e.exports=n}},a={};function l(e){var t=a[e];if(void 0!==t)return t.exports;var n=a[e]={exports:{}};return r[e](n,n.exports,l),n.exports}l.n=e=>{var t=e&&e.__esModule?()=>e.default:()=>e;return l.d(t,{a:t}),t},l.d=(e,t)=>{for(var n in t)l.o(t,n)&&!l.o(e,n)&&Object.defineProperty(e,n,{enumerable:!0,get:t[n]})},l.o=(e,t)=>Object.prototype.hasOwnProperty.call(e,t);var s={};l.d(s,{default:()=>el});var c=l(944),h=l.n(c),p=l(660),d=l.n(p),u=l(960),g=l.n(u),f=i||(i={});f.compose=function(e){return e.navigation||(e.navigation=new m(e)),e};class m{constructor(e){this.updates=[],this.chart=e}addUpdate(e){this.chart.navigation.updates.push(e)}update(e,t){this.updates.forEach(n=>{n.call(this.chart,e,t)})}}f.Additions=m;let y=i,{isSafari:x,win:w,win:{document:v}}=h(),b=w.URL||w.webkitURL||w;function S(e,t){let n=w.navigator,i=v.createElement("a");if("string"!=typeof e&&!(e instanceof String)&&n.msSaveOrOpenBlob)return void n.msSaveOrOpenBlob(e,t);if(e=""+e,n.userAgent.length>1e3)throw Error("Input too long");let o=/Edge\/\d+/.test(n.userAgent);if((x&&"string"==typeof e&&0===e.indexOf("data:application/pdf")||o||e.length>2e6)&&!(e=function(e){let t=e.replace(/filename=.*;/,"").match(/data:([^;]*)(;base64)?,([A-Z+\d\/]+)/i);if(t&&t.length>3&&w.atob&&w.ArrayBuffer&&w.Uint8Array&&w.Blob&&b.createObjectURL){let e=w.atob(t[3]),n=new w.ArrayBuffer(e.length),i=new w.Uint8Array(n);for(let t=0;te.order-t.order),function(){V(e,t,n)}}function P(e,t,n,i,o){let r=T.createElement(e);return t&&A(r,t),o&&R(r,{padding:"0",border:"none",margin:"0"}),n&&R(r,n),i&&i.appendChild(r),r}function R(e,t){A(e.style,t)}function N(e){e?.parentElement?.removeChild(e)}function A(e,t){let n;for(n in e||(e={}),t)e[n]=t[n];return e}function L(e,t,n,i){if(n=n||{},T?.createEvent&&(e.dispatchEvent||e.fireEvent&&e!==h())){let i=T.createEvent("Events");i.initEvent(t,!0,!0),n=A(i,n),e.dispatchEvent?e.dispatchEvent(n):e.fireEvent(t,n)}else if(e.hcEvents){n.target||A(n,{preventDefault:function(){n.defaultPrevented=!0},target:e,type:t});let i=[],o=e,r=!1;for(;o.hcEvents;)Object.hasOwnProperty.call(o,"hcEvents")&&o.hcEvents[t]&&(i.length&&(r=!0),i.unshift.apply(i,o.hcEvents[t])),o=Object.getPrototypeOf(o);r&&i.sort((e,t)=>e.order-t.order),i.forEach(t=>{!1===t.fn.call(e,n,e)&&n.preventDefault()})}i&&!n.defaultPrevented&&i.call(e,n)}let D=Array.prototype.find?function(e,t){return e.find(t)}:function(e,t){let n,i=e.length;for(n=0;ne.indexOf(t)&&!!e.push(t)}function V(e,t,n){function i(t,n){let i=e.removeEventListener;i&&i.call(e,t,n,!1)}function o(n){let o,r;e.nodeName&&(t?(o={})[t]=!0:o=n,B(o,function(e,t){if(n[t])for(r=n[t].length;r--;)i(t,n[t][r].fn)}))}let r="function"==typeof e&&e.prototype||e;if(Object.hasOwnProperty.call(r,"hcEvents")){let e=r.hcEvents;if(t){let r=e[t]||[];n?(e[t]=r.filter(function(e){return n!==e.fn}),i(t,n)):(o(e),e[t]=[])}else o(e),delete r.hcEvents}}let{composed:W}=h();function q(){this.fullscreen=new z(this)}class z{static compose(e){G(W,"Fullscreen")&&F(e,"beforeRender",q)}constructor(e){this.chart=e,this.isOpen=!1;const t=e.renderTo;!this.browserProps&&("function"==typeof t.requestFullscreen?this.browserProps={fullscreenChange:"fullscreenchange",requestFullscreen:"requestFullscreen",exitFullscreen:"exitFullscreen"}:t.mozRequestFullScreen?this.browserProps={fullscreenChange:"mozfullscreenchange",requestFullscreen:"mozRequestFullScreen",exitFullscreen:"mozCancelFullScreen"}:t.webkitRequestFullScreen?this.browserProps={fullscreenChange:"webkitfullscreenchange",requestFullscreen:"webkitRequestFullScreen",exitFullscreen:"webkitExitFullscreen"}:t.msRequestFullscreen&&(this.browserProps={fullscreenChange:"MSFullscreenChange",requestFullscreen:"msRequestFullscreen",exitFullscreen:"msExitFullscreen"}))}close(){let e=this,t=e.chart,n=t.options.chart;L(t,"fullscreenClose",void 0,function(){e.isOpen&&e.browserProps&&t.container.ownerDocument instanceof Document&&t.container.ownerDocument[e.browserProps.exitFullscreen](),e.unbindFullscreenEvent&&(e.unbindFullscreenEvent=e.unbindFullscreenEvent()),t.setSize(e.origWidth,e.origHeight,!1),e.origWidth=void 0,e.origHeight=void 0,n.width=e.origWidthOption,n.height=e.origHeightOption,e.origWidthOption=void 0,e.origHeightOption=void 0,e.isOpen=!1,e.setButtonText()})}open(){let e=this,t=e.chart,n=t.options.chart;L(t,"fullscreenOpen",void 0,function(){if(n&&(e.origWidthOption=n.width,e.origHeightOption=n.height),e.origWidth=t.chartWidth,e.origHeight=t.chartHeight,e.browserProps){let n=F(t.container.ownerDocument,e.browserProps.fullscreenChange,function(){e.isOpen?(e.isOpen=!1,e.close()):(t.setSize(null,null,!1),e.isOpen=!0,e.setButtonText())}),i=F(t,"destroy",n);e.unbindFullscreenEvent=()=>{n(),i()};let o=t.renderTo[e.browserProps.requestFullscreen]();o&&o.catch(function(){alert("Full screen is not supported inside a frame.")})}})}setButtonText(){let e=this.chart,t=e.exporting?.divElements,n=e.options.exporting,i=n&&n.buttons&&n.buttons.contextButton.menuItems,o=e.options.lang;if(n?.menuItemDefinitions&&o?.exitFullscreen&&o.viewFullscreen&&i&&t){let e=t[i.indexOf("viewFullscreen")];e&&d().setElementHTML(e,this.isOpen?o.exitFullscreen:n.menuItemDefinitions.viewFullscreen?.textKey||o.viewFullscreen)}}toggle(){this.isOpen?this.close():this.open()}}let{win:K}=h(),_={ajax:function(e){let t={json:"application/json",xml:"application/xml",text:"text/plain",octet:"application/octet-stream"},n=new XMLHttpRequest;function i(t,n){e.error&&e.error(t,n)}if(!e.url)return!1;n.open((e.type||"get").toUpperCase(),e.url,!0),e.headers?.["Content-Type"]||n.setRequestHeader("Content-Type",t[e.dataType||"json"]||t.text),B(e.headers,function(e,t){n.setRequestHeader(t,e)}),e.responseType&&(n.responseType=e.responseType),n.onreadystatechange=function(){let t;if(4===n.readyState){if(200===n.status){if("blob"!==e.responseType&&(t=n.responseText,"json"===e.dataType))try{t=JSON.parse(t)}catch(e){if(e instanceof Error)return i(n,e)}return e.success?.(t,n)}i(n,n.responseText)}},e.data&&"string"!=typeof e.data&&(e.data=JSON.stringify(e.data)),n.send(e.data)},getJSON:function(e,t){_.ajax({url:e,success:t,dataType:"json",headers:{"Content-Type":"text/plain"}})}};_.post=async function(e,t,n){let i=new K.FormData;B(t,function(e,t){i.append(t,e)}),i.append("b64","true");let o=await K.fetch(e,{method:"POST",body:i,...n});if(o.ok){let e=await o.text(),n=document.createElement("a");n.href=`data:${t.type};base64,${e}`,n.download=t.filename,n.click(),N(n)}};let{defaultOptions:J,setOptions:X}=h(),{composed:Y,doc:Z,isFirefox:Q,isMS:ee,isSafari:et,SVG_NS:en,win:ei}=h();d().allowedAttributes.push("data-z-index","fill-opacity","filter","preserveAspectRatio","rx","ry","stroke-dasharray","stroke-linejoin","stroke-opacity","text-anchor","transform","transform-origin","version","viewBox","visibility","xmlns","xmlns:xlink"),d().allowedTags.push("desc","clippath","fedropshadow","femorphology","g","image");let eo=ei.URL||ei.webkitURL||ei;class er{constructor(e,t){this.options={},this.chart=e,this.options=t,this.btnCount=0,this.buttonOffset=0,this.divElements=[],this.svgElements=[]}static hyphenate(e){return e.replace(/[A-Z]/g,function(e){return"-"+e.toLowerCase()})}static async imageToDataURL(e,t,n){let i=await er.loadImage(e),o=Z.createElement("canvas"),r=o?.getContext("2d");if(r)return o.height=i.height*t,o.width=i.width*t,r.drawImage(i,0,0,o.width,o.height),o.toDataURL(n);throw Error("No canvas found!")}static async fetchCSS(e){try{let t=await fetch(e),n=await t.text(),i=new CSSStyleSheet;return i.replaceSync(n),i}catch{(0,c.error)(`Warning: Failed to fetch CSS from ${e}`,!1)}}static async handleStyleSheet(e,t){try{for(let n of Array.from(e.cssRules)){if(n instanceof CSSImportRule){let e=await er.fetchCSS(n.href);e&&await er.handleStyleSheet(e,t)}if(n instanceof CSSFontFaceRule){let i=n.cssText;if(e.href){let t=e.href,n=/url\(\s*(['"]?)(?![a-z]+:|\/\/)([^'")]+?)\1\s*\)/gi;i=i.replace(n,(e,n,i)=>{let o=new URL(i,t).href;return`url(${n}${o}${n})`})}t.push(i)}}}catch{if(e.href){let n=await er.fetchCSS(e.href);n&&await er.handleStyleSheet(n,t)}}}static async fetchStyleSheets(){let e=[];for(let t of Array.from(Z.styleSheets))await er.handleStyleSheet(t,e);return e}static async inlineFonts(e){let t=await er.fetchStyleSheets(),n=/url\(([^)]+)\)/g,i=[],o=t.join("\n"),r;for(;r=n.exec(o);){let e=r[1].replace(/['"]/g,"");i.includes(e)||i.push(e)}let a=e=>{let t="",n=new Uint8Array(e);for(let e=0;e{let n=t.replace(/['"]/g,"");return`url(${l[n]||n})`});let s=document.createElementNS("http://www.w3.org/2000/svg","style");return s.textContent=o,e.append(s),e}static loadImage(e){return new Promise((t,n)=>{let i=new ei.Image;i.crossOrigin="Anonymous",i.onload=()=>{setTimeout(()=>{t(i)},er.loadEventDeferDelay)},i.onerror=e=>{n(e)},i.src=e})}static prepareImageOptions(e){let t=e?.type||"image/png",n=e?.libURL||J.exporting?.libURL;return{type:t,filename:(e?.filename||"chart")+"."+("image/svg+xml"===t?"svg":t.split("/")[1]),scale:e?.scale||1,libURL:n?.slice(-1)!=="/"?n+"/":n}}static sanitizeSVG(e,t){let n=e.indexOf("")+6,i=e.indexOf("-1,o=e.substr(n);return e=e.substr(0,n),i?e=e.replace(/(<(?:img|br).*?(?=\>))>/g,"$1 />").replace(/(]*xmlns=)[^>]*)>/g,'$1 xmlns="http://www.w3.org/2000/svg">'):o&&t?.exporting?.allowHTML&&(o=''+o.replace(/(<(?:img|br).*?(?=\>))>/g,"$1 />").replace(/(]*xmlns=)[^>]*)>/g,'$1 xmlns="http://www.w3.org/2000/svg">')+"",e=e.replace("",o+"")),e=e.replace(/zIndex="[^"]+"/g,"").replace(/symbolName="[^"]+"/g,"").replace(/jQuery\d+="[^"]+"/g,"").replace(/url\(("|")(.*?)("|")\;?\)/g,"url($2)").replace(/url\([^#]+#/g,"url(#").replace(/-1&&0>t.indexOf("Chrome");try{if(!n&&-1===e.indexOf("{};a?h=function(e){e&&e.stopPropagation(),a.call(i,e,i)}:l&&(h=function(e){e&&e.stopPropagation(),n.contextMenu(p.menuClassName,l,p.translateX||0,p.translateY||0,p.width||0,p.height||0,p),p.setState(2)}),r.text&&r.symbol?c.paddingLeft=$(c.paddingLeft,30):r.text||A(c,{width:r.width,height:r.height,padding:0});let p=o.button(r.text||"",0,0,h,c,void 0,void 0,void 0,void 0,r.useHTML).addClass(e.className||"").attr({title:$(i.options.lang[r._titleKey||r.titleKey],"")});p.menuClassName=e.menuClassName||"highcharts-menu-"+n.btnCount++,r.symbol&&(t=o.symbol(r.symbol,Math.round((r.symbolX||0)-s/2),Math.round((r.symbolY||0)-s/2),s,s,{width:s,height:s}).addClass("highcharts-button-symbol").attr({zIndex:1}).add(p),i.styledMode||t.attr({stroke:r.symbolStroke,fill:r.symbolFill,"stroke-width":r.symbolStrokeWidth||1})),p.add(n.group).align(A(r,{width:p.width,x:$(r.x,n.buttonOffset)}),!0,"spacingBox"),n.buttonOffset+=((p.width||0)+(r.buttonSpacing||0))*("right"===r.align?-1:1),n.svgElements.push(p,t)}afterPrint(){let e=this.chart;if(!this.printReverseInfo)return;let{childNodes:t,origDisplay:n,resetParams:i}=this.printReverseInfo;this.moveContainers(e.renderTo),[].forEach.call(t,function(e,t){1===e.nodeType&&(e.style.display=n[t]||"")}),this.isPrinting=!1,i&&e.setSize.apply(e,i),delete this.printReverseInfo,er.printingChart=void 0,L(e,"afterPrint")}beforePrint(){let e=this.chart,t=Z.body,n=this.options.printMaxWidth,i={childNodes:t.childNodes,origDisplay:[],resetParams:void 0};this.isPrinting=!0,e.pointer?.reset(void 0,0),L(e,"beforePrint"),n&&e.chartWidth>n&&(i.resetParams=[e.options.chart.width,void 0,!1],e.setSize(n,void 0,!1)),[].forEach.call(i.childNodes,function(e,t){1===e.nodeType&&(i.origDisplay[t]=e.style.display,e.style.display="none")}),this.moveContainers(t),this.printReverseInfo=i}contextMenu(e,t,n,i,o,r,a){let l=this,s=l.chart,c=s.options.navigation,h=s.chartWidth,p=s.chartHeight,u="cache-"+e,g=Math.max(o,r),f,m=s[u];m||(l.contextMenuEl=s[u]=m=P("div",{className:e},{position:"absolute",zIndex:1e3,padding:g+"px",pointerEvents:"auto",...s.renderer.style},s.scrollablePlotArea?.fixedDiv||s.container),f=P("ul",{className:"highcharts-menu"},s.styledMode?{}:{listStyle:"none",margin:0,padding:0},m),s.styledMode||R(f,A({MozBoxShadow:"3px 3px 10px #0008",WebkitBoxShadow:"3px 3px 10px #0008",boxShadow:"3px 3px 10px #0008"},c?.menuStyle||{})),m.hideMenu=function(){R(m,{display:"none"}),a&&a.setState(0),s.exporting&&(s.exporting.openMenu=!1),R(s.renderTo,{overflow:"hidden"}),R(s.container,{overflow:"hidden"}),H(m.hideTimer),L(s,"exportMenuHidden")},l.events?.push(F(m,"mouseleave",function(){m.hideTimer=ei.setTimeout(m.hideMenu,500)}),F(m,"mouseenter",function(){H(m.hideTimer)}),F(Z,"mouseup",function(t){s.pointer?.inClass(t.target,e)||m.hideMenu()}),F(m,"click",function(){s.exporting?.openMenu&&m.hideMenu()})),t.forEach(function(e){if("string"==typeof e&&l.options.menuItemDefinitions?.[e]&&(e=l.options.menuItemDefinitions[e]),I(e,!0)){let t;e.separator?t=P("hr",void 0,void 0,f):("viewData"===e.textKey&&l.isDataTableVisible&&(e.textKey="hideData"),t=P("li",{className:"highcharts-menu-item",onclick:function(t){t&&t.stopPropagation(),m.hideMenu(),"string"!=typeof e&&e.onclick&&e.onclick.apply(s,arguments)}},void 0,f),d().setElementHTML(t,e.text||s.options.lang[e.textKey]),s.styledMode||(t.onmouseover=function(){R(this,c?.menuItemHoverStyle||{})},t.onmouseout=function(){R(this,c?.menuItemStyle||{})},R(t,A({cursor:"pointer"},c?.menuItemStyle||{})))),l.divElements.push(t)}}),l.divElements.push(f,m),l.menuHeight=m.offsetHeight,l.menuWidth=m.offsetWidth);let y={display:"block"};n+(l.menuWidth||0)>h?y.right=h-n-o-g+"px":y.left=n-g+"px",i+r+(l.menuHeight||0)>p&&a.alignOptions?.verticalAlign!=="top"?y.bottom=p-i-g+"px":y.top=i+r-g+"px",R(m,y),R(s.renderTo,{overflow:""}),R(s.container,{overflow:""}),s.exporting&&(s.exporting.openMenu=!0),L(s,"exportMenuShown")}destroy(e){let t,n=e?e.target:this.chart,{divElements:i,events:o,svgElements:r}=this;r.forEach((e,i)=>{e&&(e.onclick=e.ontouchstart=null,n[t="cache-"+e.menuClassName]&&delete n[t],r[i]=e.destroy())}),r.length=0,this.group&&(this.group.destroy(),delete this.group),i.forEach(function(e,t){e&&(H(e.hideTimer),V(e,"mouseleave"),i[t]=e.onmouseout=e.onmouseover=e.ontouchstart=e.onclick=null,N(e))}),i.length=0,o&&(o.forEach(function(e){e()}),o.length=0)}async downloadSVG(e,t){let n,i={svg:e,exportingOptions:t,exporting:this};if(L(er.prototype,"downloadSVG",i),i.defaultPrevented)return;let{type:o,filename:r,scale:a,libURL:l}=er.prepareImageOptions(t);if("application/pdf"===o)throw Error("Offline exporting logic for PDF type is not found.");if("image/svg+xml"===o){if(void 0!==ei.MSBlobBuilder){let t=new ei.MSBlobBuilder;t.append(e),n=t.getBlob("image/svg+xml")}else n=er.svgToDataURL(e);S(n,r)}else{n=er.svgToDataURL(e);try{er.objectURLRevoke=!0;let e=await er.imageToDataURL(n,a,o);S(e,r)}catch(p){if("No canvas found!"===p.message)throw p;if(e.length>1e8)throw Error("Input too long");let t=Z.createElement("canvas"),n=t.getContext("2d"),i=e.match(/^]*\s{,1000}width\s{,1000}=\s{,1000}\"?(\d+)\"?[^>]*>/),h=e.match(/^]*\s{0,1000}height\s{,1000}=\s{,1000}\"?(\d+)\"?[^>]*>/);if(n&&i&&h){let p=i[1]*a,d=h[1]*a;if(t.width=p,t.height=d,!ei.canvg){var s;er.objectURLRevoke=!0,await (s=l+"canvg.js",new Promise((e,t)=>{let n=v.getElementsByTagName("head")[0],i=v.createElement("script");i.type="text/javascript",i.src=s,i.onload=()=>{e()},i.onerror=()=>{let e=`Error loading script ${s}`;(0,c.error)(e),t(Error(e))},n.appendChild(i)}))}ei.canvg.Canvg.fromString(n,e).start(),S(ei.navigator.msSaveOrOpenBlob?t.msToBlob():t.toDataURL(o),r)}}finally{if(er.objectURLRevoke)try{eo.revokeObjectURL(n)}catch{}}}}async exportChart(e,t){if((e=U(this.options,e)).local)await this.localExport(e,t||{});else{let n=await this.getSVGForExport(e,t);e.url&&await _.post(e.url,{filename:e.filename?e.filename.replace(/\//g,"-"):this.getFilename(),type:e.type,width:e.width,scale:e.scale,svg:n},e.fetchOptions)}}async fallbackToServer(e,t){!1===e.fallbackToExportServer?e.error?e.error(e,t):(0,c.error)(28,!0):"application/pdf"===e.type&&(e.local=!1,await this.exportChart(e))}getChartHTML(e){let t=this.chart;return e&&this.inlineStyles(),this.resolveCSSVariables(),t.container.querySelectorAll("canvas").forEach(function(e){let n=e.toDataURL("image/png"),i=e.parentNode,o=t.renderer.image(n,0,0,e.width,e.height);R(o.element,{width:e.style.width,height:e.style.height}),i.parentNode.insertBefore(o.element,i),i.remove()}),t.container.innerHTML}getFilename(){let e=this.chart.userOptions.title?.text,t=this.options.filename;return t?t.replace(/\//g,"-"):("string"==typeof e&&(t=e.toLowerCase().replace(/<\/?[^>]+(>|$)/g,"").replace(/[\s_]+/g,"-").replace(/[^a-z\d\-]/g,"").replace(/^[\-]+/g,"").replace(/[\-]+/g,"-").substr(0,24).replace(/[\-]+$/g,"")),(!t||t.length<5)&&(t="chart"),t)}getSVG(e,t){let n=this.chart,i,o,r=U(n.options,e);r.plotOptions=U(n.userOptions.plotOptions,e?.plotOptions),r.time=U(n.userOptions.time,e?.time);let a=P("div",void 0,{position:"absolute",top:"-9999em",width:n.chartWidth+"px",height:n.chartHeight+"px"},Z.body),l=n.renderTo.style.width,s=n.renderTo.style.height,h=r.exporting?.sourceWidth||r.chart.width||/px$/.test(l)&&parseInt(l,10)||(r.isGantt?800:600),p=r.exporting?.sourceHeight||r.chart.height||/px$/.test(s)&&parseInt(s,10)||400;A(r.chart,{animation:!1,renderTo:a,forExport:!0,renderer:"SVGRenderer",width:h,height:p}),r.exporting&&(r.exporting.enabled=!1),delete r.data,r.series=[],n.series.forEach(function(e){(o=U(e.userOptions,{animation:!1,enableMouseTracking:!1,showCheckbox:!1,visible:e.visible})).isInternal||r?.series?.push(o)});let d={};n.axes.forEach(function(e){e.userOptions.internalKey||(e.userOptions.internalKey=(0,c.uniqueKey)()),r&&!e.options.isInternal&&(d[e.coll]||(d[e.coll]=!0,r[e.coll]=[]),r[e.coll].push(U(e.userOptions,{visible:e.visible,type:e.type,uniqueNames:e.uniqueNames})))}),r.colorAxis=n.userOptions.colorAxis;let u=t=>{e&&["xAxis","yAxis","series"].forEach(function(n){e[n]&&t.update({[n]:e[n]})}),n.axes.forEach(function(n){let i=D(t.axes,e=>e.options.internalKey===n.userOptions.internalKey);if(i){var o;let t=n.getExtremes(),r=(j(o=e?.[n.coll]||{})?o:[o])[0],a="min"in r?r.min:t.userMin,l="max"in r?r.max:t.userMax;(void 0!==a&&a!==i.min||void 0!==l&&l!==i.max)&&i.setExtremes(a??void 0,l??void 0,!0,!1)}});let o=t.exporting;return o?.options.applyStyleSheets&&this.applyShadowDOMStyles(t),i=o?.getChartHTML(n.styledMode||r?.exporting?.applyStyleSheets)||"",L(n,"getSVG",{chartCopy:t}),i=er.sanitizeSVG(i,r),r=void 0,t.destroy(),N(a),i};return t?new Promise(e=>new n.constructor(r||{},function(t){n.callback?.call(this,t),e(u(this))})):u(new n.constructor(r,n.callback))}applyShadowDOMStyles(e){let t=this.chart,n=[],i=t.container,o;for(;i&&(!(o=i.getRootNode())||"object"!=typeof o.host);)i=i.parentNode,o=null;o?.querySelectorAll("style").forEach(t=>{let i=t.cloneNode(!0);e.container.appendChild(i),n.push(i)}),F(t,"getSVG",()=>{n.forEach(e=>{e.remove()})})}async getSVGForExport(e,t){let n=this.options;return await this.getSVG(U({chart:{borderRadius:0}},n.chartOptions,t,{exporting:{sourceWidth:e?.sourceWidth||n.sourceWidth,sourceHeight:e?.sourceHeight||n.sourceHeight}}),!0)}inlineStyles(){let e,t=er.inlineDenylist,n=er.inlineAllowlist,i={},o=P("iframe",void 0,{width:"1px",height:"1px",visibility:"hidden"},Z.body),r=o.contentWindow?.document;r&&r.body.appendChild(r.createElementNS(en,"svg")),!function o(a){let l,s,c,h,p,d,u={};if(r&&1===a.nodeType&&-1===er.unstyledElements.indexOf(a.nodeName)){if(l=ei.getComputedStyle(a,null),s="svg"===a.nodeName?{}:ei.getComputedStyle(a.parentNode,null),!i[a.nodeName]){e=r.getElementsByTagName("svg")[0],c=r.createElementNS(a.namespaceURI,a.nodeName),e.appendChild(c);let t=ei.getComputedStyle(c,null),n={};for(let e in t)e.length<1e3&&"string"==typeof t[e]&&!/^\d+$/.test(e)&&(n[e]=t[e]);i[a.nodeName]=n,"text"===a.nodeName&&delete i.text.fill,e.removeChild(c)}for(let e in l)(Q||ee||et||Object.hasOwnProperty.call(l,e))&&function(e,o){if(h=p=!1,n.length){for(d=n.length;d--&&!p;)p=n[d].test(o);h=!p}for("transform"===o&&"none"===e&&(h=!0),d=t.length;d--&&!h;){if(o.length>1e3)throw Error("Input too long");h=t[d].test(o)||"function"==typeof e}!h&&(s[o]!==e||"svg"===a.nodeName)&&i[a.nodeName][o]!==e&&(er.inlineToAttributes&&-1===er.inlineToAttributes.indexOf(o)?u[o]=e:e&&a.setAttribute(er.hyphenate(o),e))}(l[e],e);if(R(a,u),"svg"===a.nodeName&&a.setAttribute("stroke-width","1px"),"text"===a.nodeName)return;[].forEach.call(a.children||a.childNodes,o)}}(this.chart.container.querySelector("svg")),e.parentNode.removeChild(e),o.parentNode.removeChild(o)}async localExport(e,t){let n=this.chart,i,o,r=null,a;if(ee&&n.styledMode&&!er.inlineAllowlist.length&&er.inlineAllowlist.push(/^blockSize/,/^border/,/^caretColor/,/^color/,/^columnRule/,/^columnRuleColor/,/^cssFloat/,/^cursor/,/^fill$/,/^fillOpacity/,/^font/,/^inlineSize/,/^length/,/^lineHeight/,/^opacity/,/^outline/,/^parentRule/,/^rx$/,/^ry$/,/^stroke/,/^textAlign/,/^textAnchor/,/^textDecoration/,/^transform/,/^vectorEffect/,/^visibility/,/^x$/,/^y$/),ee&&("application/pdf"===e.type||n.container.getElementsByTagName("image").length&&"image/svg+xml"!==e.type)||"application/pdf"===e.type&&[].some.call(n.container.getElementsByTagName("image"),function(e){let t=e.getAttribute("href");return""!==t&&"string"==typeof t&&0!==t.indexOf("data:")}))return void await this.fallbackToServer(e,Error("Image type not supported for this chart/browser."));let l=F(n,"getSVG",e=>{o=e.chartCopy.options,a=(i=e.chartCopy.container.cloneNode(!0))&&i.getElementsByTagName("image")||[]});try{let n;for(let n of(await this.getSVGForExport(e,t),a?Array.from(a):[]))if(r=n.getAttributeNS("http://www.w3.org/1999/xlink","href")){er.objectURLRevoke=!1;let t=await er.imageToDataURL(r,e?.scale||1,e?.type||"image/png");n.setAttributeNS("http://www.w3.org/1999/xlink","href",t)}else n.parentNode.removeChild(n);let l=i?.querySelector("svg");l&&!e.chartOptions?.chart?.style?.fontFamily&&await er.inlineFonts(l);let s=(n=i?.innerHTML,er.sanitizeSVG(n||"",o));if(s.indexOf("-1&&"image/svg+xml"!==e.type&&(ee||"application/pdf"===e.type))throw Error("Image type not supported for charts with embedded HTML");return await this.downloadSVG(s,A({filename:this.getFilename()},e)),s}catch(t){await this.fallbackToServer(e,t)}finally{l()}}moveContainers(e){let t=this.chart,{scrollablePlotArea:n}=t;(n?[n.fixedDiv,n.scrollingContainer]:[t.container]).forEach(function(t){e.appendChild(t)})}print(){let e=this.chart;this.isPrinting||(er.printingChart=e,et||this.beforePrint(),setTimeout(()=>{ei.focus(),ei.print(),et||setTimeout(()=>{e.exporting?.afterPrint()},1e3)},1))}render(){let e=this,{chart:t,options:n}=e,i=e?.isDirty||!e?.svgElements.length;e.buttonOffset=0,e.isDirty&&e.destroy(),i&&!1!==n.enabled&&(e.events=[],e.group||(e.group=t.renderer.g("exporting-group").attr({zIndex:3}).add()),B(n?.buttons,function(t){e.addButton(t)}),e.isDirty=!1)}resolveCSSVariables(){Array.from(this.chart.container.querySelectorAll("*")).forEach(e=>{["color","fill","stop-color","stroke"].forEach(t=>{let n=e.getAttribute(t);n?.includes("var(")&&e.setAttribute(t,getComputedStyle(e).getPropertyValue(t));let i=e.style?.[t];i?.includes("var(")&&(e.style[t]=getComputedStyle(e).getPropertyValue(t))})})}update(e,t){this.isDirty=!0,U(!0,this.options,e),$(t,!0)&&this.chart.redraw()}}er.inlineAllowlist=[],er.inlineDenylist=[/-/,/^(clipPath|cssText|d|height|width)$/,/^font$/,/[lL]ogical(Width|Height)$/,/^parentRule$/,/^(cssRules|ownerRules)$/,/perspective/,/TapHighlightColor/,/^transition/,/^length$/,/^\d+$/],er.inlineToAttributes=["fill","stroke","strokeLinecap","strokeLinejoin","strokeWidth","textAnchor","x","y"],er.loadEventDeferDelay=150*!!ee,er.unstyledElements=["clipPath","defs","desc"],function(e){function t(e){let t=e.exporting;t&&(t.render(),F(e,"redraw",function(){this.exporting?.render()}),F(e,"destroy",function(){this.exporting?.destroy()}))}function n(){let t=this;t.options.exporting&&(t.exporting=new e(t,t.options.exporting),y.compose(t).navigation.addUpdate((e,n)=>{t.exporting&&(t.exporting.isDirty=!0,U(!0,t.options.navigation,e),$(n,!0)&&t.redraw())}))}function i({alignTo:e,key:t,textPxLength:n}){let i=this.options.exporting,{align:o,buttonSpacing:r=0,verticalAlign:a,width:l=0}=U(this.options.navigation?.buttonOptions,i?.buttons?.contextButton),s=e.width-n,c=l+r;(i?.enabled??!0)&&"title"===t&&"right"===o&&"top"===a&&s<2*c&&(s(()=>{"use strict";var h,l,p={184:t=>{t.exports=r},512:t=>{t.exports=i},532:t=>{t.exports=a},608:t=>{t.exports=s},620:t=>{t.exports=e},632:t=>{t.exports=n},820:t=>{t.exports=o},944:e=>{e.exports=t}},c={};function d(t){var e=c[t];if(void 0!==e)return e.exports;var i=c[t]={exports:{}};return p[t](i,i.exports,d),i.exports}d.n=t=>{var e=t&&t.__esModule?()=>t.default:()=>t;return d.d(e,{a:e}),e},d.d=(t,e)=>{for(var i in e)d.o(e,i)&&!d.o(t,i)&&Object.defineProperty(t,i,{enumerable:!0,get:e[i]})},d.o=(t,e)=>Object.prototype.hasOwnProperty.call(t,e);var x={};d.d(x,{default:()=>er});var y=d(944),f=d.n(y),u=d(620),z=d.n(u);let{doc:b,win:g}=f();function m(t,e,i,s={}){let o="function"==typeof t&&t.prototype||t;Object.hasOwnProperty.call(o,"hcEvents")||(o.hcEvents={});let r=o.hcEvents;f().Point&&t instanceof f().Point&&t.series&&t.series.chart&&(t.series.chart.runTrackerClick=!0);let a=t.addEventListener;a&&a.call(t,e,i,!!f().supportsPassiveEvents&&{passive:void 0===s.passive?-1!==e.indexOf("touch"):s.passive,capture:!1}),r[e]||(r[e]=[]);let n={fn:i,order:"number"==typeof s.order?s.order:1/0};return r[e].push(n),r[e].sort((t,e)=>t.order-e.order),function(){!function(t,e,i){function s(e,i){let s=t.removeEventListener;s&&s.call(t,e,i,!1)}function o(i){let o,r;t.nodeName&&(e?(o={})[e]=!0:o=i,w(o,function(t,e){if(i[e])for(r=i[e].length;r--;)s(e,i[e][r].fn)}))}let r="function"==typeof t&&t.prototype||t;if(Object.hasOwnProperty.call(r,"hcEvents")){let t=r.hcEvents;if(e){let r=t[e]||[];i?(t[e]=r.filter(function(t){return i!==t.fn}),s(e,i)):(o(t),t[e]=[])}else o(t),delete r.hcEvents}}(t,e,i)}}function v(t){return null!=t}function M(t,e){let i;for(i in t||(t={}),e)t[i]=e[i];return t}function P(t){return S(t)&&"number"==typeof t.nodeType}function A(t){let e=Object.prototype.toString.call(t);return"[object Array]"===e||"[object Array Iterator]"===e}function S(t,e){return!!t&&"object"==typeof t&&(!e||!A(t))}function k(t,...e){let i,s=[t,...e],o={},r=function(t,e){return"object"!=typeof t&&(t={}),w(e,function(i,s){if("__proto__"!==s&&"constructor"!==s){let o;!S(i,!0)||(o=i?.constructor,S(i,!0)&&!P(i)&&o?.name&&"Object"!==o.name)||P(i)?t[s]=e[s]:t[s]=r(t[s]||{},i)}}),t};!0===t&&(o=s[1],s=Array.prototype.slice.call(s,2));let a=s.length;for(i=0;it.indexOf(e)&&!!t.push(e)}function I(t,e,i){let s=t[e];t[e]=function(){let t=arguments,e=this;return i.apply(this,[function(){return s.apply(e,arguments.length?arguments:t)}].concat([].slice.call(arguments)))}}Array.prototype.find;let{deg2rad:T}=f();function O(t,e,i,s){let o=e.options.chart.options3d,r=L(s,!!i&&e.inverted),a={x:e.plotWidth/2,y:e.plotHeight/2,z:o.depth/2,vd:L(o.depth,1)*L(o.viewDistance,0)},n=e.scale3d||1,h=T*o.beta*(r?-1:1),l=T*o.alpha*(r?-1:1),p={cosA:Math.cos(l),cosB:Math.cos(-h),sinA:Math.sin(l),sinB:Math.sin(-h)};return i||(a.x+=e.plotLeft,a.y+=e.plotTop),t.map(function(t){var e,i,s;let o=(e=(r?t.y:t.x)-a.x,i=(r?t.x:t.y)-a.y,s=(t.z||0)-a.z,{x:p.cosB*e-p.sinB*s,y:-p.sinA*p.sinB*e+p.cosA*i-p.cosB*p.sinA*s,z:p.cosA*p.sinB*e+p.sinA*i+p.cosA*p.cosB*s}),h=X(o,a,a.vd);return h.x=h.x*n+a.x,h.y=h.y*n+a.y,h.z=o.z*n+a.z,{x:r?h.y:h.x,y:r?h.x:h.y,z:h.z}})}function X(t,e,i){let s=i>0&&i<1/0?i/(t.z+e.z+i):1;return{x:t.x*s,y:t.y*s}}function H(t){let e=0,i,s;for(i=0;i=0?0:360),t.beta=t.beta%360+(t.beta>=0?0:360));let e=this.inverted,i=this.clipBox,s=this.margin;i[e?"y":"x"]=-(s[3]||0),i[e?"x":"y"]=-(s[0]||0),i[e?"height":"width"]=this.chartWidth+(s[3]||0)+(s[1]||0),i[e?"width":"height"]=this.chartHeight+(s[0]||0)+(s[2]||0),this.scale3d=1,!0===t.fitToPlot&&(this.scale3d=this.chart3d.getScale(t.depth)),this.chart3d.frame3d=this.chart3d.get3dFrame()}}function a(){this.is3d()&&(this.isDirtyBox=!0)}function n(){this.chart3d&&this.is3d()&&(this.chart3d.frame3d=this.chart3d.get3dFrame())}function h(){this.chart3d||(this.chart3d=new d(this))}function l(t){return this.is3d()||t.apply(this,[].slice.call(arguments,1))}function p(t){let e,i=this.series.length;if(this.is3d())for(;i--;)(e=this.series[i]).translate(),e.render();else t.call(this)}function c(t){t.apply(this,[].slice.call(arguments,1)),this.is3d()&&(this.container.className+=" highcharts-3d-chart")}t.defaultOptions={chart:{options3d:{enabled:!1,alpha:0,beta:0,depth:100,fitToPlot:!0,viewDistance:25,axisLabelPosition:null,frame:{visible:"default",size:1,bottom:{},top:{},left:{},right:{},back:{},front:{}}}}},t.compose=function(d,x){let y=d.prototype,f=x.prototype;y.is3d=function(){return!!this.options.chart.options3d?.enabled},y.propsRequireDirtyBox.push("chart.options3d"),y.propsRequireUpdateSeries.push("chart.options3d"),f.matrixSetter=function(){let t;if(this.pos<1&&(A(this.start)||A(this.end))){let e=this.start||[1,0,0,1,0,0],i=this.end||[1,0,0,1,0,0];t=[];for(let s=0;s<6;s++)t.push(this.pos*i[s]+(1-this.pos)*e[s])}else t=this.end;this.elem.attr(this.prop,t,null,!0)},k(!0,E,t.defaultOptions),m(d,"init",h),m(d,"addSeries",e),m(d,"afterDrawChartBox",i),m(d,"afterGetContainer",s),m(d,"afterInit",o),m(d,"afterSetChartSize",r),m(d,"beforeRedraw",a),m(d,"beforeRender",n),I(y,"isInsidePlot",l),I(y,"renderSeries",p),I(y,"setClassName",c)};class d{constructor(t){this.chart=t}get3dFrame(){let t=this.chart,e=t.options.chart.options3d,i=e.frame,s=t.plotLeft,o=t.plotLeft+t.plotWidth,r=t.plotTop,a=t.plotTop+t.plotHeight,n=e.depth,h=function(e){let i=R(e,t);return i>.5?1:i<-.5?-1:0},l=h([{x:s,y:a,z:n},{x:o,y:a,z:n},{x:o,y:a,z:0},{x:s,y:a,z:0}]),p=h([{x:s,y:r,z:0},{x:o,y:r,z:0},{x:o,y:r,z:n},{x:s,y:r,z:n}]),c=h([{x:s,y:r,z:0},{x:s,y:r,z:n},{x:s,y:a,z:n},{x:s,y:a,z:0}]),d=h([{x:o,y:r,z:n},{x:o,y:r,z:0},{x:o,y:a,z:0},{x:o,y:a,z:n}]),x=h([{x:s,y:a,z:0},{x:o,y:a,z:0},{x:o,y:r,z:0},{x:s,y:r,z:0}]),y=h([{x:s,y:r,z:n},{x:o,y:r,z:n},{x:o,y:a,z:n},{x:s,y:a,z:n}]),f=!1,u=!1,z=!1,b=!1;[].concat(t.xAxis,t.yAxis,t.zAxis).forEach(function(t){t&&(t.horiz?t.opposite?u=!0:f=!0:t.opposite?b=!0:z=!0)});let g=function(t,e,i){let s=["size","color","visible"],o={};for(let e=0;e0),{size:L(o.size,1),color:L(o.color,"none"),frontFacing:e>0,visible:r}},m={axes:{},bottom:g([i.bottom,i.top,i],l,f),top:g([i.top,i.bottom,i],p,u),left:g([i.left,i.right,i.side,i],c,z),right:g([i.right,i.left,i.side,i],d,b),back:g([i.back,i.front,i],y,!0),front:g([i.front,i.back,i],x,!1)};if("auto"===e.axisLabelPosition){let e=function(t,e){return t.visible!==e.visible||t.visible&&e.visible&&t.frontFacing!==e.frontFacing},i=[];e(m.left,m.front)&&i.push({y:(r+a)/2,x:s,z:0,xDir:{x:1,y:0,z:0}}),e(m.left,m.back)&&i.push({y:(r+a)/2,x:s,z:n,xDir:{x:0,y:0,z:-1}}),e(m.right,m.front)&&i.push({y:(r+a)/2,x:o,z:0,xDir:{x:0,y:0,z:1}}),e(m.right,m.back)&&i.push({y:(r+a)/2,x:o,z:n,xDir:{x:-1,y:0,z:0}});let h=[];e(m.bottom,m.front)&&h.push({x:(s+o)/2,y:a,z:0,xDir:{x:1,y:0,z:0}}),e(m.bottom,m.back)&&h.push({x:(s+o)/2,y:a,z:n,xDir:{x:-1,y:0,z:0}});let l=[];e(m.top,m.front)&&l.push({x:(s+o)/2,y:r,z:0,xDir:{x:1,y:0,z:0}}),e(m.top,m.back)&&l.push({x:(s+o)/2,y:r,z:n,xDir:{x:-1,y:0,z:0}});let p=[];e(m.bottom,m.left)&&p.push({z:(0+n)/2,y:a,x:s,xDir:{x:0,y:0,z:-1}}),e(m.bottom,m.right)&&p.push({z:(0+n)/2,y:a,x:o,xDir:{x:0,y:0,z:1}});let c=[];e(m.top,m.left)&&c.push({z:(0+n)/2,y:r,x:s,xDir:{x:0,y:0,z:-1}}),e(m.top,m.right)&&c.push({z:(0+n)/2,y:r,x:o,xDir:{x:0,y:0,z:1}});let d=function(e,i,s){if(0===e.length)return null;if(1===e.length)return e[0];let o=C(e,t,!1),r=0;for(let t=1;ts*o[r][i]?r=t:s*o[t][i]==s*o[r][i]&&o[t].zh.minX&&(p=Math.min(p,1-Math.abs((i+a)/(h.minX+a))%1)),sh.minY&&(p=h.minY<0?Math.min(p,(o+n)/(-h.minY+o+n)):Math.min(p,1-(o+n)/(h.minY+n)%1)),r({plotX:t.x,plotY:t.y,plotZ:t.z})),this.group&&a&&a.depth&&a.beta&&(this.markerGroup&&(this.markerGroup.add(this.group),this.markerGroup.attr({translateX:0,translateY:0})),this.group.attr({zIndex:Math.max(1,a.beta>270||a.beta<90?a.depth-Math.round(this.zPadding||0):Math.round(this.zPadding||0))})),r.reversed=!0;let n=i.call(this,r,!0,!0);if(n[0]&&"M"===n[0][0]&&(n[0]=["L",n[0][1],n[0][2]]),this.areaPath){let t=this.areaPath.splice(0,this.areaPath.length/2).concat(n);t.xMap=this.areaPath.xMap,this.areaPath=t}return this.graphPath=e,e}let V={labels:{position3d:"offset",skew3d:!1},title:{position3d:null,skew3d:null}},{composed:U}=f();function q(t){let e=this.axis.axis3D;e&&M(t.pos,e.fix3dPosition(t.pos))}function J(t){let e=this.axis.axis3D,i=t.apply(this,[].slice.call(arguments,1));if(e){let t=i[0],s=i[1];if("M"===t[0]&&"L"===s[0]){let i=[e.fix3dPosition({x:t[1],y:t[2],z:0}),e.fix3dPosition({x:s[1],y:s[2],z:0})];return this.axis.chart.renderer.toLineSegments(i)}}return i}let K=function(t){D(U,"Axis.Tick3D")&&(m(t,"afterGetLabelPosition",q),I(t.prototype,"getMarkPath",J))},{defaultOptions:Q}=f(),{deg2rad:$}=f(),{perspective:tt,perspective3D:te,shapeArea:ti}=Y;function ts(){let t=this.chart,e=this.options;t.is3d?.()&&"colorAxis"!==this.coll&&(e.tickWidth=L(e.tickWidth,0),e.gridLineWidth=L(e.gridLineWidth,1))}function to(t){this.chart.is3d()&&"colorAxis"!==this.coll&&t.point&&(t.point.crosshairPos=this.isXAxis?t.point.axisXpos:this.len-t.point.axisYpos)}function tr(){this.axis3D||(this.axis3D=new tc(this))}function ta(t){return this.chart.is3d()&&"colorAxis"!==this.coll?[]:t.apply(this,[].slice.call(arguments,1))}function tn(t){if(!this.chart.is3d()||"colorAxis"===this.coll)return t.apply(this,[].slice.call(arguments,1));let e=arguments,i=e[1],s=e[2],o=[],r=this.getPlotLinePath({value:i}),a=this.getPlotLinePath({value:s});if(r&&a)for(let t=0;tti(tt([t,{x:t.x+f.x,y:t.y+f.y,z:t.z+f.z},{x:t.x+u.x,y:t.y+u.y,z:t.z+u.z}],i.chart))&&(f={x:-f.x,y:-f.y,z:-f.z});let e=tt([{x:t.x,y:t.y,z:t.z},{x:t.x+f.x,y:t.y+f.y,z:t.z+f.z},{x:t.x+u.x,y:t.y+u.y,z:t.z+u.z}],i.chart);b.matrix=[e[1].x-e[0].x,e[1].y-e[0].y,e[2].x-e[0].x,e[2].y-e[0].y,b.x,b.y],b.matrix[4]-=b.x*b.matrix[0]+b.y*b.matrix[2],b.matrix[5]-=b.x*b.matrix[1]+b.y*b.matrix[3]}return b}swapZ(t,e){let i=this.axis;if(i.isZAxis){let s=e?0:i.chart.plotLeft;return{x:s+t.z,y:t.y,z:t.x-s}}return t}}var td=d(608),tx=d.n(td),ty=d(820),tf=d.n(ty);let{composed:tu}=f(),{perspective:tz}=Y;class tb extends tf(){static compose(t){D(tu,"Core.Series3D")&&(m(t,"afterTranslate",function(){this.chart.is3d()&&this.translate3dPoints()}),M(t.prototype,{translate3dPoints:tb.prototype.translate3dPoints}))}translate3dPoints(){var t;let e,i,s=this,o=s.options,r=s.chart,a=L(s.zAxis,r.options.zAxis[0]),n=[],h=[],l=o.stacking?"number"==typeof(t=o.stack)&&!isNaN(t)&&t<1/0&&t>-1/0?o.stack:0:s.index||0;s.zPadding=l*(o.depth||0+(o.groupZPadding||1)),s.points.forEach(t=>{a?.translate?(i=a.logarithmic&&a.val2lin?a.val2lin(t.z):t.z,t.plotZ=a.translate(i),t.isInside=!!t.isInside&&i>=a.min&&i<=a.max):t.plotZ=s.zPadding,t.axisXpos=t.plotX,t.axisYpos=t.plotY,t.axisZpos=t.plotZ,n.push({x:t.plotX,y:t.plotY,z:t.plotZ}),h.push(t.plotX||0)}),s.rawPointsX=h;let p=tz(n,r,!0);s.points.forEach((t,i)=>{t.plotX=(e=p[i]).x,t.plotY=e.y,t.plotZ=e.z})}}tb.defaultOptions=k(tf().defaultOptions);var tg=d(184),tm=d.n(tg);let{parse:tv}=z(),{Element:tM}=tx().getRendererType().prototype;class tP extends tM{constructor(){super(...arguments),this.parts=["front","top","side"],this.pathType="cuboid"}initArgs(t){let e=this.renderer,i=e[this.pathType+"Path"](t),s=i.zIndexes;for(let t of this.parts){let o={class:"highcharts-3d-"+t,zIndex:s[t]||0};e.styledMode&&("top"===t?o.filter="url(#highcharts-brighter)":"side"===t&&(o.filter="url(#highcharts-darker)")),this[t]=e.path(i[t]).attr(o).add(this)}this.attr({"stroke-linejoin":"round",zIndex:s.group}),this.forcedSides=i.forcedSides}singleSetterForParts(t,e,i,s,o,r){let a={},n=[null,null,s||"attr",o,r],h=i?.zIndexes;if(i){for(let e of(h?.group&&this.attr({zIndex:h.group}),Object.keys(i)))a[e]={},a[e][t]=i[e],h&&(a[e].zIndex=i.zIndexes[e]||0);n[1]=a}else a[t]=e,n[0]=a;return this.processParts.apply(this,n)}processParts(t,e,i,s,o){for(let r of this.parts)e&&(t=L(e[r],!1)),!1!==t&&this[r][i](t,s,o);return this}destroy(){return this.processParts(null,null,"destroy"),super.destroy()}attr(t,e,i,s){if("string"==typeof t&&void 0!==e){let i=t;(t={})[i]=e}return t.shapeArgs||v(t.x)?this.singleSetterForParts("d",null,this.renderer[this.pathType+"Path"](t.shapeArgs||t)):super.attr(t,void 0,i,s)}animate(t,e,i){if(v(t.x)&&v(t.y)){let s=this.renderer[this.pathType+"Path"](t),o=s.forcedSides;this.singleSetterForParts("d",null,s,"animate",e,i),this.attr({zIndex:s.zIndexes.group}),o!==this.forcedSides&&(this.forcedSides=o,this.renderer.styledMode||this.fillSetter(this.fill))}else super.animate(t,e,i);return this}fillSetter(t){return this.forcedSides=this.forcedSides||[],this.singleSetterForParts("fill",null,{front:t,top:tv(t).brighten(this.forcedSides.indexOf("top")>=0?0:.1).get(),side:tv(t).brighten(this.forcedSides.indexOf("side")>=0?0:-.1).get()}),this.color=this.fill=t,this}}tP.types={base:tP,cuboid:tP};let{animObject:tA}=f(),{parse:tS}=z(),{charts:tk,deg2rad:tw}=f(),{perspective:tL,shapeArea:tD}=Y,tI=Math.cos,tT=Math.sin,tO=Math.PI,tX=4*(Math.sqrt(2)-1)/3/(tO/2);function tH(t,e,i,s,o,r,a,n){let h=r-o,l=[];return r>o&&r-o>Math.PI/2+1e-4?l=(l=l.concat(tH(t,e,i,s,o,o+Math.PI/2,a,n))).concat(tH(t,e,i,s,o+Math.PI/2,r,a,n)):rMath.PI/2+1e-4?l=(l=l.concat(tH(t,e,i,s,o,o-Math.PI/2,a,n))).concat(tH(t,e,i,s,o-Math.PI/2,r,a,n)):[["C",t+i*Math.cos(o)-i*tX*h*Math.sin(o)+a,e+s*Math.sin(o)+s*tX*h*Math.cos(o)+n,t+i*Math.cos(r)+i*tX*h*Math.sin(r)+a,e+s*Math.sin(r)-s*tX*h*Math.cos(r)+n,t+i*Math.cos(r)+a,e+s*Math.sin(r)+n]]}!function(t){function e(t,e){let i=[];for(let e of t)i.push(["L",e.x,e.y]);return t.length&&(i[0][0]="M",e&&i.push(["Z"])),i}function i(t){let e=[],i=!0;for(let s of t)e.push(i?["M",s.x,s.y]:["L",s.x,s.y]),i=!i;return e}function s(t){let e=this,i=e.Element.prototype,s=e.createElement("path");return s.vertexes=[],s.insidePlotArea=!1,s.enabled=!0,s.attr=function(t){if("object"==typeof t&&(v(t.enabled)||v(t.vertexes)||v(t.insidePlotArea))){this.enabled=L(t.enabled,this.enabled),this.vertexes=L(t.vertexes,this.vertexes),this.insidePlotArea=L(t.insidePlotArea,this.insidePlotArea),delete t.enabled,delete t.vertexes,delete t.insidePlotArea;let i=tk[e.chartIndex],s=tL(this.vertexes,i,this.insidePlotArea),o=e.toLinePath(s,!0),r=tD(s);t.d=o,t.visibility=this.enabled&&r>0?"inherit":"hidden"}return i.attr.apply(this,arguments)},s.animate=function(t){if("object"==typeof t&&(v(t.enabled)||v(t.vertexes)||v(t.insidePlotArea))){this.enabled=L(t.enabled,this.enabled),this.vertexes=L(t.vertexes,this.vertexes),this.insidePlotArea=L(t.insidePlotArea,this.insidePlotArea),delete t.enabled,delete t.vertexes,delete t.insidePlotArea;let i=tk[e.chartIndex],s=tL(this.vertexes,i,this.insidePlotArea),o=e.toLinePath(s,!0),r=tD(s),a=this.enabled&&r>0?"visible":"hidden";t.d=o,this.attr("visibility",a)}return i.animate.apply(this,arguments)},s.attr(t)}function o(t){let e=this,i=e.Element.prototype,s=e.g(),o=s.destroy;return this.styledMode||s.attr({"stroke-linejoin":"round"}),s.faces=[],s.destroy=function(){for(let t=0;tt.faces.length;)s.faces.pop().destroy();for(;s.faces.lengtht.faces.length;)s.faces.pop().destroy();for(;s.faces.length0===o&&t>1&&t<6?{x:d[t].x,y:d[t].y+10,z:d[t].z}:d[0].x===d[7].x&&t>=4?{x:d[t].x+10,y:d[t].y,z:d[t].z}:0===a&&t<2||t>5?{x:d[t].x,y:d[t].y,z:d[t].z+10}:d[t],y=t=>d[t],f=(t,e,i)=>{let s=t.map(y),o=e.map(y),r=t.map(x),a=e.map(x),n=[[],-1];return 0>tD(s)?n=[s,0]:0>tD(o)?n=[o,1]:i&&(l.push(i),n=0>tD(r)?[s,0]:0>tD(a)?[o,1]:[s,0]),n},u=(p=f([3,2,1,0],[7,6,5,4],"front"))[0],z=p[1],b=(p=f([1,6,7,0],[4,5,2,3],"top"))[0],g=p[1],m=(p=f([1,2,5,6],[0,7,4,3],"side"))[0],v=p[1];return 1===v?c+=1e6*(n.plotWidth-e):v||(c+=1e6*e),c+=10*(!g||h>=0&&h<=180||h<360&&h>357.5?n.plotHeight-i:10+i),1===z?c+=100*s:z||(c+=100*(1e3-s)),{front:this.toLinePath(u,!0),top:this.toLinePath(b,!0),side:this.toLinePath(m,!0),zIndexes:{group:Math.round(c)},forcedSides:l,isFront:z,isTop:g}}function h(t){let e=this.g(),i=this.Element.prototype,s=["alpha","beta","x","y","r","innerR","start","end","depth"];function o(t){let e,i={};for(e in t=k(t))-1!==s.indexOf(e)&&(i[e]=t[e],delete t[e]);return!!Object.keys(i).length&&[i,t]}for(let i of((t=k(t)).alpha=(t.alpha||0)*tw,t.beta=(t.beta||0)*tw,e.top=this.path(),e.side1=this.path(),e.side2=this.path(),e.inn=this.path(),e.out=this.path(),e.onAdd=function(){let t=e.parentGroup,i=e.attr("class");for(let s of(e.top.add(e),["out","inn","side1","side2"]))e[s].attr({class:i+" highcharts-3d-side"}).add(t)},["addClass","removeClass"]))e[i]=function(){let t=arguments;for(let s of["top","out","inn","side1","side2"])e[s][i].apply(e[s],t)};for(let i of(e.setPaths=function(t){let i=e.renderer.arc3dPath(t),s=100*i.zTop;e.attribs=t,e.top.attr({d:i.top,zIndex:i.zTop}),e.inn.attr({d:i.inn,zIndex:i.zInn}),e.out.attr({d:i.out,zIndex:i.zOut}),e.side1.attr({d:i.side1,zIndex:i.zSide1}),e.side2.attr({d:i.side2,zIndex:i.zSide2}),e.zIndex=s,e.attr({zIndex:s}),t.center&&(e.top.setRadialReference(t.center),delete t.center)},e.setPaths(t),e.fillSetter=function(t){let e=tS(t).brighten(-.1).get();return this.fill=t,this.side1.attr({fill:e}),this.side2.attr({fill:e}),this.inn.attr({fill:e}),this.out.attr({fill:e}),this.top.attr({fill:t}),this},["opacity","translateX","translateY","visibility"]))e[i+"Setter"]=function(t,i){for(let s of(e[i]=t,["out","inn","side1","side2","top"]))e[s].attr(i,t)};return e.attr=function(t){if("object"==typeof t){let i=o(t);if(i){let t=i[0];arguments[0]=i[1],void 0!==t.alpha&&(t.alpha*=tw),void 0!==t.beta&&(t.beta*=tw),M(e.attribs,t),e.attribs&&e.setPaths(e.attribs)}}return i.attr.apply(e,arguments)},e.animate=function(t,s,r){let a=this.attribs,n="data-"+Math.random().toString(26).substring(2,9);delete t.center,delete t.z;let h=tA(L(s,this.renderer.globalAnimation));if(h.duration){let i=o(t);if(e[n]=0,t[n]=1,e[n+"Setter"]=f().noop,i){let t=i[0],e=(e,i)=>a[e]+(L(t[e],a[e])-a[e])*i;h.step=function(t,i){i.prop===n&&i.elem.setPaths(k(a,{x:e("x",i.pos),y:e("y",i.pos),r:e("r",i.pos),innerR:e("innerR",i.pos),start:e("start",i.pos),end:e("end",i.pos),depth:e("depth",i.pos)}))}}s=h}return i.animate.call(this,t,s,r)},e.destroy=function(){return this.top.destroy(),this.out.destroy(),this.inn.destroy(),this.side1.destroy(),this.side2.destroy(),i.destroy.call(this)},e.hide=function(){this.top.hide(),this.out.hide(),this.inn.hide(),this.side1.hide(),this.side2.hide()},e.show=function(t){this.top.show(t),this.out.show(t),this.inn.show(t),this.side1.show(t),this.side2.show(t)},e}function l(t){let e=t.x||0,i=t.y||0,s=t.start||0,o=(t.end||0)-1e-5,r=t.r||0,a=t.innerR||0,n=t.depth||0,h=t.alpha||0,l=t.beta||0,p=Math.cos(s),c=Math.sin(s),d=Math.cos(o),x=Math.sin(o),y=r*Math.cos(l),f=r*Math.cos(h),u=a*Math.cos(l),z=a*Math.cos(h),b=n*Math.sin(l),g=n*Math.sin(h),m=[["M",e+y*p,i+f*c]];(m=m.concat(tH(e,i,y,f,s,o,0,0))).push(["L",e+u*d,i+z*x]),(m=m.concat(tH(e,i,u,z,o,s,0,0))).push(["Z"]);let v=l>0?Math.PI/2:0,M=h>0?0:Math.PI/2,P=s>-v?s:o>-v?-v:s,A=oS&&stO-M&&sMath.PI&&(t=2*Math.PI-t),t}T=H(T),O=H(O);let Y=1e5*(X=H(X)),Z=1e5*O,E=1e5*T;return{top:m,zTop:1e5*Math.PI+1,out:k,zOut:Math.max(Y,Z,E),inn:w,zInn:Math.max(Y,Z,E),side1:L,zSide1:.99*E,side2:D,zSide2:.99*Z}}t.compose=function(t){let p=t.prototype;p.element3d||M(p,{Element3D:tP,arc3d:h,arc3dPath:l,cuboid:a,cuboidPath:n,element3d:r,face3d:s,polyhedron:o,toLinePath:e,toLineSegments:i})}}(l||(l={}));let tY=l;var tZ=d(532),tE=d.n(tZ);let{defaultOptions:tC}=f();function tR(t){return new t_(this,t)}function tF(){var t;let e=this.options.zAxis=A(t=this.options.zAxis||{})?t:[t];this.is3d()&&(this.zAxis=[],e.forEach(t=>{this.addZAxis(t).setScale()}))}class t_ extends tE(){constructor(){super(...arguments),this.isZAxis=!0}static compose(t){let e=t.prototype;e.addZAxis||(tC.zAxis=k(tC.xAxis,{offset:0,lineWidth:0}),e.addZAxis=tR,e.collectionsWithInit.zAxis=[e.addZAxis],e.collectionsWithUpdate.push("zAxis"),m(t,"afterCreateAxes",tF))}init(t,e){this.isZAxis=!0,super.init(t,e,"zAxis")}getSeriesExtremes(){this.hasVisibleSeries=!1,this.dataMin=this.dataMax=this.ignoreMinPadding=this.ignoreMaxPadding=void 0,this.stacking&&this.stacking.buildStacks(),this.series.forEach(t=>{if(t.reserveSpace()){let e=t.options.threshold;this.hasVisibleSeries=!0,this.positiveValuesOnly&&e<=0&&(e=void 0);let i=t.getColumn("z");i.length&&(this.dataMin=Math.min(L(this.dataMin,i[0]),Math.min.apply(null,i)),this.dataMax=Math.max(L(this.dataMax,i[0]),Math.max.apply(null,i)))}})}setAxisSize(){let t=this.chart;super.setAxisSize(),this.width=this.len=t.options.chart.options3d?.depth||0,this.right=t.chartWidth-this.width-this.left}}let{composed:tj}=f(),{perspective:tW}=Y;function tB(){let t=this.chart,e=this.options,i=e.depth,s=(e.stacking?e.stack||0:this.index)*(i+(e.groupZPadding||1)),o=this.borderWidth%2?.5:0,r;for(let a of(t.inverted&&!this.yAxis.reversed&&(o*=-1),!1!==e.grouping&&(s=0),s+=e.groupZPadding||1,this.points))if(a.outside3dPlot=null,null!==a.y){let e,n=M({x:0,y:0,width:0,height:0},a.shapeArgs||{}),h=[["x","width"],["y","height"]],l=a.tooltipPos;for(let t of h)if((e=n[t[0]]-o)<0&&(n[t[1]]+=n[t[0]]+o,n[t[0]]=-o,e=0),e+n[t[1]]>this[t[0]+"Axis"].len&&0!==n[t[1]]&&(n[t[1]]=this[t[0]+"Axis"].len-n[t[0]]),0!==n[t[1]]&&(n[t[0]]>=this[t[0]+"Axis"].len||n[t[0]]+n[t[1]]<=o)){for(let t in n)n[t]="y"===t?-9999:0;a.outside3dPlot=!0}if("roundedRect"===a.shapeType&&(a.shapeType="cuboid"),a.shapeArgs=M(n,{z:s,depth:i,insidePlotArea:!0}),r={x:n.x+n.width/2,y:n.y,z:s+i/2},t.inverted&&(r.x=n.height,r.y=a.clientX||0),a.axisXpos=r.x,a.axisYpos=r.y,a.axisZpos=r.z,a.plot3d=tW([r],t,!0,!1)[0],l){let e=tW([{x:l[0],y:l[1],z:s+i/2}],t,!0,!1)[0];a.tooltipPos=[e.x,e.y]}}this.z=s}function tG(){if(this.chart.is3d()){let i=this.options,s=i.grouping,o=i.stacking,r=this.yAxis.options.reversedStacks,a=0;if(!(void 0!==s&&!s)){var t,e;let s,n,h,l,p,c=(t=this.chart,e=o||void 0,n=t.series,h={totalStacks:0},p=1,n.forEach(function(t){h[l=L(t.options.stack,e?0:n.length-1-t.index)]?h[l].series.push(t):(h[l]={series:[t],position:p},p++)}),h.totalStacks=p+1,h),d=i.stack||0;for(s=0;s=90&&a.alpha<=270&&(h.y+=e.shapeArgs.width)),o.x=(h=tW([h],r,!0,!1)[0]).x-n,o.y=e.outside3dPlot?-9e9:h.y}t.apply(this,[].slice.call(arguments,1))}function t0(t){return!arguments[2].outside3dPlot&&t.apply(this,[].slice.call(arguments,1))}function t1(t,e){let i=t.apply(this,[].slice.call(arguments,1)),s=this.axis.chart,{width:o}=e;if(s.is3d()&&this.base){let t=+this.base.split(",")[0],e=s.series[t],r=s.options.chart.options3d;if(e&&"column"===e.type){let t={x:i.x+(s.inverted?i.height:o/2),y:i.y,z:e.options.depth/2};s.inverted&&(i.width=0,r.alpha>=90&&r.alpha<=270&&(t.y+=o)),i.x=(t=tW([t],s,!0,!1)[0]).x-o/2,i.y=t.y}}return i}let{pie:{prototype:{pointClass:t3}}}=j().seriesTypes,t2=class extends t3{haloPath(){return this.series?.chart.is3d()?[]:super.haloPath.apply(this,arguments)}},{composed:t5,deg2rad:t6}=f(),{pie:t9}=j().seriesTypes;class t4 extends t9{static compose(t){D(t5,"Pie3D")&&(t.types.pie=t4)}addPoint(){super.addPoint.apply(this,arguments),this.chart.is3d()&&this.update(this.userOptions,!0)}animate(t){if(this.chart.is3d()){let e=this.center,i=this.group,s=this.markerGroup,o=this.options.animation,r;!0===o&&(o={}),t?(i.oldtranslateX=L(i.oldtranslateX,i.translateX),i.oldtranslateY=L(i.oldtranslateY,i.translateY),r={translateX:e[0],translateY:e[1],scaleX:.001,scaleY:.001},i.attr(r),s&&(s.attrSetters=i.attrSetters,s.attr(r))):(r={translateX:i.oldtranslateX,translateY:i.oldtranslateY,scaleX:1,scaleY:1},i.animate(r,o),s&&s.animate(r,o))}else super.animate.apply(this,arguments)}getDataLabelPosition(t,e){let i=super.getDataLabelPosition(t,e);if(this.chart.is3d()){let e=this.chart.options.chart.options3d,s=t.shapeArgs,o=s.r,r=(s.alpha||e?.alpha)*t6,a=(s.beta||e?.beta)*t6,n=(s.start+s.end)/2,h=i.connectorPosition,l=-o*(1-Math.cos(r))*Math.sin(n),p=o*(Math.cos(a)-1)*Math.cos(n);for(let t of[i?.natural,h.breakAt,h.touchingSliceAt])t.x+=p,t.y+=l}return i}pointAttribs(t){let e=super.pointAttribs.apply(this,arguments),i=this.options;return this.chart.is3d()&&!this.chart.styledMode&&(e.stroke=i.edgeColor||t.color||this.color,e["stroke-width"]=L(i.edgeWidth,1)),e}translate(){if(super.translate.apply(this,arguments),!this.chart.is3d())return;let t=this.options,e=t.depth||0,i=this.chart.options.chart.options3d,s=i.alpha,o=i.beta,r=t.stacking?(t.stack||0)*e:this._i*e;for(let i of(r+=e/2,!1!==t.grouping&&(r=0),this.points)){let a=i.shapeArgs;i.shapeType="arc3d",a.z=r,a.depth=.75*e,a.alpha=s,a.beta=o,a.center=this.center;let n=(a.end+a.start)/2;i.slicedTranslation={translateX:Math.round(Math.cos(n)*t.slicedOffset*Math.cos(s*t6)),translateY:Math.round(Math.sin(n)*t.slicedOffset*Math.cos(s*t6))}}}drawTracker(){if(super.drawTracker.apply(this,arguments),this.chart.is3d()){for(let t of this.points)if(t.graphic)for(let e of["out","inn","side1","side2"])t.graphic&&(t.graphic[e].element.point=t)}}}M(t4.prototype,{pointClass:t2});var t7=d(632),t8=d.n(t7);let{pointClass:et}=t8().prototype,ee=class extends et{applyOptions(){return super.applyOptions.apply(this,arguments),v(this.z)||(this.z=0),this}},{pointCameraDistance:ei}=Y;class es extends t8(){pointAttribs(t){let e=super.pointAttribs.apply(this,arguments);return this.chart.is3d()&&t&&(e.zIndex=ei(t,this.chart)),e}}es.defaultOptions=k(t8().defaultOptions,{tooltip:{pointFormat:"x: {point.x}
y: {point.y}
z: {point.z}
"}}),M(es.prototype,{axisTypes:["xAxis","yAxis","zAxis"],directTouch:!0,parallelArrays:["x","y","z"],pointArrayMap:["x","y","z"],pointClass:ee}),j().registerSeriesType("scatter3d",es);let eo=f();({compose:function(t){D(W,"Area3DSeries")&&I(t.prototype,"getGraphPath",N)}}).compose(eo.Series.types.area),tc.compose(eo.Axis,eo.Tick),F.compose(eo.Chart,eo.Fx),({compose:function(t,e){if(D(tj,"Column3D")){let i=t.prototype,s=e.prototype,{column:o,columnRange:r}=t.types;if(I(i,"alignDataLabel",t$),I(i,"justifyDataLabel",t0),I(s,"getStackBox",t1),o){let t=o.prototype,e=t.pointClass.prototype;t.translate3dPoints=()=>void 0,t.translate3dShapes=tB,m(t,"afterInit",tG),I(e,"hasNewShapeType",tN),I(t,"animate",tV),I(t,"plotGroup",tU),I(t,"pointAttribs",tq),I(t,"setState",tJ),I(t,"setVisible",tK),I(t,"translate",tQ)}if(r){let t=r.prototype;I(t.pointClass.prototype,"hasNewShapeType",tN),I(t,"plotGroup",tU),I(t,"pointAttribs",tq),I(t,"setState",tJ),I(t,"setVisible",tK)}}}}).compose(eo.Series,tm()),t4.compose(eo.Series),tb.compose(eo.Series),tY.compose(tx().getRendererType()),t_.compose(eo.Chart);let er=eo;return x.default})()); \ No newline at end of file diff --git a/.claude/skills/session-metrics/scripts/vendor/charts/highcharts/v12/highcharts.js b/.claude/skills/session-metrics/scripts/vendor/charts/highcharts/v12/highcharts.js new file mode 100644 index 0000000..65688bf --- /dev/null +++ b/.claude/skills/session-metrics/scripts/vendor/charts/highcharts/v12/highcharts.js @@ -0,0 +1,10 @@ +!/** + * Highcharts JS v12.6.0 (2026-04-13) + * @module highcharts/highcharts + * + * (c) 2009-2026 Highsoft AS + * + * A commercial license may be required depending on use. + * See www.highcharts.com/license + */function(t,e){"object"==typeof exports&&"object"==typeof module?(t._Highcharts=e(),module.exports=t._Highcharts):"function"==typeof define&&define.amd?define("highcharts/highcharts",[],e):"object"==typeof exports?(t._Highcharts=e(),exports.highcharts=t._Highcharts):(t.Highcharts&&t.Highcharts.error(16,!0),t.Highcharts=e())}("u"(()=>{"use strict";let t,e,i,s,o,r;var a,n,h,l,d,c,p,g,u,f,m,x,y,b,v,k,w,M,S,T,C,A,P,L,O,E,I={};I.d=(t,e)=>{for(var i in e)I.o(e,i)&&!I.o(t,i)&&Object.defineProperty(t,i,{enumerable:!0,get:e[i]})},I.o=(t,e)=>Object.prototype.hasOwnProperty.call(t,e);var D={};I.d(D,{default:()=>on}),(a=f||(f={})).SVG_NS="http://www.w3.org/2000/svg",a.product="Highcharts",a.version="12.6.0",a.win="u">typeof window?window:{},a.doc=a.win.document,a.svg=!!a.doc?.createElementNS?.(a.SVG_NS,"svg")?.createSVGRect,a.pageLang=a.doc?.documentElement?.closest("[lang]")?.lang,a.userAgent=a.win.navigator?.userAgent||"",a.isChrome=a.win.chrome,a.isFirefox=-1!==a.userAgent.indexOf("Firefox"),a.isMS=/(edge|msie|trident)/i.test(a.userAgent)&&!a.win.opera,a.isSafari=!a.isChrome&&-1!==a.userAgent.indexOf("Safari"),a.isTouchDevice=/(Mobile|Android|Windows Phone)/.test(a.userAgent),a.isWebKit=-1!==a.userAgent.indexOf("AppleWebKit"),a.deg2rad=2*Math.PI/360,a.marginNames=["plotTop","marginRight","marginBottom","plotLeft"],a.noop=function(){},a.supportsPassiveEvents=function(){let t=!1;if(!a.isMS){let e=Object.defineProperty({},"passive",{get:function(){t=!0}});a.win.addEventListener&&a.win.removeEventListener&&(a.win.addEventListener("testPassive",a.noop,e),a.win.removeEventListener("testPassive",a.noop,e))}return t}(),a.charts=[],a.composed=[],a.dateFormats={},a.seriesTypes={},a.symbolSizes={},a.chartCount=0;let B=f,{doc:N,win:z}=B;function R(t,e,i,s={}){let o="function"==typeof t&&t.prototype||t;Object.hasOwnProperty.call(o,"hcEvents")||(o.hcEvents={});let r=o.hcEvents;B.Point&&t instanceof B.Point&&t.series&&t.series.chart&&(t.series.chart.runTrackerClick=!0);let a=t.addEventListener;a&&a.call(t,e,i,!!B.supportsPassiveEvents&&{passive:void 0===s.passive?-1!==e.indexOf("touch"):s.passive,capture:!1}),r[e]||(r[e]=[]);let n={fn:i,order:"number"==typeof s.order?s.order:1/0};return r[e].push(n),r[e].sort((t,e)=>t.order-e.order),function(){tS(t,e,i)}}function W(t){let e=t.length,i=t[0];for(;e--;)t[e]i&&(i=t[e]);return i}function X(t,e,i){let s,o=td(e)&&!V(i),r=(e,i)=>{V(e)?t.setAttribute(i,e):o?(s=t.getAttribute(i))||"class"!==i||(s=t.getAttribute(i+"Name")):t.removeAttribute(i)};return td(e)?r(i,e):tm(e,r),s}function G(t,e,i){return t>e?t1e14?t:parseFloat(t.toPrecision(e||14))}function Y(t,e,i,s,o){let r=N.createElement(t);return e&&q(r,e),o&&$(r,{padding:"0",border:"none",margin:"0"}),i&&$(r,i),s&&s.appendChild(r),r}function j(t,e=0,i){let s=e%2/2,o=i?-1:1;return(Math.round(t*o-s)+s)*o}function $(t,e){q(t.style,e)}function V(t){return null!=t}function U(t,e,i){tm(t,function(s,o){s!==e&&s?.destroy&&s.destroy(),(s?.destroy||!i)&&delete t[o]})}function Z(t){t?.parentElement?.removeChild(t)}function _(t,e,i,s){let o={};return!function t(e,o,r,a){let n=i?o:e;tm(e,function(i,h){if(!a&&s&&s.indexOf(h)>-1&&o[h]){i=tT(i),r[h]=[];for(let e=0;et.order-e.order),s.forEach(e=>{!1===e.fn.call(t,i,t)&&i.preventDefault()})}s&&!i.defaultPrevented&&s.call(t,i)}let tt=(t="")=>({center:.5,right:1,middle:.5,bottom:1})[t]||0;function te(t,e){let i,s,o,r,a=!e;return t.forEach(t=>{if(t.length>1)for(r=s=t.length-1;r>0;r--)(o=t[r]-t[r-1])<0&&!a?(e?.(),e=void 0):o&&(void 0===i||o=e-1&&(e=Math.floor(i)),Math.max(0,e-(to(t,"padding-left",!0)||0)-(to(t,"padding-right",!0)||0))}if("height"===e)return Math.max(0,Math.min(t.offsetHeight,t.scrollHeight)-(to(t,"padding-top",!0)||0)-(to(t,"padding-bottom",!0)||0));let o=z.getComputedStyle(t,void 0);return o&&(s=o.getPropertyValue(e),tb(i,"opacity"!==e)&&(s=tv(s))),s}let tr=Array.prototype.find?function(t,e){return t.find(e)}:function(t,e){let i,s=t.length;for(i=0;i-1/0}function td(t){return"string"==typeof t}function tc(t){let e=Object.prototype.toString.call(t);return"[object Array]"===e||"[object Array Iterator]"===e}function tp(t){return"function"==typeof t}function tg(t,e){return!!t&&"object"==typeof t&&(!e||!tc(t))}function tu(t,...e){let i,s=[t,...e],o={},r=function(t,e){return"object"!=typeof t&&(t={}),tm(e,function(i,s){"__proto__"!==s&&"constructor"!==s&&(!tg(i,!0)||th(i)||tn(i)?t[s]=e[s]:t[s]=r(t[s]||{},i))}),t};!0===t&&(o=s[1],s=Array.prototype.slice.call(s,2));let a=s.length;for(i=0;i=t))&&(o||!(n<=(e[r]+(e[r+1]||e[r]))/2)));r++);return F(a*i,-Math.round(Math.log(.001)/Math.LN10))}function tm(t,e,i){for(let s in t)Object.hasOwnProperty.call(t,s)&&e.call(i||t[s],t[s],s,t)}function tx(t){let e=N.documentElement,i=t.parentElement||t.parentNode?t.getBoundingClientRect():{top:0,left:0,width:0,height:0};return{top:i.top+(z.pageYOffset||e.scrollTop)-(e.clientTop||0),left:i.left+(z.pageXOffset||e.scrollLeft)-(e.clientLeft||0),width:i.width,height:i.height}}function ty(t,e,i){return Array((e||2)+1-String(t).replace("-","").length).join(i||"0")+t}function tb(){let t=arguments,e=t.length;for(let i=0;it.indexOf(e)&&!!t.push(e)}function tw(t,e,i){return/%$/.test(t)?e*parseFloat(t)/100+(i||0):parseFloat(t)}function tM(t,...e){let i,s;do for(s of(i=t,e))t=t.replace(s[0],s[1]);while(t!==i);return t}function tS(t,e,i){function s(e,i){let s=t.removeEventListener;s&&s.call(t,e,i,!1)}function o(i){let o,r;t.nodeName&&(e?(o={})[e]=!0:o=i,tm(o,function(t,e){if(i[e])for(r=i[e].length;r--;)s(e,i[e][r].fn)}))}let r="function"==typeof t&&t.prototype||t;if(Object.hasOwnProperty.call(r,"hcEvents")){let t=r.hcEvents;if(e){let r=t[e]||[];i?(t[e]=r.filter(function(t){return i!==t.fn}),s(e,i)):(o(t),t[e]=[])}else o(t),delete r.hcEvents}}function tT(t){return tc(t)?t:[t]}function tC(t,e){let i,s,o=t.length;for(s=0;s0?setTimeout(t,e,i):(t.call(0,i),-1)}function tP(t){return td(t)?t.substring(0,1).toUpperCase()+t.substring(1):String(t)}let{charts:tL,win:tO}=B;function tE(t,e,i,s){let o=e?"Highcharts error":"Highcharts warning";32===t&&(t=`${o}: Deprecated member`);let r=tl(t),a=r?`${o} #${t}: www.highcharts.com/errors/${t}/`:t.toString();if(void 0!==s){let t="";r&&(a+="?"),tm(s,function(e,i){t+=` + - ${i}: ${e}`,r&&(a+=encodeURI(i)+"="+encodeURI(e))}),a+=t}Q(B,"displayError",{chart:i,code:t,message:a,params:s},function(){if(e)throw Error(a);tO.console&&-1===tE.messages.indexOf(a)&&console.warn(a)}),tE.messages.push(a)}function tI(t,e){let i,s=t.options.index,o=e.length;for(i=t.options.isInternal?o:0;i0?"+":"")+e/60),this.variableTimezone="UTC"!==o&&o?.indexOf("Etc/GMT")!==0,this.timezone=o,this.lang&&s&&(this.lang.locale=s),["months","shortMonths","weekdays","shortWeekdays"].forEach(t=>{let e=/months/i.test(t),i=/short/.test(t),s={timeZone:"UTC"};s[e?"month":"weekday"]=i?"short":"long",this[t]=(e?[0,1,2,3,4,5,6,7,8,9,10,11]:[3,4,5,6,7,8,9]).map(t=>this.dateFormat(s,(e?31:1)*24*36e5*t))})}toParts(t){let[e,i,s,o,r,a,n]=this.dateTimeFormat({weekday:"narrow",day:"numeric",month:"numeric",year:"numeric",hour:"numeric",minute:"numeric",second:"numeric"},t,"es").split(/(?:, | |\/|:)/g);return[o,s-1,i,r,a,n,Math.floor(Number(t)||0)%1e3,"DLMXJVS".indexOf(e)].map(Number)}dateTimeFormat(t,e,i=this.options.locale||tN){let s=JSON.stringify(t)+i;td(t)&&(t=this.str2dtf(t));let o=this.dTLCache[s];if(!o){t.timeZone??(t.timeZone=this.timezone);try{o=new Intl.DateTimeFormat(i,t)}catch(e){/Invalid time zone/i.test(e.message)?(tE(34),t.timeZone="UTC",o=new Intl.DateTimeFormat(i,t)):tE(e.message,!1)}}return this.dTLCache[s]=o,o?.format(e)||""}str2dtf(t,e={}){let i={L:{fractionalSecondDigits:3},S:{second:"2-digit"},M:{minute:"numeric"},H:{hour:"2-digit"},k:{hour:"numeric"},E:{weekday:"narrow"},a:{weekday:"short"},A:{weekday:"long"},d:{day:"2-digit"},e:{day:"numeric"},b:{month:"short"},B:{month:"long"},m:{month:"2-digit"},o:{month:"numeric"},y:{year:"2-digit"},Y:{year:"numeric"}};return Object.keys(i).forEach(s=>{-1!==t.indexOf(s)&&q(e,i[s])}),e}makeTime(t,e,i=1,s=0,o,r,a){let n=this.Date.UTC(t,e,i,s,o||0,r||0,a||0);if("UTC"!==this.timezone){let t=this.getTimezoneOffset(n);if(n+=t,-1!==[2,3,8,9,10,11].indexOf(e)&&(s<5||s>20)){let e=this.getTimezoneOffset(n);t!==e?n+=e-t:t-36e5!==this.getTimezoneOffset(n-36e5)||tR||(n-=36e5)}}return n}parse(t){if(!td(t))return t??void 0;let e=(t=t.replace(/\//g,"-").replace(/(GMT|UTC)/,"")).indexOf("Z")>-1||/([+-][0-9]{2}):?[0-9]{2}$/.test(t),i=/^[0-9]{4}-[0-9]{2}(-[0-9]{2}|)$/.test(t);e||i||(t+="Z");let s=Date.parse(t);if(tl(s))return s+(!e||i?this.getTimezoneOffset(s):0)}getTimezoneOffset(t){if("UTC"!==this.timezone){let[e,i,s,o,r=0]=this.dateTimeFormat({timeZoneName:"shortOffset"},t,"en").split(/(GMT|:)/).map(Number),a=-(60*(s+r/60)*6e4);if(tl(a))return a}return 0}dateFormat(t,e,i){let s=this.lang;if(!V(e)||isNaN(e))return s?.invalidDate||"";if(td(t=t??"%Y-%m-%d %H:%M:%S")){let i,o=/%\[([a-zA-Z]+)\]/g;for(;i=o.exec(t);)t=t.replace(i[0],this.dateTimeFormat(i[1],e,s?.locale))}if(td(t)&&-1!==t.indexOf("%")){let i=this,[o,r,a,n,h,l,d,c]=this.toParts(e),p=s?.weekdays||this.weekdays,g=s?.shortWeekdays||this.shortWeekdays,u=s?.months||this.months,f=s?.shortMonths||this.shortMonths;tm(q({a:g?g[c]:p[c].substr(0,3),A:p[c],d:ty(a),e:ty(a,2," "),w:c,v:s?.weekFrom??"",b:f[r],B:u[r],m:ty(r+1),o:r+1,y:o.toString().substr(2,2),Y:o,H:ty(n),k:n,I:ty(n%12||12),l:n%12||12,M:ty(h),p:n<12?"AM":"PM",P:n<12?"am":"pm",S:ty(l),L:ty(d,3)},B.dateFormats),function(s,o){if(td(t))for(;-1!==t.indexOf("%"+o);)t=t.replace("%"+o,"function"==typeof s?s.call(i,e,i):s)})}else if(tg(t)){let i=(this.getTimezoneOffset(e)||0)/36e5,s=this.timezone||"Etc/GMT"+(i>=0?"+":"")+i,{prefix:o="",suffix:r=""}=t;t=o+this.dateTimeFormat(q({timeZone:s},t),e)+r}return i?tP(t):t}resolveDTLFormat(t){return tg(t,!0)?tg(t,!0)&&void 0===t.main?{main:t}:t:{main:(t=tT(t))[0],from:t[1],to:t[2]}}getDateFormat(t,e,i,s){let o=this.dateFormat("%m-%d %H:%M:%S.%L",e),r="01-01 00:00:00.000",a={millisecond:15,second:12,minute:9,hour:6,day:3},n="millisecond",h=n;for(n in tD){if(t&&t===tD.week&&+this.dateFormat("%w",e)===i&&o.substr(6)===r.substr(6)){n="week";break}if(t&&tD[n]>t){n=h;break}if(a[n]&&o.substr(a[n])!==r.substr(a[n]))break;"week"!==n&&(h=n)}return this.resolveDTLFormat(s[n]).main}},tH=class extends tW{getTimeTicks(t,e,i,s){let o=this,r=[],a={},{count:n=1,unitRange:h}=t,[l,d,c,p,g,u]=o.toParts(e),f=(e||0)%1e3,m;if(s??(s=1),V(e)){if(f=h>=tD.second?0:n*Math.floor(f/n),h>=tD.second&&(u=h>=tD.minute?0:n*Math.floor(u/n)),h>=tD.minute&&(g=h>=tD.hour?0:n*Math.floor(g/n)),h>=tD.hour&&(p=h>=tD.day?0:n*Math.floor(p/n)),h>=tD.day&&(c=h>=tD.month?1:Math.max(1,n*Math.floor(c/n))),h>=tD.month&&(d=h>=tD.year?0:n*Math.floor(d/n)),h>=tD.year&&(l-=l%n),h===tD.week){n&&(e=o.makeTime(l,d,c,p,g,u,f));let t=this.dateTimeFormat({timeZone:this.timezone,weekday:"narrow"},e,"es"),i="DLMXJVS".indexOf(t);c+=-i+s+(i4*tD.month||o.getTimezoneOffset(e)!==o.getTimezoneOffset(i));let t=e,x=1;for(;t1?t=o.makeTime(l,d,c,p+x*n):t+=h*n,x++;r.push(t),h<=tD.hour&&r.length<1e4&&r.forEach(t=>{t%18e5==0&&"000000000"===o.dateFormat("%H%M%S%L",t)&&(a[t]="day")})}return r.info=q(t,{higherRanks:a,totalRange:h*n}),r}},{isTouchDevice:tX}=B,tG={colors:["#2caffe","#544fc5","#00e272","#fe6a35","#6b8abc","#d568fb","#2ee0ca","#fa4b42","#feb56a","#91e8e1"],symbols:["circle","diamond","square","triangle","triangle-down"],lang:{weekFrom:"week from",chartTitle:"Chart title",locale:void 0,loading:"Loading...",months:void 0,seriesName:"Series {add index 1}",shortMonths:void 0,weekdays:void 0,numericSymbols:["k","M","G","T","P","E"],pieSliceName:"Slice",resetZoom:"Reset zoom",yAxisTitle:"Values",resetZoomTitle:"Reset zoom level 1:1"},global:{buttonTheme:{fill:"#f7f7f7",padding:8,r:2,stroke:"#cccccc","stroke-width":1,style:{color:"#333333",cursor:"pointer",fontSize:"0.8em",fontWeight:"normal"},states:{hover:{fill:"#e6e6e6"},select:{fill:"#e6e9ff",style:{color:"#000000",fontWeight:"bold"}},disabled:{style:{color:"#cccccc"}}}}},time:{Date:void 0,timezone:"UTC",timezoneOffset:0,useUTC:void 0},chart:{alignThresholds:!1,panning:{enabled:!1,type:"x"},styledMode:!1,borderRadius:0,colorCount:10,allowMutatingData:!0,ignoreHiddenSeries:!0,spacing:[10,10,15,10],resetZoomButton:{theme:{},position:{}},reflow:!0,type:"line",zooming:{singleTouch:!1,resetButton:{theme:{zIndex:6},position:{align:"right",x:-10,y:10}}},width:null,height:null,borderColor:"#334eff",backgroundColor:"#ffffff",plotBorderColor:"#cccccc"},title:{style:{color:"#333333",fontWeight:"bold"},text:"Chart title",margin:15,minScale:.67},subtitle:{style:{color:"#666666",fontSize:"0.8em"},text:""},caption:{margin:15,style:{color:"#666666",fontSize:"0.8em"},text:"",align:"left",verticalAlign:"bottom"},plotOptions:{},legend:{enabled:!0,align:"center",alignColumns:!0,className:"highcharts-no-tooltip",events:{},layout:"horizontal",itemMarginBottom:2,itemMarginTop:2,labelFormatter:function(){return this.name},borderColor:"#999999",borderRadius:0,navigation:{style:{fontSize:"0.8em"},activeColor:"#0022ff",inactiveColor:"#cccccc"},itemStyle:{color:"#333333",cursor:"pointer",fontSize:"0.8em",textDecoration:"none",textOverflow:"ellipsis"},itemHoverStyle:{color:"#000000"},itemHiddenStyle:{color:"#666666",textDecoration:"line-through"},shadow:!1,itemCheckboxStyle:{position:"absolute",width:"13px",height:"13px"},squareSymbol:!0,symbolPadding:5,verticalAlign:"bottom",x:0,y:0,title:{style:{color:"#333333",fontSize:"0.8em",fontWeight:"bold"}}},loading:{labelStyle:{fontWeight:"bold",position:"relative",top:"45%"},style:{position:"absolute",backgroundColor:"#ffffff",opacity:.5,textAlign:"center"}},tooltip:{enabled:!0,animation:{duration:300,easing:t=>Math.sqrt(1-Math.pow(t-1,2))},borderRadius:3,dateTimeLabelFormats:{millisecond:"%[AebHMSL]",second:"%[AebHMS]",minute:"%[AebHM]",hour:"%[AebHM]",day:"%[AebY]",week:"%v %[AebY]",month:"%[BY]",year:"%Y"},footerFormat:"",headerShape:"callout",hideDelay:500,showDelay:0,padding:8,position:{x:0,y:3},shared:!1,snap:tX?25:10,headerFormat:'{ucfirst point.key}
',pointFormat:'● {series.name}: {point.y}
',backgroundColor:"#ffffff",borderWidth:void 0,stickOnContact:!1,style:{color:"#333333",cursor:"default",fontSize:"0.8em"},useHTML:!1},credits:{enabled:!0,href:"https://www.highcharts.com?credits",position:{align:"right",x:-10,verticalAlign:"bottom",y:-5},style:{cursor:"pointer",color:"#999999",fontSize:"0.6em"},text:"Highcharts.com"}},tF=new tH(tG.time,tG.lang),tY={defaultOptions:tG,defaultTime:tF,getOptions:function(){return tG},setOptions:function(t){return Q(B,"setOptions",{options:t}),tu(!0,tG,t),t.time&&tF.update(tG.time),t.lang&&"locale"in t.lang&&tF.update({locale:t.lang.locale}),t.lang?.chartTitle&&(tG.title={...tG.title,text:t.lang.chartTitle}),tG}},{win:tj}=B,t$=(t,e,i)=>`color-mix(in srgb,${t},${e} ${100*i}%)`,tV=t=>td(t)&&!!t&&"none"!==t;class tU{static parse(t){return t?new tU(t):tU.None}constructor(t){let e,i,s,o;this.rgba=[NaN,NaN,NaN,NaN],this.input=t;const r=B.Color;if(r&&r!==tU)return new r(t);if("object"==typeof t&&void 0!==t.stops)this.stops=t.stops.map(t=>new tU(t[1]));else if("string"==typeof t)for(this.input=t=tU.names[t.toLowerCase()]||t,s=tU.parsers.length;s--&&!i;)(e=(o=tU.parsers[s]).regex.exec(t))&&(i=o.parse(e));i&&(this.rgba=i)}get(t){let e=this.input,i=this.rgba;if(this.output)return this.output;if("object"==typeof e&&void 0!==this.stops){let i=tu(e);return i.stops=[].slice.call(i.stops),this.stops.forEach((e,s)=>{i.stops[s]=[i.stops[s][0],e.get(t)]}),i}return i&&tl(i[0])?"rgb"!==t&&(t||1!==i[3])?"a"===t?`${i[3]}`:"rgba("+i.join(",")+")":"rgb("+i[0]+","+i[1]+","+i[2]+")":e}brighten(t){let e=this.rgba;if(this.stops)this.stops.forEach(function(e){e.brighten(t)});else if(tl(t)&&0!==t)if(tl(e[0]))for(let i=0;i<3;i++)e[i]+=tv(255*t),e[i]<0&&(e[i]=0),e[i]>255&&(e[i]=255);else tU.useColorMix&&tV(this.input)&&(this.output=t$(this.input,t>0?"white":"black",Math.abs(t)));return this}setOpacity(t){return this.rgba[3]=t,this}tweenTo(t,e){let i=this.rgba,s=t.rgba;if(!tl(i[0])||!tl(s[0]))return tU.useColorMix&&tV(this.input)&&tV(t.input)&&e<.99?t$(this.input,t.input,e):t.input||"none";let o=1!==s[3]||1!==i[3],r=(t,s)=>t+(i[s]-t)*(1-e),a=s.slice(0,3).map(r).map(Math.round);return o&&a.push(r(s[3],3)),(o?"rgba(":"rgb(")+a.join(",")+")"}}tU.names={white:"#ffffff",black:"#000000"},tU.parsers=[{regex:/rgba\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d?(?:\.\d+)?)\s*\)/,parse:function(t){return[tv(t[1]),tv(t[2]),tv(t[3]),parseFloat(t[4],10)]}},{regex:/rgb\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*\)/,parse:function(t){return[tv(t[1]),tv(t[2]),tv(t[3]),1]}},{regex:/^#([a-f0-9])([a-f0-9])([a-f0-9])([a-f0-9])?$/i,parse:function(t){return[tv(t[1]+t[1],16),tv(t[2]+t[2],16),tv(t[3]+t[3],16),V(t[4])?tv(t[4]+t[4],16)/255:1]}},{regex:/^#([a-f0-9]{2})([a-f0-9]{2})([a-f0-9]{2})([a-f0-9]{2})?$/i,parse:function(t){return[tv(t[1],16),tv(t[2],16),tv(t[3],16),V(t[4])?tv(t[4],16)/255:1]}}],tU.useColorMix=tj.CSS?.supports("color","color-mix(in srgb,red,blue 9%)"),tU.None=new tU("");let{parse:tZ}=tU,{win:t_}=B;class tK{constructor(t,e,i){this.pos=NaN,this.options=e,this.elem=t,this.prop=i}dSetter(){let t=this.paths,e=t?.[0],i=t?.[1],s=this.now||0,o=[];if(1!==s&&e&&i)if(e.length===i.length&&s<1)for(let t=0;t=n+this.startTime?(this.now=this.end,this.pos=1,this.update(),h[this.prop]=!0,i=!0,tm(h,function(t){!0!==t&&(i=!1)}),i&&a&&a.call(r),e=!1):(this.pos=o.easing((s-this.startTime)/n),this.now=this.start+(this.end-this.start)*this.pos,this.update(),e=!0),e}initPath(t,e,i){let s=t.startX,o=t.endX,r=i.slice(),a=t.isArea,n=a?2:1,h=e&&i.length>e.length&&i.hasStackedCliffs,l,d,c,p,g=e?.slice();if(!g||h)return[r,r];function u(t,e){for(;t.length{let i=tq(t.options.animation);r=tg(e)&&V(e.defer)?s.defer:Math.max(r,i.duration+i.defer),a=Math.min(s.duration,i.duration)}),t.renderer.forExport&&(r=0),{defer:Math.max(0,r-a),duration:Math.min(r,a)}},setAnimation:function(t,e){e.renderer.globalAnimation=tb(t,e.options.chart.animation,!0)},stop:tJ},{SVG_NS:t0,win:t1}=B,{trustedTypes:t2}=t1,t3=t2&&tp(t2.createPolicy)&&t2.createPolicy("highcharts",{createHTML:t=>t}),t5=t3?t3.createHTML(""):"";class t6{static filterUserAttributes(t){return tm(t,(e,i)=>{let s=!0;-1===t6.allowedAttributes.indexOf(i)&&(s=!1),-1!==["background","dynsrc","href","lowsrc","src"].indexOf(i)&&(s=td(e)&&t6.allowedReferences.some(t=>0===e.indexOf(t))),s||(tE(33,!1,void 0,{"Invalid attribute in config":`${i}`}),delete t[i]),td(e)&&t[i]&&(t[i]=e.replace(/{let i=e.split(":").map(t=>t.trim()),s=i.shift();return s&&i.length&&(t[s.replace(/-([a-z])/g,t=>t[1].toUpperCase())]=i.join(":")),t},{})}static setElementHTML(t,e){t.innerHTML=t6.emptyHTML,e&&new t6(e).addToDOM(t)}constructor(t){this.nodes="string"==typeof t?this.parseMarkup(t):t}addToDOM(t){return function t(e,i){let s;return tT(e).forEach(function(e){let o,r=e.tagName,a=e.textContent?B.doc.createTextNode(e.textContent):void 0,n=t6.bypassHTMLFiltering;if(r)if("#text"===r)o=a;else if(-1!==t6.allowedTags.indexOf(r)||n){let s="svg"===r?t0:i.namespaceURI||t0,h=B.doc.createElementNS(s,r),l=e.attributes||{};tm(e,function(t,e){"tagName"!==e&&"attributes"!==e&&"children"!==e&&"style"!==e&&"textContent"!==e&&(l[e]=t)}),X(h,n?l:t6.filterUserAttributes(l)),e.style&&$(h,e.style),a&&h.appendChild(a),t(e.children||[],h),o=h}else tE(33,!1,void 0,{"Invalid tagName in config":r});o&&i.appendChild(o),s=o}),s}(this.nodes,t)}parseMarkup(t){let e,i=[];t=t.trim().replace(/ style=(["'])/g," data-style=$1");try{e=new DOMParser().parseFromString(t3?t3.createHTML(t):t,"text/html")}catch{}if(!e){let i=Y("div");i.innerHTML=t,e={body:i}}let s=(t,e)=>{let i=t.nodeName.toLowerCase(),o={tagName:i};"#text"===i&&(o.textContent=t.textContent||"");let r=t.attributes;if(r){let t={};[].forEach.call(r,e=>{"data-style"===e.name?o.style=t6.parseStyle(e.value):t[e.name]=e.value}),o.attributes=t}if(t.childNodes.length){let e=[];[].forEach.call(t.childNodes,t=>{s(t,e)}),e.length&&(o.children=e)}e.push(o)};return[].forEach.call(e.body.childNodes,t=>s(t,i)),i}}t6.allowedAttributes=["alt","aria-controls","aria-describedby","aria-expanded","aria-haspopup","aria-hidden","aria-label","aria-labelledby","aria-live","aria-pressed","aria-readonly","aria-roledescription","aria-selected","class","clip-path","color","colspan","cx","cy","d","disabled","dx","dy","fill","filterUnits","flood-color","flood-opacity","height","href","id","in","in2","markerHeight","markerWidth","offset","opacity","operator","orient","padding","paddingLeft","paddingRight","patternUnits","r","radius","refX","refY","result","role","rowspan","scope","slope","src","startOffset","stdDeviation","stroke-linecap","stroke-width","stroke","style","summary","tabindex","tableValues","target","text-align","text-anchor","textAnchor","textLength","title","type","valign","width","x","x1","x2","xlink:href","y","y1","y2","zIndex"],t6.allowedReferences=["https://","http://","mailto:","/","../","./","#"],t6.allowedTags=["#text","a","abbr","b","br","button","caption","circle","clipPath","code","dd","defs","div","dl","dt","em","feComponentTransfer","feComposite","feDropShadow","feFlood","feFuncA","feFuncB","feFuncG","feFuncR","feGaussianBlur","feMerge","feMergeNode","feMorphology","feOffset","filter","h1","h2","h3","h4","h5","h6","hr","i","img","li","linearGradient","marker","ol","p","path","pattern","pre","rect","small","span","stop","strong","style","sub","sup","svg","table","tbody","td","text","textPath","th","thead","title","tr","tspan","u","ul"],t6.emptyHTML=t5,t6.bypassHTMLFiltering=!1;let{defaultOptions:t9,defaultTime:t4}=tY,{pageLang:t8}=B,t7={add:(t,e)=>t+e,divide:(t,e)=>0!==e?t/e:"",eq:(t,e)=>t==e,each:function(t){let e=arguments[arguments.length-1];return!!tc(t)&&t.map((i,s)=>ee(e.body,q(tg(i)?i:{"@this":i},{"@index":s,"@first":0===s,"@last":s===t.length-1}))).join("")},ge:(t,e)=>t>=e,gt:(t,e)=>t>e,if:t=>!!t,le:(t,e)=>t<=e,lt:(t,e)=>tt*e,ne:(t,e)=>t!=e,subtract:(t,e)=>t-e,ucfirst:tP,unless:t=>!t},et={};function ee(t="",e,i){let s=RegExp("\\{([\\p{L}\\p{M}\\d:\\.,;\\-\\/<>\\[\\]%_@+\"'’= #\\(\\)]+)\\}","gu"),o=RegExp("\\(([\\p{L}\\p{M}\\d:\\.,;\\-\\/<>\\[\\]%_@+\"'= ]+)\\)","gu"),r=[],a=/f$/,n=/\.(\d)/,h=i?.options?.lang||t9.lang,l=i?.time||t4,d=i?.numberFormatter||ei.bind(i),c=(t="")=>{let i;return"true"===t||"false"!==t&&((i=Number(t)).toString()===t?i:/^["'].+["']$/.test(t)?t.slice(1,-1):ts(t,e))},p,g,u=0,f;for(;null!==(p=s.exec(t));){let i=p,s=o.exec(p[1]);s&&(p=s,f=!0),g?.isBlock||(g={ctx:e,expression:p[1],find:p[0],isBlock:"#"===p[1].charAt(0),start:p.index,startInner:p.index+p[0].length,length:p[0].length});let a=(g.isBlock?i:p)[1].split(" ")[0].replace("#","");t7[a]&&(g.isBlock&&a===g.fn&&u++,g.fn||(g.fn=a));let n="else"===p[1];if(g.isBlock&&g.fn&&(p[1]===`/${g.fn}`||n))if(u)!n&&u--;else{let e=g.startInner,i=t.substr(e,p.index-e);void 0===g.body?(g.body=i,g.startInner=p.index+p[0].length):g.elseBody=i,g.find+=i+p[0],n||(r.push(g),g=void 0)}else g.isBlock||r.push(g);if(s&&!g?.isBlock)break}return r.forEach(s=>{let r,p,{body:g,elseBody:u,expression:f,fn:m}=s;if(m){let t=[s],o=[],a=f.length,n=0,h;for(p=0;p<=a;p++){let t=f.charAt(p);h||'"'!==t&&"'"!==t?h===t&&(h=""):h=t,h||" "!==t&&p!==a||(o.push(f.substr(n,p-n)),n=p+1)}for(p=t7[m].length;p--;)t.unshift(c(o[p+1]));r=t7[m].apply(e,t),s.isBlock&&"boolean"==typeof r&&(r=ee(r?g:u,e,i))}else{let t=/^["'].+["']$/.test(f)?[f]:f.split(":");if(r=c(t.shift()||""),t.length&&"number"==typeof r){let e=t.join(":");if(a.test(e)){let t=parseInt((e.match(n)||["","-1"])[1],10);null!==r&&(r=d(r,t,h.decimalPoint,e.indexOf(",")>-1?h.thousandsSep:""))}else r=l.dateFormat(e,r)}o.lastIndex=0,o.test(s.find)&&td(r)&&(r=`"${r}"`)}t=t.replace(s.find,tb(r,""))}),f?ee(t,e,i):t}function ei(t,e,i,s){e*=1;let o,r,[a,n]=(t=+t||0).toString().split("e").map(Number),h=this?.options?.lang||t9.lang,l=(t.toString().split(".")[1]||"").split("e")[0].length,d=e,c={};i??(i=h.decimalPoint),s??(s=h.thousandsSep),-1===e?e=Math.min(l,20):tl(e)?e&&n<0&&((r=e+n)>=0?(a=+a.toExponential(r).split("e")[0],e=r):(a=Math.floor(a),t=e<20?+(a*Math.pow(10,n)).toFixed(e):0,n=0)):e=2,n&&(e??(e=2),t=a),tl(e)&&e>=0&&(c.minimumFractionDigits=e,c.maximumFractionDigits=e),""===s&&(c.useGrouping=!1);let p=s||i,g=p?"en":this?.locale||h.locale||t8,u=JSON.stringify(c)+g;return o=(et[u]??(et[u]=new Intl.NumberFormat(g,c))).format(t),p&&(o=o.replace(/([,\.])/g,"_$1").replace(/_\,/g,s??",").replace("_.",i??".")),(e||0!=+o)&&(!(n<0)||d)||(o="0"),n&&0!=+o&&(o+="e"+(n<0?"":"+")+n),o}let es={dateFormat:function(t,e,i){return t4.dateFormat(t,e,i)},format:ee,helpers:t7,numberFormat:ei};(n=m||(m={})).rendererTypes={},n.getRendererType=function(t=o){return n.rendererTypes[t]||n.rendererTypes[o]},n.registerRendererType=function(t,e,i){n.rendererTypes[t]=e,(!o||i)&&(o=t,B.Renderer=e)};let eo=m;(x||(x={})).distribute=function t(e,i,s){let o=e,r=o.reducedLen||i,a=(t,e)=>t.target-e.target,n=[],h=e.length,l=[],d=n.push,c,p=!0,g,u,f=0;for(c=h;c--;)f+=e[c].size;if(f>r){if(tC(e,(t,e)=>(e.rank||0)-(t.rank||0)),e[0].rank===e[e.length-1].rank){let t=[[0,h-1]];for(;t.length&&f>r;){let i=t.shift();if(!i)break;g=e[c=Math.floor((i[0]+i[1])/2)],tk(l,c)&&(f-=g.size),i[0]r&&c>=0;)g=e[c],tk(l,c)&&(f-=g.size),c--;l.sort((t,e)=>e-t).forEach(t=>d.apply(n,e.splice(t,1)))}for(tC(e,a),e=e.map(t=>({size:t.size,targets:[t.target],align:tb(t.align,.5)}));p;){for(c=e.length;c--;)g=e[c],u=(Math.min.apply(0,g.targets)+Math.max.apply(0,g.targets))/2,g.pos=G(u-g.size*g.align,0,i-g.size);for(c=e.length,p=!1;c--;)c>0&&e[c-1].pos+e[c-1].size>e[c].pos&&(e[c-1].size+=e[c].size,e[c-1].targets=e[c-1].targets.concat(e[c].targets),e[c-1].align=.5,e[c-1].pos+e[c-1].size>i&&(e[c-1].pos=i-e[c-1].size),e.splice(c,1),p=!0)}return d.apply(o,n),c=0,e.some(e=>{let r=0;return(e.targets||[]).some(()=>(o[c].pos=e.pos+r,void 0!==s&&Math.abs(o[c].pos-o[c].target)>s)?(o.slice(0,c+1).forEach(t=>delete t.pos),o.reducedLen=(o.reducedLen||i)-.1*i,o.reducedLen>.1*i&&t(o,i,s),!0):(r+=o[c].size,c++,!1))}),tC(o,a),o};let er=x,{animate:ea,animObject:en,stop:eh}=tQ,{deg2rad:el,doc:ed,svg:ec,SVG_NS:ep,win:eg,isFirefox:eu}=B;class ef{_defaultGetter(t){let e=tb(this[t+"Value"],this[t],this.element?this.element.getAttribute(t):null,0);return/^-?[\d\.]+$/.test(e)&&(e=parseFloat(e)),e}_defaultSetter(t,e,i){i.setAttribute(e,t)}add(t){let e,i=this.renderer,s=this.element;return t&&(this.parentGroup=t),void 0!==this.textStr&&"text"===this.element.nodeName&&i.buildText(this),this.added=!0,(!t||t.handleZ||this.zIndex)&&(e=this.zIndexSetter()),e||(t?t.element:i.box).appendChild(s),this.onAdd&&this.onAdd(),this}addClass(t,e){let i=e?"":this.attr("class")||"";return(t=(t||"").split(/ /g).reduce(function(t,e){return -1===i.indexOf(e)&&t.push(e),t},i?[i]:[]).join(" "))!==i&&this.attr("class",t),this}afterSetters(){this.doTransform&&(this.updateTransform(),this.doTransform=!1)}align(t,e,i,s=!0){let o=this.renderer,r=o.alignedObjects,a=!!t;t?(this.alignOptions=t,this.alignByTranslate=e,this.alignTo=i):(t=this.alignOptions||{},e=this.alignByTranslate,i=this.alignTo);let n=!i||td(i)?i||"renderer":void 0;n&&(a&&tk(r,this),i=void 0);let h=tb(i,o[n],o),l=(h.x||0)+(t.x||0)+((h.width||0)-(t.width||0))*tt(t.align),d=(h.y||0)+(t.y||0)+((h.height||0)-(t.height||0))*tt(t.verticalAlign),c={};return t.align&&(c["text-align"]=t.align),c[e?"translateX":"x"]=Math.round(l),c[e?"translateY":"y"]=Math.round(d),s&&(this[this.placed?"animate":"attr"](c),this.placed=!0),this.alignAttr=c,this}alignSetter(t){let e={left:"start",center:"middle",right:"end"};e[t]&&(this.alignValue=t,this.element.setAttribute("text-anchor",e[t]))}animate(t,e,i){let s=en(tb(e,this.renderer.globalAnimation,!0)),o=s.defer;return ed.hidden&&(s.duration=0),0!==s.duration?(i&&(s.complete=i),tA(()=>{this.element&&ea(this,t,s)},o)):(this.attr(t,void 0,i||s.complete),tm(t,function(t,e){s.step&&s.step.call(this,t,{prop:e,pos:1,elem:this})},this)),this}applyTextOutline(t){let e=this.element;-1!==t.indexOf("contrast")&&(t=t.replace(/contrast/g,this.renderer.getContrast(e.style.fill)));let i=t.indexOf(" "),s=t.substring(i+1),o=t.substring(0,i);if(o&&"none"!==o&&B.svg){this.fakeTS=!0,o=o.replace(/(^[\d\.]+)(.*?)$/g,function(t,e,i){return 2*Number(e)+i}),this.removeTextOutline();let t=ed.createElementNS(ep,"tspan");X(t,{class:"highcharts-text-outline",fill:s,stroke:s,"stroke-width":o,"stroke-linejoin":"round"});let i=e.querySelector("textPath")||e;[].forEach.call(i.childNodes,e=>{let i=e.cloneNode(!0);i.removeAttribute&&["fill","stroke","stroke-width","stroke"].forEach(t=>i.removeAttribute(t)),t.appendChild(i)});let r=0;[].forEach.call(i.querySelectorAll("text tspan"),t=>{r+=Number(t.getAttribute("dy"))});let a=ed.createElementNS(ep,"tspan");a.textContent="​",X(a,{x:Number(e.getAttribute("x")),dy:-r}),t.appendChild(a),i.insertBefore(t,i.firstChild)}}attr(t,e,i,s){let{element:o}=this,r=ef.symbolCustomAttribs,a,n,h=this,l;return"string"==typeof t&&void 0!==e&&(a=t,(t={})[a]=e),"string"==typeof t?h=(this[t+"Getter"]||this._defaultGetter).call(this,t,o):(tm(t,function(e,i){l=!1,s||eh(this,i),this.symbolName&&-1!==r.indexOf(i)&&(n||(this.symbolAttr(t),n=!0),l=!0),this.rotation&&("x"===i||"y"===i)&&(this.doTransform=!0),l||(this[i+"Setter"]||this._defaultSetter).call(this,e,i,o)},this),this.afterSetters()),i&&i.call(this),h}clip(t){if(t&&!t.clipPath){let e=tB()+"-",i=this.renderer.createElement("clipPath").attr({id:e}).add(this.renderer.defs);q(t,{clipPath:i,id:e,count:0}),t.add(i)}return this.attr("clip-path",t?`url(${this.renderer.url}#${t.id})`:"none")}crisp(t,e){e=Math.round(e||t.strokeWidth||0);let i=t.x||this.x||0,s=t.y||this.y||0,o=(t.width||this.width||0)+i,r=(t.height||this.height||0)+s,a=j(i,e),n=j(s,e);return q(t,{x:a,y:n,width:j(o,e)-a,height:j(r,e)-n}),V(t.strokeWidth)&&(t.strokeWidth=e),t}complexColor(t,e,i){let s=this.renderer,o,r,a,n,h,l,d,c,p,g,u=[],f;Q(this.renderer,"complexColor",{args:arguments},function(){if(t.radialGradient?r="radialGradient":t.linearGradient&&(r="linearGradient"),r){if(a=t[r],h=s.gradients,l=t.stops,p=i.radialReference,tc(a)&&(t[r]=a={x1:a[0],y1:a[1],x2:a[2],y2:a[3],gradientUnits:"userSpaceOnUse"}),"radialGradient"===r&&p&&!V(a.gradientUnits)&&(n=a,a=tu(a,s.getRadialAttr(p,n),{gradientUnits:"userSpaceOnUse"})),tm(a,function(t,e){"id"!==e&&u.push(e,t)}),tm(l,function(t){u.push(t)}),h[u=u.join(",")])g=h[u].attr("id");else{a.id=g=tB();let t=h[u]=s.createElement(r).attr(a).add(s.defs);t.radAttr=n,t.stops=[],l.forEach(function(e){0===e[1].indexOf("rgba")?(d=(o=tU.parse(e[1])).get("rgb"),c=o.get("a")):(d=e[1],c=1);let i=s.createElement("stop").attr({offset:e[0],"stop-color":d,"stop-opacity":c}).add(t);t.stops.push(i)})}f="url("+s.url+"#"+g+")",i.setAttribute(e,f),i.gradient=u,t.toString=function(){return f}}})}css(t){let e=this.styles,i={},s=this.element,o,r=!e;if(e&&tm(t,function(t,s){e&&e[s]!==t&&(i[s]=t,r=!0)}),r){e&&(t=q(e,i)),null===t.width||"auto"===t.width?delete this.textWidth:"text"===s.nodeName.toLowerCase()&&t.width&&(o=this.textWidth=tv(t.width)),q(this.styles,t),o&&!ec&&this.renderer.forExport&&delete t.width;let r=eu&&t.fontSize||null;r&&(tl(r)||/^\d+$/.test(r))&&(t.fontSize+="px");let a=tu(t);s.namespaceURI===this.SVG_NS&&(["textOutline","textOverflow","whiteSpace","width"].forEach(t=>a&&delete a[t]),a.color&&(a.fill=a.color,delete a.color)),$(s,a)}return this.added&&("text"===this.element.nodeName&&this.renderer.buildText(this),t.textOutline&&this.applyTextOutline(t.textOutline)),this}dashstyleSetter(t){let e,i=this["stroke-width"];if("inherit"===i&&(i=1),t){let s=(t=t.toLowerCase()).replace("shortdashdotdot","3,1,1,1,1,1,").replace("shortdashdot","3,1,1,1").replace("shortdot","1,1,").replace("shortdash","3,1,").replace("longdash","8,3,").replace(/dot/g,"1,3,").replace("dash","4,3,").replace(/,$/,"").split(",");for(e=s.length;e--;)s[e]=""+tv(s[e])*tb(i,NaN);t=s.join(",").replace(/NaN/g,"none"),this.element.setAttribute("stroke-dasharray",t)}}destroy(){let t=this,{element:e={},renderer:i,stops:s}=t,o=e.ownerSVGElement,r="SPAN"===e.nodeName&&t.parentGroup||void 0,a;if(e.onclick=e.onmouseout=e.onmouseover=e.onmousemove=e.point=null,eh(t),t.clipPath&&o){let e=t.clipPath;[].forEach.call(o.querySelectorAll("[clip-path],[CLIP-PATH]"),function(t){t.getAttribute("clip-path").indexOf(e.element.id)>-1&&t.removeAttribute("clip-path")}),t.clipPath=e.destroy()}if(s){for(let t of s)t.destroy();s.length=0}for(t.safeRemoveChild(e);r?.div&&0===r.div.childNodes.length;)a=r.parentGroup,t.safeRemoveChild(r.div),delete r.div,r=a;t.alignOptions&&K(i.alignedObjects,t),tm(t,(e,i)=>{(t[i]?.parentGroup===t||-1!==["connector","foreignObject"].indexOf(i))&&t[i]?.destroy?.(),delete t[i]})}dSetter(t,e,i){tc(t)&&("string"==typeof t[0]&&(t=this.renderer.pathToSegments(t)),this.pathArray=t,t=t.reduce((t,e,i)=>e?.join?(i?t+" ":"")+e.join(" "):(e||"").toString(),"")),/(NaN| {2}|^$)/.test(t)&&(t="M 0 0"),this[e]!==t&&(i.setAttribute(e,t),this[e]=t)}fillSetter(t,e,i){"string"==typeof t?i.setAttribute(e,t):t&&this.complexColor(t,e,i)}hrefSetter(t,e,i){i.setAttributeNS("http://www.w3.org/1999/xlink",e,t)}getBBox(t,e){let i,s,o,{element:r,renderer:a,styles:n,textStr:h}=this,{cache:l,cacheKeys:d}=a,c=r.namespaceURI===this.SVG_NS,p=tb(e,this.rotation,0),g=a.styledMode?r&&ef.prototype.getStyle.call(r,"font-size"):n.fontSize,u=this.getBBoxCacheKey([a.rootFontSize,this.textWidth,this.alignValue,n.fontWeight,n.lineClamp,n.textOverflow,g,p]);if(u&&!t&&(i=l[u]),!i||i.polygon){if(c||a.forExport){try{o=this.fakeTS&&function(t){let e=r.querySelector(".highcharts-text-outline");e&&$(e,{display:t})},tp(o)&&o("none"),i=r.getBBox?q({},r.getBBox()):{width:r.offsetWidth,height:r.offsetHeight,x:0,y:0},tp(o)&&o("")}catch{}(!i||i.width<0)&&(i={x:0,y:0,width:0,height:0})}else i=this.htmlGetBBox();s=i.height,c&&(i.height=s=({"11px,17":14,"13px,20":16})[`${g||""},${Math.round(s)}`]||s),p&&(i=this.getRotatedBox(i,p));let t={bBox:i};Q(this,"afterGetBBox",t),i=t.bBox}if(u&&(""===h||i.height>0)){for(;d.length>250;)delete l[d.shift()];l[u]||d.push(u),l[u]=i}return i}getBBoxCacheKey(t){if(V(this.textStr)){let e=""+this.textStr;return -1===e.indexOf("<")&&(e=e.replace(/\d/g,"0")),[e,...t].join(",")}}getRotatedBox(t,e){let{x:i,y:s,width:o,height:r}=t,{alignValue:a,translateY:n,rotationOriginX:h=0,rotationOriginY:l=0}=this,d=tt(a),c=Number(this.element.getAttribute("y")||0)-(n?0:s),p=e*el,g=(e-90)*el,u=Math.cos(p),f=Math.sin(p),m=o*u,x=o*f,y=Math.cos(g),b=Math.sin(g),[[v,k],[w,M]]=[h,l].map(t=>[t-t*u,t*f]),S=i+d*(o-m)+v+M+c*y,T=S+m,C=T-r*y,A=C-m,P=s+c-d*x-k+w+c*b,L=P+x,O=L-r*b,E=O-x,I=Math.min(S,T,C,A),D=Math.min(P,L,O,E),B=Math.max(S,T,C,A)-I,N=Math.max(P,L,O,E)-D;return{x:I,y:D,width:B,height:N,polygon:[[S,P],[T,L],[C,O],[A,E]]}}getStyle(t){return eg.getComputedStyle(this.element||this,"").getPropertyValue(t)}hasClass(t){return -1!==(""+this.attr("class")).split(" ").indexOf(t)}hide(){return this.attr({visibility:"hidden"})}htmlGetBBox(){return{height:0,width:0,x:0,y:0}}constructor(t,e){this.onEvents={},this.opacity=1,this.SVG_NS=ep,this.element="span"===e||"body"===e?Y(e):ed.createElementNS(this.SVG_NS,e),this.renderer=t,this.styles={},Q(this,"afterInit")}on(t,e){let{onEvents:i}=this;return i[t]&&i[t](),i[t]=R(this.element,t,e),this}opacitySetter(t,e,i){let s=Number(Number(t).toFixed(3));this.opacity=s,i.setAttribute(e,s)}reAlign(){this.alignOptions?.width&&"left"!==this.alignOptions.align&&(this.alignOptions.width=this.getBBox().width,this.placed=!1,this.align())}removeClass(t){return this.attr("class",(""+this.attr("class")).replace(td(t)?RegExp(`(^| )${t}( |$)`):t," ").replace(/ +/g," ").trim())}removeTextOutline(){let t=this.element.querySelector("tspan.highcharts-text-outline");t&&this.safeRemoveChild(t)}safeRemoveChild(t){let e=t.parentNode;e&&e.removeChild(t)}setRadialReference(t){let e=this.element.gradient&&this.renderer.gradients[this.element.gradient]||void 0;return this.element.radialReference=t,e?.radAttr&&e.animate(this.renderer.getRadialAttr(t,e.radAttr)),this}shadow(t){let{renderer:e}=this,i=tu(this.parentGroup?.rotation===90?{offsetX:-1,offsetY:-1}:{},tg(t)?t:{}),s=e.shadowDefinition(i);return this.attr({filter:t?`url(${e.url}#${s})`:"none"})}show(t=!0){return this.attr({visibility:t?"inherit":"visible"})}"stroke-widthSetter"(t,e,i){this[e]=t,i.setAttribute(e,t)}strokeWidth(){if(!this.renderer.styledMode)return this["stroke-width"]||0;let t=this.getStyle("stroke-width"),e=0,i;return/px$/.test(t)?e=tv(t):""!==t&&(X(i=ed.createElementNS(ep,"rect"),{width:t,"stroke-width":0}),this.element.parentNode.appendChild(i),e=i.getBBox().width,i.parentNode.removeChild(i)),e}symbolAttr(t){let e=this;ef.symbolCustomAttribs.forEach(function(i){e[i]=tb(t[i],e[i])}),e.attr({d:e.renderer.symbols[e.symbolName](e.x,e.y,e.width,e.height,e)})}textSetter(t){t!==this.textStr&&(delete this.textPxLength,this.textStr=t,this.added&&this.renderer.buildText(this),this.reAlign())}titleSetter(t){let e=this.element,i=e.getElementsByTagName("title")[0]||ed.createElementNS(this.SVG_NS,"title");e.insertBefore?e.insertBefore(i,e.firstChild):e.appendChild(i),i.textContent=tM(tb(t,""),[/<[^>]*>/g,""]).replace(/</g,"<").replace(/>/g,">")}toFront(){let t=this.element;return t.parentNode.appendChild(t),this}translate(t,e){return this.attr({translateX:t,translateY:e})}updateTransform(t="transform"){let{element:e,foreignObject:i,matrix:s,padding:o,rotation:r=0,rotationOriginX:a,rotationOriginY:n,scaleX:h,scaleY:l,text:d,translateX:c=0,translateY:p=0}=this,g=[`translate(${c},${p})`];V(s)&&g.push("matrix("+s.join(",")+")"),r&&(g.push("rotate("+r+" "+(a??e.getAttribute("x")??this.x??0)+" "+(n??e.getAttribute("y")??this.y??0)+")"),d?.element.tagName!=="SPAN"||d?.foreignObject||d.attr({rotation:r,rotationOriginX:(a||0)-o,rotationOriginY:(n||0)-o})),(V(h)||V(l))&&g.push(`scale(${h??1} ${l??1})`),g.length&&!(d||this).textPath&&(i?.element||e).setAttribute(t,g.join(" "))}visibilitySetter(t,e,i){"inherit"===t?i.removeAttribute(e):this[e]!==t&&i.setAttribute(e,t),this[e]=t}xGetter(t){return"circle"===this.element.nodeName&&("x"===t?t="cx":"y"===t&&(t="cy")),this._defaultGetter(t)}zIndexSetter(t,e){let i=this.renderer,s=this.parentGroup,o=(s||i).element||i.box,r=this.element,a=o===i.box,n,h,l,d=!1,c,p=this.added,g;if(V(t)?(r.setAttribute("data-z-index",t),t*=1,this[e]===t&&(p=!1)):V(this[e])&&r.removeAttribute("data-z-index"),this[e]=t,p){for((t=this.zIndex)&&s&&(s.handleZ=!0),g=(n=o.childNodes).length-1;g>=0&&!d;g--)c=!V(l=(h=n[g]).getAttribute("data-z-index")),h!==r&&(t<0&&c&&!a&&!g?(o.insertBefore(r,n[g]),d=!0):(tv(l)<=t||c&&(!V(t)||t>=0))&&(o.insertBefore(r,n[g+1]),d=!0));d||(o.insertBefore(r,n[3*!!a]),d=!0)}return d}}ef.symbolCustomAttribs=["anchorX","anchorY","clockwise","end","height","innerR","r","start","width","x","y"],ef.prototype.strokeSetter=ef.prototype.fillSetter,ef.prototype.yGetter=ef.prototype.xGetter,ef.prototype.matrixSetter=ef.prototype.rotationOriginXSetter=ef.prototype.rotationOriginYSetter=ef.prototype.rotationSetter=ef.prototype.scaleXSetter=ef.prototype.scaleYSetter=ef.prototype.translateXSetter=ef.prototype.translateYSetter=ef.prototype.verticalAlignSetter=function(t,e){this[e]=t,this.doTransform=!0};let em=ef;class ex extends em{constructor(t,e,i,s,o,r,a,n,h,l){let d;super(t,"g"),this.paddingLeftSetter=this.paddingSetter,this.paddingRightSetter=this.paddingSetter,this.doUpdate=!1,this.textStr=e,this.x=i,this.y=s,this.anchorX=r,this.anchorY=a,this.baseline=h,this.className=l,this.addClass("button"===l?"highcharts-no-tooltip":"highcharts-label"),l&&this.addClass("highcharts-"+l),this.text=t.text(void 0,0,0,n).attr({zIndex:1}),"string"==typeof o&&((d=/^url\((.*?)\)$/.test(o))||this.renderer.symbols[o])&&(this.symbolKey=o),this.bBox=ex.emptyBBox,this.padding=3,this.baselineOffset=0,this.needsBox=t.styledMode||d,this.deferredAttr={},this.alignFactor=0}alignSetter(t){let e=tt(t);this.textAlign=t,e!==this.alignFactor&&(this.alignFactor=e,this.bBox&&tl(this.xSetting)&&this.attr({x:this.xSetting}),this.updateTextPadding())}anchorXSetter(t,e){this.anchorX=t,this.boxAttr(e,Math.round(t)-this.getCrispAdjust()-this.xSetting)}anchorYSetter(t,e){this.anchorY=t,this.boxAttr(e,t-this.ySetting)}boxAttr(t,e){this.box?this.box.attr(t,e):this.deferredAttr[t]=e}css(t){if(t){let e={};t=tu(t),ex.textProps.forEach(i=>{void 0!==t[i]&&(e[i]=t[i],delete t[i])}),this.text.css(e),"fontSize"in e||"fontWeight"in e||"width"in e?this.updateTextPadding():"textOverflow"in e&&this.updateBoxSize()}return em.prototype.css.call(this,t)}destroy(){tS(this.element,"mouseenter"),tS(this.element,"mouseleave"),this.text&&this.text.destroy(),this.box&&(this.box=this.box.destroy()),em.prototype.destroy.call(this)}fillSetter(t,e){t&&(this.needsBox=!0),this.fill=t,this.boxAttr(e,t)}getBBox(t,e){(this.textStr&&0===this.bBox.width&&0===this.bBox.height||this.rotation)&&this.updateBoxSize();let{padding:i,height:s=0,translateX:o=0,translateY:r=0,width:a=0}=this,n=tb(this.paddingLeft,i),h=e??(this.rotation||0),l={width:a,height:s,x:o+this.bBox.x-n,y:r+this.bBox.y-i+this.baselineOffset};return h&&(l=this.getRotatedBox(l,h)),l}getCrispAdjust(){return(this.renderer.styledMode&&this.box?this.box.strokeWidth():this["stroke-width"]?parseInt(this["stroke-width"],10):0)%2/2}heightSetter(t){this.heightSetting=t,this.doUpdate=!0}afterSetters(){super.afterSetters(),this.doUpdate&&(this.updateBoxSize(),this.doUpdate=!1)}onAdd(){this.text.add(this),this.attr({text:tb(this.textStr,""),x:this.x||0,y:this.y||0}),this.box&&V(this.anchorX)&&this.attr({anchorX:this.anchorX,anchorY:this.anchorY})}paddingSetter(t,e){tl(t)?t!==this[e]&&(this[e]=t,this.updateTextPadding()):this[e]=void 0}rSetter(t,e){this.boxAttr(e,t)}strokeSetter(t,e){this.stroke=t,this.boxAttr(e,t)}"stroke-widthSetter"(t,e){t&&(this.needsBox=!0),this["stroke-width"]=t,this.boxAttr(e,t)}"text-alignSetter"(t){this.textAlign=this["text-align"]=t,this.updateTextPadding()}textSetter(t){void 0!==t&&this.text.attr({text:t}),this.updateTextPadding(),this.reAlign()}updateBoxSize(){let t,e=this.text,i={},s=this.padding,o=this.bBox=(!tl(this.widthSetting)||!tl(this.heightSetting)||this.textAlign)&&V(e.textStr)?e.getBBox(void 0,0):ex.emptyBBox;this.width=this.getPaddedWidth(),this.height=(this.heightSetting||o.height||0)+2*s;let r=this.renderer.fontMetrics(e);if(this.baselineOffset=s+Math.min((this.text.firstLineMetrics||r).b,o.height||1/0),this.heightSetting&&(this.baselineOffset+=(this.heightSetting-r.h)/2),this.needsBox&&!e.textPath){if(!this.box){let t=this.box=this.symbolKey?this.renderer.symbol(this.symbolKey):this.renderer.rect();t.addClass(("button"===this.className?"":"highcharts-label-box")+(this.className?" highcharts-"+this.className+"-box":"")),t.add(this)}i.x=t=this.getCrispAdjust(),i.y=(this.baseline?-this.baselineOffset:0)+t,i.width=Math.round(this.width),i.height=Math.round(this.height),this.box.attr(q(i,this.deferredAttr)),this.deferredAttr={}}}updateTextPadding(){let t=this.text,e=t.styles.textAlign||this.textAlign;if(!t.textPath){this.updateBoxSize();let i=this.baseline?0:this.baselineOffset,s=(this.paddingLeft??this.padding)+tt(e)*(this.widthSetting??this.bBox.width);(s!==t.x||i!==t.y)&&(t.attr({align:e,x:s}),void 0!==i&&t.attr("y",i)),t.x=s,t.y=i}}widthSetter(t){this.widthSetting=tl(t)?t:void 0,this.doUpdate=!0}getPaddedWidth(){let t=this.padding,e=tb(this.paddingLeft,t),i=tb(this.paddingRight,t);return(this.widthSetting||this.bBox.width||0)+e+i}xSetter(t){this.x=t,this.alignFactor&&(t-=this.alignFactor*this.getPaddedWidth(),this["forceAnimate:x"]=!0),this.anchorX&&(this["forceAnimate:anchorX"]=!0),this.xSetting=Math.round(t),this.attr("translateX",this.xSetting)}ySetter(t){this.anchorY&&(this["forceAnimate:anchorY"]=!0),this.ySetting=this.y=Math.round(t),this.attr("translateY",this.ySetting)}}function ey(t,e,i,s,o){let r=[];if(o){let a=o.start||0,n=o.end||0,h=tb(o.r,i),l=tb(o.r,s||i),d=1e-4>Math.abs(n-a-2*Math.PI);d&&(a=Math.PI/2,n=2.5*Math.PI-1e-4);let c=o.innerR,p=tb(o.open,d),g=d?0:Math.cos(a),u=d?1:Math.sin(a),f=d?0:Math.cos(n),m=d?1:Math.sin(n),x=tb(o.longArc,n-a-Math.PI<1e-4?0:1),y=["A",h,l,0,x,tb(o.clockwise,1),t+(d?.001:h*f),e+l*m];y.params={start:a,end:n,cx:t,cy:e},r.push(["M",t+h*g,e+l*u],y),V(c)&&((y=["A",c,c,0,x,V(o.clockwise)?1-o.clockwise:0,t+(d?-.001:c*g),e+c*u]).params={start:n,end:a,cx:t,cy:e},r.push(p?["M",t+c*f,e+c*m]:["L",t+c*f,e+c*m],y)),p||r.push(["Z"])}return r}function eb(t,e,i,s,o){return o?.r?ev(t,e,i,s,o):[["M",t,e],["L",t+i,e],["L",t+i,e+s],["L",t,e+s],["Z"]]}function ev(t,e,i,s,o){let r=o?.r||0;return[["M",t+r,e],["L",t+i-r,e],["A",r,r,0,0,1,t+i,e+r],["L",t+i,e+s-r],["A",r,r,0,0,1,t+i-r,e+s],["L",t+r,e+s],["A",r,r,0,0,1,t,e+s-r],["L",t,e+r],["A",r,r,0,0,1,t+r,e],["Z"]]}ex.emptyBBox={width:0,height:0,x:0,y:0},ex.textProps=["color","direction","fontFamily","fontSize","fontStyle","fontWeight","lineClamp","lineHeight","textAlign","textDecoration","textOutline","textOverflow","whiteSpace","width"];let ek={arc:ey,callout:function(t,e,i,s,o){let r=Math.min(o?.r||0,i,s),a=r+6,n=o?.anchorX,h=o?.anchorY||0,l=ev(t,e,i,s,{r});if(!tl(n)||n0&&h0)return l;if(t+n>i-a)if(h>e+a&&he+a&&h0){let i=hs&&na&&l.splice(1,1,["L",n-6,e],["L",n,e-6],["L",n+6,e],["L",i-r,e]);return l},circle:function(t,e,i,s){return ey(t+i/2,e+s/2,i/2,s/2,{start:.5*Math.PI,end:2.5*Math.PI,open:!1})},diamond:function(t,e,i,s){return[["M",t+i/2,e],["L",t+i,e+s/2],["L",t+i/2,e+s],["L",t,e+s/2],["Z"]]},rect:eb,roundedRect:ev,square:eb,triangle:function(t,e,i,s){return[["M",t+i/2,e],["L",t+i,e+s],["L",t,e+s],["Z"]]},"triangle-down":function(t,e,i,s){return[["M",t,e],["L",t+i,e],["L",t+i/2,e+s],["Z"]]}},{doc:ew,SVG_NS:eM,win:eS}=B,eT=(t,e)=>t.substring(0,e)+"…",eC=class{constructor(t){const e=t.styles;this.renderer=t.renderer,this.svgElement=t,this.width=t.textWidth,this.textLineHeight=e?.lineHeight,this.textOutline=e?.textOutline,this.ellipsis=e?.textOverflow==="ellipsis",this.lineClamp=e?.lineClamp,this.noWrap=e?.whiteSpace==="nowrap"}buildSVG(){let t=this.svgElement,e=t.element,i=t.renderer,s=tb(t.textStr,"").toString(),o=-1!==s.indexOf("<"),r=e.childNodes,a=!t.added&&i.box,n=[s,this.ellipsis,this.noWrap,this.textLineHeight,this.textOutline,t.getStyle("font-size"),t.styles.lineClamp,this.width].join(",");if(n!==t.textCache){t.textCache=n,delete t.actualWidth;for(let t=r.length;t--;)e.removeChild(r[t]);if(o||this.ellipsis||this.width||t.textPath||-1!==s.indexOf(" ")&&(!this.noWrap||//g.test(s))){if(""!==s){a&&a.appendChild(e);let i=new t6(s);this.modifyTree(i.nodes),i.addToDOM(e),this.modifyDOM(),this.ellipsis&&-1!==(e.textContent||"").indexOf("…")&&t.attr("title",this.unescapeEntities(t.textStr||"",["<",">"])),a&&a.removeChild(e)}}else e.appendChild(ew.createTextNode(this.unescapeEntities(s)));td(this.textOutline)&&t.applyTextOutline&&t.applyTextOutline(this.textOutline)}}modifyDOM(){let t,e=this.svgElement,i=X(e.element,"x");for(e.firstLineMetrics=void 0;t=e.element.firstChild;)if(/^[\s\u200B]*$/.test(t.textContent||" "))e.element.removeChild(t);else break;[].forEach.call(e.element.querySelectorAll("tspan.highcharts-br"),(t,s)=>{t.nextSibling&&t.previousSibling&&(0===s&&1===t.previousSibling.nodeType&&(e.firstLineMetrics=e.renderer.fontMetrics(t.previousSibling)),X(t,{dy:this.getLineHeight(t.nextSibling),x:i}))});let s=this.width||0;if(!s)return;let o=(t,o)=>{let r=t.textContent||"",a=r.replace(/([^\^])-/g,"$1- ").split(" "),n=!this.noWrap&&(a.length>1||e.element.childNodes.length>1),h=this.getLineHeight(o),l=Math.max(0,s-.8*h),d=0,c=e.actualWidth;if(n){let r=[],n=[];for(;o.firstChild&&o.firstChild!==t;)n.push(o.firstChild),o.removeChild(o.firstChild);for(;a.length;)if(a.length&&!this.noWrap&&d>0&&(r.push(t.textContent||""),t.textContent=a.join(" ").replace(/- /g,"-")),this.truncate(t,void 0,a,0===d&&c||0,s,l,(t,e)=>a.slice(0,e).join(" ").replace(/- /g,"-")),c=e.actualWidth,d++,this.lineClamp&&d>=this.lineClamp){a.length&&(this.truncate(t,t.textContent||"",void 0,0,s,l,eT),t.textContent=t.textContent?.replace("…","")+"…");break}n.forEach(e=>{o.insertBefore(e,t)}),r.forEach(e=>{o.insertBefore(ew.createTextNode(e),t);let s=ew.createElementNS(eM,"tspan");s.textContent="​",X(s,{dy:h,x:i}),o.insertBefore(s,t)})}else this.ellipsis&&r&&this.truncate(t,r,void 0,0,s,l,eT)},r=t=>{[].slice.call(t.childNodes).forEach(i=>{i.nodeType===eS.Node.TEXT_NODE?o(i,t):(-1!==i.className.baseVal.indexOf("highcharts-br")&&(e.actualWidth=0),r(i))})};r(e.element)}getLineHeight(t){let e=t.nodeType===eS.Node.TEXT_NODE?t.parentElement:t;return this.textLineHeight?parseInt(this.textLineHeight.toString(),10):this.renderer.fontMetrics(e||this.svgElement.element).h}modifyTree(t){let e=(i,s)=>{let{attributes:o={},children:r,style:a={},tagName:n}=i,h=this.renderer.styledMode;if("b"===n||"strong"===n?h?o.class="highcharts-strong":a.fontWeight="bold":("i"===n||"em"===n)&&(h?o.class="highcharts-emphasized":a.fontStyle="italic"),a?.color&&(a.fill=a.color),"br"===n){o.class="highcharts-br",i.textContent="​";let e=t[s+1];e?.textContent&&(e.textContent=e.textContent.replace(/^ +/gm,""))}else"a"===n&&r&&r.some(t=>"#text"===t.tagName)&&(i.children=[{children:r,tagName:"tspan"}]);"#text"!==n&&"a"!==n&&(i.tagName="tspan"),q(i,{attributes:o,style:a}),r&&r.filter(t=>"#text"!==t.tagName).forEach(e)};t.forEach(e),Q(this.svgElement,"afterModifyTree",{nodes:t})}truncate(t,e,i,s,o,r,a){let n,h,l=this.svgElement,{rotation:d}=l,c=[],p=i&&!s?1:0,g=(e||i||"").length,u=g;i||(o=r);let f=function(e,o){let r=o||e,a=t.parentNode;if(a&&void 0===c[r]&&a.getSubStringLength)try{c[r]=s+a.getSubStringLength(0,i?r+1:r)}catch{}return c[r]};if(l.rotation=0,s+(h=f(t.textContent.length))>o){for(;p<=g;)u=Math.ceil((p+g)/2),i&&(n=a(i,u)),h=f(u,n&&n.length-1),p===g?p=g+1:h>o?g=u-1:p=u;0===g?t.textContent="":e&&g===e.length-1||(t.textContent=n||a(e||i,u)),this.ellipsis&&h>o&&this.truncate(t,t.textContent||"",void 0,0,o,r,eT)}i&&i.splice(0,u),l.actualWidth=h,l.rotation=d}unescapeEntities(t,e){return tm(this.renderer.escapes,function(i,s){e&&-1!==e.indexOf(i)||(t=t.toString().replace(RegExp(i,"g"),s))}),t}},{defaultOptions:eA}=tY,{charts:eP,deg2rad:eL,doc:eO,isFirefox:eE,isMS:eI,isWebKit:eD,noop:eB,SVG_NS:eN,symbolSizes:ez,win:eR}=B;class eW{constructor(t,e,i,s,o,r,a){let n,h;this.x=0,this.y=0;const l=this.createElement("svg").attr({version:"1.1",class:"highcharts-root"}),d=l.element;a||l.css(this.getStyle(s||{})),t.appendChild(d),X(t,"dir","ltr"),-1===t.innerHTML.indexOf("xmlns")&&X(d,"xmlns",this.SVG_NS),this.box=d,this.boxWrapper=l,this.alignedObjects=[],this.url=this.getReferenceURL(),this.createElement("desc").add().element.appendChild(eO.createTextNode("Created with Highcharts 12.6.0")),this.defs=this.createElement("defs").add(),this.allowHTML=r,this.forExport=o,this.styledMode=a,this.gradients={},this.cache={},this.cacheKeys=[],this.asyncCounter=0,this.rootFontSize=l.getStyle("font-size"),this.setSize(e,i,!1),eE&&t.getBoundingClientRect&&((n=function(){$(t,{left:0,top:0}),h=t.getBoundingClientRect(),$(t,{left:Math.ceil(h.left)-h.left+"px",top:Math.ceil(h.top)-h.top+"px"})})(),this.unSubPixelFix=R(eR,"resize",n))}definition(t){return new t6([t]).addToDOM(this.defs.element)}getReferenceURL(){if((eE||eD)&&eO.getElementsByTagName("base").length){if(!V(e)){let t=tB(),i=new t6([{tagName:"svg",attributes:{width:8,height:8},children:[{tagName:"defs",children:[{tagName:"clipPath",attributes:{id:t},children:[{tagName:"rect",attributes:{width:4,height:4}}]}]},{tagName:"rect",attributes:{id:"hitme",width:8,height:8,"clip-path":`url(#${t})`,fill:"rgba(0,0,0,0.001)"}}]}]).addToDOM(eO.body);$(i,{position:"fixed",top:0,left:0,zIndex:9e5});let s=eO.elementFromPoint(6,6);e=s?.id==="hitme",eO.body.removeChild(i)}if(e)return tM(eR.location.href.split("#")[0],[/<[^>]*>/g,""],[/([\('\)])/g,"\\$1"],[/ /g,"%20"])}return""}getStyle(t){return this.style=q({fontFamily:'-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", sans-serif',fontSize:"1rem"},t),this.style}setStyle(t){this.boxWrapper.css(this.getStyle(t))}isHidden(){return!this.boxWrapper.getBBox().width}destroy(){let t=this.defs;return this.box=null,this.boxWrapper=this.boxWrapper.destroy(),U(this.gradients||{}),this.gradients=null,this.defs=t.destroy(),this.unSubPixelFix&&this.unSubPixelFix(),this.alignedObjects=null,null}createElement(t){return new this.Element(this,t)}getRadialAttr(t,e){return{cx:t[0]-t[2]/2+(e.cx||0)*t[2],cy:t[1]-t[2]/2+(e.cy||0)*t[2],r:(e.r||0)*t[2]}}shadowDefinition(t){let e=[`highcharts-drop-shadow-${this.chartIndex}`,...Object.keys(t).map(e=>`${e}-${t[e]}`)].join("-").toLowerCase().replace(/[^a-z\d\-]/g,""),i=tu({color:"#000000",offsetX:1,offsetY:1,opacity:.15,width:5},t);return this.defs.element.querySelector(`#${e}`)||this.definition({tagName:"filter",attributes:{id:e,filterUnits:i.filterUnits},children:this.getShadowFilterContent(i)}),e}getShadowFilterContent(t){return[{tagName:"feDropShadow",attributes:{dx:t.offsetX,dy:t.offsetY,"flood-color":t.color,"flood-opacity":Math.min(5*t.opacity,1),stdDeviation:t.width/2}}]}buildText(t){new eC(t).buildSVG()}getContrast(t){if("transparent"===t)return"#000000";let e=tU.parse(t).rgba,i=" clamp(0,calc(9e9*(0.5 - (0.2126*r + 0.7152*g + 0.0722*b))),1)";if(tl(e[0])||!tU.useColorMix){let t=e.map(t=>{let e=t/255;return e<=.04?e/12.92:Math.pow((e+.055)/1.055,2.4)}),i=.2126*t[0]+.7152*t[1]+.0722*t[2];return 1.05/(i+.05)>(i+.05)/.05?"#FFFFFF":"#000000"}return"color(from "+t+" srgb"+i+i+i+")"}button(t,e,i,s,o={},r,a,n,h,l){let d=this.label(t,e,i,h,void 0,void 0,l,void 0,"button"),c=this.styledMode,p=arguments,g=0;o=tu(eA.global.buttonTheme,o),c&&(delete o.fill,delete o.stroke,delete o["stroke-width"]);let u=o.states||{},f=o.style||{};delete o.states,delete o.style;let m=[t6.filterUserAttributes(o)],x=[f];return c||["hover","select","disabled"].forEach((t,e)=>{m.push(tu(m[0],t6.filterUserAttributes(p[e+5]||u[t]||{}))),x.push(m[e+1].style),delete m[e+1].style}),R(d.element,eI?"mouseover":"mouseenter",function(){3!==g&&d.setState(1)}),R(d.element,eI?"mouseout":"mouseleave",function(){3!==g&&d.setState(g)}),d.setState=(t=0)=>{if(1!==t&&(d.state=g=t),d.removeClass(/highcharts-button-(normal|hover|pressed|disabled)/).addClass("highcharts-button-"+["normal","hover","pressed","disabled"][t]),!c){d.attr(m[t]);let e=x[t];tg(e)&&d.css(e)}},d.attr(m[0]),!c&&(d.css(q({cursor:"default"},f)),l&&d.text.css({pointerEvents:"none"})),d.on("touchstart",t=>t.stopPropagation()).on("click",function(t){3!==g&&s?.call(d,t)})}crispLine(t,e){let[i,s]=t;return V(i[1])&&i[1]===s[1]&&(i[1]=s[1]=j(i[1],e)),V(i[2])&&i[2]===s[2]&&(i[2]=s[2]=j(i[2],e)),t}path(t){let e=this.styledMode?{}:{fill:"none"};return tc(t)?e.d=t:tg(t)&&q(e,t),this.createElement("path").attr(e)}circle(t,e,i){let s=tg(t)?t:void 0===t?{}:{x:t,y:e,r:i},o=this.createElement("circle");return o.xSetter=o.ySetter=function(t,e,i){i.setAttribute("c"+e,t)},o.attr(s)}arc(t,e,i,s,o,r){let a;tg(t)?(e=(a=t).y,i=a.r,s=a.innerR,o=a.start,r=a.end,t=a.x):a={innerR:s,start:o,end:r};let n=this.symbol("arc",t,e,i,i,a);return n.r=i,n}rect(t,e,i,s,o,r){let a=tg(t)?t:void 0===t?{}:{x:t,y:e,r:o,width:Math.max(i||0,0),height:Math.max(s||0,0)},n=this.createElement("rect");return this.styledMode||(void 0!==r&&(a["stroke-width"]=r,q(a,n.crisp(a))),a.fill="none"),n.rSetter=function(t,e,i){n.r=t,X(i,{rx:t,ry:t})},n.rGetter=function(){return n.r||0},n.attr(a)}roundedRect(t){return this.symbol("roundedRect").attr(t)}setSize(t,e,i){this.width=t,this.height=e,this.boxWrapper.animate({width:t,height:e},{step:function(){this.attr({viewBox:"0 0 "+this.attr("width")+" "+this.attr("height")})},duration:tb(i,!0)?void 0:0}),this.alignElements()}g(t){let e=this.createElement("g");return t?e.attr({class:"highcharts-"+t}):e}image(t,e,i,s,o,r){let a={preserveAspectRatio:"none"};tl(e)&&(a.x=e),tl(i)&&(a.y=i),tl(s)&&(a.width=s),tl(o)&&(a.height=o);let n=this.createElement("image").attr(a),h=function(e){n.attr({href:t}),r.call(n,e)};if(r){n.attr({href:"data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="});let e=new eR.Image;R(e,"load",h),e.src=t,e.complete&&h({})}else n.attr({href:t});return n}symbol(t,e,i,s,o,r){let a,n,h,l,d=this,c=/^url\((.*?)\)$/,p=c.test(t),g=!p&&(this.symbols[t]?t:"circle"),u=g&&this.symbols[g];if(u)"number"==typeof e&&(n=u.call(this.symbols,e||0,i||0,s||0,o||0,r)),a=this.path(n),d.styledMode||a.attr("fill","none"),q(a,{symbolName:g||void 0,x:e,y:i,width:s,height:o}),r&&q(a,r);else if(p){h=t.match(c)[1];let s=a=this.image(h);s.imgwidth=tb(r?.width,ez[h]?.width),s.imgheight=tb(r?.height,ez[h]?.height),l=t=>t.attr({width:t.width,height:t.height}),["width","height"].forEach(t=>{s[`${t}Setter`]=function(t,e){this[e]=t;let{alignByTranslate:i,element:s,width:o,height:a,imgwidth:n,imgheight:h}=this,l="width"===e?n:h,d=1;r&&"within"===r.backgroundSize&&o&&a&&n&&h?(d=Math.min(o/n,a/h),X(s,{width:Math.round(n*d),height:Math.round(h*d)})):s&&l&&s.setAttribute(e,l),!i&&n&&h&&this.translate(((o||0)-n*d)/2,((a||0)-h*d)/2)}}),V(e)&&s.attr({x:e,y:i}),s.isImg=!0,V(s.imgwidth)&&V(s.imgheight)?l(s):(s.attr({width:0,height:0}),Y("img",{onload:function(){let t=eP[d.chartIndex];0===this.width&&($(this,{position:"absolute",top:"-999em"}),eO.body.appendChild(this)),ez[h]={width:this.width,height:this.height},s.imgwidth=this.width,s.imgheight=this.height,s.element&&l(s),this.parentNode&&this.parentNode.removeChild(this),d.asyncCounter--,d.asyncCounter||!t||t.hasLoaded||t.onload()},src:h}),this.asyncCounter++)}return a}clipRect(t,e,i,s){return this.rect(t,e,i,s,0)}text(t,e,i,s){let o={};if(s&&(this.allowHTML||!this.forExport))return this.html(t,e,i);o.x=Math.round(e||0),i&&(o.y=Math.round(i)),V(t)&&(o.text=t);let r=this.createElement("text").attr(o);return s&&(!this.forExport||this.allowHTML)||(r.xSetter=function(t,e,i){let s=i.getElementsByTagName("tspan"),o=i.getAttribute(e);for(let i=0,r;it.align())}}q(eW.prototype,{Element:em,SVG_NS:eN,escapes:{"&":"&","<":"<",">":">","'":"'",'"':"""},symbols:ek,draw:eB}),eo.registerRendererType("svg",eW,!0);let{composed:eH,isFirefox:eX}=B;function eG(t,e,i){let s=this.div?.style;em.prototype[`${e}Setter`].call(this,t,e,i),s&&(i.style[e]=s[e]=t)}let eF=(t,e)=>{if(!t.div){let i=X(t.element,"class"),s=t.css,o=Y("div",i?{className:i}:void 0,{position:"absolute",left:`${t.translateX||0}px`,top:`${t.translateY||0}px`,...t.styles,display:t.display,opacity:t.opacity,visibility:t.visibility},t.parentGroup?.div||e);t.classSetter=(t,e,i)=>{i.setAttribute("class",t),o.className=t},t.translateXSetter=t.translateYSetter=(e,i)=>{t[i]=e,o.style["translateX"===i?"left":"top"]=`${e}px`,t.doTransform=!0},t.scaleXSetter=t.scaleYSetter=(e,i)=>{t[i]=e,t.doTransform=!0},t.opacitySetter=t.visibilitySetter=eG,t.css=e=>(s.call(t,e),e.cursor&&(o.style.cursor=e.cursor),e.pointerEvents&&(o.style.pointerEvents=e.pointerEvents),t),t.on=function(){return em.prototype.on.apply({element:o,onEvents:t.onEvents},arguments),t},t.div=o}return t.div};class eY extends em{static compose(t){tk(eH,this.compose)&&(t.prototype.html=function(t,e,i){return new eY(this,"span").attr({text:t,x:Math.round(e),y:Math.round(i)})})}constructor(t,e){super(t,e),eY.useForeignObject?this.foreignObject=t.createElement("foreignObject").attr({zIndex:2}):this.css({position:"absolute",...t.styledMode?{}:{fontFamily:t.style.fontFamily,fontSize:t.style.fontSize}}),this.element.style.whiteSpace="nowrap"}getSpanCorrection(t,e,i){this.xCorr=-t*i,this.yCorr=-e}css(t){let e,{element:i}=this,s="SPAN"===i.tagName&&t&&"width"in t,o=s&&t.width;return s&&(delete t.width,this.textWidth=tv(o)||void 0,e=!0),t?.textOverflow==="ellipsis"&&(t.overflow="hidden",t.whiteSpace="nowrap"),t?.lineClamp&&(t.display="-webkit-box",t.WebkitLineClamp=t.lineClamp,t.WebkitBoxOrient="vertical",t.overflow="hidden"),tl(Number(t?.fontSize))&&(t.fontSize+="px"),q(this.styles,t),$(i,t),e&&this.updateTransform(),this}htmlGetBBox(){let{element:t}=this;return{x:t.offsetLeft,y:t.offsetTop,width:t.offsetWidth,height:t.offsetHeight}}updateTransform(){if(!this.added){this.alignOnAdd=!0;return}let{element:t,foreignObject:e,oldTextWidth:i,renderer:s,rotation:o,rotationOriginX:r,rotationOriginY:a,scaleX:n,scaleY:h,styles:{display:l="inline-block",whiteSpace:d},textAlign:c="left",textWidth:p,translateX:g=0,translateY:u=0,x:f=0,y:m=0}=this,x=()=>this.textPxLength?this.textPxLength:($(t,{width:"",whiteSpace:d||"nowrap"}),t.offsetWidth);if(e||$(t,{marginLeft:`${g}px`,marginTop:`${u}px`}),"SPAN"===t.tagName){let g,u=[o,c,t.innerHTML,p,this.textAlign].join(","),y=-(this.parentGroup?.padding*1)||0;if(p!==i){let e=x(),r=p||0,a=!s.styledMode&&""===t.style.textOverflow&&t.style.webkitLineClamp;(r>i||e>r||a)&&(/[\-\s\u00AD]/.test(t.textContent||t.innerText)||"ellipsis"===t.style.textOverflow)&&($(t,{width:(o||n||e>r)&&tl(p)?p+"px":a?Math.min(e+1,r)+"px":"auto",display:l,whiteSpace:d||"normal"}),this.oldTextWidth=p)}e&&($(t,{display:"inline-block",verticalAlign:"top"}),e.attr({width:s.width,height:s.height})),u!==this.cTT&&(g=s.fontMetrics(t).b,V(o)&&!e&&(o!==(this.oldRotation||0)||c!==this.oldAlign)&&$(t,{transform:`rotate(${o}deg)`,transformOrigin:`${y}% ${y}px`}),this.getSpanCorrection(!V(o)&&!this.textWidth&&this.textPxLength||t.offsetWidth,g,tt(c)));let{xCorr:b=0,yCorr:v=0}=this,k={left:`${f+b}px`,top:`${m+v}px`,textAlign:c,transformOrigin:`${(r??f)-b-f-y}px ${(a??m)-v-m-y}px`};(n||h)&&(k.transform=`scale(${n??1},${h??1})`),e?(super.updateTransform(),tl(f)&&tl(m)?(e.attr({x:f+b,y:m+v,width:t.offsetWidth+3,height:t.offsetHeight,"transform-origin":t.getAttribute("transform-origin")||"0 0"}),$(t,{display:l,textAlign:c})):eX&&e.attr({width:0,height:0})):$(t,k),this.cTT=u,this.oldRotation=o,this.oldAlign=c}}add(t){let{foreignObject:e,renderer:i}=this,s=i.box.parentNode,o=[];if(e)e.add(t),super.add(i.createElement("body").attr({xmlns:"http://www.w3.org/1999/xhtml"}).css({background:"transparent",margin:"0 3px 0 0"}).add(e));else{let e;if(this.parentGroup=t,t&&!(e=t.div)){let i=t;for(;i;)o.push(i),i=i.parentGroup;for(let t of o.reverse())e=eF(t,s)}(e||s).appendChild(this.element)}return this.added=!0,this.alignOnAdd&&this.updateTransform(),this}textSetter(t){t!==this.textStr&&(delete this.bBox,delete this.oldTextWidth,t6.setElementHTML(this.element,t??""),this.textStr=t,this.doTransform=!0)}alignSetter(t){this.alignValue=this.textAlign=t,this.doTransform=!0}xSetter(t,e){this[e]=t,this.doTransform=!0}}let ej=eY.prototype;ej.visibilitySetter=ej.opacitySetter=eG,ej.ySetter=ej.rotationSetter=ej.rotationOriginXSetter=ej.rotationOriginYSetter=ej.xSetter,(h=y||(y={})).xAxis={alignTicks:!0,allowDecimals:void 0,panningEnabled:!0,zIndex:2,zoomEnabled:!0,dateTimeLabelFormats:{millisecond:{main:"%[HMSL]",range:!1},second:{main:"%[HMS]",range:!1},minute:{main:"%[HM]",range:!1},hour:{main:"%[HM]",range:!1},day:{main:"%[eb]"},week:{main:"%[eb]"},month:{main:"%[bY]"},year:{main:"%Y"}},endOnTick:!1,gridLineDashStyle:"Solid",gridZIndex:1,labels:{autoRotationLimit:80,distance:15,enabled:!0,indentation:10,overflow:"justify",reserveSpace:void 0,rotation:void 0,staggerLines:0,step:0,useHTML:!1,zIndex:7,style:{color:"#333333",cursor:"default",fontSize:"0.8em",textOverflow:"ellipsis"}},maxPadding:.01,minorGridLineDashStyle:"Solid",minorTickLength:2,minorTickPosition:"outside",minorTicksPerMajor:5,minPadding:.01,offset:void 0,reversed:void 0,reversedStacks:!1,showEmpty:!0,showFirstLabel:!0,showLastLabel:!0,startOfWeek:1,startOnTick:!1,tickLength:10,tickmarkPlacement:"between",tickPixelInterval:100,tickPosition:"outside",title:{align:"middle",useHTML:!1,x:0,y:0,style:{color:"#666666",fontSize:"0.8em"}},visible:!0,minorGridLineColor:"#f2f2f2",minorGridLineWidth:1,minorTickColor:"#999999",lineColor:"#333333",lineWidth:1,gridLineColor:"#e6e6e6",gridLineWidth:void 0,tickColor:"#333333"},h.yAxis={reversedStacks:!0,endOnTick:!0,maxPadding:.05,minPadding:.05,tickPixelInterval:72,showLastLabel:!0,labels:{x:void 0},startOnTick:!0,title:{},stackLabels:{animation:{},allowOverlap:!1,enabled:!1,crop:!0,overflow:"justify",formatter:function(){return this.axis.chart.numberFormatter(this.total||0,-1)},style:{color:"#000000",fontSize:"0.7em",fontWeight:"bold",textOutline:"1px contrast"}},gridLineWidth:1,lineWidth:0};let e$=y;(b||(b={})).registerEventOptions=function(t,e){t.eventOptions=t.eventOptions||{},tm(e.events,function(e,i){t.eventOptions[i]!==e&&(t.eventOptions[i]&&(tS(t,i,t.eventOptions[i]),delete t.eventOptions[i]),tp(e)&&(t.eventOptions[i]=e,R(t,i,e,{order:0})))})};let eV=b,{deg2rad:eU}=B,eZ=class{constructor(t,e,i,s,o){this.isNew=!0,this.isNewLabel=!0,this.axis=t,this.pos=e,this.type=i||"",this.parameters=o||{},this.tickmarkOffset=this.parameters.tickmarkOffset,this.options=this.parameters.options,Q(this,"init"),i||s||this.addLabel()}addLabel(){let t=this,e=t.axis,i=e.options,s=e.chart,o=e.categories,r=e.logarithmic,a=e.names,n=t.pos,h=tb(t.options?.labels,i.labels),l=e.tickPositions,d=n===l[0],c=n===l[l.length-1],p=(!h.step||1===h.step)&&1===e.tickInterval,g=l.info,u=t.label,f,m,x,y=this.parameters.category||(o?tb(o[n],a[n],n):n);r&&tl(y)&&(y=F(r.lin2log(y))),e.dateTime&&(g?f=(m=s.time.resolveDTLFormat(i.dateTimeLabelFormats[!i.grid?.enabled&&g.higherRanks[n]||g.unitName])).main:tl(y)&&(f=e.dateTime.getXDateFormat(y,i.dateTimeLabelFormats||{}))),t.isFirst=d,t.isLast=c;let b={axis:e,chart:s,dateTimeLabelFormat:f,isFirst:d,isLast:c,pos:n,tick:t,tickPositionInfo:g,value:y};Q(this,"labelFormat",b);let v=t=>h.formatter?h.formatter.call(t,t):h.format?(t.text=e.defaultLabelFormatter.call(t),es.format(h.format,t,s)):e.defaultLabelFormatter.call(t),k=v.call(b,b),w=m?.list;w?t.shortenLabel=function(){for(x=0;x0&&s+d*c>n&&(f=Math.round((o-s)/Math.cos(l*eU))):(s-d*cn&&(g=n-t.x+g*d,u=-1),(g=Math.min(p,g))g||e.autoRotation&&h?.styles?.width)&&(f=g)),f&&h&&(this.shortenLabel?this.shortenLabel():h.css(q({},{width:Math.floor(f)+"px",lineClamp:+!e.isRadial})))}moveLabel(t,e){let i=this,s=i.label,o=i.axis,r=!1,a;s&&s.textStr===t?(i.movedLabel=s,r=!0,delete i.label):tm(o.ticks,function(e){r||e.isNew||e===i||!e.label||e.label.textStr!==t||(i.movedLabel=e.label,r=!0,e.labelPos=i.movedLabel.xy,delete e.label)}),!r&&(i.labelPos||s)&&(a=i.labelPos||s.xy,i.movedLabel=i.createLabel(t,e,a),i.movedLabel&&i.movedLabel.attr({opacity:0}))}render(t,e,i){let s=this.axis,o=s.horiz,r=this.pos,a=tb(this.tickmarkOffset,s.tickmarkOffset),n=this.getPosition(o,r,a,e),h=n.x,l=n.y,d=s.pos,c=d+s.len,p=o?h:l,g=tb(i,this.label?.newOpacity,1);!s.chart.polar&&(F(p)c)&&(i=0),i??(i=1),this.isActive=!0,this.renderGridLine(e,i),this.renderMark(n,i),this.renderLabel(n,e,g,t),this.isNew=!1,Q(this,"afterRender")}renderGridLine(t,e){let i=this.axis,s=i.options,o={},r=this.pos,a=this.type,n=tb(this.tickmarkOffset,i.tickmarkOffset),h=i.chart.renderer,l=this.gridLine,d,c=s.gridLineWidth,p=s.gridLineColor,g=s.gridLineDashStyle;"minor"===this.type&&(c=s.minorGridLineWidth,p=s.minorGridLineColor,g=s.minorGridLineDashStyle),l||(i.chart.styledMode||(o.stroke=p,o["stroke-width"]=c||0,o.dashstyle=g),a||(o.zIndex=1),t&&(e=0),this.gridLine=l=h.path().attr(o).addClass("highcharts-"+(a?a+"-":"")+"grid-line").add(i.gridGroup)),l&&(d=i.getPlotLinePath({value:r+n,lineWidth:l.strokeWidth(),force:"pass",old:t,acrossPanes:!1}))&&l[t||this.isNew?"attr":"animate"]({d:d,opacity:e})}renderMark(t,e){let i=this.axis,s=i.options,o=i.chart.renderer,r=this.type,a=i.tickSize(r?r+"Tick":"tick"),n=t.x,h=t.y,l=tb(s["minor"!==r?"tickWidth":"minorTickWidth"],!r&&i.isXAxis?1:0),d=s["minor"!==r?"tickColor":"minorTickColor"],c=this.mark,p=!c;a&&(i.opposite&&(a[0]=-a[0]),!c&&(this.mark=c=o.path().addClass("highcharts-"+(r?r+"-":"")+"tick").add(i.axisGroup),i.chart.styledMode||c.attr({stroke:d,"stroke-width":l})),c[p?"attr":"animate"]({d:this.getMarkPath(n,h,a[0],c.strokeWidth(),i.horiz,o),opacity:e}))}renderLabel(t,e,i,s){let o=this.axis,r=o.horiz,a=o.options,n=this.label,h=a.labels,l=h.step,d=tb(this.tickmarkOffset,o.tickmarkOffset),c=t.x,p=t.y,g=!0;n&&tl(c)&&(n.xy=t=this.getLabelPosition(c,p,n,r,h,d,s,l),(!this.isFirst||this.isLast||a.showFirstLabel)&&(!this.isLast||this.isFirst||a.showLastLabel)?r&&!e&&0!==i&&this.handleOverflow(t):g=!1,l&&s%l&&(g=!1),g&&tl(t.y)?(t.opacity=i,n[this.isNewLabel?"attr":"animate"](t).show(!0),this.isNewLabel=!1):(n.hide(),this.isNewLabel=!0))}replaceMovedLabel(){let t=this.label,e=this.axis;t&&!this.isNew&&(t.animate({opacity:0},void 0,t.destroy),delete this.label),e.isDirty=!0,this.label=this.movedLabel,delete this.movedLabel}},{animObject:e_}=tQ,{xAxis:eK,yAxis:eq}=e$,{defaultOptions:eJ}=tY,{registerEventOptions:eQ}=eV,{deg2rad:e0}=B,e1=(t,e)=>tf(e,void 0,void 0,tb(t.options.allowDecimals,e<.5||void 0!==t.tickAmount),!!t.tickAmount);q(eJ,{xAxis:eK,yAxis:tu(eK,eq)});class e2{constructor(t,e,i){this.init(t,e,i)}init(t,e,i=this.coll){let s="xAxis"===i,o=this.isZAxis||(t.inverted?!s:s);this.chart=t,this.horiz=o,this.isXAxis=s,this.coll=i,Q(this,"init",{userOptions:e}),this.opposite=tb(e.opposite,this.opposite),this.side=tb(e.side,this.side,o?2*!this.opposite:this.opposite?1:3),this.setOptions(e);let r=this.options,a=r.labels;this.type??(this.type=r.type||"linear"),this.uniqueNames??(this.uniqueNames=r.uniqueNames??!0),Q(this,"afterSetType"),this.userOptions=e,this.minPixelPadding=0,this.reversed=tb(r.reversed,this.reversed),this.visible=r.visible,this.zoomEnabled=r.zoomEnabled,this.hasNames="category"===this.type||!0===r.categories,this.categories=tc(r.categories)&&r.categories||(this.hasNames?[]:void 0),this.names||(this.names=[],this.names.keys={}),this.plotLinesAndBandsGroups={},this.positiveValuesOnly=!!this.logarithmic,this.isLinked=V(r.linkedTo),this.ticks={},this.labelEdge=[],this.minorTicks={},this.plotLinesAndBands=[],this.alternateBands={},this.len??(this.len=0),this.minRange=this.userMinRange=r.minRange||r.maxZoom,this.range=r.range,this.offset=r.offset||0,this.max=void 0,this.min=void 0;let n=tb(r.crosshair,tT(t.options.tooltip.crosshairs)[+!s]);this.crosshair=!0===n?{}:n,-1===t.axes.indexOf(this)&&(s?t.axes.splice(t.xAxis.length,0,this):t.axes.push(this),tI(this,t[this.coll])),t.orderItems(this.coll),this.series=this.series||[],t.inverted&&!this.isZAxis&&s&&!V(this.reversed)&&(this.reversed=!0),this.labelRotation=tl(a.rotation)?a.rotation:void 0,eQ(this,r),Q(this,"afterInit")}setOptions(t){let e=this.horiz?{labels:{autoRotation:[-45],padding:3},margin:15}:{labels:{padding:1},title:{rotation:90*this.side}};this.options=tu(e,"yAxis"===this.coll?{title:{text:this.chart.options.lang.yAxisTitle}}:{},eJ[this.coll],t),Q(this,"afterSetOptions",{userOptions:t})}defaultLabelFormatter(){let t=this.axis,e=this.chart,{numberFormatter:i}=e,s=tl(this.value)?this.value:NaN,o=t.chart.time,r=t.categories,a=this.dateTimeLabelFormat,n=eJ.lang,h=n.numericSymbols,l=n.numericSymbolMagnitude||1e3,d=t.logarithmic?Math.abs(s):t.tickInterval,c=h?.length,p,g;if(r)g=`${this.value}`;else if(a)g=o.dateFormat(a,s,!0);else if(c&&h&&d>=1e3)for(;c--&&void 0===g;)d>=(p=Math.pow(l,c+1))&&10*s%p==0&&null!==h[c]&&0!==s&&(g=i(s/p,-1,void 0,void 0,e)+h[c]);return g??(g=i(s,-1,void 0,1e4>Math.abs(s)?"":void 0,e)),g}getSeriesExtremes(){let t,e=this;Q(this,"getSeriesExtremes",null,function(){e.hasVisibleSeries=!1,e.dataMin=e.dataMax=e.threshold=void 0,e.softThreshold=!e.isXAxis,e.series.forEach(i=>{if(i.reserveSpace()){let s=i.options,o,r=s.threshold,a,n;if(e.hasVisibleSeries=!0,e.positiveValuesOnly&&0>=(r||0)&&(r=void 0),e.isXAxis)(o=i.getColumn("x")).length&&(o=e.logarithmic?o.filter(t=>t>0):o,a=(t=i.getXExtremes(o)).min,n=t.max,tl(a)||a instanceof Date||(o=o.filter(tl),a=(t=i.getXExtremes(o)).min,n=t.max),o.length&&(e.dataMin=Math.min(tb(e.dataMin,a),a),e.dataMax=Math.max(tb(e.dataMax,n),n)));else{let t=i.applyExtremes();tl(t.dataMin)&&(a=t.dataMin,e.dataMin=Math.min(tb(e.dataMin,a),a)),tl(t.dataMax)&&(n=t.dataMax,e.dataMax=Math.max(tb(e.dataMax,n),n)),V(r)&&(e.threshold=r),(!s.softThreshold||e.positiveValuesOnly)&&(e.softThreshold=!1)}}})}),Q(this,"afterGetSeriesExtremes")}translate(t,e,i,s,o,r){let a=this.linkedParent||this,n=s&&a.old?a.old.min:a.min;if(!tl(n))return NaN;let h=a.minPixelPadding,l=(a.isOrdinal||a.brokenAxis?.hasBreaks||a.logarithmic&&o)&&!!a.lin2val,d=1,c=0,p=s&&a.old?a.old.transA:a.transA,g=0;return p||(p=a.transA),i&&(d*=-1,c=a.len),a.reversed&&(d*=-1,c-=d*(a.sector||a.len)),e?(g=(t=t*d+c-h)/p+n,l&&(g=a.lin2val(g))):(l&&(t=a.val2lin(t)),g=d*(t-n)*p+c+d*h+(tl(r)?p*r:0),a.isRadial||(g=F(g))),g}toPixels(t,e){return this.translate(this.chart?.time.parse(t)??NaN,!1,!this.horiz,void 0,!0)+(e?0:this.pos)}toValue(t,e){return this.translate(t-(e?0:this.pos),!0,!this.horiz,void 0,!0)}getPlotLinePath(t){let e=this,i=e.chart,s=e.left,o=e.top,r=t.old,a=t.value,n=t.lineWidth,h=r&&i.oldChartHeight||i.chartHeight,l=r&&i.oldChartWidth||i.chartWidth,d=e.transB,c=t.translatedValue,p=t.force,g,u,f,m,x;function y(t,e,i){return"pass"!==p&&(ti)&&(p?t=G(t,e,i):x=!0),t}let b={value:a,lineWidth:n,old:r,force:p,acrossPanes:t.acrossPanes,translatedValue:c};return Q(this,"getPlotLinePath",b,function(t){g=f=(c=G(c=tb(c,e.translate(a,void 0,void 0,r)),-1e9,1e9))+d,u=m=h-c-d,tl(c)?e.horiz?(u=o,m=h-e.bottom+(e.options.isInternal?0:i.scrollablePixelsY||0),g=f=y(g,s,s+e.width)):(g=s,f=l-e.right+(i.scrollablePixelsX||0),u=m=y(u,o,o+e.height)):(x=!0,p=!1),t.path=x&&!p?void 0:i.renderer.crispLine([["M",g,u],["L",f,m]],n||1)}),b.path}getLinearTickPositions(t,e,i){let s,o,r,a=F(Math.floor(e/t)*t),n=F(Math.ceil(i/t)*t),h=[];if(F(a+t)===a&&(r=20),this.single)return[e];for(s=a;s<=n&&(h.push(s),(s=F(s+t,r))!==o);)o=s;return h}getMinorTickInterval(){let{minorTicks:t,minorTickInterval:e}=this.options;return!0===t?tb(e,"auto"):!1!==t?e:void 0}getMinorTickPositions(){let t=this.options,e=this.tickPositions,i=this.minorTickInterval,s=this.pointRangePadding||0,o=(this.min||0)-s,r=(this.max||0)+s,a=this.brokenAxis?.hasBreaks?this.brokenAxis.unitLength:r-o,n=[],h;if(a&&a/i{let e=t.getColumn("x");return t.xIncrement?e.slice(0,2):e}))||0),this.dataMax-this.dataMin)),tl(s)&&tl(o)&&tl(r)&&s-o=r,a=(r-s+o)/2,h=[o-a,i.parse(t.min)??o-a],n&&(h[2]=e?e.log2lin(this.dataMin):this.dataMin),l=[(o=H(h))+r,i.parse(t.max)??o+r],n&&(l[2]=e?e.log2lin(this.dataMax):this.dataMax),(s=W(l))-ot-e),t=te([i]))}return t&&e?Math.min(t,e):t||e}nameToX(t){let e=tc(this.options.categories),i=e?this.categories:this.names,s=t.options.x,o;return t.series.requireSorting=!1,V(s)||(s=this.uniqueNames&&i?e?i.indexOf(t.name):tb(i.keys[t.name],-1):t.series.autoIncrement()),-1===s?!e&&i&&(o=i.length):tl(s)&&(o=s),void 0!==o?(this.names[o]=t.name,this.names.keys[t.name]=o):t.x&&(o=t.x),o}updateNames(){let t=this,e=this.names;e.length>0&&(Object.keys(e.keys).forEach(function(t){delete e.keys[t]}),e.length=0,this.minRange=this.userMinRange,(this.series||[]).forEach(e=>{e.xIncrement=null,(!e.points||e.isDirtyData)&&(t.max=Math.max(t.max||0,e.dataTable.rowCount-1),e.processData(),e.generatePoints());let i=e.getColumn("x").slice();e.data.forEach((e,s)=>{let o=i[s];e?.options&&void 0!==e.name&&void 0!==(o=t.nameToX(e))&&o!==e.x&&(i[s]=e.x=o)}),e.dataTable.setColumn("x",i)}))}setAxisTranslation(){let t=this,e=t.max-t.min,i=t.linkedParent,s=!!t.categories,o=t.isXAxis,r=t.axisPointRange||0,a,n=0,h=0,l,d=t.transA;(o||s||r)&&(a=t.getClosest(),i?(n=i.minPointOffset,h=i.pointRangePadding):t.series.forEach(function(e){let i=s?1:o?tb(e.options.pointRange,a,0):t.axisPointRange||0,l=e.options.pointPlacement;if(r=Math.max(r,i),!t.single||s){let t=e.is("xrange")?!o:o;n=Math.max(n,t&&td(l)?0:i/2),h=Math.max(h,t&&"on"===l?0:i)}}),l=t.ordinal?.slope&&a?t.ordinal.slope/a:1,t.minPointOffset=n*=l,t.pointRangePadding=h*=l,t.pointRange=Math.min(r,t.single&&s?1:e),o&&(t.closestPointRange=a)),t.translationSlope=t.transA=d=t.staticScale||t.len/(e+h||1),t.transB=t.horiz?t.left:t.bottom,t.minPixelPadding=d*n,Q(this,"afterSetAxisTranslation")}minFromRange(){let{max:t,min:e}=this;return tl(t)&&tl(e)&&t-e||void 0}setTickInterval(t){let{categories:e,chart:i,dataMax:s,dataMin:o,dateTime:r,isXAxis:a,logarithmic:n,options:h,softThreshold:l}=this,d=i.time,c=tl(this.threshold)?this.threshold:void 0,p=this.minRange||0,{ceiling:g,floor:u,linkedTo:f,softMax:m,softMin:x}=h,y=tl(f)&&i[this.coll]?.[f],b=h.tickPixelInterval,v=h.maxPadding,k=h.minPadding,w=0,M,S=tl(h.tickInterval)&&h.tickInterval>=0?h.tickInterval:void 0,T,C,A,P;if(r||e||y||this.getTickAmount(),A=tb(this.userMin,d.parse(h.min)),P=tb(this.userMax,d.parse(h.max)),y?(this.linkedParent=y,M=y.getExtremes(),this.min=tb(M.min,M.dataMin),this.max=tb(M.max,M.dataMax),this.type!==y.type&&tE(11,!0,i)):(l&&V(c)&&tl(s)&&tl(o)&&(o>=c?(T=c,k=0):s<=c&&(C=c,v=0)),this.min=tb(A,T,o),this.max=tb(P,C,s)),tl(this.max)&&tl(this.min)&&(n&&(this.positiveValuesOnly&&!t&&0>=Math.min(this.min,tb(o,this.min))&&tE(10,!0,i),this.min=F(n.log2lin(this.min),16),this.max=F(n.log2lin(this.max),16)),this.range&&tl(o)&&(this.userMin=this.min=A=Math.max(o,this.minFromRange()||0),this.userMax=P=this.max,this.range=void 0)),Q(this,"foundExtremes"),this.adjustForMinRange(),tl(this.min)&&tl(this.max)){if(!tl(this.userMin)&&tl(x)&&xthis.max&&(this.max=P=m),e||this.axisPointRange||this.stacking?.usePercentage||y||(w=this.max-this.min)&&(!V(A)&&k&&(this.min-=w*k),!V(P)&&v&&(this.max+=w*v)),!tl(this.userMin)&&tl(u)&&(this.min=Math.max(this.min,u)),!tl(this.userMax)&&tl(g)&&(this.max=Math.min(this.max,g)),l&&tl(o)&&tl(s)){let t=c||0;!V(A)&&this.min=t?this.min=h.minRange?Math.min(t,this.max-p):t:!V(P)&&this.max>t&&s<=t&&(this.max=h.minRange?Math.max(t,this.min+p):t)}!i.polar&&this.min>this.max&&(V(h.min)?this.max=this.min:V(h.max)&&(this.min=this.max)),w=this.max-this.min}if(this.min!==this.max&&tl(this.min)&&tl(this.max)?y&&!S&&b===y.options.tickPixelInterval?this.tickInterval=S=y.tickInterval:this.tickInterval=tb(S,this.tickAmount?w/Math.max(this.tickAmount-1,1):void 0,e?1:w*b/Math.max(this.len,b)):this.tickInterval=1,a&&!t){let t=this.min!==this.old?.min||this.max!==this.old?.max;this.series.forEach(function(e){e.forceCrop=e.forceCropping?.(),e.processData(t)}),Q(this,"postProcessData",{hasExtremesChanged:t})}this.setAxisTranslation(),Q(this,"initialAxisTranslation"),this.pointRange&&!S&&(this.tickInterval=Math.max(this.pointRange,this.tickInterval));let L=tb(h.minTickInterval,r&&!this.series.some(t=>!t.sorted)?this.closestPointRange:0);!S&&L&&this.tickIntervalMath.max(2*this.len,200))n=[this.min,this.max],tE(19,!1,this.chart);else if(this.dateTime)n=this.getTimeTicks(this.dateTime.normalizeTimeTickInterval(this.tickInterval,t.units),this.min,this.max,t.startOfWeek,this.ordinal?.positions,this.closestPointRange,!0);else if(this.logarithmic)n=this.logarithmic.getLogTickPositions(this.tickInterval,this.min,this.max);else{let t=this.tickInterval,e=t;for(;e<=2*t;)if(n=this.getLinearTickPositions(this.tickInterval,this.min,this.max),this.tickAmount&&n.length>this.tickAmount)this.tickInterval=e1(this,e*=1.1);else break}n.length>this.len&&(n=[n[0],n[n.length-1]])[0]===n[1]&&(n.length=1),i&&(this.tickPositions=n,(h=i.apply(this,[this.min,this.max,this]))&&(n=h))}this.isDirty||n.length===this.tickPositions?.length||(this.isDirty=!0),this.tickPositions=n,this.minorTickInterval="auto"===s&&this.tickInterval?this.tickInterval/t.minorTicksPerMajor:s,this.paddedTicks=n.slice(0),this.trimTicks(n,r,a),!this.isLinked&&tl(this.min)&&tl(this.max)&&(this.single&&n.length<2&&!this.categories&&!this.series.some(t=>t.is("heatmap")&&"between"===t.options.pointPlacement)&&(this.min-=.5,this.max+=.5),e||h||this.adjustTickAmount()),Q(this,"afterSetTickPositions")}trimTicks(t,e,i){let s=t[0],o=t[t.length-1],r=!this.isOrdinal&&this.minPointOffset||0;if(Q(this,"trimTicks"),!this.isLinked||!this.grid){if(e&&s!==-1/0)this.min=s;else for(;this.min-r>t[0];)t.shift();if(i)this.max=o;else for(;this.max+r{let{horiz:e,options:i}=t;return[e?i.left:i.top,i.width,i.height,i.pane].join(",")},r=o(this);i[this.coll].forEach(function(i){let{series:a}=i;a.length&&a.some(t=>t.visible)&&i!==e&&o(i)===r&&(t=!0,s.push(i))})}if(t&&a){s.forEach(t=>{let i=t.getThresholdAlignment(e);tl(i)&&n.push(i)});let t=n.length>1?n.reduce((t,e)=>t+=e,0)/n.length:void 0;s.forEach(e=>{e.thresholdAlignment=t})}return t}getThresholdAlignment(t){if((!tl(this.dataMin)||this!==t&&this.series.some(t=>t.isDirty||t.isDirtyData||t.xAxis?.isDirty))&&this.getSeriesExtremes(),tl(this.threshold)){let t=G((this.threshold-(this.dataMin||0))/((this.dataMax||0)-(this.dataMin||0)),0,1);return this.options.reversed&&(t=1-t),t}}getTickAmount(){let t=this.options,e=t.tickPixelInterval,i=t.tickAmount;V(t.tickInterval)||i||!(this.lenr.push(F(r[r.length-1]+p)),f=()=>r.unshift(F(r[0]-p));if(tl(n)&&(g=0===n?0:1===n?a-1:Math.round(G(n*(a-1),1,a-2)),o.reversed&&(g=a-1-g)),t.hasData()&&tl(s)&&tl(i)){let n=()=>{t.transA*=(h-1)/(a-1),t.min=o.startOnTick?r[0]:Math.min(s,r[0]),t.max=o.endOnTick?r[r.length-1]:Math.max(i,r[r.length-1])};if(tl(g)&&tl(t.threshold)){for(;r[g]!==l||r.length!==a||r[0]>s||r[r.length-1]t.threshold?f():u();if(p>8*t.tickInterval)break;p*=2}n()}else if(h0&&c{i=i||t.isDirtyData||t.isDirty,s=s||t.xAxis?.isDirty||!1}),this.setAxisSize();let o=this.len!==this.old?.len;o||i||s||this.isLinked||this.forceRedraw||this.userMin!==this.old?.userMin||this.userMax!==this.old?.userMax||this.alignToOthers()?(e&&"yAxis"===t&&e.buildStacks(),this.forceRedraw=!1,this.userMinRange||(this.minRange=void 0),this.getSeriesExtremes(),this.setTickInterval(),e&&"xAxis"===t&&e.buildStacks(),this.isDirty||(this.isDirty=o||this.min!==this.old?.min||this.max!==this.old?.max)):e&&e.cleanStacks(),i&&delete this.allExtremes,Q(this,"afterSetScale")}setExtremes(t,e,i=!0,s,o){let r=this.chart;this.series.forEach(t=>{delete t.kdTree}),t=r.time.parse(t),e=r.time.parse(e),Q(this,"setExtremes",o=q(o,{min:t,max:e}),t=>{this.userMin=t.min,this.userMax=t.max,this.eventArgs=t,i&&r.redraw(s)})}setAxisSize(){let t=this.chart,e=this.options,i=e.offsets||[0,0,0,0],s=this.horiz,o=this.width=Math.round(tw(tb(e.width,t.plotWidth-i[3]+i[1]),t.plotWidth)),r=this.height=Math.round(tw(tb(e.height,t.plotHeight-i[0]+i[2]),t.plotHeight)),a=this.top=Math.round(tw(tb(e.top,t.plotTop+i[0]),t.plotHeight,t.plotTop)),n=this.left=Math.round(tw(tb(e.left,t.plotLeft+i[3]),t.plotWidth,t.plotLeft));this.bottom=t.chartHeight-r-a,this.right=t.chartWidth-o-n,this.len=Math.max(s?o:r,0),this.pos=s?n:a}getExtremes(){let t=this.logarithmic;return{min:t?F(t.lin2log(this.min)):this.min,max:t?F(t.lin2log(this.max)):this.max,dataMin:this.dataMin,dataMax:this.dataMax,userMin:this.userMin,userMax:this.userMax}}getThreshold(t){let e=this.logarithmic,i=e?e.lin2log(this.min):this.min,s=e?e.lin2log(this.max):this.max;return null===t||t===-1/0?t=i:t===1/0?t=s:i>t?t=i:s15&&e<165?t.align="right":e>195&&e<345&&(t.align="left")}),i.align}tickSize(t){let e=this.options,i=tb(e["tick"===t?"tickWidth":"minorTickWidth"],"tick"===t&&this.isXAxis&&!this.categories?1:0),s=e["tick"===t?"tickLength":"minorTickLength"],o;i&&s&&("inside"===e[t+"Position"]&&(s=-s),o=[s,i]);let r={tickSize:o};return Q(this,"afterTickSize",r),r.tickSize}labelMetrics(){let t=this.chart.renderer,e=this.ticks,i=e[Object.keys(e)[0]]||{};return this.chart.renderer.fontMetrics(i.label||i.movedLabel||t.box)}unsquish(){let t=this.options.labels,e=t.padding||0,i=this.horiz,s=this.tickInterval,o=this.len/((+!!this.categories+this.max-this.min)/s),r=t.rotation,a=F(.8*this.labelMetrics().h),n=Math.max(this.max-this.min,0),h=function(t){let i=(t+2*e)/(o||1);return(i=i>1?Math.ceil(i):1)*s>n&&t!==1/0&&o!==1/0&&n&&(i=Math.ceil(n/s)),F(i*s)},l=s,d,c=Number.MAX_VALUE,p;if(i){if(!t.staggerLines&&(tl(r)?p=[r]:o=-90&&i<=90)&&(e=(t=h(Math.abs(a/Math.sin(e0*i))))+Math.abs(i/360))u&&(u=i)}),this.maxLabelLength=u,this.autoRotation?u>h&&u>d.h?l.rotation=this.labelRotation:this.labelRotation=0:n&&(p=h),l.rotation&&(p=u>.5*t.chartHeight?.33*t.chartHeight:u,c||(g=1)),this.labelAlign=o.align||this.autoLabelAlign(this.labelRotation||0),this.labelAlign&&(l.align=this.labelAlign),i.forEach(function(t){let e=s[t],i=e?.label,o=r.width,a={};i&&(i.attr(l),e.shortenLabel?e.shortenLabel():p&&!o&&"nowrap"!==r.whiteSpace&&(p<(i.textPxLength||0)||"SPAN"===i.element.tagName)?i.css(q(a,{width:`${p}px`,lineClamp:g})):!i.styles.width||a.width||o||i.css({width:"auto"}),e.rotation=l.rotation)},this),this.tickRotCorr=e.rotCorr(d.b,this.labelRotation||0,0!==this.side)}hasData(){return this.series.some(function(t){return t.hasData()})||this.options.showEmpty&&V(this.min)&&V(this.max)}addTitle(t){let e,i=this.chart.renderer,s=this.horiz,o=this.opposite,r=this.options.title,a=this.chart.styledMode;this.axisTitle||((e=r.textAlign)||(e=(s?{low:"left",middle:"center",high:"right"}:{low:o?"right":"left",middle:"center",high:o?"left":"right"})[r.align]),this.axisTitle=i.text(r.text||"",0,0,r.useHTML).attr({zIndex:7,rotation:r.rotation||0,align:e}).addClass("highcharts-axis-title"),a||this.axisTitle.css(tu(r.style)),this.axisTitle.add(this.axisGroup),this.axisTitle.isNew=!0),a||r.style.width||this.isRadial||this.axisTitle.css({width:this.len+"px"}),this.axisTitle[t?"show":"hide"](t)}generateTick(t){let e=this.ticks;e[t]?e[t].addLabel():e[t]=new eZ(this,t)}createGroups(){let{axisParent:t,chart:e,coll:i,options:s}=this,o=e.renderer,r=(e,r,a)=>o.g(e).attr({zIndex:a}).addClass(`highcharts-${i.toLowerCase()}${r} `+(this.isRadial?`highcharts-radial-axis${r} `:"")+(s.className||"")).add(t);this.axisGroup||(this.gridGroup=r("grid","-grid",s.gridZIndex),this.axisGroup=r("axis","",s.zIndex),this.labelGroup=r("axis-labels","-labels",s.labels.zIndex))}getOffset(){let t=this,{chart:e,horiz:i,options:s,side:o,ticks:r,tickPositions:a,coll:n}=t,h=e.inverted&&!t.isZAxis?[1,0,3,2][o]:o,l=t.hasData(),d=s.title,c=s.labels,p=tl(s.crossing),g=e.axisOffset,u=e.clipOffset,f=[-1,1,1,-1][o],m,x=0,y,b=0,v=0,k,w;if(t.showAxis=m=l||s.showEmpty,t.staggerLines=t.horiz&&c.staggerLines||void 0,t.createGroups(),l||t.isLinked?(a.forEach(function(e){t.generateTick(e)}),t.renderUnsquish(),t.reserveSpaceDefault=0===o||2===o||({1:"left",3:"right"})[o]===t.labelAlign,tb(c.reserveSpace,!p&&null,"center"===t.labelAlign||null,t.reserveSpaceDefault)&&a.forEach(function(t){v=Math.max(r[t].getLabelSize(),v)}),t.staggerLines&&(v*=t.staggerLines),t.labelOffset=v*(t.opposite?-1:1)):tm(r,function(t,e){t.destroy(),delete r[e]}),d?.text&&!1!==d.enabled&&(t.addTitle(m),m&&!p&&!1!==d.reserveSpace&&(t.titleOffset=x=t.axisTitle.getBBox()[i?"height":"width"],b=V(y=d.offset)?0:tb(d.margin,i?5:10))),t.renderLine(),t.offset=f*tb(s.offset,g[o]?g[o]+(s.margin||0):0),t.tickRotCorr=t.tickRotCorr||{x:0,y:0},w=0===o?-t.labelMetrics().h:2===o?t.tickRotCorr.y:0,k=Math.abs(v)+b,v&&(k-=w,k+=f*(i?tb(c.y,t.tickRotCorr.y+f*c.distance):tb(c.x,f*c.distance))),t.axisTitleMargin=tb(y,k),t.getMaxLabelDimensions&&(t.maxLabelDimensions=t.getMaxLabelDimensions(r,a)),"colorAxis"!==n&&u){let e=this.tickSize("tick");g[o]=Math.max(g[o],(t.axisTitleMargin||0)+x+f*t.offset,k,a?.length&&e?e[0]+f*t.offset:0);let i=!t.axisLine||s.offset?0:t.axisLine.strokeWidth()/2;u[h]=Math.max(u[h],i)}Q(this,"afterGetOffset")}getLinePath(t){let e=this.chart,i=this.opposite,s=this.offset,o=this.horiz,r=this.left+(i?this.width:0)+s,a=e.chartHeight-this.bottom-(i?this.height:0)+s;return i&&(t*=-1),e.renderer.crispLine([["M",o?this.left:r,o?a:this.top],["L",o?e.chartWidth-this.right:r,o?a:e.chartHeight-this.bottom]],t)}renderLine(){!this.axisLine&&(this.axisLine=this.chart.renderer.path().addClass("highcharts-axis-line").add(this.axisGroup),this.chart.styledMode||this.axisLine.attr({stroke:this.options.lineColor,"stroke-width":this.options.lineWidth,zIndex:7}))}getTitlePosition(t){let e=this.horiz,i=this.left,s=this.top,o=this.len,r=this.options.title,a=e?i:s,n=this.opposite,h=this.offset,l=r.x,d=r.y,c=this.chart.renderer.fontMetrics(t),p=t?Math.max(t.getBBox(!1,0).height-c.h-1,0):0,g={low:a+(e?0:o),middle:a+o/2,high:a+(e?o:0)}[r.align],u=(e?s+this.height:i)+(e?1:-1)*(n?-1:1)*(this.axisTitleMargin||0)+[-p,p,c.f,-p][this.side],f={x:e?g+l:u+(n?this.width:0)+h+l,y:e?u+d-(n?this.height:0)+h:g+d};return Q(this,"afterGetTitlePosition",{titlePosition:f}),f}renderMinorTick(t,e){let i=this.minorTicks;i[t]||(i[t]=new eZ(this,t,"minor")),e&&i[t].isNew&&i[t].render(null,!0),i[t].render(null,!1,1)}renderTick(t,e,i){let s=this.isLinked,o=this.ticks;(!s||t>=this.min&&t<=this.max||this.grid?.isColumn)&&(o[t]||(o[t]=new eZ(this,t)),i&&o[t].isNew&&o[t].render(e,!0,-1),o[t].render(e))}render(){let t,e,i=this,s=i.chart,o=i.logarithmic,r=s.renderer,a=i.options,n=i.isLinked,h=i.tickPositions,l=i.axisTitle,d=i.ticks,c=i.minorTicks,p=i.alternateBands,g=a.stackLabels,u=a.alternateGridColor,f=a.crossing,m=i.tickmarkOffset,x=i.axisLine,y=i.showAxis,b=e_(r.globalAnimation);if(i.labelEdge.length=0,i.overlap=!1,[d,c,p].forEach(function(t){tm(t,function(t){t.isActive=!1})}),tl(f)){let t=this.isXAxis?s.yAxis[0]:s.xAxis[0],e=[1,-1,-1,1][this.side];if(t){let s=t.toPixels(f,!0);i.horiz&&(s=t.len-s),i.offset=e*s}}if(i.hasData()||n){let r=i.chart.hasRendered&&i.old&&tl(i.old.min);i.minorTickInterval&&!i.categories&&i.getMinorTickPositions().forEach(function(t){i.renderMinorTick(t,r)}),h.length&&(h.forEach(function(t,e){i.renderTick(t,e,r)}),m&&(0===i.min||i.single)&&(d[-1]||(d[-1]=new eZ(i,-1,null,!0)),d[-1].render(-1))),u&&h.forEach(function(r,a){e=void 0!==h[a+1]?h[a+1]+m:i.max-m,a%2==0&&r{let e=this.cross;e||(this.cross=e=h.renderer.path().addClass("highcharts-crosshair highcharts-crosshair-"+(o?"category ":"thin ")+(a.className||"")).attr({zIndex:tb(a.zIndex,2)}).add(),!h.styledMode&&(e.attr({stroke:a.color||(o?tU.parse("#ccd3ff").setOpacity(.25).get():"#cccccc"),"stroke-width":tb(a.width,1)}).css({"pointer-events":"none"}),a.dashStyle&&e.attr({dashstyle:a.dashStyle}))),e.show().animate({d:i},e_(a?.animation)),o&&!a.width&&e.attr({"stroke-width":this.transA}),this.cross&&(this.cross.e=t)},(!l||"hidden"===l.attr("visibility"))&&a.showDelay||0)}else this.hideCrosshair();Q(this,"afterDrawCrosshair",{e:t,point:e})}hideCrosshair(){clearTimeout(this.crossShowTimer),this.cross&&this.cross.hide(),Q(this,"afterHideCrosshair")}update(t,e){let i=this.chart;t=tu(this.userOptions,t),this.destroy(!0),this.init(i,t),i.isDirtyBox=!0,tb(e,!0)&&i.redraw()}remove(t){let e=this.chart,i=this.coll,s=this.series,o=s.length;for(;o--;)s[o]&&s[o].remove(!1);K(e.axes,this),K(e[i]||[],this),e.orderItems(i),this.destroy(),e.isDirtyBox=!0,tb(t,!0)&&e.redraw()}setTitle(t,e){this.update({title:t},e)}setCategories(t,e){this.update({categories:t},e)}}e2.keepProps=["coll","extKey","hcEvents","len","names","series","userMax","userMin"],!function(t){function e(){return this.chart.time.getTimeTicks.apply(this.chart.time,arguments)}function i(){if("datetime"!==this.type){this.dateTime=void 0;return}this.dateTime||(this.dateTime=new s(this))}t.compose=function(t){return t.keepProps.includes("dateTime")||(t.keepProps.push("dateTime"),t.prototype.getTimeTicks=e,R(t,"afterSetType",i)),t};class s{constructor(t){this.axis=t}normalizeTimeTickInterval(t,e){let i=e||[["millisecond",[1,2,5,10,20,25,50,100,200,500]],["second",[1,2,5,10,15,30]],["minute",[1,2,5,10,15,30]],["hour",[1,2,3,4,6,8,12]],["day",[1,2]],["week",[1,2]],["month",[1,2,3,4,6]],["year",null]],s=i[i.length-1],o=tD[s[0]],r=s[1],a,n;for(a=0;a=.5)t=Math.round(t),n=o.getLinearTickPositions(t,e,i);else if(t>=.08){let o,r,a,h,l,d,c,p=Math.floor(e);for(o=t>.3?[1,2,4]:t>.15?[1,2,4,6,8]:[1,2,3,4,5,6,7,8,9],r=p;re&&(!s||d<=i)&&void 0!==d&&n.push(d),d>i&&(c=!0),d=l}else{let h=this.lin2log(e),l=this.lin2log(i),d=s?o.getMinorTickInterval():a.tickInterval,c=a.tickPixelInterval/(s?5:1),p=s?r/o.tickPositions.length:r;t=tf(t=tb("auto"===d?null:d,this.minorAutoInterval,(l-h)*c/(p||1))),n=o.getLinearTickPositions(t,h,l).map(this.log2lin),s||(this.minorAutoInterval=t/5)}return s||(o.tickInterval=t),n}lin2log(t){return Math.pow(10,t)}log2lin(t){return Math.log(t)/Math.LN10}}t.Additions=s}(k||(k={}));let e5=k;!function(t){let e;function i(t){return this.addPlotBandOrLine(t,"plotBands")}function s(t,i){let s=this.userOptions,o=new e(this,t);if(this.visible&&(o=o.render()),o){if(this._addedPlotLB||(this._addedPlotLB=!0,(s.plotLines||[]).concat(s.plotBands||[]).forEach(t=>{this.addPlotBandOrLine(t)})),i){let e=s[i]||[];e.push(t),s[i]=e}this.plotLinesAndBands.push(o)}return o}function o(t){return this.addPlotBandOrLine(t,"plotLines")}function r(t,e,i){i=i||this.options;let s=this.getPlotLinePath({value:e,force:!0,acrossPanes:i.acrossPanes}),o=[],r=this.horiz,a=!tl(this.min)||!tl(this.max)||tthis.max&&e>this.max,n=this.getPlotLinePath({value:t,force:!0,acrossPanes:i.acrossPanes}),h,l=1,d;if(n&&s)for(a&&(d=n.toString()===s.toString(),l=0),h=0;h{let t=[];for(let e of this.axes)for(let{label:i,options:s}of e.plotLinesAndBands)i&&!s?.label?.allowOverlap&&t.push(i);return t})}),e6.compose(e9,e)}constructor(t,e){this.axis=t,this.options=e,this.id=e.id}render(){Q(this,"render");let{axis:t,options:e}=this,{horiz:i,logarithmic:s}=t,{color:o,events:r,zIndex:a=0}=e,{renderer:n,time:h}=t.chart,l={},d=h.parse(e.to),c=h.parse(e.from),p=h.parse(e.value),g=e.borderWidth,u=e.label,{label:f,svgElem:m}=this,x=[],y,b=V(c)&&V(d),v=V(p),k=!m,w={class:"highcharts-plot-"+(b?"band ":"line ")+(e.className||"")},M=b?"bands":"lines";if(!t.chart.styledMode&&(v?(w.stroke=o||"#999999",w["stroke-width"]=tb(e.width,1),e.dashStyle&&(w.dashstyle=e.dashStyle)):b&&(w.fill=o||"#e6e9ff",g&&(w.stroke=e.borderColor,w["stroke-width"]=g))),l.zIndex=a,M+="-"+a,(y=t.plotLinesAndBandsGroups[M])||(t.plotLinesAndBandsGroups[M]=y=n.g("plot-"+M).attr(l).add()),m||(this.svgElem=m=n.path().attr(w).add(y)),V(p))x=t.getPlotLinePath({value:s?.log2lin(p)??p,lineWidth:m.strokeWidth(),acrossPanes:e.acrossPanes});else{if(!(V(c)&&V(d)))return;x=t.getPlotBandPath(s?.log2lin(c)??c,s?.log2lin(d)??d,e)}return!this.eventsAdded&&r&&(tm(r,(t,e)=>{m?.on(e,t=>{r[e].apply(this,[t,this])})}),this.eventsAdded=!0),(k||!m.d)&&x?.length?m.attr({d:x}):m&&(x?(m.show(),m.animate({d:x})):m.d&&(m.hide(),f&&(this.label=f=f.destroy()))),u&&(V(u.text)||V(u.formatter))&&x?.length&&t.width>0&&t.height>0&&!x.isFlat?(u=tu({align:i&&b?"center":void 0,x:i?!b&&4:10,verticalAlign:!i&&b?"middle":void 0,y:i?b?16:10:b?6:-4,rotation:i&&!b?90:0,...b?{inside:!0}:{}},u),this.renderLabel(u,x,b,a)):f&&f.hide(),this}renderLabel(t,e,i,s){let o=this.axis,r=o.chart.renderer,a=t.inside,n=this.label;n||(this.label=n=r.text(this.getLabelText(t),0,0,t.useHTML).attr({align:t.textAlign||t.align,rotation:t.rotation,class:"highcharts-plot-"+(i?"band":"line")+"-label "+(t.className||""),zIndex:s}),o.chart.styledMode||n.css(tu({color:o.chart.options.title?.style?.color,fontSize:"0.8em",textOverflow:i&&!a?"":"ellipsis"},t.style)),n.add());let h=e.xBounds||[e[0][1],e[1][1],i?e[2][1]:e[0][1]],l=e.yBounds||[e[0][2],e[1][2],i?e[2][2]:e[0][2]],d=W(h),c=W(l),p=H(h)-d;n.align(t,!1,{x:d,y:c,width:p,height:H(l)-c}),n.alignAttr.y-=r.fontMetrics(n).b,(!n.alignValue||"left"===n.alignValue||V(a))&&n.css({width:(t.style?.width||(i&&a?p:90===n.rotation?o.height-(n.alignAttr.y-o.top):(t.clip?o.width+o.left:o.chart.chartWidth)-n.alignAttr.x))+"px"}),n.show(!0)}getLabelText(t){return V(t.formatter)?t.formatter.call(this,this):t.text}destroy(){K(this.axis.plotLinesAndBands,this),delete this.axis,U(this)}}let{animObject:e4}=tQ,{format:e8}=es,{composed:e7,dateFormats:it,doc:ie,isSafari:ii}=B,{distribute:is}=er,io=t=>{clearTimeout(t.hideTimer),clearTimeout(t.showTimer)};class ir{constructor(t,e,i){this.allowShared=!0,this.crosshairs=[],this.distance=0,this.isHidden=!0,this.isSticky=!1,this.options={},this.outside=!1,this.chart=t,this.init(t,e),this.pointer=i}bodyFormatter(t){return t.map(t=>{let e=t.series.tooltipOptions,i=t.formatPrefix||"point";return(e[i+"Formatter"]||t.tooltipFormatter).call(t,e[i+"Format"]||"",t)})}cleanSplit(t){this.chart.series.forEach(function(e){let i=e?.tt;i&&(!i.isActive||t?e.tt=i.destroy():i.isActive=!1)})}defaultFormatter(t){let e,i=this.points||tT(this);return(e=(e=[t.headerFooterFormatter(i[0])]).concat(t.bodyFormatter(i))).push(t.headerFooterFormatter(i[0],!0)),e}destroy(){this.label&&(this.label=this.label.destroy()),this.split&&(this.cleanSplit(!0),this.tt&&(this.tt=this.tt.destroy())),this.renderer&&(this.renderer=this.renderer.destroy(),Z(this.container)),ta(this.hideTimer),io(this)}getAnchor(t,e){let i,{chart:s,pointer:o}=this,r=s.inverted,a=s.plotTop,n=s.plotLeft;if(t=tT(t),t[0].series?.yAxis&&!t[0].series.yAxis.options.reversedStacks&&(t=t.slice().reverse()),this.followPointer&&e)void 0===e.chartX&&(e=o.normalize(e)),i=[e.chartX-n,e.chartY-a];else if(t[0].tooltipPos)i=t[0].tooltipPos;else{let s=0,o=0;t.forEach(function(t){let e=t.pos(!0);e&&(s+=e[0],o+=e[1])}),s/=t.length,o/=t.length,this.shared&&t.length>1&&e&&(r?s=e.chartX:o=e.chartY),i=[s-n,o-a]}let h={point:t[0],ret:i};return Q(this,"getAnchor",h),h.ret.map(Math.round)}getClassName(t,e,i){let s=this.options,o=t.series,r=o.options;return[s.className,"highcharts-label",i&&"highcharts-tooltip-header",e?"highcharts-tooltip-box":"highcharts-tooltip",!i&&"highcharts-color-"+tb(t.colorIndex,o.colorIndex),r?.className].filter(td).join(" ")}getLabel({anchorX:t,anchorY:e}={anchorX:0,anchorY:0}){let i=this,s=this.chart.styledMode,o=this.options,r=this.split&&this.allowShared,a=this.container,n=this.chart.renderer;if(this.label){let t=!this.label.hasClass("highcharts-label");(!r&&t||r&&!t)&&this.destroy()}if(!this.label){if(this.outside){let t=this.chart,e=t.options.chart.style,i=eo.getRendererType();this.container=a=B.doc.createElement("div"),a.className="highcharts-tooltip-container "+(t.renderTo.className.match(/(highcharts[a-zA-Z0-9-]+)\s?/gm)||""),$(a,{position:"absolute",top:"1px",pointerEvents:"none",zIndex:Math.max(this.options.style.zIndex||0,(e?.zIndex||0)+3)}),this.renderer=n=new i(a,0,0,e,void 0,void 0,n.styledMode)}if(r?this.label=n.g("tooltip"):(this.label=n.label("",t,e,o.shape||"callout",void 0,void 0,o.useHTML,void 0,"tooltip").attr({padding:o.padding,r:o.borderRadius}),s||this.label.attr({fill:o.backgroundColor,"stroke-width":o.borderWidth||0}).css(o.style).css({pointerEvents:o.style.pointerEvents||(this.shouldStickOnContact()?"auto":"none")})),i.outside){let t=this.label;[t.xSetter,t.ySetter].forEach((e,s)=>{t[s?"ySetter":"xSetter"]=o=>{e.call(t,i.distance),t[s?"y":"x"]=o,a&&(a.style[s?"top":"left"]=`${o}px`)}})}this.label.attr({zIndex:8}).shadow(o.shadow??!o.fixed).add()}return a&&!a.parentElement&&B.doc.body.appendChild(a),this.label}getPlayingField(){let{body:t,documentElement:e}=ie,{chart:i,distance:s,outside:o}=this;return{width:o?Math.max(t.scrollWidth,e.scrollWidth,t.offsetWidth,e.offsetWidth,e.clientWidth)-2*s-2:i.chartWidth,height:o?Math.max(t.scrollHeight,e.scrollHeight,t.offsetHeight,e.offsetHeight,e.clientHeight):i.chartHeight}}getPosition(t,e,i){let{distance:s,chart:o,outside:r,pointer:a}=this,{inverted:n,plotLeft:h,plotTop:l,polar:d}=o,{plotX:c=0,plotY:p=0}=i,g={},u=n&&i.h||0,{height:f,width:m}=this.getPlayingField(),x=a.getChartPosition(),y=i=>{let a="x"===i;return[i,a?m:f,a?t:e].concat(r?[a?t*x.scaleX:e*x.scaleY,a?x.left-s+(c+h)*x.scaleX:x.top-s+(p+l)*x.scaleY,0,a?m:f]:[a?t:e,a?c+h:p+l,a?h:l,a?h+o.plotWidth:l+o.plotHeight])},b=y("y"),v=y("x"),k,w=!!i.negative;!d&&o.hoverSeries?.yAxis?.reversed&&(w=!w);let M=!this.followPointer&&tb(i.ttBelow,!d&&!n===w),S=function(t,e,i,o,a,n,h){let l=r?"y"===t?s*x.scaleY:s*x.scaleX:s,d=(i-o)/2,c=oe?m:m+u)}},T=function(t,e,i,o,r){if(re-s)return!1;re-o/2?g[t]=e-o-2:g[t]=r-i/2},C=function(t){[b,v]=[v,b],k=t},A=()=>{!1!==S.apply(0,b)?!1!==T.apply(0,v)||k||(C(!0),A()):k?g.x=g.y=0:(C(!0),A())};return(n&&!d||this.len>1)&&C(),A(),r&&(g.x-=x.left,g.y-=x.top),g}getFixedPosition(t,e,i){let s=i.series,{chart:o,options:r,split:a}=this,n=r.position,h=n.relativeTo,l=r.shared||s?.yAxis?.isRadial&&("pane"===h||!h)?"plotBox":h,d="chart"===l?o.renderer:o[l]||o.getClipBox(s,!0);return{x:d.x+(d.width-t)*tt(n.align)+n.x,y:d.y+(d.height-e)*tt(n.verticalAlign)+(!a&&n.y||0)}}hide(t){let e=this;io(this),t=tb(t,this.options.hideDelay),this.isHidden||(this.hideTimer=tA(function(){let i=e.getLabel();e.getLabel().animate({opacity:0},{duration:t?150:t,complete:()=>{i.hide(),e.container&&e.container.remove()}}),e.isHidden=!0},t))}init(t,e){this.chart=t,this.options=e,this.crosshairs=[],this.isHidden=!0,this.split=e.split&&!t.inverted&&!t.polar,this.shared=e.shared||this.split,this.outside=tb(e.outside,!!(t.scrollablePixelsX||t.scrollablePixelsY))}shouldStickOnContact(t){return!!(!this.followPointer&&this.options.stickOnContact&&(!t||this.pointer.inClass(t.target,"highcharts-tooltip")))}move(t,e,i,s){let{followPointer:o,options:r}=this,a=e4(!o&&!this.isHidden&&!r.fixed&&r.animation),n=o||(this.len||0)>1,h={x:t,y:e};n?h.anchorX=h.anchorY=NaN:(h.anchorX=i,h.anchorY=s),a.step=()=>this.drawTracker(),this.getLabel().animate(h,a)}refresh(t,e){let i=this,{chart:s,options:o,pointer:r,shared:a}=this,n=tT(t),h=n[0],l=o.format,d=o.formatter||i.defaultFormatter,c=s.styledMode,p=i.allowShared;if(!o.enabled||!h.series)return;io(this),i.allowShared=!(!tc(t)&&t.series&&t.series.noSharedTooltip),p=p&&!i.allowShared,i.followPointer=!i.split&&h.series.tooltipOptions.followPointer;let g=i.getAnchor(t,e),u=g[0],f=g[1];a&&i.allowShared&&(r.applyInactiveState(n),n.forEach(t=>t.setState("hover")),h.points=n),this.len=n.length;let m=td(l)?e8(l,h,s):d.call(h,i,h);h.points=void 0;let x=h.series;this.distance=tb(x.tooltipOptions.distance,16),!1===m?this.hide():this.showTimer=tA(()=>{if(i.split&&i.allowShared)i.renderSplit(m,n);else{let t=u,a=f;if(e&&r.isDirectTouch&&(t=e.chartX-s.plotLeft,a=e.chartY-s.plotTop),!(s.polar||!1===x.options.clip||n.some(e=>r.isDirectTouch||e.series.shouldShowTooltip(t,a))))return void i.hide();{let t=i.getLabel(p&&i.tt||{});(!o.style.width||c)&&t.css({width:(this.outside?this.getPlayingField():s.spacingBox).width-2*o.padding+"px"}),t.attr({class:i.getClassName(h),text:tc(m)?m.join(""):m}),this.outside&&t.attr({x:G(t.x||0,0,this.getPlayingField().width-(t.width||0)-1)}),c||t.attr({stroke:o.borderColor||h.color||x.color||"#666666"}),i.updatePosition({plotX:u,plotY:f,negative:h.negative,ttBelow:h.ttBelow,series:x,h:g[2]||0})}}i.isHidden&&i.label&&i.label.attr({opacity:1}).show(),i.isHidden=!1},i.isHidden&&o.showDelay||0),Q(this,"refresh")}renderSplit(t,e){let i=this,{chart:s,chart:{chartWidth:o,chartHeight:r,plotHeight:a,plotLeft:n,plotTop:h,scrollablePixelsY:l=0,scrollablePixelsX:d,styledMode:c},distance:p,options:g,options:{fixed:u,position:f,positioner:m},pointer:x}=i,{scrollLeft:y=0,scrollTop:b=0}=s.scrollablePlotArea?.scrollingContainer||{},v=i.outside&&"number"!=typeof d?ie.documentElement.getBoundingClientRect():{left:y,right:y+o,top:b,bottom:b+r},k=i.getLabel(),w=this.renderer||s.renderer,M=!!s.xAxis[0]?.opposite,{left:S,top:T}=x.getChartPosition(),C=m||u,A=h+b,P=0,L=a-l,O=function(t,e,s,o,r=[0,0],a=!0){let n,h;if(s.isHeader)h=M?0:L,n=G(r[0]-t/2,v.left,v.right-t-(i.outside?S:0));else if(u&&s){let o=i.getFixedPosition(t,e,s);n=o.x,h=o.y-A}else h=r[1]-A,n=G(n=a?r[0]-t-p:r[0]+p,a?n:v.left,v.right);return{x:n,y:h}};td(t)&&(t=[!1,t]);let E=t.slice(0,e.length+1).reduce(function(t,s,o){if(!1!==s&&""!==s){let r=e[o-1]||{isHeader:!0,plotX:e[0].plotX,plotY:a,series:{}},l=r.isHeader,d=l?i:r.series,f=d.tt=function(t,e,s){let o=t,{isHeader:r,series:a}=e,n=a.tooltipOptions||g;if(!o){let t={padding:n.padding,r:n.borderRadius};c||(t.fill=n.backgroundColor,t["stroke-width"]=n.borderWidth??(u&&!r?0:1)),o=w.label("",0,0,n[r?"headerShape":"shape"]||(u&&!r?"rect":"callout"),void 0,void 0,n.useHTML).addClass(i.getClassName(e,!0,r)).attr(t).add(k)}return o.isActive=!0,o.attr({text:s}),c||o.css(n.style).attr({stroke:n.borderColor||e.color||a.color||"#333333"}),o}(d.tt,r,s.toString()),x=f.getBBox(),y=x.width+f.strokeWidth();l&&(P=x.height,L+=P,M&&(A-=P));let{anchorX:b,anchorY:S}=function(t){let e,i,{isHeader:s,plotX:o=0,plotY:r=0,series:l}=t;if(s)e=Math.max(n+o,n),i=h+a/2;else{let{xAxis:t,yAxis:s}=l;e=t.pos+G(o,-p,t.len+p),l.shouldShowTooltip(0,s.pos-h+r,{ignoreX:!0})&&(i=s.pos+r)}return{anchorX:e=G(e,v.left-p,v.right+p),anchorY:i}}(r);if("number"==typeof S){let e=x.height+1,s=(m||O).call(i,y,e,r,i,[b,S]);t.push({align:C?0:void 0,anchorX:b,anchorY:S,boxWidth:y,point:r,rank:tb(s.rank,+!!l),size:e,target:s.y,tt:f,x:s.x})}else f.isActive=!1}return t},[]);!C&&E.some(t=>{let{outside:e}=i,s=(e?S:0)+t.anchorX;return ss})&&(E=E.map(t=>{let{x:e,y:i}=O.call(this,t.boxWidth,t.size,t.point,void 0,[t.anchorX,t.anchorY],!1);return q(t,{target:i,x:e})})),i.cleanSplit(),is(E,L);let I={left:S,right:S};E.forEach(function(t){let{x:e,boxWidth:s,isHeader:o}=t;!o&&(i.outside&&S+eI.right&&(I.right=S+e))}),E.forEach(function(t){let{x:e,anchorX:s,anchorY:o,pos:r,point:{isHeader:a}}=t,n={visibility:void 0===r?"hidden":"inherit",x:e,y:(r||0)+A+(u&&f.y||0),anchorX:s,anchorY:o};if(i.outside&&e0&&(a||(n.x=e+t,n.anchorX=s+t),a&&(n.x=(I.right-I.left)/2,n.anchorX=s+t))}t.tt.attr(n)});let{container:D,outside:B,renderer:N}=i;if(B&&D&&N){let{width:t,height:e,x:i,y:s}=k.getBBox();N.setSize(t+i,e+s,!1),D.style.left=I.left+"px",D.style.top=T+"px"}ii&&k.attr({opacity:1===k.opacity?.999:1})}drawTracker(){let t=this;if(!this.shouldStickOnContact()){t.tracker&&(t.tracker=t.tracker.destroy());return}let e=t.chart,i=t.label,s=t.shared?e.hoverPoints:e.hoverPoint;if(!i||!s)return;let o={x:0,y:0,width:0,height:0},r=this.getAnchor(s),a=i.getBBox();r[0]+=e.plotLeft-(i.translateX||0),r[1]+=e.plotTop-(i.translateY||0),o.x=Math.min(0,r[0]),o.y=Math.min(0,r[1]),o.width=r[0]<0?Math.max(Math.abs(r[0]),a.width-r[0]):Math.max(Math.abs(r[0]),a.width),o.height=r[1]<0?Math.max(Math.abs(r[1]),a.height-Math.abs(r[1])):Math.max(Math.abs(r[1]),a.height),t.tracker?t.tracker.attr(o):(t.tracker=i.renderer.rect(o).addClass("highcharts-tracker").add(i),R(t.tracker.element,"mouseenter",()=>io(t)),e.styledMode||t.tracker.attr({fill:"rgba(0,0,0,0)"}))}styledModeFormat(t){return t.replace('style="font-size: 0.8em"','class="highcharts-header"').replace(/style="color:{(point|series)\.color}"/g,'class="highcharts-color-{$1.colorIndex} {series.options.className} {point.options.className}"')}headerFooterFormatter(t,e){let i=t.series,s=i.tooltipOptions,o=i.xAxis,r=o?.dateTime,a={isFooter:e,point:t},n=s.xDateFormat||"",h=s[e?"footerFormat":"headerFormat"];return Q(this,"headerFormatter",a,function(e){if(r&&!n&&tl(t.key)&&(n=r.getXDateFormat(t.key,s.dateTimeLabelFormats)),r&&n){if(tg(n)){let t=n;it[0]=e=>i.chart.time.dateFormat(t,e),n="%0"}(t.tooltipDateKeys||["key"]).forEach(t=>{h=h.replace(RegExp("point\\."+t+"([ \\)}])"),`(point.${t}:${n})$1`)})}i.chart.styledMode&&(h=this.styledModeFormat(h)),e.text=e8(h,t,this.chart)}),a.text||""}update(t){this.destroy(),this.init(this.chart,tu(!0,this.options,t))}updatePosition(t){let{chart:e,container:i,distance:s,options:o,pointer:r,renderer:a}=this,{height:n=0,width:h=0}=this.getLabel(),{fixed:l,positioner:d}=o,{left:c,top:p,scaleX:g,scaleY:u}=r.getChartPosition(),f=(d||l&&this.getFixedPosition||this.getPosition).call(this,h,n,t,this),m=B.doc,x=(t.plotX||0)+e.plotLeft,y=(t.plotY||0)+e.plotTop,b;if(a&&i){let{scrollLeft:t=0,scrollTop:r=0}=e.scrollablePlotArea?.scrollingContainer||{};f.x+=t+c,f.y+=r+p,b=(o.borderWidth||0)+2*s+2,a.setSize(G(h+b,0,m.documentElement.clientWidth)-1,n+b,!1),(1!==g||1!==u)&&($(i,{transform:`scale(${g}, ${u})`}),x*=g,y*=u),x+=c-f.x,y+=p-f.y}this.move(Math.round(f.x),Math.round(f.y||0),x,y)}}(l=ir||(ir={})).compose=function(t){tk(e7,"Core.Tooltip")&&R(t,"afterInit",function(){let t=this.chart;t.options.tooltip&&(t.tooltip=new l(t,t.options.tooltip,this))})};let ia=ir,{animObject:ih}=tQ,{defaultOptions:il}=tY,{format:id}=es;class ic{constructor(t,e,i){this.formatPrefix="point",this.visible=!0,this.point=this,this.series=t,this.applyOptions(e,i),this.id??(this.id=tB()),this.resolveColor(),this.dataLabelOnNull??(this.dataLabelOnNull=t.options.nullInteraction),t.chart.pointCount++,this.category=t.xAxis?.categories?.[this.x]??this.x,this.key=this.name??this.category,Q(this,"afterInit")}animateBeforeDestroy(){let t=this,e={x:t.startXPos,opacity:0},i=t.getGraphicalProps();i.singular.forEach(function(i){t[i]=t[i].animate("dataLabel"===i?{x:t[i].startXPos,y:t[i].startYPos,opacity:0}:e)}),i.plural.forEach(function(e){t[e].forEach(function(e){e.element&&e.animate(q({x:t.startXPos},e.startYPos?{x:e.startXPos,y:e.startYPos}:{}))})})}applyOptions(t,e){let i=this.series,s=i.options.pointValKey||i.pointValKey;return q(this,t=ic.prototype.optionsToObject.call(this,t)),this.options?this.options=i.chart.options.chart.allowMutatingData?q(this.options,t):tu(this.options,t):this.options=t,t.group&&delete this.group,t.dataLabels&&delete this.dataLabels,s&&(this.y=ic.prototype.getNestedProperty.call(this,s)),this.selected&&(this.state="select"),"name"in this&&void 0===e&&i.xAxis&&i.xAxis.hasNames&&(this.x=i.xAxis.nameToX(this)),void 0===this.x&&i?this.x=e??i.autoIncrement():tl(t.x)&&i.options.relativeXValue?this.x=i.autoIncrement(t.x):"string"==typeof this.x&&(e??(e=i.chart.time.parse(this.x)),tl(e)&&(this.x=e)),this.isNull=this.isValid&&!this.isValid(),this.formatPrefix=this.isNull?"null":"point",this}destroy(){if(!this.destroyed){let t=this,e=t.series,i=e.chart,s=e.options.dataSorting,o=i.hoverPoints,r=ih(t.series.chart.renderer.globalAnimation),a=()=>{for(let e in(t.graphic||t.graphics||t.dataLabel||t.dataLabels)&&(tS(t),t.destroyElements()),t)delete t[e]};t.legendItem&&i.legend.destroyItem(t),o&&(t.setState(),K(o,t),o.length||(i.hoverPoints=null)),t===i.hoverPoint&&t.onMouseOut(),s?.enabled?(this.animateBeforeDestroy(),tA(a,r.duration)):a(),i.pointCount--}this.destroyed=!0}destroyElements(t){let e=this,i=e.getGraphicalProps(t);i.singular.forEach(function(t){e[t]=e[t].destroy()}),i.plural.forEach(function(t){e[t].forEach(function(t){t?.element&&t.destroy()}),delete e[t]})}firePointEvent(t,e,i){let s=this,o=this.series.options;s.manageEvent(t),"click"===t&&o.allowPointSelect&&(i=function(t){!s.destroyed&&s.select&&s.select(null,t.ctrlKey||t.metaKey||t.shiftKey)}),Q(s,t,e,i)}getClassName(){return"highcharts-point"+(this.selected?" highcharts-point-select":"")+(this.negative&&!1!==this.series.options.negativeColor?" highcharts-negative":"")+(this.isNull?" highcharts-null-point":"")+(void 0!==this.colorIndex?" highcharts-color-"+this.colorIndex:"")+(this.options.className?" "+this.options.className:"")+(this.zone?.className?" "+this.zone.className.replace("highcharts-negative",""):"")}getGraphicalProps(t){let e,i,s=this,o=[],r={singular:[],plural:[]};for((t=t||{graphic:1,dataLabel:1}).graphic&&o.push("graphic","connector"),t.dataLabel&&o.push("dataLabel","dataLabelPath","dataLabelUpper"),i=o.length;i--;)s[e=o[i]]&&r.singular.push(e);return["graphic","dataLabel"].forEach(function(e){let i=e+"s";t[e]&&s[i]&&r.plural.push(i)}),r}getNestedProperty(t){if(t)return 0===t.indexOf("custom.")?ts(t,this.options):this[t]}getZone(){let t=this.series,e=t.zones,i=t.zoneAxis||"y",s,o=0;for(s=e[0];this[i]>=s.value;)s=e[++o];return this.nonZonedColor||(this.nonZonedColor=this.color),s?.color&&!this.options.color?this.color=s.color:this.color=this.nonZonedColor,s}hasNewShapeType(){return(this.graphic&&(this.graphic.symbolName||this.graphic.element.nodeName))!==this.shapeType}isValid(){return(tl(this.x)||this.x instanceof Date)&&tl(this.y)}optionsToObject(t){let e=this.series,i=e.options.keys,s=i||e.pointArrayMap||["y"],o=s.length,r={},a,n=0,h=0;if(tl(t)||null===t)r[s[0]]=t;else if(tc(t))for(!i&&t.length>o&&("string"==(a=typeof t[0])?e.xAxis?.dateTime?r.x=e.chart.time.parse(t[0]):r.name=t[0]:"number"===a&&(r.x=t[0]),n++);h0?ic.prototype.setNestedProperty(r,t[n],s[h]):r[s[h]]=t[n]),n++,h++;else"object"==typeof t&&(r=t,t.dataLabels&&(e.hasDataLabels=()=>!0),t.marker&&(e._hasPointMarkers=!0));return r}pos(t,e=this.plotY){if(!this.destroyed){let{plotX:i,series:s}=this,{chart:o,xAxis:r,yAxis:a}=s,n=0,h=0;if(tl(i)&&tl(e))return t&&(n=r?r.pos:o.plotLeft,h=a?a.pos:o.plotTop),o.inverted&&r&&a?[a.len-e+h,r.len-i+n]:[i+n,e+h]}}resolveColor(){let t=this.series,e=t.chart.options.chart,i=t.chart.styledMode,s,o,r=e.colorCount,a;delete this.nonZonedColor,t.options.colorByPoint?(i||(s=(o=t.options.colors||t.chart.options.colors)[t.colorCounter],r=o.length),a=t.colorCounter,t.colorCounter++,t.colorCounter===r&&(t.colorCounter=0)):(i||(s=t.color),a=t.colorIndex),this.colorIndex=tb(this.options.colorIndex,a),this.color=tb(this.options.color,s)}setNestedProperty(t,e,i){return i.split(".").reduce(function(t,i,s,o){let r=o.length-1===s;return t[i]=r?e:tg(t[i],!0)?t[i]:{},t[i]},t),t}shouldDraw(){return!this.isNull}tooltipFormatter(t){let{chart:e,pointArrayMap:i=["y"],tooltipOptions:s}=this.series,{valueDecimals:o="",valuePrefix:r="",valueSuffix:a=""}=s;return e.styledMode&&(t=e.tooltip?.styledModeFormat(t)||t),i.forEach(e=>{e="{point."+e,(r||a)&&(t=t.replace(RegExp(e+"}","g"),r+e+"}"+a)),t=t.replace(RegExp(e+"}","g"),e+":,."+o+"f}")}),id(t,this,e)}update(t,e,i,s){let o,r=this,a=r.series,n=r.graphic,h=a.chart,l=a.options,d=l.data;function c(){r.applyOptions(t);let s=n&&r.hasMockGraphic,c=null===r.y?!s:s;n&&c&&(r.graphic=n.destroy(),delete r.hasMockGraphic),tg(t,!0)&&(n?.element&&t&&t.marker&&void 0!==t.marker.symbol&&(r.graphic=n.destroy()),t?.dataLabels&&r.dataLabel&&(r.dataLabel=r.dataLabel.destroy())),o=r.index;let p={};for(let t of a.dataColumnKeys())p[t]=r[t];a.dataTable.setRow(p,o),d&&!a.processedData&&(d[o]=tg(d[o],!0)||tg(t,!0)?r.options:t??d[o]),a.isDirty=a.isDirtyData=!0,!a.fixedBox&&a.hasCartesianSeries&&(h.isDirtyBox=!0),"point"===l.legendType&&(h.isDirtyLegend=!0),e&&h.redraw(i)}e=tb(e,!0),!1===s?c():r.firePointEvent("update",{options:t},c)}remove(t,e){this.series.removePoint(this.series.data.indexOf(this),t,e)}select(t,e){let i=this,s=i.series,o=s.chart;t=tb(t,!i.selected),this.selectedStaging=t,i.firePointEvent(t?"select":"unselect",{accumulate:e},function(){i.selected=i.options.selected=t,s.options.data[s.data.indexOf(i)]=i.options,i.setState(t&&"select"),e||o.getSelectedPoints().forEach(function(t){let e=t.series;t.selected&&t!==i&&(t.selected=t.options.selected=!1,e.options.data[e.data.indexOf(t)]=t.options,t.setState(o.hoverPoints&&e.options.inactiveOtherPoints?"inactive":""),t.firePointEvent("unselect"))})}),delete this.selectedStaging}onMouseOver(t){let{inverted:e,pointer:i}=this.series.chart;i&&(t=t?i.normalize(t):i.getChartCoordinatesFromPoint(this,e),i.runPointActions(t,this))}onMouseOut(){let t=this.series.chart;this.firePointEvent("mouseOut"),this.series.options.inactiveOtherPoints||(t.hoverPoints||[]).forEach(function(t){t.setState()}),t.hoverPoints=t.hoverPoint=null}manageEvent(t){let e=tu(this.series.options.point,this.options),i=e.events?.[t];tp(i)&&(!this.hcEvents?.[t]||this.hcEvents?.[t]?.map(t=>t.fn).indexOf(i)===-1)?(this.importedUserEvent?.(),this.importedUserEvent=R(this,t,i),this.hcEvents&&(this.hcEvents[t].userEvent=!0)):this.importedUserEvent&&!i&&this.hcEvents?.[t]&&this.hcEvents?.[t].userEvent&&(tS(this,t),delete this.hcEvents[t],Object.keys(this.hcEvents)||delete this.importedUserEvent)}setState(t,e){let i=this.series,s=this.state,o=i.options.states[t||"normal"]||{},r=il.plotOptions[i.type].marker&&i.options.marker,a=r&&!1===r.enabled,n=r?.states?.[t||"normal"]||{},h=!1===n.enabled,l=this.marker||{},d=i.chart,c=r&&i.markerAttribs,p=i.halo,g,u,f,m=i.stateMarkerGraphic,x;if((t=t||"")===this.state&&!e||this.selected&&"select"!==t||!1===o.enabled||t&&(h||a&&!1===n.enabled)||t&&l.states&&l.states[t]&&!1===l.states[t].enabled)return;if(this.state=t,c&&(g=i.markerAttribs(this,t)),this.graphic&&!this.hasMockGraphic){if(s&&this.graphic.removeClass("highcharts-point-"+s),t&&this.graphic.addClass("highcharts-point-"+t),!d.styledMode){u=i.pointAttribs(this,t),f=tb(d.options.chart.animation,o.animation);let e=u.opacity;i.options.inactiveOtherPoints&&tl(e)&&(this.dataLabels||[]).forEach(function(t){t&&!t.hasClass("highcharts-data-label-hidden")&&(t.animate({opacity:e},f),t.connector&&t.connector.animate({opacity:e},f))}),this.graphic.animate(u,f)}g&&this.graphic.animate(g,tb(d.options.chart.animation,n.animation,r.animation)),m&&m.hide()}else t&&n&&(x=l.symbol||i.symbol,m&&m.currentSymbol!==x&&(m=m.destroy()),g&&(m?m[e?"animate":"attr"]({x:g.x,y:g.y}):x&&(i.stateMarkerGraphic=m=d.renderer.symbol(x,g.x,g.y,g.width,g.height,tu(r,n)).add(i.markerGroup),m.currentSymbol=x)),!d.styledMode&&m&&"inactive"!==this.state&&m.attr(i.pointAttribs(this,t))),m&&(m[t&&this.isInside?"show":"hide"](),m.element.point=this,m.addClass(this.getClassName(),!0));let y=o.halo,b=this.graphic||m,v=b?.visibility||"inherit";y?.size&&b&&"hidden"!==v&&!this.isCluster?(p||(i.halo=p=d.renderer.path().add(b.parentGroup)),p.show()[e?"animate":"attr"]({d:this.haloPath(y.size)}),p.attr({class:"highcharts-halo highcharts-color-"+tb(this.colorIndex,i.colorIndex)+(this.className?" "+this.className:""),visibility:v,zIndex:-1}),p.point=this,d.styledMode||p.attr(q({fill:this.color||i.color,"fill-opacity":y.opacity},t6.filterUserAttributes(y.attributes||{})))):p?.point?.haloPath&&!p.point.destroyed&&p.animate({d:p.point.haloPath(0)},null,p.hide),Q(this,"afterSetState",{state:t})}haloPath(t){let e=this.pos();return e?this.series.chart.renderer.symbols.circle(j(e[0],1)-t,e[1]-t,2*t,2*t):[]}}let ip=ic,{parse:ig}=tU,{charts:iu,composed:im,isTouchDevice:ix}=B,iy=(t,e)=>!V(e)||t[`${e}Key`];class ib{applyInactiveState(t=[]){let e=[];for(let i of(t.forEach(t=>{let i=t.series;e.push(i),i.linkedParent&&e.push(i.linkedParent),i.linkedSeries&&e.push.apply(e,i.linkedSeries),i.navigatorSeries&&e.push(i.navigatorSeries),i.boosted&&i.markerGroup&&e.push.apply(e,this.chart.series.filter(t=>t.markerGroup===i.markerGroup))}),this.chart.series)){let t=i.options;t.states?.inactive?.enabled!==!1&&(-1===e.indexOf(i)?i.setState("inactive",!0):t.inactiveOtherPoints&&i.setAllPointsToState("inactive"))}}destroy(){let t=this;this.eventsToUnbind.forEach(t=>t()),this.eventsToUnbind=[],!B.chartCount&&(ib.unbindDocumentMouseUp.forEach(t=>t.unbind()),ib.unbindDocumentMouseUp.length=0,ib.unbindDocumentTouchEnd&&(ib.unbindDocumentTouchEnd=ib.unbindDocumentTouchEnd())),tm(t,function(e,i){t[i]=void 0})}getSelectionMarkerAttrs(t,e){let i={args:{chartX:t,chartY:e},attrs:{},shapeType:"rect"};return Q(this,"getSelectionMarkerAttrs",i,i=>{let s,{chart:o,zoomHor:r,zoomVert:a}=this,{mouseDownX:n=0,mouseDownY:h=0}=o,l=i.attrs;l.x=o.plotLeft,l.y=o.plotTop,l.width=r?1:o.plotWidth,l.height=a?1:o.plotHeight,r&&(l.width=Math.max(1,Math.abs(s=t-n)),l.x=(s>0?0:s)+n),a&&(l.height=Math.max(1,Math.abs(s=e-h)),l.y=(s>0?0:s)+h)}),i}drag(t){let{chart:e}=this,{mouseDownX:i=0,mouseDownY:s=0}=e,{panning:o,panKey:r,selectionMarkerFill:a}=e.options.chart,n=e.plotLeft,h=e.plotTop,l=e.plotWidth,d=e.plotHeight,c=tg(o)?o.enabled:o,p=r&&t[`${r}Key`],g=t.chartX,u=t.chartY,f,m=this.selectionMarker;if((!m||!m.touch)&&(gn+l&&(g=n+l),uh+d&&(u=h+d),this.hasDragged=Math.sqrt(Math.pow(i-g,2)+Math.pow(s-u,2)),this.hasDragged>10)){f=e.isInsidePlot(i-n,s-h,{visiblePlotOnly:!0});let{shapeType:l,attrs:d}=this.getSelectionMarkerAttrs(g,u);this.hasZoom&&f&&!p&&!m&&(this.selectionMarker=m=e.renderer[l](),m.attr({class:"highcharts-selection-marker",zIndex:7}).add(),e.styledMode||m.attr({fill:a||ig("#334eff").setOpacity(.25).get()})),m&&m.attr(d),f&&!m&&c&&iy(t,r)&&e.pan(t,o)}}dragStart(t){let e=this.chart;e.mouseIsDown=t.type,e.cancelClick=!1,e.mouseDownX=t.chartX,e.mouseDownY=t.chartY}getSelectionBox(t){let e={args:{marker:t},result:t.getBBox()};return Q(this,"getSelectionBox",e),e.result}drop(t){let e,{chart:i,selectionMarker:s}=this;for(let t of i.axes)t.isPanning&&(t.isPanning=!1,(t.options.startOnTick||t.options.endOnTick||t.series.some(t=>t.boosted))&&(t.forceRedraw=!0,t.setExtremes(t.userMin,t.userMax,!1),e=!0));if(e&&i.redraw(),s&&t){if(this.hasDragged){let e=this.getSelectionBox(s);i.transform({axes:i.axes.filter(t=>t.zoomEnabled&&("xAxis"===t.coll&&this.zoomX||"yAxis"===t.coll&&this.zoomY)),selection:{originalEvent:t,xAxis:[],yAxis:[],...e},from:e})}tl(i.index)&&(this.selectionMarker=s.destroy())}i&&tl(i.index)&&($(i.container,{cursor:i._cursor}),i.cancelClick=this.hasDragged>10,i.mouseIsDown=!1,this.hasDragged=0,this.pinchDown=[],this.hasPinchMoved=!1)}findNearestKDPoint(t,e,i){let s;return t.forEach(function(t){var o;let r,a,n,h=!(t.noSharedTooltip&&e)&&0>t.options.findNearestPointBy.indexOf("y"),l=t.searchPoint(i,h);tg(l,!0)&&l.series&&(!tg(s,!0)||(r=(o=s).distX-l.distX,a=o.dist-l.dist,n=l.series.group?.zIndex-o.series.group?.zIndex,(0!==r&&e?r:0!==a?a:0!==n?n:o.series.index>l.series.index?-1:1)>0))&&(s=l)}),s}getChartCoordinatesFromPoint(t,e){let{xAxis:i,yAxis:s}=t.series,o=t.shapeArgs;if(i&&s){let r=t.clientX??t.plotX??0,a=t.plotY||0;return t.isNode&&o&&tl(o.x)&&tl(o.y)&&(r=o.x,a=o.y),e?{chartX:s.len+s.pos-a,chartY:i.len+i.pos-r}:{chartX:r+i.pos,chartY:a+s.pos}}if(o?.x&&o.y)return{chartX:o.x,chartY:o.y}}getChartPosition(){if(this.chartPosition)return this.chartPosition;let{container:t}=this.chart,e=tx(t);this.chartPosition={left:e.left,top:e.top,scaleX:1,scaleY:1};let{offsetHeight:i,offsetWidth:s}=t;return s>2&&i>2&&(this.chartPosition.scaleX=e.width/s,this.chartPosition.scaleY=e.height/i),this.chartPosition}getCoordinates(t){let e={xAxis:[],yAxis:[]};for(let i of this.chart.axes)e[i.isXAxis?"xAxis":"yAxis"].push({axis:i,value:i.toValue(t[i.horiz?"chartX":"chartY"])});return e}getHoverData(t,e,i,s,o,r){let a=[],n=function(t){return t.visible&&!(!o&&t.directTouch)&&tb(t.options.enableMouseTracking,!0)},h=e,l,d={chartX:r?r.chartX:void 0,chartY:r?r.chartY:void 0,shared:o};Q(this,"beforeGetHoverData",d),l=h&&!h.stickyTracking?[h]:i.filter(t=>t.stickyTracking&&(d.filter||n)(t));let c=s&&t||!r?t:this.findNearestKDPoint(l,o,r);return h=c?.series,c&&(o&&!h.noSharedTooltip?(l=i.filter(function(t){return d.filter?d.filter(t):n(t)&&!t.noSharedTooltip})).forEach(function(t){let e=t.options?.nullInteraction,i=tr(t.points,function(t){return t.x===c.x&&(!t.isNull||!!e)});tg(i)&&(t.boosted&&t.boost&&(i=t.boost.getPoint(i)),a.push(i))}):a.push(c)),Q(this,"afterGetHoverData",d={hoverPoint:c}),{hoverPoint:d.hoverPoint,hoverSeries:h,hoverPoints:a}}getPointFromEvent(t){let e=t.target,i;for(;e&&!i;)i=e.point,e=e.parentNode;return i}onTrackerMouseOut(t){let e=this.chart,i=t.relatedTarget,s=e.hoverSeries;this.isDirectTouch=!1,!s||!i||s.stickyTracking||this.inClass(i,"highcharts-tooltip")||this.inClass(i,"highcharts-series-"+s.index)&&this.inClass(i,"highcharts-tracker")||s.onMouseOut()}inClass(t,e){let i=t,s;for(;i;){if(s=X(i,"class")){if(-1!==s.indexOf(e))return!0;if(-1!==s.indexOf("highcharts-container"))return!1}i=i.parentElement}}constructor(t,e){this.hasDragged=0,this.pointerCaptureEventsToUnbind=[],this.eventsToUnbind=[],this.options=e,this.chart=t,this.runChartClick=!!e.chart.events?.click,this.pinchDown=[],this.setDOMEvents(),Q(this,"afterInit")}normalize(t,e){let i=t.touches,s=i?i.length?i.item(0):tb(i.changedTouches,t.changedTouches)[0]:t;e||(e=this.getChartPosition());let o=s.pageX-e.left,r=s.pageY-e.top;return q(t,{chartX:Math.round(o/=e.scaleX),chartY:Math.round(r/=e.scaleY)})}onContainerClick(t){let e=this.chart,i=e.hoverPoint,s=this.normalize(t),o=e.plotLeft,r=e.plotTop;!e.cancelClick&&(i&&this.inClass(s.target,"highcharts-tracker")?(Q(i.series,"click",q(s,{point:i})),e.hoverPoint&&i.firePointEvent("click",s)):(q(s,this.getCoordinates(s)),e.isInsidePlot(s.chartX-o,s.chartY-r,{visiblePlotOnly:!0})&&Q(e,"click",s)))}onContainerMouseDown(t){let e=(1&(t.buttons||t.button))==1;t=this.normalize(t),B.isFirefox&&0!==t.button&&this.onContainerMouseMove(t),(void 0===t.button||e)&&(this.zoomOption(t),e&&t.preventDefault?.(),this.dragStart(t))}onContainerMouseLeave(t){let{pointer:e}=iu[tb(ib.hoverChartIndex,-1)]||{};t=this.normalize(t),this.onContainerMouseMove(t),e&&!this.inClass(t.relatedTarget,"highcharts-tooltip")&&(e.reset(),e.chartPosition=void 0)}onContainerMouseEnter(){delete this.chartPosition}onContainerMouseMove(t){let e=this.chart,i=e.tooltip,s=this.normalize(t);this.setHoverChartIndex(t),("mousedown"===e.mouseIsDown||this.touchSelect(s))&&this.drag(s),!e.exporting?.openMenu&&(this.inClass(s.target,"highcharts-tracker")||e.isInsidePlot(s.chartX-e.plotLeft,s.chartY-e.plotTop,{visiblePlotOnly:!0}))&&!i?.shouldStickOnContact(s)&&(this.inClass(s.target,"highcharts-no-tooltip")?this.reset(!1,0):this.runPointActions(s))}onDocumentTouchEnd(t){this.onDocumentMouseUp(t)}onContainerTouchMove(t){this.touchSelect(t)?this.onContainerMouseMove(t):this.touch(t)}onContainerTouchStart(t){this.touchSelect(t)?this.onContainerMouseDown(t):(this.zoomOption(t),this.touch(t,!0))}onDocumentMouseMove(t){let e=this.chart,i=e.tooltip,s=this.chartPosition,o=this.normalize(t,s);!s||e.isInsidePlot(o.chartX-e.plotLeft,o.chartY-e.plotTop,{visiblePlotOnly:!0})||i?.shouldStickOnContact(o)||o.target!==e.container.ownerDocument&&this.inClass(o.target,"highcharts-tracker")||this.reset()}onDocumentMouseUp(t){t?.touches&&this.hasPinchMoved&&t?.preventDefault?.(),iu[tb(ib.hoverChartIndex,-1)]?.pointer?.drop(t)}pinch(t){let e=this,{chart:i,hasZoom:s,lastTouches:o}=e,r=[].map.call(t.touches||[],t=>e.normalize(t)),a=r.length,n=1===a&&(e.inClass(t.target,"highcharts-tracker")&&i.runTrackerClick||e.runChartClick),h=i.tooltip,l=1===a&&tb(h?.options.followTouchMove,!0);a>1?e.initiated=!0:l&&(e.initiated=!1),s&&e.initiated&&!n&&!1!==t.cancelable&&t.preventDefault(),"touchstart"===t.type?(e.pinchDown=r,e.res=!0,i.mouseDownX=t.chartX):l?this.runPointActions(e.normalize(t)):o&&(Q(i,"touchpan",{originalEvent:t,touches:r},()=>{let e=t=>{let e=t[0],i=t[1]||e;return{x:e.chartX,y:e.chartY,width:i.chartX-e.chartX,height:i.chartY-e.chartY}};i.transform({axes:i.axes.filter(t=>t.zoomEnabled&&(this.zoomHor&&t.horiz||this.zoomVert&&!t.horiz)),to:e(r),from:e(o),trigger:t.type})}),e.res&&(e.res=!1,this.reset(!1,0))),e.lastTouches=r}reset(t,e){let i=this.chart,s=i.hoverSeries,o=i.hoverPoint,r=i.hoverPoints,a=i.tooltip,n=a?.shared?r:o;t&&n&&tT(n).forEach(function(e){e.series.isCartesian&&void 0===e.plotX&&(t=!1)}),t?a&&n&&tT(n).length&&(a.refresh(n),a.shared&&r?r.forEach(function(t){t.setState(t.state,!0),t.series.isCartesian&&(t.series.xAxis.crosshair&&t.series.xAxis.drawCrosshair(null,t),t.series.yAxis.crosshair&&t.series.yAxis.drawCrosshair(null,t))}):o&&(o.setState(o.state,!0),i.axes.forEach(function(t){t.crosshair&&o.series[t.coll]===t&&t.drawCrosshair(null,o)}))):(o&&o.onMouseOut(),r&&r.forEach(function(t){t.setState()}),s&&s.onMouseOut(),a&&a.hide(e),this.unDocMouseMove&&(this.unDocMouseMove=this.unDocMouseMove()),i.axes.forEach(function(t){t.hideCrosshair()}),i.hoverPoints=i.hoverPoint=void 0)}runPointActions(t,e,i){let s=this.chart,o=s.series,r=s.tooltip?.options.enabled?s.tooltip:void 0,a=!!r&&r.shared,n=e||s.hoverPoint,h=n?.series||s.hoverSeries,l=(!t||"touchmove"!==t.type)&&(!!e||h?.directTouch&&this.isDirectTouch),d=this.getHoverData(n,h,o,l,a,t);n=d.hoverPoint,h=d.hoverSeries;let c=d.hoverPoints,p=h?.tooltipOptions.followPointer&&!h.tooltipOptions.split,g=a&&h&&!h.noSharedTooltip;if(n&&(i||n!==s.hoverPoint||r?.isHidden)){if((s.hoverPoints||[]).forEach(function(t){-1===c.indexOf(t)&&t.setState()}),s.hoverSeries!==h&&h.onMouseOver(),this.applyInactiveState(c),(c||[]).forEach(function(t){t.setState("hover")}),s.hoverPoint&&s.hoverPoint.firePointEvent("mouseOut"),!n.series)return;s.hoverPoints=c,s.hoverPoint=n,n.firePointEvent("mouseOver",void 0,()=>{r&&n&&r.refresh(g?c:n,t)})}else if(p&&r&&!r.isHidden){let e=r.getAnchor([{}],t);s.isInsidePlot(e[0],e[1],{visiblePlotOnly:!0})&&r.updatePosition({plotX:e[0],plotY:e[1]})}this.unDocMouseMove||(this.unDocMouseMove=R(s.container.ownerDocument,"mousemove",t=>iu[ib.hoverChartIndex??-1]?.pointer?.onDocumentMouseMove(t)),this.eventsToUnbind.push(this.unDocMouseMove)),s.axes.forEach(function(e){let i,o=e.crosshair?.snap??!0;o&&((i=s.hoverPoint)&&i.series[e.coll]===e||(i=tr(c,t=>t.series?.[e.coll]===e))),i||!o?e.drawCrosshair(t,i):e.hideCrosshair()})}setDOMEvents(){let t=this.chart.container,e=t.ownerDocument,i=t=>t.parentElement||t.getRootNode()?.host?.parentElement;t.onmousedown=this.onContainerMouseDown.bind(this),t.onmousemove=this.onContainerMouseMove.bind(this),t.onclick=this.onContainerClick.bind(this),this.eventsToUnbind.push(R(t,"mouseenter",this.onContainerMouseEnter.bind(this)),R(t,"mouseleave",this.onContainerMouseLeave.bind(this))),ib.unbindDocumentMouseUp.some(t=>t.doc===e)||ib.unbindDocumentMouseUp.push({doc:e,unbind:R(e,"mouseup",this.onDocumentMouseUp.bind(this))});let s=i(this.chart.renderTo);for(;s&&"BODY"!==s.tagName;)this.eventsToUnbind.push(R(s,"scroll",()=>{delete this.chartPosition})),s=i(s);this.eventsToUnbind.push(R(t,"touchstart",this.onContainerTouchStart.bind(this),{passive:!1}),R(t,"touchmove",this.onContainerTouchMove.bind(this),{passive:!1})),ib.unbindDocumentTouchEnd||(ib.unbindDocumentTouchEnd=R(e,"touchend",this.onDocumentTouchEnd.bind(this),{passive:!1})),this.setPointerCapture(),R(this.chart,"redraw",this.setPointerCapture.bind(this))}setPointerCapture(){if(!ix)return;let t=this.pointerCaptureEventsToUnbind,e=this.chart,i=e.container,s=tb(e.options.tooltip?.followTouchMove,!0)&&e.series.some(t=>t.options.findNearestPointBy.indexOf("y")>-1);!this.hasPointerCapture&&s?(t.push(R(i,"pointerdown",t=>{t.target?.hasPointerCapture(t.pointerId)&&t.target?.releasePointerCapture(t.pointerId)}),R(i,"pointermove",t=>{e.pointer?.getPointFromEvent(t)?.onMouseOver(t)})),e.styledMode||$(i,{"touch-action":"none"}),i.className+=" highcharts-no-touch-action",this.hasPointerCapture=!0):this.hasPointerCapture&&!s&&(t.forEach(t=>t()),t.length=0,e.styledMode||$(i,{"touch-action":tb(e.options.chart.style?.["touch-action"],"manipulation")}),i.className=i.className.replace(" highcharts-no-touch-action",""),this.hasPointerCapture=!1)}setHoverChartIndex(t){let e=this.chart,i=B.charts[tb(ib.hoverChartIndex,-1)];if(i&&i!==e){let s={relatedTarget:e.container};t&&!t?.relatedTarget&&Object.assign({},t,s),i.pointer?.onContainerMouseLeave(t||s)}i?.mouseIsDown||(ib.hoverChartIndex=e.index)}touch(t,e){let i,{chart:s,pinchDown:o=[]}=this;this.setHoverChartIndex(),1===(t=this.normalize(t)).touches.length?s.isInsidePlot(t.chartX-s.plotLeft,t.chartY-s.plotTop,{visiblePlotOnly:!0})&&!s.exporting?.openMenu?(e&&this.runPointActions(t),"touchmove"===t.type&&(this.hasPinchMoved=i=!!o[0]&&Math.pow(o[0].chartX-t.chartX,2)+Math.pow(o[0].chartY-t.chartY,2)>=16),tb(i,!0)&&this.pinch(t)):e&&this.reset():2===t.touches.length&&this.pinch(t)}touchSelect(t){return!!(this.chart.zooming.singleTouch&&t.touches&&1===t.touches.length)}zoomOption(t){let e=this.chart,i=e.inverted,s=e.zooming.type||"",o,r;/touch/.test(t.type)&&(s=tb(e.zooming.pinchType,s)),this.zoomX=o=/x/.test(s),this.zoomY=r=/y/.test(s),this.zoomHor=o&&!i||r&&i,this.zoomVert=r&&!i||o&&i,this.hasZoom=(o||r)&&iy(t,e.zooming.key)}}ib.unbindDocumentMouseUp=[],(d=ib||(ib={})).compose=function(t){tk(im,"Core.Pointer")&&R(t,"beforeRender",function(){this.pointer=new d(this,this.options)})};let iv=ib,{setLength:ik,splice:iw}={convertToNumber:function(t,e){switch(typeof t){case"boolean":return+!!t;case"number":return isNaN(t)&&!e?null:t;default:return isNaN(t=parseFloat(`${t??""}`))&&!e?null:t}},setLength:function(t,e,i){return Array.isArray(t)?(t.length=e,t):t[i?"subarray":"slice"](0,e)},splice:function(t,e,i,s,o=[]){if(Array.isArray(t))return Array.isArray(o)||(o=Array.from(o)),{removed:t.splice(e,i,...o),array:t};let r=Object.getPrototypeOf(t).constructor,a=t[s?"subarray":"slice"](e,e+i),n=new r(t.length-i+o.length);return n.set(t.subarray(0,e),0),n.set(o,e),n.set(t.subarray(e+i),e+o.length),{removed:a,array:n}}},iM=class{constructor(t={}){this.autoId=!t.id,this.columns={},this.id=t.id||tB(),this.rowCount=0,this.versionTag=tB();let e=0;tm(t.columns||{},(t,i)=>{this.columns[i]=t.slice(),e=Math.max(e,t.length)}),this.applyRowCount(e)}applyRowCount(t){this.rowCount=t,tm(this.columns,(e,i)=>{e.length!==t&&(this.columns[i]=ik(e,t))})}deleteRows(t,e=1){if(e>0&&t{this.columns[o]=iw(s,t,e).array,i=s.length}),this.rowCount=i}Q(this,"afterDeleteRows",{rowIndex:t,rowCount:e}),this.versionTag=tB()}getColumn(t,e){return this.columns[t]}getColumns(t,e){return(t||Object.keys(this.columns)).reduce((t,e)=>(t[e]=this.columns[e],t),{})}getRow(t,e){return(e||Object.keys(this.columns)).map(e=>this.columns[e]?.[t])}setColumn(t,e=[],i=0,s){this.setColumns({[t]:e},i,s)}setColumns(t,e,i){let s=this.rowCount;tm(t,(t,e)=>{this.columns[e]=t.slice(),s=t.length}),this.applyRowCount(s),i?.silent||(Q(this,"afterSetColumns"),this.versionTag=tB())}setRow(t,e=this.rowCount,i,s){let{columns:o}=this,r=i?this.rowCount+1:e+1,a=Object.keys(t);if(s?.addColumns!==!1)for(let t=0,e=a.length;t{a||s?.addColumns===!1||(a=Array(r)),a&&(i?a=iw(a,e,0,!0,[t[n]??null]).array:a[e]=t[n]??null,o[n]=a)}),r>this.rowCount&&this.applyRowCount(r),s?.silent||(Q(this,"afterSetRows"),this.versionTag=tB())}getModified(){return this.modified||this}};var iS=M||(M={});function iT(t,e,i){let s=this.legendItem=this.legendItem||{},{chart:o,options:r}=this,{baseline:a=0,symbolWidth:n,symbolHeight:h}=t,l=this.symbol||"circle",d=h/2,c=o.renderer,p=s.group,g=a-Math.round((t.fontMetrics?.b||h)*(i?.4:.3)),u={},f,m=r.marker,x=0;if(o.styledMode||(u["stroke-width"]=Math.min(r.lineWidth||0,24),r.dashStyle?u.dashstyle=r.dashStyle:"square"!==r.linecap&&(u["stroke-linecap"]="round")),s.line=c.path().addClass("highcharts-graph").attr(u).add(p),i&&(s.area=c.path().addClass("highcharts-area").add(p)),u["stroke-linecap"]&&(x=Math.min(s.line.strokeWidth(),n)/2),n){let t=[["M",x,g],["L",n-x,g]];s.line.attr({d:t}),s.area?.attr({d:[...t,["L",n-x,a],["L",x,a]]})}if(m&&!1!==m.enabled&&n){let t=Math.min(tb(m.radius,d),d);0===l.indexOf("url")&&(m=tu(m,{width:h,height:h}),t=0),s.symbol=f=c.symbol(l,n/2-t,g-t,2*t,2*t,q({context:"legend"},m)).addClass("highcharts-point").add(p),f.isMarker=!0}}iS.areaMarker=function(t,e){iT.call(this,t,e,!0)},iS.lineMarker=iT;let iC=M,{defaultOptions:iA}=tY;var iP=S||(S={});function iL(t,e){let i=iA.plotOptions||{},s=e.defaultOptions,o=e.prototype;return o.type=t,o.pointClass||(o.pointClass=ip),!iP.seriesTypes[t]&&(s&&(i[t]=s),iP.seriesTypes[t]=e,!0)}iP.seriesTypes=B.seriesTypes,iP.registerSeriesType=iL,iP.seriesType=function(t,e,i,s,o){let r=iA.plotOptions||{};if(e=e||"",r[t]=tu(r[e],i),delete iP.seriesTypes[t],iL(t,J(iP.seriesTypes[e]||B.Series,s)),iP.seriesTypes[t].prototype.type=t,o){class e extends ip{}q(e.prototype,o),iP.seriesTypes[t].prototype.pointClass=e}return iP.seriesTypes[t]};let iO=S,{animObject:iE,setAnimation:iI}=tQ,{defaultOptions:iD}=tY,{registerEventOptions:iB}=eV,{svg:iN,win:iz}=B,{seriesTypes:iR}=iO,{format:iW}=es;class iH{constructor(){this.zoneAxis="y"}init(t,e){let i;Q(this,"init",{options:e}),this.dataTable??(this.dataTable=new iM);let s=t.series;this.eventsToUnbind=[],this.chart=t,this.options=this.setOptions(e);let o=this.options,r=!1!==o.visible;this.linkedSeries=[],this.bindAxes(),q(this,{name:o.name,state:"",visible:r,selected:!0===o.selected}),iB(this,o);let a=o.events;(a?.click||o.point?.events?.click||o.allowPointSelect)&&(t.runTrackerClick=!0),this.getColor(),this.getSymbol(),this.isCartesian&&(t.hasCartesianSeries=!0),s.length&&(i=s[s.length-1]),this._i=tb(i?._i,-1)+1,this.opacity=this.options.opacity,t.orderItems("series",tI(this,s)),o.dataSorting?.enabled?this.setDataSortingOptions():this.points||this.data||this.setData(o.data,!1),Q(this,"afterInit")}is(t){return iR[t]&&this instanceof iR[t]}bindAxes(){let t,e=this,i=e.options,s=e.chart;Q(this,"bindAxes",null,function(){(e.axisTypes||[]).forEach(function(o){(s[o]||[]).forEach(function(s){t=s.options,(tb(i[o],0)===s.index||void 0!==i[o]&&i[o]===t.id)&&(tI(e,s.series),e[o]=s,s.isDirty=!0)}),e[o]||e.optionalAxis===o||tE(18,!0,s)})}),Q(this,"afterBindAxes")}hasData(){return this.visible&&void 0!==this.dataMax&&void 0!==this.dataMin||this.visible&&this.dataTable.rowCount>0}hasMarkerChanged(t,e){let i=t.marker,s=e.marker||{};return i&&(s.enabled&&!i.enabled||s.symbol!==i.symbol||s.height!==i.height||s.width!==i.width)}autoIncrement(t){let e,i=this.options,{pointIntervalUnit:s,relativeXValue:o}=this.options,r=this.chart.time,a=this.xIncrement??r.parse(i.pointStart)??0;if(this.pointInterval=e=tb(this.pointInterval,i.pointInterval,1),o&&tl(t)&&(e*=t),s){let t=r.toParts(a);"day"===s?t[2]+=e:"month"===s?t[1]+=e:"year"===s&&(t[0]+=e),e=r.makeTime.apply(r,t)-a}return o&&tl(t)?a+e:(this.xIncrement=a+e,a)}setDataSortingOptions(){let t=this.options;q(this,{requireSorting:!1,sorted:!1,enabledDataSorting:!0,allowDG:!1}),V(t.pointRange)||(t.pointRange=1)}setOptions(t){let e,i=this.chart,s=i.options.plotOptions,o=i.userOptions||{},r=tu(t),a=i.styledMode,n={plotOptions:s,userOptions:r};Q(this,"setOptions",n);let h=n.plotOptions[this.type],l=o.plotOptions||{},d=l.series||{},c=iD.plotOptions[this.type]||{},p=l[this.type]||{};h.dataLabels=this.mergeArrays(c.dataLabels,h.dataLabels),this.userOptions=n.userOptions;let g=tu(h,s.series,p,r);this.tooltipOptions=tu(iD.tooltip,iD.plotOptions.series?.tooltip,c?.tooltip,i.userOptions.tooltip,l.series?.tooltip,p.tooltip,r.tooltip),this.stickyTracking=tb(r.stickyTracking,p.stickyTracking,d.stickyTracking,!!this.tooltipOptions.shared&&!this.noSharedTooltip||g.stickyTracking),null===h.marker&&delete g.marker;let{negativeColor:u,negativeFillColor:f,zoneAxis:m="y",zones:x}=g,y=this.zones=(x||[]).map(t=>({...t}));return this.zoneAxis=m,(u||f)&&!x&&(e={value:g[m+"Threshold"]||g.threshold||0,className:"highcharts-negative"},a||("boolean"!=typeof u&&(e.color=u),e.fillColor=f),y.push(e)),y.length&&V(y[y.length-1].value)&&y.push(a?{}:{color:this.color,fillColor:this.fillColor}),Q(this,"afterSetOptions",{options:g}),g}getName(){return this.options.name??iW(this.chart.options.lang.seriesName,this,this.chart)}getCyclic(t,e,i){let s,o,r=this.chart,a=`${t}Index`,n=`${t}Counter`,h=i?.length||r.options.chart.colorCount;!e&&(V(o=tb("color"===t?this.options.colorIndex:void 0,this[a]))?s=o:(r.series.length||(r[n]=0),s=r[n]%h,r[n]+=1),i&&(e=i[s])),void 0!==s&&(this[a]=s),this[t]=e}getColor(){this.chart.styledMode?this.getCyclic("color"):this.options.colorByPoint?this.color="#cccccc":this.getCyclic("color",this.options.color||iD.plotOptions[this.type].color,this.chart.options.colors)}getPointsCollection(){return(this.hasGroupedData?this.points:this.data)||[]}getSymbol(){let t=this.options.marker;this.getCyclic("symbol",t.symbol,this.chart.options.symbols)}getColumn(t,e){return(e?this.dataTable.getModified():this.dataTable).getColumn(t,!0)||[]}findPointIndex(t,e){let i,s,o,{id:r,x:a}=t,n=this.points,h=this.options.dataSorting,l=this.cropStart||0;if(r){let t=this.chart.get(r);t instanceof ip&&(i=t)}else if(this.linkedParent||this.enabledDataSorting||this.options.relativeXValue){let e=e=>!e.touched&&e.index===t.index;if(h?.matchByName?e=e=>!e.touched&&e.name===t.name:this.options.relativeXValue&&(e=e=>!e.touched&&e.options.x===t.x),!(i=tr(n,e)))return}return i&&void 0!==(o=i?.index)&&(s=!0),void 0===o&&tl(a)&&(o=this.getColumn("x").indexOf(a,e)),-1!==o&&void 0!==o&&this.cropped&&(o=o>=l?o-l:o),!s&&tl(o)&&n[o]?.touched&&(o=void 0),o}updateData(t,e){let{options:i,requireSorting:s}=this,o=i.dataSorting,r=this.points,a=[],n=t.length===r.length,h=this.xIncrement,l,d,c,p,g=!0;if(this.xIncrement=null,t.forEach((t,e)=>{let h,d=V(t)&&this.pointClass.prototype.optionsToObject.call({series:this},t)||{},{id:c,x:g}=d;c||tl(g)?(-1===(h=this.findPointIndex(d,p))||void 0===h?a.push(t):r[h]&&t!==i.data?.[h]?(r[h].update(t,!1,void 0,!1),r[h].touched=!0,s&&(p=h+1)):r[h]&&(r[h].touched=!0),(!n||e!==h||o?.enabled||this.hasDerivedData)&&(l=!0)):a.push(t)},this),l)for(d=r.length;d--;)(c=r[d])&&!c.touched&&c.remove?.(!1,e);else n&&!o?.enabled?(t.forEach((t,e)=>{t===r[e].y||r[e].destroyed||r[e].update(t,!1,void 0,!1)}),a.length=0):g=!1;if(r.forEach(t=>{t&&(t.touched=!1)}),!g)return!1;a.forEach(t=>{this.addPoint(t,!1,void 0,void 0,!1)},this);let u=this.getColumn("x");return null!==h&&null===this.xIncrement&&u.length&&(this.xIncrement=H(u),this.autoIncrement()),!0}dataColumnKeys(){return["x",...this.pointArrayMap||["y"]]}setData(t,e=!0,i,s){let o=this.points,r=o?.length||0,a=this.options,n=this.chart,h=a.dataSorting,l=this.xAxis,d=a.turboThreshold,c=this.dataTable,p=this.dataColumnKeys(),g=this.pointValKey||"y",u=(this.pointArrayMap||[]).length,f=a.keys,m,x,y=0,b=1,v;n.options.chart.allowMutatingData||(a.data&&delete this.options.data,this.userOptions.data&&delete this.userOptions.data,v=tu(!0,t));let k=(t=v||t||[]).length;if(h?.enabled&&(t=this.sortData(t)),!1!==s&&k&&r&&!this.cropped&&!this.hasGroupedData&&this.visible&&!this.boosted&&(x=this.updateData(t,i)),!x){this.xIncrement=null,this.colorCounter=0;let e=d&&!a.relativeXValue&&k>d;if(e){let i=this.getFirstValidPoint(t),s=this.getFirstValidPoint(t,k-1,-1),o=t=>!!(tc(t)&&(f||tl(t[0])));if(tl(i)&&tl(s)){let e=[],i=[];for(let s of t)e.push(this.autoIncrement()),i.push(s);c.setColumns({x:e,[g]:i})}else if(o(i)&&o(s))if(u){let e=+(i.length===u),s=Array(p.length).fill(0).map(()=>[]);for(let i of t){e&&s[0].push(this.autoIncrement());for(let t=e;t<=u;t++)s[t]?.push(i[t-e])}c.setColumns(p.reduce((t,e,i)=>(t[e]=s[i],t),{}))}else{f&&(y=f.indexOf("x"),b=f.indexOf("y"),y=y>=0?y:0,b=b>=0?b:1),1===i.length&&(b=0);let e=[],s=[];for(let i of t)y===b?e.push(this.autoIncrement()):e.push(i[y]??i.x??null),s.push(i[b]??i.y??null);c.setColumns({x:e,[g]:s})}else e=!1}if(!e){let e=p.reduce((t,e)=>(t[e]=[],t),{});for(m=0;m{let s=ts(i,t),o=ts(i,e);return os)}).forEach(function(t,e){t.x=e},this),e.linkedSeries&&e.linkedSeries.forEach(function(e){let i=e.options,o=i.data;!i.dataSorting?.enabled&&o&&(o.forEach(function(i,r){o[r]=s(e,i),t[r]&&(o[r].x=t[r].x,o[r].index=r)}),e.setData(o,!1))}),t}getProcessedData(t){let e=this,{dataTable:i,isCartesian:s,options:o,xAxis:r}=e,a=o.cropThreshold,n=t||e.getExtremesFromAll,h=r?.logarithmic,l=i.rowCount,d,c,p=0,g,u,f,m=e.getColumn("x"),x=i,y=!1;return r&&(u=(g=r.getExtremes()).min,f=g.max,y=!!(r.categories&&!r.names.length),s&&e.sorted&&!n&&(!a||l>a||e.forceCrop)&&(m[l-1]f?x=new iM:e.getColumn(e.pointValKey||"y").length&&(m[0]f)&&(x=(d=this.cropData(i,u,f)).modified,p=d.start,c=!0))),m=x.getColumn("x")||[],{modified:x,cropped:c,cropStart:p,closestPointRange:te([h?m.map(h.log2lin):m],()=>e.requireSorting&&!y&&tE(15,!1,e.chart))}}processData(t){let e=this.xAxis,i=this.dataTable;if(this.isCartesian&&!this.isDirty&&!e.isDirty&&!this.yAxis.isDirty&&!t)return!1;let s=this.getProcessedData();i.modified=s.modified,this.cropped=s.cropped,this.cropStart=s.cropStart,this.closestPointRange=this.basePointRange=s.closestPointRange,Q(this,"afterProcessData")}cropData(t,e,i){let s=t.getColumn("x",!0)||[],o=s.length,r={},a,n,h=0,l=o;for(a=0;a=e){h=Math.max(0,a-1);break}for(n=a;ni){l=n+1;break}for(let e of this.dataColumnKeys()){let i=t.getColumn(e,!0);i&&(r[e]=i.slice(h,l))}return{modified:new iM({columns:r}),start:h,end:l}}generatePoints(){let t=this.options,e=this.processedData||t.data,i=this.dataTable.getModified(),s=this.getColumn("x",!0),o=this.pointClass,r=i.rowCount,a=this.cropStart||0,n=this.hasGroupedData,h=t.keys,l=[],d=t.dataGrouping?.groupAll?a:0,c=this.pointArrayMap||["y"],p=this.dataColumnKeys(),g,u,f,m,x=this.data,y;if(!x&&!n){let t=[];t.length=e?.length||0,x=this.data=t}for(h&&n&&(this.options.keys=!1),m=0;mr.getColumn(t,!0)||[])||[],l=this.getColumn("x",!0),d=[],c=this.requireSorting&&!this.is("column")?1:0,p=!!s&&s.positiveValuesOnly,g=o||this.cropped||!i,u,f,m,x=0,y=0;for(i&&(x=(u=i.getExtremes()).min,y=u.max),m=0;m=x&&(l[m-c]||f)<=y)for(let t of h){let e=t[m];tl(e)&&(e>0||!p)&&d.push(e)}let b={activeYData:d,dataMin:W(d),dataMax:H(d)};return Q(this,"afterGetExtremes",{dataExtremes:b}),b}applyExtremes(){let t=this.getExtremes();return this.dataMin=t.dataMin,this.dataMax=t.dataMax,t}getFirstValidPoint(t,e=0,i=1){let s=t.length,o=e;for(;o>=0&&o1)&&(r.step=function(t,e){i&&i.apply(e,arguments),"width"===e.prop&&h?.element&&h.attr(o?"height":"width",t+99)}),n.addClass("highcharts-animating").animate(t,r)}}afterAnimate(){this.setClip(),tm(this.chart.sharedClips,(t,e,i)=>{t&&!this.chart.container.querySelector(`[clip-path="url(#${t.id})"]`)&&(t.destroy(),delete i[e])}),this.finishedAnimating=!0,Q(this,"afterAnimate")}drawPoints(t=this.points){let e,i,s,o,r,a,n,h=this.chart,l=h.styledMode,{colorAxis:d,options:c}=this,p=c.marker,g=c.nullInteraction,u=this[this.specialGroup||"markerGroup"],f=this.xAxis,m=tb(p.enabled,!f||!!f.isRadial||null,this.closestPointRangePx>=p.enabledThreshold*p.radius);if(!1!==p.enabled||this._hasPointMarkers)for(e=0;e0||i.hasImage)&&(i.graphic=s=h.renderer.symbol(t,n.x,n.y,n.width,n.height,a?r:p).add(u),this.enabledDataSorting&&h.hasRendered&&(s.attr({x:i.startXPos}),o="animate")),s&&"animate"===o&&s[e?"show":"hide"](e).animate(n),s){let t=this.pointAttribs(i,l||!i.selected?void 0:"select");l?d&&s.css({fill:t.fill}):s[o](t)}s&&s.addClass(i.getClassName(),!0)}else s&&(i.graphic=s.destroy())}}markerAttribs(t,e){let i=this.options,s=i.marker,o=t.marker||{},r=o.symbol||s.symbol,a={},n,h,l=tb(o.radius,s?.radius);e&&(n=s?.states?.[e],h=o.states?.[e],l=tb(h?.radius,n?.radius,l&&l+(n?.radiusPlus||0))),t.hasImage=r&&0===r.indexOf("url"),t.hasImage&&(l=0);let d=t.pos();return tl(l)&&d&&(i.crisp&&(d[0]=j(d[0],t.hasImage?0:"rect"===r?s?.lineWidth||0:1)),a.x=d[0]-l,a.y=d[1]-l),l&&(a.width=a.height=2*l),a}pointAttribs(t,e){let i=this.options,s=i.marker,o=t?.options,r=o?.marker||{},a=o?.color,n=t?.color,h=t?.zone?.color,l,d,c=this.color,p,g,u=tb(r.lineWidth,s.lineWidth),f=t?.isNull&&i.nullInteraction?0:1;return c=a||h||n||c,p=r.fillColor||s.fillColor||c,g=r.lineColor||s.lineColor||c,e=e||"normal",l=s.states[e]||{},u=tb((d=r.states&&r.states[e]||{}).lineWidth,l.lineWidth,u+tb(d.lineWidthPlus,l.lineWidthPlus,0)),p=d.fillColor||l.fillColor||p,g=d.lineColor||l.lineColor||g,{stroke:g,"stroke-width":u,fill:p,opacity:f=tb(d.opacity,l.opacity,f)}}destroy(t){let e,i,s=this,o=s.chart,r=/AppleWebKit\/533/.test(iz.navigator.userAgent),a=s.data||[];for(Q(s,"destroy",{keepEventsForUpdate:t}),this.removeEvents(t),(s.axisTypes||[]).forEach(function(t){i=s[t],i?.series&&(K(i.series,s),i.isDirty=i.forceRedraw=!0)}),s.legendItem&&s.chart.legend.destroyItem(s),e=a.length;e--;)a[e]?.destroy?.();for(let t of s.zones)U(t,void 0,!0);ta(s.animationTimeout),tm(s,function(t,e){t instanceof em&&!t.survive&&t[r&&"group"===e?"hide":"destroy"]()}),o.hoverSeries===s&&(o.hoverSeries=void 0),K(o.series,s),o.orderItems("series"),tm(s,function(e,i){t&&"hcEvents"===i||delete s[i]})}applyZones(){let{area:t,chart:e,graph:i,zones:s,points:o,xAxis:r,yAxis:a,zoneAxis:n}=this,{inverted:h,renderer:l}=e,d=this[`${n}Axis`],{isXAxis:c,len:p=0,minPointOffset:g=0}=d||{},u=(i?.strokeWidth()||0)/2+1,f=(t,e=0,i=0)=>{h&&(i=p-i);let{translated:s=0,lineClip:o}=t,r=i-s;o?.push(["L",e,Math.abs(r){t.forEach((e,i)=>{("M"===e[0]||"L"===e[0])&&(t[i]=[e[0],c?p-e[1]:e[1],c?e[2]:p-e[2]])})};if(s.forEach(t=>{t.lineClip=[],t.translated=G(d.toPixels(tb(t.value,e),!0)||0,0,p)}),i&&!this.showLine&&i.hide(),t&&t.hide(),"y"===n&&o.length{let s=e.lineClip||[],o=Math.round(e.translated||0);r.reversed&&s.reverse();let{clip:n,simpleClip:d}=e,p=0,g=0,f=r.len,y=a.len;c?(p=o,f=x):(g=o,y=x);let b=[["M",p,g],["L",f,g],["L",f,y],["L",p,y],["Z"]],v=[b[0],...s,b[1],b[2],...m,b[3],b[4]];m=s.reverse(),x=o,h&&(u(v),t&&u(b)),n?(n.animate({d:v}),d?.animate({d:b})):(n=e.clip=l.path(v),t&&(d=e.simpleClip=l.path(b))),i&&e.graph?.clip(n),t&&e.area?.clip(d)})}else this.visible&&(i&&i.show(),t&&t.show())}plotGroup(t,e,i,s,o){let r=this[t],a=!r,n={visibility:i,zIndex:s||.1};return V(this.opacity)&&!this.chart.styledMode&&"inactive"!==this.state&&(n.opacity=this.opacity),r||(this[t]=r=this.chart.renderer.g().add(o)),r.addClass("highcharts-"+e+" highcharts-series-"+this.index+" highcharts-"+this.type+"-series "+(V(this.colorIndex)?"highcharts-color-"+this.colorIndex+" ":"")+(this.options.className||"")+(r.hasClass("highcharts-tracker")?" highcharts-tracker":""),!0),r.attr(n)[a?"attr":"animate"](this.getPlotBox(e)),r}getPlotBox(t){let e=this.xAxis,i=this.yAxis,s=this.chart,o=s.inverted&&!s.polar&&e&&this.invertible&&"series"===t;s.inverted&&(e=i,i=this.xAxis);let r={scale:1,translateX:e?e.left:s.plotLeft,translateY:i?i.top:s.plotTop,name:t};Q(this,"getPlotBox",r);let{scale:a,translateX:n,translateY:h}=r;return{translateX:n,translateY:h,rotation:90*!!o,rotationOriginX:o?a*(e.len-i.len)/2:0,rotationOriginY:o?a*(e.len+i.len)/2:0,scaleX:o?-a:a,scaleY:a}}removeEvents(t){let{eventsToUnbind:e}=this;t||tS(this),e.length&&(e.forEach(t=>{t()}),e.length=0)}render(){let t=this,{chart:e,options:i,hasRendered:s}=t,o=iE(i.animation),r=t.visible?"inherit":"hidden",a=i.zIndex,n=e.seriesGroup,h=t.finishedAnimating?0:o.duration;Q(this,"render"),t.plotGroup("group","series",r,a,n),t.markerGroup=t.plotGroup("markerGroup","markers",r,a,n),!1!==i.clip&&t.setClip(),h&&t.animate?.(!0),t.drawGraph&&(t.drawGraph(),t.applyZones()),t.visible&&t.drawPoints(),t.drawDataLabels?.(),t.redrawPoints?.(),i.enableMouseTracking&&t.drawTracker?.(),h&&t.animate?.(),s||(h&&o.defer&&(h+=o.defer),t.animationTimeout=tA(()=>{t.afterAnimate()},h||0)),t.isDirty=!1,t.hasRendered=!0,Q(t,"afterRender")}redraw(){let t=this.isDirty||this.isDirtyData;this.translate(),this.render(),t&&delete this.kdTree}reserveSpace(){return this.visible||!this.chart.options.chart.ignoreHiddenSeries}searchPoint(t,e){let{xAxis:i,yAxis:s}=this,o=this.chart.inverted;return this.searchKDTree({clientX:o?i.len-t.chartY+i.pos:t.chartX-i.pos,plotY:o?s.len-t.chartX+s.pos:t.chartY-s.pos},e,t)}buildKDTree(t){this.buildingKdTree=!0;let e=this,i=e.options,s=i.findNearestPointBy.indexOf("y")>-1?2:1;delete e.kdTree,tA(function(){e.kdTree=function t(i,s,o){let r,a,n=i?.length;if(n)return r=e.kdAxisArray[s%o],i.sort((t,e)=>(t[r]||0)-(e[r]||0)),{point:i[a=Math.floor(n/2)],left:t(i.slice(0,a),s+1,o),right:t(i.slice(a+1),s+1,o)}}(e.getValidPoints(void 0,!e.directTouch,i?.nullInteraction),s,s),e.buildingKdTree=!1},i.kdNow||t?.type==="touchstart"?0:1)}searchKDTree(t,e,i,s,o){let r=this,[a,n]=this.kdAxisArray,h=e?"distX":"dist",l=(r.options.findNearestPointBy||"").indexOf("y")>-1?2:1,d=!!r.isBubble,c=s||((t,e,i)=>{let s=t[i]||0,o=e[i]||0;return[s===o&&t.index>e.index||st=0&&r<=(s?s.len:e.plotHeight)&&o>=0&&o<=(i?i.len:e.plotWidth)}drawTracker(){let t=this,e=t.options,i=e.trackByArea,s=[].concat((i?t.areaPath:t.graphPath)||[]),o=t.chart,r=o.pointer,a=o.renderer,n=o.options.tooltip?.snap||0,h=()=>{e.enableMouseTracking&&o.hoverSeries!==t&&t.onMouseOver()},l="rgba(192,192,192,"+(iN?1e-4:.002)+")",d=t.tracker;d?d.attr({d:s}):t.graph&&(t.tracker=d=a.path(s).attr({visibility:t.visible?"inherit":"hidden",zIndex:2}).addClass(i?"highcharts-tracker-area":"highcharts-tracker-line").add(t.group),o.styledMode||d.attr({"stroke-linecap":"round","stroke-linejoin":"round",stroke:l,fill:i?l:"none","stroke-width":t.graph.strokeWidth()+(i?0:2*n)}),[t.tracker,t.markerGroup,...t.dataLabelsGroups||[]].forEach(t=>{t&&(t.addClass("highcharts-tracker").on("mouseover",h).on("mouseout",t=>{r?.onTrackerMouseOut(t)}),e.cursor&&!o.styledMode&&t.css({cursor:e.cursor}),t.on("touchstart",h))})),Q(this,"afterDrawTracker")}addPoint(t,e,i,s,o){let r,a,n=this.options,{chart:h,data:l,dataTable:d,xAxis:c}=this,p=c?.hasNames&&c.names,g=n.data,u=this.getColumn("x");e=tb(e,!0);let f={series:this};this.pointClass.prototype.applyOptions.apply(f,[t]);let m=f.x;if(a=u.length,this.requireSorting&&mm;)a--;d.setRow(f,a,!0,{addColumns:!1}),p&&f.name&&(p[m]=f.name),g?.splice(a,0,t),(r||this.processedData)&&(this.data.splice(a,0,null),this.processData()),"point"===n.legendType&&this.generatePoints(),i&&(l[0]&&l[0].remove?l[0].remove(!1):([l,g].filter(V).forEach(t=>{t.shift()}),d.deleteRows(0))),!1!==o&&Q(this,"addPoint",{point:f}),this.isDirty=!0,this.isDirtyData=!0,e&&h.redraw(s)}removePoint(t,e,i){let s=this,{chart:o,data:r,points:a,dataTable:n}=s,h=r[t],l=function(){[a?.length===r.length?a:void 0,r,s.options.data].filter(V).forEach(e=>{e.splice(t,1)}),n.deleteRows(t),h?.destroy(),s.isDirty=!0,s.isDirtyData=!0,e&&o.redraw()};iI(i,o),e=tb(e,!0),h?h.firePointEvent("remove",null,l):l()}remove(t,e,i,s){let o=this,r=o.chart;function a(){o.destroy(s),r.isDirtyLegend=r.isDirtyBox=!0,r.linkSeries(s),tb(t,!0)&&r.redraw(e)}!1!==i?Q(o,"remove",null,a):a()}update(t,e){Q(this,"update",{options:t=_(t,this.userOptions)});let i=this,s=i.chart,o=i.userOptions,r=i.initialType||i.type,a=s.options.plotOptions,n=iR[r].prototype,h=i.finishedAnimating&&{animation:!1},l={},d,c,p=iH.keepProps.slice(),g=t.type||o.type||s.options.chart.type,u=!(this.hasDerivedData||g&&g!==this.type||void 0!==t.keys||void 0!==t.pointStart||void 0!==t.pointInterval||void 0!==t.relativeXValue||t.joinBy||t.mapData||["dataGrouping","pointStart","pointInterval","pointIntervalUnit","keys"].some(t=>i.hasOptionChanged(t)));g=g||r,u?(p.push.apply(p,iH.keepPropsForPoints),!1!==t.visible&&p.push("area","graph"),i.parallelArrays.forEach(function(t){p.push(t+"Data")}),t.data&&(t.dataSorting&&q(i.options.dataSorting,t.dataSorting),this.setData(t.data,!1))):this.dataTable.modified=this.dataTable,t.dataLabels&&o.dataLabels&&(t.dataLabels=this.mergeArrays(o.dataLabels,t.dataLabels)),t=tu(o,{index:void 0===o.index?i.index:o.index,pointStart:a?.series?.pointStart??o.pointStart??i.getColumn("x")[0]},!u&&{data:i.options.data},t,h),u&&t.data&&(t.data=i.options.data),(p=["dataLabelsGroup","dataLabelsGroups","dataLabelsParentGroups","group","markerGroup","transformGroup"].concat(p)).forEach(function(t){p[t]=i[t],delete i[t]});let f=!1;if(iR[g]){if(f=g!==i.type,i.remove(!1,!1,!1,!0),f)if(s.propFromSeries(),Object.setPrototypeOf)Object.setPrototypeOf(i,iR[g].prototype);else{let t=Object.hasOwnProperty.call(i,"hcEvents")&&i.hcEvents;for(c in n)i[c]=void 0;q(i,iR[g].prototype),t?i.hcEvents=t:delete i.hcEvents}}else tE(17,!0,s,{missingModuleFor:g});if(p.forEach(function(t){i[t]=p[t]}),i.init(s,t),u&&this.points)for(let t of(!1===(d=i.options).visible?(l.graphic=1,l.dataLabel=1):(this.hasMarkerChanged(d,o)&&(l.graphic=1),i.hasDataLabels?.()||(l.dataLabel=1)),this.points))t?.series&&(t.resolveColor(),Object.keys(l).length&&t.destroyElements(l),!1===d.showInLegend&&t.legendItem&&s.legend.destroyItem(t));i.initialType=r,s.linkSeries(),s.setSortedData(),f&&i.linkedSeries.length&&(i.isDirtyData=!0),Q(this,"afterUpdate"),tb(e,!0)&&s.redraw(!!u&&void 0)}setName(t){this.name=this.options.name=this.userOptions.name=t,this.chart.isDirtyLegend=!0}hasOptionChanged(t){let e=this.chart,i=this.options[t],s=e.options.plotOptions,o=this.userOptions[t],r=tb(s?.[this.type]?.[t],s?.series?.[t]);return o&&!V(r)?i!==o:i!==tb(r,i)}onMouseOver(){let t=this.chart,e=t.hoverSeries,i=t.pointer;i?.setHoverChartIndex(),e&&e!==this&&e.onMouseOut(),this.options.events.mouseOver&&Q(this,"mouseOver"),this.setState("hover"),t.hoverSeries=this}onMouseOut(){let t=this.options,e=this.chart,i=e.tooltip,s=e.hoverPoint;e.hoverSeries=null,s&&s.onMouseOut(),this&&t.events.mouseOut&&Q(this,"mouseOut"),i&&!this.stickyTracking&&(!i.shared||this.noSharedTooltip)&&i.hide(),e.series.forEach(function(t){t.setState("",!0)})}setState(t,e){let i=this,{graph:s,options:o}=i,{inactiveOtherPoints:r,states:a}=o,n=tb(a?.[t||"normal"]?.animation,i.chart.options.chart.animation),{lineWidth:h,opacity:l}=o;if(t=t||"",i.state!==t&&([i.group,i.markerGroup,...i.dataLabelsGroups||[]].forEach(function(e){e&&(i.state&&e.removeClass("highcharts-series-"+i.state),t&&e.addClass("highcharts-series-"+t))}),i.state=t,!i.chart.styledMode)){if(a[t]?.enabled===!1)return;if(t&&(h=a[t].lineWidth||h+(a[t].lineWidthPlus||0),l=tb(a[t].opacity,l)),s&&!s.dashstyle&&tl(h))for(let t of[s,...this.zones.map(t=>t.graph)])t?.animate({"stroke-width":h},n);r||[i.group,i.markerGroup,...i.dataLabelsGroups||[],i.labelBySeries].forEach(function(t){t?.animate({opacity:l},n)})}e&&r&&i.points&&i.setAllPointsToState(t||void 0)}setAllPointsToState(t){this.points.forEach(function(e){e.setState&&e.setState(t)})}setVisible(t,e){let i=this,s=i.chart,o=s.options.chart.ignoreHiddenSeries,r=i.visible;i.visible=t=i.options.visible=i.userOptions.visible=void 0===t?!r:t;let a=t?"show":"hide";["group","markerGroup","tracker","tt"].forEach(t=>{i[t]?.[a]()}),i.dataLabelsGroups?.forEach(t=>{t?.[a]()}),(s.hoverSeries===i||s.hoverPoint?.series===i)&&i.onMouseOut(),i.legendItem&&s.legend.colorizeItem(i,t),i.isDirty=!0,i.options.stacking&&s.series.forEach(t=>{t.options.stacking&&t.visible&&(t.isDirty=!0)}),i.linkedSeries.forEach(e=>{e.setVisible(t,!1)}),o&&(s.isDirtyBox=!0),Q(i,a),!1!==e&&s.redraw()}show(){this.setVisible(!0)}hide(){this.setVisible(!1)}select(t){this.selected=t=this.options.selected=void 0===t?!this.selected:t,this.checkbox&&(this.checkbox.checked=t),Q(this,t?"select":"unselect")}shouldShowTooltip(t,e,i={}){return i.series=this,i.visiblePlotOnly=!0,this.chart.isInsidePlot(t,e,i)}drawLegendSymbol(t,e){let i=this.chart.renderer,s=this.options.legendSymbol||"rectangle",o=e.legendItem||{},{options:r,symbolHeight:a,symbolWidth:n}=t,h=r.squareSymbol,l=h?a:n,d=h?(n-a)/2:0,c=(t.baseline||0)-a+1,p=r.symbolRadius??a,g="rectangle"===s?i.rect(d,c,l,a,p):i.symbols[s]&&i.symbol(s,d,c,l,a,{r:p});g?o.symbol=g.addClass("highcharts-point").attr({zIndex:3}).add(o.group):iC[s]?.call(this,t,e)}}iH.defaultOptions={lineWidth:2,allowPointSelect:!1,crisp:!0,showCheckbox:!1,animation:{duration:1e3},enableMouseTracking:!0,events:{},marker:{enabledThreshold:2,lineColor:"#ffffff",lineWidth:0,radius:4,states:{normal:{animation:!0},hover:{animation:{duration:150},enabled:!0,radiusPlus:2,lineWidthPlus:1},select:{fillColor:"#cccccc",lineColor:"#000000",lineWidth:2}}},point:{events:{}},dataLabels:{animation:{},align:"center",borderWidth:0,defer:!0,formatter:function(){let{numberFormatter:t}=this.series.chart;return"number"!=typeof this.y?"":t(this.y,-1)},padding:5,style:{fontSize:"0.7em",fontWeight:"bold",color:"contrast",textOutline:"1px contrast"},verticalAlign:"bottom",x:0,y:0},cropThreshold:300,opacity:1,pointRange:0,softThreshold:!0,states:{normal:{animation:!0},hover:{animation:{duration:150},lineWidthPlus:1,marker:{},halo:{size:10,opacity:.25}},select:{animation:{duration:0}},inactive:{animation:{duration:150},opacity:.2}},stickyTracking:!0,turboThreshold:1e3,findNearestPointBy:"x"},iH.types=iO.seriesTypes,iH.registerType=iO.registerSeriesType,iH.keepProps=["colorIndex","eventOptions","navigatorSeries","symbolIndex","baseSeries"],iH.keepPropsForPoints=["data","isDirtyData","isDirtyCanvas","points","dataTable","processedData","xIncrement","cropped","_hasPointMarkers","hasDataLabels","nodes","layout","level","mapMap","mapData","minY","maxY","minX","maxX","transformGroups"],q(iH.prototype,{axisTypes:["xAxis","yAxis"],coll:"series",colorCounter:0,directTouch:!1,invertible:!0,isCartesian:!0,kdAxisArray:["clientX","plotY"],parallelArrays:["x","y"],pointClass:ip,requireSorting:!0,sorted:!0}),iO.series=iH;let iX=iH,{animObject:iG,setAnimation:iF}=tQ,{registerEventOptions:iY}=eV,{composed:ij,marginNames:i$}=B,{distribute:iV}=er,{format:iU}=es;class iZ{constructor(t,e){this.allItems=[],this.initialItemY=0,this.itemHeight=0,this.itemMarginBottom=0,this.itemMarginTop=0,this.itemX=0,this.itemY=0,this.lastItemY=0,this.lastLineHeight=0,this.legendHeight=0,this.legendWidth=0,this.maxItemWidth=0,this.maxLegendWidth=0,this.offsetWidth=0,this.padding=0,this.pages=[],this.symbolHeight=0,this.symbolWidth=0,this.titleHeight=0,this.totalItemWidth=0,this.widthOption=0,this.chart=t,this.setOptions(e),e.enabled&&(this.render(),iY(this,e),R(this.chart,"endResize",function(){this.legend.positionCheckboxes()})),R(this.chart,"render",()=>{this.options.enabled&&this.proximate&&(this.proximatePositions(),this.positionItems())})}setOptions(t){let e=tb(t.padding,8);this.options=t,this.chart.styledMode||(this.itemStyle=t.itemStyle,this.itemHiddenStyle=tu(this.itemStyle,t.itemHiddenStyle)),this.itemMarginTop=t.itemMarginTop,this.itemMarginBottom=t.itemMarginBottom,this.padding=e,this.initialItemY=e-5,this.symbolWidth=tb(t.symbolWidth,16),this.pages=[],this.proximate="proximate"===t.layout&&!this.chart.inverted,this.baseline=void 0}update(t,e){let i=this.chart;this.setOptions(tu(!0,this.options,t)),"events"in this.options&&iY(this,this.options),this.destroy(),i.isDirtyLegend=i.isDirtyBox=!0,tb(e,!0)&&i.redraw(),Q(this,"afterUpdate",{redraw:e})}colorizeItem(t,e){let i=t.color,{area:s,group:o,label:r,line:a,symbol:n}=t.legendItem||{};if((t instanceof iX||t instanceof ip)&&(t.color=t.options?.legendSymbolColor||i),o?.[e?"removeClass":"addClass"]("highcharts-legend-item-hidden"),!this.chart.styledMode){let{itemHiddenStyle:i={}}=this,o=i.color,{fillColor:h,fillOpacity:l,lineColor:d,marker:c}=t.options,p=t=>(!e&&(t.fill&&(t.fill=o),t.stroke&&(t.stroke=o)),t);r?.css(tu(e?this.itemStyle:i)),a?.attr(p({stroke:d||t.color})),n&&n.attr(p(c&&n.isMarker?t.pointAttribs():{fill:t.color})),s?.attr(p({fill:h||t.color,"fill-opacity":h?1:l??.75}))}t.color=i,Q(this,"afterColorizeItem",{item:t,visible:e})}positionItems(){this.allItems.forEach(this.positionItem,this),this.chart.isResizing||this.positionCheckboxes()}positionItem(t){let{group:e,x:i=0,y:s=0}=t.legendItem||{},o=this.options,r=o.symbolPadding,a=!o.rtl,n=t.checkbox;if(e?.element){let o={translateX:a?i:this.legendWidth-i-2*r-4,translateY:s},n=()=>{Q(this,"afterPositionItem",{item:t})};e[V(e.translateY)?"animate":"attr"](o,void 0,n)}n&&(n.x=i,n.y=s)}destroyItem(t){let e=t.legendItem||{};for(let t of["group","label","line","symbol"])e[t]&&(e[t]=e[t].destroy());t.checkbox=Z(t.checkbox),t.legendItem=void 0}destroy(){for(let t of this.getAllItems())this.destroyItem(t);for(let t of["clipRect","up","down","pager","nav","box","title","group"])this[t]&&(this[t]=this[t].destroy());this.display=null}positionCheckboxes(){let t,e=this.group?.alignAttr,i=this.clipHeight||this.legendHeight,s=this.titleHeight;e&&(t=e.translateY,this.allItems.forEach(function(o){let r,a=o.checkbox;a&&(r=t+s+a.y+(this.scrollOffset||0)+3,$(a,{left:e.translateX+o.checkboxOffset+a.x-20+"px",top:r+"px",display:this.proximate||r>t-6&&r1.5*k?v.height:k))}layoutItem(t){let e=this.options,i=this.padding,s="horizontal"===e.layout,o=t.itemHeight,r=this.itemMarginBottom,a=this.itemMarginTop,n=s?tb(e.itemDistance,20):0,h=this.maxLegendWidth,l=e.alignColumns&&this.totalItemWidth>h?this.maxItemWidth:t.itemWidth,d=t.legendItem||{};s&&this.itemX-i+l>h&&(this.itemX=i,this.lastLineHeight&&(this.itemY+=a+this.lastLineHeight+r),this.lastLineHeight=0),this.lastItemY=a+this.itemY+r,this.lastLineHeight=Math.max(o,this.lastLineHeight),d.x=this.itemX,d.y=this.itemY,s?this.itemX+=l:(this.itemY+=a+o+r,this.lastLineHeight=o),this.offsetWidth=this.widthOption||Math.max((s?this.itemX-i-(t.checkbox?0:n):l)+i,this.offsetWidth)}getAllItems(){let t=[];return this.chart.series.forEach(function(e){let i=e?.options;e&&tb(i.showInLegend,!V(i.linkedTo)&&void 0,!0)&&(t=t.concat(e.legendItem?.labels||("point"===i.legendType?e.data:e)))}),Q(this,"afterGetAllItems",{allItems:t}),t}getAlignment(){let t=this.options;return this.proximate?t.align.charAt(0)+"tv":t.floating?"":t.align.charAt(0)+t.verticalAlign.charAt(0)+t.layout.charAt(0)}adjustMargins(t,e){let i=this.chart,s=this.options,o=this.getAlignment();o&&[/(lth|ct|rth)/,/(rtv|rm|rbv)/,/(rbh|cb|lbh)/,/(lbv|lm|ltv)/].forEach((r,a)=>{r.test(o)&&!V(t[a])&&(i[i$[a]]=Math.max(i[i$[a]],i.legend[(a+1)%2?"legendHeight":"legendWidth"]+[1,-1,-1,1][a]*s[a%2?"x":"y"]+(s.margin??12)+e[a]+(i.titleOffset[a]||0)))})}proximatePositions(){let t,e=this.chart,i=[],s="left"===this.options.align;for(let o of(this.allItems.forEach(function(t){let o,r,a=s,n,h;t.yAxis&&(t.xAxis.options.reversed&&(a=!a),t.points&&(o=tr(a?t.points:t.points.slice(0).reverse(),function(t){return tl(t.plotY)})),r=this.itemMarginTop+t.legendItem.label.getBBox().height+this.itemMarginBottom,h=t.yAxis.top-e.plotTop,n=t.visible?(o?o.plotY:t.yAxis.height)+(h-.3*r):h+t.yAxis.height,i.push({target:n,size:r,item:t}))},this),iV(i,e.plotHeight)))t=o.item.legendItem||{},tl(o.pos)&&(t.y=e.plotTop-e.spacing[0]+o.pos)}render(){let t=this.chart,e=t.spacingBox.width,i=t.renderer,s=this.options,o=this.padding,r=this.getAllItems(),a,n,h,l=this.group,d,c=this.box;this.itemX=o,this.itemY=this.initialItemY,this.offsetWidth=0,this.lastItemY=0,this.widthOption=tw(s.width,e-o),d=e-2*o-s.x,["rm","lm"].indexOf(this.getAlignment().substring(0,2))>-1&&(d/=2),this.maxLegendWidth=this.widthOption||d,l||(this.group=l=i.g("legend").addClass(s.className||"").attr({zIndex:7}).add(),this.contentGroup=i.g().attr({zIndex:1}).add(l),this.scrollGroup=i.g().add(this.contentGroup)),this.renderTitle(),tC(r,(t,e)=>(t.options?.legendIndex||0)-(e.options?.legendIndex||0)),s.reversed&&r.reverse(),this.allItems=r,this.display=a=!!r.length,this.lastLineHeight=0,this.maxItemWidth=0,this.totalItemWidth=0,this.itemHeight=0,r.forEach(this.renderItem,this),r.forEach(this.layoutItem,this),n=(s.maxWidth?Math.min(this.widthOption||this.offsetWidth,d,tw(s.maxWidth,t.chartWidth)||1/0):this.widthOption||this.offsetWidth)+o,h=this.lastItemY+this.lastLineHeight+this.titleHeight,h=this.handleOverflow(h)+o,c||(this.box=c=i.rect().addClass("highcharts-legend-box").attr({r:s.borderRadius}).add(l)),t.styledMode||c.attr({stroke:s.borderColor,"stroke-width":s.borderWidth||0,fill:s.backgroundColor||"none"}).shadow(s.shadow),n>0&&h>0&&c[c.placed?"animate":"attr"](c.crisp.call({},{x:0,y:0,width:n,height:h},c.strokeWidth())),l[a?"show":"hide"](),t.styledMode&&"none"===l.getStyle("display")&&(n=h=0),this.legendWidth=n,this.legendHeight=h,a&&this.align(),this.proximate||this.positionItems(),Q(this,"afterRender")}align(t=this.chart.spacingBox){let e=this.chart,i=this.options,s=t.y;/(lth|ct|rth)/.test(this.getAlignment())&&e.titleOffset[0]>0?s+=e.titleOffset[0]:/(lbh|cb|rbh)/.test(this.getAlignment())&&e.titleOffset[2]>0&&(s-=e.titleOffset[2]),s!==t.y&&(t=tu(t,{y:s})),e.hasRendered||(this.group.placed=!1),this.group.align(tu(i,{width:this.legendWidth,height:this.legendHeight,verticalAlign:this.proximate?"top":i.verticalAlign}),!0,t)}handleOverflow(t){let e=this,i=this.chart,s=i.renderer,o=this.options,r=o.y,a="top"===o.verticalAlign,n=this.padding,h=o.maxHeight,l=o.navigation,d=tb(l.animation,!0),c=l.arrowSize||12,p=this.pages,g=this.allItems,u=function(t){"number"==typeof t?w.attr({height:t}):w&&(e.clipRect=w.destroy(),e.contentGroup.clip()),e.contentGroup.div&&(e.contentGroup.div.style.clip=t?"rect("+n+"px,9999px,"+(n+t)+"px,0)":"auto")},f=function(t){return e[t]=s.circle(0,0,1.3*c).translate(c/2,c/2).add(k),i.styledMode||e[t].attr("fill","rgba(0,0,0,0.0001)"),e[t]},m,x,y,b,v=i.spacingBox.height+(a?-r:r)-n,k=this.nav,w=this.clipRect;return"horizontal"!==o.layout||"middle"===o.verticalAlign||o.floating||(v/=2),h&&(v=Math.min(v,h)),p.length=0,t&&v>0&&t>v&&!1!==l.enabled?(this.clipHeight=m=Math.max(v-20-this.titleHeight-n,0),this.currentPage=tb(this.currentPage,1),this.fullHeight=t,g.forEach((t,e)=>{let i=(y=t.legendItem||{}).y||0,s=Math.round(y.label.getBBox().height),o=p.length;(!o||i-p[o-1]>m&&(x||i)!==p[o-1])&&(p.push(x||i),o++),y.pageIx=o-1,x&&b&&(b.pageIx=o-1),e===g.length-1&&i+s-p[o-1]>m&&i>p[o-1]&&(p.push(i),y.pageIx=o),i!==x&&(x=i),b=y}),w||(w=e.clipRect=s.clipRect(0,n-2,9999,0),e.contentGroup.clip(w)),u(m),k||(this.nav=k=s.g().attr({zIndex:1}).add(this.group),this.up=s.symbol("triangle",0,0,c,c).add(k),f("upTracker").on("click",function(){e.scroll(-1,d)}),this.pager=s.text("",15,10).addClass("highcharts-legend-navigation"),!i.styledMode&&l.style&&this.pager.css(l.style),this.pager.add(k),this.down=s.symbol("triangle-down",0,0,c,c).add(k),f("downTracker").on("click",function(){e.scroll(1,d)})),e.scroll(0),t=v):k&&(u(),this.nav=k.destroy(),this.scrollGroup.attr({translateY:1}),this.clipHeight=0),t}scroll(t,e){let i=this.chart,s=this.pages,o=s.length,r=this.clipHeight,a=this.options.navigation,n=this.pager,h=this.padding,l=this.currentPage+t;l>o&&(l=o),l>0&&(void 0!==e&&iF(e,i),this.nav.attr({translateX:h,translateY:r+this.padding+7+this.titleHeight,visibility:"inherit"}),[this.up,this.upTracker].forEach(function(t){t.attr({class:1===l?"highcharts-legend-nav-inactive":"highcharts-legend-nav-active"})}),n.attr({text:l+"/"+o}),[this.down,this.downTracker].forEach(function(t){t.attr({x:18+this.pager.getBBox().width,class:l===o?"highcharts-legend-nav-inactive":"highcharts-legend-nav-active"})},this),i.styledMode||(this.up.attr({fill:1===l?a.inactiveColor:a.activeColor}),this.upTracker.css({cursor:1===l?"default":"pointer"}),this.down.attr({fill:l===o?a.inactiveColor:a.activeColor}),this.downTracker.css({cursor:l===o?"default":"pointer"})),this.scrollOffset=-s[l-1]+this.initialItemY,this.scrollGroup.animate({translateY:this.scrollOffset}),this.currentPage=l,this.positionCheckboxes(),tA(()=>{Q(this,"afterScroll",{currentPage:l})},iG(tb(e,i.renderer.globalAnimation,!0)).duration))}setItemEvents(t,e,i){let s=this,o=t.legendItem||{},r=s.chart.renderer.boxWrapper,a=t instanceof ip,n=t instanceof iX,h="highcharts-legend-"+(a?"point":"series")+"-active",l=s.chart.styledMode,d=i?[e,o.symbol]:[o.group],c=e=>{s.allItems.forEach(i=>{t!==i&&[i].concat(i.linkedSeries||[]).forEach(t=>{t.setState(e,!a)})})};for(let i of d)i&&i.on("mouseover",function(){t.visible&&c("inactive"),t.setState("hover"),t.visible&&r.addClass(h),l||e.css(s.options.itemHoverStyle)}).on("mouseout",function(){s.chart.styledMode||e.css(tu(t.visible?s.itemStyle:s.itemHiddenStyle)),c(""),r.removeClass(h),t.setState()}).on("click",function(e){let i=function(){t.setVisible&&t.setVisible(),c(t.visible?"inactive":"")};r.removeClass(h),Q(s,"itemClick",{browserEvent:e,legendItem:t,context:s},i),a?t.firePointEvent("legendItemClick",{browserEvent:e}):n&&Q(t,"legendItemClick",{browserEvent:e})})}createCheckboxForItem(t){t.checkbox=Y("input",{type:"checkbox",className:"highcharts-legend-checkbox",checked:t.selected,defaultChecked:t.selected},this.options.itemCheckboxStyle,this.chart.container),R(t.checkbox,"click",function(e){let i=e.target;Q(t.series||t,"checkboxClick",{checked:i.checked,item:t},function(){t.select()})})}}(c=iZ||(iZ={})).compose=function(t){tk(ij,"Core.Legend")&&R(t,"beforeMargins",function(){this.legend=new c(this,this.options.legend)})};let i_=iZ,{animate:iK,animObject:iq,setAnimation:iJ}=tQ,{defaultOptions:iQ}=tY,{numberFormat:i0}=es,{registerEventOptions:i1}=eV,{charts:i2,doc:i3,marginNames:i5,svg:i6,win:i9}=B,{seriesTypes:i4}=iO;class i8{static chart(t,e,i){return new i8(t,e,i)}constructor(t,e,i){if(this.sharedClips={},!i3)return void tE(36,!1,this);const s=[...arguments];(td(t)||t.nodeName)&&(this.renderTo=s.shift()),this.init(s[0],s[1])}setZoomOptions(){let t=this.options.chart,e=t.zooming;this.zooming={...e,type:tb(t.zoomType,e.type),key:tb(t.zoomKey,e.key),pinchType:tb(t.pinchType,e.pinchType),singleTouch:tb(t.zoomBySingleTouch,e.singleTouch,!1),resetButton:tu(e.resetButton,t.resetZoomButton)}}init(t,e){Q(this,"init",{args:arguments},function(){let i=tu(iQ,t),s=i.chart,o=this.renderTo||s.renderTo;this.userOptions=q({},t),(this.renderTo=td(o)?i3.getElementById(o):o)||tE(13,!0,this),this.margin=[],this.spacing=[],this.labelCollectors=[],this.callback=e,this.isResizing=0,this.options=i,this.axes=[],this.series=[],this.locale=i.lang.locale??this.renderTo.closest("[lang]")?.lang,this.time=new tH(q(i.time||{},{locale:this.locale}),i.lang),i.time=this.time.options,this.numberFormatter=(s.numberFormatter||i0).bind(this),this.styledMode=s.styledMode,this.hasCartesianSeries=s.showAxes,this.index=i2.length,i2.push(this),B.chartCount++,i1(this,s),this.xAxis=[],this.yAxis=[],this.pointCount=this.colorCounter=this.symbolCounter=0,this.setZoomOptions(),Q(this,"afterInit"),this.firstRender()})}initSeries(t){let e=this.options.chart,i=t.type||e.type,s=i4[i];s||tE(17,!0,this,{missingModuleFor:i});let o=new s;return"function"==typeof o.init&&o.init(this,t),o}setSortedData(){this.getSeriesOrderByLinks().forEach(function(t){t.points||t.data||!t.enabledDataSorting||t.setData(t.options.data,!1)})}getSeriesOrderByLinks(){return this.series.concat().sort(function(t,e){return t.linkedSeries.length||e.linkedSeries.length?e.linkedSeries.length-t.linkedSeries.length:0})}orderItems(t,e=0){let i=this[t],s=this.options[t]=tT(this.options[t]).slice(),o=this.userOptions[t]=this.userOptions[t]?tT(this.userOptions[t]).slice():[];if(this.hasRendered&&(s.splice(e),o.splice(e)),i)for(let t=e,r=i.length;t=Math.max(h+r,t.pos)&&e<=Math.min(h+r+c.width,t.pos+t.len)||(u.isInsidePlot=!1)}if(!i.ignoreY&&u.isInsidePlot){let t=!s&&i.axis&&!i.axis.isXAxis&&i.axis||d&&(s?d.xAxis:d.yAxis)||{pos:a,len:1/0},e=i.paneCoordinates?t.pos+g:a+g;e>=Math.max(l+a,t.pos)&&e<=Math.min(l+a+c.height,t.pos+t.len)||(u.isInsidePlot=!1)}return Q(this,"afterIsInsidePlot",u),u.isInsidePlot}redraw(t){Q(this,"beforeRedraw");let e=this.hasCartesianSeries?this.axes:this.colorAxis||[],i=this.series,s=this.pointer,o=this.legend,r=this.userOptions.legend,a=this.renderer,n=a.isHidden(),h=[],l,d,c,p=this.isDirtyBox,g=this.isDirtyLegend,u;for(a.rootFontSize=a.boxWrapper.getStyle("font-size"),this.setResponsive&&this.setResponsive(!1),iJ(!!this.hasRendered&&t,this),n&&this.temporaryDisplay(),this.layOutTitles(!1),c=i.length;c--;)if(((u=i[c]).options.stacking||u.options.centerInCategory)&&(d=!0,u.isDirty)){l=!0;break}if(l)for(c=i.length;c--;)(u=i[c]).options.stacking&&(u.isDirty=!0);i.forEach(function(t){t.isDirty&&("point"===t.options.legendType?("function"==typeof t.updateTotals&&t.updateTotals(),g=!0):r&&(r.labelFormatter||r.labelFormat)&&(g=!0)),t.isDirtyData&&Q(t,"updatedData")}),g&&o&&o.options.enabled&&(o.render(),this.isDirtyLegend=!1),d&&this.getStacks(),e.forEach(function(t){t.updateNames(),t.setScale()}),this.getMargins(),e.forEach(function(t){t.isDirty&&(p=!0)}),e.forEach(function(t){let e=t.min+","+t.max;t.extKey!==e&&(t.extKey=e,h.push(function(){Q(t,"afterSetExtremes",q(t.eventArgs,t.getExtremes())),delete t.eventArgs})),(p||d)&&t.redraw()}),p&&this.drawChartBox(),Q(this,"predraw"),i.forEach(function(t){(p||t.isDirty)&&t.visible&&t.redraw(),t.isDirtyData=!1}),s&&s.reset(!0),a.draw(),Q(this,"redraw"),Q(this,"render"),n&&this.temporaryDisplay(!0),h.forEach(function(t){t.call()})}get(t){let e=this.series;function i(e){return e.id===t||e.options&&e.options.id===t}let s=tr(this.axes,i)||tr(this.series,i);for(let t=0;!s&&t(e.getPointsCollection().forEach(e=>{tb(e.selectedStaging,e.selected)&&t.push(e)}),t),[])}getSelectedSeries(){return this.series.filter(t=>t.selected)}setTitle(t,e,i){this.applyDescription("title",t),this.applyDescription("subtitle",e),this.applyDescription("caption",void 0),this.layOutTitles(i)}applyDescription(t,e){let i=this,s=this.options[t]=tu(this.options[t],e),o=this[t];o&&e&&(this[t]=o=o.destroy()),s&&!o&&((o=this.renderer.text(s.text,0,0,s.useHTML).attr({align:s.align,class:"highcharts-"+t,zIndex:s.zIndex||4}).css({textOverflow:"ellipsis",whiteSpace:"nowrap"}).add()).update=function(e,s){i.applyDescription(t,e),i.layOutTitles(s)},this.styledMode||o.css(q("title"===t?{fontSize:this.options.isStock?"1em":"1.2em"}:{},s.style)),o.textPxLength=o.getBBox().width,o.css({whiteSpace:s.style?.whiteSpace}),this[t]=o)}layOutTitles(t=!0){let e=[0,0,0],{options:i,renderer:s,spacingBox:o}=this;["title","subtitle","caption"].forEach(t=>{let i=this[t],r=this.options[t],a=tu(o),n=i?.textPxLength||0;if(i&&r){Q(this,"layOutTitle",{alignTo:a,key:t,textPxLength:n});let o=s.fontMetrics(i),h=o.b,l=o.h,d=r.verticalAlign||"top",c="top"===d,p=c&&r.minScale||1,g="title"===t?c?-3:0:c?e[0]+2:0,u=Math.min(a.width/n,1),f=Math.max(p,u),m=tu({y:"bottom"===d?h:g+h},r),x=(r.width||(u>p?this.chartWidth:a.width)/f)+"px";m.align??(m.align="title"===t?u{if(t!==this.container){let e=t.style.display;return t.style.display="none",[t,e]}}),e={width:to(this.renderTo,"width",!0)||0,height:to(this.renderTo,"height",!0)||0};return t.filter(Boolean).forEach(([t,e])=>{t.style.display=e}),e}getChartSize(){let t=this.options.chart,e=t.width,i=t.height,s=this.getContainerBox(),o=s.height<=1||!this.renderTo.parentElement?.style.height&&"100%"===this.renderTo.style.height;this.chartWidth=Math.max(0,e||s.width||600),this.chartHeight=Math.max(0,tw(i,this.chartWidth)||(o?400:s.height)),this.containerBox=s}temporaryDisplay(t){let e=this.renderTo,i;if(t)for(;e?.style;)e.hcOrigStyle&&($(e,e.hcOrigStyle),delete e.hcOrigStyle),e.hcOrigDetached&&(i3.body.removeChild(e),e.hcOrigDetached=!1),e=e.parentNode;else for(;e?.style&&(i3.body.contains(e)||e.parentNode||(e.hcOrigDetached=!0,i3.body.appendChild(e)),("none"===to(e,"display",!1)||e.hcOrigDetached)&&(e.hcOrigStyle={display:e.style.display,height:e.style.height,overflow:e.style.overflow},i={display:"block",overflow:"hidden"},e!==this.renderTo&&(i.height=0),$(e,i),e.offsetWidth||e.style.setProperty("display","block","important")),(e=e.parentNode)!==i3.body););}setClassName(t){this.container.className="highcharts-container "+(t||"")}getContainer(){let t,e=this.options,i=e.chart,s="data-highcharts-chart",o=tB(),r=this.renderTo,a=tv(X(r,s));tl(a)&&i2[a]&&i2[a].hasRendered&&i2[a].destroy(),X(r,s,this.index),r.innerHTML=t6.emptyHTML,i.skipClone||r.offsetWidth||this.temporaryDisplay(),this.getChartSize();let n=this.chartHeight,h=this.chartWidth;$(r,{overflow:"hidden"}),this.styledMode||(t=q({position:"relative",overflow:"hidden",width:h+"px",height:n+"px",textAlign:"left",lineHeight:"normal",zIndex:0,"-webkit-tap-highlight-color":"rgba(0,0,0,0)",userSelect:"none","touch-action":"manipulation",outline:"none",padding:"0px"},i.style||{}));let l=Y("div",{id:o},t,r);this.container=l,this.getChartSize(),h!==this.chartWidth&&(h=this.chartWidth,this.styledMode||$(l,{width:tb(i.style?.width,h+"px")})),this.containerBox=this.getContainerBox(),this._cursor=l.style.cursor;let d=i.renderer||!i6?eo.getRendererType(i.renderer):eW;if(this.renderer=new d(l,h,n,void 0,i.forExport,e.exporting?.allowHTML,this.styledMode),iJ(void 0,this),this.setClassName(i.className),this.styledMode)for(let t in e.defs)this.renderer.definition(e.defs[t]);else this.renderer.setStyle(i.style);this.renderer.chartIndex=this.index,Q(this,"afterGetContainer")}getMargins(t){let{spacing:e,margin:i,titleOffset:s}=this;this.resetMargins(),s[0]&&!V(i[0])&&(this.plotTop=Math.max(this.plotTop,s[0]+e[0])),s[2]&&!V(i[2])&&(this.marginBottom=Math.max(this.marginBottom,s[2]+e[2])),this.legend?.display&&this.legend.adjustMargins(i,e),Q(this,"getMargins"),t||this.getAxisMargins()}getAxisMargins(){let t=this,e=t.axisOffset=[0,0,0,0],i=t.colorAxis,s=t.margin,o=t=>{t.forEach(t=>{t.visible&&t.getOffset()})};t.hasCartesianSeries?o(t.axes):i?.length&&o(i),i5.forEach((i,o)=>{V(s[o])||(t[i]+=e[o])}),t.setChartSize()}getOptions(){return _(this.userOptions,iQ)}reflow(t){let e=this,i=e.containerBox,s=e.getContainerBox();delete e.pointer?.chartPosition,!e.exporting?.isPrinting&&!e.isResizing&&i&&s.width&&((s.width!==i.width||s.height!==i.height)&&(ta(e.reflowTimeout),e.reflowTimeout=tA(function(){if(e.container){e.setSize(void 0,void 0,!1);let t=e.containerBox;t&&(t.height=e.chartHeight)}},100*!!t)),e.containerBox=s)}setReflow(){let t=this,e=e=>{t.options?.chart.reflow&&t.hasLoaded&&t.reflow(e)};if("function"==typeof ResizeObserver)new ResizeObserver(e).observe(t.renderTo);else{let t=R(i9,"resize",e);R(this,"destroy",t)}}setSize(t,e,i){let s=this,o=s.renderer;s.isResizing+=1,iJ(i,s);let r=o.globalAnimation;s.oldChartHeight=s.chartHeight,s.oldChartWidth=s.chartWidth,void 0!==t&&(s.options.chart.width=t),void 0!==e&&(s.options.chart.height=e),s.getChartSize();let{chartWidth:a,chartHeight:n,scrollablePixelsX:h=0,scrollablePixelsY:l=0}=s;(s.isDirtyBox||a!==s.oldChartWidth||n!==s.oldChartHeight)&&(s.styledMode||(r?iK:$)(s.container,{width:`${a+h}px`,height:`${n+l}px`},r),s.setChartSize(!0),o.setSize(a,n,r),s.axes.forEach(function(t){t.isDirty=!0,t.setScale()}),s.isDirtyLegend=!0,s.isDirtyBox=!0,s.layOutTitles(),s.getMargins(),s.redraw(r),s.oldChartHeight=void 0,Q(s,"resize"),setTimeout(()=>{s&&Q(s,"endResize")},iq(r).duration)),s.isResizing-=1}setChartSize(t){let e,i,s,o,{chartHeight:r,chartWidth:a,inverted:n,spacing:h,renderer:l}=this,d=this.clipOffset,c=Math[n?"floor":"round"];this.plotLeft=e=Math.round(this.plotLeft),this.plotTop=i=Math.round(this.plotTop),this.plotWidth=s=Math.max(0,Math.round(a-e-(this.marginRight??0))),this.plotHeight=o=Math.max(0,Math.round(r-i-(this.marginBottom??0))),this.plotSizeX=n?o:s,this.plotSizeY=n?s:o,this.spacingBox=l.spacingBox={x:h[3],y:h[0],width:a-h[3]-h[1],height:r-h[0]-h[2]},this.plotBox=l.plotBox={x:e,y:i,width:s,height:o},d&&(this.clipBox={x:c(d[3]),y:c(d[0]),width:c(this.plotSizeX-d[1]-d[3]),height:c(this.plotSizeY-d[0]-d[2])}),t||(this.axes.forEach(function(t){t.setAxisSize(),t.setAxisTranslation()}),l.alignElements()),Q(this,"afterSetChartSize",{skipAxes:t})}resetMargins(){Q(this,"resetMargins");let t=this,e=t.options.chart,i=e.plotBorderWidth||0,s=Math.round(i)/2;["margin","spacing"].forEach(i=>{let s=e[i],o=tg(s)?s:[s,s,s,s];["Top","Right","Bottom","Left"].forEach((s,r)=>{t[i][r]=e[`${i}${s}`]??o[r]})}),i5.forEach((e,i)=>{t[e]=t.margin[i]??t.spacing[i]}),t.axisOffset=[0,0,0,0],t.clipOffset=[s,s,s,s],t.plotBorderWidth=i}drawChartBox(){let t=this.options.chart,e=this.renderer,i=this.chartWidth,s=this.chartHeight,o=this.styledMode,r=this.plotBGImage,a=t.backgroundColor,n=t.plotBackgroundColor,h=t.plotBackgroundImage,l=this.plotLeft,d=this.plotTop,c=this.plotWidth,p=this.plotHeight,g=this.plotBox,u=this.clipRect,f=this.clipBox,m=this.chartBackground,x=this.plotBackground,y=this.plotBorder,b,v,k,w="animate";m||(this.chartBackground=m=e.rect().addClass("highcharts-background").add(),w="attr"),o?b=v=m.strokeWidth():(v=(b=t.borderWidth||0)+8*!!t.shadow,k={fill:a||"none"},(b||m["stroke-width"])&&(k.stroke=t.borderColor,k["stroke-width"]=b),m.attr(k).shadow(t.shadow)),m[w]({x:v/2,y:v/2,width:i-v-b%2,height:s-v-b%2,r:t.borderRadius}),w="animate",x||(w="attr",this.plotBackground=x=e.rect().addClass("highcharts-plot-background").add()),x[w](g),!o&&(x.attr({fill:n||"none"}).shadow(t.plotShadow),h&&(r?(h!==r.attr("href")&&r.attr("href",h),r.animate(g)):this.plotBGImage=e.image(h,l,d,c,p).add())),u?u.animate({width:f.width,height:f.height}):this.clipRect=e.clipRect(f),w="animate",y||(w="attr",this.plotBorder=y=e.rect().addClass("highcharts-plot-border").attr({zIndex:1}).add()),o||y.attr({stroke:t.plotBorderColor,"stroke-width":t.plotBorderWidth||0,fill:"none"}),y[w](y.crisp(g,-y.strokeWidth())),this.isDirtyBox=!1,Q(this,"afterDrawChartBox")}propFromSeries(){let t,e,i,s=this,o=s.options.chart,r=s.options.series;["inverted","angular","polar"].forEach(function(a){for(e=i4[o.type],i=o[a]||e&&e.prototype[a],t=r?.length;!i&&t--;)(e=i4[r[t].type])&&e.prototype[a]&&(i=!0);s[a]=i})}linkSeries(t){let e=this,i=e.series;i.forEach(function(t){t.linkedSeries.length=0}),i.forEach(function(t){let{linkedTo:s}=t.options,o=td(s)&&(":previous"===s?i[t.index-1]:e.get(s));o&&o.linkedParent!==t&&(o.linkedSeries.push(t),t.linkedParent=o,o.enabledDataSorting&&t.setDataSortingOptions(),t.visible=t.options.visible??o.options.visible??t.visible)}),Q(this,"afterLinkSeries",{isUpdating:t})}renderSeries(){this.series.forEach(function(t){t.translate(),t.render()})}render(){let t=this.axes,e=this.colorAxis,i=this.renderer,s=this.options.chart.axisLayoutRuns||2,o=t=>{t.forEach(t=>{t.visible&&t.render()})},r=0,a=!0,n,h=0;for(let e of(this.setTitle(),Q(this,"beforeMargins"),this.getStacks?.(),this.getMargins(!0),this.setChartSize(),t)){let{options:t}=e,{labels:i}=t;if(this.hasCartesianSeries&&e.horiz&&e.visible&&i.enabled&&e.series.length&&"colorAxis"!==e.coll&&!this.polar){r=t.tickLength,e.createGroups();let s=new eZ(e,0,"",!0),o=s.createLabel("x",i);if(s.destroy(),o&&tb(i.reserveSpace,!tl(t.crossing))&&(r=o.getBBox().height+i.distance+Math.max(t.offset||0,0)),r){o?.destroy();break}}}for(this.plotHeight=Math.max(this.plotHeight-r,0);(a||n||s>1)&&h(h?1:s[1]),n=i/this.plotHeight>(h?1:s[0]),h++}this.drawChartBox(),this.hasCartesianSeries?o(t):e?.length&&o(e),this.seriesGroup||(this.seriesGroup=i.g("series-group").attr({zIndex:3}).shadow(this.options.chart.seriesGroupShadow).add()),this.renderSeries(),this.addCredits(),this.setResponsive&&this.setResponsive(),this.hasRendered=!0}addCredits(t){let e=this,i=tu(!0,this.options.credits,t);i.enabled&&!this.credits&&(this.credits=this.renderer.text(i.text+(this.mapCredits||""),0,0).addClass("highcharts-credits").on("click",function(t){Q(e,"creditsClick",t,()=>{i.href&&(i9.location.href=i.href)})}).attr({align:i.position.align,zIndex:8}),i.events?.click&&R(e,"creditsClick",i.events.click),e.styledMode||this.credits.css(i.style),this.credits.add().align(i.position),this.credits.update=function(t){e.credits=e.credits.destroy(),e.addCredits(t)})}destroy(){let t,e=this,i=e.axes,s=e.series,o=e.container,r=o?.parentNode;for(Q(e,"destroy"),e.renderer.forExport?K(i2,e):i2[e.index]=void 0,B.chartCount--,e.renderTo.removeAttribute("data-highcharts-chart"),tS(e),t=i.length;t--;)i[t]=i[t].destroy();for(this.scroller?.destroy?.(),t=s.length;t--;)s[t]=s[t].destroy();["title","subtitle","chartBackground","plotBackground","plotBGImage","plotBorder","seriesGroup","clipRect","credits","pointer","rangeSelector","legend","resetZoomButton","tooltip","renderer"].forEach(t=>{e[t]=e[t]?.destroy?.()}),o&&(o.innerHTML=t6.emptyHTML,tS(o),r&&Z(o)),tm(e,function(t,i){delete e[i]})}firstRender(){let t=this,e=t.options;t.getContainer(),t.resetMargins(),t.setChartSize(),t.propFromSeries(),t.createAxes();let i=tc(e.series)?e.series:[];e.series=[],i.forEach(function(e){t.initSeries(e)}),t.linkSeries(),t.setSortedData(),Q(t,"beforeRender"),t.render(),t.pointer?.getChartPosition(),t.renderer.asyncCounter||t.hasLoaded||t.onload(),t.temporaryDisplay(!0)}onload(){this.callbacks.concat([this.callback]).forEach(function(t){t&&void 0!==this.index&&t.apply(this,[this])},this),Q(this,"load"),Q(this,"render"),V(this.index)&&this.setReflow(),this.warnIfA11yModuleNotLoaded(),this.warnIfCSSNotLoaded(),this.hasLoaded=!0}warnIfA11yModuleNotLoaded(){let{options:t,title:e}=this;t&&!this.accessibility&&(this.renderer.boxWrapper.attr({role:"img","aria-label":(e?.element.textContent||"").replace(/{t[e]&&(tT(t[e]).forEach((t,s)=>{let o;if(!t)return;let r=V(t.id);r&&(o=n.get(t.id)),!o&&n[e]&&(o=n[e][tb(t.index,s)])&&(r&&V(o.options.id)||o.options.isInternal)&&(o=void 0),o&&o.coll===e&&(o.update(t,!1),i&&(o.touched=!0)),!o&&i&&n.collectionsWithInit[e]&&(n.collectionsWithInit[e][0].apply(n,[t].concat(n.collectionsWithInit[e][1]||[]).concat([!1])).touched=!0)}),i&&n[e].forEach(t=>{t.touched||t.options.isInternal?delete t.touched:d.push(t)}))}),d.forEach(t=>{t.chart&&t.remove&&t.remove(!1)}),o&&n.axes.forEach(function(t){t.update({},!1)}),r&&n.getSeriesOrderByLinks().forEach(function(t){t.chart&&t.update({},!1)},this);let p=c?.width,g=c&&(td(c.height)?tw(c.height,p||n.chartWidth):c.height);a||tl(p)&&p!==n.chartWidth||tl(g)&&g!==n.chartHeight?n.setSize(p,g,s):tb(e,!0)&&n.redraw(s),Q(n,"afterUpdate",{options:t,redraw:e,animation:s})}setSubtitle(t,e){this.applyDescription("subtitle",t),this.layOutTitles(e)}setCaption(t,e){this.applyDescription("caption",t),this.layOutTitles(e)}showResetZoom(){let t=this,e=iQ.lang,i=t.zooming.resetButton,s=i.theme,o="chart"===i.relativeTo||"spacingBox"===i.relativeTo?null:"plotBox";function r(){t.zoomOut()}Q(this,"beforeShowResetZoom",null,function(){t.resetZoomButton=t.renderer.button(e.resetZoom,null,null,r,s).attr({align:i.position.align,title:e.resetZoomTitle}).addClass("highcharts-reset-zoom").add().align(i.position,!1,o)}),Q(this,"afterShowResetZoom")}zoomOut(){Q(this,"selection",{resetSelection:!0},()=>this.transform({reset:!0,trigger:"zoom"}))}pan(t,e){let i=this,s="object"==typeof e?e:{enabled:e,type:"x"},o=s.type,r=o&&i[({x:"xAxis",xy:"axes",y:"yAxis"})[o]].filter(t=>t.options.panningEnabled&&!t.options.isInternal),a=i.options.chart;a?.panning&&(a.panning=s),Q(this,"pan",{originalEvent:t},()=>{i.transform({axes:r,event:t,to:{x:t.chartX-(i.mouseDownX||0),y:t.chartY-(i.mouseDownY||0)},trigger:"pan"}),$(i.container,{cursor:"move"})})}transform(t){let{axes:e=this.axes,event:i,from:s={},reset:o,selection:r,to:a={},trigger:n,allowResetButton:h=!0}=t,{inverted:l,time:d}=this;this.hoverPoints?.forEach(t=>t.setState()),Q(this,"transform",t);let c=t.hasZoomed||!1,p,g;for(let t of e){let{horiz:e,len:u,minPointOffset:f=0,options:m,reversed:x}=t,y=e?"width":"height",b=e?"x":"y",v=tb(a[y],t.len),k=tb(s[y],t.len),w=10>Math.abs(v)?1:v/k,M=(s[b]||0)+k/2-t.pos,S=M-((a[b]??t.pos)+v/2-t.pos)/w,T=x&&!l||!x&&l?-1:1;if(!o&&(M<0||M>t.len))continue;let C=t.chart.polar||t.isOrdinal?0:f*T||0,A=t.toValue(S,!0),P=t.toValue(S+u/w,!0),L=A+C,O=P-C,E=t.allExtremes;if(r&&r[t.coll].push({axis:t,min:Math.min(A,P),max:Math.max(A,P)}),L>O&&([L,O]=[O,L]),1===w&&!o&&"yAxis"===t.coll&&!E){for(let e of t.series){let t=e.getExtremes(e.getProcessedData(!0).modified.getColumn(e.pointValKey||"y")||[],!0);E??(E={dataMin:Number.MAX_VALUE,dataMax:-Number.MAX_VALUE}),tl(t.dataMin)&&tl(t.dataMax)&&(E.dataMin=Math.min(t.dataMin,E.dataMin),E.dataMax=Math.max(t.dataMax,E.dataMax))}t.allExtremes=E}let{dataMin:I,dataMax:D,min:B,max:N}=q(t.getExtremes(),E||{}),z=d.parse(m.min),R=d.parse(m.max),W=I??z,H=D??R,X=O-L,G=t.categories?0:Math.min(X,H-W),F=W-G*(V(z)?0:m.minPadding),Y=H+G*(V(R)?0:m.maxPadding),j=t.allowZoomOutside||1===w||"zoom"!==n&&w>1,$=Math.min(z??F,F,j?B:F),U=Math.max(R??Y,Y,j?N:Y);(!t.isOrdinal||1!==w||o)&&(L<$&&(L=$,w>=1&&(O=L+X)),O>U&&(O=U,w>=1&&(L=O-X)),(o||t.series.length&&(L!==B||O!==N)&&L>=$&&O<=U)&&(r?r[t.coll].push({axis:t,min:L,max:O}):(t.isPanning="zoom"!==n,t.isPanning&&"mousewheel"!==n&&(g=!0),t.setExtremes(o?void 0:L,o?void 0:O,!1,!1,{move:S,trigger:n,scale:w}),!o&&(L>$||O{delete t.selection,t.trigger="zoom",this.transform(t)}):(!p||g||this.resetZoomButton?!p&&this.resetZoomButton&&(this.resetZoomButton=this.resetZoomButton.destroy()):this.showResetZoom(),this.redraw("zoom"===n&&(this.options.chart.animation??this.pointCount<100)))),c}}q(i8.prototype,{callbacks:[],collectionsWithInit:{xAxis:[i8.prototype.addAxis,[!0]],yAxis:[i8.prototype.addAxis,[!1]],series:[i8.prototype.addSeries]},collectionsWithUpdate:["xAxis","yAxis","series"],propsRequireDirtyBox:["backgroundColor","borderColor","borderWidth","borderRadius","plotBackgroundColor","plotBackgroundImage","plotBorderColor","plotBorderWidth","plotShadow","shadow"],propsRequireReflow:["margin","marginTop","marginRight","marginBottom","marginLeft","spacing","spacingTop","spacingRight","spacingBottom","spacingLeft"],propsRequireUpdateSeries:["chart.inverted","chart.polar","chart.ignoreHiddenSeries","chart.type","colors","plotOptions","time","tooltip"]});let{stop:i7}=tQ,{composed:st}=B;function se(){let t=this.scrollablePlotArea;(this.scrollablePixelsX||this.scrollablePixelsY)&&!t&&(this.scrollablePlotArea=t=new ss(this)),t?.applyFixed()}function si(){this.chart.scrollablePlotArea&&(this.chart.scrollablePlotArea.isDirty=!0)}class ss{static compose(t,e,i){tk(st,this.compose)&&(R(t,"afterInit",si),R(e,"afterSetChartSize",t=>this.afterSetSize(t.target,t)),R(e,"render",se),R(i,"show",si))}static afterSetSize(t,e){let i,s,o,{minWidth:r,minHeight:a}=t.options.chart.scrollablePlotArea||{},{clipBox:n,plotBox:h,inverted:l,renderer:d}=t;if(!d.forExport)if(r?(t.scrollablePixelsX=i=Math.max(0,r-t.chartWidth),i&&(t.scrollablePlotBox=tu(t.plotBox),h.width=t.plotWidth+=i,n[l?"height":"width"]+=i,o=!0)):a&&(t.scrollablePixelsY=s=Math.max(0,a-t.chartHeight),V(s)&&(t.scrollablePlotBox=tu(t.plotBox),h.height=t.plotHeight+=s,n[l?"width":"height"]+=s,o=!1)),V(o)){if(!e.skipAxes)for(let e of t.axes)(e.horiz===o||t.hasParallelCoordinates&&"yAxis"===e.coll)&&(e.setAxisSize(),e.setAxisTranslation())}else delete t.scrollablePlotBox}constructor(t){let e;const i=t.options.chart,s=eo.getRendererType(),o=i.scrollablePlotArea||{},r=this.moveFixedElements.bind(this),a={WebkitOverflowScrolling:"touch",overflowX:"hidden",overflowY:"hidden"};t.scrollablePixelsX&&(a.overflowX="auto"),t.scrollablePixelsY&&(a.overflowY="auto"),this.chart=t;const n=this.parentDiv=Y("div",{className:"highcharts-scrolling-parent"},{position:"relative"},t.renderTo),h=this.scrollingContainer=Y("div",{className:"highcharts-scrolling"},a,n),l=this.innerContainer=Y("div",{className:"highcharts-inner-container"},void 0,h),d=this.fixedDiv=Y("div",{className:"highcharts-fixed"},{position:"absolute",overflow:"hidden",pointerEvents:"none",zIndex:(i.style?.zIndex||0)+2,top:0},void 0,!0),c=this.fixedRenderer=new s(d,t.chartWidth,t.chartHeight,i.style);this.mask=c.path().attr({fill:i.backgroundColor||"#fff","fill-opacity":o.opacity??.85,zIndex:-1}).addClass("highcharts-scrollable-mask").add(),h.parentNode.insertBefore(d,h),$(t.renderTo,{overflow:"visible"}),R(t,"afterShowResetZoom",r),R(t,"afterApplyDrilldown",r),R(t,"afterLayOutTitles",r),R(h,"scroll",()=>{let{pointer:i,hoverPoint:s}=t;i&&(delete i.chartPosition,s&&(e=s),i.runPointActions(void 0,e,!0))}),l.appendChild(t.container)}applyFixed(){let{chart:t,fixedRenderer:e,isDirty:i,scrollingContainer:s}=this,{axisOffset:o,chartWidth:r,chartHeight:a,container:n,plotHeight:h,plotLeft:l,plotTop:d,plotWidth:c,scrollablePixelsX:p=0,scrollablePixelsY:g=0}=t,{scrollPositionX:u=0,scrollPositionY:f=0}=t.options.chart.scrollablePlotArea||{},m=r+p,x=a+g;e.setSize(r,a),(i??!0)&&(this.isDirty=!1,this.moveFixedElements()),i7(t.container),$(n,{width:`${m}px`,height:`${x}px`}),t.renderer.boxWrapper.attr({width:m,height:x,viewBox:["0 0",m,x].join(" ")}),t.chartBackground?.attr({width:m,height:x}),$(s,{width:`${r}px`,height:`${a}px`}),V(i)||(s.scrollLeft=p*u,s.scrollTop=g*f);let y=d-o[0]-1,b=l-o[3]-1,v=d+h+o[2]+1,k=l+c+o[1]+1,w=l+c-p,M=d+h-g,S=[["M",0,0]];p?S=[["M",0,y],["L",l-1,y],["L",l-1,v],["L",0,v],["Z"],["M",w,y],["L",r,y],["L",r,v],["L",w,v],["Z"]]:g&&(S=[["M",b,0],["L",b,d-1],["L",k,d-1],["L",k,0],["Z"],["M",b,M],["L",b,a],["L",k,a],["L",k,M],["Z"]]),"adjustHeight"!==t.redrawTrigger&&this.mask.attr({d:S})}moveFixedElements(){let t,{container:e,inverted:i,scrollablePixelsX:s,scrollablePixelsY:o}=this.chart,r=this.fixedRenderer,a=ss.fixedSelectors.slice();if(s&&!i?t=".highcharts-yaxis":s&&i||o&&!i?t=".highcharts-xaxis":o&&i&&(t=".highcharts-yaxis"),t&&!(this.chart.hasParallelCoordinates&&".highcharts-yaxis"===t))for(let e of[`${t}:not(.highcharts-radial-axis)`,`${t}-labels:not(.highcharts-radial-axis-labels)`])tk(a,e);else for(let t of[".highcharts-xaxis",".highcharts-yaxis"])for(let e of[`${t}:not(.highcharts-radial-axis)`,`${t}-labels:not(.highcharts-radial-axis-labels)`])K(a,e);for(let t of a)[].forEach.call(e.querySelectorAll(t),t=>{(t.namespaceURI===r.SVG_NS?r.box:r.box.parentNode).appendChild(t),t.style.pointerEvents="auto"})}}ss.fixedSelectors=[".highcharts-breadcrumbs-group",".highcharts-contextbutton",".highcharts-caption",".highcharts-credits",".highcharts-drillup-button",".highcharts-legend",".highcharts-legend-checkbox",".highcharts-navigator-series",".highcharts-navigator-xaxis",".highcharts-navigator-yaxis",".highcharts-navigator",".highcharts-range-selector-group",".highcharts-reset-zoom",".highcharts-scrollbar",".highcharts-subtitle",".highcharts-title"];let{format:so}=es,{series:sr}=iO,sa=class{constructor(t,e,i,s,o){const r=t.chart.inverted,a=t.reversed;this.axis=t;const n=this.isNegative=!!i!=!!a;this.options=e=e||{},this.x=s,this.total=null,this.cumulative=null,this.points={},this.hasValidPoints=!1,this.stack=o,this.leftCliff=0,this.rightCliff=0,this.alignOptions={align:e.align||(r?n?"left":"right":"center"),verticalAlign:e.verticalAlign||(r?"middle":n?"bottom":"top"),y:e.y,x:e.x},this.textAlign=e.textAlign||(r?n?"right":"left":"center")}destroy(){U(this,this.axis)}render(t){let e=this.axis.chart,i=this.options,s=i.format,o=(s?so(s,this,e):i.formatter?.call(this,this))||"";if(this.label)this.label.attr({text:o,visibility:"hidden"});else{this.label=e.renderer.label(o,null,void 0,i.shape,void 0,void 0,i.useHTML,!1,"stack-labels");let s={r:i.borderRadius||0,text:o,padding:tb(i.padding,5),visibility:"hidden"};e.styledMode||(s.fill=i.backgroundColor,s.stroke=i.borderColor,s["stroke-width"]=i.borderWidth,this.label.css(i.style||{})),this.label.attr(s),this.label.added||this.label.add(t)}this.label.labelrank=e.plotSizeY,Q(this,"afterRender")}setOffset(t,e,i,s,o,r){let{alignOptions:a,axis:n,label:h,options:l,textAlign:d}=this,c=n.chart,p=this.getStackBox({xOffset:t,width:e,boxBottom:i,boxTop:s,defaultX:o,xAxis:r}),{verticalAlign:g}=a;if(h&&p){let t=h.getBBox(void 0,0),e=h.padding,i="justify"===tb(l.overflow,"justify"),s;a.x=l.x||0,a.y=l.y||0;let{x:o,y:r}=this.adjustStackPosition({labelBox:t,verticalAlign:g,textAlign:d});p.x-=o,p.y-=r,h.align(a,!1,p),(s=c.isInsidePlot(h.alignAttr.x+a.x+o,h.alignAttr.y+a.y+r))||(i=!1),i&&sr.prototype.justifyDataLabel.call(n,h,a,h.alignAttr,t,p),h.attr({x:h.alignAttr.x,y:h.alignAttr.y,rotation:l.rotation,rotationOriginX:t.width*tt(l.textAlign||"center"),rotationOriginY:t.height/2}),tb(!i&&l.crop,!0)&&(s=tl(h.x)&&tl(h.y)&&c.isInsidePlot(h.x-e+(h.width||0),h.y)&&c.isInsidePlot(h.x+e,h.y)),h[s?"show":"hide"]()}Q(this,"afterSetOffset",{xOffset:t,width:e})}adjustStackPosition({labelBox:t,verticalAlign:e,textAlign:i}){return{x:t.width/2+t.width/2*(2*tt(i)-1),y:t.height/2*2*(1-tt(e))}}getStackBox(t){let e=this.axis,i=e.chart,{boxTop:s,defaultX:o,xOffset:r,width:a,boxBottom:n}=t,h=e.stacking.usePercentage?100:tb(s,this.total,0),l=e.toPixels(h),d=t.xAxis||i.xAxis[0],c=tb(o,d.translate(this.x))+r,p=Math.abs(l-e.toPixels(n||tl(e.min)&&e.logarithmic&&e.logarithmic.lin2log(e.min)||0)),g=i.inverted,u=this.isNegative;return g?{x:(u?l:l-p)-i.plotLeft,y:d.height-c-a+d.top-i.plotTop,width:p,height:a}:{x:c+d.transB-i.plotLeft,y:(u?l-p:l)-i.plotTop,width:a,height:p}}},{getDeferredAnimation:sn}=tQ,{series:{prototype:sh}}=iO;function sl(){let t=this.inverted;this.axes.forEach(t=>{t.stacking?.stacks&&t.hasVisibleSeries&&(t.stacking.oldStacks=t.stacking.stacks)}),this.series.forEach(e=>{let i=e.xAxis?.options||{};e.options.stacking&&e.reserveSpace()&&(e.stackKey=[e.type,tb(e.options.stack,""),t?i.top:i.left,t?i.height:i.width].join(","))})}function sd(){let t=this.stacking;if(t){let e=t.stacks;tm(e,(t,i)=>{U(t),delete e[i]}),t.stackTotalGroup?.destroy()}}function sc(){this.stacking||(this.stacking=new sx(this))}function sp(t,e,i,s){return!V(t)||t.x!==e||s&&t.stackKey!==s?t={x:e,index:0,key:s,stackKey:s}:t.index++,t.key=[i,e,t.index].join(","),t}function sg(){let t,e=this,i=e.yAxis,s=e.stackKey||"",o=i.stacking.stacks,r=e.getColumn("x",!0),a=e.options.stacking,n=e[a+"Stacker"];n&&[s,"-"+s].forEach(i=>{let s=r.length,a,h,l;for(;s--;)a=r[s],t=e.getStackIndicator(t,a,e.index,i),h=o[i]?.[a],(l=h?.points[t.key||""])&&n.call(e,l,h,s)})}function su(t,e,i){let s=e.total?100/e.total:0;t[0]=F(t[0]*s),t[1]=F(t[1]*s),this.stackedYData[i]=t[1]}function sf(t){(this.is("column")||this.is("columnrange"))&&(this.options.centerInCategory&&this.chart.series.length>1?sh.setStackedPoints.call(this,t,"group"):t.stacking.resetStacks())}function sm(t,e){let i,s,o,r,a,n,h,l=e||this.options.stacking;if(!l||!this.reserveSpace()||(({group:"xAxis"})[l]||"yAxis")!==t.coll)return;let d=this.getColumn("x",!0),c=this.getColumn(this.pointValKey||"y",!0),p=[],g=c.length,u=this.options,f=u.threshold||0,m=u.startFromThreshold?f:0,x=u.stack,y=e?`${this.type},${l}`:this.stackKey||"",b="-"+y,v=this.negStacks,k=t.stacking,w=k.stacks,M=k.oldStacks;for(k.stacksTouched+=1,h=0;h0&&!1===this.singleStacks&&(o.points[n][0]=o.points[this.index+","+e+",0"][0])):(delete o.points[n],delete o.points[this.index]);let S=o.total||0;"percent"===l?(r=s?y:b,S=v&&w[r]?.[e]?(r=w[r][e]).total=Math.max(r.total||0,S)+Math.abs(u):F(S+Math.abs(u))):"group"===l?tl(g)&&S++:S=F(S+u),"group"===l?o.cumulative=(S||1)-1:o.cumulative=F(tb(o.cumulative,m)+u),o.total=S,null!==g&&(o.points[n].push(o.cumulative),p[h]=o.cumulative,o.hasValidPoints=!0)}"percent"===l&&(k.usePercentage=!0),"group"!==l&&(this.stackedYData=p),k.oldStacks={}}class sx{constructor(t){this.oldStacks={},this.stacks={},this.stacksTouched=0,this.axis=t}buildStacks(){let t,e,i=this.axis,s=i.series,o="xAxis"===i.coll,r=i.options.reversedStacks,a=s.length;for(this.resetStacks(),this.usePercentage=!1,e=a;e--;)t=s[r?e:a-e-1],o&&t.setGroupedPoints(i),t.setStackedPoints(i);if(!o)for(e=0;e{tm(t,t=>{t.cumulative=t.total})}))}resetStacks(){tm(this.stacks,t=>{tm(t,(e,i)=>{tl(e.touched)&&e.touched{tm(t,t=>{t.render(r)})}),r.animate({opacity:1},o)}}(T||(T={})).compose=function(t,e,i){let s=e.prototype,o=i.prototype;s.getStacks||(R(t,"init",sc),R(t,"destroy",sd),s.getStacks=sl,o.getStackIndicator=sp,o.modifyStacks=sg,o.percentStacker=su,o.setGroupedPoints=sf,o.setStackedPoints=sm)};let sy=T;class sb extends iX{drawGraph(){let t=this.options,e=(this.gappedPath||this.getGraphPath).call(this),i=this.chart.styledMode;[this,...this.zones].forEach((s,o)=>{let r,a=s.graph,n=a?"animate":"attr",h=s.dashStyle||t.dashStyle;if(a?(a.endX=this.preventGraphAnimation?null:e.xMap,a.animate({d:e})):e.length&&(s.graph=a=this.chart.renderer.path(e).addClass("highcharts-graph"+(o?` highcharts-zone-graph-${o-1} `:" ")+(o&&s.className||"")).attr({zIndex:1}).add(this.group)),a&&!i&&(r={stroke:!o&&t.lineColor||s.color||this.color||"#cccccc","stroke-width":t.lineWidth||0,fill:this.fillGraph&&this.color||"none"},h?r.dashstyle=h:"square"!==t.linecap&&(r["stroke-linecap"]=r["stroke-linejoin"]="round"),a[n](r),t.shadow)){let e=this.chart.inverted,i={filterUnits:"userSpaceOnUse"},s=tg(t.shadow)?tu(e?{}:i,t.shadow):!!e||i;a.shadow(s)}a&&(a.startX=e.xMap,a.isArea=e.isArea)})}getGraphPath(t,e,i){let s=this,o=s.options,r=[],a=[],n,h=o.step,l=(t=t||s.points).reversed;return l&&t.reverse(),(h=({right:1,center:2})[h]||h&&3)&&l&&(h=4-h),(t=this.getValidPoints(t,!1,o.nullInteraction||!(o.connectNulls&&!e&&!i))).forEach(function(l,d){let c,p=l.plotX,g=l.plotY,u=t[d-1],f=l.isNull||"number"!=typeof g;(l.leftCliff||u?.rightCliff)&&!i&&(n=!0),f&&!V(e)&&d>0?n=!o.connectNulls:f&&!e?n=!0:(0===d||n?c=[["M",l.plotX,l.plotY]]:s.getPointSpline?c=[s.getPointSpline(t,l,d)]:h?(c=1===h?[["L",u.plotX,g]]:2===h?[["L",(u.plotX+p)/2,u.plotY],["L",(u.plotX+p)/2,g]]:[["L",p,u.plotY]]).push(["L",p,g]):c=[["L",p,g]],a.push(l.x),h&&(a.push(l.x),2===h&&a.push(l.x)),r.push.apply(r,c),n=!1)}),r.xMap=a,s.graphPath=r,r}}sb.defaultOptions=tu(iX.defaultOptions,{legendSymbol:"lineMarker"}),iO.registerSeriesType("line",sb);let{seriesTypes:{line:sv}}=iO;class sk extends sv{drawGraph(){this.areaPath=[],super.drawGraph.apply(this);let{areaPath:t,options:e}=this;[this,...this.zones].forEach((i,s)=>{let o={},r=i.fillColor||e.fillColor,a=i.area,n=a?"animate":"attr";a?(a.endX=this.preventGraphAnimation?null:t.xMap,a.animate({d:t})):(o.zIndex=0,(a=i.area=this.chart.renderer.path(t).addClass("highcharts-area"+(s?` highcharts-zone-area-${s-1} `:" ")+(s&&i.className||"")).add(this.group)).isArea=!0),this.chart.styledMode||(o.fill=r||i.color||this.color,o["fill-opacity"]=r?1:e.fillOpacity??.75,a.css({pointerEvents:this.stickyTracking?"none":"auto"})),a[n](o),a.startX=t.xMap,a.shiftUnit=e.step?2:1})}getGraphPath(t){let e,i,s,o=sv.prototype.getGraphPath,r=this.options,a=r.stacking,n=this.yAxis,h=[],l=[],d=this.index,c=n.stacking.stacks[this.stackKey],p=r.threshold,g=Math.round(n.getThreshold(r.threshold)),u=tb(r.connectNulls,"percent"===a),f=function(i,s,o){let r=t[i],u=t[s],f=a&&c[r.x].points[d],m=r[o+"Null"]||0,x=r[o+"Cliff"]||0,y,b,v=!0;f&&(x||m)?(y=(m?f[0]:f[1])+x,b=f[0]+x,v=!!m):!a&&u&&(u.isNull||!V(u.plotY))&&(y=b=p),void 0!==y&&(l.push({plotX:e,plotY:null===y?g:n.getThreshold(y),isNull:v,isCliff:!0}),h.push({plotX:e,plotY:null===b?g:n.getThreshold(b),doCurve:!1}))};t=t||this.points,a&&(t=this.getStackPoints(t));for(let o=0,r=t.length;o1&&a&&l.some(t=>t.isCliff)&&(b.hasStackedCliffs=v.hasStackedCliffs=!0),b.xMap=m.xMap,this.areaPath=b,v}getStackPoints(t){let e=this,i=[],s=[],o=this.xAxis,r=this.yAxis,a=r.stacking.stacks[this.stackKey],n={},h=r.series,l=h.length,d=r.options.reversedStacks?1:-1,c=h.indexOf(e),p=r.getThreshold(e.options.threshold||0);if(t=t||this.points,this.options.stacking){for(let e=0;et.visible);s.forEach(function(t,u){let f=0,m,x;if(n[t]&&!n[t].isNull)i.push(n[t]),[-1,1].forEach(function(i){let o=1===i?"rightNull":"leftNull",r=a[s[u+i]],p=0;if(r){let i=c;for(;i>=0&&i=0&&ei&&o>h?(o=Math.max(i,h),a=2*h-o):op&&a>h?(a=Math.max(p,h),o=2*h-a):a1){let o=this.xAxis.series.filter(t=>t.visible).map(t=>t.index),r=0,a=0;tm(this.xAxis.stacking?.stacks,t=>{let e="number"==typeof i.x?t[i.x.toString()]?.points:void 0,s=e?.[this.index],n={};if(e&&tc(s)){let t=this.index,i=Object.keys(e).filter(t=>!t.match(",")&&e[t]&&e[t].length>1).map(parseFloat).filter(t=>-1!==o.indexOf(t)).filter(e=>{let i=this.chart.series[e].options,s=i.stacking&&i.stack;if(V(s)){if(tl(n[s]))return t===e&&(t=n[s]),!1;n[s]=e}return!0}).sort((t,e)=>e-t);r=i.indexOf(t),a=i.length}}),r=this.xAxis.reversed?a-1-r:r;let n=(a-1)*s.paddedWidth+e;t=(i.plotX||0)+n/2-e-r*s.paddedWidth}return t}translate(){let t=this,e=t.chart,i=t.options,s=t.dense=t.closestPointRange*t.xAxis.transA<2,o=t.borderWidth=i.borderWidth??+!s,r=t.xAxis,a=t.yAxis,n=i.threshold,h=i.minPointLength??5,l=t.getColumnMetrics(),d=l.width,c=t.pointXOffset=l.offset,p=t.dataMin,g=t.dataMax,u=t.translatedThreshold=a.getThreshold(n),f=t.barW=Math.max(d,1+2*o);i.pointPadding&&i.crisp&&(f=Math.ceil(f)),iX.prototype.translate.apply(t),t.points.forEach(function(s){let o=s.yBottom??u,m=999+Math.abs(o),x=s.plotX||0,y=G(s.plotY,-m,a.len+m),b,v=Math.min(y,o),k=Math.max(y,o)-v,w=d,M=x+c,S=f;h&&Math.abs(k)h?o-(b?h:0):u-(b?h:0)),V(s.options.pointWidth)&&(M-=Math.round(((w=S=Math.ceil(s.options.pointWidth))-d)/2)),i.centerInCategory&&(M=t.adjustForMissingColumns(M,w,s,l)),s.barX=M,s.pointWidth=w,s.tooltipPos=e.inverted?[G(a.len+a.pos-e.plotLeft-y,a.pos-e.plotLeft,a.len+a.pos-e.plotLeft),r.len+r.pos-e.plotTop-M-S/2,k]:[r.left-e.plotLeft+M+S/2,G(y+a.pos-e.plotTop,a.pos-e.plotTop,a.len+a.pos-e.plotTop),k],s.shapeType=t.pointClass.prototype.shapeType||"roundedRect",s.shapeArgs=t.crispCol(M,v,S,s.isNull?0:k)}),Q(this,"afterColumnTranslate")}drawGraph(){this.group[this.dense?"addClass":"removeClass"]("highcharts-dense-data")}pointAttribs(t,e){let i=this.options,s=this.pointAttrToOptions||{},o=s.stroke||"borderColor",r=s["stroke-width"]||"borderWidth",a,n,h,l=t&&t.color||this.color,d=t&&t[o]||i[o]||l,c=t&&t.options.dashStyle||i.dashStyle,p=t&&t[r]||i[r]||this[r]||0,g=t?.isNull&&i.nullInteraction?0:t?.opacity??i.opacity??1;t&&this.zones.length&&(n=t.getZone(),l=t.options.color||n&&(n.color||t.nonZonedColor)||this.color,n&&(d=n.borderColor||d,c=n.dashStyle||c,p=n.borderWidth||p)),e&&t&&(h=(a=tu(i.states[e],t.options.states?.[e]||{})).brightness,l=a.color||void 0!==h&&sL(l).brighten(a.brightness).get()||l,d=a[o]||d,p=a[r]||p,c=a.dashStyle||c,g=tb(a.opacity,g));let u={fill:l,stroke:d,"stroke-width":p,opacity:g};return c&&(u.dashstyle=c),u}drawPoints(t=this.points){let e,i=this,s=this.chart,o=i.options,r=o.nullInteraction,a=s.renderer,n=o.animationLimit||250;t.forEach(function(t){let h=t.plotY,l=t.graphic,d=!!l,c=l&&s.pointCount("dataLabelsGroup"===e?t.push(...i.dataLabelsGroups||[]):t.push(i[e]),t),[]).forEach(t=>{t&&(t.addClass("highcharts-tracker").on("mouseover",r).on("mouseout",function(t){o?.onTrackerMouseOut(t)}).on("touchstart",r),!s.styledMode&&i.options.cursor&&t.css({cursor:i.options.cursor}))}),i._hasTracking=!0),Q(this,"afterDrawTracker")}remove(){let t=this,e=t.chart;e.hasRendered&&e.series.forEach(function(e){e.type===t.type&&(e.isDirty=!0)}),iX.prototype.remove.apply(t,arguments)}}sE.defaultOptions=tu(iX.defaultOptions,{borderRadius:3,centerInCategory:!1,groupPadding:.2,marker:null,pointPadding:.1,minPointLength:0,cropThreshold:50,pointRange:null,states:{hover:{halo:!1,brightness:.1},select:{color:"#cccccc",borderColor:"#000000"}},dataLabels:{align:void 0,verticalAlign:void 0,y:void 0},startFromThreshold:!0,stickyTracking:!1,tooltip:{distance:6},threshold:0,borderColor:"#ffffff"}),q(sE.prototype,{directTouch:!0,getSymbol:sO,negStacks:!0,trackerGroups:["group","dataLabelsGroup"]}),iO.registerSeriesType("column",sE);let sI=sE,{getDeferredAnimation:sD}=tQ,{format:sB}=es;!function(t){function e(){return h(this).some(t=>t?.enabled)}function i(t,e,i,s,o){let{chart:r,enabledDataSorting:a}=this,n=this.isCartesian&&r.inverted,h=t.plotX,l=t.plotY,d=i.rotation||0,c=V(h)&&V(l)&&r.isInsidePlot(h,Math.round(l),{inverted:n,paneCoordinates:!0,series:this}),p=0===d&&"justify"===tb(i.overflow,a?"none":"justify"),g=this.visible&&!1!==t.visible&&V(h)&&(t.series.forceDL||a&&!p||c||tb(i.inside,!!this.options.stacking)&&s&&r.isInsidePlot(h,n?s.x+1:s.y+s.height-1,{inverted:n,paneCoordinates:!0,series:this})),u=t.pos();if(g&&u){var f;let h=e.getBBox(),l=e.getBBox(void 0,0);if(s=q({x:u[0],y:Math.round(u[1]),width:0,height:0},s||{}),"plotEdges"===i.alignTo&&this.isCartesian&&(s[n?"x":"y"]=0,s[n?"width":"height"]=this.yAxis?.len||0),q(i,{width:h.width,height:h.height}),f=s,a&&this.xAxis&&!p&&this.setDataLabelStartPos(t,e,o,c,f),e.align(tu(i,{width:l.width,height:l.height}),!1,s,!1),e.alignAttr.x+=tt(i.align)*(l.width-h.width),e.alignAttr.y+=tt(i.verticalAlign)*(l.height-h.height),e[e.placed?"animate":"attr"]({"text-align":e.alignAttr["text-align"]||"center",x:e.alignAttr.x+(h.width-l.width)/2,y:e.alignAttr.y+(h.height-l.height)/2,rotationOriginX:(e.width||0)/2,rotationOriginY:(e.height||0)/2}),p&&s.height>=0)this.justifyDataLabel(e,i,e.alignAttr,h,s,o);else if(tb(i.crop,!0)){let{x:t,y:i}=e.alignAttr;g=r.isInsidePlot(t,i,{paneCoordinates:!0,series:this})&&r.isInsidePlot(t+h.width-1,i+h.height-1,{paneCoordinates:!0,series:this})}i.shape&&!d&&e[o?"attr":"animate"]({anchorX:u[0],anchorY:u[1]})}o&&a&&(e.placed=!1),g||a&&!p?(e.show(),e.placed=!0):(e.hide(),e.placed=!1)}function s(t,e){Q(this,"initDataLabelsGroup",{index:t,zIndex:e?.zIndex??6}),this.dataLabelsGroup=this.dataLabelsGroups?.[t];let i=this.plotGroup("dataLabelsGroup","data-labels",this.hasRendered?"inherit":"hidden",e?.zIndex??6,this.dataLabelsParentGroups?.[t]);return this.dataLabelsGroups||(this.dataLabelsGroups=[]),this.dataLabelsGroups[t]=i,this.dataLabelsGroup=this.dataLabelsGroups[0],i}function o(t,e,i){let s=!!this.hasRendered,o=this.initDataLabelsGroup(t,i).attr({opacity:+s});return!s&&o&&(this.visible&&o.show(),this.options.animation?o.animate({opacity:1},e):o.attr({opacity:1})),o}function r(t){let e;t=t||this.points;let i=this,s=i.chart,o=i.options,r=s.renderer,{backgroundColor:a,plotBackgroundColor:l}=s.options.chart,d=r.getContrast(td(l)&&l||td(a)&&a||"#000000"),c=h(i),{animation:p,defer:g}=c[0],u=g?sD(s,p,i):{defer:0,duration:0};Q(this,"drawDataLabels"),i.hasDataLabels?.()&&t.forEach(t=>{let a=t.dataLabels||[],h=t.color||i.color;tT(n(c,t.dlOptions||t.options?.dataLabels)).forEach((n,l)=>{e=this.initDataLabels(l,u,n);let c=n.enabled&&(t.visible||t.dataLabelOnHidden)&&(!t.isNull||t.dataLabelOnNull)&&function(t,e){let i=e.filter;if(i){let e=i.operator,s=t[i.property],o=i.value;return">"===e&&s>o||"<"===e&&s="===e&&s>=o||"<="===e&&s<=o||"=="===e&&s==o||"==="===e&&s===o||"!="===e&&s!=o||"!=="===e&&s!==o||!1}return!0}(t,n),{backgroundColor:p,borderColor:g,distance:f,style:m={}}=n,x,y,b,v={},k=a[l],w=!k,M;c&&(y=V(x=tb(n[t.formatPrefix+"Format"],n.format))?sB(x,t,s):(n[t.formatPrefix+"Formatter"]||n.formatter).call(t,n,t),b=n.rotation,!s.styledMode&&(m.color=tb(n.color,m.color,td(i.color)?i.color:void 0,"#000000"),"contrast"===m.color?("none"!==p&&(M=p),t.contrastColor=r.getContrast("auto"!==M&&td(M)&&M||(td(h)?h:"")),m.color=M||!V(f)&&n.inside||0>tv(f||0)||o.stacking?t.contrastColor:d):delete t.contrastColor,o.cursor&&(m.cursor=o.cursor)),v={r:n.borderRadius||0,rotation:b,padding:n.padding,zIndex:1},s.styledMode||(v.fill="auto"===p?t.color:p,v.stroke="auto"===g?t.color:g,v["stroke-width"]=n.borderWidth),tm(v,(t,e)=>{void 0===t&&delete v[e]})),!k||c&&V(y)&&!!(k.div||k.text?.foreignObject)==!!n.useHTML&&(k.rotation&&n.rotation||k.rotation===n.rotation)||(k=void 0,w=!0),c&&V(y)&&""!==y&&(k?v.text=y:(k=r.label(y,0,0,n.shape,void 0,void 0,n.useHTML,void 0,"data-label")).addClass(" highcharts-data-label-color-"+t.colorIndex+" "+(n.className||"")+(n.useHTML?" highcharts-tracker":"")),k&&(k.options=n,k.attr(v),s.styledMode?m.width&&k.css({width:m.width,textOverflow:m.textOverflow,whiteSpace:m.whiteSpace}):k.css(m).shadow(n.shadow),Q(k,"beforeAddingDataLabel",{labelOptions:n,point:t}),k.added||k.add(e),i.alignDataLabel(t,k,n,void 0,w),k.isActive=!0,a[l]&&a[l]!==k&&a[l].destroy(),a[l]=k))});let l=a.length;for(;l--;)a[l]?.isActive?a[l].isActive=!1:(a[l]?.destroy(),a.splice(l,1));t.dataLabel=a[0],t.dataLabels=a}),Q(this,"afterDrawDataLabels")}function a(t,e,i,s,o,r){let a=this.chart,n=e.align,h=e.verticalAlign,l=t.box?0:t.padding||0,d=a.inverted?this.yAxis:this.xAxis,c=d?d.left-a.plotLeft:0,p=a.inverted?this.xAxis:this.yAxis,g=p?p.top-a.plotTop:0,{x:u=0,y:f=0}=e,m,x;return(m=(i.x||0)+l+c)<0&&("right"===n&&u>=0?(e.align="left",e.inside=!0):u-=m,x=!0),(m=(i.x||0)+s.width-l+c)>a.plotWidth&&("left"===n&&u<=0?(e.align="right",e.inside=!0):u+=a.plotWidth-m,x=!0),(m=i.y+l+g)<0&&("bottom"===h&&f>=0?(e.verticalAlign="top",e.inside=!0):f-=m,x=!0),(m=(i.y||0)+s.height-l+g)>a.plotHeight&&("top"===h&&f<=0?(e.verticalAlign="bottom",e.inside=!0):f+=a.plotHeight-m,x=!0),x&&(e.x=u,e.y=f,t.placed=!r,t.align(e,void 0,o)),x}function n(t,e){let i=[],s;if(tc(t)&&!tc(e))i=t.map(function(t){return tu(t,e)});else if(tc(e)&&!tc(t))i=e.map(function(e){return tu(t,e)});else if(tc(t)||tc(e)){if(tc(t)&&tc(e))for(s=Math.max(t.length,e.length);s--;)i[s]=tu(t[s],e[s])}else i=tu(t,e);return i}function h(t){let e=t.chart.options.plotOptions;return tT(n(n(e?.series?.dataLabels,e?.[t.type]?.dataLabels),t.options.dataLabels))}function l(t,e,i,s,o){let r=this.chart,a=r.inverted,n=this.xAxis,h=n.reversed,l=((a?e.height:e.width)||0)/2,d=t.pointWidth,c=d?d/2:0;e.startXPos=a?o.x:h?-l-c:n.width-l+c,e.startYPos=a?h?this.yAxis.height-l+c:-l-c:o.y,s?"hidden"===e.visibility&&(e.show(),e.attr({opacity:0}).animate({opacity:1})):e.attr({opacity:1}).animate({opacity:0},void 0,e.hide),r.hasRendered&&(i&&e.attr({x:e.startXPos,y:e.startYPos}),e.placed=!0)}t.compose=function(t){let h=t.prototype;h.initDataLabels||(h.initDataLabels=o,h.initDataLabelsGroup=s,h.alignDataLabel=i,h.drawDataLabels=r,h.justifyDataLabel=a,h.mergeArrays=n,h.setDataLabelStartPos=l,h.hasDataLabels=e)}}(C||(C={}));let sN=C,{composed:sz}=B,{series:sR}=iO;function sW(t,e,i,s,o){let{chart:r,options:a}=this,n=r.inverted,h=this.xAxis?.len||r.plotSizeX||0,l=this.yAxis?.len||r.plotSizeY||0,d=t.dlBox||t.shapeArgs,c=t.below??(t.plotY||0)>(this.translatedThreshold??l),p=i.inside??!!a.stacking;if(d){if(s=tu(d),"allow"!==i.overflow||!1!==i.crop||!1!==a.clip){s.y<0&&(s.height+=s.y,s.y=0);let t=s.y+s.height-l;t>0&&t● {series.name}
',pointFormat:"x: {point.x}
y: {point.y}
"}}),q(sY.prototype,{allowOutsidePlotInteraction:!0,drawTracker:sG.prototype.drawTracker,sorted:!1,requireSorting:!1,noSharedTooltip:!0,trackerGroups:["group","markerGroup","dataLabelsGroup"]}),R(sY,"afterTranslate",function(){this.applyJitter()}),iO.registerSeriesType("scatter",sY);let{deg2rad:sj}=B;(p=P||(P={})).getCenter=function(){let t=this.options,e=this.chart,i=2*(t.slicedOffset||0),s=e.plotWidth-2*i,o=e.plotHeight-2*i,r=t.center,a=Math.min(s,o),n=t.thickness,h,l=t.size,d=t.innerSize||0,c,p;"string"==typeof l&&(l=parseFloat(l)),"string"==typeof d&&(d=parseFloat(d));let g=[tb(r?.[0],"50%"),tb(r?.[1],"50%"),tb(l&&l<0?void 0:t.size,"100%"),tb(d&&d<0?void 0:t.innerSize||0,"0%")];for(!e.angular||this instanceof iX||(g[3]=0),c=0;c<4;++c)p=g[c],h=c<2||2===c&&/%$/.test(p),g[c]=tw(p,[s,o,a,g[2]][c])+(h?i:0);return g[3]>g[2]&&(g[3]=g[2]),tl(n)&&2*n0&&(g[3]=g[2]-2*n),Q(this,"afterGetCenter",{positions:g}),g},p.getStartAndEndRadians=function(t,e){let i=tl(t)?t:0,s=tl(e)&&e>i&&e-i<360?e:i+360;return{start:sj*(i+-90),end:sj*(s+-90)}};let s$=P,{setAnimation:sV}=tQ;class sU extends ip{getConnectorPath(t){let e=t.dataLabelPosition,i=t.options||{},s=i.connectorShape,o=this.connectorShapes[s]||s;return e&&o.call(this,{...e.computed,alignment:e.alignment},e.connectorPosition,i)||[]}getTranslate(){return this.sliced&&this.slicedTranslation||{translateX:0,translateY:0}}haloPath(t){let e=this.shapeArgs;return this.sliced||!this.visible?[]:this.series.chart.renderer.symbols.arc(e.x,e.y,e.r+t,e.r+t,{innerR:e.r-1,start:e.start,end:e.end,borderRadius:e.borderRadius})}constructor(t,e,i){super(t,e,i),this.half=0,this.name??(this.name=t.chart.options.lang.pieSliceName);const s=t=>{this.slice("select"===t.type)};R(this,"select",s),R(this,"unselect",s)}isValid(){return tl(this.y)&&this.y>=0}setVisible(t,e=!0){t!==this.visible&&this.update({visible:t??!this.visible},e,void 0,!1)}slice(t,e,i){let s=this.series;sV(i,s.chart),e=tb(e,!0),this.sliced=this.options.sliced=t=V(t)?t:!this.sliced,s.options.data[s.data.indexOf(this)]=this.options,this.graphic&&this.graphic.animate(this.getTranslate())}}q(sU.prototype,{connectorShapes:{fixedOffset:function(t,e,i){let s=e.breakAt,o=e.touchingSliceAt,r=i.softConnector?["C",t.x+("left"===t.alignment?-5:5),t.y,2*s.x-o.x,2*s.y-o.y,s.x,s.y]:["L",s.x,s.y];return[["M",t.x,t.y],r,["L",o.x,o.y]]},straight:function(t,e){let i=e.touchingSliceAt;return[["M",t.x,t.y],["L",i.x,i.y]]},crookedLine:function(t,e,i){let{angle:s=this.angle||0,breakAt:o,touchingSliceAt:r}=e,{series:a}=this,[n,h,l]=a.center,d=l/2,{plotLeft:c,plotWidth:p}=a.chart,g="left"===t.alignment,{x:u,y:f}=t,m=o.x;if(i.crookDistance){let t=tw(i.crookDistance,1);m=g?n+d+(p+c-n-d)*(1-t):c+(n-d)*t}else m=n+(h-f)*Math.tan(s-Math.PI/2);let x=[["M",u,f]];return(g?m<=u&&m>=o.x:m>=u&&m<=o.x)&&x.push(["L",m,f]),x.push(["L",o.x,o.y],["L",r.x,r.y]),x}}});let{getStartAndEndRadians:sZ}=s$,{noop:s_}=B;class sK extends iX{animate(t){let e=this,i=e.points,s=e.startAngleRad;t||i.forEach(function(t){let i=t.graphic,o=t.shapeArgs;i&&o&&(i.attr({r:tb(t.startR,e.center&&e.center[3]/2),start:s,end:s}),i.animate({r:o.r,start:o.start,end:o.end},e.options.animation))})}drawEmpty(){let t,e,i=this.startAngleRad,s=this.endAngleRad,o=this.options;0===this.total&&this.center?(t=this.center[0],e=this.center[1],this.graph||(this.graph=this.chart.renderer.arc(t,e,this.center[1]/2,0,i,s).addClass("highcharts-empty-series").add(this.group)),this.graph.attr({d:ek.arc(t,e,this.center[2]/2,0,{start:i,end:s,innerR:this.center[3]/2})}),this.chart.styledMode||this.graph.attr({"stroke-width":o.borderWidth,fill:o.fillColor||"none",stroke:o.color||"#cccccc"})):this.graph&&(this.graph=this.graph.destroy())}drawPoints(){let t=this.chart.renderer;this.points.forEach(function(e){e.graphic&&e.hasNewShapeType()&&(e.graphic=e.graphic.destroy()),e.graphic||(e.graphic=t[e.shapeType](e.shapeArgs).add(e.series.group),e.delayedRendering=!0)})}generatePoints(){super.generatePoints(),this.updateTotals()}getX(t,e,i,s){let o=this.center,r=this.radii?this.radii[i.index]||0:o[2]/2,a=s.dataLabelPosition,n=a?.distance||0,h=Math.asin(G((t-o[1])/(r+n),-1,1));return o[0]+Math.cos(h)*(r+n)*(e?-1:1)+(n>0?(e?-1:1)*(s.padding||0):0)}hasData(){return this.points.some(t=>t.visible)}redrawPoints(){let t,e,i,s,o=this,r=o.chart;this.drawEmpty(),o.group&&!r.styledMode&&o.group.shadow(o.options.shadow),o.points.forEach(function(a){let n={};e=a.graphic,!a.isNull&&e?(s=a.shapeArgs,t=a.getTranslate(),r.styledMode||(i=o.pointAttribs(a,a.selected&&"select")),a.delayedRendering?(e.setRadialReference(o.center).attr(s).attr(t),r.styledMode||e.attr(i).attr({"stroke-linejoin":"round"}),a.delayedRendering=!1):(e.setRadialReference(o.center),r.styledMode||tu(!0,n,i),tu(!0,n,s,t),e.animate(n)),e.attr({visibility:a.visible?"inherit":"hidden"}),e.addClass(a.getClassName(),!0)):e&&(a.graphic=e.destroy())})}sortByAngle(t,e){t.sort(function(t,i){return void 0!==t.angle&&(i.angle-t.angle)*e})}translate(t){Q(this,"translate"),this.generatePoints();let e=this.options,i=e.slicedOffset,s=sZ(e.startAngle,e.endAngle),o=this.startAngleRad=s.start,r=(this.endAngleRad=s.end)-o,a=this.points,n=e.ignoreHiddenPoint,h=a.length,l,d,c,p,g,u,f,m=0;for(t||(this.center=t=this.getCenter()),u=0;u1.5*Math.PI?c-=2*Math.PI:c<-Math.PI/2&&(c+=2*Math.PI),f.slicedTranslation={translateX:Math.round(Math.cos(c)*i),translateY:Math.round(Math.sin(c)*i)},p=Math.cos(c)*t[2]/2,g=Math.sin(c)*t[2]/2,f.tooltipPos=[t[0]+.7*p,t[1]+.7*g],f.half=+(c<-Math.PI/2||c>Math.PI/2),f.angle=c}Q(this,"afterTranslate")}updateTotals(){let t=this.points,e=t.length,i=this.options.ignoreHiddenPoint,s,o,r=0;for(s=0;s0&&(o.visible||!i)?o.y/r*100:0,o.total=r}}sK.defaultOptions=tu(iX.defaultOptions,{borderRadius:3,center:[null,null],clip:!1,colorByPoint:!0,dataLabels:{connectorPadding:5,connectorShape:"crookedLine",crookDistance:void 0,distance:30,enabled:!0,formatter:function(){return this.isNull?void 0:this.name},softConnector:!0,x:0},fillColor:void 0,ignoreHiddenPoint:!0,inactiveOtherPoints:!0,legendType:"point",marker:null,size:null,showInLegend:!1,slicedOffset:10,stickyTracking:!1,tooltip:{followPointer:!0},borderColor:"#ffffff",borderWidth:1,lineWidth:void 0,states:{hover:{brightness:.1}}}),q(sK.prototype,{axisTypes:[],directTouch:!0,drawGraph:void 0,drawTracker:sI.prototype.drawTracker,getCenter:s$.getCenter,getSymbol:s_,invertible:!1,isCartesian:!1,noSharedTooltip:!0,pointAttribs:sI.prototype.pointAttribs,pointClass:sU,requireSorting:!1,searchPoint:s_,trackerGroups:["group","dataLabelsGroup"]}),iO.registerSeriesType("pie",sK);let{composed:sq,noop:sJ}=B,{distribute:sQ}=er,{series:s0}=iO;!function(t){let e={radialDistributionY:function(t,e){return(e.dataLabelPosition?.top||0)+t.distributeBox.pos},radialDistributionX:function(t,e,i,s,o){let r=o.dataLabelPosition;return t.getX(i<(r?.top||0)+2||i>(r?.bottom||0)-2?s:i,e.half,e,o)},justify:function(t,e,i,s){return s[0]+(t.half?-1:1)*(i+(e.dataLabelPosition?.distance||0))},alignToPlotEdges:function(t,e,i,s){let o=t.getBBox().width;return e?o+s:i-o-s},alignToConnectors:function(t,e,i,s){let o=0,r;return t.forEach(function(t){(r=t.dataLabel.getBBox().width)>o&&(o=r)}),e?o+s:i-o-s}};function i(t,e){let i=Math.PI/2,{start:s=0,end:o=0}=t.shapeArgs||{},r=t.angle||0;e>0&&si&&r>i/2&&r<1.5*i&&(r=r<=i?Math.max(i/2,(s+i)/2):Math.min(1.5*i,(i+o)/2));let{center:a,options:n}=this,h=a[2]/2,l=Math.cos(r),d=Math.sin(r),c=a[0]+l*h,p=a[1]+d*h,g=Math.min((n.slicedOffset||0)+(n.borderWidth||0),e/5);return{natural:{x:c+l*e,y:p+d*e},computed:{},alignment:e<0?"center":t.half?"right":"left",connectorPosition:{angle:r,breakAt:{x:c+l*g,y:p+d*g},touchingSliceAt:{x:c,y:p}},distance:e}}function s(){let t=this,e=t.points,i=t.chart,s=i.plotWidth,o=i.plotHeight,r=i.plotLeft,a=Math.round(i.chartWidth/3),n=t.center,h=n[2]/2,l=n[1],d=[[],[]],c=[0,0,0,0],p=t.dataLabelPositioners,g,u,f,m=0;t.visible&&t.hasDataLabels?.()&&(e.forEach(t=>{(t.dataLabels||[]).forEach(t=>{t.shortened&&(t.attr({width:"auto"}).css({width:"auto",textOverflow:"clip"}),t.shortened=!1)})}),s0.prototype.drawDataLabels.apply(t),e.forEach(t=>{(t.dataLabels||[]).forEach((e,i)=>{let s=n[2]/2,o=e.options,r=tw(o?.distance||0,s);0===i&&d[t.half].push(t),!V(o?.style?.width)&&e.getBBox().width>a&&(e.css({width:Math.round(.7*a)+"px"}),e.shortened=!0),e.dataLabelPosition=this.getDataLabelPosition(t,r),m=Math.max(m,r)})}),d.forEach((e,a)=>{let d=e.length,g=[],x,y,b=0,v;d&&(t.sortByAngle(e,a-.5),m>0&&(x=Math.max(0,l-h-m),y=Math.min(l+h+m,i.plotHeight),e.forEach(t=>{(t.dataLabels||[]).forEach(e=>{let s=e.dataLabelPosition;s&&s.distance>0&&(s.top=Math.max(0,l-h-s.distance),s.bottom=Math.min(l+h+s.distance,i.plotHeight),b=e.getBBox().height||21,e.lineHeight=i.renderer.fontMetrics(e.text||e).h+2*e.padding,t.distributeBox={target:(e.dataLabelPosition?.natural.y||0)-s.top+e.lineHeight/2,size:b,rank:t.y},g.push(t.distributeBox))})}),sQ(g,v=y+b-x,v/5)),e.forEach(i=>{(i.dataLabels||[]).forEach(l=>{let d=l.options||{},m=i.distributeBox,x=l.dataLabelPosition,y=x?.natural.y||0,b=d.connectorPadding||0,v=l.lineHeight||21,k=(v-l.getBBox().height)/2,w=0,M=y,S="inherit";if(x){if(g&&V(m)&&x.distance>0&&(void 0===m.pos?S="hidden":(f=m.size,M=p.radialDistributionY(i,l))),d.justify)w=p.justify(i,l,h,n);else switch(d.alignTo){case"connectors":w=p.alignToConnectors(e,a,s,r);break;case"plotEdges":w=p.alignToPlotEdges(l,a,s,r);break;default:w=p.radialDistributionX(t,i,M-k,y,l)}if(x.attribs={visibility:S,align:x.alignment},x.posAttribs={x:w+(d.x||0)+(({left:b,right:-b})[x.alignment]||0),y:M+(d.y||0)-v/2},x.computed.x=w,x.computed.y=M-k,tb(d.crop,!0)){let t;w-(u=l.getBBox().width)s-b&&0===a&&(t=Math.round(w+u-s+b),c[1]=Math.max(t,c[1])),M-f/2<0?c[0]=Math.max(Math.round(-M+f/2),c[0]):M+f/2>o&&(c[2]=Math.max(Math.round(M+f/2-o),c[2])),x.sideOverflow=t}}})}))}),(0===H(c)||this.verifyDataLabelOverflow(c))&&(this.placeDataLabels(),this.points.forEach(e=>{e.dataLabels?.forEach((s,o)=>{let{connectorColor:r,connectorWidth:a=1}=s.options||{},n=s.dataLabelPosition;if(tl(a)){let h;g=s.connector,n&&n.distance>0?(h=!g,g||(s.connector=g=i.renderer.path().addClass("highcharts-data-label-connector highcharts-color-"+e.colorIndex+(e.className?" "+e.className:"")).add(t.dataLabelsGroups?.[o])),i.styledMode||g.attr({"stroke-width":a,stroke:r||e.color||"#666666"}),g[h?"attr":"animate"]({d:e.getConnectorPath(s)}),g.attr({visibility:n.attribs?.visibility})):g&&(s.connector=g.destroy())}})})))}function o(){this.points.forEach(t=>{(t.dataLabels||[]).forEach(t=>{let e=t.dataLabelPosition;e?(e.sideOverflow&&(t.css({width:Math.max(t.getBBox().width-e.sideOverflow,0)+"px",textOverflow:t.options?.style?.textOverflow||"ellipsis"}),t.shortened=!0),t.attr(e.attribs),t[t.moved?"animate":"attr"](e.posAttribs),t.moved=!0):t&&t.attr({y:-9999})}),delete t.distributeBox},this)}function r(t){let e=this.center,i=this.options,s=i.center,o=i.minSize||80,r=o,a=null!==i.size;return!a&&(null!==s[0]?r=Math.max(e[2]-Math.max(t[1],t[3]),o):(r=Math.max(e[2]-t[1]-t[3],o),e[0]+=(t[3]-t[1])/2),null!==s[1]?r=G(r,o,e[2]-Math.max(t[0],t[2])):(r=G(r,o,e[2]-t[0]-t[2]),e[1]+=(t[0]-t[2])/2),r(t.x+=e.x,t.y+=e.y,t),{x:0,y:0});return{x:e.x/t.length,y:e.y/t.length}},g.getDistanceBetweenPoints=function(t,e){return Math.sqrt(Math.pow(e.x-t.x,2)+Math.pow(e.y-t.y,2))},g.getAngleBetweenPoints=function(t,e){return Math.atan2(e.x-t.x,e.y-t.y)},g.pointInPolygon=function({x:t,y:e},i){let s=i.length,o,r,a=!1;for(o=0,r=s-1;oe!=l>e&&t<(h-s)*(e-n)/(l-n)+s&&(a=!a)}return a};let{pointInPolygon:s2}=O;function s3(t,e){let i,s=!1;return t&&(i=t.newOpacity,t.oldOpacity!==i&&(t.hasClass("highcharts-data-label")?(t[i?"removeClass":"addClass"]("highcharts-data-label-hidden"),s=!0,t[t.isOld?"animate":"attr"]({opacity:i},void 0,function(){e.styledMode||t.css({pointerEvents:i?"auto":"none"})}),Q(e,"afterHideOverlappingLabel")):t.attr({opacity:i})),t.isOld=!0),s}let{defaultOptions:s5}=tY,{noop:s6}=B,s9={radius:0,scope:"stack",where:void 0},s4=s6,s8=s6;function s7(t,e,i,s,o={}){let r=s4(t,e,i,s,o),{brStart:a=!0,brEnd:n=!0,innerR:h=0,r:l=i,start:d=0,end:c=0}=o;if(o.open||!o.borderRadius)return r;let p=c-d,g=Math.sin(p/2),u=Math.max(Math.min(tw(o.borderRadius||0,l-h),(l-h)/2,l*g/(1+g)),0),f=Math.min(u,p/Math.PI*2*h),m=r.length-1;for(;m--;)(a||0!==m&&3!==m)&&(n||1!==m&&2!==m)&&!function(t,e,i){let s,o,r,a=t[e],n=t[e+1];if("Z"===n[0]&&(n=t[0]),("M"===a[0]||"L"===a[0])&&"A"===n[0]?(s=a,o=n,r=!0):"A"===a[0]&&("M"===n[0]||"L"===n[0])&&(s=n,o=a),s&&o&&o.params){let a=o[1],n=o[5],h=o.params,{start:l,end:d,cx:c,cy:p}=h,g=n?a-i:a+i,u=g?Math.asin(i/g):0,f=n?u:-u,m=Math.cos(u)*g;r?(h.start=l+f,s[1]=c+m*Math.cos(l),s[2]=p+m*Math.sin(l),t.splice(e+1,0,["A",i,i,0,0,1,c+a*Math.cos(h.start),p+a*Math.sin(h.start)])):(h.end=d-f,o[6]=c+a*Math.cos(h.end),o[7]=p+a*Math.sin(h.end),t.splice(e+1,0,["A",i,i,0,0,1,c+m*Math.cos(d),p+m*Math.sin(d)])),o[4]=Math.abs(h.end-h.start)1?f:u);return r}function ot(){if(this.options.borderRadius&&!(this.chart.is3d&&this.chart.is3d())){let{options:t,yAxis:e}=this,i="percent"===t.stacking,s=s5.plotOptions?.[this.type]?.borderRadius,o=oe(t.borderRadius,tg(s)?s:{}),r=e.options.reversed;for(let s of this.points){let{shapeArgs:a}=s;if("roundedRect"===s.shapeType&&a){let{width:n=0,height:h=0,y:l=0}=a,d=l,c=h;if("stack"===o.scope&&s.stackTotal){let o=e.translate(i?100:s.stackTotal,!1,!0,!1,!0),r=e.translate(t.threshold||0,!1,!0,!1,!0),a=this.crispCol(0,Math.min(o,r),0,Math.abs(o-r));d=a.y,c=a.height}let p=(s.negative?-1:1)*(r?-1:1)==-1,g=o.where;!g&&this.is("waterfall")&&Math.abs((s.yBottom||0)-(this.translatedThreshold||0))>this.borderWidth&&(g="all"),g||(g="end");let u=Math.min(tw(o.radius,n),n/2,"all"===g?c/2:1/0)||0;"end"===g&&(p&&(d-=u),c+=u),q(a,{brBoxHeight:c,brBoxY:d,r:u})}}}}function oe(t,e){return tg(t)||(t={radius:t||0}),tu(s9,e,t)}function oi(){let t=oe(this.options.borderRadius);for(let e of this.points){let i=e.shapeArgs;i&&(i.borderRadius=tw(t.radius,(i.r||0)-(i.innerR||0)))}}function os(t,e,i,s,o={}){let r=s8(t,e,i,s,o),{r:a=0,brBoxHeight:n=s,brBoxY:h=e}=o,l=e-h,d=h+n-(e+s),c=l-a>-.1?0:a,p=d-a>-.1?0:a,g=Math.max(c&&l,0),u=Math.max(p&&d,0),f=[t+c,e],m=[t+i-c,e],x=[t+i,e+c],y=[t+i,e+s-p],b=[t+i-p,e+s],v=[t+p,e+s],k=[t,e+s-p],w=[t,e+c],M=(t,e)=>Math.sqrt(Math.pow(t,2)-Math.pow(e,2));if(g){let t=M(c,c-g);f[0]-=t,m[0]+=t,x[1]=w[1]=e+c-g}if(s=tb(i.minWidth,0)&&this.chartHeight>=tb(i.minHeight,0)}).call(this,this)&&e.push(t._id)}function or(t,e){let i=this.options.responsive,s=this.currentResponsive,o=[],r;!e&&i&&i.rules&&i.rules.forEach(t=>{void 0===t._id&&(t._id=tB()),this.matchResponsiveRule(t,o)},this);let a=tu(...o.map(t=>tr(i?.rules||[],e=>e._id===t)).map(t=>t?.chartOptions));a.isResponsiveOptions=!0,o=o.toString()||void 0;let n=s?.ruleIds;o!==n&&(s&&(this.currentResponsive=void 0,this.updatingResponsive=!0,this.update(s.undoOptions,t,!0),this.updatingResponsive=!1),o?((r=_(a,this.options,!0,this.collectionsWithUpdate)).isResponsiveOptions=!0,this.currentResponsive={ruleIds:o,mergedOptions:a,undoOptions:r},this.updatingResponsive||this.update(a,t,!0)):this.currentResponsive=void 0)}(E||(E={})).compose=function(t){let e=t.prototype;return e.matchResponsiveRule||q(e,{matchResponsiveRule:oo,setResponsive:or}),t};let oa=E;B.AST=t6,B.Axis=e2,B.Chart=i8,B.Color=tU,B.DataLabel=sN,B.DataTableCore=iM,B.Fx=tK,B.HTMLElement=eY,B.Legend=i_,B.LegendSymbol=iC,B.PlotLineOrBand=e9,B.Point=ip,B.Pointer=iv,B.RendererRegistry=eo,B.Series=iX,B.SeriesRegistry=iO,B.StackItem=sa,B.SVGElement=em,B.SVGRenderer=eW,B.Templating=es,B.Tick=eZ,B.Time=tH,B.Tooltip=ia,B.addEvent=R,B.animObject=tQ.animObject,B.animate=tQ.animate,B.arrayMax=H,B.arrayMin=W,B.attr=X,B.chart=i8.chart,B.clamp=G,B.color=tU.parse,B.correctFloat=F,B.createElement=Y,B.css=$,B.dateFormat=es.dateFormat,B.defaultOptions=tY.defaultOptions,B.defined=V,B.destroyObjectProperties=U,B.diffObjects=_,B.discardElement=Z,B.distribute=er.distribute,B.erase=K,B.error=tE,B.extend=q,B.extendClass=J,B.find=tr,B.fireEvent=Q,B.format=es.format,B.getDeferredAnimation=tQ.getDeferredAnimation,B.getMagnitude=ti,B.getOptions=tY.getOptions,B.getStyle=to,B.insertItem=tI,B.isArray=tc,B.isClass=th,B.isDOMElement=tn,B.isFunction=tp,B.isNumber=tl,B.isObject=tg,B.isString=td,B.merge=tu,B.normalizeTickInterval=tf,B.numberFormat=es.numberFormat,B.objectEach=tm,B.offset=tx,B.pad=ty,B.pick=tb,B.pInt=tv,B.relativeLength=tw,B.removeEvent=tS,B.seriesType=iO.seriesType,B.setAnimation=tQ.setAnimation,B.setOptions=tY.setOptions,B.splat=tT,B.stableSort=tC,B.stop=tQ.stop,B.syncTimeout=tA,B.time=tY.defaultTime,B.timers=tK.timers,B.timeUnits=tD,B.uniqueKey=tB,B.useSerialIds=function(e){return t=tb(e,t)},B.wrap=function(t,e,i){let s=t[e];t[e]=function(){let t=arguments,e=this;return i.apply(this,[function(){return s.apply(e,arguments.length?arguments:t)}].concat([].slice.call(arguments)))}},({compose:function(t,e,i){let s=t.types.pie;if(!e.symbolCustomAttribs.includes("borderRadius")){let o=i.prototype.symbols;R(t,"afterColumnTranslate",ot,{order:9}),R(s,"afterTranslate",oi),e.symbolCustomAttribs.push("borderRadius","brBoxHeight","brBoxY","brEnd","brStart"),s4=o.arc,s8=o.roundedRect,o.arc=s7,o.roundedRect=os}},optionsToObject:oe}).compose(B.Series,B.SVGElement,B.SVGRenderer),sH.compose(B.Series.types.column),sN.compose(B.Series),e3.compose(B.Axis),eY.compose(B.SVGRenderer),i_.compose(B.Chart),e5.compose(B.Axis),(r=(u=B.Chart).prototype).hideOverlappingLabels||(r.hideOverlappingLabels=function(t){let e=t.length,i=(t,e)=>!(e.x>=t.x+t.width||e.x+e.width<=t.x||e.y>=t.y+t.height||e.y+e.height<=t.y),s=(t,e)=>{for(let i of t)if(s2({x:i[0],y:i[1]},e))return!0;return!1},o,r,a,n,h,l=!1;for(let i=0;i(e?.labelrank||0)-(t?.labelrank||0));for(let o=0;o{tm(t,t=>{t.label&&e.push(t.label)})});for(let i of t.series||[])if(i.visible&&i.hasDataLabels?.()){let s=i=>{for(let s of i)s.visible&&(s.dataLabels||[]).forEach(i=>{let o=i.options||{};i.labelrank=tb(o.labelrank,s.labelrank,s.shapeArgs?.height),o.allowOverlap??Number(o.distance)>0?(i.oldOpacity=i.opacity,i.newOpacity=1,s3(i,t)):e.push(i)})};s(i.nodes||[]),s(i.points)}this.hideOverlappingLabels(e)})),s1.compose(B.Series.types.pie),e9.compose(B.Chart,B.Axis),iv.compose(B.Chart),oa.compose(B.Chart),ss.compose(B.Axis,B.Chart,B.Series),sy.compose(B.Axis,B.Chart,B.Series),ia.compose(B.Pointer);let on=B;return D.default})()); \ No newline at end of file diff --git a/.claude/skills/session-metrics/scripts/vendor/charts/manifest.json b/.claude/skills/session-metrics/scripts/vendor/charts/manifest.json new file mode 100644 index 0000000..ef69b7c --- /dev/null +++ b/.claude/skills/session-metrics/scripts/vendor/charts/manifest.json @@ -0,0 +1,64 @@ +{ + "_note": "Per-library vendor manifest. SHA-256 is verified before inlining.", + "libraries": { + "highcharts": { + "version": "12", + "source": "https://cdn.jsdelivr.net/npm/highcharts@12/", + "license": "non-commercial-free", + "license_url": "https://www.highcharts.com/license", + "files": [ + { + "name": "highcharts.js", + "path": "highcharts/v12/highcharts.js", + "sha256": "892b57c41d27a9d30537f9c9887ff2d098f9319f7f0ea2a002a9422981298a1c" + }, + { + "name": "highcharts-3d.js", + "path": "highcharts/v12/highcharts-3d.js", + "sha256": "d894e1a3819b9ef4756c732ac49ef76fbb8d1c29c5e0029507ca27eaee4eae75" + }, + { + "name": "exporting.js", + "path": "highcharts/v12/exporting.js", + "sha256": "5dc63388bd0d8b8a9fc598e53c690e249fd6119c812b115ac9e5b8c68dde8d6d" + }, + { + "name": "export-data.js", + "path": "highcharts/v12/export-data.js", + "sha256": "ef86f5cfefca5bd7af44b912dfc949ba9e687d6d2d4cd8af6cb82070e2ac2401" + } + ] + }, + "uplot": { + "version": "1", + "source": "https://cdn.jsdelivr.net/npm/uplot@1/", + "license": "MIT", + "license_url": "https://github.com/leeoniya/uPlot/blob/master/LICENSE", + "files": [ + { + "name": "uPlot.iife.min.js", + "path": "uplot/v1/uPlot.iife.min.js", + "sha256": "19c8d4c6ad88929a79f4ae49d6f7161566dfd0ba3d15cc495e974f787eb78f1f" + }, + { + "name": "uPlot.min.css", + "path": "uplot/v1/uPlot.min.css", + "sha256": "df630c6a8d6f8eeaff264b50f73ce5b114f646ffd9a0bb74f049b0a00135fa04" + } + ] + }, + "chartjs": { + "version": "4", + "source": "https://cdn.jsdelivr.net/npm/chart.js@4/", + "license": "MIT", + "license_url": "https://github.com/chartjs/Chart.js/blob/master/LICENSE.md", + "files": [ + { + "name": "chart.umd.js", + "path": "chartjs/v4/chart.umd.js", + "sha256": "ecc3cd1eeb8c34d2178e3f59fd63ec5a3d84358c11730af0b9958dc886d7652a" + } + ] + } + } +} diff --git a/.claude/skills/session-metrics/scripts/vendor/charts/uplot/v1/LICENSE.txt b/.claude/skills/session-metrics/scripts/vendor/charts/uplot/v1/LICENSE.txt new file mode 100644 index 0000000..cde4b3f --- /dev/null +++ b/.claude/skills/session-metrics/scripts/vendor/charts/uplot/v1/LICENSE.txt @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) 2022 Leon Sorokin + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. \ No newline at end of file diff --git a/.claude/skills/session-metrics/scripts/vendor/charts/uplot/v1/uPlot.iife.min.js b/.claude/skills/session-metrics/scripts/vendor/charts/uplot/v1/uPlot.iife.min.js new file mode 100644 index 0000000..047f29b --- /dev/null +++ b/.claude/skills/session-metrics/scripts/vendor/charts/uplot/v1/uPlot.iife.min.js @@ -0,0 +1,2 @@ +/*! https://github.com/leeoniya/uPlot (v1.6.32) */ +var uPlot=function(){"use strict";const l="u-off",e="u-label",t="width",n="height",i="top",o="bottom",s="left",r="right",u="#000",a=u+"0",f="mousemove",c="mousedown",h="mouseup",d="mouseenter",p="mouseleave",m="dblclick",g="change",x="dppxchange",w="--",_="undefined"!=typeof window,b=_?document:null,v=_?window:null,k=_?navigator:null;let y,M;function S(l,e){if(null!=e){let t=l.classList;!t.contains(e)&&t.add(e)}}function T(l,e){let t=l.classList;t.contains(e)&&t.remove(e)}function E(l,e,t){l.style[e]=t+"px"}function z(l,e,t,n){let i=b.createElement(l);return null!=e&&S(i,e),null!=t&&t.insertBefore(i,n),i}function D(l,e){return z("div",l,e)}const P=new WeakMap;function A(e,t,n,i,o){let s="translate("+t+"px,"+n+"px)";s!=P.get(e)&&(e.style.transform=s,P.set(e,s),0>t||0>n||t>i||n>o?S(e,l):T(e,l))}const W=new WeakMap;function Y(l,e,t){let n=e+t;n!=W.get(l)&&(W.set(l,n),l.style.background=e,l.style.borderColor=t)}const C=new WeakMap;function H(l,e,t,n){let i=e+""+t;i!=C.get(l)&&(C.set(l,i),l.style.height=t+"px",l.style.width=e+"px",l.style.marginLeft=n?-e/2+"px":0,l.style.marginTop=n?-t/2+"px":0)}const F={passive:!0},R={...F,capture:!0};function G(l,e,t,n){e.addEventListener(l,t,n?R:F)}function I(l,e,t){e.removeEventListener(l,t,F)}function L(l,e,t,n){let i;t=t||0;let o=2147483647>=(n=n||e.length-1);for(;n-t>1;)i=o?t+n>>1:sl((t+n)/2),l>e[i]?t=i:n=i;return l-e[t]>e[n]-l?n:t}function O(l){return(e,t,n)=>{let i=-1,o=-1;for(let o=t;n>=o;o++)if(l(e[o])){i=o;break}for(let i=n;i>=t;i--)if(l(e[i])){o=i;break}return[i,o]}}_&&function l(){let e=devicePixelRatio;y!=e&&(y=e,M&&I(g,M,l),M=matchMedia(`(min-resolution: ${y-.001}dppx) and (max-resolution: ${y+.001}dppx)`),G(g,M,l),v.dispatchEvent(new CustomEvent(x)))}();const N=l=>null!=l,j=l=>null!=l&&l>0,U=O(N),V=O(j);function B(l,e,t,n){let i=hl(l),o=hl(e);l==e&&(-1==i?(l*=t,e/=t):(l/=t,e*=t));let s=10==t?dl:pl,r=1==o?ul:sl,u=(1==i?sl:ul)(s(ol(l))),a=r(s(ol(e))),f=cl(t,u),c=cl(t,a);return 10==t&&(0>u&&(f=Al(f,-u)),0>a&&(c=Al(c,-a))),n||2==t?(l=f*i,e=c*o):(l=Pl(l,f),e=Dl(e,c)),[l,e]}function $(l,e,t,n){let i=B(l,e,t,n);return 0==l&&(i[0]=0),0==e&&(i[1]=0),i}const J=.1,q={mode:3,pad:J},K={pad:0,soft:null,mode:0},X={min:K,max:K};function Z(l,e,t,n){return Ol(t)?ll(l,e,t):(K.pad=t,K.soft=n?0:null,K.mode=n?3:0,ll(l,e,X))}function Q(l,e){return null==l?e:l}function ll(l,e,t){let n=t.min,i=t.max,o=Q(n.pad,0),s=Q(i.pad,0),r=Q(n.hard,-gl),u=Q(i.hard,gl),a=Q(n.soft,gl),f=Q(i.soft,-gl),c=Q(n.mode,0),h=Q(i.mode,0),d=e-l,p=dl(d),m=fl(ol(l),ol(e)),g=dl(m),x=ol(g-p);(1e-24>d||x>10)&&(d=0,0!=l&&0!=e||(d=1e-24,2==c&&a!=gl&&(o=0),2==h&&f!=-gl&&(s=0)));let w=d||m||1e3,_=dl(w),b=cl(10,sl(_)),v=Al(Pl(l-w*(0==d?0==l?.1:1:o),b/10),24),k=a>l||1!=c&&(3!=c||v>a)&&(2!=c||a>v)?gl:a,y=fl(r,k>v&&l>=k?k:al(k,v)),M=Al(Dl(e+w*(0==d?0==e?.1:1:s),b/10),24),S=e>f||1!=h&&(3!=h||f>M)&&(2!=h||M>f)?-gl:f,T=al(u,M>S&&S>=e?S:fl(S,M));return y==T&&0==y&&(T=100),[y,T]}const el=new Intl.NumberFormat(_?k.language:"en-US"),tl=l=>el.format(l),nl=Math,il=nl.PI,ol=nl.abs,sl=nl.floor,rl=nl.round,ul=nl.ceil,al=nl.min,fl=nl.max,cl=nl.pow,hl=nl.sign,dl=nl.log10,pl=nl.log2,ml=(l,e=1)=>nl.asinh(l/e),gl=1/0;function xl(l){return 1+(0|dl((l^l>>31)-(l>>31)))}function wl(l,e,t){return al(fl(l,e),t)}function _l(l){return"function"==typeof l}function bl(l){return _l(l)?l:()=>l}const vl=l=>l,kl=(l,e)=>e,yl=()=>null,Ml=()=>!0,Sl=(l,e)=>l==e,Tl=/\.\d*?(?=9{6,}|0{6,})/gm,El=l=>{if(Il(l)||Wl.has(l))return l;const e=""+l,t=e.match(Tl);if(null==t)return l;let n=t[0].length-1;if(-1!=e.indexOf("e-")){let[l,t]=e.split("e");return+`${El(l)}e${t}`}return Al(l,n)};function zl(l,e){return El(Al(El(l/e))*e)}function Dl(l,e){return El(ul(El(l/e))*e)}function Pl(l,e){return El(sl(El(l/e))*e)}function Al(l,e=0){if(Il(l))return l;let t=10**e;return rl(l*t*(1+Number.EPSILON))/t}const Wl=new Map;function Yl(l){return((""+l).split(".")[1]||"").length}function Cl(l,e,t,n){let i=[],o=n.map(Yl);for(let s=e;t>s;s++){let e=ol(s),t=Al(cl(l,s),e);for(let r=0;n.length>r;r++){let u=10==l?+`${n[r]}e${s}`:n[r]*t,a=(0>s?e:0)+(o[r]>s?o[r]:0),f=10==l?u:Al(u,a);i.push(f),Wl.set(f,a)}}return i}const Hl={},Fl=[],Rl=[null,null],Gl=Array.isArray,Il=Number.isInteger;function Ll(l){return"string"==typeof l}function Ol(l){let e=!1;if(null!=l){let t=l.constructor;e=null==t||t==Object}return e}function Nl(l){return null!=l&&"object"==typeof l}const jl=Object.getPrototypeOf(Uint8Array),Ul="__proto__";function Vl(l,e=Ol){let t;if(Gl(l)){let n=l.find((l=>null!=l));if(Gl(n)||e(n)){t=Array(l.length);for(let n=0;l.length>n;n++)t[n]=Vl(l[n],e)}else t=l.slice()}else if(l instanceof jl)t=l.slice();else if(e(l)){t={};for(let n in l)n!=Ul&&(t[n]=Vl(l[n],e))}else t=l;return t}function Bl(l){let e=arguments;for(let t=1;e.length>t;t++){let n=e[t];for(let e in n)e!=Ul&&(Ol(l[e])?Bl(l[e],Vl(n[e])):l[e]=Vl(n[e]))}return l}function $l(l,e,t){for(let n,i=0,o=-1;e.length>i;i++){let s=e[i];if(s>o){for(n=s-1;n>=0&&null==l[n];)l[n--]=null;for(n=s+1;t>n&&null==l[n];)l[o=n++]=null}}}const Jl="undefined"==typeof queueMicrotask?l=>Promise.resolve().then(l):queueMicrotask,ql=["January","February","March","April","May","June","July","August","September","October","November","December"],Kl=["Sunday","Monday","Tuesday","Wednesday","Thursday","Friday","Saturday"];function Xl(l){return l.slice(0,3)}const Zl=Kl.map(Xl),Ql=ql.map(Xl),le={MMMM:ql,MMM:Ql,WWWW:Kl,WWW:Zl};function ee(l){return(10>l?"0":"")+l}const te={YYYY:l=>l.getFullYear(),YY:l=>(l.getFullYear()+"").slice(2),MMMM:(l,e)=>e.MMMM[l.getMonth()],MMM:(l,e)=>e.MMM[l.getMonth()],MM:l=>ee(l.getMonth()+1),M:l=>l.getMonth()+1,DD:l=>ee(l.getDate()),D:l=>l.getDate(),WWWW:(l,e)=>e.WWWW[l.getDay()],WWW:(l,e)=>e.WWW[l.getDay()],HH:l=>ee(l.getHours()),H:l=>l.getHours(),h:l=>{let e=l.getHours();return 0==e?12:e>12?e-12:e},AA:l=>12>l.getHours()?"AM":"PM",aa:l=>12>l.getHours()?"am":"pm",a:l=>12>l.getHours()?"a":"p",mm:l=>ee(l.getMinutes()),m:l=>l.getMinutes(),ss:l=>ee(l.getSeconds()),s:l=>l.getSeconds(),fff:l=>function(l){return(10>l?"00":100>l?"0":"")+l}(l.getMilliseconds())};function ne(l,e){e=e||le;let t,n=[],i=/\{([a-z]+)\}|[^{]+/gi;for(;t=i.exec(l);)n.push("{"==t[0][0]?te[t[1]]:t[0]);return l=>{let t="";for(let i=0;n.length>i;i++)t+="string"==typeof n[i]?n[i]:n[i](l,e);return t}}const ie=(new Intl.DateTimeFormat).resolvedOptions().timeZone,oe=l=>l%1==0,se=[1,2,2.5,5],re=Cl(10,-32,0,se),ue=Cl(10,0,32,se),ae=ue.filter(oe),fe=re.concat(ue),ce="{YYYY}",he="\n"+ce,de="{M}/{D}",pe="\n"+de,me=pe+"/{YY}",ge="{aa}",xe="{h}:{mm}"+ge,we="\n"+xe,_e=":{ss}",be=null;function ve(l){let e=1e3*l,t=60*e,n=60*t,i=24*n,o=30*i,s=365*i;return[(1==l?Cl(10,0,3,se).filter(oe):Cl(10,-3,0,se)).concat([e,5*e,10*e,15*e,30*e,t,5*t,10*t,15*t,30*t,n,2*n,3*n,4*n,6*n,8*n,12*n,i,2*i,3*i,4*i,5*i,6*i,7*i,8*i,9*i,10*i,15*i,o,2*o,3*o,4*o,6*o,s,2*s,5*s,10*s,25*s,50*s,100*s]),[[s,ce,be,be,be,be,be,be,1],[28*i,"{MMM}",he,be,be,be,be,be,1],[i,de,he,be,be,be,be,be,1],[n,"{h}"+ge,me,be,pe,be,be,be,1],[t,xe,me,be,pe,be,be,be,1],[e,_e,me+" "+xe,be,pe+" "+xe,be,we,be,1],[l,_e+".{fff}",me+" "+xe,be,pe+" "+xe,be,we,be,1]],function(e){return(r,u,a,f,c,h)=>{let d=[],p=c>=s,m=c>=o&&s>c,g=e(a),x=Al(g*l,3),w=Pe(g.getFullYear(),p?0:g.getMonth(),m||p?1:g.getDate()),_=Al(w*l,3);if(m||p){let t=m?c/o:0,n=p?c/s:0,i=x==_?x:Al(Pe(w.getFullYear()+n,w.getMonth()+t,1)*l,3),r=new Date(rl(i/l)),u=r.getFullYear(),a=r.getMonth();for(let o=0;f>=i;o++){let s=Pe(u+n*o,a+t*o,1),r=s-e(Al(s*l,3));i=Al((+s+r)*l,3),i>f||d.push(i)}}else{let o=i>c?c:i,s=_+(sl(a)-sl(x))+Dl(x-_,o);d.push(s);let p=e(s),m=p.getHours()+p.getMinutes()/t+p.getSeconds()/n,g=c/n,w=h/r.axes[u]._space;for(;s=Al(s+c,1==l?0:3),f>=s;)if(g>1){let l=sl(Al(m+g,6))%24,t=e(s).getHours()-l;t>1&&(t=-1),s-=t*n,m=(m+g)%24,.7>Al((s-d[d.length-1])/c,3)*w||d.push(s)}else d.push(s)}return d}}]}const[ke,ye,Me]=ve(1),[Se,Te,Ee]=ve(.001);function ze(l,e){return l.map((l=>l.map(((t,n)=>0==n||8==n||null==t?t:e(1==n||0==l[8]?t:l[1]+t)))))}function De(l,e){return(t,n,i,o,s)=>{let r,u,a,f,c,h,d=e.find((l=>s>=l[0]))||e[e.length-1];return n.map((e=>{let t=l(e),n=t.getFullYear(),i=t.getMonth(),o=t.getDate(),s=t.getHours(),p=t.getMinutes(),m=t.getSeconds(),g=n!=r&&d[2]||i!=u&&d[3]||o!=a&&d[4]||s!=f&&d[5]||p!=c&&d[6]||m!=h&&d[7]||d[1];return r=n,u=i,a=o,f=s,c=p,h=m,g(t)}))}}function Pe(l,e,t){return new Date(l,e,t)}function Ae(l,e){return e(l)}function We(l,e){return(t,n,i,o)=>null==o?w:e(l(n))}Cl(2,-53,53,[1]);const Ye={show:!0,live:!0,isolate:!1,mount:()=>{},markers:{show:!0,width:2,stroke:function(l,e){let t=l.series[e];return t.width?t.stroke(l,e):t.points.width?t.points.stroke(l,e):null},fill:function(l,e){return l.series[e].fill(l,e)},dash:"solid"},idx:null,idxs:null,values:[]},Ce=[0,0];function He(l,e,t,n=!0){return l=>{0==l.button&&(!n||l.target==e)&&t(l)}}function Fe(l,e,t,n=!0){return l=>{(!n||l.target==e)&&t(l)}}const Re={show:!0,x:!0,y:!0,lock:!1,move:function(l,e,t){return Ce[0]=e,Ce[1]=t,Ce},points:{one:!1,show:function(l,e){let i=l.cursor.points,o=D(),s=i.size(l,e);E(o,t,s),E(o,n,s);let r=s/-2;E(o,"marginLeft",r),E(o,"marginTop",r);let u=i.width(l,e,s);return u&&E(o,"borderWidth",u),o},size:function(l,e){return l.series[e].points.size},width:0,stroke:function(l,e){let t=l.series[e].points;return t._stroke||t._fill},fill:function(l,e){let t=l.series[e].points;return t._fill||t._stroke}},bind:{mousedown:He,mouseup:He,click:He,dblclick:He,mousemove:Fe,mouseleave:Fe,mouseenter:Fe},drag:{setScale:!0,x:!0,y:!1,dist:0,uni:null,click:(l,e)=>{e.stopPropagation(),e.stopImmediatePropagation()},_x:!1,_y:!1},focus:{dist:(l,e,t,n,i)=>n-i,prox:-1,bias:0},hover:{skip:[void 0],prox:null,bias:0},left:-10,top:-10,idx:null,dataIdx:null,idxs:null,event:null},Ge={show:!0,stroke:"rgba(0,0,0,0.07)",width:2},Ie=Bl({},Ge,{filter:kl}),Le=Bl({},Ie,{size:10}),Oe=Bl({},Ge,{show:!1}),Ne='12px system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"',je="bold "+Ne,Ue={show:!0,scale:"x",stroke:u,space:50,gap:5,alignTo:1,size:50,labelGap:0,labelSize:30,labelFont:je,side:2,grid:Ie,ticks:Le,border:Oe,font:Ne,lineGap:1.5,rotate:0},Ve={show:!0,scale:"x",auto:!1,sorted:1,min:gl,max:-gl,idxs:[]};function Be(l,e){return e.map((l=>null==l?"":tl(l)))}function $e(l,e,t,n,i,o,s){let r=[],u=Wl.get(i)||0;for(let l=t=s?t:Al(Dl(t,i),u);n>=l;l=Al(l+i,u))r.push(Object.is(l,-0)?0:l);return r}function Je(l,e,t,n,i){const o=[],s=l.scales[l.axes[e].scale].log,r=sl((10==s?dl:pl)(t));i=cl(s,r),10==s&&(i=fe[L(i,fe)]);let u=t,a=i*s;10==s&&(a=fe[L(a,fe)]);do{o.push(u),u+=i,10!=s||Wl.has(u)||(u=Al(u,Wl.get(i))),a>u||(a=(i=u)*s,10==s&&(a=fe[L(a,fe)]))}while(n>=u);return o}function qe(l,e,t,n,i){let o=l.scales[l.axes[e].scale].asinh,s=n>o?Je(l,e,fl(o,t),n,i):[o],r=0>n||t>0?[]:[0];return(-o>t?Je(l,e,fl(o,-n),-t,i):[o]).reverse().map((l=>-l)).concat(r,s)}const Ke=/./,Xe=/[12357]/,Ze=/[125]/,Qe=/1/,lt=(l,e,t,n)=>l.map(((l,i)=>4==e&&0==l||i%n==0&&t.test(l.toExponential()[0>l?1:0])?l:null));function et(l,e,t){let n=l.axes[t],i=n.scale,o=l.scales[i],s=l.valToPos,r=n._space,u=s(10,i),a=s(9,i)-ul)return lt(e.slice().reverse(),o.distr,a,ul(r/l)).reverse()}return lt(e,o.distr,a,1)}function tt(l,e,t){let n=l.axes[t],i=n.scale,o=n._space,s=l.valToPos,r=ol(s(1,i)-s(2,i));return o>r?lt(e.slice().reverse(),3,Ke,ul(o/r)).reverse():e}function nt(l,e,t,n){return null==n?w:null==e?"":tl(e)}const it={show:!0,scale:"y",stroke:u,space:30,gap:5,alignTo:1,size:50,labelGap:0,labelSize:30,labelFont:je,side:3,grid:Ie,ticks:Le,border:Oe,font:Ne,lineGap:1.5,rotate:0},ot={scale:null,auto:!0,sorted:0,min:gl,max:-gl},st=(l,e,t,n,i)=>i,rt={show:!0,auto:!0,sorted:0,gaps:st,alpha:1,facets:[Bl({},ot,{scale:"x"}),Bl({},ot,{scale:"y"})]},ut={scale:"y",auto:!0,sorted:0,show:!0,spanGaps:!1,gaps:st,alpha:1,points:{show:function(l,e){let{scale:t,idxs:n}=l.series[0],i=l._data[0],o=l.valToPos(i[n[0]],t,!0),s=l.valToPos(i[n[1]],t,!0);return ol(s-o)/(l.series[e].points.space*y)>=n[1]-n[0]},filter:null},values:null,min:gl,max:-gl,idxs:[],path:null,clip:null};function at(l,e,t){return t/10}const ft={time:!0,auto:!0,distr:1,log:10,asinh:1,min:null,max:null,dir:1,ori:0},ct=Bl({},ft,{time:!1,ori:1}),ht={};function dt(l){let e=ht[l];return e||(e={key:l,plots:[],sub(l){e.plots.push(l)},unsub(l){e.plots=e.plots.filter((e=>e!=l))},pub(l,t,n,i,o,s,r){for(let u=0;e.plots.length>u;u++)e.plots[u]!=t&&e.plots[u].pub(l,t,n,i,o,s,r)}},null!=l&&(ht[l]=e)),e}function pt(l,e,t){const n=l.mode,i=l.series[e],o=2==n?l._data[e]:l._data,s=l.scales,r=l.bbox;let u=o[0],a=2==n?o[1]:o[e],f=2==n?s[i.facets[0].scale]:s[l.series[0].scale],c=2==n?s[i.facets[1].scale]:s[i.scale],h=r.left,d=r.top,p=r.width,m=r.height,g=l.valToPosH,x=l.valToPosV;return 0==f.ori?t(i,u,a,f,c,g,x,h,d,p,m,kt,Mt,Tt,zt,Pt):t(i,u,a,f,c,x,g,d,h,m,p,yt,St,Et,Dt,At)}function mt(l,e){let t=0,n=0,i=Q(l.bands,Fl);for(let l=0;i.length>l;l++){let o=i[l];o.series[0]==e?t=o.dir:o.series[1]==e&&(n|=1==o.dir?1:2)}return[t,1==n?-1:2==n?1:3==n?2:0]}function gt(l,e,t,n,i){let o=l.series[e],s=l.scales[2==l.mode?o.facets[1].scale:o.scale];return-1==i?s.min:1==i?s.max:3==s.distr?1==s.dir?s.min:s.max:0}function xt(l,e,t,n,i,o){return pt(l,e,((l,e,s,r,u,a,f,c,h,d,p)=>{let m=l.pxRound;const g=0==r.ori?Mt:St;let x,w;1==r.dir*(0==r.ori?1:-1)?(x=t,w=n):(x=n,w=t);let _=m(a(e[x],r,d,c)),b=m(f(s[x],u,p,h)),v=m(a(e[w],r,d,c)),k=m(f(1==o?u.max:u.min,u,p,h)),y=new Path2D(i);return g(y,v,k),g(y,_,k),g(y,_,b),y}))}function wt(l,e,t,n,i,o){let s=null;if(l.length>0){s=new Path2D;const r=0==e?Tt:Et;let u=t;for(let e=0;l.length>e;e++){let t=l[e];if(t[1]>t[0]){let l=t[0]-u;l>0&&r(s,u,n,l,n+o),u=t[1]}}let a=t+i-u,f=10;a>0&&r(s,u,n-f/2,a,n+o+f)}return s}function _t(l,e,t,n,i,o,s){let r=[],u=l.length;for(let a=1==i?t:n;a>=t&&n>=a;a+=i)if(null===e[a]){let f=a,c=a;if(1==i)for(;++a<=n&&null===e[a];)c=a;else for(;--a>=t&&null===e[a];)c=a;let h=o(l[f]),d=c==f?h:o(l[c]),p=f-i;h=s>0||0>p||p>=u?h:o(l[p]);let m=c+i;d=0>s||0>m||m>=u?d:o(l[m]),h>d||r.push([h,d])}return r}function bt(l){return 0==l?vl:1==l?rl:e=>zl(e,l)}function vt(l){let e=0==l?kt:yt,t=0==l?(l,e,t,n,i,o)=>{l.arcTo(e,t,n,i,o)}:(l,e,t,n,i,o)=>{l.arcTo(t,e,i,n,o)},n=0==l?(l,e,t,n,i)=>{l.rect(e,t,n,i)}:(l,e,t,n,i)=>{l.rect(t,e,i,n)};return(l,i,o,s,r,u=0,a=0)=>{0==u&&0==a?n(l,i,o,s,r):(u=al(u,s/2,r/2),a=al(a,s/2,r/2),e(l,i+u,o),t(l,i+s,o,i+s,o+r,u),t(l,i+s,o+r,i,o+r,a),t(l,i,o+r,i,o,a),t(l,i,o,i+s,o,u),l.closePath())}}const kt=(l,e,t)=>{l.moveTo(e,t)},yt=(l,e,t)=>{l.moveTo(t,e)},Mt=(l,e,t)=>{l.lineTo(e,t)},St=(l,e,t)=>{l.lineTo(t,e)},Tt=vt(0),Et=vt(1),zt=(l,e,t,n,i,o)=>{l.arc(e,t,n,i,o)},Dt=(l,e,t,n,i,o)=>{l.arc(t,e,n,i,o)},Pt=(l,e,t,n,i,o,s)=>{l.bezierCurveTo(e,t,n,i,o,s)},At=(l,e,t,n,i,o,s)=>{l.bezierCurveTo(t,e,i,n,s,o)};function Wt(){return(l,e,t,n,i)=>pt(l,e,((e,o,s,r,u,a,f,c,h,d,p)=>{let m,g,{pxRound:x,points:w}=e;0==r.ori?(m=kt,g=zt):(m=yt,g=Dt);const _=Al(w.width*y,3);let b=(w.size-w.width)/2*y,v=Al(2*b,3),k=new Path2D,M=new Path2D,{left:S,top:T,width:E,height:z}=l.bbox;Tt(M,S-v,T-v,E+2*v,z+2*v);const D=l=>{if(null!=s[l]){let e=x(a(o[l],r,d,c)),t=x(f(s[l],u,p,h));m(k,e+b,t),g(k,e,t,b,0,2*il)}};if(i)i.forEach(D);else for(let l=t;n>=l;l++)D(l);return{stroke:_>0?k:null,fill:k,clip:M,flags:3}}))}function Yt(l){return(e,t,n,i,o,s)=>{n!=i&&(o!=n&&s!=n&&l(e,t,n),o!=i&&s!=i&&l(e,t,i),l(e,t,s))}}const Ct=Yt(Mt),Ht=Yt(St);function Ft(l){const e=Q(l?.alignGaps,0);return(l,t,n,i)=>pt(l,t,((o,s,r,u,a,f,c,h,d,p,m)=>{[n,i]=U(r,n,i);let g,x,w=o.pxRound,_=l=>w(f(l,u,p,h)),b=l=>w(c(l,a,m,d));0==u.ori?(g=Mt,x=Ct):(g=St,x=Ht);const v=u.dir*(0==u.ori?1:-1),k={stroke:new Path2D,fill:null,clip:null,band:null,gaps:null,flags:1},y=k.stroke;let M=!1;if(i-n<4*p)for(let l=1==v?n:i;l>=n&&i>=l;l+=v){let e=r[l];null===e?M=!0:null!=e&&g(y,_(s[l]),b(e))}else{let e,t,o,a=e=>l.posToVal(e,u.key,!0),f=null,c=null,h=_(s[1==v?n:i]),d=_(s[n]),p=_(s[i]),m=a(1==v?d+1:p-1);for(let l=1==v?n:i;l>=n&&i>=l;l+=v){let n=s[l],i=(1==v?m>n:n>m)?h:_(n),o=r[l];i==h?null!=o?(t=o,null==f?(g(y,i,b(t)),e=f=c=t):f>t?f=t:t>c&&(c=t)):null===o&&(M=!0):(null!=f&&x(y,h,b(f),b(c),b(e),b(t)),null!=o?(t=o,g(y,i,b(t)),f=c=e=t):(f=c=null,null===o&&(M=!0)),h=i,m=a(h+v))}null!=f&&f!=c&&o!=h&&x(y,h,b(f),b(c),b(e),b(t))}let[S,T]=mt(l,t);if(null!=o.fill||0!=S){let e=k.fill=new Path2D(y),r=b(o.fillTo(l,t,o.min,o.max,S)),u=_(s[n]),a=_(s[i]);-1==v&&([a,u]=[u,a]),g(e,a,r),g(e,u,r)}if(!o.spanGaps){let a=[];M&&a.push(..._t(s,r,n,i,v,_,e)),k.gaps=a=o.gaps(l,t,n,i,a),k.clip=wt(a,u.ori,h,d,p,m)}return 0!=T&&(k.band=2==T?[xt(l,t,n,i,y,-1),xt(l,t,n,i,y,1)]:xt(l,t,n,i,y,T)),k}))}function Rt(l,e,t,n,i,o,s=gl){if(l.length>1){let r=null;for(let u=0,a=1/0;l.length>u;u++)if(void 0!==e[u]){if(null!=r){let e=ol(l[u]-l[r]);a>e&&(a=e,s=ol(t(l[u],n,i,o)-t(l[r],n,i,o)))}r=u}}return s}function Gt(l,e,t,n,i){const o=l.length;if(2>o)return null;const s=new Path2D;if(t(s,l[0],e[0]),2==o)n(s,l[1],e[1]);else{let t=Array(o),n=Array(o-1),r=Array(o-1),u=Array(o-1);for(let t=0;o-1>t;t++)r[t]=e[t+1]-e[t],u[t]=l[t+1]-l[t],n[t]=r[t]/u[t];t[0]=n[0];for(let l=1;o-1>l;l++)0===n[l]||0===n[l-1]||n[l-1]>0!=n[l]>0?t[l]=0:(t[l]=3*(u[l-1]+u[l])/((2*u[l]+u[l-1])/n[l-1]+(u[l]+2*u[l-1])/n[l]),isFinite(t[l])||(t[l]=0));t[o-1]=n[o-2];for(let n=0;o-1>n;n++)i(s,l[n]+u[n]/3,e[n]+t[n]*u[n]/3,l[n+1]-u[n]/3,e[n+1]-t[n+1]*u[n]/3,l[n+1],e[n+1])}return s}const It=new Set;function Lt(){for(let l of It)l.syncRect(!0)}_&&(G("resize",v,Lt),G("scroll",v,Lt,!0),G(x,v,(()=>{en.pxRatio=y})));const Ot=Ft(),Nt=Wt();function jt(l,e,t,n){return(n?[l[0],l[1]].concat(l.slice(2)):[l[0]].concat(l.slice(1))).map(((l,n)=>Ut(l,n,e,t)))}function Ut(l,e,t,n){return Bl({},0==e?t:n,l)}function Vt(l,e,t){return null==e?Rl:[e,t]}const Bt=Vt;function $t(l,e,t){return null==e?Rl:Z(e,t,J,!0)}function Jt(l,e,t,n){return null==e?Rl:B(e,t,l.scales[n].log,!1)}const qt=Jt;function Kt(l,e,t,n){return null==e?Rl:$(e,t,l.scales[n].log,!1)}const Xt=Kt;function Zt(l,e,t,n,i){let o=fl(xl(l),xl(e)),s=e-l,r=L(i/n*s,t);do{let l=t[r],e=n*l/s;if(e>=i&&17>=o+(5>l?Wl.get(l):0))return[l,e]}while(++r(e=rl((t=+n)*y))+"px")),e,t]}function ln(l){l.show&&[l.font,l.labelFont].forEach((l=>{let e=Al(l[2]*y,1);l[0]=l[0].replace(/[0-9.]+px/,e+"px"),l[1]=e}))}function en(u,g,_){const k={mode:Q(u.mode,1)},M=k.mode;function P(l,e,t,n){let i=e.valToPct(l);return n+t*(-1==e.dir?1-i:i)}function W(l,e,t,n){let i=e.valToPct(l);return n+t*(-1==e.dir?i:1-i)}function C(l,e,t,n){return 0==e.ori?P(l,e,t,n):W(l,e,t,n)}k.valToPosH=P,k.valToPosV=W;let F=!1;k.status=0;const R=k.root=D("uplot");null!=u.id&&(R.id=u.id),S(R,u.class),u.title&&(D("u-title",R).textContent=u.title);const O=z("canvas"),K=k.ctx=O.getContext("2d"),X=D("u-wrap",R);G("click",X,(l=>{l.target===el&&(Nn!=Gn||jn!=In)&&Zn.click(k,l)}),!0);const ll=k.under=D("u-under",X);X.appendChild(O);const el=k.over=D("u-over",X),tl=+Q((u=Vl(u)).pxAlign,1),sl=bt(tl);(u.plugins||[]).forEach((l=>{l.opts&&(u=l.opts(k,u)||u)}));const hl=u.ms||.001,pl=k.series=1==M?jt(u.series||[],Ve,ut,!1):function(l,e){return l.map(((l,t)=>0==t?{}:Bl({},e,l)))}(u.series||[null],rt),xl=k.axes=jt(u.axes||[],Ue,it,!0),vl=k.scales={},Tl=k.bands=u.bands||[];Tl.forEach((l=>{l.fill=bl(l.fill||null),l.dir=Q(l.dir,-1)}));const El=2==M?pl[1].facets[0].scale:pl[0].scale,Dl={axes:function(){for(let l=0;xl.length>l;l++){let e=xl[l];if(!e.show||!e._show)continue;let t,n,u=e.side,a=u%2,f=e.stroke(k,l),c=0==u||3==u?-1:1,[h,d]=e._found;if(null!=e.label){let s=rl((e._lpos+e.labelGap*c)*y);_n(e.labelFont[0],f,"center",2==u?i:o),K.save(),1==a?(t=n=0,K.translate(s,rl(lt+st/2)),K.rotate((3==u?-il:il)/2)):(t=rl(Qe+ot/2),n=s);let r=_l(e.label)?e.label(k,l,h,d):e.label;K.fillText(r,t,n),K.restore()}if(0==d)continue;let p=vl[e.scale],m=0==a?ot:st,g=0==a?Qe:lt,x=e._splits,w=2==p.distr?x.map((l=>pn[l])):x,_=2==p.distr?pn[x[1]]-pn[x[0]]:h,b=e.ticks,v=e.border,M=b.show?b.size:0,S=rl(M*y),T=rl((2==e.alignTo?e._size-M-e.gap:e.gap)*y),E=e._rotate*-il/180,z=sl(e._pos*y),D=z+(S+T)*c;n=0==a?D:0,t=1==a?D:0,_n(e.font[0],f,1==e.align?s:2==e.align?r:E>0?s:0>E?r:0==a?"center":3==u?r:s,E||1==a?"middle":2==u?i:o);let P=e.font[1]*e.lineGap,A=x.map((l=>sl(C(l,p,m,g)))),W=e._values;for(let l=0;W.length>l;l++){let e=W[l];if(null!=e){0==a?t=A[l]:n=A[l],e=""+e;let i=-1==e.indexOf("\n")?[e]:e.split(/\n/gm);for(let l=0;i.length>l;l++){let e=i[l];E?(K.save(),K.translate(t,n+l*P),K.rotate(E),K.fillText(e,0,0),K.restore()):K.fillText(e,t,n+l*P)}}}b.show&&zn(A,b.filter(k,w,l,d,_),a,u,z,S,Al(b.width*y,3),b.stroke(k,l),b.dash,b.cap);let Y=e.grid;Y.show&&zn(A,Y.filter(k,w,l,d,_),a,0==a?2:1,0==a?lt:Qe,0==a?st:ot,Al(Y.width*y,3),Y.stroke(k,l),Y.dash,Y.cap),v.show&&zn([z],[1],0==a?1:0,0==a?1:2,1==a?lt:Qe,1==a?st:ot,Al(v.width*y,3),v.stroke(k,l),v.dash,v.cap)}Ci("drawAxes")},series:function(){if(Gt>0){let l=pl.some((l=>l._focus))&&dn!=Tt.alpha;l&&(K.globalAlpha=dn=Tt.alpha),pl.forEach(((l,e)=>{if(e>0&&l.show&&(kn(e,!1),kn(e,!0),null==l._paths)){let t=dn;dn!=l.alpha&&(K.globalAlpha=dn=l.alpha);let n=2==M?[0,g[e][0].length-1]:function(l){let e=wl(Lt-1,0,Gt-1),t=wl(en+1,0,Gt-1);for(;null==l[e]&&e>0;)e--;for(;null==l[t]&&Gt-1>t;)t++;return[e,t]}(g[e]);l._paths=l.paths(k,e,n[0],n[1]),dn!=t&&(K.globalAlpha=dn=t)}})),pl.forEach(((l,e)=>{if(e>0&&l.show){let t=dn;dn!=l.alpha&&(K.globalAlpha=dn=l.alpha),null!=l._paths&&yn(e,!1);{let t=null!=l._paths?l._paths.gaps:null,n=l.points.show(k,e,Lt,en,t),i=l.points.filter(k,e,n,t);(n||i)&&(l.points._paths=l.points.paths(k,e,Lt,en,i),yn(e,!0))}dn!=t&&(K.globalAlpha=dn=t),Ci("drawSeries",e)}})),l&&(K.globalAlpha=dn=1)}}},Pl=(u.drawOrder||["axes","series"]).map((l=>Dl[l]));function Cl(l){const e=3==l.distr?e=>dl(e>0?e:l.clamp(k,e,l.min,l.max,l.key)):4==l.distr?e=>ml(e,l.asinh):100==l.distr?e=>l.fwd(e):l=>l;return t=>{let n=e(t),{_min:i,_max:o}=l;return(n-i)/(o-i)}}function Il(l){let e=vl[l];if(null==e){let t=(u.scales||Hl)[l]||Hl;if(null!=t.from){Il(t.from);let e=Bl({},vl[t.from],t,{key:l});e.valToPct=Cl(e),vl[l]=e}else{e=vl[l]=Bl({},l==El?ft:ct,t),e.key=l;let n=e.time,i=e.range,o=Gl(i);if((l!=El||2==M&&!n)&&(!o||null!=i[0]&&null!=i[1]||(i={min:null==i[0]?q:{mode:1,hard:i[0],soft:i[0]},max:null==i[1]?q:{mode:1,hard:i[1],soft:i[1]}},o=!1),!o&&Ol(i))){let l=i;i=(e,t,n)=>null==t?Rl:Z(t,n,l)}e.range=bl(i||(n?Bt:l==El?3==e.distr?qt:4==e.distr?Xt:Vt:3==e.distr?Jt:4==e.distr?Kt:$t)),e.auto=bl(!o&&e.auto),e.clamp=bl(e.clamp||at),e._min=e._max=null,e.valToPct=Cl(e)}}}Il("x"),Il("y"),1==M&&pl.forEach((l=>{Il(l.scale)})),xl.forEach((l=>{Il(l.scale)}));for(let l in u.scales)Il(l);const jl=vl[El],Ul=jl.distr;let $l,ql;0==jl.ori?(S(R,"u-hz"),$l=P,ql=W):(S(R,"u-vt"),$l=W,ql=P);const Kl={};for(let l in vl){let e=vl[l];null==e.min&&null==e.max||(Kl[l]={min:e.min,max:e.max},e.min=e.max=null)}const Xl=u.tzDate||(l=>new Date(rl(l/hl))),Zl=u.fmtDate||ne,Ql=1==hl?Me(Xl):Ee(Xl),le=De(Xl,ze(1==hl?ye:Te,Zl)),ee=We(Xl,Ae("{YYYY}-{MM}-{DD} {h}:{mm}{aa}",Zl)),te=[],ie=k.legend=Bl({},Ye,u.legend),oe=k.cursor=Bl({},Re,{drag:{y:2==M}},u.cursor),se=ie.show,re=oe.show,ue=ie.markers;let ce,he,de;ie.idxs=te,ue.width=bl(ue.width),ue.dash=bl(ue.dash),ue.stroke=bl(ue.stroke),ue.fill=bl(ue.fill);let pe,me=[],ge=[],xe=!1,we={};if(ie.live){const l=pl[1]?pl[1].values:null;xe=null!=l,pe=xe?l(k,1,0):{_:0};for(let l in pe)we[l]=w}if(se)if(ce=z("table","u-legend",R),de=z("tbody",null,ce),ie.mount(k,ce),xe){he=z("thead",null,ce,de);let l=z("tr",null,he);for(var _e in z("th",null,l),pe)z("th",e,l).textContent=_e}else S(ce,"u-inline"),ie.live&&S(ce,"u-live");const be={show:!0},ve={show:!1},Pe=new Map;function Ce(l,e,t,n=!0){const i=Pe.get(e)||{},o=oe.bind[l](k,e,t,n);o&&(G(l,e,i[l]=o),Pe.set(e,i))}function He(l,e){const t=Pe.get(e)||{};for(let n in t)null!=l&&n!=l||(I(n,e,t[n]),delete t[n]);null==l&&Pe.delete(e)}let Fe=0,Ge=0,Ie=0,Le=0,Oe=0,Ne=0,je=Oe,Ke=Ne,Xe=Ie,Ze=Le,Qe=0,lt=0,ot=0,st=0;k.bbox={};let ht=!1,pt=!1,mt=!1,xt=!1,wt=!1,_t=!1;function vt(l,e,t){(t||l!=k.width||e!=k.height)&&kt(l,e),An(!1),mt=!0,pt=!0,Jn()}function kt(l,e){k.width=Fe=Ie=l,k.height=Ge=Le=e,Oe=Ne=0,function(){let l=!1,e=!1,t=!1,n=!1;xl.forEach((i=>{if(i.show&&i._show){let{side:o,_size:s}=i,r=s+(null!=i.label?i.labelSize:0);r>0&&(o%2?(Ie-=r,3==o?(Oe+=r,n=!0):t=!0):(Le-=r,0==o?(Ne+=r,l=!0):e=!0))}})),Ct[0]=l,Ct[1]=t,Ct[2]=e,Ct[3]=n,Ie-=Rt[1]+Rt[3],Oe+=Rt[3],Le-=Rt[2]+Rt[0],Ne+=Rt[0]}(),function(){let l=Oe+Ie,e=Ne+Le,t=Oe,n=Ne;function i(i,o){switch(i){case 1:return l+=o,l-o;case 2:return e+=o,e-o;case 3:return t-=o,t+o;case 0:return n-=o,n+o}}xl.forEach((l=>{if(l.show&&l._show){let e=l.side;l._pos=i(e,l._size),null!=l.label&&(l._lpos=i(e,l.labelSize))}}))}();let t=k.bbox;Qe=t.left=zl(Oe*y,.5),lt=t.top=zl(Ne*y,.5),ot=t.width=zl(Ie*y,.5),st=t.height=zl(Le*y,.5)}const yt=3;if(k.setSize=function({width:l,height:e}){vt(l,e)},null==oe.dataIdx){let l=oe.hover,e=l.skip=new Set(l.skip??[]);e.add(void 0);let t=l.prox=bl(l.prox),n=l.bias??=0;oe.dataIdx=(l,i,o,s)=>{if(0==i)return o;let r=o,u=t(l,i,o,s)??gl,a=u>=0&&gl>u,f=0==jl.ori?Ie:Le,c=oe.left,h=g[0],d=g[i];if(e.has(d[o])){r=null;let l,t=null,i=null;if(0==n||-1==n)for(l=o;null==t&&l-- >0;)e.has(d[l])||(t=l);if(0==n||1==n)for(l=o;null==i&&l++e?e>u||(r=i):l>u||(r=t)}else r=null==i?t:null==t||o-t>i-o?i:t}else a&&ol(c-$l(h[o],jl,f,0))>u&&(r=null);return r}}const Mt=l=>{oe.event=l};oe.idxs=te,oe._lock=!1;let St=oe.points;St.show=bl(St.show),St.size=bl(St.size),St.stroke=bl(St.stroke),St.width=bl(St.width),St.fill=bl(St.fill);const Tt=k.focus=Bl({},u.focus||{alpha:.3},oe.focus),Et=Tt.prox>=0,zt=Et&&St.one;let Dt=[],Pt=[],At=[];function Wt(l,e){let t=St.show(k,e);if(t instanceof HTMLElement)return S(t,"u-cursor-pt"),S(t,l.class),A(t,-10,-10,Ie,Le),el.insertBefore(t,Dt[e]),t}function Yt(t,n){if(1==M||n>0){let l=1==M&&vl[t.scale].time,e=t.value;t.value=l?Ll(e)?We(Xl,Ae(e,Zl)):e||ee:e||nt,t.label=t.label||(l?"Time":"Value")}if(zt||n>0){t.width=null==t.width?1:t.width,t.paths=t.paths||Ot||yl,t.fillTo=bl(t.fillTo||gt),t.pxAlign=+Q(t.pxAlign,tl),t.pxRound=bt(t.pxAlign),t.stroke=bl(t.stroke||null),t.fill=bl(t.fill||null),t._stroke=t._fill=t._paths=t._focus=null;let l=function(l){return Al(1*(3+2*(l||1)),3)}(fl(1,t.width)),e=t.points=Bl({},{size:l,width:fl(1,.2*l),stroke:t.stroke,space:2*l,paths:Nt,_stroke:null,_fill:null},t.points);e.show=bl(e.show),e.filter=bl(e.filter),e.fill=bl(e.fill),e.stroke=bl(e.stroke),e.paths=bl(e.paths),e.pxAlign=t.pxAlign}if(se){let i=function(t,n){if(0==n&&(xe||!ie.live||2==M))return Rl;let i=[],o=z("tr","u-series",de,de.childNodes[n]);S(o,t.class),t.show||S(o,l);let s=z("th",null,o);if(ue.show){let l=D("u-marker",s);if(n>0){let e=ue.width(k,n);e&&(l.style.border=e+"px "+ue.dash(k,n)+" "+ue.stroke(k,n)),l.style.background=ue.fill(k,n)}}let r=D(e,s);for(var u in t.label instanceof HTMLElement?r.appendChild(t.label):r.textContent=t.label,n>0&&(ue.show||(r.style.color=t.width>0?ue.stroke(k,n):ue.fill(k,n)),Ce("click",s,(l=>{if(oe._lock)return;Mt(l);let e=pl.indexOf(t);if((l.ctrlKey||l.metaKey)!=ie.isolate){let l=pl.some(((l,t)=>t>0&&t!=e&&l.show));pl.forEach(((t,n)=>{n>0&&oi(n,l?n==e?be:ve:be,!0,Fi.setSeries)}))}else oi(e,{show:!t.show},!0,Fi.setSeries)}),!1),Et&&Ce(d,s,(l=>{oe._lock||(Mt(l),oi(pl.indexOf(t),ai,!0,Fi.setSeries))}),!1)),pe){let l=z("td","u-value",o);l.textContent="--",i.push(l)}return[o,i]}(t,n);me.splice(n,0,i[0]),ge.splice(n,0,i[1]),ie.values.push(null)}if(re){te.splice(n,0,null);let l=null;zt?0==n&&(l=Wt(t,n)):n>0&&(l=Wt(t,n)),Dt.splice(n,0,l),Pt.splice(n,0,0),At.splice(n,0,0)}Ci("addSeries",n)}k.addSeries=function(l,e){e=null==e?pl.length:e,l=1==M?Ut(l,e,Ve,ut):Ut(l,e,{},rt),pl.splice(e,0,l),Yt(pl[e],e)},k.delSeries=function(l){if(pl.splice(l,1),se){ie.values.splice(l,1),ge.splice(l,1);let e=me.splice(l,1)[0];He(null,e.firstChild),e.remove()}re&&(te.splice(l,1),Dt.splice(l,1)[0].remove(),Pt.splice(l,1),At.splice(l,1)),Ci("delSeries",l)};const Ct=[!1,!1,!1,!1];function Ht(l,e,t){let[n,i,o,s]=t,r=e%2,u=0;return 0==r&&(s||i)&&(u=0==e&&!n||2==e&&!o?rl(Ue.size/3):0),1==r&&(n||o)&&(u=1==e&&!i||3==e&&!s?rl(it.size/2):0),u}const Ft=k.padding=(u.padding||[Ht,Ht,Ht,Ht]).map((l=>bl(Q(l,Ht)))),Rt=k._padding=Ft.map(((l,e)=>l(k,e,Ct,0)));let Gt,Lt=null,en=null;const tn=1==M?pl[0].idxs:null;let nn,on,sn,rn,un,an,fn,cn,hn,dn,pn=null,mn=!1;function gn(l,e){if(k.data=k._data=g=null==l?[]:l,2==M){Gt=0;for(let l=1;pl.length>l;l++)Gt+=g[l][0].length}else{0==g.length&&(k.data=k._data=g=[[]]),pn=g[0],Gt=pn.length;let l=g;if(2==Ul){l=g.slice();let e=l[0]=Array(Gt);for(let l=0;Gt>l;l++)e[l]=l}k._data=g=l}if(An(!0),Ci("setData"),2==Ul&&(mt=!0),!1!==e){let l=jl;l.auto(k,mn)?xn():ii(El,l.min,l.max),xt=xt||oe.left>=0,_t=!0,Jn()}}function xn(){let l,e;mn=!0,1==M&&(Gt>0?(Lt=tn[0]=0,en=tn[1]=Gt-1,l=g[0][Lt],e=g[0][en],2==Ul?(l=Lt,e=en):l==e&&(3==Ul?[l,e]=B(l,l,jl.log,!1):4==Ul?[l,e]=$(l,l,jl.log,!1):jl.time?e=l+rl(86400/hl):[l,e]=Z(l,e,J,!0))):(Lt=tn[0]=l=null,en=tn[1]=e=null)),ii(El,l,e)}function wn(l,e,t,n,i,o){l??=a,t??=Fl,n??="butt",i??=a,o??="round",l!=nn&&(K.strokeStyle=nn=l),i!=on&&(K.fillStyle=on=i),e!=sn&&(K.lineWidth=sn=e),o!=un&&(K.lineJoin=un=o),n!=an&&(K.lineCap=an=n),t!=rn&&K.setLineDash(rn=t)}function _n(l,e,t,n){e!=on&&(K.fillStyle=on=e),l!=fn&&(K.font=fn=l),t!=cn&&(K.textAlign=cn=t),n!=hn&&(K.textBaseline=hn=n)}function bn(l,e,t,n,i=0){if(n.length>0&&l.auto(k,mn)&&(null==e||null==e.min)){let e=Q(Lt,0),o=Q(en,n.length-1),s=null==t.min?function(l,e,t,n=0,i=!1){let o=i?V:U,s=i?j:N;[e,t]=o(l,e,t);let r=l[e],u=l[e];if(e>-1)if(1==n)r=l[e],u=l[t];else if(-1==n)r=l[t],u=l[e];else for(let n=e;t>=n;n++){let e=l[n];s(e)&&(r>e?r=e:e>u&&(u=e))}return[r??gl,u??-gl]}(n,e,o,i,3==l.distr):[t.min,t.max];l.min=al(l.min,t.min=s[0]),l.max=fl(l.max,t.max=s[1])}}k.setData=gn;const vn={min:null,max:null};function kn(l,e){let t=e?pl[l].points:pl[l];t._stroke=t.stroke(k,l),t._fill=t.fill(k,l)}function yn(l,e){let t=e?pl[l].points:pl[l],{stroke:n,fill:i,clip:o,flags:s,_stroke:r=t._stroke,_fill:u=t._fill,_width:a=t.width}=t._paths;a=Al(a*y,3);let f=null,c=a%2/2;e&&null==u&&(u=a>0?"#fff":r);let h=1==t.pxAlign&&c>0;if(h&&K.translate(c,c),!e){let l=Qe-a/2,e=lt-a/2,t=ot+a,n=st+a;f=new Path2D,f.rect(l,e,t,n)}e?Sn(r,a,t.dash,t.cap,u,n,i,s,o):function(l,e,t,n,i,o,s,r,u,a,f){let c=!1;0!=u&&Tl.forEach(((h,d)=>{if(h.series[0]==l){let l,p=pl[h.series[1]],m=g[h.series[1]],x=(p._paths||Hl).band;Gl(x)&&(x=1==h.dir?x[0]:x[1]);let w=null;p.show&&x&&function(l,e,t){for(e=Q(e,0),t=Q(t,l.length-1);t>=e;){if(null!=l[e])return!0;e++}return!1}(m,Lt,en)?(w=h.fill(k,d)||o,l=p._paths.clip):x=null,Sn(e,t,n,i,w,s,r,u,a,f,l,x),c=!0}})),c||Sn(e,t,n,i,o,s,r,u,a,f)}(l,r,a,t.dash,t.cap,u,n,i,s,f,o),h&&K.translate(-c,-c)}const Mn=3;function Sn(l,e,t,n,i,o,s,r,u,a,f,c){wn(l,e,t,n,i),(u||a||c)&&(K.save(),u&&K.clip(u),a&&K.clip(a)),c?(r&Mn)==Mn?(K.clip(c),f&&K.clip(f),En(i,s),Tn(l,o,e)):2&r?(En(i,s),K.clip(c),Tn(l,o,e)):1&r&&(K.save(),K.clip(c),f&&K.clip(f),En(i,s),K.restore(),Tn(l,o,e)):(En(i,s),Tn(l,o,e)),(u||a||c)&&K.restore()}function Tn(l,e,t){t>0&&(e instanceof Map?e.forEach(((l,e)=>{K.strokeStyle=nn=e,K.stroke(l)})):null!=e&&l&&K.stroke(e))}function En(l,e){e instanceof Map?e.forEach(((l,e)=>{K.fillStyle=on=e,K.fill(l)})):null!=e&&l&&K.fill(e)}function zn(l,e,t,n,i,o,s,r,u,a){let f=s%2/2;1==tl&&K.translate(f,f),wn(r,s,u,a,r),K.beginPath();let c,h,d,p,m=i+(0==n||3==n?-o:o);0==t?(h=i,p=m):(c=i,d=m);for(let n=0;l.length>n;n++)null!=e[n]&&(0==t?c=d=l[n]:h=p=l[n],K.moveTo(c,h),K.lineTo(d,p));K.stroke(),1==tl&&K.translate(-f,-f)}function Dn(l){let e=!0;return xl.forEach(((t,n)=>{if(!t.show)return;let i=vl[t.scale];if(null==i.min)return void(t._show&&(e=!1,t._show=!1,An(!1)));t._show||(e=!1,t._show=!0,An(!1));let o=t.side,s=o%2,{min:r,max:u}=i,[a,f]=function(l,e,t,n){let i,o=xl[l];if(n>0){let s=o._space=o.space(k,l,e,t,n);i=Zt(e,t,o._incrs=o.incrs(k,l,e,t,n,s),n,s)}else i=[0,0];return o._found=i}(n,r,u,0==s?Ie:Le);if(0==f)return;let c=t._splits=t.splits(k,n,r,u,a,f,2==i.distr),h=2==i.distr?c.map((l=>pn[l])):c,d=2==i.distr?pn[c[1]]-pn[c[0]]:a,p=t._values=t.values(k,t.filter(k,h,n,f,d),n,f,d);t._rotate=2==o?t.rotate(k,p,n,f):0;let m=t._size;t._size=ul(t.size(k,p,n,l)),null!=m&&t._size!=m&&(e=!1)})),e}function Pn(l){let e=!0;return Ft.forEach(((t,n)=>{let i=t(k,n,Ct,l);i!=Rt[n]&&(e=!1),Rt[n]=i})),e}function An(l){pl.forEach(((e,t)=>{t>0&&(e._paths=null,l&&(1==M?(e.min=null,e.max=null):e.facets.forEach((l=>{l.min=null,l.max=null}))))}))}let Wn,Yn,Cn,Hn,Fn,Rn,Gn,In,Ln,On,Nn,jn,Un=!1,Vn=!1,Bn=[];function $n(){Vn=!1;for(let l=0;Bn.length>l;l++)Ci(...Bn[l]);Bn.length=0}function Jn(){Un||(Jl(qn),Un=!0)}function qn(){if(ht&&(function(){for(let l in vl){let e=vl[l];null==Kl[l]&&(null==e.min||null!=Kl[El]&&e.auto(k,mn))&&(Kl[l]=vn)}for(let l in vl){let e=vl[l];null==Kl[l]&&null!=e.from&&null!=Kl[e.from]&&(Kl[l]=vn)}null!=Kl[El]&&An(!0);let l={};for(let e in Kl){let t=Kl[e];if(null!=t){let n=l[e]=Vl(vl[e],Nl);if(null!=t.min)Bl(n,t);else if(e!=El||2==M)if(0==Gt&&null==n.from){let l=n.range(k,null,null,e);n.min=l[0],n.max=l[1]}else n.min=gl,n.max=-gl}}if(Gt>0){pl.forEach(((e,t)=>{if(1==M){let n=e.scale,i=Kl[n];if(null==i)return;let o=l[n];if(0==t){let l=o.range(k,o.min,o.max,n);o.min=l[0],o.max=l[1],Lt=L(o.min,g[0]),en=L(o.max,g[0]),en-Lt>1&&(o.min>g[0][Lt]&&Lt++,g[0][en]>o.max&&en--),e.min=pn[Lt],e.max=pn[en]}else e.show&&e.auto&&bn(o,i,e,g[t],e.sorted);e.idxs[0]=Lt,e.idxs[1]=en}else if(t>0&&e.show&&e.auto){let[n,i]=e.facets,o=n.scale,s=i.scale,[r,u]=g[t],a=l[o],f=l[s];null!=a&&bn(a,Kl[o],n,r,n.sorted),null!=f&&bn(f,Kl[s],i,u,i.sorted),e.min=i.min,e.max=i.max}}));for(let e in l){let t=l[e],n=Kl[e];if(null==t.from&&(null==n||null==n.min)){let l=t.range(k,t.min==gl?null:t.min,t.max==-gl?null:t.max,e);t.min=l[0],t.max=l[1]}}}for(let e in l){let t=l[e];if(null!=t.from){let n=l[t.from];if(null==n.min)t.min=t.max=null;else{let l=t.range(k,n.min,n.max,e);t.min=l[0],t.max=l[1]}}}let e={},t=!1;for(let n in l){let i=l[n],o=vl[n];if(o.min!=i.min||o.max!=i.max){o.min=i.min,o.max=i.max;let l=o.distr;o._min=3==l?dl(o.min):4==l?ml(o.min,o.asinh):100==l?o.fwd(o.min):o.min,o._max=3==l?dl(o.max):4==l?ml(o.max,o.asinh):100==l?o.fwd(o.max):o.max,e[n]=t=!0}}if(t){pl.forEach(((l,t)=>{2==M?t>0&&e.y&&(l._paths=null):e[l.scale]&&(l._paths=null)}));for(let l in e)mt=!0,Ci("setScale",l);re&&oe.left>=0&&(xt=_t=!0)}for(let l in Kl)Kl[l]=null}(),ht=!1),mt&&(function(){let l=!1,e=0;for(;!l;){e++;let t=Dn(e),n=Pn(e);l=e==yt||t&&n,l||(kt(k.width,k.height),pt=!0)}}(),mt=!1),pt){if(E(ll,s,Oe),E(ll,i,Ne),E(ll,t,Ie),E(ll,n,Le),E(el,s,Oe),E(el,i,Ne),E(el,t,Ie),E(el,n,Le),E(X,t,Fe),E(X,n,Ge),O.width=rl(Fe*y),O.height=rl(Ge*y),xl.forEach((({_el:e,_show:t,_size:n,_pos:i,side:o})=>{if(null!=e)if(t){let t=o%2==1;E(e,t?"left":"top",i-(3===o||0===o?n:0)),E(e,t?"width":"height",n),E(e,t?"top":"left",t?Ne:Oe),E(e,t?"height":"width",t?Le:Ie),T(e,l)}else S(e,l)})),nn=on=sn=un=an=fn=cn=hn=rn=null,dn=1,_i(!0),Oe!=je||Ne!=Ke||Ie!=Xe||Le!=Ze){An(!1);let l=Ie/Xe,e=Le/Ze;if(re&&!xt&&oe.left>=0){oe.left*=l,oe.top*=e,Cn&&A(Cn,rl(oe.left),0,Ie,Le),Hn&&A(Hn,0,rl(oe.top),Ie,Le);for(let t=0;Dt.length>t;t++){let n=Dt[t];null!=n&&(Pt[t]*=l,At[t]*=e,A(n,ul(Pt[t]),ul(At[t]),Ie,Le))}}if(ei.show&&!wt&&ei.left>=0&&ei.width>0){ei.left*=l,ei.width*=l,ei.top*=e,ei.height*=e;for(let l in ki)E(ti,l,ei[l])}je=Oe,Ke=Ne,Xe=Ie,Ze=Le}Ci("setSize"),pt=!1}Fe>0&&Ge>0&&(K.clearRect(0,0,O.width,O.height),Ci("drawClear"),Pl.forEach((l=>l())),Ci("draw")),ei.show&&wt&&(ni(ei),wt=!1),re&&xt&&(xi(null,!0,!1),xt=!1),ie.show&&ie.live&&_t&&(mi(),_t=!1),F||(F=!0,k.status=1,Ci("ready")),mn=!1,Un=!1}function Kn(l,e){let t=vl[l];if(null==t.from){if(0==Gt){let n=t.range(k,e.min,e.max,l);e.min=n[0],e.max=n[1]}if(e.min>e.max){let l=e.min;e.min=e.max,e.max=l}if(Gt>1&&null!=e.min&&null!=e.max&&1e-16>e.max-e.min)return;l==El&&2==t.distr&&Gt>0&&(e.min=L(e.min,g[0]),e.max=L(e.max,g[0]),e.min==e.max&&e.max++),Kl[l]=e,ht=!0,Jn()}}k.batch=function(l,e=!1){Un=!0,Vn=e,l(k),qn(),e&&Bn.length>0&&queueMicrotask($n)},k.redraw=(l,e)=>{mt=e||!1,!1!==l?ii(El,jl.min,jl.max):Jn()},k.setScale=Kn;let Xn=!1;const Zn=oe.drag;let Qn=Zn.x,li=Zn.y;re&&(oe.x&&(Wn=D("u-cursor-x",el)),oe.y&&(Yn=D("u-cursor-y",el)),0==jl.ori?(Cn=Wn,Hn=Yn):(Cn=Yn,Hn=Wn),Nn=oe.left,jn=oe.top);const ei=k.select=Bl({show:!0,over:!0,left:0,width:0,top:0,height:0},u.select),ti=ei.show?D("u-select",ei.over?el:ll):null;function ni(l,e){if(ei.show){for(let e in l)ei[e]=l[e],e in ki&&E(ti,e,l[e]);!1!==e&&Ci("setSelect")}}function ii(l,e,t){Kn(l,{min:e,max:t})}function oi(e,t,n,i){null!=t.focus&&function(l){if(l!=ui){let e=null==l,t=1!=Tt.alpha;pl.forEach(((n,i)=>{if(1==M||i>0){let o=e||0==i||i==l;n._focus=e?null:o,t&&function(l,e){pl[l].alpha=e,re&&null!=Dt[l]&&(Dt[l].style.opacity=e),se&&me[l]&&(me[l].style.opacity=e)}(i,o?1:Tt.alpha)}})),ui=l,t&&Jn()}}(e),null!=t.show&&pl.forEach(((n,i)=>{0>=i||e!=i&&null!=e||(n.show=t.show,function(e){if(pl[e].show)se&&T(me[e],l);else if(se&&S(me[e],l),re){let l=zt?Dt[0]:Dt[e];null!=l&&A(l,-10,-10,Ie,Le)}}(i),2==M?(ii(n.facets[0].scale,null,null),ii(n.facets[1].scale,null,null)):ii(n.scale,null,null),Jn())})),!1!==n&&Ci("setSeries",e,t),i&&Ii("setSeries",k,e,t)}let si,ri,ui;k.setSelect=ni,k.setSeries=oi,k.addBand=function(l,e){l.fill=bl(l.fill||null),l.dir=Q(l.dir,-1),Tl.splice(e=null==e?Tl.length:e,0,l)},k.setBand=function(l,e){Bl(Tl[l],e)},k.delBand=function(l){null==l?Tl.length=0:Tl.splice(l,1)};const ai={focus:!0};function fi(l,e,t){let n=vl[e];t&&(l=l/y-(1==n.ori?Ne:Oe));let i=Ie;1==n.ori&&(i=Le,l=i-l),-1==n.dir&&(l=i-l);let o=n._min,s=o+l/i*(n._max-o),r=n.distr;return 3==r?cl(10,s):4==r?((l,e=1)=>nl.sinh(l)*e)(s,n.asinh):100==r?n.bwd(s):s}function ci(l,e){E(ti,s,ei.left=l),E(ti,t,ei.width=e)}function hi(l,e){E(ti,i,ei.top=l),E(ti,n,ei.height=e)}se&&Et&&Ce(p,ce,(l=>{oe._lock||(Mt(l),null!=ui&&oi(null,ai,!0,Fi.setSeries))})),k.valToIdx=l=>L(l,g[0]),k.posToIdx=function(l,e){return L(fi(l,El,e),g[0],Lt,en)},k.posToVal=fi,k.valToPos=(l,e,t)=>0==vl[e].ori?P(l,vl[e],t?ot:Ie,t?Qe:0):W(l,vl[e],t?st:Le,t?lt:0),k.setCursor=(l,e,t)=>{Nn=l.left,jn=l.top,xi(null,e,t)};let di=0==jl.ori?ci:hi,pi=1==jl.ori?ci:hi;function mi(l,e){if(null!=l&&(l.idxs?l.idxs.forEach(((l,e)=>{te[e]=l})):(l=>void 0===l)(l.idx)||te.fill(l.idx),ie.idx=te[0]),se&&ie.live){for(let l=0;pl.length>l;l++)(l>0||1==M&&!xe)&&gi(l,te[l]);!function(){if(se&&ie.live)for(let l=2==M?1:0;pl.length>l;l++){if(0==l&&xe)continue;let e=ie.values[l],t=0;for(let n in e)ge[l][t++].firstChild.nodeValue=e[n]}}()}_t=!1,!1!==e&&Ci("setLegend")}function gi(l,e){let t,n=pl[l],i=0==l&&2==Ul?pn:g[l];xe?t=n.values(k,l,e)??we:(t=n.value(k,null==e?null:i[e],l,e),t=null==t?we:{_:t}),ie.values[l]=t}function xi(l,e,t){let n;Ln=Nn,On=jn,[Nn,jn]=oe.move(k,Nn,jn),oe.left=Nn,oe.top=jn,re&&(Cn&&A(Cn,rl(Nn),0,Ie,Le),Hn&&A(Hn,0,rl(jn),Ie,Le)),si=gl,ri=null;let i=0==jl.ori?Ie:Le,o=1==jl.ori?Ie:Le;if(0>Nn||0==Gt||Lt>en){n=oe.idx=null;for(let l=0;pl.length>l;l++){let e=Dt[l];null!=e&&A(e,-10,-10,Ie,Le)}Et&&oi(null,ai,!0,null==l&&Fi.setSeries),ie.live&&(te.fill(n),_t=!0)}else{let l,e,t;1==M&&(l=0==jl.ori?Nn:jn,e=fi(l,El),n=oe.idx=L(e,g[0],Lt,en),t=$l(g[0][n],jl,i,0));let s=-10,r=-10,u=0,a=0,f=!0,c="",h="";for(let l=2==M?1:0;pl.length>l;l++){let d=pl[l],p=te[l],m=null==p?null:1==M?g[l][p]:g[l][1][p],x=oe.dataIdx(k,l,n,e),w=null==x?null:1==M?g[l][x]:g[l][1][x];if(_t=_t||w!=m||x!=p,te[l]=x,l>0&&d.show){let e=null==x?-10:x==n?t:$l(1==M?g[0][x]:g[l][0][x],jl,i,0),p=null==w?-10:ql(w,1==M?vl[d.scale]:vl[d.facets[1].scale],o,0);if(Et&&null!=w){let e=1==jl.ori?Nn:jn,t=ol(Tt.dist(k,l,x,p,e));if(si>t){let n=Tt.bias;if(0!=n){let i=fi(e,d.scale),o=0>i?-1:1;o!=(0>w?-1:1)||(1==o?1==n?i>w:w>i:1==n?w>i:i>w)||(si=t,ri=l)}else si=t,ri=l}}if(_t||zt){let t,n;0==jl.ori?(t=e,n=p):(t=p,n=e);let i,o,d,m,g,x,w=!0,_=St.bbox;if(null!=_){w=!1;let e=_(k,l);d=e.left,m=e.top,i=e.width,o=e.height}else d=t,m=n,i=o=St.size(k,l);if(x=St.fill(k,l),g=St.stroke(k,l),zt)l!=ri||si>Tt.prox||(s=d,r=m,u=i,a=o,f=w,c=x,h=g);else{let e=Dt[l];null!=e&&(Pt[l]=d,At[l]=m,H(e,i,o,w),Y(e,x,g),A(e,ul(d),ul(m),Ie,Le))}}}}if(zt){let l=Tt.prox;if(_t||(null==ui?l>=si:si>l||ri!=ui)){let l=Dt[0];null!=l&&(Pt[0]=s,At[0]=r,H(l,u,a,f),Y(l,c,h),A(l,ul(s),ul(r),Ie,Le))}}}if(ei.show&&Xn)if(null!=l){let[e,t]=Fi.scales,[n,s]=Fi.match,[r,u]=l.cursor.sync.scales,a=l.cursor.drag;if(Qn=a._x,li=a._y,Qn||li){let a,f,c,h,d,{left:p,top:m,width:g,height:x}=l.select,w=l.scales[r].ori,_=l.posToVal,b=null!=e&&n(e,r),v=null!=t&&s(t,u);b&&Qn?(0==w?(a=p,f=g):(a=m,f=x),c=vl[e],h=$l(_(a,r),c,i,0),d=$l(_(a+f,r),c,i,0),di(al(h,d),ol(d-h))):di(0,i),v&&li?(1==w?(a=p,f=g):(a=m,f=x),c=vl[t],h=ql(_(a,u),c,o,0),d=ql(_(a+f,u),c,o,0),pi(al(h,d),ol(d-h))):pi(0,o)}else yi()}else{let l=ol(Ln-Fn),e=ol(On-Rn);if(1==jl.ori){let t=l;l=e,e=t}Qn=Zn.x&&l>=Zn.dist,li=Zn.y&&e>=Zn.dist;let t,n,s=Zn.uni;null!=s?Qn&&li&&(Qn=l>=s,li=e>=s,Qn||li||(e>l?li=!0:Qn=!0)):Zn.x&&Zn.y&&(Qn||li)&&(Qn=li=!0),Qn&&(0==jl.ori?(t=Gn,n=Nn):(t=In,n=jn),di(al(t,n),ol(n-t)),li||pi(0,o)),li&&(1==jl.ori?(t=Gn,n=Nn):(t=In,n=jn),pi(al(t,n),ol(n-t)),Qn||di(0,i)),Qn||li||(di(0,0),pi(0,0))}if(Zn._x=Qn,Zn._y=li,null==l){if(t){if(null!=Ri){let[l,e]=Fi.scales;Fi.values[0]=null!=l?fi(0==jl.ori?Nn:jn,l):null,Fi.values[1]=null!=e?fi(1==jl.ori?Nn:jn,e):null}Ii(f,k,Nn,jn,Ie,Le,n)}if(Et){let l=t&&Fi.setSeries,e=Tt.prox;null==ui?si>e||oi(ri,ai,!0,l):si>e?oi(null,ai,!0,l):ri!=ui&&oi(ri,ai,!0,l)}}_t&&(ie.idx=n,mi()),!1!==e&&Ci("setCursor")}k.setLegend=mi;let wi=null;function _i(l=!1){l?wi=null:(wi=el.getBoundingClientRect(),Ci("syncRect",wi))}function bi(l,e,t,n,i,o){oe._lock||Xn&&null!=l&&0==l.movementX&&0==l.movementY||(vi(l,e,t,n,i,o,0,!1,null!=l),null!=l?xi(null,!0,!0):xi(e,!0,!1))}function vi(l,e,t,n,i,o,s,r,u){if(null==wi&&_i(!1),Mt(l),null!=l)t=l.clientX-wi.left,n=l.clientY-wi.top;else{if(0>t||0>n)return Nn=-10,void(jn=-10);let[l,s]=Fi.scales,r=e.cursor.sync,[u,a]=r.values,[f,c]=r.scales,[h,d]=Fi.match,p=e.axes[0].side%2==1,m=0==jl.ori?Ie:Le,g=1==jl.ori?Ie:Le,x=p?o:i,w=p?i:o,_=p?n:t,b=p?t:n;if(t=null!=f?h(l,f)?C(u,vl[l],m,0):-10:m*(_/x),n=null!=c?d(s,c)?C(a,vl[s],g,0):-10:g*(b/w),1==jl.ori){let l=t;t=n,n=l}}!u||null!=e&&e.cursor.event.type!=f||(t>1&&Ie-1>t||(t=zl(t,Ie)),n>1&&Le-1>n||(n=zl(n,Le))),r?(Fn=t,Rn=n,[Gn,In]=oe.move(k,t,n)):(Nn=t,jn=n)}Object.defineProperty(k,"rect",{get:()=>(null==wi&&_i(!1),wi)});const ki={width:0,height:0,left:0,top:0};function yi(){ni(ki,!1)}let Mi,Si,Ti,Ei;function zi(l,e,t,n,i,o){Xn=!0,Qn=li=Zn._x=Zn._y=!1,vi(l,e,t,n,i,o,0,!0,!1),null!=l&&(Ce(h,b,Di,!1),Ii(c,k,Gn,In,Ie,Le,null));let{left:s,top:r,width:u,height:a}=ei;Mi=s,Si=r,Ti=u,Ei=a}function Di(l,e,t,n,i,o){Xn=Zn._x=Zn._y=!1,vi(l,e,t,n,i,o,0,!1,!0);let{left:s,top:r,width:u,height:a}=ei,f=u>0||a>0,c=Mi!=s||Si!=r||Ti!=u||Ei!=a;if(f&&c&&ni(ei),Zn.setScale&&f&&c){let l=s,e=u,t=r,n=a;if(1==jl.ori&&(l=r,e=a,t=s,n=u),Qn&&ii(El,fi(l,El),fi(l+e,El)),li)for(let l in vl){let e=vl[l];l!=El&&null==e.from&&e.min!=gl&&ii(l,fi(t+n,l),fi(t,l))}yi()}else oe.lock&&(oe._lock=!oe._lock,xi(e,!0,null!=l));null!=l&&(He(h,b),Ii(h,k,Nn,jn,Ie,Le,null))}function Pi(l){oe._lock||(Mt(l),xn(),yi(),null!=l&&Ii(m,k,Nn,jn,Ie,Le,null))}function Ai(){xl.forEach(ln),vt(k.width,k.height,!0)}G(x,v,Ai);const Wi={};Wi.mousedown=zi,Wi.mousemove=bi,Wi.mouseup=Di,Wi.dblclick=Pi,Wi.setSeries=(l,e,t,n)=>{-1!=(t=(0,Fi.match[2])(k,e,t))&&oi(t,n,!0,!1)},re&&(Ce(c,el,zi),Ce(f,el,bi),Ce(d,el,(l=>{Mt(l),_i(!1)})),Ce(p,el,(function(l){if(oe._lock)return;Mt(l);let e=Xn;if(Xn){let l,e,t=!0,n=!0,i=10;0==jl.ori?(l=Qn,e=li):(l=li,e=Qn),l&&e&&(t=i>=Nn||Nn>=Ie-i,n=i>=jn||jn>=Le-i),l&&t&&(Nn=Gn>Nn?0:Ie),e&&n&&(jn=In>jn?0:Le),xi(null,!0,!0),Xn=!1}Nn=-10,jn=-10,te.fill(null),xi(null,!0,!0),e&&(Xn=e)})),Ce(m,el,Pi),It.add(k),k.syncRect=_i);const Yi=k.hooks=u.hooks||{};function Ci(l,e,t){Vn?Bn.push([l,e,t]):l in Yi&&Yi[l].forEach((l=>{l.call(null,k,e,t)}))}(u.plugins||[]).forEach((l=>{for(let e in l.hooks)Yi[e]=(Yi[e]||[]).concat(l.hooks[e])}));const Hi=(l,e,t)=>t,Fi=Bl({key:null,setSeries:!1,filters:{pub:Ml,sub:Ml},scales:[El,pl[1]?pl[1].scale:null],match:[Sl,Sl,Hi],values:[null,null]},oe.sync);2==Fi.match.length&&Fi.match.push(Hi),oe.sync=Fi;const Ri=Fi.key,Gi=dt(Ri);function Ii(l,e,t,n,i,o,s){Fi.filters.pub(l,e,t,n,i,o,s)&&Gi.pub(l,e,t,n,i,o,s)}function Li(){Ci("init",u,g),gn(g||u.data,!1),Kl[El]?Kn(El,Kl[El]):xn(),wt=ei.show&&(ei.width>0||ei.height>0),xt=_t=!0,vt(u.width,u.height)}return Gi.sub(k),k.pub=function(l,e,t,n,i,o,s){Fi.filters.sub(l,e,t,n,i,o,s)&&Wi[l](null,e,t,n,i,o,s)},k.destroy=function(){Gi.unsub(k),It.delete(k),Pe.clear(),I(x,v,Ai),R.remove(),ce?.remove(),Ci("destroy")},pl.forEach(Yt),xl.forEach((function(l,e){if(l._show=l.show,l.show){let t=vl[l.scale];null==t&&(l.scale=l.side%2?pl[1].scale:El,t=vl[l.scale]);let n=t.time;l.size=bl(l.size),l.space=bl(l.space),l.rotate=bl(l.rotate),Gl(l.incrs)&&l.incrs.forEach((l=>{!Wl.has(l)&&Wl.set(l,Yl(l))})),l.incrs=bl(l.incrs||(2==t.distr?ae:n?1==hl?ke:Se:fe)),l.splits=bl(l.splits||(n&&1==t.distr?Ql:3==t.distr?Je:4==t.distr?qe:$e)),l.stroke=bl(l.stroke),l.grid.stroke=bl(l.grid.stroke),l.ticks.stroke=bl(l.ticks.stroke),l.border.stroke=bl(l.border.stroke);let i=l.values;l.values=Gl(i)&&!Gl(i[0])?bl(i):n?Gl(i)?De(Xl,ze(i,Zl)):Ll(i)?function(l,e){let t=ne(e);return(e,n)=>n.map((e=>t(l(e))))}(Xl,i):i||le:i||Be,l.filter=bl(l.filter||(3>t.distr||10!=t.log?3==t.distr&&2==t.log?tt:kl:et)),l.font=Qt(l.font),l.labelFont=Qt(l.labelFont),l._size=l.size(k,null,e,0),l._space=l._rotate=l._incrs=l._found=l._splits=l._values=null,l._size>0&&(Ct[e]=!0,l._el=D("u-axis",X))}})),_?_ instanceof HTMLElement?(_.appendChild(R),Li()):_(k,Li):Li(),k}en.assign=Bl,en.fmtNum=tl,en.rangeNum=Z,en.rangeLog=B,en.rangeAsinh=$,en.orient=pt,en.pxRatio=y,en.join=function(l,e){if(function(l){let e=l[0][0],t=e.length;for(let n=1;l.length>n;n++){let i=l[n][0];if(i.length!=t)return!1;if(i!=e)for(let l=0;t>l;l++)if(i[l]!=e[l])return!1}return!0}(l)){let e=l[0].slice();for(let t=1;l.length>t;t++)e.push(...l[t].slice(1));return function(l,e=100){const t=l.length;if(1>=t)return!0;let n=0,i=t-1;for(;i>=n&&null==l[n];)n++;for(;i>=n&&null==l[i];)i--;if(n>=i)return!0;const o=fl(1,sl((i-n+1)/e));for(let e=l[n],t=n+o;i>=t;t+=o){const n=l[t];if(null!=n){if(e>=n)return!1;e=n}}return!0}(e[0])||(e=function(l){let e=l[0],t=e.length,n=Array(t);for(let l=0;n.length>l;l++)n[l]=l;n.sort(((l,t)=>e[l]-e[t]));let i=[];for(let e=0;l.length>e;e++){let o=l[e],s=Array(t);for(let l=0;t>l;l++)s[l]=o[n[l]];i.push(s)}return i}(e)),e}let t=new Set;for(let e=0;l.length>e;e++){let n=l[e][0],i=n.length;for(let l=0;i>l;l++)t.add(n[l])}let n=[Array.from(t).sort(((l,e)=>l-e))],i=n[0].length,o=new Map;for(let l=0;i>l;l++)o.set(n[0][l],l);for(let t=0;l.length>t;t++){let s=l[t],r=s[0];for(let l=1;s.length>l;l++){let u=s[l],a=Array(i).fill(void 0),f=e?e[t][l]:1,c=[];for(let l=0;u.length>l;l++){let e=u[l],t=o.get(r[l]);null===e?0!=f&&(a[t]=e,2==f&&c.push(t)):a[t]=e}$l(a,c,i),n.push(a)}}return n},en.fmtDate=ne,en.tzDate=function(l,e){let t;return"UTC"==e||"Etc/UTC"==e?t=new Date(+l+6e4*l.getTimezoneOffset()):e==ie?t=l:(t=new Date(l.toLocaleString("en-US",{timeZone:e})),t.setMilliseconds(l.getMilliseconds())),t},en.sync=dt;{en.addGap=function(l,e,t){let n=l[l.length-1];n&&n[0]==e?n[1]=t:l.push([e,t])},en.clipGaps=wt;let l=en.paths={points:Wt};l.linear=Ft,l.stepped=function(l){const e=Q(l.align,1),t=Q(l.ascDesc,!1),n=Q(l.alignGaps,0),i=Q(l.extend,!1);return(l,o,s,r)=>pt(l,o,((u,a,f,c,h,d,p,m,g,x,w)=>{[s,r]=U(f,s,r);let _=u.pxRound,{left:b,width:v}=l.bbox,k=l=>_(d(l,c,x,m)),M=l=>_(p(l,h,w,g)),S=0==c.ori?Mt:St;const T={stroke:new Path2D,fill:null,clip:null,band:null,gaps:null,flags:1},E=T.stroke,z=c.dir*(0==c.ori?1:-1);let D=M(f[1==z?s:r]),P=k(a[1==z?s:r]),A=P,W=P;i&&-1==e&&(W=b,S(E,W,D)),S(E,P,D);for(let l=1==z?s:r;l>=s&&r>=l;l+=z){let t=f[l];if(null==t)continue;let n=k(a[l]),i=M(t);1==e?S(E,n,D):S(E,A,i),S(E,n,i),D=i,A=n}let Y=A;i&&1==e&&(Y=b+v,S(E,Y,D));let[C,H]=mt(l,o);if(null!=u.fill||0!=C){let e=T.fill=new Path2D(E),t=M(u.fillTo(l,o,u.min,u.max,C));S(e,Y,t),S(e,W,t)}if(!u.spanGaps){let i=[];i.push(..._t(a,f,s,r,z,k,n));let h=u.width*y/2,d=t||1==e?h:-h,p=t||-1==e?-h:h;i.forEach((l=>{l[0]+=d,l[1]+=p})),T.gaps=i=u.gaps(l,o,s,r,i),T.clip=wt(i,c.ori,m,g,x,w)}return 0!=H&&(T.band=2==H?[xt(l,o,s,r,E,-1),xt(l,o,s,r,E,1)]:xt(l,o,s,r,E,H)),T}))},l.bars=function(l){const e=Q((l=l||Hl).size,[.6,gl,1]),t=l.align||0,n=l.gap||0;let i=l.radius;i=null==i?[0,0]:"number"==typeof i?[i,0]:i;const o=bl(i),s=1-e[0],r=Q(e[1],gl),u=Q(e[2],1),a=Q(l.disp,Hl),f=Q(l.each,(()=>{})),{fill:c,stroke:h}=a;return(l,e,i,d)=>pt(l,e,((p,m,g,x,w,_,b,v,k,M,S)=>{let T,E,z=p.pxRound,D=t,P=n*y,A=r*y,W=u*y;0==x.ori?[T,E]=o(l,e):[E,T]=o(l,e);const Y=x.dir*(0==x.ori?1:-1);let C,H,F,R=0==x.ori?Tt:Et,G=0==x.ori?f:(l,e,t,n,i,o,s)=>{f(l,e,t,i,n,s,o)},I=Q(l.bands,Fl).find((l=>l.series[0]==e)),L=p.fillTo(l,e,p.min,p.max,null!=I?I.dir:0),O=z(b(L,w,S,k)),N=M,j=z(p.width*y),U=!1,V=null,B=null,$=null,J=null;null==c||0!=j&&null==h||(U=!0,V=c.values(l,e,i,d),B=new Map,new Set(V).forEach((l=>{null!=l&&B.set(l,new Path2D)})),j>0&&($=h.values(l,e,i,d),J=new Map,new Set($).forEach((l=>{null!=l&&J.set(l,new Path2D)}))));let{x0:q,size:K}=a;if(null!=q&&null!=K){D=1,m=q.values(l,e,i,d),2==q.unit&&(m=m.map((e=>l.posToVal(v+e*M,x.key,!0))));let t=K.values(l,e,i,d);H=2==K.unit?t[0]*M:_(t[0],x,M,v)-_(0,x,M,v),N=Rt(m,g,_,x,M,v,N),F=N-H+P}else N=Rt(m,g,_,x,M,v,N),F=N*s+P,H=N-F;1>F&&(F=0),H/2>j||(j=0),5>F&&(z=vl);let X=F>0;H=z(wl(N-F-(X?j:0),W,A)),C=(0==D?H/2:D==Y?0:H)-D*Y*((0==D?P/2:0)+(X?j/2:0));const Z={stroke:null,fill:null,clip:null,band:null,gaps:null,flags:0},ll=U?null:new Path2D;let el=null;if(null!=I)el=l.data[I.series[1]];else{let{y0:t,y1:n}=a;null!=t&&null!=n&&(g=n.values(l,e,i,d),el=t.values(l,e,i,d))}let tl=T*H,nl=E*H;for(let t=1==Y?i:d;t>=i&&d>=t;t+=Y){let n=g[t];if(null==n)continue;if(null!=el){let l=el[t]??0;if(n-l==0)continue;O=b(l,w,S,k)}let i=_(2!=x.distr||null!=a?m[t]:t,x,M,v),o=b(Q(n,L),w,S,k),s=z(i-C),r=z(fl(o,O)),u=z(al(o,O)),f=r-u;if(null!=n){let i=0>n?nl:tl,o=0>n?tl:nl;U?(j>0&&null!=$[t]&&R(J.get($[t]),s,u+sl(j/2),H,fl(0,f-j),i,o),null!=V[t]&&R(B.get(V[t]),s,u+sl(j/2),H,fl(0,f-j),i,o)):R(ll,s,u+sl(j/2),H,fl(0,f-j),i,o),G(l,e,t,s-j/2,u,H+j,f)}}return j>0?Z.stroke=U?J:ll:U||(Z._fill=0==p.width?p._fill:p._stroke??p._fill,Z.width=0),Z.fill=U?B:ll,Z}))},l.spline=function(l){return function(l,e){const t=Q(e?.alignGaps,0);return(e,n,i,o)=>pt(e,n,((s,r,u,a,f,c,h,d,p,m,g)=>{[i,o]=U(u,i,o);let x,w,_,b=s.pxRound,v=l=>b(c(l,a,m,d)),k=l=>b(h(l,f,g,p));0==a.ori?(x=kt,_=Mt,w=Pt):(x=yt,_=St,w=At);const y=a.dir*(0==a.ori?1:-1);let M=v(r[1==y?i:o]),S=M,T=[],E=[];for(let l=1==y?i:o;l>=i&&o>=l;l+=y)if(null!=u[l]){let e=v(r[l]);T.push(S=e),E.push(k(u[l]))}const z={stroke:l(T,E,x,_,w,b),fill:null,clip:null,band:null,gaps:null,flags:1},D=z.stroke;let[P,A]=mt(e,n);if(null!=s.fill||0!=P){let l=z.fill=new Path2D(D),t=k(s.fillTo(e,n,s.min,s.max,P));_(l,S,t),_(l,M,t)}if(!s.spanGaps){let l=[];l.push(..._t(r,u,i,o,y,v,t)),z.gaps=l=s.gaps(e,n,i,o,l),z.clip=wt(l,a.ori,d,p,m,g)}return 0!=A&&(z.band=2==A?[xt(e,n,i,o,D,-1),xt(e,n,i,o,D,1)]:xt(e,n,i,o,D,A)),z}))}(Gt,l)}}return en}(); diff --git a/.claude/skills/session-metrics/scripts/vendor/charts/uplot/v1/uPlot.min.css b/.claude/skills/session-metrics/scripts/vendor/charts/uplot/v1/uPlot.min.css new file mode 100644 index 0000000..a030d63 --- /dev/null +++ b/.claude/skills/session-metrics/scripts/vendor/charts/uplot/v1/uPlot.min.css @@ -0,0 +1 @@ +.uplot, .uplot *, .uplot *::before, .uplot *::after {box-sizing: border-box;}.uplot {font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";line-height: 1.5;width: min-content;}.u-title {text-align: center;font-size: 18px;font-weight: bold;}.u-wrap {position: relative;user-select: none;}.u-over, .u-under {position: absolute;}.u-under {overflow: hidden;}.uplot canvas {display: block;position: relative;width: 100%;height: 100%;}.u-axis {position: absolute;}.u-legend {font-size: 14px;margin: auto;text-align: center;}.u-inline {display: block;}.u-inline * {display: inline-block;}.u-inline tr {margin-right: 16px;}.u-legend th {font-weight: 600;}.u-legend th > * {vertical-align: middle;display: inline-block;}.u-legend .u-marker {width: 1em;height: 1em;margin-right: 4px;background-clip: padding-box !important;}.u-inline.u-live th::after {content: ":";vertical-align: middle;}.u-inline:not(.u-live) .u-value {display: none;}.u-series > * {padding: 4px;}.u-series th {cursor: pointer;}.u-legend .u-off > * {opacity: 0.3;}.u-select {background: rgba(0,0,0,0.07);position: absolute;pointer-events: none;}.u-cursor-x, .u-cursor-y {position: absolute;left: 0;top: 0;pointer-events: none;will-change: transform;}.u-hz .u-cursor-x, .u-vt .u-cursor-y {height: 100%;border-right: 1px dashed #607D8B;}.u-hz .u-cursor-y, .u-vt .u-cursor-x {width: 100%;border-bottom: 1px dashed #607D8B;}.u-cursor-pt {position: absolute;top: 0;left: 0;border-radius: 50%;border: 0 solid;pointer-events: none;will-change: transform;/*this has to be !important since we set inline "background" shorthand */background-clip: padding-box !important;}.u-axis.u-off, .u-select.u-off, .u-cursor-x.u-off, .u-cursor-y.u-off, .u-cursor-pt.u-off {display: none;} \ No newline at end of file diff --git a/.claude/skills/session-metrics/tests/fixtures/mini.jsonl b/.claude/skills/session-metrics/tests/fixtures/mini.jsonl new file mode 100644 index 0000000..1bb7c9b --- /dev/null +++ b/.claude/skills/session-metrics/tests/fixtures/mini.jsonl @@ -0,0 +1,12 @@ +{"type":"user","uuid":"u1","timestamp":"2026-04-15T22:30:00.000Z","isMeta":true,"sessionId":"s1","message":{"role":"user","content":[{"type":"text","text":""}]}} +{"type":"user","uuid":"u2","timestamp":"2026-04-15T22:31:00.000Z","sessionId":"s1","message":{"role":"user","content":[{"type":"text","text":"hello as list"}]}} +{"type":"assistant","uuid":"a1","timestamp":"2026-04-15T22:31:05.000Z","sessionId":"s1","message":{"id":"msg_A","model":"claude-opus-4-7","role":"assistant","usage":{"input_tokens":100,"output_tokens":50,"cache_read_input_tokens":0,"cache_creation_input_tokens":1000}}} +{"type":"assistant","uuid":"a1b","timestamp":"2026-04-15T22:31:06.000Z","sessionId":"s1","message":{"id":"msg_A","model":"claude-opus-4-7","role":"assistant","usage":{"input_tokens":120,"output_tokens":80,"cache_read_input_tokens":500,"cache_creation_input_tokens":1000}}} +{"type":"user","uuid":"u3","timestamp":"2026-04-15T22:31:10.000Z","sessionId":"s1","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"t1","content":"ok"}]}} +{"type":"assistant","uuid":"a2","timestamp":"2026-04-15T22:31:15.000Z","sessionId":"s1","message":{"id":"msg_B","model":"claude-sonnet-4-7","role":"assistant","usage":{"input_tokens":10,"output_tokens":20,"cache_read_input_tokens":2000,"cache_creation_input_tokens":0}}} +{"type":"user","uuid":"u4","timestamp":"2026-04-15T22:31:20.000Z","sessionId":"s1","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"t2","content":"ok"}]}} +{"type":"user","uuid":"u5","timestamp":"2026-04-15T22:31:25.000Z","isSidechain":true,"sessionId":"s1","message":{"role":"user","content":[{"type":"text","text":"subagent"}]}} +{"type":"assistant","uuid":"a3","timestamp":"2026-04-15T22:31:30.000Z","sessionId":"s1","message":{"id":"msg_C","model":"claude-opus-4-7","role":"assistant","usage":{"input_tokens":5,"output_tokens":15,"cache_read_input_tokens":3000,"cache_creation_input_tokens":0}}} +{"type":"user","uuid":"u6","timestamp":"2026-04-16T03:45:00.000Z","sessionId":"s1","message":{"role":"user","content":"second prompt as plain string"}} +{"type":"user","uuid":"u7","timestamp":"2026-04-16T03:45:05.000Z","sessionId":"s1","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"t3","content":"ok"}]}} +{"type":"assistant","uuid":"a4","timestamp":"2026-04-16T03:45:10.000Z","sessionId":"s1","message":{"id":"msg_D","model":"claude-sonnet-4-7","role":"assistant","usage":{"input_tokens":200,"output_tokens":300,"cache_read_input_tokens":1500,"cache_creation_input_tokens":0}}} diff --git a/.claude/skills/session-metrics/tests/test_session_metrics.py b/.claude/skills/session-metrics/tests/test_session_metrics.py new file mode 100644 index 0000000..030ce05 --- /dev/null +++ b/.claude/skills/session-metrics/tests/test_session_metrics.py @@ -0,0 +1,705 @@ +"""Unit + integration tests for session-metrics.py. + +Run with: uv run python -m pytest tests/ -v +""" +import importlib.util +import sys +from pathlib import Path + +import pytest + +_HERE = Path(__file__).parent +_SCRIPT = _HERE.parent / "scripts" / "session-metrics.py" +_FIXTURE = _HERE / "fixtures" / "mini.jsonl" + + +def _load_module(): + spec = importlib.util.spec_from_file_location("session_metrics", _SCRIPT) + mod = importlib.util.module_from_spec(spec) + sys.modules["session_metrics"] = mod + spec.loader.exec_module(mod) + return mod + + +sm = _load_module() + + +# --- Pricing ----------------------------------------------------------------- + +def test_pricing_opus_4_7_explicit(): + # Opus 4.5-generation uses the new cheaper tier: $5 input / $25 output. + r = sm._pricing_for("claude-opus-4-7") + assert r["input"] == 5.00 + assert r["output"] == 25.00 + assert r["cache_read"] == 0.50 + assert r["cache_write"] == 6.25 + + +def test_pricing_sonnet_4_7_explicit(): + r = sm._pricing_for("claude-sonnet-4-7") + assert r["input"] == 3.00 + + +def test_pricing_opus_4_old_tier_retained(): + # Opus 4 / 4.1 stayed on the original $15 / $75 tier. + r = sm._pricing_for("claude-opus-4") + assert r["input"] == 15.00 + assert r["output"] == 75.00 + + +def test_pricing_haiku_4_5_new_tier(): + # Haiku 4.5 has its own tier: $1 input / $5 output. + r = sm._pricing_for("claude-haiku-4-5-20251001") + assert r["input"] == 1.00 + assert r["output"] == 5.00 + + +def test_pricing_prefix_fallback(): + """Unknown future model falls through to nearest known prefix.""" + # "claude-opus-4-99-future" doesn't start with 4-5/4-6/4-7/4-1, so it + # matches "claude-opus-4" (old-tier). Safer to over- than under-estimate. + r = sm._pricing_for("claude-opus-4-99-future") + assert r["input"] == 15.00 + + +# --- Cost math --------------------------------------------------------------- + +def test_cost_opus_all_buckets(): + usage = { + "input_tokens": 120, + "output_tokens": 80, + "cache_read_input_tokens": 500, + "cache_creation_input_tokens": 1000, + } + # Opus 4.7 new tier: 120*5 + 80*25 + 500*0.5 + 1000*6.25 + # = 600 + 2000 + 250 + 6250 = 9100 per M + assert sm._cost(usage, "claude-opus-4-7") == pytest.approx(0.00910, abs=1e-7) + + +def test_no_cache_cost_folds_cache_tokens(): + usage = { + "input_tokens": 10, "output_tokens": 5, + "cache_read_input_tokens": 1000, "cache_creation_input_tokens": 500, + } + # hypothetical: (10 + 1000 + 500) * 5/M + 5 * 25/M (Opus 4.7 new tier) + expected = (1510 * 5 + 5 * 25) / 1_000_000 + assert sm._no_cache_cost(usage, "claude-opus-4-7") == pytest.approx(expected) + + +# --- User-prompt filter ------------------------------------------------------ + +def test_is_user_prompt_text_list(): + assert sm._is_user_prompt({"type": "user", "message": {"content": [{"type": "text", "text": "hi"}]}}) + + +def test_is_user_prompt_image_list(): + assert sm._is_user_prompt({"type": "user", "message": {"content": [{"type": "image"}]}}) + + +def test_is_user_prompt_plain_string(): + assert sm._is_user_prompt({"type": "user", "message": {"content": "hello"}}) + + +def test_is_user_prompt_excludes_tool_result(): + assert not sm._is_user_prompt({"type": "user", "message": {"content": [{"type": "tool_result"}]}}) + + +def test_is_user_prompt_excludes_meta(): + assert not sm._is_user_prompt({"type": "user", "isMeta": True, + "message": {"content": [{"type": "text", "text": "x"}]}}) + + +def test_is_user_prompt_excludes_empty_string(): + assert not sm._is_user_prompt({"type": "user", "message": {"content": ""}}) + + +def test_is_user_prompt_excludes_assistant_type(): + assert not sm._is_user_prompt({"type": "assistant", "message": {"content": "hi"}}) + + +# --- Dedup + timestamp extraction on the fixture ---------------------------- + +def test_fixture_dedup_keeps_last_write(): + entries = sm._parse_jsonl(_FIXTURE) + turns = sm._extract_turns(entries) + assert len(turns) == 4 + by_id = {t["message"]["id"]: t["message"]["usage"] for t in turns} + # msg_A appears twice; the last write (120/80/500/1000) must win + assert by_id["msg_A"]["input_tokens"] == 120 + assert by_id["msg_A"]["cache_read_input_tokens"] == 500 + + +def test_fixture_user_timestamps_default_excludes_sidechain_and_tool_results(): + entries = sm._parse_jsonl(_FIXTURE) + ts = sm._extract_user_timestamps(entries) + # u2 (text list) + u6 (plain string) = 2. u1 meta, u3/u4/u7 tool_result, + # u5 sidechain — all excluded. + assert len(ts) == 2 + + +def test_fixture_user_timestamps_include_sidechain_adds_one(): + entries = sm._parse_jsonl(_FIXTURE) + ts = sm._extract_user_timestamps(entries, include_sidechain=True) + # adds u5 sidechain text + assert len(ts) == 3 + + +# --- End-to-end totals on the fixture --------------------------------------- + +def _build_fixture_report(): + sid, turns, user_ts = sm._load_session(_FIXTURE, include_subagents=False) + return sm._build_report("session", "test-slug", [(sid, turns, user_ts)]) + + +def test_fixture_total_cost_exact(): + r = _build_fixture_report() + # New Opus 4.7 tier ($5/$25/$0.50/$6.25), Sonnet 4.7 unchanged ($3/$15/$0.30/$3.75). + # msg_A (opus, deduped, last write wins): 120*5 + 80*25 + 500*0.5 + 1000*6.25 = 9100/M = 0.00910 + # msg_B (sonnet): 10*3 + 20*15 + 2000*0.3 + 0*3.75 = 930/M = 0.00093 + # msg_C (opus): 5*5 + 15*25 + 3000*0.5 + 0*6.25 = 1900/M = 0.00190 + # msg_D (sonnet): 200*3 + 300*15 + 1500*0.3 + 0*3.75 = 5550/M = 0.00555 + # Total = 0.01748 + assert r["totals"]["cost"] == pytest.approx(0.01748, abs=1e-7) + + +def test_fixture_turns_count_and_models(): + r = _build_fixture_report() + assert r["totals"]["turns"] == 4 + assert r["models"]["claude-opus-4-7"] == 2 + assert r["models"]["claude-sonnet-4-7"] == 2 + + +def test_fixture_time_of_day_total_is_user_prompt_count(): + r = _build_fixture_report() + # 2 real user prompts — must NOT equal the 7 user-type entries in the file + assert r["time_of_day"]["message_count"] == 2 + + +# --- Input validation -------------------------------------------------------- + +def test_validate_session_id_accepts_uuid_and_hex(): + assert sm._validate_session_id("ca4ecd6c-93c2-4b60-9fc3-37d20120e306") + assert sm._validate_session_id("abc123") + + +def test_validate_session_id_rejects_traversal(): + import argparse + with pytest.raises(argparse.ArgumentTypeError): + sm._validate_session_id("../etc/passwd") + with pytest.raises(argparse.ArgumentTypeError): + sm._validate_session_id("a/b") + + +def test_validate_slug_preserves_leading_dash(): + assert sm._validate_slug("-Volumes-foo-bar") + + +def test_validate_slug_rejects_slashes_and_traversal(): + import argparse + with pytest.raises(argparse.ArgumentTypeError): + sm._validate_slug("foo/bar") + with pytest.raises(argparse.ArgumentTypeError): + sm._validate_slug("foo/../bar") + + +# --- Time-of-day bucketing --------------------------------------------------- + +def _epoch(y, mo, d, h=0, m=0): + from datetime import datetime, timezone + return int(datetime(y, mo, d, h, m, tzinfo=timezone.utc).timestamp()) + + +def test_bucket_utc_midnight_is_night(): + counts = sm._bucket_time_of_day([_epoch(2026, 4, 15, 0, 0)], offset_hours=0) + assert counts["night"] == 1 + assert counts["total"] == 1 + + +def test_bucket_offset_shifts_hour(): + # 22:00 UTC on a given day = 08:00 next day in Brisbane (UTC+10) + ts = [_epoch(2026, 4, 15, 22, 0)] + assert sm._bucket_time_of_day(ts, offset_hours=0)["evening"] == 1 + assert sm._bucket_time_of_day(ts, offset_hours=10)["morning"] == 1 + + +# --- Hour-of-day (24-bucket) ------------------------------------------------- + +def test_hour_of_day_length_and_total(): + ts = [_epoch(2026, 4, 15, 9, 0), _epoch(2026, 4, 15, 9, 30), + _epoch(2026, 4, 15, 22, 0)] + hod = sm._build_hour_of_day(ts, offset_hours=0) + assert len(hod["hours"]) == 24 + assert hod["total"] == 3 + assert hod["hours"][9] == 2 + assert hod["hours"][22] == 1 + + +def test_hour_of_day_offset_shifts_bucket(): + ts = [_epoch(2026, 4, 15, 22, 0)] # 22:00 UTC + hod_utc = sm._build_hour_of_day(ts, offset_hours=0) + hod_bne = sm._build_hour_of_day(ts, offset_hours=10) # 08:00 Brisbane next day + assert hod_utc["hours"][22] == 1 + assert hod_bne["hours"][8] == 1 + + +def test_hour_of_day_empty(): + hod = sm._build_hour_of_day([]) + assert hod["hours"] == [0] * 24 + assert hod["total"] == 0 + + +# --- Weekday x hour matrix -------------------------------------------------- + +def test_weekday_hour_matrix_shape(): + wh = sm._build_weekday_hour_matrix([_epoch(2026, 4, 15, 9, 0)]) + assert len(wh["matrix"]) == 7 + assert all(len(row) == 24 for row in wh["matrix"]) + assert wh["total"] == 1 + + +def test_weekday_hour_matrix_mon_is_row_zero(): + # 2026-04-13 is a Monday (verify via Python's weekday()) + from datetime import datetime, timezone + d = datetime(2026, 4, 13, 9, 0, tzinfo=timezone.utc) + assert d.weekday() == 0 + wh = sm._build_weekday_hour_matrix([int(d.timestamp())]) + assert wh["matrix"][0][9] == 1 + assert wh["row_totals"][0] == 1 + assert wh["col_totals"][9] == 1 + + +def test_weekday_hour_matrix_offset_crosses_day_boundary(): + # 2026-04-15 22:00 UTC -> 2026-04-16 08:00 Brisbane (weekday shifts Wed->Thu) + from datetime import datetime, timezone + e = _epoch(2026, 4, 15, 22, 0) + utc_wd = datetime(2026, 4, 15, 22, 0, tzinfo=timezone.utc).weekday() + bne_wd = datetime(2026, 4, 16, 8, 0, tzinfo=timezone.utc).weekday() + wh_utc = sm._build_weekday_hour_matrix([e], offset_hours=0) + wh_bne = sm._build_weekday_hour_matrix([e], offset_hours=10) + assert wh_utc["matrix"][utc_wd][22] == 1 + assert wh_bne["matrix"][bne_wd][8] == 1 + + +def test_fixture_hour_of_day_from_real_prompts(): + r = _build_fixture_report() + hod = r["time_of_day"]["hour_of_day"] + # u2 at 22:31 UTC + u6 at 03:45 UTC = one each at h=22 and h=3 + assert hod["hours"][22] == 1 + assert hod["hours"][3] == 1 + assert hod["total"] == 2 + + +# --- 5-hour session blocks --------------------------------------------------- + +def test_session_blocks_fixture_splits_on_5h_gap(): + """Fixture has events at 22:31 (Apr 15) and 03:45 (Apr 16) — ~5h 14m gap. + + The 5h window from 22:31 ends at 03:31 the next day, so 03:45 must + anchor a second block. + """ + r = _build_fixture_report() + blocks = r["session_blocks"] + assert len(blocks) == 2 + # First block anchors at u2 (22:31 UTC) — the earliest event + assert blocks[0]["anchor_iso"].startswith("2026-04-15T22:31:") + # Second block anchors at u6 (03:45 UTC next day) + assert blocks[1]["anchor_iso"].startswith("2026-04-16T03:45:") + + +def test_session_blocks_counts(): + r = _build_fixture_report() + blocks = r["session_blocks"] + # Block 0: u2 (user) + 3 assistant turns (a1_dedup, a2, a3) = 1 user, 3 turns + # Note: a1 appears twice in the JSONL under same msg_id "msg_A" but + # assistant timestamps aren't deduped in block building — both are events. + # What matters: user_msg_count is from filtered prompts. + assert blocks[0]["user_msg_count"] == 1 + # Block 1: u6 + a4 = 1 user, 1 turn + assert blocks[1]["user_msg_count"] == 1 + + +def test_session_blocks_cost_sums_match_report_total(): + r = _build_fixture_report() + # The sum of block costs should NOT equal totals["cost"] because blocks + # include every raw turn (duplicates included), while totals dedups on + # message.id. Verify blocks include at least one duplicate (block cost + # > per-turn-dedup total would indicate duplicates counted). The point + # of this test: blocks are computed from raw events and expose the + # rate-limit picture correctly, not the deduped picture. + blocks = r["session_blocks"] + assert len(blocks) >= 1 + total_block_cost = sum(b["cost_usd"] for b in blocks) + # At least the full deduped total is present in the blocks. + assert total_block_cost >= r["totals"]["cost"] - 1e-6 + + +def test_parse_peak_hours_valid(): + assert sm._parse_peak_hours("5-11") == (5, 11) + assert sm._parse_peak_hours("0-24") == (0, 24) + assert sm._parse_peak_hours(" 9 - 17 ") == (9, 17) + + +def test_parse_peak_hours_rejects_wrap_or_invalid(): + import argparse + for bad in ["5", "11-5", "24-25", "-1-5", "abc", ""]: + with pytest.raises(argparse.ArgumentTypeError): + sm._parse_peak_hours(bad) + + +def test_build_peak_none_when_no_hours(): + assert sm._build_peak(None, None) is None + + +def test_build_peak_defaults_to_los_angeles(): + p = sm._build_peak((5, 11), None) + assert p is not None + assert p["start"] == 5 + assert p["end"] == 11 + assert p["tz_label"] == "America/Los_Angeles" + # LA is either UTC-8 (PST) or UTC-7 (PDT); either is acceptable. + assert p["tz_offset_hours"] in (-7.0, -8.0) + assert "community" in p["note"].lower() + + +def test_weekly_rollup_has_data_flag(): + r = _build_fixture_report() + # Fixture has 4 turns; fixture dates are in 2026-04, so whether the + # trailing/prior windows catch them depends on "now". We only assert + # structure here: the keys and shapes are stable. + ro = r["weekly_rollup"] + assert "trailing_7d" in ro and "prior_7d" in ro + for w in (ro["trailing_7d"], ro["prior_7d"]): + assert set(w.keys()) >= {"turns", "user_prompts", "cost", "blocks", + "input", "output", "cache_read", "cache_write", + "cache_hit_pct"} + + +def test_weekly_rollup_uses_deduped_cost(): + """Trailing-7d cost (when fixture dates are in-window) should equal the + report total — confirms rollup uses the deduped turn records, not raw.""" + now = _epoch(2026, 4, 17, 0, 0) # just after both fixture events + sid, turns, user_ts = sm._load_session(_FIXTURE, include_subagents=False) + r = sm._build_report("session", "test", [(sid, turns, user_ts)]) + ro = sm._build_weekly_rollup( + r["sessions"], [(sid, turns, user_ts)], r["session_blocks"], + now_epoch=now, + ) + assert ro["trailing_7d"]["cost"] == pytest.approx(0.01748, abs=1e-7) + assert ro["prior_7d"]["cost"] == pytest.approx(0.0, abs=1e-9) + + +def test_fmt_delta_pct_prior_zero_returns_new(): + d, _ = sm._fmt_delta_pct(5, 0) + assert d == "new" + d, _ = sm._fmt_delta_pct(0, 0) + assert d in ("new", "\u2013") + + +def test_fmt_delta_pct_positive_and_negative(): + d, _ = sm._fmt_delta_pct(120, 100) + assert d == "+20.0%" + d, _ = sm._fmt_delta_pct(80, 100) + assert d == "-20.0%" + + +def test_session_duration_stats_requires_two_turns(): + assert sm._session_duration_stats({"turns": []}) is None + one_turn = {"turns": [{"timestamp": "2026-04-15T22:31:00Z"}], + "subtotal": {"total": 100, "cost": 0.1, "turns": 1}} + assert sm._session_duration_stats(one_turn) is None + + +def test_cached_parse_matches_uncached(tmp_path, monkeypatch): + """The cache round-trip must produce exactly the same entries as direct parse.""" + # Redirect the cache dir so we don't pollute ~/.cache. + monkeypatch.setattr(sm, "_parse_cache_dir", lambda: tmp_path / "parse") + direct = sm._parse_jsonl(_FIXTURE) + cached = sm._cached_parse_jsonl(_FIXTURE, use_cache=True) + assert direct == cached + # Second call should hit the cache — still equal. + cached2 = sm._cached_parse_jsonl(_FIXTURE, use_cache=True) + assert direct == cached2 + + +def test_cached_parse_writes_blob(tmp_path, monkeypatch): + monkeypatch.setattr(sm, "_parse_cache_dir", lambda: tmp_path / "parse") + sm._cached_parse_jsonl(_FIXTURE, use_cache=True) + blobs = list((tmp_path / "parse").glob("*.json.gz")) + assert len(blobs) == 1 + + +def test_cached_parse_no_cache_skips_disk(tmp_path, monkeypatch): + monkeypatch.setattr(sm, "_parse_cache_dir", lambda: tmp_path / "parse") + sm._cached_parse_jsonl(_FIXTURE, use_cache=False) + # Cache dir should not even exist (no writes). + assert not (tmp_path / "parse").exists() + + +def test_cached_parse_invalidates_on_mtime(tmp_path, monkeypatch): + """A touched JSONL must generate a fresh cache key, not a stale one.""" + monkeypatch.setattr(sm, "_parse_cache_dir", lambda: tmp_path / "parse") + # Copy fixture to a writable temp file so we can bump its mtime. + src = tmp_path / "mini.jsonl" + src.write_text(_FIXTURE.read_text(encoding="utf-8")) + sm._cached_parse_jsonl(src, use_cache=True) + before = {p.name for p in (tmp_path / "parse").iterdir()} + # Bump mtime by 2 seconds to force a distinct key. + import os + stat = src.stat() + os.utime(src, (stat.st_atime, stat.st_mtime + 2)) + sm._cached_parse_jsonl(src, use_cache=True) + after = {p.name for p in (tmp_path / "parse").iterdir()} + # Two distinct cache files now. + assert len(after) == 2 + assert before.issubset(after) + + +def test_render_html_single_page_has_everything(): + r = _build_fixture_report() + html = sm.render_html(r, variant="single") + assert 'id="session-blocks"' in html + assert 'id="hod-chart"' in html + assert 'id="chart-container' in html # chart lives on the same page + + +def test_render_html_dashboard_omits_chart_and_highcharts(): + r = _build_fixture_report() + html = sm.render_html(r, variant="dashboard", nav_sibling="detail.html") + assert 'id="session-blocks"' in html + assert 'id="hod-chart"' in html + assert 'id="chart-container' not in html + assert "Highcharts" not in html + assert 'href="detail.html"' in html + + +def test_render_html_detail_omits_insights(): + r = _build_fixture_report() + html = sm.render_html(r, variant="detail", nav_sibling="dashboard.html") + assert 'id="chart-container' in html + assert "Highcharts" in html + assert 'id="session-blocks"' not in html + assert 'class="cards"' not in html + assert 'href="dashboard.html"' in html + + +def test_session_duration_stats_computes_burn_rate(): + session = { + "turns": [ + {"timestamp": "2026-04-15T22:00:00Z"}, + {"timestamp": "2026-04-15T22:10:00Z"}, + ], + "subtotal": {"total": 100_000, "cost": 5.00, "turns": 2}, + } + st = sm._session_duration_stats(session) + assert st is not None + assert st["wall_sec"] == 600 + assert st["wall_min"] == pytest.approx(10.0) + assert st["tokens_per_min"] == pytest.approx(10_000) + assert st["cost_per_min"] == pytest.approx(0.5) + + +def test_weekly_block_counts_trailing_windows(): + # Build a small block list at fixed epoch times, then count with a + # fixed "now" so the test is deterministic regardless of when run. + now = _epoch(2026, 4, 20, 0, 0) + blocks = [ + {"last_epoch": now - 2 * 86400}, # 2 days ago — in 7d + {"last_epoch": now - 10 * 86400}, # 10 days ago — in 14d, not 7d + {"last_epoch": now - 45 * 86400}, # 45 days ago — in total only + ] + s = sm._weekly_block_counts(blocks, now_epoch=now) + assert s["trailing_7"] == 1 + assert s["trailing_14"] == 2 + assert s["trailing_30"] == 2 + assert s["total"] == 3 + + +# --- Chart library dispatch / vendoring -------------------------------------- + +def test_chart_renderers_registry_has_all_four_renderers(): + for key in ("highcharts", "uplot", "chartjs", "none"): + assert key in sm.CHART_RENDERERS, f"{key} missing from CHART_RENDERERS" + assert callable(sm.CHART_RENDERERS[key]), f"{key} not callable" + + +def test_render_chart_none_empty_payload(): + body, head = sm._render_chart_none([]) + assert body == "" + assert head == "" + + +def test_render_chart_highcharts_empty_turns_is_empty(): + # No turns -> no chart and no JS (the dashboard-only variant relies on + # this so it can skip inlining the entire vendored bundle). + body, head = sm._render_chart_highcharts([]) + assert body == "" + assert head == "" + + +def test_vendor_manifest_loads_with_expected_schema(): + m = sm._load_chart_manifest() + libs = m.get("libraries", {}) + assert "highcharts" in libs + hc = libs["highcharts"] + assert hc["license"].startswith("non-commercial") + assert len(hc["files"]) >= 4 + for f in hc["files"]: + assert {"name", "path", "sha256"} <= f.keys() + assert len(f["sha256"]) == 64 + + +def test_read_vendor_js_returns_real_payload_and_hash_matches(): + # Sanity check: the bundled Highcharts files exist and their SHA-256 + # matches what the manifest claims. The function returns a non-empty + # JS blob when verification passes. + payload = sm._read_vendor_js("highcharts") + assert len(payload) > 100_000 # ~360 KB when all 4 files verify + + +def test_read_vendor_js_unknown_library_returns_empty(capsys): + payload = sm._read_vendor_js("not-a-library") + assert payload == "" + err = capsys.readouterr().err + assert "not in vendor manifest" in err + + +def _mini_report(): + turns = sm._extract_turns(sm._parse_jsonl(_FIXTURE)) + user_ts = sm._extract_user_timestamps(sm._parse_jsonl(_FIXTURE)) + return sm._build_report( + "session", "test-slug", [("mini", turns, user_ts)], + tz_offset_hours=0.0, tz_label="UTC", + ) + + +def test_render_html_chart_lib_none_omits_highcharts_bundle(): + html = sm.render_html(_mini_report(), variant="single", chart_lib="none") + assert "Highcharts.chart" not in html + assert 'id="chart-container"' not in html + + +def test_render_html_chart_lib_highcharts_inlines_bundle(): + html = sm.render_html(_mini_report(), variant="single", chart_lib="highcharts") + # Inlined library + chart container both present; no CDN reference. + assert "Highcharts.chart" in html + assert 'id="chart-container"' in html + assert "cdn.jsdelivr.net" not in html + + +def test_maybe_warn_chart_license_silent_for_none(capsys): + sm._maybe_warn_chart_license("none", ["html"]) + err = capsys.readouterr().err + assert "license" not in err.lower() + + +def test_maybe_warn_chart_license_warns_for_highcharts(capsys): + sm._maybe_warn_chart_license("highcharts", ["html"]) + err = capsys.readouterr().err + assert "non-commercial" in err + + +def test_maybe_warn_chart_license_silent_when_html_not_exported(capsys): + sm._maybe_warn_chart_license("highcharts", ["text", "json"]) + err = capsys.readouterr().err + assert err == "" + + +# --- uPlot + Chart.js renderers ---------------------------------------------- + +def test_render_chart_uplot_empty_turns_is_empty(): + body, head = sm._render_chart_uplot([]) + assert body == "" + assert head == "" + + +def test_render_chart_chartjs_empty_turns_is_empty(): + body, head = sm._render_chart_chartjs([]) + assert body == "" + assert head == "" + + +def test_vendor_manifest_loads_uplot_and_chartjs(): + libs = sm._load_chart_manifest().get("libraries", {}) + for name in ("uplot", "chartjs"): + assert name in libs, f"{name} missing from manifest" + assert libs[name]["license"] == "MIT" + for f in libs[name]["files"]: + assert {"name", "path", "sha256"} <= f.keys() + assert len(f["sha256"]) == 64 + + +def test_read_vendor_js_returns_real_payload_uplot(): + payload = sm._read_vendor_js("uplot") + assert len(payload) > 30_000 # ~50 KB minified IIFE bundle + assert "uPlot" in payload # global namespace marker + + +def test_read_vendor_css_returns_real_payload_uplot(): + css = sm._read_vendor_css("uplot") + assert len(css) > 500 # ~1.8 KB stylesheet + assert ".uplot" in css # uPlot's own class prefix + + +def test_read_vendor_css_chartjs_is_empty(): + # Chart.js ships no CSS — confirm the helper handles that cleanly. + assert sm._read_vendor_css("chartjs") == "" + + +def test_read_vendor_js_returns_real_payload_chartjs(): + payload = sm._read_vendor_js("chartjs") + assert len(payload) > 100_000 # ~204 KB UMD bundle + assert "Chart" in payload + + +def _real_turns(): + """Real enriched turns from the fixture (with ``timestamp_fmt`` and + other report-level keys the chart renderers rely on).""" + rep = _mini_report() + return [t for s in rep["sessions"] for t in s["turns"]] + + +def test_render_chart_uplot_emits_canvas_and_data(): + turns = _real_turns() + assert turns, "fixture must have at least one turn" + body, head = sm._render_chart_uplot(turns) + assert 'id="chart-container"' in body + assert 'class="chart-lazy"' in body + assert "new uPlot(" in body # init call + assert " diff --git a/.claude/skills/session-metrics/tests/fixtures/mini.jsonl b/.claude/skills/session-metrics/tests/fixtures/mini.jsonl index 1bb7c9b..deb2cbe 100644 --- a/.claude/skills/session-metrics/tests/fixtures/mini.jsonl +++ b/.claude/skills/session-metrics/tests/fixtures/mini.jsonl @@ -10,3 +10,7 @@ {"type":"user","uuid":"u6","timestamp":"2026-04-16T03:45:00.000Z","sessionId":"s1","message":{"role":"user","content":"second prompt as plain string"}} {"type":"user","uuid":"u7","timestamp":"2026-04-16T03:45:05.000Z","sessionId":"s1","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"t3","content":"ok"}]}} {"type":"assistant","uuid":"a4","timestamp":"2026-04-16T03:45:10.000Z","sessionId":"s1","message":{"id":"msg_D","model":"claude-sonnet-4-7","role":"assistant","usage":{"input_tokens":200,"output_tokens":300,"cache_read_input_tokens":1500,"cache_creation_input_tokens":0}}} +{"type":"user","uuid":"u8","timestamp":"2026-04-16T03:46:00.000Z","sessionId":"s1","message":{"role":"user","content":[{"type":"text","text":"prompt before pure-1h turn"}]}} +{"type":"assistant","uuid":"a5","timestamp":"2026-04-16T03:46:05.000Z","sessionId":"s1","message":{"id":"msg_E","model":"claude-opus-4-7","role":"assistant","usage":{"input_tokens":10,"output_tokens":20,"cache_read_input_tokens":0,"cache_creation_input_tokens":500,"cache_creation":{"ephemeral_1h_input_tokens":500,"ephemeral_5m_input_tokens":0}}}} +{"type":"user","uuid":"u9","timestamp":"2026-04-16T03:46:10.000Z","sessionId":"s1","message":{"role":"user","content":[{"type":"text","text":"prompt before mix turn"}]}} +{"type":"assistant","uuid":"a6","timestamp":"2026-04-16T03:46:15.000Z","sessionId":"s1","message":{"id":"msg_F","model":"claude-sonnet-4-7","role":"assistant","usage":{"input_tokens":5,"output_tokens":10,"cache_read_input_tokens":0,"cache_creation_input_tokens":1000,"cache_creation":{"ephemeral_1h_input_tokens":400,"ephemeral_5m_input_tokens":600}}}} diff --git a/.claude/skills/session-metrics/tests/test_session_metrics.py b/.claude/skills/session-metrics/tests/test_session_metrics.py index 030ce05..affe555 100644 --- a/.claude/skills/session-metrics/tests/test_session_metrics.py +++ b/.claude/skills/session-metrics/tests/test_session_metrics.py @@ -33,11 +33,14 @@ def test_pricing_opus_4_7_explicit(): assert r["output"] == 25.00 assert r["cache_read"] == 0.50 assert r["cache_write"] == 6.25 + # 1-hour TTL tier is 2x base input (vs 1.25x for 5m). + assert r["cache_write_1h"] == 10.00 def test_pricing_sonnet_4_7_explicit(): r = sm._pricing_for("claude-sonnet-4-7") assert r["input"] == 3.00 + assert r["cache_write_1h"] == 6.00 def test_pricing_opus_4_old_tier_retained(): @@ -45,6 +48,7 @@ def test_pricing_opus_4_old_tier_retained(): r = sm._pricing_for("claude-opus-4") assert r["input"] == 15.00 assert r["output"] == 75.00 + assert r["cache_write_1h"] == 30.00 def test_pricing_haiku_4_5_new_tier(): @@ -52,6 +56,7 @@ def test_pricing_haiku_4_5_new_tier(): r = sm._pricing_for("claude-haiku-4-5-20251001") assert r["input"] == 1.00 assert r["output"] == 5.00 + assert r["cache_write_1h"] == 2.00 def test_pricing_prefix_fallback(): @@ -73,9 +78,50 @@ def test_cost_opus_all_buckets(): } # Opus 4.7 new tier: 120*5 + 80*25 + 500*0.5 + 1000*6.25 # = 600 + 2000 + 250 + 6250 = 9100 per M + # Legacy fallback path: no nested cache_creation, so the full 1000 tokens + # price at the 5m rate (6.25/M). assert sm._cost(usage, "claude-opus-4-7") == pytest.approx(0.00910, abs=1e-7) +def test_cost_splits_5m_and_1h_when_nested_present(): + """Nested ``cache_creation`` object triggers the split pricing path.""" + usage = { + "input_tokens": 0, "output_tokens": 0, + "cache_read_input_tokens": 0, + "cache_creation_input_tokens": 1000, # Sum — not used when nested present + "cache_creation": { + "ephemeral_5m_input_tokens": 600, + "ephemeral_1h_input_tokens": 400, + }, + } + # Sonnet 4.7: 5m = 3.75, 1h = 6.00 + # 600*3.75 + 400*6.00 = 2250 + 2400 = 4650 per M = 0.00465 + assert sm._cost(usage, "claude-sonnet-4-7") == pytest.approx(0.00465, abs=1e-7) + + +def test_cache_write_split_fallback_without_nested(): + """Legacy transcripts (no nested cache_creation) charge everything at 5m.""" + usage = { + "cache_creation_input_tokens": 1000, + } + tokens_5m, tokens_1h = sm._cache_write_split(usage) + assert tokens_5m == 1000 + assert tokens_1h == 0 + + +def test_cache_write_split_reads_nested_when_present(): + usage = { + "cache_creation_input_tokens": 1000, + "cache_creation": { + "ephemeral_5m_input_tokens": 200, + "ephemeral_1h_input_tokens": 800, + }, + } + tokens_5m, tokens_1h = sm._cache_write_split(usage) + assert tokens_5m == 200 + assert tokens_1h == 800 + + def test_no_cache_cost_folds_cache_tokens(): usage = { "input_tokens": 10, "output_tokens": 5, @@ -122,7 +168,8 @@ def test_is_user_prompt_excludes_assistant_type(): def test_fixture_dedup_keeps_last_write(): entries = sm._parse_jsonl(_FIXTURE) turns = sm._extract_turns(entries) - assert len(turns) == 4 + # msg_A..D (legacy flat cache writes) + msg_E (pure 1h) + msg_F (mix) = 6 + assert len(turns) == 6 by_id = {t["message"]["id"]: t["message"]["usage"] for t in turns} # msg_A appears twice; the last write (120/80/500/1000) must win assert by_id["msg_A"]["input_tokens"] == 120 @@ -132,16 +179,16 @@ def test_fixture_dedup_keeps_last_write(): def test_fixture_user_timestamps_default_excludes_sidechain_and_tool_results(): entries = sm._parse_jsonl(_FIXTURE) ts = sm._extract_user_timestamps(entries) - # u2 (text list) + u6 (plain string) = 2. u1 meta, u3/u4/u7 tool_result, + # u2, u6, u8, u9 are text prompts. u1 meta, u3/u4/u7 tool_result, # u5 sidechain — all excluded. - assert len(ts) == 2 + assert len(ts) == 4 def test_fixture_user_timestamps_include_sidechain_adds_one(): entries = sm._parse_jsonl(_FIXTURE) ts = sm._extract_user_timestamps(entries, include_sidechain=True) # adds u5 sidechain text - assert len(ts) == 3 + assert len(ts) == 5 # --- End-to-end totals on the fixture --------------------------------------- @@ -153,26 +200,134 @@ def _build_fixture_report(): def test_fixture_total_cost_exact(): r = _build_fixture_report() - # New Opus 4.7 tier ($5/$25/$0.50/$6.25), Sonnet 4.7 unchanged ($3/$15/$0.30/$3.75). - # msg_A (opus, deduped, last write wins): 120*5 + 80*25 + 500*0.5 + 1000*6.25 = 9100/M = 0.00910 - # msg_B (sonnet): 10*3 + 20*15 + 2000*0.3 + 0*3.75 = 930/M = 0.00093 - # msg_C (opus): 5*5 + 15*25 + 3000*0.5 + 0*6.25 = 1900/M = 0.00190 - # msg_D (sonnet): 200*3 + 300*15 + 1500*0.3 + 0*3.75 = 5550/M = 0.00555 - # Total = 0.01748 - assert r["totals"]["cost"] == pytest.approx(0.01748, abs=1e-7) + # Opus 4.7 ($5/$25/$0.50/$6.25/$10.00), Sonnet 4.7 ($3/$15/$0.30/$3.75/$6.00). + # msg_A (opus, deduped, legacy flat cwr): 120*5 + 80*25 + 500*0.5 + 1000*6.25 = 0.00910 + # msg_B (sonnet): 10*3 + 20*15 + 2000*0.3 + 0 = 0.00093 + # msg_C (opus): 5*5 + 15*25 + 3000*0.5 + 0 = 0.00190 + # msg_D (sonnet): 200*3 + 300*15 + 1500*0.3 + 0 = 0.00555 + # msg_E (opus, pure 1h): 10*5 + 20*25 + 0 + 500*10.00 = 0.00555 + # msg_F (sonnet, mix 5m=600 + 1h=400): 5*3 + 10*15 + 0 + 600*3.75 + 400*6.00 = 0.004815 + # Total = 0.027845 + assert r["totals"]["cost"] == pytest.approx(0.027845, abs=1e-7) def test_fixture_turns_count_and_models(): r = _build_fixture_report() - assert r["totals"]["turns"] == 4 - assert r["models"]["claude-opus-4-7"] == 2 - assert r["models"]["claude-sonnet-4-7"] == 2 + assert r["totals"]["turns"] == 6 + assert r["models"]["claude-opus-4-7"] == 3 # msg_A, msg_C, msg_E + assert r["models"]["claude-sonnet-4-7"] == 3 # msg_B, msg_D, msg_F def test_fixture_time_of_day_total_is_user_prompt_count(): r = _build_fixture_report() - # 2 real user prompts — must NOT equal the 7 user-type entries in the file - assert r["time_of_day"]["message_count"] == 2 + # 4 real user prompts — must NOT equal the user-type entry count in the file + assert r["time_of_day"]["message_count"] == 4 + + +# --- Cache TTL drilldown (Proposal A) --------------------------------------- + +def test_fixture_ttl_classification_per_turn(): + """Each turn carries a correct `cache_write_ttl` derived from its split.""" + r = _build_fixture_report() + by_id = {t["model"] + "_" + str(t["index"]): t for t in r["sessions"][0]["turns"]} + # Index 1 = msg_A (legacy flat → classified as 5m via fallback) + assert r["sessions"][0]["turns"][0]["cache_write_ttl"] == "5m" + # Index 5 = msg_E (pure 1h) + msg_E = r["sessions"][0]["turns"][4] + assert msg_E["cache_write_ttl"] == "1h" + assert msg_E["cache_write_5m_tokens"] == 0 + assert msg_E["cache_write_1h_tokens"] == 500 + # Index 6 = msg_F (mix) + msg_F = r["sessions"][0]["turns"][5] + assert msg_F["cache_write_ttl"] == "mix" + assert msg_F["cache_write_5m_tokens"] == 600 + assert msg_F["cache_write_1h_tokens"] == 400 + + +def test_fixture_totals_ttl_aggregation(): + r = _build_fixture_report() + t = r["totals"] + # 5m buckets: msg_A 1000 (flat fallback) + msg_F 600 = 1600 + assert t["cache_write_5m"] == 1600 + # 1h buckets: msg_E 500 + msg_F 400 = 900 + assert t["cache_write_1h"] == 900 + # Extra cost paid for the 1h tier (delta vs. 5m rate): + # msg_E: 500 * (10.00 - 6.25)/M = 0.001875 (opus) + # msg_F: 400 * (6.00 - 3.75)/M = 0.000900 (sonnet) + # Total = 0.002775 + assert t["extra_1h_cost"] == pytest.approx(0.002775, abs=1e-7) + + +def test_has_1h_cache_detects_fixture(): + r = _build_fixture_report() + assert sm._has_1h_cache(r) is True + + +def test_has_1h_cache_false_on_legacy_only(): + """A report built from only legacy flat-cache turns reports False.""" + legacy_entries = sm._parse_jsonl(_FIXTURE) + # Strip msg_E, msg_F and their paired users from the raw entries + keep = [e for e in legacy_entries + if e.get("uuid") not in {"u8", "a5", "u9", "a6"}] + # Extract turns from the trimmed set and build a synthetic report + trimmed_turns = sm._extract_turns(keep) + user_ts = sm._extract_user_timestamps(keep) + r = sm._build_report("session", "test-slug", [("s1", trimmed_turns, user_ts)]) + assert sm._has_1h_cache(r) is False + + +def test_csv_has_ttl_columns(): + r = _build_fixture_report() + csv_out = sm.render_csv(r) + header = csv_out.splitlines()[0] + assert "cache_write_5m_tokens" in header + assert "cache_write_1h_tokens" in header + assert "cache_write_ttl" in header + + +def test_json_has_ttl_totals_keys(): + r = _build_fixture_report() + import json as _json + data = _json.loads(sm.render_json(r)) + assert "cache_write_5m" in data["totals"] + assert "cache_write_1h" in data["totals"] + assert "extra_1h_cost" in data["totals"] + # Per-turn nested fields + t = data["sessions"][0]["turns"][-1] # msg_F + assert t["cache_write_ttl"] == "mix" + assert t["cache_write_5m_tokens"] == 600 + assert t["cache_write_1h_tokens"] == 400 + + +def test_text_render_includes_legend_and_1h_annotation(): + r = _build_fixture_report() + text = sm.render_text(r) + # Legend header block present + assert "Columns:" in text + assert "CacheRd" in text + # 1h-tier annotation surfaces the `*` suffix and footer explanation + assert "*" in text + assert "Extra cost paid for 1h cache tier" in text + + +def test_md_render_includes_legend_and_annotation(): + r = _build_fixture_report() + md = sm.render_md(r) + assert "## Column legend" in md + assert "1-hour TTL tier" in md + # Summary card line for the extra 1h cost + assert "Extra cost paid for 1h cache tier" in md + + +def test_html_render_includes_legend_and_badge(): + r = _build_fixture_report() + html = sm.render_html(r, variant="single") + assert 'class="legend-block"' in html + # TTL badge renders on the 1h and mix rows + assert 'class="badge-ttl ttl-1h"' in html + assert 'class="badge-ttl ttl-mix"' in html + # Cache TTL mix dashboard card + assert "Cache TTL mix" in html # --- Input validation -------------------------------------------------------- @@ -283,10 +438,10 @@ def test_weekday_hour_matrix_offset_crosses_day_boundary(): def test_fixture_hour_of_day_from_real_prompts(): r = _build_fixture_report() hod = r["time_of_day"]["hour_of_day"] - # u2 at 22:31 UTC + u6 at 03:45 UTC = one each at h=22 and h=3 + # u2 at 22:31 UTC + u6/u8/u9 at 03:45/03:46 UTC = 1 at h=22, 3 at h=3 assert hod["hours"][22] == 1 - assert hod["hours"][3] == 1 - assert hod["total"] == 2 + assert hod["hours"][3] == 3 + assert hod["total"] == 4 # --- 5-hour session blocks --------------------------------------------------- @@ -314,8 +469,8 @@ def test_session_blocks_counts(): # assistant timestamps aren't deduped in block building — both are events. # What matters: user_msg_count is from filtered prompts. assert blocks[0]["user_msg_count"] == 1 - # Block 1: u6 + a4 = 1 user, 1 turn - assert blocks[1]["user_msg_count"] == 1 + # Block 1: u6 + a4 + u8 + a5 + u9 + a6 = 3 user prompts, 3 turns + assert blocks[1]["user_msg_count"] == 3 def test_session_blocks_cost_sums_match_report_total(): @@ -384,7 +539,7 @@ def test_weekly_rollup_uses_deduped_cost(): r["sessions"], [(sid, turns, user_ts)], r["session_blocks"], now_epoch=now, ) - assert ro["trailing_7d"]["cost"] == pytest.approx(0.01748, abs=1e-7) + assert ro["trailing_7d"]["cost"] == pytest.approx(0.027845, abs=1e-7) assert ro["prior_7d"]["cost"] == pytest.approx(0.0, abs=1e-9) From 0eb57be85b0384612afa936fe4f69276ae05d7c4 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sat, 18 Apr 2026 15:35:16 +1000 Subject: [PATCH 111/174] session-metrics: sync to dev v1.3.0 (Proposal B + streaming-dedup fix) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Proposal B — per-turn content-block distribution: - New Content column across text / MD / HTML (letter-encoded T thinking / u tool_use / x text / r tool_result / i image, zero counts omitted). - HTML dashboard gains Extended thinking engagement + Tool calls cards (conditional on non-zero counts). - CSV gains 5 new trailing columns; JSON exposes nested content_blocks + tool_use_names per turn and aggregate thinking_turn_count / pct, tool_call_total / avg, tool_names_top3 in totals. Streaming-dedup fix (critical): - Claude Code writes one assistant message as N JSONL entries sharing msg_id, each carrying ONE distinct content block. The previous last-occurrence dedup silently dropped earlier thinking, text, and tool_use blocks. Fix: _extract_turns now unions content blocks across every occurrence. Cost math unaffected (usage dict is identical across occurrences). - On a representative 287-turn session: thinking_turn_count went from 0 to 125 (42.8%), tool_use from 261 to 295, text from 9 to 76. Total cost unchanged. 103 tests pass (up from 89 in v1.2.0). --- .claude/skills/session-metrics/SKILL.md | 27 +- .../references/jsonl-schema.md | 5 + .../scripts/session-metrics.py | 408 ++++++++++++++++-- .../session-metrics/tests/fixtures/mini.jsonl | 17 +- .../tests/test_session_metrics.py | 221 ++++++++++ 5 files changed, 617 insertions(+), 61 deletions(-) diff --git a/.claude/skills/session-metrics/SKILL.md b/.claude/skills/session-metrics/SKILL.md index f31117d..a901147 100644 --- a/.claude/skills/session-metrics/SKILL.md +++ b/.claude/skills/session-metrics/SKILL.md @@ -77,15 +77,17 @@ project root, named `session__.` (single) or ## Output columns -| Column | Meaning | -|----------|----------------------------------------------| -| `#` | Deduplicated turn index | -| `Time` | Timestamp of the turn in the user's local timezone (auto-detected from system; override with `--tz` or `--utc-offset`). The header shows the active tz label, e.g. `Time (UTC+10)` or `Time (Australia/Brisbane)`. Raw `timestamp` fields in JSON/CSV exports remain UTC ISO-8601 (`...Z`) for machine-readability. | -| `Input` | Net new input tokens (uncached portion only — cache reads/writes are shown separately) | -| `Output` | Output tokens generated (includes thinking + tool_use block tokens) | -| `CacheRd`| Tokens served from prompt cache (cheap) | -| `CacheWr`| Tokens written to prompt cache (one-time). **v1.2.0+**: a `1h` / `mix` badge (HTML) or `*` suffix (text / Markdown) marks turns that used the 1-hour TTL tier; hover or scroll to the footer for the 5m / 1h split. CSV/JSON expose `cache_write_5m_tokens` and `cache_write_1h_tokens` as dedicated columns alongside the existing `cache_write_tokens` sum. | -| `Cost $` | Estimated USD for this turn | +| Column | Meaning | +|-----------|----------------------------------------------| +| `#` | Deduplicated turn index | +| `Time` | Timestamp of the turn in the user's local timezone (auto-detected from system; override with `--tz` or `--utc-offset`). The header shows the active tz label, e.g. `Time (UTC+10)` or `Time (Australia/Brisbane)`. Raw `timestamp` fields in JSON/CSV exports remain UTC ISO-8601 (`...Z`) for machine-readability. | +| `Input` | Net new input tokens (uncached portion only — cache reads/writes are shown separately) | +| `Output` | Output tokens generated (includes thinking + tool_use block tokens) | +| `CacheRd` | Tokens served from prompt cache (cheap) | +| `CacheWr` | Tokens written to prompt cache (one-time). **v1.2.0+**: a `1h` / `mix` badge (HTML) or `*` suffix (text / Markdown) marks turns that used the 1-hour TTL tier; hover or scroll to the footer for the 5m / 1h split. CSV/JSON expose `cache_write_5m_tokens` and `cache_write_1h_tokens` as dedicated columns alongside the existing `cache_write_tokens` sum. | +| `Content` | **v1.3.0+**: per-turn content-block distribution. Letter encoding `T` thinking, `u` tool_use, `x` text, `r` tool_result, `i` image (zero counts omitted). `tool_result` and `image` counts come from the user entry that immediately preceded the turn. Column renders only when at least one turn in the report carries any content block. HTML cells include a tooltip with expanded descriptions; CSV/JSON expose `thinking_blocks`, `tool_use_blocks`, `text_blocks`, `tool_result_blocks`, `image_blocks` as dedicated per-turn columns/keys. | +| `Total` | Sum of the four billable token buckets | +| `Cost $` | Estimated USD for this turn | A short **column legend** renders near the Timeline header in every human-facing format (text, Markdown, HTML). CSV and JSON are @@ -95,7 +97,12 @@ Footer shows session totals + **cache savings** vs a hypothetical no-cache run. When any turn used the 1-hour cache TTL tier, an extra `Extra cost paid for 1h cache tier` line breaks out the premium paid for the longer reuse window, and a **Cache TTL mix** dashboard card -appears on the HTML report. +appears on the HTML report. **v1.3.0+** adds two more conditional +dashboard cards: **Extended thinking engagement** (shown when any turn +carried a `thinking` block — counts turns and blocks but cannot +recover per-block tokens, which are rolled into `output_tokens` by +Anthropic) and **Tool calls** (shown when any turn used +`tool_use` blocks — total, average per turn, and the top-3 tool names). ## Reference files diff --git a/.claude/skills/session-metrics/references/jsonl-schema.md b/.claude/skills/session-metrics/references/jsonl-schema.md index b7f1b5a..d2056af 100644 --- a/.claude/skills/session-metrics/references/jsonl-schema.md +++ b/.claude/skills/session-metrics/references/jsonl-schema.md @@ -368,6 +368,11 @@ templates. ## Proposal B — Content-block distribution +> **Status: Implemented in v1.3.0.** The prose below is preserved as +> historical design context. See `SKILL.md` for the current column/card +> specification and `scripts/session-metrics.py` for the +> implementation. + **Fields.** Per-turn counts of `message.content[].type` values: `thinking`, `tool_use`, `text` on assistant entries, and `tool_result`, `image` on the preceding user entry. diff --git a/.claude/skills/session-metrics/scripts/session-metrics.py b/.claude/skills/session-metrics/scripts/session-metrics.py index aac4105..f00a1a5 100644 --- a/.claude/skills/session-metrics/scripts/session-metrics.py +++ b/.claude/skills/session-metrics/scripts/session-metrics.py @@ -216,22 +216,108 @@ def _cached_parse_jsonl(path: Path, use_cache: bool = True) -> list[dict]: def _extract_turns(entries: list[dict]) -> list[dict]: - """Deduplicate on message.id, keep last occurrence, sort by timestamp.""" - seen: dict[str, dict] = {} + """Deduplicate on message.id and return one entry per assistant turn. + + Claude Code writes a single assistant response across **multiple JSONL + entries** that all share the same ``message.id`` and an identical + ``usage`` dict, but each carries a **different single content block** + (one thinking block, one text block, one tool_use block, etc.). This + is how Anthropic's streaming output is persisted. Dedup strategy: + + - ``usage``, ``model``, and timestamp come from the **last** occurrence + (canonical "message settled" snapshot; cost math was always correct + because ``usage`` is constant across occurrences). + - ``content`` is the **union** of content blocks across **every** + occurrence (so the turn record reflects the full thinking + text + + tool_use distribution the model actually emitted). Empirically, + each occurrence contributes exactly one distinct block and they never + overlap; if Claude Code ever starts shipping cumulative snapshots + alongside incremental ones, we'd need to dedup block-by-block here. + + Each returned entry has ``_preceding_user_content`` attached — the + ``message.content`` of the user entry immediately before this turn's + **first** occurrence in the raw stream (content-block counters use + this to attribute ``tool_result`` / ``image`` blocks to the turn that + consumed them). + """ + last_entry: dict[str, dict] = {} + merged_content: dict[str, list] = {} + preceding_user: dict[str, object] = {} + last_user_content = None for entry in entries: - if entry.get("type") != "assistant": + t = entry.get("type") + if t == "user": + msg = entry.get("message") or {} + last_user_content = msg.get("content") + continue + if t != "assistant": continue msg = entry.get("message", {}) if "usage" not in msg: continue msg_id = msg.get("id") - if msg_id: - seen[msg_id] = entry - turns = list(seen.values()) + if not msg_id: + continue + # First-occurrence wins for the preceding user pointer — streaming + # echo entries of the same msg_id don't see a new user prompt in + # between, so the triggering user entry is the one we saw before + # the first streaming chunk. + if msg_id not in preceding_user: + preceding_user[msg_id] = last_user_content + # Union content blocks across every occurrence of this msg_id. + content = msg.get("content") + if isinstance(content, list): + merged_content.setdefault(msg_id, []).extend(content) + # Last occurrence wins for usage / model / timestamp. + last_entry[msg_id] = entry + turns: list[dict] = [] + for msg_id, entry in last_entry.items(): + merged_msg = {**entry["message"], "content": merged_content.get(msg_id, [])} + turns.append({ + **entry, + "message": merged_msg, + "_preceding_user_content": preceding_user.get(msg_id), + }) turns.sort(key=lambda e: e.get("timestamp", "")) return turns +# Content-block letter codes used in the per-turn Content cell. +_CONTENT_LETTERS = ( + ("thinking", "T"), + ("tool_use", "u"), + ("text", "x"), + ("tool_result", "r"), + ("image", "i"), +) + + +def _count_content_blocks(content) -> tuple[dict[str, int], list[str]]: + """Count content blocks by type. Return (counts, tool_names). + + ``content`` is the ``message.content`` field, which is either a list of + block dicts (normal case) or a plain string (rare: old-style user prompts) + or missing entirely. Non-list content has no structured blocks, so the + returned counts are all zero. + """ + counts = {"thinking": 0, "tool_use": 0, "text": 0, + "tool_result": 0, "image": 0} + names: list[str] = [] + if not isinstance(content, list): + return counts, names + for block in content: + if not isinstance(block, dict): + continue + t = block.get("type", "") + if t in counts: + counts[t] += 1 + if t == "tool_use": + name = block.get("name") + if isinstance(name, str) and name: + names.append(name) + return counts, names + + # --------------------------------------------------------------------------- # Time-of-day analysis # --------------------------------------------------------------------------- @@ -826,6 +912,18 @@ def _build_turn_record(global_index: int, entry: dict, ttl = "mix" c = _cost(u, model) nc = _no_cache_cost(u, model) + # Content-block distribution: assistant blocks come from this turn's own + # message.content; tool_result / image blocks are attributed from the user + # entry that immediately preceded this turn in the raw JSONL stream. + assist_counts, tool_names = _count_content_blocks(msg.get("content")) + user_counts, _ = _count_content_blocks(entry.get("_preceding_user_content")) + content_blocks = { + "thinking": assist_counts["thinking"], + "tool_use": assist_counts["tool_use"], + "text": assist_counts["text"], + "tool_result": user_counts["tool_result"], + "image": user_counts["image"], + } return { "index": global_index, "timestamp": entry.get("timestamp", ""), @@ -842,6 +940,8 @@ def _build_turn_record(global_index: int, entry: dict, "cost_usd": c, "no_cache_cost_usd": nc, "speed": u.get("speed", ""), + "content_blocks": content_blocks, + "tool_use_names": tool_names, } @@ -849,6 +949,10 @@ def _totals_from_turns(turn_records: list[dict]) -> dict: t = {"input": 0, "output": 0, "cache_read": 0, "cache_write": 0, "cache_write_5m": 0, "cache_write_1h": 0, "extra_1h_cost": 0.0, "cost": 0.0, "no_cache_cost": 0.0, "turns": len(turn_records)} + content_block_totals = {"thinking": 0, "tool_use": 0, "text": 0, + "tool_result": 0, "image": 0} + thinking_turn_count = 0 + name_counts: dict[str, int] = {} for r in turn_records: t["input"] += r["input_tokens"] t["output"] += r["output_tokens"] @@ -864,10 +968,30 @@ def _totals_from_turns(turn_records: list[dict]) -> dict: if tokens_1h: rates = _pricing_for(r["model"]) t["extra_1h_cost"] += tokens_1h * (rates["cache_write_1h"] - rates["cache_write"]) / 1_000_000 + cb = r.get("content_blocks") or {} + for k in content_block_totals: + content_block_totals[k] += cb.get(k, 0) + if cb.get("thinking", 0) > 0: + thinking_turn_count += 1 + for name in r.get("tool_use_names", []) or []: + name_counts[name] = name_counts.get(name, 0) + 1 + n_turns = len(turn_records) t["total"] = t["input"] + t["output"] + t["cache_read"] + t["cache_write"] t["total_input"] = t["input"] + t["cache_read"] + t["cache_write"] t["cache_savings"] = t["no_cache_cost"] - t["cost"] t["cache_hit_pct"] = 100 * t["cache_read"] / max(1, t["total_input"]) + t["content_blocks"] = content_block_totals + t["thinking_turn_count"] = thinking_turn_count + t["thinking_turn_pct"] = ( + 100 * thinking_turn_count / n_turns if n_turns else 0.0 + ) + t["tool_call_total"] = content_block_totals["tool_use"] + t["tool_call_avg_per_turn"] = ( + content_block_totals["tool_use"] / n_turns if n_turns else 0.0 + ) + # Stable ordering: count desc, then name asc so ties are deterministic. + ranked = sorted(name_counts.items(), key=lambda x: (-x[1], x[0])) + t["tool_names_top3"] = [name for name, _ in ranked[:3]] return t @@ -943,20 +1067,35 @@ def _build_report( # --------------------------------------------------------------------------- COL = "{:<4} {:<19} {:>11} {:>7} {:>9} {:>9} {:>10} {:>9}" -# Mode (speed) column — appended when any turn in the report used fast mode -COL_M = COL + " {:<4}" +# Optional suffix columns: Mode (fast mode), Content (per-turn block distribution) +_COL_MODE_SUFFIX = " {:<4}" +_COL_CONTENT_SUFFIX = " {:<15}" +COL_M = COL + _COL_MODE_SUFFIX # retained for back-compat + + +def _text_format(show_mode: bool, show_content: bool) -> str: + """Assemble the text-row format string with optional trailing columns.""" + fmt = COL + if show_mode: + fmt += _COL_MODE_SUFFIX + if show_content: + fmt += _COL_CONTENT_SUFFIX + return fmt def _text_table_headers(tz_offset_hours: float = 0.0, - show_mode: bool = False) -> tuple[str, str, str]: + show_mode: bool = False, + show_content: bool = False) -> tuple[str, str, str]: """Return (hdr, sep, wide) for the text timeline table in the given tz.""" time_col = f"Time ({_short_tz_label(tz_offset_hours)})" + fmt = _text_format(show_mode, show_content) + args = ["#", time_col, "Input (new)", "Output", + "CacheRd", "CacheWr", "Total", "Cost $"] if show_mode: - hdr = COL_M.format("#", time_col, "Input (new)", "Output", - "CacheRd", "CacheWr", "Total", "Cost $", "Mode") - else: - hdr = COL.format("#", time_col, "Input (new)", "Output", - "CacheRd", "CacheWr", "Total", "Cost $") + args.append("Mode") + if show_content: + args.append("Content") + hdr = fmt.format(*args) return hdr, "-" * len(hdr), "=" * len(hdr) @@ -978,6 +1117,63 @@ def _has_1h_cache(report: dict) -> bool: return False +def _has_thinking(report: dict) -> bool: + """Return True if any turn carried at least one thinking block.""" + for s in report["sessions"]: + for t in s["turns"]: + if (t.get("content_blocks") or {}).get("thinking", 0) > 0: + return True + return False + + +def _has_tool_use(report: dict) -> bool: + """Return True if any turn carried at least one tool_use block.""" + for s in report["sessions"]: + for t in s["turns"]: + if (t.get("content_blocks") or {}).get("tool_use", 0) > 0: + return True + return False + + +def _has_content_blocks(report: dict) -> bool: + """Return True if any turn carried any content block of any type. + + Drives conditional rendering of the Content column so legacy reports + (or empty fixtures) stay visually unchanged. + """ + for s in report["sessions"]: + for t in s["turns"]: + cb = t.get("content_blocks") or {} + if any(cb.get(k, 0) > 0 for k in cb): + return True + return False + + +def _fmt_content_cell(cb: dict) -> str: + """Format the per-turn Content cell. Zeros are omitted. + + Example: ``{thinking: 3, tool_use: 2, text: 1}`` → ``"T3 u2 x1"``. + Returns ``"-"`` when every count is zero so empty rows stay visible. + """ + if not cb: + return "-" + parts: list[str] = [] + for key, letter in _CONTENT_LETTERS: + n = cb.get(key, 0) + if n: + parts.append(f"{letter}{n}") + return " ".join(parts) if parts else "-" + + +def _fmt_content_title(cb: dict) -> str: + """Human-readable tooltip text for the per-turn Content cell.""" + if not cb: + return "" + parts = [f"{cb.get(key, 0)} {key}" + for key, _ in _CONTENT_LETTERS if cb.get(key, 0) > 0] + return ", ".join(parts) + + def _fmt_ts(ts: str, offset_hours: float = 0.0) -> str: try: dt = datetime.fromisoformat(ts.replace("Z", "+00:00")) @@ -1020,8 +1216,9 @@ def _fmt_cwr_subtotal(s: dict) -> str: return f"{n:>9,}" -def _row_text(t: dict, show_mode: bool = False) -> str: - base = COL_M if show_mode else COL +def _row_text(t: dict, show_mode: bool = False, + show_content: bool = False) -> str: + fmt = _text_format(show_mode, show_content) args = [ t["index"], t["timestamp_fmt"], f"{t['input_tokens']:>7,}", f"{t['output_tokens']:>7,}", @@ -1032,11 +1229,14 @@ def _row_text(t: dict, show_mode: bool = False) -> str: if show_mode: spd = t.get("speed", "") args.append("fast" if spd == "fast" else "std") - return base.format(*args) + if show_content: + args.append(_fmt_content_cell(t.get("content_blocks") or {})) + return fmt.format(*args) -def _subtotal_text(label: str, s: dict, show_mode: bool = False) -> str: - base = COL_M if show_mode else COL +def _subtotal_text(label: str, s: dict, show_mode: bool = False, + show_content: bool = False) -> str: + fmt = _text_format(show_mode, show_content) args = [ label, "", f"{s['input']:>7,}", f"{s['output']:>7,}", @@ -1046,10 +1246,13 @@ def _subtotal_text(label: str, s: dict, show_mode: bool = False) -> str: ] if show_mode: args.append("") - return base.format(*args) + if show_content: + args.append("") + return fmt.format(*args) -def _text_legend(tz_label: str, show_mode: bool, show_ttl: bool) -> str: +def _text_legend(tz_label: str, show_mode: bool, show_ttl: bool, + show_content: bool = False) -> str: """Build the column legend emitted above the timeline table.""" rows = [ ("#", "deduplicated turn index"), @@ -1070,6 +1273,12 @@ def _text_legend(tz_label: str, show_mode: bool, show_ttl: bool) -> str: ("Total", "sum of the four billable token buckets"), ("Cost $", "estimated USD for this turn"), ]) + if show_content: + rows.append(( + "Content", + "content blocks per turn: T thinking, u tool_use, x text, " + "r tool_result, i image (zeros omitted)", + )) w = max(len(k) for k, _ in rows) lines = ["Columns:"] + [f" {k:<{w}} {v}" for k, v in rows] return "\n".join(lines) @@ -1102,6 +1311,22 @@ def _footer_text(totals: dict, models: dict[str, int], f"Cache TTL mix (1h share of writes) : {pct_1h:.1f}% " f"[* in CacheWr column = includes 1h-tier cache write]" ) + if totals.get("thinking_turn_count", 0) > 0: + lines.append( + f"Extended thinking turns : " + f"{totals['thinking_turn_count']} of {totals.get('turns', 0)} " + f"({totals.get('thinking_turn_pct', 0.0):.1f}%, " + f"{(totals.get('content_blocks') or {}).get('thinking', 0)} blocks)" + ) + if totals.get("tool_call_total", 0) > 0: + top3 = totals.get("tool_names_top3") or [] + top3_str = ", ".join(top3) if top3 else "none" + lines.append( + f"Tool calls : " + f"{totals['tool_call_total']} total, " + f"{totals.get('tool_call_avg_per_turn', 0.0):.1f}/turn " + f"(top: {top3_str})" + ) if models: lines.append("") lines.append("Models used:") @@ -1176,11 +1401,14 @@ def p(*args, **kw): m = _has_fast(report) has_1h = _has_1h_cache(report) + has_content = _has_content_blocks(report) tz_offset = report.get("tz_offset_hours", 0.0) tz_label = report.get("tz_label", "UTC") - hdr, sep, wide = _text_table_headers(tz_offset, show_mode=m) + hdr, sep, wide = _text_table_headers(tz_offset, show_mode=m, + show_content=has_content) - p(_text_legend(tz_label, show_mode=m, show_ttl=has_1h)) + p(_text_legend(tz_label, show_mode=m, show_ttl=has_1h, + show_content=has_content)) p() if report["mode"] == "project": @@ -1193,23 +1421,23 @@ def p(*args, **kw): p(wide) p(hdr) for t in s["turns"]: - p(_row_text(t, m)) + p(_row_text(t, m, has_content)) p(sep) - p(_subtotal_text(f"S{i:02}", s["subtotal"], m)) + p(_subtotal_text(f"S{i:02}", s["subtotal"], m, has_content)) p() p(wide) p(f" PROJECT TOTAL — {len(sessions)} session{'s' if len(sessions) != 1 else ''}, {report['totals']['turns']} turns") p(wide) p(hdr) p(sep) - p(_subtotal_text("TOT", report["totals"], m)) + p(_subtotal_text("TOT", report["totals"], m, has_content)) else: s = sessions[0] p(hdr) for t in s["turns"]: - p(_row_text(t, m)) + p(_row_text(t, m, has_content)) p(sep) - p(_subtotal_text("TOT", s["subtotal"], m)) + p(_subtotal_text("TOT", s["subtotal"], m, has_content)) p(_footer_text(report["totals"], report["models"], report.get("time_of_day"), tz_label=report.get("tz_label", "UTC"), @@ -1271,9 +1499,12 @@ def render_csv(report: dict) -> str: w.writerow(["session_id", "turn", "timestamp", "model", "speed", "input_tokens", "output_tokens", "cache_read_tokens", "cache_write_tokens", "cache_write_5m_tokens", "cache_write_1h_tokens", "cache_write_ttl", - "total_tokens", "cost_usd", "no_cache_cost_usd"]) + "total_tokens", "cost_usd", "no_cache_cost_usd", + "thinking_blocks", "tool_use_blocks", "text_blocks", + "tool_result_blocks", "image_blocks"]) for s in report["sessions"]: for t in s["turns"]: + cb = t.get("content_blocks") or {} w.writerow([ s["session_id"], t["index"], t["timestamp"], t["model"], t.get("speed", ""), @@ -1284,6 +1515,9 @@ def render_csv(report: dict) -> str: t.get("cache_write_ttl", ""), t["total_tokens"], f"{t['cost_usd']:.6f}", f"{t['no_cache_cost_usd']:.6f}", + cb.get("thinking", 0), cb.get("tool_use", 0), + cb.get("text", 0), cb.get("tool_result", 0), + cb.get("image", 0), ]) # Time-of-day summary section @@ -1395,6 +1629,22 @@ def p(*args, **kw): pct_1h = 100 * totals["cache_write_1h"] / max(1, totals["cache_write"]) p(f"| Cache TTL mix (1h share of writes) | {pct_1h:.1f}% |") p(f"| Extra cost paid for 1h cache tier | ${totals.get('extra_1h_cost', 0.0):.4f} |") + if totals.get("thinking_turn_count", 0) > 0: + cb = totals.get("content_blocks") or {} + p( + f"| Extended thinking turns | " + f"{totals['thinking_turn_count']} of {totals['turns']} " + f"({totals.get('thinking_turn_pct', 0.0):.1f}%, " + f"{cb.get('thinking', 0)} blocks) |" + ) + if totals.get("tool_call_total", 0) > 0: + top3 = totals.get("tool_names_top3") or [] + top3_str = ", ".join(top3) if top3 else "none" + p( + f"| Tool calls | {totals['tool_call_total']} total, " + f"{totals.get('tool_call_avg_per_turn', 0.0):.1f}/turn " + f"(top: {top3_str}) |" + ) p() # Time-of-day section @@ -1469,6 +1719,7 @@ def p(*args, **kw): p() has_1h_cache = _has_1h_cache(report) + has_content = _has_content_blocks(report) p("## Column legend") p() p("- **#** — deduplicated turn index") @@ -1482,6 +1733,9 @@ def p(*args, **kw): p("- **CacheWr** — tokens written to cache (one-time)") p("- **Total** — sum of the four billable token buckets") p("- **Cost $** — estimated USD for this turn") + if has_content: + p("- **Content** — per-turn content blocks: `T` thinking, `u` tool_use, " + "`x` text, `r` tool_result, `i` image (zero counts omitted)") p() for i, s in enumerate(report["sessions"], 1): @@ -1492,20 +1746,30 @@ def p(*args, **kw): p(f"{s['first_ts']} → {s['last_ts']}  ·  {len(s['turns'])} turns  ·  **${st['cost']:.4f}**") p() - p(f"| # | Time ({tz_label}) | Input (new) | Output | CacheRd | CacheWr | Total | Cost $ |") - p("|--:|-----------|------------:|------:|--------:|--------:|------:|-------:|") + if has_content: + p(f"| # | Time ({tz_label}) | Input (new) | Output | CacheRd | CacheWr | Total | Cost $ | Content |") + p("|--:|-----------|------------:|------:|--------:|--------:|------:|-------:|:--------|") + else: + p(f"| # | Time ({tz_label}) | Input (new) | Output | CacheRd | CacheWr | Total | Cost $ |") + p("|--:|-----------|------------:|------:|--------:|--------:|------:|-------:|") for t in s["turns"]: ttl = t.get("cache_write_ttl", "") cwr_cell = f"{t['cache_write_tokens']:,}" + ("*" if ttl in ("1h", "mix") else "") - p(f"| {t['index']} | {t['timestamp_fmt']} " - f"| {t['input_tokens']:,} | {t['output_tokens']:,} " - f"| {t['cache_read_tokens']:,} | {cwr_cell} " - f"| {t['total_tokens']:,} | ${t['cost_usd']:.4f} |") + row = (f"| {t['index']} | {t['timestamp_fmt']} " + f"| {t['input_tokens']:,} | {t['output_tokens']:,} " + f"| {t['cache_read_tokens']:,} | {cwr_cell} " + f"| {t['total_tokens']:,} | ${t['cost_usd']:.4f} |") + if has_content: + row += f" {_fmt_content_cell(t.get('content_blocks') or {})} |" + p(row) st = s["subtotal"] st_cwr_cell = f"{st['cache_write']:,}" + ("*" if st.get("cache_write_1h", 0) > 0 else "") - p(f"| **TOT** | | **{st['input']:,}** | **{st['output']:,}** " - f"| **{st['cache_read']:,}** | **{st_cwr_cell}** " - f"| **{st['total']:,}** | **${st['cost']:.4f}** |") + trow = (f"| **TOT** | | **{st['input']:,}** | **{st['output']:,}** " + f"| **{st['cache_read']:,}** | **{st_cwr_cell}** " + f"| **{st['total']:,}** | **${st['cost']:.4f}** |") + if has_content: + trow += " |" + p(trow) if st.get("cache_write_1h", 0) > 0: p() p(f"_`*` = cache write includes the 1-hour TTL tier " @@ -2812,11 +3076,13 @@ def render_html(report: dict, variant: str = "single", + hod_html + punchcard_html + heatmap_html) # ---- Table rows -------------------------------------------------------- - show_mode = _has_fast(report) - show_ttl = _has_1h_cache(report) + show_mode = _has_fast(report) + show_ttl = _has_1h_cache(report) + show_content = _has_content_blocks(report) - # Total columns = #, Time, Model, [Mode], Input, Output, CacheRd, CacheWr, Total, Cost - _full_cols = 10 + (1 if show_mode else 0) + # Total columns = #, Time, Model, [Mode], Input, Output, CacheRd, CacheWr, + # [Content], Total, Cost + _full_cols = 10 + (1 if show_mode else 0) + (1 if show_content else 0) # Label cell in subtotal rows spans the non-numeric prefix: #, Time, Model, [Mode] _label_span = 4 if show_mode else 3 @@ -2831,6 +3097,14 @@ def _cwr_cell(tokens: int, tokens_5m: int, tokens_1h: int, return f'{inner}{badge}' return f'{inner}' + def _content_cell(cb: dict) -> str: + label = _fmt_content_cell(cb) + title = _fmt_content_title(cb) + if label == "-": + return '–' + return (f'' + f'{label}') + def turn_row(t: dict, session_id: str) -> str: bar_w = min(100, int(t["cost_usd"] * 2000)) mode_td = "" @@ -2845,6 +3119,8 @@ def turn_row(t: dict, session_id: str) -> str: t.get("cache_write_1h_tokens", 0), t.get("cache_write_ttl", ""), ) + content_td = (_content_cell(t.get("content_blocks") or {}) + if show_content else "") return ( f'' f'{t["index"]}' @@ -2855,6 +3131,7 @@ def turn_row(t: dict, session_id: str) -> str: f'{t["output_tokens"]:,}' f'{t["cache_read_tokens"]:,}' f'{cwr_td}' + f'{content_td}' f'{t["total_tokens"]:,}' f'' f'${t["cost_usd"]:.4f}' @@ -2885,6 +3162,8 @@ def subtotal_row(label: str, st: dict) -> str: tokens_5m = st.get("cache_write_5m", 0) sub_ttl = "" cwr_td = _cwr_cell(st["cache_write"], tokens_5m, tokens_1h, sub_ttl, bold=True) + content_td = (' ' + if show_content else "") return ( f'' f'{label}' @@ -2892,6 +3171,7 @@ def subtotal_row(label: str, st: dict) -> str: f'{st["output"]:,}' f'{st["cache_read"]:,}' f'{cwr_td}' + f'{content_td}' f'{st["total"]:,}' f'${st["cost"]:.4f}' f'' @@ -2960,11 +3240,20 @@ def subtotal_row(label: str, st: dict) -> str: ) else: legend_parts.append('CacheWr cache_creation_input_tokens · ') + if show_content: + legend_parts.append( + 'Content per-turn content blocks: ' + 'T thinking, u tool_use, ' + 'x text, r tool_result, ' + 'i image (zero counts omitted) · ' + ) legend_parts.extend([ 'Total sum of the four billable token buckets · ', 'Cost $ estimated USD for this turn.', ]) legend_html = '

' + ''.join(legend_parts) + '

' + content_th = ('Content' + if show_content else "") table_section_html = ( '

Timeline

\n' + legend_html + '\n' @@ -2973,6 +3262,7 @@ def subtotal_row(label: str, st: dict) -> str: f' {"Mode" if show_mode else ""}\n' ' Input (new)Output\n' ' CacheRdCacheWr\n' + f' {content_th}\n' ' TotalCost $\n' f'\n\n{"".join(table_rows)}\n\n\n' ) @@ -3000,6 +3290,32 @@ def subtotal_row(label: str, st: dict) -> str: f'
{pct_1h:.0f}% 1h · ${extra:.4f}
' f'
Cache TTL mix (extra paid for 1h)
' ) + thinking_card = "" + if totals.get("thinking_turn_count", 0) > 0: + tn = totals["thinking_turn_count"] + tp = totals.get("thinking_turn_pct", 0.0) + blocks = (totals.get("content_blocks") or {}).get("thinking", 0) + total_turns = totals.get("turns", 0) + thinking_card = ( + f'\n
' + f'
{tp:.0f}% · {blocks} blocks
' + f'
Extended thinking engagement ' + f'({tn} of {total_turns} turns)
' + ) + tool_calls_card = "" + if totals.get("tool_call_total", 0) > 0: + tc = totals["tool_call_total"] + avg = totals.get("tool_call_avg_per_turn", 0.0) + top3 = totals.get("tool_names_top3") or [] + top3_str = ", ".join(top3) if top3 else "none" + tool_calls_card = ( + f'\n
' + f'
{tc} · {avg:.1f}/turn
' + f'
Tool calls · top: {top3_str}
' + ) summary_cards_html = f'''\
${totals['cost']:.4f}
Total cost (USD)
@@ -3009,7 +3325,7 @@ def subtotal_row(label: str, st: dict) -> str:
{totals['input']:,}
Input tokens (new)
{totals['output']:,}
Output tokens
{totals['cache_read']:,}
Cache read tokens
-
{totals['cache_write']:,}
Cache write tokens
{ttl_mix_card} +
{totals['cache_write']:,}
Cache write tokens
{ttl_mix_card}{thinking_card}{tool_calls_card}
''' toggle_script_html = "" @@ -3091,6 +3407,12 @@ def subtotal_row(label: str, st: dict) -> str: border: 1px solid #d2992266; }} .badge-ttl.ttl-mix {{ background: #8957e533; color: #bc8cff; border: 1px solid #8957e566; }} + td.content-blocks, th.content-blocks {{ font-variant-numeric: tabular-nums; + font-family: "SF Mono", Menlo, Consolas, monospace; + font-size: 11px; white-space: nowrap; + color: #8b949e; cursor: help; }} + td.content-blocks span {{ color: #a5d6ff; }} + td.content-blocks.muted {{ color: #484f58; cursor: default; }} .legend-block {{ color: #8b949e; font-size: 11px; margin: -4px 0 12px; padding: 8px 12px; background: #161b22; border: 1px solid #30363d; border-radius: 6px; diff --git a/.claude/skills/session-metrics/tests/fixtures/mini.jsonl b/.claude/skills/session-metrics/tests/fixtures/mini.jsonl index deb2cbe..3de1c32 100644 --- a/.claude/skills/session-metrics/tests/fixtures/mini.jsonl +++ b/.claude/skills/session-metrics/tests/fixtures/mini.jsonl @@ -1,16 +1,17 @@ {"type":"user","uuid":"u1","timestamp":"2026-04-15T22:30:00.000Z","isMeta":true,"sessionId":"s1","message":{"role":"user","content":[{"type":"text","text":""}]}} {"type":"user","uuid":"u2","timestamp":"2026-04-15T22:31:00.000Z","sessionId":"s1","message":{"role":"user","content":[{"type":"text","text":"hello as list"}]}} -{"type":"assistant","uuid":"a1","timestamp":"2026-04-15T22:31:05.000Z","sessionId":"s1","message":{"id":"msg_A","model":"claude-opus-4-7","role":"assistant","usage":{"input_tokens":100,"output_tokens":50,"cache_read_input_tokens":0,"cache_creation_input_tokens":1000}}} -{"type":"assistant","uuid":"a1b","timestamp":"2026-04-15T22:31:06.000Z","sessionId":"s1","message":{"id":"msg_A","model":"claude-opus-4-7","role":"assistant","usage":{"input_tokens":120,"output_tokens":80,"cache_read_input_tokens":500,"cache_creation_input_tokens":1000}}} +{"type":"assistant","uuid":"a1","timestamp":"2026-04-15T22:31:05.000Z","sessionId":"s1","message":{"id":"msg_A","model":"claude-opus-4-7","role":"assistant","content":[{"type":"thinking","thinking":"","signature":"abc"}],"usage":{"input_tokens":120,"output_tokens":80,"cache_read_input_tokens":500,"cache_creation_input_tokens":1000}}} +{"type":"assistant","uuid":"a1b","timestamp":"2026-04-15T22:31:06.000Z","sessionId":"s1","message":{"id":"msg_A","model":"claude-opus-4-7","role":"assistant","content":[{"type":"tool_use","id":"t1","name":"Bash","input":{}}],"usage":{"input_tokens":120,"output_tokens":80,"cache_read_input_tokens":500,"cache_creation_input_tokens":1000}}} +{"type":"assistant","uuid":"a1c","timestamp":"2026-04-15T22:31:07.000Z","sessionId":"s1","message":{"id":"msg_A","model":"claude-opus-4-7","role":"assistant","content":[{"type":"text","text":"done"}],"usage":{"input_tokens":120,"output_tokens":80,"cache_read_input_tokens":500,"cache_creation_input_tokens":1000}}} {"type":"user","uuid":"u3","timestamp":"2026-04-15T22:31:10.000Z","sessionId":"s1","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"t1","content":"ok"}]}} -{"type":"assistant","uuid":"a2","timestamp":"2026-04-15T22:31:15.000Z","sessionId":"s1","message":{"id":"msg_B","model":"claude-sonnet-4-7","role":"assistant","usage":{"input_tokens":10,"output_tokens":20,"cache_read_input_tokens":2000,"cache_creation_input_tokens":0}}} +{"type":"assistant","uuid":"a2","timestamp":"2026-04-15T22:31:15.000Z","sessionId":"s1","message":{"id":"msg_B","model":"claude-sonnet-4-7","role":"assistant","content":[{"type":"text","text":"reply"}],"usage":{"input_tokens":10,"output_tokens":20,"cache_read_input_tokens":2000,"cache_creation_input_tokens":0}}} {"type":"user","uuid":"u4","timestamp":"2026-04-15T22:31:20.000Z","sessionId":"s1","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"t2","content":"ok"}]}} {"type":"user","uuid":"u5","timestamp":"2026-04-15T22:31:25.000Z","isSidechain":true,"sessionId":"s1","message":{"role":"user","content":[{"type":"text","text":"subagent"}]}} -{"type":"assistant","uuid":"a3","timestamp":"2026-04-15T22:31:30.000Z","sessionId":"s1","message":{"id":"msg_C","model":"claude-opus-4-7","role":"assistant","usage":{"input_tokens":5,"output_tokens":15,"cache_read_input_tokens":3000,"cache_creation_input_tokens":0}}} +{"type":"assistant","uuid":"a3","timestamp":"2026-04-15T22:31:30.000Z","sessionId":"s1","message":{"id":"msg_C","model":"claude-opus-4-7","role":"assistant","content":[{"type":"text","text":"c-reply"}],"usage":{"input_tokens":5,"output_tokens":15,"cache_read_input_tokens":3000,"cache_creation_input_tokens":0}}} {"type":"user","uuid":"u6","timestamp":"2026-04-16T03:45:00.000Z","sessionId":"s1","message":{"role":"user","content":"second prompt as plain string"}} {"type":"user","uuid":"u7","timestamp":"2026-04-16T03:45:05.000Z","sessionId":"s1","message":{"role":"user","content":[{"type":"tool_result","tool_use_id":"t3","content":"ok"}]}} -{"type":"assistant","uuid":"a4","timestamp":"2026-04-16T03:45:10.000Z","sessionId":"s1","message":{"id":"msg_D","model":"claude-sonnet-4-7","role":"assistant","usage":{"input_tokens":200,"output_tokens":300,"cache_read_input_tokens":1500,"cache_creation_input_tokens":0}}} +{"type":"assistant","uuid":"a4","timestamp":"2026-04-16T03:45:10.000Z","sessionId":"s1","message":{"id":"msg_D","model":"claude-sonnet-4-7","role":"assistant","content":[{"type":"tool_use","id":"t4","name":"WebFetch","input":{}},{"type":"text","text":"d-reply"}],"usage":{"input_tokens":200,"output_tokens":300,"cache_read_input_tokens":1500,"cache_creation_input_tokens":0}}} {"type":"user","uuid":"u8","timestamp":"2026-04-16T03:46:00.000Z","sessionId":"s1","message":{"role":"user","content":[{"type":"text","text":"prompt before pure-1h turn"}]}} -{"type":"assistant","uuid":"a5","timestamp":"2026-04-16T03:46:05.000Z","sessionId":"s1","message":{"id":"msg_E","model":"claude-opus-4-7","role":"assistant","usage":{"input_tokens":10,"output_tokens":20,"cache_read_input_tokens":0,"cache_creation_input_tokens":500,"cache_creation":{"ephemeral_1h_input_tokens":500,"ephemeral_5m_input_tokens":0}}}} -{"type":"user","uuid":"u9","timestamp":"2026-04-16T03:46:10.000Z","sessionId":"s1","message":{"role":"user","content":[{"type":"text","text":"prompt before mix turn"}]}} -{"type":"assistant","uuid":"a6","timestamp":"2026-04-16T03:46:15.000Z","sessionId":"s1","message":{"id":"msg_F","model":"claude-sonnet-4-7","role":"assistant","usage":{"input_tokens":5,"output_tokens":10,"cache_read_input_tokens":0,"cache_creation_input_tokens":1000,"cache_creation":{"ephemeral_1h_input_tokens":400,"ephemeral_5m_input_tokens":600}}}} +{"type":"assistant","uuid":"a5","timestamp":"2026-04-16T03:46:05.000Z","sessionId":"s1","message":{"id":"msg_E","model":"claude-opus-4-7","role":"assistant","content":[{"type":"thinking","thinking":""},{"type":"text","text":"e-reply"}],"usage":{"input_tokens":10,"output_tokens":20,"cache_read_input_tokens":0,"cache_creation_input_tokens":500,"cache_creation":{"ephemeral_1h_input_tokens":500,"ephemeral_5m_input_tokens":0}}}} +{"type":"user","uuid":"u9","timestamp":"2026-04-16T03:46:10.000Z","sessionId":"s1","message":{"role":"user","content":[{"type":"text","text":"prompt before mix turn"},{"type":"image","source":{"type":"base64"}}]}} +{"type":"assistant","uuid":"a6","timestamp":"2026-04-16T03:46:15.000Z","sessionId":"s1","message":{"id":"msg_F","model":"claude-sonnet-4-7","role":"assistant","content":[{"type":"tool_use","id":"t5","name":"Read","input":{}},{"type":"tool_use","id":"t6","name":"Bash","input":{}},{"type":"text","text":"f-reply"}],"usage":{"input_tokens":5,"output_tokens":10,"cache_read_input_tokens":0,"cache_creation_input_tokens":1000,"cache_creation":{"ephemeral_1h_input_tokens":400,"ephemeral_5m_input_tokens":600}}}} diff --git a/.claude/skills/session-metrics/tests/test_session_metrics.py b/.claude/skills/session-metrics/tests/test_session_metrics.py index affe555..494ae8e 100644 --- a/.claude/skills/session-metrics/tests/test_session_metrics.py +++ b/.claude/skills/session-metrics/tests/test_session_metrics.py @@ -330,6 +330,227 @@ def test_html_render_includes_legend_and_badge(): assert "Cache TTL mix" in html +# --- Content-block distribution (Proposal B) -------------------------------- + +def test_count_content_blocks_mixed_list(): + content = [ + {"type": "thinking", "thinking": ""}, + {"type": "tool_use", "id": "t", "name": "Bash", "input": {}}, + {"type": "tool_use", "id": "u", "name": "Read", "input": {}}, + {"type": "text", "text": "hi"}, + ] + counts, names = sm._count_content_blocks(content) + assert counts["thinking"] == 1 + assert counts["tool_use"] == 2 + assert counts["text"] == 1 + assert counts["tool_result"] == 0 + assert counts["image"] == 0 + assert names == ["Bash", "Read"] + + +def test_count_content_blocks_non_list_returns_zeros(): + # Plain string content (older user prompts) has no structured blocks. + counts, names = sm._count_content_blocks("hello") + assert sum(counts.values()) == 0 + assert names == [] + counts, names = sm._count_content_blocks(None) + assert sum(counts.values()) == 0 + assert names == [] + + +def test_fixture_content_block_counts_per_turn(): + r = _build_fixture_report() + turns = r["sessions"][0]["turns"] + # msg_A: thinking + tool_use Bash + text (u2 text → no tool_result/image) + assert turns[0]["content_blocks"] == { + "thinking": 1, "tool_use": 1, "text": 1, "tool_result": 0, "image": 0, + } + # msg_B: text only; preceded by u3 (tool_result) + assert turns[1]["content_blocks"] == { + "thinking": 0, "tool_use": 0, "text": 1, "tool_result": 1, "image": 0, + } + # msg_C: text only; preceded by u5 (sidechain text) — no attributable blocks + assert turns[2]["content_blocks"] == { + "thinking": 0, "tool_use": 0, "text": 1, "tool_result": 0, "image": 0, + } + # msg_D: tool_use WebFetch + text; preceded by u7 (tool_result) + assert turns[3]["content_blocks"] == { + "thinking": 0, "tool_use": 1, "text": 1, "tool_result": 1, "image": 0, + } + # msg_E: thinking + text (pure 1h turn, preceded by u8 text) + assert turns[4]["content_blocks"] == { + "thinking": 1, "tool_use": 0, "text": 1, "tool_result": 0, "image": 0, + } + # msg_F: 2 tool_use + text; preceded by u9 (text + image) + assert turns[5]["content_blocks"] == { + "thinking": 0, "tool_use": 2, "text": 1, "tool_result": 0, "image": 1, + } + + +def test_fixture_tool_names_top3_ranked_by_count_then_name(): + r = _build_fixture_report() + totals = r["totals"] + # Across the fixture: Bash=2 (msg_A + msg_F), Read=1, WebFetch=1. + # Ties by name ascending → Read < WebFetch. + assert totals["tool_names_top3"] == ["Bash", "Read", "WebFetch"] + + +def test_fixture_thinking_turn_pct(): + r = _build_fixture_report() + t = r["totals"] + # 2 turns carry thinking out of 6 → 33.33% + assert t["thinking_turn_count"] == 2 + assert t["thinking_turn_pct"] == pytest.approx(200 / 6, abs=1e-6) + + +def test_fixture_totals_content_blocks_aggregate(): + r = _build_fixture_report() + cb = r["totals"]["content_blocks"] + assert cb == {"thinking": 2, "tool_use": 4, "text": 6, + "tool_result": 2, "image": 1} + assert r["totals"]["tool_call_total"] == 4 + assert r["totals"]["tool_call_avg_per_turn"] == pytest.approx(4 / 6, abs=1e-6) + + +def test_has_content_blocks_helpers_detect_fixture(): + r = _build_fixture_report() + assert sm._has_content_blocks(r) is True + assert sm._has_thinking(r) is True + assert sm._has_tool_use(r) is True + + +def test_csv_has_content_block_columns(): + r = _build_fixture_report() + csv_out = sm.render_csv(r) + header = csv_out.splitlines()[0] + for col in ("thinking_blocks", "tool_use_blocks", "text_blocks", + "tool_result_blocks", "image_blocks"): + assert col in header + + +def test_json_has_content_blocks_nested(): + r = _build_fixture_report() + import json as _json + data = _json.loads(sm.render_json(r)) + # Per-turn nested `content_blocks` + t = data["sessions"][0]["turns"][5] # msg_F + assert t["content_blocks"]["tool_use"] == 2 + assert t["content_blocks"]["image"] == 1 + assert t["tool_use_names"] == ["Read", "Bash"] + # Totals nested `content_blocks` + scalar aggregates + assert data["totals"]["content_blocks"]["tool_use"] == 4 + assert data["totals"]["thinking_turn_count"] == 2 + assert data["totals"]["tool_names_top3"] == ["Bash", "Read", "WebFetch"] + + +def test_text_render_includes_content_column_and_legend(): + r = _build_fixture_report() + text = sm.render_text(r) + # Legend row for Content present (only emitted when any blocks exist) + assert "Content" in text + # Per-turn content cell uses letter encoding + assert "T1 u1 x1" in text # msg_A pattern + # Tool calls footer summary visible + assert "Tool calls" in text + assert "Extended thinking turns" in text + + +def test_md_render_includes_content_column_and_legend(): + r = _build_fixture_report() + md = sm.render_md(r) + assert "**Content**" in md + assert "Extended thinking turns" in md + assert "Tool calls" in md + + +def test_html_render_includes_content_column_and_cards(): + r = _build_fixture_report() + html = sm.render_html(r, variant="single") + # Column header + a per-turn content cell rendered with tooltip + assert 'class="content-blocks"' in html + assert "Extended thinking engagement" in html + assert "Tool calls" in html + # Top-3 tool list surfaces in the Tool calls card + assert "Bash" in html + + +def test_extract_turns_merges_streaming_content_blocks(): + """Claude Code emits a single assistant message across N JSONL entries + (one per content block) that share the same msg_id and usage. Dedup + must UNION the content arrays, not keep-last-only, or Proposal B + counters silently drop thinking + earlier tool_use + text blocks. + """ + entries = [ + {"type": "user", "uuid": "u_pre", "timestamp": "2026-04-15T22:30:00Z", + "sessionId": "s", "message": {"role": "user", "content": "hi"}}, + # Streaming occurrence 1: thinking only + {"type": "assistant", "uuid": "a1", + "timestamp": "2026-04-15T22:31:05.100Z", "sessionId": "s", + "message": {"id": "msg_stream", "model": "claude-opus-4-7", + "role": "assistant", + "content": [{"type": "thinking", "thinking": "", + "signature": "sig1"}], + "usage": {"input_tokens": 10, "output_tokens": 50, + "cache_read_input_tokens": 0, + "cache_creation_input_tokens": 0}}}, + # Streaming occurrence 2: tool_use only + {"type": "assistant", "uuid": "a2", + "timestamp": "2026-04-15T22:31:05.500Z", "sessionId": "s", + "message": {"id": "msg_stream", "model": "claude-opus-4-7", + "role": "assistant", + "content": [{"type": "tool_use", "id": "t_x", + "name": "Bash", "input": {}}], + "usage": {"input_tokens": 10, "output_tokens": 50, + "cache_read_input_tokens": 0, + "cache_creation_input_tokens": 0}}}, + # Streaming occurrence 3: second tool_use only + {"type": "assistant", "uuid": "a3", + "timestamp": "2026-04-15T22:31:05.900Z", "sessionId": "s", + "message": {"id": "msg_stream", "model": "claude-opus-4-7", + "role": "assistant", + "content": [{"type": "tool_use", "id": "t_y", + "name": "Read", "input": {}}], + "usage": {"input_tokens": 10, "output_tokens": 50, + "cache_read_input_tokens": 0, + "cache_creation_input_tokens": 0}}}, + ] + turns = sm._extract_turns(entries) + assert len(turns) == 1 + content = turns[0]["message"]["content"] + types = [b["type"] for b in content] + # Union of all three streaming entries: 1 thinking + 2 tool_use. + assert types.count("thinking") == 1 + assert types.count("tool_use") == 2 + # Usage (cost math) correctly taken from last occurrence — identical across all. + assert turns[0]["message"]["usage"]["output_tokens"] == 50 + + +def test_no_content_blocks_means_column_omitted_in_text(): + """Synthesize a minimal fixture with no content blocks and verify the + text report preserves its pre-v1.3.0 shape (no Content column/legend row). + """ + entries = [ + {"type": "user", "uuid": "uU", "timestamp": "2026-04-15T22:31:00.000Z", + "sessionId": "synth", + "message": {"role": "user", "content": "hello"}}, + {"type": "assistant", "uuid": "aA", + "timestamp": "2026-04-15T22:31:05.000Z", "sessionId": "synth", + "message": {"id": "msg_S1", "model": "claude-sonnet-4-7", + "role": "assistant", + "usage": {"input_tokens": 10, "output_tokens": 20, + "cache_read_input_tokens": 0, + "cache_creation_input_tokens": 0}}}, + ] + turns = sm._extract_turns(entries) + user_ts = sm._extract_user_timestamps(entries) + r = sm._build_report("session", "synth", [("synth", turns, user_ts)]) + assert sm._has_content_blocks(r) is False + text = sm.render_text(r) + # Column legend lists the standard columns only — no `Content` row. + legend_block, _rest = text.split("\n\n", 1) + assert "Content" not in legend_block + + # --- Input validation -------------------------------------------------------- def test_validate_session_id_accepts_uuid_and_hex(): From 12c023ddd2d90b1bb85e373ef796bde9a4de04d6 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sat, 18 Apr 2026 23:23:50 +1000 Subject: [PATCH 112/174] session-metrics: sync to dev v1.3.1 SKILL.md script-invocation examples now use ${CLAUDE_SKILL_DIR} so plugin-installed users stop hitting the project-relative path that only worked for direct-copy installs. --- .claude/skills/session-metrics/SKILL.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/.claude/skills/session-metrics/SKILL.md b/.claude/skills/session-metrics/SKILL.md index a901147..2475db1 100644 --- a/.claude/skills/session-metrics/SKILL.md +++ b/.claude/skills/session-metrics/SKILL.md @@ -18,28 +18,30 @@ a timeline-ordered cost summary with per-turn and cumulative totals. ```bash # Current session (auto-detected from cwd) -uv run python .claude/skills/session-metrics/scripts/session-metrics.py +uv run python ${CLAUDE_SKILL_DIR}/scripts/session-metrics.py # Specific session ID -uv run python .claude/skills/session-metrics/scripts/session-metrics.py --session +uv run python ${CLAUDE_SKILL_DIR}/scripts/session-metrics.py --session # Specific project slug (use = when slug starts with "-") -uv run python .claude/skills/session-metrics/scripts/session-metrics.py --slug=-home-user-projects-myapp +uv run python ${CLAUDE_SKILL_DIR}/scripts/session-metrics.py --slug=-home-user-projects-myapp # Or via env var (always safe): -CLAUDE_PROJECT_SLUG="-home-user-projects-myapp" uv run python .claude/skills/session-metrics/scripts/session-metrics.py +CLAUDE_PROJECT_SLUG="-home-user-projects-myapp" uv run python ${CLAUDE_SKILL_DIR}/scripts/session-metrics.py # List available sessions for this project -uv run python .claude/skills/session-metrics/scripts/session-metrics.py --list +uv run python ${CLAUDE_SKILL_DIR}/scripts/session-metrics.py --list # All sessions — timeline + per-session subtotals + grand project total -uv run python .claude/skills/session-metrics/scripts/session-metrics.py --project-cost +uv run python ${CLAUDE_SKILL_DIR}/scripts/session-metrics.py --project-cost # Export to exports/session-metrics/ (one or more formats) -uv run python .claude/skills/session-metrics/scripts/session-metrics.py --output json -uv run python .claude/skills/session-metrics/scripts/session-metrics.py --output json csv md html -uv run python .claude/skills/session-metrics/scripts/session-metrics.py --project-cost --output html +uv run python ${CLAUDE_SKILL_DIR}/scripts/session-metrics.py --output json +uv run python ${CLAUDE_SKILL_DIR}/scripts/session-metrics.py --output json csv md html +uv run python ${CLAUDE_SKILL_DIR}/scripts/session-metrics.py --project-cost --output html ``` +> `${CLAUDE_SKILL_DIR}` is expanded by Claude Code to the skill's install directory (plugin cache, project-local copy, or bundled template — whichever applies). When running the script manually from a shell, substitute the actual path. + ## Export formats `--output` accepts one or more of: `json` `csv` `md` `html` From 0ad8e5e0e9d0c987bd216ee579f87b4a9b75e648 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sun, 19 Apr 2026 00:01:31 +1000 Subject: [PATCH 113/174] session-metrics: sync to dev v1.3.2 --- .../scripts/session-metrics.py | 179 ++++++++++-------- 1 file changed, 102 insertions(+), 77 deletions(-) diff --git a/.claude/skills/session-metrics/scripts/session-metrics.py b/.claude/skills/session-metrics/scripts/session-metrics.py index f00a1a5..fcb8816 100644 --- a/.claude/skills/session-metrics/scripts/session-metrics.py +++ b/.claude/skills/session-metrics/scripts/session-metrics.py @@ -29,6 +29,7 @@ import argparse import csv as csv_mod +import functools import gzip import hashlib import io @@ -193,13 +194,14 @@ def _cached_parse_jsonl(path: Path, use_cache: bool = True) -> list[dict]: cache_dir = _parse_cache_dir() cache_path = cache_dir / _parse_cache_key(path, mtime_ns) - if cache_path.exists(): - try: - with gzip.open(cache_path, "rt", encoding="utf-8") as fh: - return json.load(fh) - except (OSError, json.JSONDecodeError): - # Corrupt or unreadable — fall through to fresh parse. - pass + try: + with gzip.open(cache_path, "rt", encoding="utf-8") as fh: + return json.load(fh) + except FileNotFoundError: + pass + except (OSError, json.JSONDecodeError): + # Corrupt or unreadable — fall through to fresh parse. + pass entries = _parse_jsonl(path) try: @@ -264,11 +266,9 @@ def _extract_turns(entries: list[dict]) -> list[dict]: # the first streaming chunk. if msg_id not in preceding_user: preceding_user[msg_id] = last_user_content - # Union content blocks across every occurrence of this msg_id. content = msg.get("content") if isinstance(content, list): merged_content.setdefault(msg_id, []).extend(content) - # Last occurrence wins for usage / model / timestamp. last_entry[msg_id] = entry turns: list[dict] = [] for msg_id, entry in last_entry.items(): @@ -330,6 +330,20 @@ def _count_content_blocks(content) -> tuple[dict[str, int], list[str]]: ) +def _parse_iso_dt(ts: str) -> datetime | None: + """Parse an ISO-8601 timestamp to a tz-aware ``datetime``; ``None`` on failure. + + Catches the union of error types historically swallowed at every call + site so each caller's existing safety net is preserved unchanged. + """ + if not ts: + return None + try: + return datetime.fromisoformat(ts.replace("Z", "+00:00")) + except (ValueError, AttributeError, TypeError, OSError): + return None + + def _is_user_prompt(entry: dict) -> bool: """Return True for genuine user-typed prompts only. @@ -383,13 +397,12 @@ def _extract_user_timestamps( continue if entry.get("isSidechain") and not include_sidechain: continue - ts = entry.get("timestamp", "") - if not ts: + dt = _parse_iso_dt(entry.get("timestamp", "")) + if dt is None: continue try: - dt = datetime.fromisoformat(ts.replace("Z", "+00:00")) timestamps.append(int(dt.timestamp())) - except (ValueError, OSError): + except (OSError, OverflowError): continue timestamps.sort() return timestamps @@ -612,11 +625,12 @@ def _resolve_tz(tz_name: str | None, utc_offset: float | None) -> tuple[float, s def _parse_iso_epoch(ts: str) -> int: """Parse an ISO-8601 timestamp to UTC epoch seconds; 0 on failure.""" - if not ts: + dt = _parse_iso_dt(ts) + if dt is None: return 0 try: - return int(datetime.fromisoformat(ts.replace("Z", "+00:00")).timestamp()) - except (ValueError, AttributeError, OSError): + return int(dt.timestamp()) + except (OSError, OverflowError): return 0 @@ -866,26 +880,28 @@ def _resolve_session(args) -> tuple[Path, str]: return files[0], slug -def _env_slug() -> str | None: - v = os.environ.get("CLAUDE_PROJECT_SLUG") +def _env_validated(env_key: str, validator) -> str | None: + """Read ``env_key`` and run it through ``validator``. + + Returns the validated value, ``None`` if the env var is unset, or + exits 1 with an `[error] : ` line on validation failure. + """ + v = os.environ.get(env_key) if v is None: return None try: - return _validate_slug(v) + return validator(v) except argparse.ArgumentTypeError as exc: - print(f"[error] CLAUDE_PROJECT_SLUG: {exc}", file=sys.stderr) + print(f"[error] {env_key}: {exc}", file=sys.stderr) sys.exit(1) +def _env_slug() -> str | None: + return _env_validated("CLAUDE_PROJECT_SLUG", _validate_slug) + + def _env_session_id() -> str | None: - v = os.environ.get("CLAUDE_SESSION_ID") - if v is None: - return None - try: - return _validate_session_id(v) - except argparse.ArgumentTypeError as exc: - print(f"[error] CLAUDE_SESSION_ID: {exc}", file=sys.stderr) - sys.exit(1) + return _env_validated("CLAUDE_SESSION_ID", _validate_session_id) # --------------------------------------------------------------------------- @@ -1099,40 +1115,33 @@ def _text_table_headers(tz_offset_hours: float = 0.0, return hdr, "-" * len(hdr), "=" * len(hdr) +def _report_has_any(report: dict, predicate) -> bool: + """Return True if any turn across any session matches ``predicate``.""" + return any(predicate(t) for s in report["sessions"] for t in s["turns"]) + + def _has_fast(report: dict) -> bool: """Return True if any turn in the report used fast mode.""" - for s in report["sessions"]: - for t in s["turns"]: - if t.get("speed") == "fast": - return True - return False + return _report_has_any(report, lambda t: t.get("speed") == "fast") def _has_1h_cache(report: dict) -> bool: """Return True if any turn used the 1-hour cache TTL tier.""" - for s in report["sessions"]: - for t in s["turns"]: - if t.get("cache_write_1h_tokens", 0) > 0: - return True - return False + return _report_has_any(report, lambda t: t.get("cache_write_1h_tokens", 0) > 0) def _has_thinking(report: dict) -> bool: """Return True if any turn carried at least one thinking block.""" - for s in report["sessions"]: - for t in s["turns"]: - if (t.get("content_blocks") or {}).get("thinking", 0) > 0: - return True - return False + return _report_has_any( + report, lambda t: (t.get("content_blocks") or {}).get("thinking", 0) > 0 + ) def _has_tool_use(report: dict) -> bool: """Return True if any turn carried at least one tool_use block.""" - for s in report["sessions"]: - for t in s["turns"]: - if (t.get("content_blocks") or {}).get("tool_use", 0) > 0: - return True - return False + return _report_has_any( + report, lambda t: (t.get("content_blocks") or {}).get("tool_use", 0) > 0 + ) def _has_content_blocks(report: dict) -> bool: @@ -1141,12 +1150,10 @@ def _has_content_blocks(report: dict) -> bool: Drives conditional rendering of the Content column so legacy reports (or empty fixtures) stay visually unchanged. """ - for s in report["sessions"]: - for t in s["turns"]: - cb = t.get("content_blocks") or {} - if any(cb.get(k, 0) > 0 for k in cb): - return True - return False + def _any_nonzero(t): + cb = t.get("content_blocks") or {} + return any(v > 0 for v in cb.values()) + return _report_has_any(report, _any_nonzero) def _fmt_content_cell(cb: dict) -> str: @@ -1175,15 +1182,37 @@ def _fmt_content_title(cb: dict) -> str: def _fmt_ts(ts: str, offset_hours: float = 0.0) -> str: + dt = _parse_iso_dt(ts) + if dt is None: + return ts[:19] if len(ts) >= 19 else ts try: - dt = datetime.fromisoformat(ts.replace("Z", "+00:00")) if offset_hours: dt = dt.astimezone(timezone(timedelta(hours=offset_hours))) return dt.strftime("%Y-%m-%d %H:%M:%S") - except Exception: + except (ValueError, OverflowError, OSError): return ts[:19] if len(ts) >= 19 else ts +def _fmt_generated_at(report: dict) -> str: + """Format ``report["generated_at"]`` in the report's display tz. + + Falls back to a UTC-suffixed string when the timestamp can't be + parsed or shifted (preserves the prior bare-except behavior of the + two markdown/HTML render sites this consolidates). + """ + raw = report.get("generated_at", "") + tz_offset = report.get("tz_offset_hours", 0.0) + fallback = raw[:19].replace("T", " ") + " UTC" + dt = _parse_iso_dt(raw) + if dt is None: + return fallback + try: + local = dt.astimezone(timezone(timedelta(hours=tz_offset))) + return local.strftime("%Y-%m-%d %H:%M:%S") + f" {_short_tz_label(tz_offset)}" + except (ValueError, OverflowError, OSError): + return fallback + + def _short_tz_label(offset_hours: float) -> str: if offset_hours == 0: return "UTC" @@ -1597,13 +1626,7 @@ def p(*args, **kw): totals = report["totals"] mode = report["mode"] tz_offset = report.get("tz_offset_hours", 0.0) - try: - _gen_dt = datetime.fromisoformat( - report["generated_at"].replace("Z", "+00:00") - ).astimezone(timezone(timedelta(hours=tz_offset))) - generated = _gen_dt.strftime("%Y-%m-%d %H:%M:%S") + f" {_short_tz_label(tz_offset)}" - except Exception: - generated = report["generated_at"][:19].replace("T", " ") + " UTC" + generated = _fmt_generated_at(report) p(f"# Session Metrics — {slug}") p() @@ -2587,9 +2610,14 @@ def _build_chart_html( _VENDOR_CHARTS_DIR = Path(__file__).parent / "vendor" / "charts" +@functools.lru_cache(maxsize=1) def _load_chart_manifest() -> dict: """Parse ``vendor/charts/manifest.json``. Returns an empty libraries dict - if the manifest is missing (keeps the tool usable in degraded mode).""" + if the manifest is missing (keeps the tool usable in degraded mode). + + Cached for the process lifetime — callers (``_read_vendor_files`` and + ``_maybe_warn_chart_license``) only read from the returned dict. + """ mpath = _VENDOR_CHARTS_DIR / "manifest.json" if not mpath.exists(): return {"libraries": {}} @@ -3025,14 +3053,7 @@ def render_html(report: dict, variant: str = "single", slug = report["slug"] totals = report["totals"] mode = report["mode"] - _tz_off_for_gen = report.get("tz_offset_hours", 0.0) - try: - _gen_dt = datetime.fromisoformat( - report["generated_at"].replace("Z", "+00:00") - ).astimezone(timezone(timedelta(hours=_tz_off_for_gen))) - generated = _gen_dt.strftime("%Y-%m-%d %H:%M:%S") + f" {_short_tz_label(_tz_off_for_gen)}" - except Exception: - generated = report["generated_at"][:19].replace("T", " ") + " UTC" + generated = _fmt_generated_at(report) sessions = report["sessions"] # ---- Chart data -------------------------------------------------------- @@ -3191,12 +3212,16 @@ def subtotal_row(label: str, st: dict) -> str: table_rows.append('') table_rows.append(subtotal_row("PROJECT TOTAL" if mode == "project" else "TOTAL", totals)) + def _model_row_html(m: str, cnt: int) -> str: + r = _pricing_for(m) + return (f'{m}{cnt:,}' + f'${r["input"]:.2f}' + f'${r["output"]:.2f}' + f'${r["cache_read"]:.2f}' + f'${r["cache_write"]:.2f}') + model_rows = "".join( - f'{m}{cnt:,}' - f'${_pricing_for(m)["input"]:.2f}' - f'${_pricing_for(m)["output"]:.2f}' - f'${_pricing_for(m)["cache_read"]:.2f}' - f'${_pricing_for(m)["cache_write"]:.2f}' + _model_row_html(m, cnt) for m, cnt in sorted(report["models"].items(), key=lambda x: -x[1]) ) From ae44988f589d9317f42ec854a9efc80067a2ac47 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sun, 19 Apr 2026 19:02:10 +1000 Subject: [PATCH 114/174] session-metrics: sync to dev v1.3.3 --- .../scripts/session-metrics.py | 5 +++-- .../tests/test_session_metrics.py | 21 +++++++++++++++++++ 2 files changed, 24 insertions(+), 2 deletions(-) diff --git a/.claude/skills/session-metrics/scripts/session-metrics.py b/.claude/skills/session-metrics/scripts/session-metrics.py index fcb8816..f11517e 100644 --- a/.claude/skills/session-metrics/scripts/session-metrics.py +++ b/.claude/skills/session-metrics/scripts/session-metrics.py @@ -32,6 +32,7 @@ import functools import gzip import hashlib +import html as html_mod import io import json import os @@ -3146,7 +3147,7 @@ def turn_row(t: dict, session_id: str) -> str: f'' f'{t["index"]}' f'{t["timestamp_fmt"]}' - f'{t["model"]}' + f'{html_mod.escape(t["model"])}' f'{mode_td}' f'{t["input_tokens"]:,}' f'{t["output_tokens"]:,}' @@ -3214,7 +3215,7 @@ def subtotal_row(label: str, st: dict) -> str: def _model_row_html(m: str, cnt: int) -> str: r = _pricing_for(m) - return (f'{m}{cnt:,}' + return (f'{html_mod.escape(m)}{cnt:,}' f'${r["input"]:.2f}' f'${r["output"]:.2f}' f'${r["cache_read"]:.2f}' diff --git a/.claude/skills/session-metrics/tests/test_session_metrics.py b/.claude/skills/session-metrics/tests/test_session_metrics.py index 494ae8e..f7fb866 100644 --- a/.claude/skills/session-metrics/tests/test_session_metrics.py +++ b/.claude/skills/session-metrics/tests/test_session_metrics.py @@ -330,6 +330,27 @@ def test_html_render_includes_legend_and_badge(): assert "Cache TTL mix" in html +def test_html_escapes_synthetic_model_name(): + # CC writes `model: ""` for no-op assistant entries (local-command + # caveats, API errors). Without escaping, `` renders as an unknown + # HTML tag and the model cell appears blank. This test guards both the + # timeline row and the Models summary row. + r = _build_fixture_report() + # Inject a synthetic turn into the first session + models dict + syn_turn = dict(r["sessions"][0]["turns"][0]) + syn_turn["model"] = "" + r["sessions"][0]["turns"].append(syn_turn) + r["models"][""] = r["models"].get("", 0) + 1 + + html = sm.render_html(r, variant="single") + # Literal `` must NOT appear outside harmless contexts. Check the + # two specific rendering sites are escaped. + assert '' not in html + assert '' not in html + assert '<synthetic>' in html + assert '<synthetic>' in html + + # --- Content-block distribution (Proposal B) -------------------------------- def test_count_content_blocks_mixed_list(): From 63b3e181a7151b2f86c76442215de60d9f20e5db Mon Sep 17 00:00:00 2001 From: George Liu Date: Sun, 19 Apr 2026 19:48:20 +1000 Subject: [PATCH 115/174] session-metrics: sync to dev v1.4.0 --- .claude/skills/session-metrics/SKILL.md | 9 + .../scripts/session-metrics.py | 136 +++++++++++++++- .../tests/test_session_metrics.py | 154 ++++++++++++++++++ 3 files changed, 298 insertions(+), 1 deletion(-) diff --git a/.claude/skills/session-metrics/SKILL.md b/.claude/skills/session-metrics/SKILL.md index 2475db1..99dfdca 100644 --- a/.claude/skills/session-metrics/SKILL.md +++ b/.claude/skills/session-metrics/SKILL.md @@ -105,6 +105,15 @@ carried a `thinking` block — counts turns and blocks but cannot recover per-block tokens, which are rolled into `output_tokens` by Anthropic) and **Tool calls** (shown when any turn used `tool_use` blocks — total, average per turn, and the top-3 tool names). +**v1.4.0+** adds a **Session resumes** conditional card + an inline +timeline divider row at each resume point. Detection is precise: it +fires only when a `/exit` local command +appears within the last ~10 user entries before a synthetic no-op +assistant turn — the fingerprint of a `claude -c` resume. Recall is +incomplete: resumes after Ctrl+C or crash leave no trace, so the count +is a *lower bound* (hover the card for the caveat). JSON exports +include a top-level `resumes` array and a per-turn `is_resume_marker` +boolean; CSV does not add new columns. ## Reference files diff --git a/.claude/skills/session-metrics/scripts/session-metrics.py b/.claude/skills/session-metrics/scripts/session-metrics.py index f11517e..1569b2f 100644 --- a/.claude/skills/session-metrics/scripts/session-metrics.py +++ b/.claude/skills/session-metrics/scripts/session-metrics.py @@ -218,6 +218,15 @@ def _cached_parse_jsonl(path: Path, use_cache: bool = True) -> list[dict]: return entries +# Resume-marker detection: `claude -c` replays the prior session's trailing +# `/exit` local-command triplet into the resumed JSONL, and CC responds with +# a no-op `model: ""` assistant turn. The predicate below matches +# that fingerprint. See CLAUDE-session-metrics-development-history.md S22 +# for the corpus-scan data justifying the precision/recall tradeoffs. +_EXIT_CMD_MARKER = "/exit" +_RESUME_LOOKBACK_USER_ENTRIES = 10 + + def _extract_turns(entries: list[dict]) -> list[dict]: """Deduplicate on message.id and return one entry per assistant turn. @@ -242,16 +251,27 @@ def _extract_turns(entries: list[dict]) -> list[dict]: **first** occurrence in the raw stream (content-block counters use this to attribute ``tool_result`` / ``image`` blocks to the turn that consumed them). + + Also attaches ``_is_resume_marker``: True when the turn is a synthetic + no-op whose preceding ``_RESUME_LOOKBACK_USER_ENTRIES`` user entries + contain a ``/exit`` local-command marker — i.e. the fingerprint of a + `claude -c` resume. Precision is high (the triplet is unambiguous); + recall is incomplete (resumes after Ctrl+C / crash leave no trace). """ last_entry: dict[str, dict] = {} merged_content: dict[str, list] = {} preceding_user: dict[str, object] = {} + resume_marker_msg_ids: set[str] = set() + recent_user_contents: list[object] = [] last_user_content = None for entry in entries: t = entry.get("type") if t == "user": msg = entry.get("message") or {} last_user_content = msg.get("content") + recent_user_contents.append(last_user_content) + if len(recent_user_contents) > _RESUME_LOOKBACK_USER_ENTRIES: + recent_user_contents.pop(0) continue if t != "assistant": continue @@ -261,6 +281,13 @@ def _extract_turns(entries: list[dict]) -> list[dict]: msg_id = msg.get("id") if not msg_id: continue + # Resume-marker detection runs once per msg_id (first occurrence); + # streaming dupes of the same synthetic msg_id carry the same + # preceding-user context by construction. + if msg.get("model") == "" and msg_id not in resume_marker_msg_ids: + if any(isinstance(c, str) and _EXIT_CMD_MARKER in c + for c in recent_user_contents): + resume_marker_msg_ids.add(msg_id) # First-occurrence wins for the preceding user pointer — streaming # echo entries of the same msg_id don't see a new user prompt in # between, so the triggering user entry is the one we saw before @@ -278,6 +305,7 @@ def _extract_turns(entries: list[dict]) -> list[dict]: **entry, "message": merged_msg, "_preceding_user_content": preceding_user.get(msg_id), + "_is_resume_marker": msg_id in resume_marker_msg_ids, }) turns.sort(key=lambda e: e.get("timestamp", "")) return turns @@ -959,6 +987,7 @@ def _build_turn_record(global_index: int, entry: dict, "speed": u.get("speed", ""), "content_blocks": content_blocks, "tool_use_names": tool_names, + "is_resume_marker": bool(entry.get("_is_resume_marker", False)), } @@ -1057,6 +1086,7 @@ def _build_report( "subtotal": _totals_from_turns(turn_records), "models": _model_counts(turn_records), "time_of_day": _build_time_of_day(user_ts, offset_hours=tz_offset_hours), + "resumes": _build_resumes(turn_records), }) all_turns = [t for s in sessions_out for t in s["turns"]] @@ -1076,9 +1106,52 @@ def _build_report( "block_summary": _weekly_block_counts(blocks), "weekly_rollup": _build_weekly_rollup(sessions_out, sessions_raw, blocks), "peak": peak, + "resumes": [r for s in sessions_out for r in s["resumes"]], } +def _build_resumes(turn_records: list[dict]) -> list[dict]: + """Extract resume markers from per-session turn records. + + A resume marker is a turn flagged ``is_resume_marker=True`` by + `_extract_turns` (synthetic no-op preceded by a `/exit` local-command + replay in the last ~10 user entries). For each marker we compute the + wall-clock gap to the previous assistant turn in the same session — + the practical "away" time between the user's prior work and the + resumed work. When the marker is the first turn in the session + (prior-session context not observable from this file), gap is null. + When the marker is the last turn in the session (user exited and did + not return), ``terminal`` is True — render as an exit marker rather + than a resume divider. + + Returns a list ordered by ``turn_index``; each entry is a dict with + ``timestamp``, ``timestamp_fmt``, ``turn_index``, ``gap_seconds``, + ``terminal``. + """ + markers: list[dict] = [] + for i, t in enumerate(turn_records): + if not t.get("is_resume_marker"): + continue + gap: float | None = None + if i > 0: + prev_dt = _parse_iso_dt(turn_records[i-1].get("timestamp", "")) + cur_dt = _parse_iso_dt(t.get("timestamp", "")) + if prev_dt and cur_dt: + try: + gap = (cur_dt - prev_dt).total_seconds() + except (ValueError, AttributeError, TypeError, OSError): + gap = None + terminal = (i == len(turn_records) - 1) + markers.append({ + "timestamp": t.get("timestamp", ""), + "timestamp_fmt": t.get("timestamp_fmt", ""), + "turn_index": t.get("index"), + "gap_seconds": gap, + "terminal": terminal, + }) + return markers + + # --------------------------------------------------------------------------- # Formatting helpers (shared) # --------------------------------------------------------------------------- @@ -3128,6 +3201,26 @@ def _content_cell(cb: dict) -> str: f'{label}') def turn_row(t: dict, session_id: str) -> str: + # Resume markers replace the normal data row with a full-width divider + # so users see "session resumed here" inline with the timeline rather + # than an all-zero row labelled ``. The marker is still + # counted in the turn index; only the rendering changes. + if t.get("is_resume_marker"): + ts_fmt = html_mod.escape(t.get("timestamp_fmt", "")) + return ( + f'' + f'{t["index"]}' + f'' + f'' + f'↺' + f'Session resumed' + f'at {ts_fmt}' + f'' + ) bar_w = min(100, int(t["cost_usd"] * 2000)) mode_td = "" if show_mode: @@ -3342,6 +3435,32 @@ def _model_row_html(m: str, cnt: int) -> str: f'
{tc} · {avg:.1f}/turn
' f'
Tool calls · top: {top3_str}
' ) + resumes_card = "" + resumes_list = report.get("resumes") or [] + if resumes_list: + non_terminal = [r for r in resumes_list if not r.get("terminal")] + n_resumes = len(non_terminal) + # Collect short local times (HH:MM portion of timestamp_fmt) + times = [r.get("timestamp_fmt", "").split(" ")[-1][:5] + for r in non_terminal if r.get("timestamp_fmt")] + times_str = ", ".join(times) if times else "" + terminal_note = "" + n_terminal = len(resumes_list) - n_resumes + if n_terminal: + terminal_note = f' · {n_terminal} terminal exit' + if n_terminal != 1: + terminal_note += "s" + resumes_card = ( + f'\n
' + f'
↺ {n_resumes} detected
' + f'
' + f'Session resumes' + f'{(" · " + times_str) if times_str else ""}' + f'{terminal_note}' + f'
' + ) summary_cards_html = f'''\
${totals['cost']:.4f}
Total cost (USD)
@@ -3351,7 +3470,7 @@ def _model_row_html(m: str, cnt: int) -> str:
{totals['input']:,}
Input tokens (new)
{totals['output']:,}
Output tokens
{totals['cache_read']:,}
Cache read tokens
-
{totals['cache_write']:,}
Cache write tokens
{ttl_mix_card}{thinking_card}{tool_calls_card} +
{totals['cache_write']:,}
Cache write tokens
{ttl_mix_card}{thinking_card}{tool_calls_card}{resumes_card}
''' toggle_script_html = "" @@ -3449,6 +3568,21 @@ def _model_row_html(m: str, cnt: int) -> str: color: #a5d6ff; }} .chart-page-label {{ font-size: 11px; color: #8b949e; padding: 8px 16px 0; border-top: 1px solid #30363d; margin-top: 4px; }} + tr.resume-marker-row td {{ background: #0d1a2e; border-top: 1px dashed #2f5f9c; + border-bottom: 1px dashed #2f5f9c; padding: 6px 10px; }} + tr.resume-marker-row td.resume-marker-idx {{ color: #58a6ff; opacity: 0.7; }} + tr.resume-marker-row td.resume-marker-cell {{ text-align: center; + color: #8b949e; font-size: 12px; }} + .resume-marker-pill {{ display: inline-flex; align-items: center; + gap: 8px; padding: 3px 10px; + background: #1f3552; border: 1px solid #2f5f9c; + border-radius: 12px; color: #c9d1d9; cursor: help; }} + .resume-marker-pill strong {{ color: #58a6ff; font-weight: 600; + font-size: 12px; letter-spacing: 0.2px; }} + .resume-marker-pill .resume-marker-icon {{ color: #58a6ff; + font-size: 14px; line-height: 1; }} + .resume-marker-pill .resume-marker-time {{ color: #8b949e; font-size: 11px; + font-variant-numeric: tabular-nums; }} diff --git a/.claude/skills/session-metrics/tests/test_session_metrics.py b/.claude/skills/session-metrics/tests/test_session_metrics.py index f7fb866..79cdfc2 100644 --- a/.claude/skills/session-metrics/tests/test_session_metrics.py +++ b/.claude/skills/session-metrics/tests/test_session_metrics.py @@ -351,6 +351,160 @@ def test_html_escapes_synthetic_model_name(): assert '<synthetic>' in html +# --- Resume detection (Phase 3) --------------------------------------------- + +_EXIT_USER_ENTRY = { + "type": "user", + "message": {"content": "/exit\n"}, +} +_EXIT_STDOUT_ENTRY = { + "type": "user", + "message": {"content": "See ya!"}, +} +_CLEAR_USER_ENTRY = { + "type": "user", + "message": {"content": "/clear"}, +} + + +def _synthetic_assistant_entry(msg_id: str, timestamp: str = "2026-04-19T08:29:07Z"): + """Build a synthetic no-op assistant entry as CC writes it.""" + return { + "type": "assistant", + "timestamp": timestamp, + "message": { + "id": msg_id, + "model": "", + "role": "assistant", + "usage": {"input_tokens": 0, "output_tokens": 0, + "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0, + "cache_creation": {"ephemeral_1h_input_tokens": 0, + "ephemeral_5m_input_tokens": 0}}, + "content": [{"type": "text", "text": "No response requested."}], + }, + } + + +def test_extract_turns_flags_resume_marker_after_exit(): + # /exit triplet (caveat, /exit, stdout) → synthetic assistant → marker flagged + entries = [ + {"type": "user", "message": {"content": "...", + "isMeta": True}}, + _EXIT_USER_ENTRY, + _EXIT_STDOUT_ENTRY, + _synthetic_assistant_entry("msg_syn_1"), + ] + turns = sm._extract_turns(entries) + assert len(turns) == 1 + assert turns[0]["_is_resume_marker"] is True + + +def test_extract_turns_does_not_flag_synthetic_without_exit(): + # Synthetic preceded by /clear (not /exit) — no resume marker + entries = [ + _CLEAR_USER_ENTRY, + _synthetic_assistant_entry("msg_syn_2"), + ] + turns = sm._extract_turns(entries) + assert len(turns) == 1 + assert turns[0]["_is_resume_marker"] is False + + +def test_extract_turns_flags_multiple_resumes_in_one_session(): + # Two /exit → synthetic pairs separated by real work = two resumes + entries = [ + # Real assistant turn in between + {"type": "user", "message": {"content": "first prompt"}}, + {"type": "assistant", "timestamp": "2026-04-19T08:28:24Z", + "message": {"id": "msg_real_1", "model": "claude-opus-4-7", + "role": "assistant", + "usage": {"input_tokens": 6, "output_tokens": 10, + "cache_creation_input_tokens": 0, + "cache_read_input_tokens": 0}, + "content": []}}, + _EXIT_USER_ENTRY, _EXIT_STDOUT_ENTRY, + _synthetic_assistant_entry("msg_syn_a", "2026-04-19T08:29:07Z"), + # Another real turn + {"type": "user", "message": {"content": "second prompt"}}, + {"type": "assistant", "timestamp": "2026-04-19T08:30:00Z", + "message": {"id": "msg_real_2", "model": "claude-opus-4-7", + "role": "assistant", + "usage": {"input_tokens": 5, "output_tokens": 8, + "cache_creation_input_tokens": 0, + "cache_read_input_tokens": 0}, + "content": []}}, + _EXIT_USER_ENTRY, _EXIT_STDOUT_ENTRY, + _synthetic_assistant_entry("msg_syn_b", "2026-04-19T08:31:00Z"), + ] + turns = sm._extract_turns(entries) + resume_flags = [t["_is_resume_marker"] for t in turns] + # Sorted by timestamp: real_1, syn_a, real_2, syn_b + assert resume_flags == [False, True, False, True] + + +def test_build_resumes_computes_gap_and_terminal_flag(): + # Construct turn records with one mid-session and one terminal marker + turns = [ + {"index": 1, "timestamp": "2026-04-19T08:28:24Z", + "timestamp_fmt": "2026-04-19 08:28:24", "is_resume_marker": False}, + {"index": 2, "timestamp": "2026-04-19T08:29:00Z", + "timestamp_fmt": "2026-04-19 08:29:00", "is_resume_marker": True}, # mid + {"index": 3, "timestamp": "2026-04-19T08:30:00Z", + "timestamp_fmt": "2026-04-19 08:30:00", "is_resume_marker": False}, + {"index": 4, "timestamp": "2026-04-19T08:31:00Z", + "timestamp_fmt": "2026-04-19 08:31:00", "is_resume_marker": True}, # terminal + ] + resumes = sm._build_resumes(turns) + assert len(resumes) == 2 + # First marker — mid-session — gap = 36s (08:29:00 - 08:28:24) + assert resumes[0]["turn_index"] == 2 + assert resumes[0]["gap_seconds"] == 36.0 + assert resumes[0]["terminal"] is False + # Second marker — terminal — gap = 60s; terminal=True + assert resumes[1]["turn_index"] == 4 + assert resumes[1]["gap_seconds"] == 60.0 + assert resumes[1]["terminal"] is True + + +def test_html_renders_resume_marker_divider_and_card(): + # Inject a marker into the fixture report; HTML should include the + # dashboard card and timeline divider row. Baseline fixture carries no + # markers — without injection, neither the row nor the card appears. + # CSS rules for .resume-marker-row live in diff --git a/.claude/skills/session-metrics/tests/test_session_metrics.py b/.claude/skills/session-metrics/tests/test_session_metrics.py index 79cdfc2..33dc5ed 100644 --- a/.claude/skills/session-metrics/tests/test_session_metrics.py +++ b/.claude/skills/session-metrics/tests/test_session_metrics.py @@ -505,6 +505,32 @@ def test_resumes_card_absent_when_no_markers(): assert '>Session resumes' not in html +def test_html_distinguishes_terminal_exit_marker_from_resume_marker(): + # Two markers in one session: a mid-session resume (followed by more turns) + # and a terminal exit (last turn in the session). The dashboard card + # already breaks these out as "N detected · M terminal exit"; the timeline + # divider must use the same distinction so the two surfaces stay + # internally consistent. + r = _build_fixture_report() + turns = r["sessions"][0]["turns"] + # Mid marker on first turn (followed by 5 more — so non-terminal) + turns[0]["is_resume_marker"] = True + turns[0]["is_terminal_exit_marker"] = False + # Terminal marker on last turn (no subsequent turns in session) + turns[-1]["is_resume_marker"] = True + turns[-1]["is_terminal_exit_marker"] = True + r["sessions"][0]["resumes"] = sm._build_resumes(turns) + r["resumes"] = [m for s in r["sessions"] for m in s["resumes"]] + + html = sm.render_html(r, variant="single") + # Resume pill: blue, "Session resumed" label + assert 'class="resume-marker-pill"' in html + assert "Session resumed" in html + # Terminal pill: amber via .terminal modifier, "Session exited" label + assert 'class="resume-marker-pill terminal"' in html + assert "Session exited" in html + + # --- Content-block distribution (Proposal B) -------------------------------- def test_count_content_blocks_mixed_list(): From 88229730a0ed65e8d687cd80e8cd6aa4624d5cd0 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sun, 19 Apr 2026 22:31:00 +1000 Subject: [PATCH 117/174] session-metrics: sync to dev v1.5.0 --- .claude/skills/session-metrics/SKILL.md | 16 + .../references/jsonl-schema.md | 5 +- .../scripts/session-metrics.py | 452 +++++++++++++++++- .../tests/test_session_metrics.py | 290 +++++++++++ 4 files changed, 752 insertions(+), 11 deletions(-) diff --git a/.claude/skills/session-metrics/SKILL.md b/.claude/skills/session-metrics/SKILL.md index 99dfdca..27f55df 100644 --- a/.claude/skills/session-metrics/SKILL.md +++ b/.claude/skills/session-metrics/SKILL.md @@ -115,6 +115,22 @@ is a *lower bound* (hover the card for the caveat). JSON exports include a top-level `resumes` array and a per-turn `is_resume_marker` boolean; CSV does not add new columns. +**v1.5.0+** adds a **Usage Insights** panel to the HTML dashboard — +prose-style characterisations of usage patterns inspired by Anthropic's +`/usage` command (e.g. *"38% of cost came from sessions running 3+ +subagents"*, *"72% of cost was spent on turns with ≥150k context +filled"*). 10 candidate insights compute against the report with +auto-hide thresholds; only those that cross the bar render. The +highest-value passing insight sits above-the-fold; the rest collapse +into a native `
/` accordion (no JavaScript). Insights +also flow into the JSON export under the top-level `usage_insights` +key (each entry: `id`, `headline`, `body`, `value`, `threshold`, +`shown`, `always_on`) and into the Markdown export as a flat +`## Usage Insights` bullet list. Text and CSV outputs are unchanged. +Each session dict additionally gains a `duration_seconds` field +(integer, computed from raw timestamps) used by the long-session and +session-pacing insights. + ## Reference files - [`references/pricing.md`](references/pricing.md) — Per-model token prices used diff --git a/.claude/skills/session-metrics/references/jsonl-schema.md b/.claude/skills/session-metrics/references/jsonl-schema.md index d2056af..a893e14 100644 --- a/.claude/skills/session-metrics/references/jsonl-schema.md +++ b/.claude/skills/session-metrics/references/jsonl-schema.md @@ -301,8 +301,9 @@ first. Each row is a candidate for a future report-expansion plan. | Field / signal | If surfaced, the report gains… | |-------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------| -| `cache_creation.ephemeral_{5m,1h}_input_tokens` | **Proposal A.** Fixes 1h-tier cost under-count (up to 60% on cache writes) + new "Cache TTL mix" dashboard card. | -| `message.content[].type` counts (thinking / tool_use / text / tool_result / image) | **Proposal B.** Per-turn "Content" column + "Extended thinking engagement" and "Tool calls" dashboard cards. No cost-math change. | +| `cache_creation.ephemeral_{5m,1h}_input_tokens` | **Proposal A** *(implemented v1.2.0)*. Fixes 1h-tier cost under-count + "Cache TTL mix" dashboard card. | +| `message.content[].type` counts (thinking / tool_use / text / tool_result / image) | **Proposal B** *(implemented v1.3.0)*. Per-turn "Content" column + "Extended thinking engagement" and "Tool calls" cards. | +| Cross-cutting derived insights (parallel sessions, big context, big cache misses, subagent-heavy, top-3 tool dominance, off-peak share, cost concentration, model mix, session pacing, long sessions) | **Proposal C** *(implemented v1.5.0)*. Computes 10 candidate "Usage Insights" with auto-hide thresholds; renders the highest-value as an above-the-fold prose insight + the rest in a `
` accordion on the HTML dashboard. Also flows into JSON (`usage_insights`) and Markdown (`## Usage Insights` section). Inspired by Anthropic's `/usage` slash command. No cost-math change — pure derivation pass. | | `server_tool_use.{web_search,web_fetch}_requests` | Separate per-request billing currently not applied; sessions that touch server-side web tools silently under-report cost. See **Adjacent**. | | `usage.speed == "fast"` cost multiplier | Fast-mode turns under-costed 6×. Already in `references/pricing.md` as a known limitation. | | `usage.inference_geo` | 1.1× multiplier for US-only inference. Untracked; no non-empty values observed yet. | diff --git a/.claude/skills/session-metrics/scripts/session-metrics.py b/.claude/skills/session-metrics/scripts/session-metrics.py index 5f07934..930b111 100644 --- a/.claude/skills/session-metrics/scripts/session-metrics.py +++ b/.claude/skills/session-metrics/scripts/session-metrics.py @@ -1048,6 +1048,328 @@ def _model_counts(turn_records: list[dict]) -> dict[str, int]: return counts +# --------------------------------------------------------------------------- +# Usage Insights — /usage-style prose characterisations of the report +# --------------------------------------------------------------------------- +# +# Each candidate is computed against the already-built report dict (no JSONL +# re-parse). Candidates with `shown=True` render in the dashboard's Usage +# Insights panel; the rest are kept in the JSON export for downstream tools. +# Thresholds are constants here — change-by-edit if you want to tune what +# qualifies as "noteworthy" for your workflow. + +_INSIGHT_PARALLEL_PCT_THRESHOLD = 20.0 # ≥ 20% of cost from multi-session 5h blocks +_INSIGHT_LONG_SESSION_HOURS = 8 # session spans ≥ 8h wall-clock +_INSIGHT_LONG_SESSION_PCT_THRESHOLD = 10.0 +_INSIGHT_BIG_CONTEXT_TOKENS = 150_000 +_INSIGHT_BIG_CONTEXT_PCT_THRESHOLD = 10.0 +_INSIGHT_BIG_CACHE_MISS_TOKENS = 100_000 +_INSIGHT_BIG_CACHE_MISS_PCT_THRESHOLD = 5.0 +_INSIGHT_SUBAGENT_TASK_COUNT = 3 # ≥ 3 Task tool calls in a session +_INSIGHT_SUBAGENT_PCT_THRESHOLD = 10.0 +_INSIGHT_TOOL_DOMINANCE_MIN_CALLS = 10 # gate, not % +_INSIGHT_OFF_PEAK_PCT_THRESHOLD = 60.0 # heavy off-peak only (above ~58% baseline) +_INSIGHT_COST_CONCENTRATION_TOP_N = 5 +_INSIGHT_COST_CONCENTRATION_PCT = 25.0 +_INSIGHT_COST_CONCENTRATION_MIN_TURNS = 10 # avoid trivially-100% case for tiny sessions + + +def _session_task_count(session: dict) -> int: + """Count `Task` tool invocations across a session's turns. The Task tool + is Claude Code's subagent-dispatch mechanism — counting spawn calls in + the main agent's transcript works regardless of `--include-subagents`.""" + n = 0 + for t in session.get("turns", []): + for name in (t.get("tool_use_names") or []): + if name == "Task": + n += 1 + return n + + +def _turn_total_input(turn: dict) -> int: + """Total tokens fed into the model on this turn (proxy for context fill).""" + return (turn.get("input_tokens", 0) + + turn.get("cache_read_tokens", 0) + + turn.get("cache_write_tokens", 0)) + + +def _is_off_peak_local(epoch_utc: int, tz_offset_hours: float) -> bool: + """True iff the local-time hour is outside 09:00–18:00 on a weekday, + OR the local day is Saturday/Sunday. Calibrated against a 9-to-6 + Mon–Fri baseline; ~58% of hours in a 24/7 distribution are off-peak.""" + if not epoch_utc: + return False + local = datetime.fromtimestamp(epoch_utc + int(tz_offset_hours * 3600), tz=timezone.utc) + if local.weekday() >= 5: # Sat / Sun + return True + return local.hour < 9 or local.hour >= 18 + + +def _model_family(model_id: str) -> str: + """Coarse family bucket from a model id like `claude-opus-4-7`.""" + m = (model_id or "").lower() + if "opus" in m: + return "Opus" + if "sonnet" in m: + return "Sonnet" + if "haiku" in m: + return "Haiku" + return "Other" + + +def _percentile(values: list[float], pct: float) -> float: + """Nearest-rank percentile. `values` is assumed unsorted; sorted internally.""" + if not values: + return 0.0 + s = sorted(values) + k = max(0, min(len(s) - 1, int(round(pct / 100.0 * (len(s) - 1))))) + return s[k] + + +def _fmt_long_duration(seconds: float) -> str: + """Compact human duration for insight prose: `42m`, `3.2h`, `1d 4h`. + + Distinct from the existing ``_fmt_duration(int)`` helper used by the + per-session burn-rate card (which formats short, exact intervals like + ``45m12s``). Insight strings prefer rounder numbers and multi-day + coverage at the cost of second-level precision. + """ + s = max(0, int(seconds)) + if s < 3600: + return f"{s // 60}m" + h = s / 3600.0 + if h < 24: + return f"{h:.1f}h" + days = int(h // 24) + rem = int(h - days * 24) + return f"{days}d {rem}h" if rem else f"{days}d" + + +def _compute_usage_insights(report: dict) -> list[dict]: + """Compute the Usage Insights candidate list. See module-level + `_INSIGHT_*` constants for thresholds. Each entry: + {id, headline, body, value, threshold, shown, always_on} + Returns `[]` if total cost is zero (avoids percentage division by zero). + """ + totals = report.get("totals", {}) or {} + total_cost = float(totals.get("cost", 0.0) or 0.0) + if total_cost <= 0: + return [] + + sessions = report.get("sessions", []) or [] + blocks = report.get("session_blocks", []) or [] + tz_off = float(report.get("tz_offset_hours", 0.0) or 0.0) + all_turns = [t for s in sessions for t in s.get("turns", [])] + total_turns = len(all_turns) + candidates: list[dict] = [] + + # 1. Parallel sessions — cost from 5h blocks where multiple sessions touched the window. + parallel_cost = sum(b.get("cost_usd", 0.0) for b in blocks + if len(b.get("sessions_touched") or []) > 1) + parallel_pct = 100.0 * parallel_cost / total_cost + candidates.append({ + "id": "parallel_sessions", + "headline": f"{parallel_pct:.0f}%", + "body": f" of cost came from 5-hour windows where you ran more than one session in parallel — concurrent sessions share the same rate-limit window.", + "value": parallel_pct, + "threshold": _INSIGHT_PARALLEL_PCT_THRESHOLD, + "shown": parallel_pct >= _INSIGHT_PARALLEL_PCT_THRESHOLD, + "always_on": False, + }) + + # 2. Long sessions — cost share from sessions ≥ 8h wall-clock. + long_cutoff = _INSIGHT_LONG_SESSION_HOURS * 3600 + long_cost = sum(s.get("subtotal", {}).get("cost", 0.0) + for s in sessions + if s.get("duration_seconds", 0) >= long_cutoff) + long_pct = 100.0 * long_cost / total_cost + candidates.append({ + "id": "long_sessions", + "headline": f"{long_pct:.0f}%", + "body": f" of cost came from sessions active for {_INSIGHT_LONG_SESSION_HOURS}+ hours — long-lived sessions accumulate context cost over time.", + "value": long_pct, + "threshold": _INSIGHT_LONG_SESSION_PCT_THRESHOLD, + "shown": long_pct >= _INSIGHT_LONG_SESSION_PCT_THRESHOLD, + "always_on": False, + }) + + # 3. Big-context turns — cost share of turns where total input ≥ 150k. + big_ctx_cost = sum(t.get("cost_usd", 0.0) for t in all_turns + if _turn_total_input(t) >= _INSIGHT_BIG_CONTEXT_TOKENS) + big_ctx_pct = 100.0 * big_ctx_cost / total_cost + candidates.append({ + "id": "big_context_turns", + "headline": f"{big_ctx_pct:.0f}%", + "body": f" of cost was spent on turns with ≥{_INSIGHT_BIG_CONTEXT_TOKENS // 1000}k context filled — `/compact` mid-task or `/clear` between tasks keeps the running input down.", + "value": big_ctx_pct, + "threshold": _INSIGHT_BIG_CONTEXT_PCT_THRESHOLD, + "shown": big_ctx_pct >= _INSIGHT_BIG_CONTEXT_PCT_THRESHOLD, + "always_on": False, + }) + + # 4. Big cache misses — cost share of turns sending ≥ 100k uncached input. + miss_cost = sum(t.get("cost_usd", 0.0) for t in all_turns + if (t.get("input_tokens", 0) + t.get("cache_write_tokens", 0)) + >= _INSIGHT_BIG_CACHE_MISS_TOKENS) + miss_pct = 100.0 * miss_cost / total_cost + candidates.append({ + "id": "big_cache_misses", + "headline": f"{miss_pct:.0f}%", + "body": f" of cost came from turns with ≥{_INSIGHT_BIG_CACHE_MISS_TOKENS // 1000}k tokens of uncached input — typically a cold-start after a session went idle, or a large new prompt that wasn't cached.", + "value": miss_pct, + "threshold": _INSIGHT_BIG_CACHE_MISS_PCT_THRESHOLD, + "shown": miss_pct >= _INSIGHT_BIG_CACHE_MISS_PCT_THRESHOLD, + "always_on": False, + }) + + # 5. Subagent-heavy sessions — cost share from sessions with ≥ 3 Task calls. + subagent_cost = sum(s.get("subtotal", {}).get("cost", 0.0) + for s in sessions + if _session_task_count(s) >= _INSIGHT_SUBAGENT_TASK_COUNT) + subagent_pct = 100.0 * subagent_cost / total_cost + candidates.append({ + "id": "subagent_heavy", + "headline": f"{subagent_pct:.0f}%", + "body": f" of cost came from sessions that ran {_INSIGHT_SUBAGENT_TASK_COUNT}+ subagent dispatches (Task tool) — each subagent runs its own request loop.", + "value": subagent_pct, + "threshold": _INSIGHT_SUBAGENT_PCT_THRESHOLD, + "shown": subagent_pct >= _INSIGHT_SUBAGENT_PCT_THRESHOLD, + "always_on": False, + }) + + # 6. Tool dominance — top-3 tool names' share of all tool calls. + name_counts: dict[str, int] = {} + for t in all_turns: + for name in (t.get("tool_use_names") or []): + name_counts[name] = name_counts.get(name, 0) + 1 + total_tool_calls = sum(name_counts.values()) + if total_tool_calls >= _INSIGHT_TOOL_DOMINANCE_MIN_CALLS: + ranked = sorted(name_counts.items(), key=lambda x: (-x[1], x[0])) + top3 = ranked[:3] + top3_share = 100.0 * sum(c for _, c in top3) / total_tool_calls + names_str = ", ".join(html_mod.escape(n) for n, _ in top3) + candidates.append({ + "id": "top3_tools", + "headline": f"{top3_share:.0f}%", + "body": f" of all tool calls were {names_str} — your top-3 tools dominate this {total_tool_calls:,}-call workload.", + "value": top3_share, + "threshold": 0.0, + "shown": True, + "always_on": False, + }) + else: + candidates.append({ + "id": "top3_tools", + "headline": "0%", + "body": " (insufficient tool-call volume).", + "value": 0.0, + "threshold": 0.0, + "shown": False, + "always_on": False, + }) + + # 7. Off-peak share — cost share with timestamps outside 09:00–18:00 local weekday. + off_peak_cost = sum(t.get("cost_usd", 0.0) for t in all_turns + if _is_off_peak_local(_parse_iso_epoch(t.get("timestamp", "")), tz_off)) + off_peak_pct = 100.0 * off_peak_cost / total_cost + candidates.append({ + "id": "off_peak_share", + "headline": f"{off_peak_pct:.0f}%", + "body": f" of cost happened outside business hours (before 09:00, after 18:00, or on weekends in your local timezone) — heads-up that long-running subagents while you're AFK still bill.", + "value": off_peak_pct, + "threshold": _INSIGHT_OFF_PEAK_PCT_THRESHOLD, + "shown": off_peak_pct >= _INSIGHT_OFF_PEAK_PCT_THRESHOLD, + "always_on": False, + }) + + # 8. Cost concentration — top-N turns' cost share (gated on total turns ≥ 10). + if total_turns >= _INSIGHT_COST_CONCENTRATION_MIN_TURNS: + sorted_costs = sorted((t.get("cost_usd", 0.0) for t in all_turns), reverse=True) + topn_share = 100.0 * sum(sorted_costs[:_INSIGHT_COST_CONCENTRATION_TOP_N]) / total_cost + candidates.append({ + "id": "cost_concentration", + "headline": f"{topn_share:.0f}%", + "body": f" of cost was driven by just the top {_INSIGHT_COST_CONCENTRATION_TOP_N} most-expensive turns out of {total_turns:,} total — a few large turns dominate the bill.", + "value": topn_share, + "threshold": _INSIGHT_COST_CONCENTRATION_PCT, + "shown": topn_share >= _INSIGHT_COST_CONCENTRATION_PCT, + "always_on": False, + }) + else: + candidates.append({ + "id": "cost_concentration", + "headline": "0%", + "body": " (too few turns to call concentration meaningful).", + "value": 0.0, + "threshold": _INSIGHT_COST_CONCENTRATION_PCT, + "shown": False, + "always_on": False, + }) + + # 9. Model mix — cost share by family, shown iff ≥ 2 families seen. + family_cost: dict[str, float] = {} + for t in all_turns: + fam = _model_family(t.get("model", "")) + family_cost[fam] = family_cost.get(fam, 0) + t.get("cost_usd", 0.0) + families_used = [f for f, c in family_cost.items() if c > 0] + if len(families_used) >= 2: + ranked_fams = sorted(family_cost.items(), key=lambda x: -x[1]) + parts = [f"{html_mod.escape(f)} {100.0 * c / total_cost:.0f}%" + for f, c in ranked_fams if c > 0] + candidates.append({ + "id": "model_mix", + "headline": f"{len(families_used)} families", + "body": f" — cost split: {' · '.join(parts)}.", + "value": float(len(families_used)), + "threshold": 2.0, + "shown": True, + "always_on": True, + }) + else: + candidates.append({ + "id": "model_mix", + "headline": "1 family", + "body": " (single-model project).", + "value": 1.0, + "threshold": 2.0, + "shown": False, + "always_on": True, + }) + + # 10. Session pacing — turn-count distribution + duration extremes (≥ 2 sessions). + if len(sessions) >= 2: + durations = [s.get("duration_seconds", 0) for s in sessions if s.get("duration_seconds", 0) > 0] + turn_counts = [len(s.get("turns", [])) for s in sessions] + median_dur = _percentile(durations, 50) if durations else 0 + longest_dur = max(durations) if durations else 0 + tc_min = min(turn_counts) if turn_counts else 0 + tc_max = max(turn_counts) if turn_counts else 0 + tc_avg = (sum(turn_counts) / len(turn_counts)) if turn_counts else 0 + tc_p95 = _percentile([float(x) for x in turn_counts], 95) if turn_counts else 0 + candidates.append({ + "id": "session_pacing", + "headline": f"{len(sessions)} sessions", + "body": (f" — median duration {_fmt_long_duration(median_dur)}, longest {_fmt_long_duration(longest_dur)};" + f" turns/session min {tc_min:,} · avg {tc_avg:.0f} · p95 {int(tc_p95):,} · max {tc_max:,}."), + "value": float(len(sessions)), + "threshold": 2.0, + "shown": True, + "always_on": True, + }) + else: + candidates.append({ + "id": "session_pacing", + "headline": "1 session", + "body": " (no distribution to summarise).", + "value": 1.0, + "threshold": 2.0, + "shown": False, + "always_on": True, + }) + + return candidates + + def _build_report( mode: str, slug: str, @@ -1091,21 +1413,28 @@ def _build_report( if t["index"] == idx: t["is_terminal_exit_marker"] = True break + # Raw epoch span — used by usage-insights (long_sessions, session_pacing). + # Computed here while raw_turns is still in scope; the formatted + # display strings would be brittle to re-parse for arithmetic. + first_epoch = _parse_iso_epoch(raw_turns[0].get("timestamp", "")) if raw_turns else 0 + last_epoch = _parse_iso_epoch(raw_turns[-1].get("timestamp", "")) if raw_turns else 0 + duration_seconds = (last_epoch - first_epoch) if (first_epoch and last_epoch and last_epoch > first_epoch) else 0 sessions_out.append({ - "session_id": session_id, - "first_ts": _fmt_ts(raw_turns[0].get("timestamp", ""), tz_offset_hours) if raw_turns else "", - "last_ts": _fmt_ts(raw_turns[-1].get("timestamp", ""), tz_offset_hours) if raw_turns else "", - "turns": turn_records, - "subtotal": _totals_from_turns(turn_records), - "models": _model_counts(turn_records), - "time_of_day": _build_time_of_day(user_ts, offset_hours=tz_offset_hours), - "resumes": resumes, + "session_id": session_id, + "first_ts": _fmt_ts(raw_turns[0].get("timestamp", ""), tz_offset_hours) if raw_turns else "", + "last_ts": _fmt_ts(raw_turns[-1].get("timestamp", ""), tz_offset_hours) if raw_turns else "", + "duration_seconds": duration_seconds, + "turns": turn_records, + "subtotal": _totals_from_turns(turn_records), + "models": _model_counts(turn_records), + "time_of_day": _build_time_of_day(user_ts, offset_hours=tz_offset_hours), + "resumes": resumes, }) all_turns = [t for s in sessions_out for t in s["turns"]] all_user_ts = sorted(ts for _, _, uts in sessions_raw for ts in uts) blocks = _build_session_blocks(sessions_raw) - return { + report = { "generated_at": datetime.now(timezone.utc).isoformat(), "mode": mode, "slug": slug, @@ -1121,6 +1450,8 @@ def _build_report( "peak": peak, "resumes": [r for s in sessions_out for r in s["resumes"]], } + report["usage_insights"] = _compute_usage_insights(report) + return report def _build_resumes(turn_records: list[dict]) -> list[dict]: @@ -1757,6 +2088,13 @@ def p(*args, **kw): ) p() + # Usage Insights — derived from `_compute_usage_insights`. Renders only + # when at least one insight crossed its threshold; otherwise the + # section is omitted entirely so the existing layout flow is preserved. + md_insights = _build_usage_insights_md(report.get("usage_insights", []) or []) + if md_insights: + p(md_insights) + # Time-of-day section tod = report.get("time_of_day", {}) tz_label = report.get("tz_label", "UTC") @@ -3115,6 +3453,68 @@ def _render_chart_none(all_turns: list[dict]) -> tuple[str, str]: } +def _build_usage_insights_html(insights: list[dict]) -> str: + """Render the Usage Insights panel for the dashboard variant. + + Top-of-fold = the highest-value insight that crossed its threshold + (tie-break by candidate-list order). The remaining `shown` insights + collapse into a native ``
``/```` accordion. Returns + `""` if no insights are shown — the panel disappears entirely so the + layout reflows naturally to the existing rhythm. + """ + shown = [i for i in (insights or []) if i.get("shown")] + if not shown: + return "" + threshold_bearing = [i for i in shown if not i.get("always_on")] + top = max(threshold_bearing, key=lambda i: i.get("value", 0)) if threshold_bearing else shown[0] + rest = [i for i in shown if i is not top] + + def _li(insight: dict) -> str: + # `body` and `headline` are constructed in `_compute_usage_insights` + # with html_mod.escape already applied to identifier sub-strings + # (model/tool names). Here we belt-and-braces escape the whole + # string before wrapping in HTML tags. Numeric formatters + # (`f"{pct:.0f}%"` etc.) are safe. + h = html_mod.escape(insight.get("headline", "")) + b = html_mod.escape(insight.get("body", "")) + return f"
  • {h}{b}
    • " + + top_h = html_mod.escape(top.get("headline", "")) + top_b = html_mod.escape(top.get("body", "")) + if not rest: + return (f'
    \n' + f'

    {top_h}{top_b}

    \n' + f'
    ') + n = len(rest) + plural = "" if n == 1 else "s" + rest_html = "\n".join(_li(i) for i in rest) + return ( + f'
    \n' + f'

    {top_h}{top_b}

    \n' + f'
    \n' + f' Show {n} more insight{plural}\n' + f'
      \n{rest_html}\n
    \n' + f'
    \n' + f'
    ' + ) + + +def _build_usage_insights_md(insights: list[dict]) -> str: + """Render the Usage Insights as a flat Markdown bullet list. + Returns `""` if no insights are shown.""" + shown = [i for i in (insights or []) if i.get("shown")] + if not shown: + return "" + threshold_bearing = [i for i in shown if not i.get("always_on")] + top = max(threshold_bearing, key=lambda i: i.get("value", 0)) if threshold_bearing else shown[0] + ordered = [top] + [i for i in shown if i is not top] + lines = ["## Usage Insights", ""] + for i in ordered: + lines.append(f"- **{i.get('headline', '')}**{i.get('body', '')}") + lines.append("") + return "\n".join(lines) + + def render_html(report: dict, variant: str = "single", nav_sibling: str | None = None, chart_lib: str = "highcharts") -> str: @@ -3504,6 +3904,14 @@ def _model_row_html(m: str, cnt: int) -> str:
    {totals['cache_write']:,}
    Cache write tokens
    {ttl_mix_card}{thinking_card}{tool_calls_card}{resumes_card} ''' + # Usage Insights panel — sits between the summary cards and the + # weekly-rollup / time-of-day insight sections. Dashboard variant only; + # rides the same `include_insights` gate as `summary_cards_html` above. + usage_insights_html = ( + _build_usage_insights_html(report.get("usage_insights", []) or []) + if include_insights else "" + ) + toggle_script_html = "" if include_chart and mode == "project": toggle_script_html = """.", "value": 100.0, + "threshold": 1.0, "always_on": False}] + out = sm._build_usage_insights_html(bad) + assert " & ' \" ", + }) + html = smc.render_compare_html(report) + assert """" + + # Per-turn drill-down: embed one JSON payload per page (keyed by + # "-"), render a right-side drawer + optional Prompts section, + # and wire both Timeline rows and Prompts rows to the same open/close JS. + # Skip resume-marker rows — the drawer doesn't open on them. + turn_data_json_html = "" + turn_drawer_html = "" + prompts_section_html = "" + drawer_script_html = "" + if include_chart: + turn_data: dict[str, dict] = {} + prompts_rows: list[dict] = [] + for s in sessions: + sid8 = s["session_id"][:8] + for t in s["turns"]: + if t.get("is_resume_marker"): + continue + key = f'{sid8}-{t["index"]}' + turn_data[key] = { + "idx": t["index"], + "ts": t.get("timestamp_fmt", ""), + "model": t.get("model", ""), + "prompt_snippet": t.get("prompt_snippet", ""), + "prompt_text": t.get("prompt_text", ""), + "slash_command": t.get("slash_command", ""), + "tools": t.get("tool_use_detail", []) or [], + "content": t.get("content_blocks") or {}, + "cost": t.get("cost_usd", 0.0), + "no_cache_cost": t.get("no_cache_cost_usd", 0.0), + "input": t.get("input_tokens", 0), + "output": t.get("output_tokens", 0), + "cache_read": t.get("cache_read_tokens", 0), + "cache_write": t.get("cache_write_tokens", 0), + "cache_write_ttl": t.get("cache_write_ttl", ""), + "assistant_snippet": t.get("assistant_snippet", ""), + "assistant_text": t.get("assistant_text", ""), + } + if t.get("prompt_text"): + prompts_rows.append({ + "key": key, + "cost": t.get("cost_usd", 0.0), + "idx": t["index"], + "model": t.get("model", ""), + "prompt": t.get("prompt_snippet", ""), + "tools": [tu.get("name", "") for tu in + (t.get("tool_use_detail") or [])], + "tokens": t.get("total_tokens", 0), + "slash": t.get("slash_command", ""), + }) + # ` tag early. + # Replace them with `<\/` (still valid JSON inside a string literal). + payload_json = json.dumps(turn_data, separators=(",", ":"), default=str) + payload_json = payload_json.replace("{payload_json}' + ) + + turn_drawer_html = ''' +''' + + if prompts_rows: + prompts_rows.sort(key=lambda r: -r["cost"]) + top = prompts_rows[:20] + rows_html: list[str] = [] + for r in top: + tool_names = r["tools"] + if tool_names: + tools_str = ", ".join(html_mod.escape(n) + for n in tool_names[:3]) + if len(tool_names) > 3: + tools_str += f" +{len(tool_names) - 3}" + else: + tools_str = "—" + slash_badge = "" + if r.get("slash"): + slash_badge = (f' ' + f'{html_mod.escape(r["slash"])}') + key_esc = html_mod.escape(r["key"]) + rows_html.append( + f'' + f'${r["cost"]:.4f}' + f'' + f'{html_mod.escape(r["prompt"])}{slash_badge}' + f'{html_mod.escape(r["model"])}' + f'#{r["idx"]}' + f'{tools_str}' + f'{r["tokens"]:,}' + f'' + ) + prompts_section_html = ( + '
    ' + '

    Prompts ' + 'most-expensive user prompts in this report ' + '· click a row to open turn drawer

    \n' + '\n' + '' + '' + '\n' + f'{"".join(rows_html)}
    CostPromptModelTurnToolsTokens
    \n' + '
    ' + ) + + drawer_script_html = """""" title_suffix = (" — Dashboard" if variant == "dashboard" @@ -4286,6 +4782,87 @@ def _model_row_html(m: str, cnt: int) -> str: .resume-marker-pill.terminal {{ background: #2e1f0d; border-color: #9c7a2f; }} .resume-marker-pill.terminal strong, .resume-marker-pill.terminal .resume-marker-icon {{ color: #e3b341; }} + tr.turn-row {{ cursor: pointer; }} + tr.turn-row:focus {{ outline: 1px solid #58a6ff; outline-offset: -1px; }} + .turn-drawer {{ position: fixed; top: 0; right: 0; width: 380px; max-width: 92vw; + height: 100vh; background: #161b22; border-left: 1px solid #30363d; + transform: translateX(100%); transition: transform 0.18s ease-out; + overflow-y: auto; z-index: 1000; padding: 16px 20px 24px; + box-shadow: -4px 0 20px rgba(0,0,0,0.5); }} + .turn-drawer.open {{ transform: translateX(0); }} + .turn-drawer h3 {{ font-size: 14px; font-weight: 600; color: #f0f6fc; margin: 0; }} + .turn-drawer h4 {{ font-size: 11px; font-weight: 600; color: #8b949e; + margin: 14px 0 6px; text-transform: uppercase; + letter-spacing: 0.6px; }} + .turn-drawer-hdr {{ display: flex; justify-content: space-between; + align-items: center; margin-bottom: 4px; + border-bottom: 1px solid #30363d; padding-bottom: 10px; }} + .turn-drawer-close {{ background: none; border: none; color: #8b949e; + font-size: 22px; cursor: pointer; line-height: 1; + padding: 4px 8px; }} + .turn-drawer-close:hover {{ color: #f0f6fc; }} + .turn-drawer-meta {{ color: #8b949e; font-size: 11px; margin-top: 6px; + line-height: 1.6; }} + .turn-drawer-meta code {{ color: #a5d6ff; background: #0d1117; + border: 1px solid #30363d; padding: 0 5px; + border-radius: 3px; font-size: 10px; }} + .turn-drawer-pre {{ background: #0d1117; border: 1px solid #30363d; + border-radius: 4px; padding: 8px 10px; color: #c9d1d9; + font-family: "SF Mono", Menlo, Consolas, monospace; + font-size: 11px; white-space: pre-wrap; word-break: break-word; + max-height: 240px; overflow-y: auto; margin: 0; }} + .turn-drawer-more, .turn-drawer-more-a {{ margin-top: 6px; background: none; + border: 1px solid #30363d; color: #58a6ff; + padding: 3px 10px; font-size: 11px; border-radius: 4px; + cursor: pointer; }} + .turn-drawer-more:hover, .turn-drawer-more-a:hover {{ border-color: #58a6ff; }} + .turn-drawer-tools-list {{ list-style: none; padding: 0; margin: 0; }} + .turn-drawer-tools-list li {{ padding: 4px 0; border-top: 1px dashed #21262d; + font-size: 11px; color: #c9d1d9; }} + .turn-drawer-tools-list li:first-child {{ border-top: none; }} + .turn-drawer-tools-list code {{ color: #a5d6ff; background: #0d1117; + border: 1px solid #30363d; padding: 0 4px; + border-radius: 3px; font-size: 10px; }} + .turn-drawer-tool-preview {{ color: #8b949e; + font-family: "SF Mono", Menlo, Consolas, monospace; + font-size: 10px; word-break: break-word; }} + .turn-drawer-content-dl {{ display: grid; grid-template-columns: auto 1fr; + gap: 4px 12px; font-size: 11px; color: #c9d1d9; + margin: 0; }} + .turn-drawer-content-dl dt {{ color: #8b949e; }} + .turn-drawer-content-dl dd {{ margin: 0; color: #a5d6ff; + font-variant-numeric: tabular-nums; }} + .turn-drawer-cost-table {{ width: 100%; font-size: 11px; }} + .turn-drawer-cost-table th {{ color: #8b949e; font-weight: 500; + padding: 3px 6px; border: none; background: none; + text-align: left; white-space: nowrap; }} + .turn-drawer-cost-table td {{ text-align: right; padding: 3px 6px; + border: none; color: #c9d1d9; + font-variant-numeric: tabular-nums; }} + .turn-drawer-savings {{ color: #3fb950; font-size: 11px; margin-top: 4px; }} + .turn-drawer-backdrop {{ position: fixed; inset: 0; + background: rgba(0,0,0,0.35); z-index: 999; }} + .prompts-details {{ margin-top: 16px; }} + .prompts-details > summary {{ list-style: none; cursor: pointer; }} + .prompts-details > summary::-webkit-details-marker {{ display: none; }} + .prompts-details > summary h2.prompts-h2 {{ display: inline; }} + .prompts-details > summary::before {{ content: "\\25b8 "; font-size: 10px; + color: #8b949e; }} + .prompts-details[open] > summary::before {{ content: "\\25be "; }} + .prompts-table tbody tr.prompts-row {{ cursor: pointer; }} + .prompts-table tbody tr.prompts-row:focus {{ outline: 1px solid #58a6ff; + outline-offset: -1px; }} + .prompts-table td.prompt-cell {{ max-width: 560px; overflow: hidden; + text-overflow: ellipsis; white-space: nowrap; + color: #c9d1d9; }} + .prompts-table td.cost {{ color: #d29922; font-variant-numeric: tabular-nums; + white-space: nowrap; }} + .prompts-table td.model code {{ color: #a5d6ff; font-size: 11px; }} + .prompts-table .prompts-slash {{ display: inline-block; padding: 0 5px; + font-size: 10px; color: #bc8cff; + background: #8957e522; + border: 1px solid #8957e566; + border-radius: 3px; margin-left: 6px; }} @@ -4298,8 +4875,12 @@ def _model_row_html(m: str, cnt: int) -> str: {tod_html} {chart_section_html} {table_section_html} +{prompts_section_html} {models_section_html} {toggle_script_html} +{turn_data_json_html} +{turn_drawer_html} +{drawer_script_html} """ diff --git a/.claude/skills/session-metrics/tests/test_session_metrics.py b/.claude/skills/session-metrics/tests/test_session_metrics.py index 37fcd75..3576246 100644 --- a/.claude/skills/session-metrics/tests/test_session_metrics.py +++ b/.claude/skills/session-metrics/tests/test_session_metrics.py @@ -5716,3 +5716,197 @@ def test_write_output_default_ts_still_works(tmp_path, monkeypatch): # Filename must end with 16-char UTC stamp, not be empty. import re as _re assert _re.search(r"session_abcdef01_\d{8}T\d{6}Z\.json$", path.name) + + +# --- Per-turn drill-down (drawer + Prompts section) ------------------------- +# +# These tests guard the new right-side drawer + "Prompts" section that surface +# each turn's user prompt, slash command, tool calls, content-block mix, and +# assistant reply. Both are gated on the Detail + single-page HTML variants — +# Dashboard must stay untouched. + +def test_turn_record_has_prompt_and_tool_detail_fields(): + """Every non-resume turn built from the fixture carries the new fields.""" + r = _build_fixture_report() + new_keys = { + "prompt_text", "prompt_snippet", "slash_command", + "assistant_text", "assistant_snippet", "tool_use_detail", + } + for t in r["sessions"][0]["turns"]: + if t.get("is_resume_marker"): + continue + missing = new_keys - t.keys() + assert not missing, f"turn {t['index']} missing fields: {missing}" + assert isinstance(t["prompt_text"], str) + assert isinstance(t["prompt_snippet"], str) + assert isinstance(t["slash_command"], str) + assert isinstance(t["assistant_text"], str) + assert isinstance(t["assistant_snippet"], str) + assert isinstance(t["tool_use_detail"], list) + + +def test_prompt_snippet_is_truncated_to_240_chars(): + """Prompts longer than 240 chars are clipped + ellipsis; shorter stay whole.""" + long_prompt = "x" * 500 + out = sm._truncate(long_prompt, 240) + assert len(out) == 241 # 240 chars + ellipsis glyph + assert out.endswith("\u2026") + # Short prompts pass through unchanged. + assert sm._truncate("short", 240) == "short" + # Non-string input returns empty string (defensive). + assert sm._truncate(None, 240) == "" + + +@pytest.mark.parametrize("prompt,raw,expected", [ + ("/clear please", None, "/clear"), + ("/compact-now", None, "/compact-now"), + ("no slash here", None, ""), + ("", None, ""), + # XML-wrapped form — stripped from prompt_text but detected on raw content + ("wipe context", "/clear\nwipe context", "/clear"), + # Raw-list content form + ("wipe context", + [{"type": "text", "text": "/exitbye"}], + "/exit"), +]) +def test_slash_command_extraction(prompt, raw, expected): + assert sm._extract_slash_command(prompt, raw) == expected + + +def test_html_has_turn_data_json_blob(): + """Single-page HTML embeds a ", start) + blob = html[start:end].replace("<\\/", "' in html + # Every prompts row must carry data-turn-id so click-to-open works. + import re as _re + rows = _re.findall(r'= 1 + # Each row's key must match a Timeline row id="turn-". + for key in rows: + assert f'id="turn-{key}"' in html + + +def test_html_omits_prompts_section_when_no_prompts(): + """A synthetic report with zero real prompts must not render the section.""" + r = _build_fixture_report() + # Wipe prompts from every turn — simulates a tool-only subagent session. + for t in r["sessions"][0]["turns"]: + t["prompt_text"] = "" + t["prompt_snippet"] = "" + html = sm.render_html(r, variant="single") + # CSS selectors for .prompts-table live in + + +

    {page_title}

    +

    Generated {generated}  ·  Scanning: {projects_dir} +  ·  {report.get("project_count", 0)} projects, + {report.get("session_count", 0)} sessions, + {totals.get("turns", 0):,} turns

    +{summary_cards_html} +{chart_section_html} +{projects_table_html} +{insights_html} +{models_table_html} + +""" + + +# === instance mode: end ===================================================== + + def _dispatch(report: dict, formats: list[str], single_page: bool = False, chart_lib: str = "highcharts", @@ -5207,6 +6243,22 @@ def _build_parser() -> argparse.ArgumentParser: p.add_argument("--project-cost", "-p", action="store_true", help="Show all sessions in chronological order with per-session " "subtotals and a grand project total.") + p.add_argument("--all-projects", action="store_true", + help="Instance-wide dashboard: aggregate every project under the " + "projects directory into one report. Writes HTML/MD/CSV/JSON " + "and (unless --no-project-drilldown) a per-project HTML " + "drilldown for each project into a dated subfolder under " + "exports/session-metrics/instance/.") + p.add_argument("--no-project-drilldown", action="store_true", + help="With --all-projects: skip the per-project HTML drilldown " + "pass. Fast path for CI / quick-glance runs. The instance " + "HTML still renders, but project rows are plain text " + "without hyperlinks.") + p.add_argument("--projects-dir", metavar="PATH", + help="Override the Claude Code projects directory (normally " + "~/.claude/projects or $CLAUDE_PROJECTS_DIR). Highest " + "precedence. Makes it trivial to script multi-instance " + "dashboards: run --all-projects once per path.") p.add_argument("--output", "-o", nargs="+", metavar="FMT", choices=["text", "json", "csv", "md", "html"], help="Export formats in addition to stdout text. " @@ -5693,6 +6745,24 @@ def main() -> None: ) return + if args.all_projects: + # Apply the --projects-dir override (if any) before any discovery + # call. ``_projects_dir()`` reads this module-level var first, so + # setting it here cascades through _list_all_projects, _load_session, + # and every downstream helper without threading an arg through them. + if args.projects_dir: + global _PROJECTS_DIR_OVERRIDE + _PROJECTS_DIR_OVERRIDE = Path(args.projects_dir).expanduser() + _run_all_projects( + formats, tz_offset, tz_label, + peak=peak, single_page=args.single_page, + use_cache=not args.no_cache, chart_lib=chart_lib, + include_subagents=args.include_subagents, + drilldown=not args.no_project_drilldown, + suppress_model_compare_insight=args.no_model_compare_insight, + ) + return + if args.project_cost: print(f"Slug : {slug}", file=sys.stderr) print(f"TZ : {tz_label} (UTC{'+' if tz_offset >= 0 else '-'}{abs(tz_offset):g})", file=sys.stderr) diff --git a/.claude/skills/session-metrics/tests/test_session_metrics.py b/.claude/skills/session-metrics/tests/test_session_metrics.py index 0536c38..2117942 100644 --- a/.claude/skills/session-metrics/tests/test_session_metrics.py +++ b/.claude/skills/session-metrics/tests/test_session_metrics.py @@ -4,7 +4,9 @@ """ import html as html_std import importlib.util +import os import sys +import time from pathlib import Path import pytest @@ -6401,3 +6403,376 @@ def test_turn_data_json_is_html_escaped(): sid8 = r["sessions"][0]["session_id"][:8] payload = data[f"{sid8}-1"] assert payload["prompt_text"] == "" + + +# ---- Perf regression guard (opt-in) ---------------------------------------- +# Gated behind SESSION_METRICS_RUN_PERF_TESTS=1 so the default CI / uv run +# path stays fast. Baselines live under exports/perf-baselines/ and are +# updated by scripts/benchmark.py. + +@pytest.mark.perf +@pytest.mark.skipif( + not os.environ.get("SESSION_METRICS_RUN_PERF_TESTS"), + reason="set SESSION_METRICS_RUN_PERF_TESTS=1 to enable", +) +def test_parse_jsonl_under_perf_budget(tmp_path): + """Cold-parse a 5k-turn synthetic fixture in under 2 seconds. + + Deliberately generous slack (the benchmark shows ~60ms at N=1k on a + laptop). This guards against accidental 10x regressions in parse + throughput — it's a safety net, not a precision benchmark. + """ + # Inline fixture generator: keeps test self-contained, no committed + # binary fixture needed. + import json as _json + import random as _random + fx = tmp_path / "perf-5k.jsonl" + rng = _random.Random(42) + with fx.open("w", encoding="utf-8") as fh: + for i in range(5_000): + fh.write(_json.dumps({ + "type": "user", "uuid": f"u{i}", + "timestamp": "2026-01-01T00:00:00Z", + "sessionId": "perf", + "message": {"role": "user", + "content": [{"type": "text", "text": f"p{i}"}]}, + }) + "\n") + fh.write(_json.dumps({ + "type": "assistant", "uuid": f"a{i}", + "timestamp": "2026-01-01T00:00:01Z", + "sessionId": "perf", + "message": { + "id": f"m{i}", "model": "claude-opus-4-7", + "role": "assistant", + "content": [{"type": "text", "text": "x" * 50}], + "usage": { + "input_tokens": rng.randint(100, 2000), + "output_tokens": rng.randint(50, 500), + "cache_read_input_tokens": rng.randint(0, 500), + "cache_creation_input_tokens": rng.randint(0, 100), + }, + }, + }) + "\n") + t0 = time.perf_counter() + entries = sm._parse_jsonl(fx) + elapsed = time.perf_counter() - t0 + assert len(entries) == 10_000 + assert elapsed < 2.0, f"parse took {elapsed:.2f}s (budget 2.0s)" + + +# --- Instance mode (--all-projects) ------------------------------------------ +# +# Covers _list_all_projects discovery, _build_instance_report aggregation, +# _run_all_projects orchestration, and the five instance-branch renderers. + +def _write_turn(fh, *, session_id: str, uuid: str, ts: str, model: str, + input_tokens: int, output_tokens: int, + cache_read: int = 0, cache_write: int = 0, + msg_id: str | None = None) -> None: + """Append one assistant turn + its preceding user prompt to an open fh.""" + import json as _json + # User prompt (so _load_session picks up user_ts for time-of-day) + fh.write(_json.dumps({ + "type": "user", + "uuid": f"u{uuid}", + "timestamp": ts, + "sessionId": session_id, + "message": {"role": "user", + "content": [{"type": "text", "text": "hi"}]}, + }) + "\n") + fh.write(_json.dumps({ + "type": "assistant", + "uuid": f"a{uuid}", + "timestamp": ts, + "sessionId": session_id, + "message": { + "id": msg_id or f"m{uuid}", + "model": model, + "role": "assistant", + "content": [{"type": "text", "text": "ok"}], + "usage": { + "input_tokens": input_tokens, + "output_tokens": output_tokens, + "cache_read_input_tokens": cache_read, + "cache_creation_input_tokens": cache_write, + }, + }, + }) + "\n") + + +def _make_instance_fixture(root: Path, specs: dict[str, list[dict]]) -> Path: + """Materialise a fake ``~/.claude/projects/`` tree under ``root``. + + ``specs`` is ``{slug: [session_spec, ...]}`` where each session_spec is + ``{"id": str, "turns": [{model, in, out, cache_read?, cache_write?}]}``. + + Returns the projects dir path (``root``) to be passed as the + ``_PROJECTS_DIR_OVERRIDE``. + """ + root.mkdir(parents=True, exist_ok=True) + base_ts = 1_700_000_000 + for slug, sessions in specs.items(): + proj = root / slug + proj.mkdir(parents=True, exist_ok=True) + for si, sess in enumerate(sessions): + sid = sess["id"] + path = proj / f"{sid}.jsonl" + with path.open("w", encoding="utf-8") as fh: + for ti, t in enumerate(sess["turns"]): + ts_epoch = base_ts + si * 3600 + ti * 60 + ts_iso = ( + time.strftime("%Y-%m-%dT%H:%M:%S", + time.gmtime(ts_epoch)) + "Z" + ) + _write_turn( + fh, session_id=sid, uuid=f"{slug}_{si}_{ti}", + ts=ts_iso, model=t["model"], + input_tokens=t.get("in", 0), + output_tokens=t.get("out", 0), + cache_read=t.get("cache_read", 0), + cache_write=t.get("cache_write", 0), + msg_id=f"{slug}-{si}-{ti}", + ) + return root + + +@pytest.fixture +def instance_env(tmp_path, monkeypatch): + """Isolate instance-mode side effects (projects dir, parse cache, cwd).""" + projects_dir = tmp_path / "projects" + monkeypatch.setattr(sm, "_PROJECTS_DIR_OVERRIDE", projects_dir) + monkeypatch.setattr(sm, "_parse_cache_dir", lambda: tmp_path / "parse") + monkeypatch.chdir(tmp_path) # so _export_dir() lands under tmp_path + return tmp_path, projects_dir + + +def test_list_all_projects_skips_subagents_and_hidden(instance_env): + tmp_path, projects_dir = instance_env + _make_instance_fixture(projects_dir, { + "-home-user-alpha": [{"id": "sess-alpha-1", + "turns": [{"model": "claude-opus-4-7", + "in": 100, "out": 50}]}], + "-home-user-beta": [{"id": "sess-beta-1", + "turns": [{"model": "claude-sonnet-4-7", + "in": 200, "out": 80}]}], + }) + # Junk that should be skipped + (projects_dir / ".hidden").mkdir() + (projects_dir / ".hidden" / "fake.jsonl").write_text("{}\n") + (projects_dir / "subagents").mkdir() + (projects_dir / "not a slug!").mkdir() + (projects_dir / "empty-shell").mkdir() # no JSONLs → skipped + # Directory that passes _SLUG_RE but has no JSONLs + (projects_dir / "-home-user-empty").mkdir() + + discovered = sm._list_all_projects() + slugs = {s for s, _ in discovered} + assert slugs == {"-home-user-alpha", "-home-user-beta"} + # Every returned entry is a directory under projects_dir + for slug, path in discovered: + assert path.parent == projects_dir + assert path.is_dir() + + +def test_run_all_projects_aggregates_correctly(instance_env, capsys): + tmp_path, projects_dir = instance_env + _make_instance_fixture(projects_dir, { + "-home-user-alpha": [{"id": "a1", "turns": [ + {"model": "claude-opus-4-7", "in": 1000, "out": 500}]}], + "-home-user-beta": [{"id": "b1", "turns": [ + {"model": "claude-sonnet-4-7", "in": 2000, "out": 1000}]}], + }) + + sm._run_all_projects( + formats=["html", "md", "csv", "json"], + tz_offset=0.0, tz_label="UTC", + use_cache=False, chart_lib="none", + include_subagents=False, drilldown=False, + ) + + # Dated subfolder under exports/session-metrics/instance/ + runs = list((tmp_path / "exports" / "session-metrics" + / "instance").iterdir()) + assert len(runs) == 1 + run = runs[0] + for fmt in ("html", "md", "csv", "json"): + assert (run / f"index.{fmt}").exists(), f"missing index.{fmt}" + # No drilldown folder + assert not (run / "projects").exists() + + +def test_instance_report_shape(instance_env): + tmp_path, projects_dir = instance_env + _make_instance_fixture(projects_dir, { + "-home-user-alpha": [{"id": "a1", "turns": [ + {"model": "claude-opus-4-7", "in": 1000, "out": 500}]}], + "-home-user-beta": [{"id": "b1", "turns": [ + {"model": "claude-sonnet-4-7", "in": 2000, "out": 1000}]}], + }) + # Drive _run_all_projects with no formats so only in-memory assertions matter + captured = {} + real_dispatch = sm._dispatch_instance + + def spy(instance_report, project_reports, formats, **kw): + captured["ir"] = instance_report + captured["prs"] = project_reports + return real_dispatch(instance_report, project_reports, formats, **kw) + + import pytest as _pytest + with _pytest.MonkeyPatch.context() as mp: + mp.setattr(sm, "_dispatch_instance", spy) + sm._run_all_projects( + formats=[], tz_offset=0.0, tz_label="UTC", + use_cache=False, chart_lib="none", + include_subagents=False, drilldown=False, + ) + ir = captured["ir"] + assert ir["mode"] == "instance" + assert ir["slug"] == "all-projects" + assert ir["project_count"] == 2 + assert ir["session_count"] == 2 + assert isinstance(ir["projects"], list) and len(ir["projects"]) == 2 + # No per-turn leakage: session summaries have turn_count but no "turns" key + for proj in ir["projects"]: + for s in proj.get("sessions", []): + assert "turns" not in s + assert "turn_count" in s + # Totals actually aggregated + assert ir["totals"]["input"] == 1000 + 2000 + assert ir["totals"]["output"] == 500 + 1000 + # Models merged + assert set(ir["models"].keys()) == { + "claude-opus-4-7", "claude-sonnet-4-7"} + + +def test_instance_breakdown_sorted_by_cost_desc(instance_env): + tmp_path, projects_dir = instance_env + # Make three projects with markedly different costs (use Opus to amplify) + _make_instance_fixture(projects_dir, { + "-home-user-alpha": [{"id": "a1", "turns": [ # small + {"model": "claude-opus-4-7", "in": 100, "out": 50}]}], + "-home-user-beta": [{"id": "b1", "turns": [ # huge + {"model": "claude-opus-4-7", "in": 100_000, "out": 50_000}]}], + "-home-user-gamma": [{"id": "c1", "turns": [ # medium + {"model": "claude-opus-4-7", "in": 10_000, "out": 5_000}]}], + }) + captured = {} + + def spy(instance_report, project_reports, formats, **kw): + captured["ir"] = instance_report + + import pytest as _pytest + with _pytest.MonkeyPatch.context() as mp: + mp.setattr(sm, "_dispatch_instance", spy) + sm._run_all_projects( + formats=[], tz_offset=0.0, tz_label="UTC", + use_cache=False, chart_lib="none", + include_subagents=False, drilldown=False, + ) + slugs_in_order = [p["slug"] for p in captured["ir"]["projects"]] + assert slugs_in_order == [ + "-home-user-beta", "-home-user-gamma", "-home-user-alpha" + ], f"unsorted: {slugs_in_order}" + costs = [p["cost_usd"] for p in captured["ir"]["projects"]] + assert costs == sorted(costs, reverse=True) + + +def _run_instance_capture_html(instance_env, *, drilldown: bool) -> tuple[str, Path]: + """Helper: run instance mode, return (html_text, run_dir).""" + tmp_path, projects_dir = instance_env + _make_instance_fixture(projects_dir, { + "-home-user-alpha": [{"id": "a1", "turns": [ + {"model": "claude-opus-4-7", "in": 1000, "out": 500}]}], + "-home-user-beta": [{"id": "b1", "turns": [ + {"model": "claude-sonnet-4-7", "in": 2000, "out": 1000}]}], + }) + sm._run_all_projects( + formats=["html"], tz_offset=0.0, tz_label="UTC", + use_cache=False, chart_lib="none", + include_subagents=False, drilldown=drilldown, + ) + runs = list((tmp_path / "exports" / "session-metrics" + / "instance").iterdir()) + assert len(runs) == 1 + run = runs[0] + html_path = run / "index.html" + return html_path.read_text(encoding="utf-8"), run + + +def test_render_html_instance_suppresses_drawer(instance_env): + html, _ = _run_instance_capture_html(instance_env, drilldown=False) + # The per-turn drawer is a detail-page artefact — it must not appear + # in the instance index. Same for the turn-level data blob. + assert 'id="turn-drawer"' not in html + assert 'id="turn-data-json"' not in html + + +def test_render_html_instance_hyperlinks_to_project_drilldowns(instance_env): + html, run = _run_instance_capture_html(instance_env, drilldown=True) + # One href per project, pointing at a relative projects/.html + assert 'href="projects/-home-user-alpha.html"' in html + assert 'href="projects/-home-user-beta.html"' in html + # Drilldown files actually exist on disk + assert (run / "projects" / "-home-user-alpha.html").exists() + assert (run / "projects" / "-home-user-beta.html").exists() + + +def test_render_html_instance_no_drilldown_flag(instance_env): + html, run = _run_instance_capture_html(instance_env, drilldown=False) + assert 'href="projects/' not in html + assert not (run / "projects").exists() + + +def test_render_csv_instance_has_project_slug_column(instance_env): + tmp_path, projects_dir = instance_env + _make_instance_fixture(projects_dir, { + "-home-user-alpha": [{"id": "a1", "turns": [ + {"model": "claude-opus-4-7", "in": 1000, "out": 500}]}], + "-home-user-beta": [{"id": "b1", "turns": [ + {"model": "claude-sonnet-4-7", "in": 2000, "out": 1000}]}], + }) + sm._run_all_projects( + formats=["csv"], tz_offset=0.0, tz_label="UTC", + use_cache=False, chart_lib="none", + include_subagents=False, drilldown=False, + ) + run = next(iter( + (tmp_path / "exports" / "session-metrics" / "instance").iterdir())) + content = (run / "index.csv").read_text(encoding="utf-8") + header = content.splitlines()[0] + assert header.startswith("project_slug,") + # Two per-session data rows — filter to rows whose first column looks + # like a project slug (starts with "-"), which skips the "# TOTALS" / + # "# PROJECTS" sub-section headers that follow. + data_rows = [ln for ln in content.splitlines() + if ln and ln[0] == "-" and "," in ln] + assert len(data_rows) >= 2, f"expected >=2 slug rows; got {data_rows}" + # Drop the "projects breakdown" rollup (one row per project) so only + # per-session rows remain — they have the session_id in column 1. + per_session = [row for row in data_rows + if row.split(",")[1] in {"a1", "b1"}] + assert len(per_session) == 2 + slugs_seen = {row.split(",")[0] for row in per_session} + assert slugs_seen == {"-home-user-alpha", "-home-user-beta"} + + +def test_render_md_instance_has_projects_breakdown(instance_env): + tmp_path, projects_dir = instance_env + _make_instance_fixture(projects_dir, { + "-home-user-alpha": [{"id": "a1", "turns": [ + {"model": "claude-opus-4-7", "in": 1000, "out": 500}]}], + "-home-user-beta": [{"id": "b1", "turns": [ + {"model": "claude-sonnet-4-7", "in": 2000, "out": 1000}]}], + }) + sm._run_all_projects( + formats=["md"], tz_offset=0.0, tz_label="UTC", + use_cache=False, chart_lib="none", + include_subagents=False, drilldown=False, + ) + run = next(iter( + (tmp_path / "exports" / "session-metrics" / "instance").iterdir())) + md = (run / "index.md").read_text(encoding="utf-8") + # Contains the instance dashboard header + both project rows + assert "all-projects" in md.lower() or "instance" in md.lower() + assert "-home-user-alpha" in md + assert "-home-user-beta" in md From 58abe000d578efe88e7bb9f4edf9de32d73d6682 Mon Sep 17 00:00:00 2001 From: George Liu Date: Wed, 22 Apr 2026 22:04:41 +1000 Subject: [PATCH 136/174] session-metrics: sync to dev v1.14.0 (test-hygiene autouse fixture) --- .../tests/test_session_metrics.py | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/.claude/skills/session-metrics/tests/test_session_metrics.py b/.claude/skills/session-metrics/tests/test_session_metrics.py index 2117942..875eef5 100644 --- a/.claude/skills/session-metrics/tests/test_session_metrics.py +++ b/.claude/skills/session-metrics/tests/test_session_metrics.py @@ -32,6 +32,41 @@ def _load_module(name: str, path: Path): smc = _load_module("session_metrics_compare", _COMPARE) +# --- Global test-isolation guard --------------------------------------------- +# +# Several helpers in the script (``_touch_compare_state_marker``, +# ``_find_jsonl_files``, ``_resolve_session``) reach into ``_projects_dir()`` +# directly. If a test exercises a code path that writes into the projects +# dir — most notably ``_touch_compare_state_marker`` which ``mkdir``s the +# slug directory as a side effect — and does NOT monkeypatch +# ``_PROJECTS_DIR_OVERRIDE``, the write lands in the *real* +# ``~/.claude/projects/``. Over many test runs that leaves hundreds of +# pytest-named leftover directories that pollute the user's actual projects +# catalogue. +# +# This autouse fixture redirects ``_projects_dir()`` to a per-test tmp dir +# for every test in the suite by setting the ``CLAUDE_PROJECTS_DIR`` env +# var (the public override documented for end-users). We deliberately do +# NOT set ``_PROJECTS_DIR_OVERRIDE`` here — that takes *higher* precedence +# than the env var and would clobber the ~30 existing tests that set +# ``CLAUDE_PROJECTS_DIR`` themselves to point at a fixture tree. Tests +# that later call ``monkeypatch.setenv`` override this safely (pytest's +# monkeypatch stacks values and unwinds them in LIFO order at teardown). +# Tests that use ``_PROJECTS_DIR_OVERRIDE`` directly (e.g. the +# ``instance_env`` fixture) also override this because that var has +# higher precedence inside ``_projects_dir()``. +# +# Tests that legitimately need to read the user's real projects dir can +# opt out with ``@pytest.mark.real_projects_dir``. +@pytest.fixture(autouse=True) +def _isolate_projects_dir(tmp_path, monkeypatch, request): + if request.node.get_closest_marker("real_projects_dir"): + return + safe = tmp_path / "_autouse_projects" + safe.mkdir(parents=True, exist_ok=True) + monkeypatch.setenv("CLAUDE_PROJECTS_DIR", str(safe)) + + # --- Pricing ----------------------------------------------------------------- def test_pricing_opus_4_7_explicit(): From dc155091d04f307f29e00fd83afb9d9bb94c0c5a Mon Sep 17 00:00:00 2001 From: George Liu Date: Wed, 22 Apr 2026 22:29:44 +1000 Subject: [PATCH 137/174] session-metrics: sync to dev v1.14.1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Payload fix: the v1.14.0 instance dashboard's daily-cost-timeline chart had hardcoded zero token series (flatlined stacked bars) and an incorrect "Turn" x-axis label even though each data point was a calendar day. Dev v1.14.1 threads real per-day input/output/ cache-read/cache-write token buckets into the chart and relabels the axis as "Day" (pagination header now reads "Days 1–60 of N"). Also documents the --all-projects instance dashboard (shipped in v1.14.0, previously unmentioned) across all four README variants with a pointer to the `/plugin install session-metrics@centminmod` marketplace install path. --- .../scripts/session-metrics.py | 81 ++++++++--- .../tests/test_session_metrics.py | 128 ++++++++++++++++++ README-v2.md | 2 +- README-v3.md | 2 +- README-v4.md | 4 +- README.md | 3 +- 6 files changed, 195 insertions(+), 25 deletions(-) diff --git a/.claude/skills/session-metrics/scripts/session-metrics.py b/.claude/skills/session-metrics/scripts/session-metrics.py index f9a8282..38931b8 100644 --- a/.claude/skills/session-metrics/scripts/session-metrics.py +++ b/.claude/skills/session-metrics/scripts/session-metrics.py @@ -3722,18 +3722,24 @@ def _extract_chart_series(all_turns: list[dict]) -> dict: } -def _render_chart_highcharts(all_turns: list[dict]) -> tuple[str, str]: +def _render_chart_highcharts(all_turns: list[dict], + x_title: str = "Turn") -> tuple[str, str]: """Highcharts renderer. Returns ``(chart_body_html, head_html)``. ``chart_body_html`` is the full ``
    …
    `` block dropped in the report body; ``head_html`` is the vendored library bundle wrapped in a ready-to-inline ``") @@ -3771,7 +3777,8 @@ def _build_lib_chart_pages(series: dict, x_title: str) -> tuple[str, str]: return ("\n".join(divs), data_json) -def _render_chart_uplot(all_turns: list[dict]) -> tuple[str, str]: +def _render_chart_uplot(all_turns: list[dict], + x_title: str = "Turn") -> tuple[str, str]: """uPlot renderer (MIT). Returns ``(body_html, head_html)``. uPlot has no built-in stacked-bars API — we pre-compute cumulative @@ -3779,11 +3786,14 @@ def _render_chart_uplot(all_turns: list[dict]) -> tuple[str, str]: baseline (the bottom-most series is drawn last so it sits on top visually). Cost is a separate line series on a right-hand y-axis. Pagination + lazy rendering match the Highcharts renderer. + + ``x_title`` controls the x-series label and the pagination header. + See :func:`_render_chart_highcharts` for the instance-scope rationale. """ if not all_turns: return ("", "") series = _extract_chart_series(all_turns) - containers_html, data_json = _build_lib_chart_pages(series, "Turn") + containers_html, data_json = _build_lib_chart_pages(series, x_title) css = _read_vendor_css("uplot") js = _read_vendor_js("uplot") @@ -3847,7 +3857,7 @@ def _render_chart_uplot(all_turns: list[dict]) -> tuple[str, str]: }} }}, ], series: [ - {{ label: 'Turn' }}, + {{ label: '{x_title}' }}, {{ label: 'Input (new)', stroke: '#1f6feb', fill: 'rgba(31,111,235,0.85)', paths: bars, points: {{ show: false }}, value: function (u, v, sIdx, dIdx) {{ @@ -3917,18 +3927,23 @@ def _render_chart_uplot(all_turns: list[dict]) -> tuple[str, str]: return (body, head_html) -def _render_chart_chartjs(all_turns: list[dict]) -> tuple[str, str]: +def _render_chart_chartjs(all_turns: list[dict], + x_title: str = "Turn") -> tuple[str, str]: """Chart.js v4 renderer (MIT). Returns ``(body_html, head_html)``. Mixed bar+line: four ``type: 'bar'`` datasets share ``stack: 'tokens'`` on the left y-axis (``stacked: true``), one ``type: 'line'`` dataset rides on the right y-axis ``y1`` for cost. Pagination + lazy rendering match the Highcharts renderer. + + ``x_title`` controls the pagination header text (Chart.js itself has + no x-axis title configured here; the instance dashboard still needs + "Days 1–60 of N" instead of the default "Turns 1–60 of N"). """ if not all_turns: return ("", "") series = _extract_chart_series(all_turns) - containers_html, data_json = _build_lib_chart_pages(series, "Turn") + containers_html, data_json = _build_lib_chart_pages(series, x_title) js = _read_vendor_js("chartjs") if not js: @@ -4034,10 +4049,14 @@ def _render_chart_chartjs(all_turns: list[dict]) -> tuple[str, str]: return (body, head_html) -def _render_chart_none(all_turns: list[dict]) -> tuple[str, str]: +def _render_chart_none(all_turns: list[dict], + x_title: str = "Turn") -> tuple[str, str]: """No-chart renderer. Emits an empty body + empty head — useful when the - caller wants a minimal detail page with no JS dependencies.""" - del all_turns + caller wants a minimal detail page with no JS dependencies. + + ``x_title`` accepted for API parity with the other renderers; ignored. + """ + del all_turns, x_title return ("", "") @@ -5274,10 +5293,15 @@ def _build_instance_daily(project_reports: list[dict], """Aggregate per-turn cost into daily buckets, attributed by project. Returns ``(daily, top_slugs)`` where ``daily`` is a list of - ``{date, cost, tokens, by_project: {slug: cost_usd}}`` dicts sorted - oldest-first, and ``top_slugs`` is the slug list that the instance - chart stacks (all other projects are rolled into an "other" series - by the renderer). + ``{date, cost, tokens, input, output, cache_read, cache_write, + by_project: {slug: cost_usd}}`` dicts sorted oldest-first, and + ``top_slugs`` is the slug list that the instance chart stacks + (all other projects are rolled into an "other" series by the renderer). + + The four per-token subcategories (``input`` / ``output`` / ``cache_read`` + / ``cache_write``) are tracked separately so the instance daily-cost + chart can feed a real stacked-bar breakdown to the chart renderer, + rather than flatlining those four series at 0 (the pre-v1.14.1 bug). """ buckets: dict[str, dict] = {} project_cost: dict[str, float] = {} @@ -5293,10 +5317,18 @@ def _build_instance_daily(project_reports: list[dict], local = (dt + shift).date().isoformat() cost = float(t.get("cost_usd", 0.0)) tokens = int(t.get("total_tokens", 0)) - b = buckets.setdefault(local, {"date": local, "cost": 0.0, - "tokens": 0, "by_project": {}}) + b = buckets.setdefault(local, { + "date": local, "cost": 0.0, "tokens": 0, + "input": 0, "output": 0, + "cache_read": 0, "cache_write": 0, + "by_project": {}, + }) b["cost"] += cost b["tokens"] += tokens + b["input"] += int(t.get("input_tokens", 0) or 0) + b["output"] += int(t.get("output_tokens", 0) or 0) + b["cache_read"] += int(t.get("cache_read_tokens", 0) or 0) + b["cache_write"] += int(t.get("cache_write_tokens", 0) or 0) b["by_project"][slug] = b["by_project"].get(slug, 0.0) + cost project_cost[slug] = project_cost.get(slug, 0.0) + cost daily = sorted(buckets.values(), key=lambda x: x["date"]) @@ -5935,16 +5967,23 @@ def _render_instance_html(report: dict, chart_lib: str = "highcharts") -> str: "timestamp_fmt": d["date"], "cost_usd": float(d.get("cost", 0.0)), "total_tokens": int(d.get("tokens", 0)), - "input_tokens": 0, - "output_tokens": 0, - "cache_read_tokens": 0, - "cache_write_tokens": 0, + # v1.14.1: pipe real per-day token buckets through to the + # chart renderer. Prior to this change all four series were + # hardcoded to 0, producing a flatlined stacked-bar chart + # where only the Cost $ line carried real data. + "input_tokens": int(d.get("input", 0)), + "output_tokens": int(d.get("output", 0)), + "cache_read_tokens": int(d.get("cache_read", 0)), + "cache_write_tokens": int(d.get("cache_write", 0)), "model": "instance", "index": 0, }) if synth_turns: renderer = CHART_RENDERERS.get(chart_lib) or _render_chart_none - chart_html, chart_head_html = renderer(synth_turns) + # At instance scope each data point is a calendar day — override + # the chart renderers' default "Turn" axis label so the x-axis + # title + pagination header ("Days 1–60 of N") match reality. + chart_html, chart_head_html = renderer(synth_turns, x_title="Day") else: chart_html = "" chart_head_html = "" diff --git a/.claude/skills/session-metrics/tests/test_session_metrics.py b/.claude/skills/session-metrics/tests/test_session_metrics.py index 875eef5..5e030c7 100644 --- a/.claude/skills/session-metrics/tests/test_session_metrics.py +++ b/.claude/skills/session-metrics/tests/test_session_metrics.py @@ -6811,3 +6811,131 @@ def test_render_md_instance_has_projects_breakdown(instance_env): assert "all-projects" in md.lower() or "instance" in md.lower() assert "-home-user-alpha" in md assert "-home-user-beta" in md + + +# --- v1.14.1: instance daily token breakdown + chart axis label ------------- +# +# Pre-v1.14.1 the daily buckets only tracked cost + total_tokens, so the +# instance HTML chart flatlined the four stacked-bar series (input, output, +# cache_read, cache_write) at 0 and the x-axis was labelled "Turn" even +# though each data point was a calendar day. These tests pin the fix. + +def test_build_instance_daily_tracks_per_token_breakdowns(instance_env): + """_build_instance_daily must accumulate input/output/cache_read/ + cache_write totals per day so the instance chart can render real + stacked-bar data rather than hardcoded zeros.""" + tmp_path, projects_dir = instance_env + _make_instance_fixture(projects_dir, { + "-home-user-alpha": [{"id": "a1", "turns": [ + {"model": "claude-opus-4-7", "in": 1000, "out": 500, + "cache_read": 400, "cache_write": 200}]}], + "-home-user-beta": [{"id": "b1", "turns": [ + {"model": "claude-sonnet-4-7", "in": 2000, "out": 1000, + "cache_read": 800, "cache_write": 300}]}], + }) + captured = {} + + def spy(instance_report, project_reports, formats, **kw): + captured["ir"] = instance_report + + import pytest as _pytest + with _pytest.MonkeyPatch.context() as mp: + mp.setattr(sm, "_dispatch_instance", spy) + sm._run_all_projects( + formats=[], tz_offset=0.0, tz_label="UTC", + use_cache=False, chart_lib="none", + include_subagents=False, drilldown=False, + ) + daily = captured["ir"]["daily"] + assert daily, "expected at least one daily bucket" + # Every bucket carries the four per-token subcategories + required_keys = {"date", "cost", "tokens", + "input", "output", "cache_read", "cache_write"} + for b in daily: + assert required_keys.issubset(b.keys()), \ + f"missing keys in bucket {b}" + # And they're integers, non-negative + for k in ("input", "output", "cache_read", "cache_write"): + assert isinstance(b[k], int) and b[k] >= 0 + + # Summing across days must reproduce the grand totals + assert sum(b["input"] for b in daily) == 3000 # 1000 + 2000 + assert sum(b["output"] for b in daily) == 1500 # 500 + 1000 + assert sum(b["cache_read"] for b in daily) == 1200 # 400 + 800 + assert sum(b["cache_write"] for b in daily) == 500 # 200 + 300 + + +@pytest.mark.parametrize("chart_lib", ["highcharts", "uplot", "chartjs"]) +def test_render_chart_accepts_x_title_override(chart_lib): + """All three JS chart renderers must accept an x_title kwarg so the + instance dashboard can label the axis 'Day' instead of the default + 'Turn'. The 'none' renderer accepts x_title for API parity but is + exercised trivially below. + + We generate >_CHART_PAGE (60) points so the pagination header renders — + Chart.js only surfaces x_title in the pagination label, whereas + Highcharts and uPlot also embed it directly in the chart JS. + """ + # 61 synthetic turns → forces multi-page pagination so every renderer + # has an opportunity to emit the x_title string somewhere in its body. + turns = [ + {"timestamp": f"2026-04-{((i % 28) + 1):02d}T12:00:00Z", + "timestamp_fmt": f"2026-04-{((i % 28) + 1):02d}", + "input_tokens": 100 + i, "output_tokens": 50 + i, + "cache_read_tokens": 40, "cache_write_tokens": 20, + "total_tokens": 210 + 2 * i, "cost_usd": 0.001 * (i + 1), + "model": "claude-opus-4-7"} + for i in range(sm._CHART_PAGE + 1) # 61 points → 2 pages + ] + renderer = sm.CHART_RENDERERS[chart_lib] + body_turn, _ = renderer(turns) # default "Turn" + body_day, _ = renderer(turns, x_title="Day") + # The default body references "Turn" in its pagination header / labels + assert "Turn" in body_turn, ( + f"{chart_lib}: default x_title 'Turn' missing from body" + ) + # The overridden body must reference "Day" and not bleed through to 'Turn' + assert "Day" in body_day, ( + f"{chart_lib}: x_title override 'Day' absent from body" + ) + assert body_turn != body_day, ( + f"{chart_lib}: body unchanged when x_title overridden" + ) + + +def test_render_chart_none_accepts_x_title(): + """The 'none' renderer ignores x_title but must not raise on it.""" + out = sm._render_chart_none([], x_title="Day") + assert out == ("", "") + + +def test_render_html_instance_chart_uses_day_axis_label(instance_env): + """End-to-end: instance HTML chart section must label the axis as + 'Day' (not 'Turn'), matching the 'one point per day' semantics.""" + tmp_path, projects_dir = instance_env + _make_instance_fixture(projects_dir, { + "-home-user-alpha": [{"id": "a1", "turns": [ + {"model": "claude-opus-4-7", "in": 1000, "out": 500, + "cache_read": 400, "cache_write": 200}]}], + "-home-user-beta": [{"id": "b1", "turns": [ + {"model": "claude-sonnet-4-7", "in": 2000, "out": 1000, + "cache_read": 800, "cache_write": 300}]}], + }) + sm._run_all_projects( + formats=["html"], tz_offset=0.0, tz_label="UTC", + use_cache=False, chart_lib="highcharts", + include_subagents=False, drilldown=False, + ) + run = next(iter( + (tmp_path / "exports" / "session-metrics" / "instance").iterdir())) + html = (run / "index.html").read_text(encoding="utf-8") + # Highcharts writes the axis label into a `var X_TITLE = '…';` + # line inside the chart IIFE — assert it reads 'Day'. + assert "var X_TITLE = 'Day'" in html, ( + "instance HTML chart x-axis label must be 'Day', not 'Turn'" + ) + # And the body must NOT mention 'Turns 1–60' pagination labels — + # the instance scope's pagination, when shown, should say 'Days'. + assert "Turns 1\u20131" not in html and "Turns 1-1" not in html, ( + "instance chart pagination header must say 'Days', not 'Turns'" + ) diff --git a/README-v2.md b/README-v2.md index 44d5397..344fb8f 100644 --- a/README-v2.md +++ b/README-v2.md @@ -776,7 +776,7 @@ Skills provide specialized capabilities. See [Agent Skills documentation](https: | **consult-zai** | Dual-AI consultation comparing z.ai GLM 4.7 and code-searcher | `/consult-zai "question"` or via Skill tool | | **consult-codex** | Dual-AI consultation comparing Codex GPT-5.2 and code-searcher | `/consult-codex "question"` or via Skill tool | | **ai-image-creator** | Generate PNG images using AI (multiple models including Gemini, FLUX.2, Riverflow, SeedDream, GPT-5 via OpenRouter/Cloudflare AI Gateway). Supports transparent backgrounds (`-t`), reference image editing (`-r`), image analysis and description (`--analyze`), per-project cost tracking (`--costs`), prompt enhancement patterns, and composite banner generation for multi-size logo banners via ImageMagick. Requires [setup](.claude/skills/ai-image-creator/references/setup-guide.md) | `/ai-image-creator` or via Skill tool | -| **session-metrics** | Parse Claude Code JSONL logs into per-turn token/cost/cache breakdowns with multi-format export (text/JSON/CSV/MD/HTML). Includes 5-hour session blocks with 7/14/30-day counters for weekly-cap tracking, weekly roll-up with percentage deltas, session duration + burn rate, hour-of-day bars, weekday × hour punchcard, and pluggable chart libraries via `--chart-lib {highcharts,uplot,chartjs,none}` (Highcharts default, uPlot/Chart.js MIT alternatives, all vendored + SHA-256 verified). Zero network at runtime, stdlib-only Python. | Auto-triggers on cost/usage questions or `uv run python .claude/skills/session-metrics/scripts/session-metrics.py` | +| **session-metrics** | Parse Claude Code JSONL logs into per-turn token/cost/cache breakdowns with multi-format export (text/JSON/CSV/MD/HTML). Includes 5-hour session blocks with 7/14/30-day counters for weekly-cap tracking, weekly roll-up with percentage deltas, session duration + burn rate, hour-of-day bars, weekday × hour punchcard, and pluggable chart libraries via `--chart-lib {highcharts,uplot,chartjs,none}` (Highcharts default, uPlot/Chart.js MIT alternatives, all vendored + SHA-256 verified). Instance-wide dashboard (`--all-projects`, v1.14.0+) rolls up every project under `~/.claude/projects/` into one dated export folder with per-project HTML drilldowns and a daily-cost timeline. Zero network at runtime, stdlib-only Python. | Auto-triggers on cost/usage questions or `uv run python .claude/skills/session-metrics/scripts/session-metrics.py` — also installable via `/plugin marketplace add centminmod/claude-plugins` + `/plugin install session-metrics@centminmod` | ### 5.3 Custom Slash Commands diff --git a/README-v3.md b/README-v3.md index 48ce90e..dfa2297 100644 --- a/README-v3.md +++ b/README-v3.md @@ -521,7 +521,7 @@ Skills provide specialized capabilities. See [official docs](https://docs.claude | **consult-zai** | Dual-AI consultation comparing z.ai GLM 4.7 and code-searcher responses | | **consult-codex** | Dual-AI consultation comparing Codex GPT-5.2 and code-searcher responses | | **ai-image-creator** | Generate PNG images using AI (Gemini, FLUX.2, Riverflow, SeedDream, GPT-5) with configurable aspect ratios and resolutions. Supports transparent backgrounds (`-t`), reference image editing (`-r`), image analysis/description (`--analyze`), cost tracking (`--costs`), prompt enhancement patterns, and composite banner generation for multi-size logo banners. Requires [setup](.claude/skills/ai-image-creator/references/setup-guide.md) | -| **session-metrics** | Parse Claude Code JSONL logs into per-turn token/cost/cache breakdowns. Multi-format export (text/JSON/CSV/MD/HTML), 5-hour session blocks with 7/14/30-day counters, weekly roll-up with percentage deltas, session duration + burn rate, hour-of-day + weekday punchcard, and pluggable chart libraries via `--chart-lib {highcharts,uplot,chartjs,none}`. Stdlib-only Python, zero network at runtime. | +| **session-metrics** | Parse Claude Code JSONL logs into per-turn token/cost/cache breakdowns. Multi-format export (text/JSON/CSV/MD/HTML), 5-hour session blocks with 7/14/30-day counters, weekly roll-up with percentage deltas, session duration + burn rate, hour-of-day + weekday punchcard, and pluggable chart libraries via `--chart-lib {highcharts,uplot,chartjs,none}`. Instance-wide dashboard (`--all-projects`, v1.14.0+) aggregates every project under `~/.claude/projects/` with per-project HTML drilldowns. Stdlib-only Python, zero network at runtime. Also installable via `/plugin install session-metrics@centminmod`. | ### Custom Subagents diff --git a/README-v4.md b/README-v4.md index 3a7f011..c41160e 100644 --- a/README-v4.md +++ b/README-v4.md @@ -888,7 +888,9 @@ All three libraries are vendored and SHA-256 verified. See `.claude/skills/sessi **Security**: CLI inputs (`--session`, `--slug`) and their env-var equivalents (`CLAUDE_SESSION_ID`, `CLAUDE_PROJECT_SLUG`, `CLAUDE_PROJECTS_DIR`) are validated against strict allowlists; path traversal is rejected; resolved file paths are asserted to live under `~/.claude/projects/` before any read. -**Usage**: Auto-triggers when you ask questions like "how much has this session cost?", "show me token usage", "session summary", or "cost so far". Manual: `uv run python .claude/skills/session-metrics/scripts/session-metrics.py [flags]`. +**Instance-wide dashboard** (v1.14.0+, `--all-projects`): aggregates every project under `~/.claude/projects/` into a single dated export folder (`exports/session-metrics/instance/YYYY-MM-DD-HHMMSS/`). Contains `index.html` (summary cards, daily-cost timeline stacked by tokens, projects breakdown table sorted by cost descending, aggregated models/weekly/hour-of-day/punchcard rollups) plus a `projects/.html` per project with the full per-turn drilldown, hyperlinked from the index. `--no-project-drilldown` skips drilldowns for a fast flat index; `--projects-dir /path` targets a non-default install (also honours `CLAUDE_PROJECTS_DIR`). + +**Usage**: Auto-triggers when you ask questions like "how much has this session cost?", "show me token usage", "session summary", "cost so far", or "how much have I spent across all my projects?". Manual: `uv run python .claude/skills/session-metrics/scripts/session-metrics.py [flags]`. Also installable as a Claude Code plugin: `/plugin marketplace add centminmod/claude-plugins` then `/plugin install session-metrics@centminmod`. --- diff --git a/README.md b/README.md index 46cd7e1..682d075 100644 --- a/README.md +++ b/README.md @@ -918,7 +918,8 @@ Claude Code now supports [Agent Skills](https://docs.claude.com/en/docs/claude-c * Hour-of-day 24-bucket bars + weekday × hour punchcard in your chosen timezone * Pluggable chart library via `--chart-lib {highcharts,uplot,chartjs,none}` — Highcharts default (vendored + SHA-256 verified, non-commercial licence); uPlot and Chart.js are MIT alternatives; `none` emits a JS-free detail page * Input validation and path-containment checks so `--session` / `--slug` / env vars can't escape `~/.claude/projects/` -* **Usage**: Auto-triggers when you ask questions like "how much has this session cost?", "show me token usage", or "session summary". Manual: `uv run python .claude/skills/session-metrics/scripts/session-metrics.py` + * Instance-wide dashboard (v1.14.0+) via `--all-projects` — aggregates every project under `~/.claude/projects/` into a single dated export folder (`exports/session-metrics/instance/YYYY-MM-DD-HHMMSS/`) with per-project HTML drilldowns, daily-cost timeline chart, and a projects breakdown table sorted by cost descending. Add `--no-project-drilldown` for a flat fast-path index; `--projects-dir /path` to target a secondary Claude Code install (also honours `CLAUDE_PROJECTS_DIR`) +* **Usage**: Auto-triggers when you ask questions like "how much has this session cost?", "show me token usage", or "session summary". Manual: `uv run python .claude/skills/session-metrics/scripts/session-metrics.py`. Install via marketplace: `/plugin marketplace add centminmod/claude-plugins` then `/plugin install session-metrics@centminmod` ## Claude Code Hooks From 9b5770df393f927badceea2d418a3810b495f03f Mon Sep 17 00:00:00 2001 From: George Liu Date: Wed, 22 Apr 2026 23:46:34 +1000 Subject: [PATCH 138/174] add GPT-5.4 Image 2 support to ai-image-creator skill --- .claude/skills/ai-image-creator/SKILL.md | 5 +++-- .../ai-image-creator/references/api-reference.md | 3 ++- .../ai-image-creator/scripts/generate-image.py | 14 ++++++++++++-- README-v2.md | 2 +- README-v3.md | 2 +- README-v4.md | 9 +++++---- README.md | 8 ++++---- 7 files changed, 28 insertions(+), 15 deletions(-) diff --git a/.claude/skills/ai-image-creator/SKILL.md b/.claude/skills/ai-image-creator/SKILL.md index 8e39838..19c5c60 100644 --- a/.claude/skills/ai-image-creator/SKILL.md +++ b/.claude/skills/ai-image-creator/SKILL.md @@ -1,10 +1,10 @@ --- name: ai-image-creator -description: Generate PNG images using AI (multiple models via OpenRouter including Gemini, FLUX.2, Riverflow, SeedDream, GPT-5 Image, proxied through Cloudflare AI Gateway BYOK). Also analyze/describe existing images using multimodal AI vision. Use when user asks to "generate an image", "create a PNG", "make an icon", "make it transparent", "describe this image", "analyze this image", "what's in this image", "explain this image", or needs AI-generated visual assets for the project. Supports model selection via keywords (gemini, riverflow, flux2, seedream, gpt5), configurable aspect ratios/resolutions, transparent backgrounds (-t), reference image editing (-r), image analysis (--analyze), and per-project cost tracking (--costs). +description: Generate PNG images using AI (multiple models via OpenRouter including Gemini, FLUX.2, Riverflow, SeedDream, GPT-5 Image, GPT-5.4 Image 2, proxied through Cloudflare AI Gateway BYOK). Also analyze/describe existing images using multimodal AI vision. Use when user asks to "generate an image", "create a PNG", "make an icon", "make it transparent", "describe this image", "analyze this image", "what's in this image", "explain this image", or needs AI-generated visual assets for the project. Supports model selection via keywords (gemini, riverflow, flux2, seedream, gpt5, gpt5.4), configurable aspect ratios/resolutions, transparent backgrounds (-t), reference image editing (-r), image analysis (--analyze), and per-project cost tracking (--costs). allowed-tools: Bash, Read, Write compatibility: Requires uv (Python runner) and network access. Environment variables for CF AI Gateway or direct API keys must be configured in shell profile (~/.zshrc on macOS, ~/.bashrc on Linux, or System Environment Variables on Windows). metadata: - tags: image-generation, ai, openrouter, cloudflare, gemini, flux2, riverflow, seedream, gpt5 + tags: image-generation, ai, openrouter, cloudflare, gemini, flux2, riverflow, seedream, gpt5, gpt54 --- # AI Image Creator @@ -22,6 +22,7 @@ When the user mentions a model keyword in their image request, use the correspon | `flux2` | [FLUX.2 Max](https://openrouter.ai/black-forest-labs/flux.2-max) | "flux2", "flux", "use flux" | | `seedream` | [ByteDance SeedDream 4.5](https://openrouter.ai/bytedance-seed/seedream-4.5) | "seedream", "use seedream" | | `gpt5` | [OpenAI GPT-5 Image](https://openrouter.ai/openai/gpt-5-image) | "gpt5", "gpt5 image", "use gpt5" | +| `gpt5.4` | [OpenAI GPT-5.4 Image 2](https://openrouter.ai/openai/gpt-5.4-image-2) | "gpt5.4", "gpt-5.4 image", "use gpt5.4" | ## Instructions diff --git a/.claude/skills/ai-image-creator/references/api-reference.md b/.claude/skills/ai-image-creator/references/api-reference.md index 9557e15..175e566 100644 --- a/.claude/skills/ai-image-creator/references/api-reference.md +++ b/.claude/skills/ai-image-creator/references/api-reference.md @@ -11,10 +11,11 @@ All models use the same OpenRouter `/v1/chat/completions` endpoint and response | `flux2` | [`black-forest-labs/flux.2-max`](https://openrouter.ai/black-forest-labs/flux.2-max) | `["image"]` | Image-only | | `seedream` | [`bytedance-seed/seedream-4.5`](https://openrouter.ai/bytedance-seed/seedream-4.5) | `["image"]` | Image-only | | `gpt5` | [`openai/gpt-5-image`](https://openrouter.ai/openai/gpt-5-image) | `["image", "text"]` | Multimodal | +| `gpt5.4` | [`openai/gpt-5.4-image-2`](https://openrouter.ai/openai/gpt-5.4-image-2) | `["image", "text"]` | Multimodal | **Important:** Image-only models MUST use `"modalities": ["image"]`. Using `["image", "text"]` may cause errors with these models. The script handles this automatically when using keywords. -**Reference image support:** Only multimodal models (gemini, gpt5) support image input for editing and style transfer. Image-only models (riverflow, flux2, seedream) do not accept reference images. +**Reference image support:** Only multimodal models (gemini, gpt5, gpt5.4) support image input for editing and style transfer. Image-only models (riverflow, flux2, seedream) do not accept reference images. --- diff --git a/.claude/skills/ai-image-creator/scripts/generate-image.py b/.claude/skills/ai-image-creator/scripts/generate-image.py index 1c61c74..beb3b20 100644 --- a/.claude/skills/ai-image-creator/scripts/generate-image.py +++ b/.claude/skills/ai-image-creator/scripts/generate-image.py @@ -71,6 +71,11 @@ "modalities": ["image", "text"], "description": "OpenAI GPT-5 Image — multimodal (text+image)", }, + "gpt5.4": { + "id": "openai/gpt-5.4-image-2", + "modalities": ["image", "text"], + "description": "OpenAI GPT-5.4 Image 2 — multimodal (text+image), 272K context", + }, } # Environment variable names (prefixed to avoid collisions) @@ -232,7 +237,7 @@ def parse_args() -> argparse.Namespace: parser.add_argument( "-m", "--model", default=None, - help="Model keyword (gemini, riverflow, flux2, seedream, gpt5) or full model ID", + help="Model keyword (gemini, riverflow, flux2, seedream, gpt5, gpt5.4) or full model ID", ) parser.add_argument( "-r", "--ref", @@ -971,7 +976,12 @@ def log_cost_entry( log.warning(f"Could not read {costs_path}, starting fresh") entries.append(entry) - costs_path.write_text(json.dumps(entries, indent=2) + "\n", encoding="utf-8") + # Atomic write: temp file + rename to prevent corruption on Ctrl-C + import tempfile as _tf + with _tf.NamedTemporaryFile("w", dir=str(costs_path.parent), delete=False, suffix=".tmp") as f: + f.write(json.dumps(entries, indent=2) + "\n") + tmp_path = Path(f.name) + tmp_path.replace(costs_path) log.info(f"Cost entry logged to {costs_path}") # Warn about .gitignore if applicable diff --git a/README-v2.md b/README-v2.md index 344fb8f..a3d818a 100644 --- a/README-v2.md +++ b/README-v2.md @@ -775,7 +775,7 @@ Skills provide specialized capabilities. See [Agent Skills documentation](https: | **claude-docs-consultant** | Selectively fetches official Claude Code documentation from docs.claude.com | Automatic when working on Claude Code features | | **consult-zai** | Dual-AI consultation comparing z.ai GLM 4.7 and code-searcher | `/consult-zai "question"` or via Skill tool | | **consult-codex** | Dual-AI consultation comparing Codex GPT-5.2 and code-searcher | `/consult-codex "question"` or via Skill tool | -| **ai-image-creator** | Generate PNG images using AI (multiple models including Gemini, FLUX.2, Riverflow, SeedDream, GPT-5 via OpenRouter/Cloudflare AI Gateway). Supports transparent backgrounds (`-t`), reference image editing (`-r`), image analysis and description (`--analyze`), per-project cost tracking (`--costs`), prompt enhancement patterns, and composite banner generation for multi-size logo banners via ImageMagick. Requires [setup](.claude/skills/ai-image-creator/references/setup-guide.md) | `/ai-image-creator` or via Skill tool | +| **ai-image-creator** | Generate PNG images using AI (multiple models including Gemini, FLUX.2, Riverflow, SeedDream, GPT-5, GPT-5.4 Image 2 via OpenRouter/Cloudflare AI Gateway). Supports transparent backgrounds (`-t`), reference image editing (`-r`), image analysis and description (`--analyze`), per-project cost tracking (`--costs`), prompt enhancement patterns, and composite banner generation for multi-size logo banners via ImageMagick. Requires [setup](.claude/skills/ai-image-creator/references/setup-guide.md) | `/ai-image-creator` or via Skill tool | | **session-metrics** | Parse Claude Code JSONL logs into per-turn token/cost/cache breakdowns with multi-format export (text/JSON/CSV/MD/HTML). Includes 5-hour session blocks with 7/14/30-day counters for weekly-cap tracking, weekly roll-up with percentage deltas, session duration + burn rate, hour-of-day bars, weekday × hour punchcard, and pluggable chart libraries via `--chart-lib {highcharts,uplot,chartjs,none}` (Highcharts default, uPlot/Chart.js MIT alternatives, all vendored + SHA-256 verified). Instance-wide dashboard (`--all-projects`, v1.14.0+) rolls up every project under `~/.claude/projects/` into one dated export folder with per-project HTML drilldowns and a daily-cost timeline. Zero network at runtime, stdlib-only Python. | Auto-triggers on cost/usage questions or `uv run python .claude/skills/session-metrics/scripts/session-metrics.py` — also installable via `/plugin marketplace add centminmod/claude-plugins` + `/plugin install session-metrics@centminmod` | ### 5.3 Custom Slash Commands diff --git a/README-v3.md b/README-v3.md index dfa2297..c99d2f7 100644 --- a/README-v3.md +++ b/README-v3.md @@ -520,7 +520,7 @@ Skills provide specialized capabilities. See [official docs](https://docs.claude | **claude-docs-consultant** | Selectively fetches official Claude Code documentation | | **consult-zai** | Dual-AI consultation comparing z.ai GLM 4.7 and code-searcher responses | | **consult-codex** | Dual-AI consultation comparing Codex GPT-5.2 and code-searcher responses | -| **ai-image-creator** | Generate PNG images using AI (Gemini, FLUX.2, Riverflow, SeedDream, GPT-5) with configurable aspect ratios and resolutions. Supports transparent backgrounds (`-t`), reference image editing (`-r`), image analysis/description (`--analyze`), cost tracking (`--costs`), prompt enhancement patterns, and composite banner generation for multi-size logo banners. Requires [setup](.claude/skills/ai-image-creator/references/setup-guide.md) | +| **ai-image-creator** | Generate PNG images using AI (Gemini, FLUX.2, Riverflow, SeedDream, GPT-5, GPT-5.4 Image 2) with configurable aspect ratios and resolutions. Supports transparent backgrounds (`-t`), reference image editing (`-r`), image analysis/description (`--analyze`), cost tracking (`--costs`), prompt enhancement patterns, and composite banner generation for multi-size logo banners. Requires [setup](.claude/skills/ai-image-creator/references/setup-guide.md) | | **session-metrics** | Parse Claude Code JSONL logs into per-turn token/cost/cache breakdowns. Multi-format export (text/JSON/CSV/MD/HTML), 5-hour session blocks with 7/14/30-day counters, weekly roll-up with percentage deltas, session duration + burn rate, hour-of-day + weekday punchcard, and pluggable chart libraries via `--chart-lib {highcharts,uplot,chartjs,none}`. Instance-wide dashboard (`--all-projects`, v1.14.0+) aggregates every project under `~/.claude/projects/` with per-project HTML drilldowns. Stdlib-only Python, zero network at runtime. Also installable via `/plugin install session-metrics@centminmod`. | ### Custom Subagents diff --git a/README-v4.md b/README-v4.md index c41160e..c52323b 100644 --- a/README-v4.md +++ b/README-v4.md @@ -809,7 +809,7 @@ Skills are defined in `.claude/skills/` directories containing: #### ai-image-creator -**Purpose**: Generate PNG images using AI (multiple models via OpenRouter including Gemini, FLUX.2, Riverflow, SeedDream, GPT-5 Image, proxied through Cloudflare AI Gateway BYOK). +**Purpose**: Generate PNG images using AI (multiple models via OpenRouter including Gemini, FLUX.2, Riverflow, SeedDream, GPT-5 Image, GPT-5.4 Image 2, proxied through Cloudflare AI Gateway BYOK). **Setup**: Requires API credentials and optional Cloudflare AI Gateway configuration before use. See [setup guide](.claude/skills/ai-image-creator/references/setup-guide.md). @@ -822,6 +822,7 @@ Skills are defined in `.claude/skills/` directories containing: | `flux2` | FLUX.2 Max | | `seedream` | ByteDance SeedDream 4.5 | | `gpt5` | OpenAI GPT-5 Image | +| `gpt5.4` | OpenAI GPT-5.4 Image 2 (272K context) | **Providers**: - OpenRouter (recommended, pay-as-you-go) @@ -834,8 +835,8 @@ Skills are defined in `.claude/skills/` directories containing: - Image sizes: 0.5K, 1K (default), 2K, 4K - Automatic fallback from gateway to direct API - Transparent background generation (`-t`) with green-screen chroma key pipeline -- Reference image editing/style transfer (`-r`) for multimodal models (gemini, gpt5) -- Image analysis/description (`--analyze`) — text-only output; no image generated. Multimodal models only (gemini, gpt5) +- Reference image editing/style transfer (`-r`) for multimodal models (gemini, gpt5, gpt5.4) +- Image analysis/description (`--analyze`) — text-only output; no image generated. Multimodal models only (gemini, gpt5, gpt5.4) - Per-project cost tracking (`--costs`) with per-model breakdown - Prompt enhancement with 11 category-specific professional patterns - Composite banners for multi-size logo banners via ImageMagick (no API calls needed) @@ -844,7 +845,7 @@ Skills are defined in `.claude/skills/` directories containing: **Composite Banners**: Generate consistent logo banners across multiple sizes from a JSON config using ImageMagick. Use when the user has an existing logo and wants multi-size branded banners (not creative/artistic designs). Quick start: `--init` to scaffold config, `--validate` to check, then generate. See [composite reference](.claude/skills/ai-image-creator/references/composite-reference.md) for full config schema. -**Image Analysis**: Describe, analyze, or explain existing images using multimodal AI vision (`--analyze`). Returns text-only JSON output — no image generated. Pass `-r` with the image file and optionally `-p` with a custom prompt. Multimodal models only (gemini, gpt5). Example: `--analyze -r photo.png -p "What text is visible?"`. +**Image Analysis**: Describe, analyze, or explain existing images using multimodal AI vision (`--analyze`). Returns text-only JSON output — no image generated. Pass `-r` with the image file and optionally `-p` with a custom prompt. Multimodal models only (gemini, gpt5, gpt5.4). Example: `--analyze -r photo.png -p "What text is visible?"`. **Usage**: `/ai-image-creator` or invoke via Skill tool when user asks to generate images, create PNGs, make visual assets, or describe/analyze existing images. diff --git a/README.md b/README.md index 682d075..79cd12d 100644 --- a/README.md +++ b/README.md @@ -886,16 +886,16 @@ Claude Code now supports [Agent Skills](https://docs.claude.com/en/docs/claude-c ### ai-image-creator -* **Purpose**: Generate PNG images using AI (multiple models via OpenRouter including Gemini, FLUX.2, Riverflow, SeedDream, GPT-5 Image, proxied through Cloudflare AI Gateway BYOK) +* **Purpose**: Generate PNG images using AI (multiple models via OpenRouter including Gemini, FLUX.2, Riverflow, SeedDream, GPT-5 Image, GPT-5.4 Image 2, proxied through Cloudflare AI Gateway BYOK) * **Location**: `.claude/skills/ai-image-creator/` * **Key Features**: - * Model selection via keywords: gemini (default), riverflow, flux2, seedream, gpt5 + * Model selection via keywords: gemini (default), riverflow, flux2, seedream, gpt5, gpt5.4 * Supports configurable aspect ratios (1:1, 16:9, 9:16, 3:2, 4:3, etc.) and image sizes (0.5K to 4K) * Multiple providers: OpenRouter (recommended), Google AI Studio, Cloudflare AI Gateway BYOK * Automatic fallback from gateway to direct API * Transparent background generation (`-t`) with green-screen chroma key pipeline - * Reference image editing/style transfer (`-r`) for multimodal models (gemini, gpt5) - * Image analysis/description (`--analyze`) — text-only output from multimodal models (gemini, gpt5); no image generated + * Reference image editing/style transfer (`-r`) for multimodal models (gemini, gpt5, gpt5.4) + * Image analysis/description (`--analyze`) — text-only output from multimodal models (gemini, gpt5, gpt5.4); no image generated * Per-project cost tracking (`--costs`) with per-model breakdown * Prompt enhancement with 11 category-specific professional patterns (product hero, social media, marketing banners, etc.) * Composite banners for multi-size logo banners via ImageMagick — no API calls needed From 7c1224769738b2537b0fa22ac8a68dfe690fe196 Mon Sep 17 00:00:00 2001 From: George Liu Date: Sat, 25 Apr 2026 06:24:42 +1000 Subject: [PATCH 139/174] session-metrics: sync to dev v1.15.0 4-theme picker (Beacon/Console/Lattice/Pulse) embedded in every HTML export. Theme persists via URL hash with localStorage fallback. Chart layout rationalised per variant: dashboard=none, detail=chartrail, single=Highcharts+chartrail, instance=daily cost rail. Switcher placed inline in topbar nav; 25% global font size increase via zoom:1.25. --- .../scripts/session-metrics.py | 1971 ++++++++++++----- .../tests/test_session_metrics.py | 60 +- 2 files changed, 1412 insertions(+), 619 deletions(-) diff --git a/.claude/skills/session-metrics/scripts/session-metrics.py b/.claude/skills/session-metrics/scripts/session-metrics.py index 38931b8..a54370d 100644 --- a/.claude/skills/session-metrics/scripts/session-metrics.py +++ b/.claude/skills/session-metrics/scripts/session-metrics.py @@ -2858,40 +2858,28 @@ def fmt_local(epoch: int) -> str: for s, st in rows_data: sid = s["session_id"][:8] rows_html.append( - f'{sid}\u2026' - f'{fmt_local(st["first_epoch"])}' - f'{_fmt_duration(st["wall_sec"])}' - f'{st["turns"]:,}' - f'${s["subtotal"]["cost"]:.3f}' - f'{st["tokens_per_min"]:,.0f}' - f'${st["cost_per_min"]:.3f}' + f'{sid}\u2026' + f'{fmt_local(st["first_epoch"])}' + f'{_fmt_duration(st["wall_sec"])}' + f'{st["turns"]:,}' + f'${s["subtotal"]["cost"]:.3f}' + f'{st["tokens_per_min"]:,.0f}' + f'${st["cost_per_min"]:.3f}' ) - return f"""\ -
    -
    Session duration \u2014 newest first
    - - - - - - - - - - - - - {"".join(rows_html)} -
    SessionFirst turn ({tz_label})WallTurnsCosttok/min$/min
    -
    """ + return ( + f'
    \n' + f'

    Session duration

    ' + f'top 10 by wall time ({tz_label})
    \n' + f'
    \n' + f' \n' + f' \n' + f' ' + f'' + f'\n' + f' \n' + f' {"".join(rows_html)}\n' + f'
    SessionFirst turn ({tz_label})WallTurnsCosttok/min$/min
    \n
    \n
    ' + ) def _fmt_delta_pct(cur: float, prev: float) -> tuple[str, str]: @@ -2931,33 +2919,25 @@ def _build_weekly_rollup_html(rollup: dict) -> str: for label, cur_s, prev_s, cur_v, prev_v in metrics: delta, color = _fmt_delta_pct(cur_v, prev_v) rows.append( - f'{label}' - f'{cur_s}' - f'{prev_s}' - f'{delta}' + f'{label}' + f'{cur_s}' + f'{prev_s}' + f'{delta}' ) - return f"""\ -
    -
    Weekly roll-up
    - - - - - - - - - - {"".join(rows)} -
    MetricLast 7dPrior 7d\u0394
    -
    """ + return ( + '
    \n' + '

    Weekly rollup

    ' + 'trailing 7d vs prior 7d
    \n' + '
    \n' + ' \n' + ' ' + '' + '' + '\n' + f' {"".join(rows)}\n' + '
    MetricLast 7dPrior 7d\u0394
    \n
    \n
    ' + ) def _build_session_blocks_html( @@ -2984,62 +2964,42 @@ def fmt_local(epoch: int) -> str: s30 = summary.get("trailing_30", 0) tot = summary.get("total", len(blocks)) recent = list(reversed(blocks[-12:])) - rows = "".join( - f'{fmt_local(b["anchor_epoch"])}' - f'{b["elapsed_min"]:.0f}m' - f'{b["turn_count"]:,}' - f'{b["user_msg_count"]:,}' - f'${b["cost_usd"]:.3f}' - f'{len(b["sessions_touched"])}' + + # Determine max cost for the block-row bars (preview .block-row pattern) + max_cost = max((b["cost_usd"] for b in recent), default=0.0) or 1.0 + block_rows = "".join( + f'
    ' + f'{fmt_local(b["anchor_epoch"])}' + f'
    ' + f'${b["cost_usd"]:.3f}' + f'{b["turn_count"]:,} turns' + f'
    ' for b in recent ) - def card(label: str, value: str, hint: str = "") -> str: - hint_html = (f'' - f'{hint}') if hint else "" - return ( - f'
    ' - f'
    {label}
    ' - f'
    {value}{hint_html}
    ' - ) + # Kpi-style stat cards for the trailing-window counts + stat_card = lambda label, value: ( + f'
    ' + f'
    {label}
    ' + f'
    {value}
    ' + ) - return f"""\ -
    -
    5-hour session blocks
    -
    - {card("Last 7 days", f"{s7}")} - {card("Last 14 days", f"{s14}")} - {card("Last 30 days", f"{s30}")} - {card("All time", f"{tot}")} -
    -
    - Recent blocks ({tz_label}) \u2014 a new block starts 5h after the previous anchor. -
    - - - - - - - - - - - - {rows} -
    AnchorDurationTurnsPromptsCostSessions
    -
    """ + return ( + '
    \n' + '

    5-hour session blocks

    ' + f'recent blocks · {tz_label}
    \n' + '
    \n' + '
    \n' + f' {stat_card("Last 7 days", s7)}\n' + f' {stat_card("Last 14 days", s14)}\n' + f' {stat_card("Last 30 days", s30)}\n' + f' {stat_card("All time", tot)}\n' + '
    \n' + f' {block_rows}\n' + '
    \n
    ' + ) def _build_hour_of_day_html(tod: dict, tz_label: str = "UTC", @@ -3078,19 +3038,20 @@ def _build_hour_of_day_html(tod: dict, tz_label: str = "UTC", ) return f"""\ -
    +
    +

    Hour of day

    + user messages
    +
    - Hour of day - - Peak: - - + + Peak: + - {peak_legend}
    -
    +
    @@ -3100,11 +3061,11 @@ def _build_hour_of_day_html(tod: dict, tz_label: str = "UTC",
    -
    +
    {"".join(f'
    {h:02d}
    ' for h in range(24))}
    -
    +
    +
    ' + ) + + +def _theme_bootstrap_body_js() -> str: + """End-of-body script: applies the theme class to , wires the + switcher buttons, persists to ``localStorage`` wrapped in try/catch + (Firefox ``privacy.file_unique_origin=true`` throws ``SecurityError`` + on ``file://``), and rewrites any ``a[data-sm-nav]`` href with the + current ``#theme=`` so cross-file nav preserves the picked theme. + + Also re-skins accent-color-bearing chart libraries when possible — + current strategy: reload with the hash preserved. uPlot/Highcharts + have no cheap post-init accent API so a reload is the simplest + correct answer, and the hash makes it seamless. + """ + return ( + '' + ) + + +def _build_chartrail_section_html(chartrail_data: list) -> str: + """Return the chartrail section HTML for a given list of turn dicts. + + Returns an empty string if ``chartrail_data`` is empty. + """ + if not chartrail_data: + return "" + rail_json = json.dumps(chartrail_data, separators=(",", ":"), + default=str).replace("\n' + '

    Token usage over time

    ' + 'scroll horizontally · click a turn ' + 'to drill in · \u2190 \u2192
    \n' + '
    \n' + '
    \n' + ' Input (new)\n' + ' Output\n' + ' Cache write\n' + ' Cache read\n' + ' Cost $\n' + '
    \n' + '
    \n' + '
    \n' + '
    \n' + '
    ' + '
    \n' + '
    \n' + ' \n' + ' \n' + '
    \n' + '
    \n' + f' 01 / {n_turns}\n' + '
    ' + '
    ' + '
    \n' + ' scroll or use \u2190 \u2192\n' + '
    \n' + '
    \n' + '\n' + '' + ) + + +def _chartrail_script() -> str: + """Return the full chartrail interaction JS string.""" + return """""" + + +def _build_daily_cost_rail_html(daily_data: list) -> str: + """Return a horizontally-scrollable daily-cost rail for the instance page. + + Each column is one calendar day; bar height is proportional to cost. + Reuses ``.chartrail-card`` CSS layout; DOM IDs use the ``costail-`` + prefix so the element names don't clash with the per-session chartrail. + + Returns ``""`` if ``daily_data`` is empty. + """ + if not daily_data: + return "" + rail_json = json.dumps( + [{"n": i, "date": d.get("date", ""), "cost": float(d.get("cost", 0.0))} + for i, d in enumerate(daily_data, 1)], + separators=(",", ":"), + ).replace("\n' + '

    Daily cost timeline

    ' + 'one bar per calendar day · ' + 'scroll horizontally · \u2190 \u2192
    \n' + '
    \n' + '
    \n' + '
    \n' + '
    \n' + '
    \n' + '
    \n' + ' \n' + ' \n' + '
    \n' + '
    \n' + f' 01 / {n_days} days\n' + '
    ' + '
    \n' + ' scroll or use \u2190 \u2192\n' + '
    \n' + '
    \n' + '\n' + '' + ) + + +def _daily_cost_rail_script() -> str: + """Interaction JS for the daily-cost rail (costail). + + Renders one bar per calendar day whose height is proportional to cost. + Y-axis ticks show dollar amounts. Wires chevrons, keyboard, and wheel + scroll — identical UX to the per-session chartrail. + """ + return """""" + + def render_html(report: dict, variant: str = "single", nav_sibling: str | None = None, chart_lib: str = "highcharts") -> str: @@ -4154,6 +5036,7 @@ def render_html(report: dict, variant: str = "single", return _render_instance_html(report, chart_lib=chart_lib) include_insights = variant in ("single", "dashboard") include_chart = variant in ("single", "detail") + include_hc_chart = variant == "single" # Highcharts 3D for single only; detail uses chartrail slug = report["slug"] totals = report["totals"] mode = report["mode"] @@ -4168,7 +5051,7 @@ def render_html(report: dict, variant: str = "single", # ```` while the container div goes in the body. chart_html = "" chart_head_html = "" - if include_chart: + if include_hc_chart: if mode == "project": all_turns = [t for s in sessions for t in s["turns"]] else: @@ -4373,24 +5256,42 @@ def _model_row_html(m: str, cnt: int) -> str: for m, cnt in sorted(report["models"].items(), key=lambda x: -x[1]) ) - # Nav bar: cross-link to the companion page (only present in split mode). - nav_html = "" + # Nav bar: cross-link to the companion page. + # Switcher is embedded inside the topbar's
    ' ) thinking_card = "" if totals.get("thinking_turn_count", 0) > 0: @@ -4470,13 +5376,13 @@ def _model_row_html(m: str, cnt: int) -> str: blocks = (totals.get("content_blocks") or {}).get("thinking", 0) total_turns = totals.get("turns", 0) thinking_card = ( - f'\n
    ' - f'
    {tp:.0f}% · {blocks} blocks
    ' - f'
    Extended thinking engagement ' - f'({tn} of {total_turns} turns)
    ' + f'
    Extended thinking engagement ' + f'({tn} of {total_turns} turns)
    ' + f'
    {tp:.0f}% · {blocks} blocks
    ' ) tool_calls_card = "" if totals.get("tool_call_total", 0) > 0: @@ -4487,9 +5393,9 @@ def _model_row_html(m: str, cnt: int) -> str: # in a compromised transcript — escape each before interpolating. top3_str = ", ".join(html_mod.escape(n) for n in top3) if top3 else "none" tool_calls_card = ( - f'\n
    ' - f'
    {tc} · {avg:.1f}/turn
    ' - f'
    Tool calls · top: {top3_str}
    ' + f'\n
    ' + f'
    Tool calls · top: {top3_str}
    ' + f'
    {tc} · {avg:.1f}/turn
    ' ) resumes_card = "" resumes_list = report.get("resumes") or [] @@ -4507,26 +5413,26 @@ def _model_row_html(m: str, cnt: int) -> str: if n_terminal != 1: terminal_note += "s" resumes_card = ( - f'\n
    ' - f'
    ↺ {n_resumes} detected
    ' - f'
    ' + f'
    ' f'Session resumes' f'{(" · " + times_str) if times_str else ""}' f'{terminal_note}' - f'
    ' + f'
    ' + f'
    ↺ {n_resumes} detected
    ' ) summary_cards_html = f'''\ -
    -
    ${totals['cost']:.4f}
    Total cost (USD)
    -
    ${totals['cache_savings']:.4f}
    Cache savings
    -
    {totals['cache_hit_pct']:.1f}%
    Cache hit ratio
    -
    {totals['total_input']:,}
    Total input tokens
    -
    {totals['input']:,}
    Input tokens (new)
    -
    {totals['output']:,}
    Output tokens
    -
    {totals['cache_read']:,}
    Cache read tokens
    -
    {totals['cache_write']:,}
    Cache write tokens
    {ttl_mix_card}{thinking_card}{tool_calls_card}{resumes_card} +
    +
    Total cost (USD)
    ${totals['cost']:.4f}
    +
    Cache savings
    ${totals['cache_savings']:.4f}
    +
    Cache hit ratio
    {totals['cache_hit_pct']:.1f}%
    +
    Total input tokens
    {totals['total_input']:,}
    +
    Input tokens (new)
    {totals['input']:,}
    +
    Output tokens
    {totals['output']:,}
    +
    Cache read tokens
    {totals['cache_read']:,}
    +
    Cache write tokens
    {totals['cache_write']:,}
    {ttl_mix_card}{thinking_card}{tool_calls_card}{resumes_card}
    ''' # Usage Insights panel — sits between the summary cards and the @@ -4559,13 +5465,40 @@ def _model_row_html(m: str, cnt: int) -> str: turn_drawer_html = "" prompts_section_html = "" drawer_script_html = "" + chartrail_section_html = "" if include_chart: turn_data: dict[str, dict] = {} prompts_rows: list[dict] = [] + # Chart-rail data — one row per turn in document order. + # Resume markers are rendered as a distinct column (.tcol.resume) rather + # than a full stacked bar; they don't enter turn_data (no drawer). + chartrail_data: list[dict] = [] for s in sessions: sid8 = s["session_id"][:8] + sess_label = f'{sid8} · {s.get("first_ts", "")}' + first_in_session = True for t in s["turns"]: if t.get("is_resume_marker"): + chartrail_data.append({ + "n": t["index"], + "key": "", + "ts": t.get("timestamp_fmt", ""), + "time": (t.get("timestamp_fmt", "").split(" ") + [-1][:5]), + "model": "", + "input": 0, + "output": 0, + "cache_read": 0, + "cache_write": 0, + "total": 0, + "cost": 0.0, + "session_id": sid8, + "session_label": sess_label, + "session_break": first_in_session, + "is_resume": True, + "is_terminal": bool(t.get("is_terminal_exit_marker")), + }) + first_in_session = False continue key = f'{sid8}-{t["index"]}' turn_data[key] = { @@ -4587,6 +5520,26 @@ def _model_row_html(m: str, cnt: int) -> str: "assistant_snippet": t.get("assistant_snippet", ""), "assistant_text": t.get("assistant_text", ""), } + chartrail_data.append({ + "n": t["index"], + "key": key, + "ts": t.get("timestamp_fmt", ""), + "time": (t.get("timestamp_fmt", "").split(" ") + [-1][:5]), + "model": t.get("model", ""), + "input": t.get("input_tokens", 0), + "output": t.get("output_tokens", 0), + "cache_read": t.get("cache_read_tokens", 0), + "cache_write": t.get("cache_write_tokens", 0), + "total": t.get("total_tokens", 0), + "cost": t.get("cost_usd", 0.0), + "session_id": sid8, + "session_label": sess_label, + "session_break": first_in_session, + "is_resume": False, + "is_terminal": False, + }) + first_in_session = False if t.get("prompt_text"): prompts_rows.append({ "key": key, @@ -4607,49 +5560,64 @@ def _model_row_html(m: str, cnt: int) -> str: f'' ) - turn_drawer_html = ''' -