Compare commits
15 Commits
ai/issue-1
...
ai/issue-2
| Author | SHA1 | Date | |
|---|---|---|---|
| bb4b3c4553 | |||
|
|
ba84e10525 | ||
| 9d9738b2b4 | |||
| ce03b0bfb9 | |||
|
|
ed0b9af00b | ||
| 9c6f59f937 | |||
| 5cd468ed24 | |||
|
|
4a5b17c77c | ||
| 67ca4b0210 | |||
| ff4090412c | |||
| 445e97f2f8 | |||
| dc6a04df8a | |||
| 0799dec5b3 | |||
|
|
8378e9b3e7 | ||
|
|
7d19a22a4b |
440
.agents/skills/accessibility/SKILL.md
Normal file
440
.agents/skills/accessibility/SKILL.md
Normal file
@@ -0,0 +1,440 @@
|
|||||||
|
---
|
||||||
|
name: accessibility
|
||||||
|
description: Audit and improve web accessibility following WCAG 2.2 guidelines. Use when asked to "improve accessibility", "a11y audit", "WCAG compliance", "screen reader support", "keyboard navigation", or "make accessible".
|
||||||
|
license: MIT
|
||||||
|
metadata:
|
||||||
|
author: web-quality-skills
|
||||||
|
version: "1.1"
|
||||||
|
---
|
||||||
|
|
||||||
|
# Accessibility (a11y)
|
||||||
|
|
||||||
|
Comprehensive accessibility guidelines based on WCAG 2.2 and Lighthouse accessibility audits. Goal: make content usable by everyone, including people with disabilities.
|
||||||
|
|
||||||
|
## WCAG Principles: POUR
|
||||||
|
|
||||||
|
| Principle | Description |
|
||||||
|
|-----------|-------------|
|
||||||
|
| **P**erceivable | Content can be perceived through different senses |
|
||||||
|
| **O**perable | Interface can be operated by all users |
|
||||||
|
| **U**nderstandable | Content and interface are understandable |
|
||||||
|
| **R**obust | Content works with assistive technologies |
|
||||||
|
|
||||||
|
## Conformance levels
|
||||||
|
|
||||||
|
| Level | Requirement | Target |
|
||||||
|
|-------|-------------|--------|
|
||||||
|
| **A** | Minimum accessibility | Must pass |
|
||||||
|
| **AA** | Standard compliance | Should pass (legal requirement in many jurisdictions) |
|
||||||
|
| **AAA** | Enhanced accessibility | Nice to have |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Perceivable
|
||||||
|
|
||||||
|
### Text alternatives (1.1)
|
||||||
|
|
||||||
|
**Images require alt text:**
|
||||||
|
```html
|
||||||
|
<!-- ❌ Missing alt -->
|
||||||
|
<img src="chart.png">
|
||||||
|
|
||||||
|
<!-- ✅ Descriptive alt -->
|
||||||
|
<img src="chart.png" alt="Bar chart showing 40% increase in Q3 sales">
|
||||||
|
|
||||||
|
<!-- ✅ Decorative image (empty alt) -->
|
||||||
|
<img src="decorative-border.png" alt="" role="presentation">
|
||||||
|
|
||||||
|
<!-- ✅ Complex image with longer description -->
|
||||||
|
<figure>
|
||||||
|
<img src="infographic.png" alt="2024 market trends infographic"
|
||||||
|
aria-describedby="infographic-desc">
|
||||||
|
<figcaption id="infographic-desc">
|
||||||
|
<!-- Detailed description -->
|
||||||
|
</figcaption>
|
||||||
|
</figure>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Icon buttons need accessible names:**
|
||||||
|
```html
|
||||||
|
<!-- ❌ No accessible name -->
|
||||||
|
<button><svg><!-- menu icon --></svg></button>
|
||||||
|
|
||||||
|
<!-- ✅ Using aria-label -->
|
||||||
|
<button aria-label="Open menu">
|
||||||
|
<svg aria-hidden="true"><!-- menu icon --></svg>
|
||||||
|
</button>
|
||||||
|
|
||||||
|
<!-- ✅ Using visually hidden text -->
|
||||||
|
<button>
|
||||||
|
<svg aria-hidden="true"><!-- menu icon --></svg>
|
||||||
|
<span class="visually-hidden">Open menu</span>
|
||||||
|
</button>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Visually hidden class:**
|
||||||
|
```css
|
||||||
|
.visually-hidden {
|
||||||
|
position: absolute;
|
||||||
|
width: 1px;
|
||||||
|
height: 1px;
|
||||||
|
padding: 0;
|
||||||
|
margin: -1px;
|
||||||
|
overflow: hidden;
|
||||||
|
clip: rect(0, 0, 0, 0);
|
||||||
|
white-space: nowrap;
|
||||||
|
border: 0;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Color contrast (1.4.3, 1.4.6)
|
||||||
|
|
||||||
|
| Text Size | AA minimum | AAA enhanced |
|
||||||
|
|-----------|------------|--------------|
|
||||||
|
| Normal text (< 18px / < 14px bold) | 4.5:1 | 7:1 |
|
||||||
|
| Large text (≥ 18px / ≥ 14px bold) | 3:1 | 4.5:1 |
|
||||||
|
| UI components & graphics | 3:1 | 3:1 |
|
||||||
|
|
||||||
|
```css
|
||||||
|
/* ❌ Low contrast (2.5:1) */
|
||||||
|
.low-contrast {
|
||||||
|
color: #999;
|
||||||
|
background: #fff;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* ✅ Sufficient contrast (7:1) */
|
||||||
|
.high-contrast {
|
||||||
|
color: #333;
|
||||||
|
background: #fff;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* ✅ Focus states need contrast too */
|
||||||
|
:focus-visible {
|
||||||
|
outline: 2px solid #005fcc;
|
||||||
|
outline-offset: 2px;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Don't rely on color alone:**
|
||||||
|
```html
|
||||||
|
<!-- ❌ Only color indicates error -->
|
||||||
|
<input class="error-border">
|
||||||
|
<style>.error-border { border-color: red; }</style>
|
||||||
|
|
||||||
|
<!-- ✅ Color + icon + text -->
|
||||||
|
<div class="field-error">
|
||||||
|
<input aria-invalid="true" aria-describedby="email-error">
|
||||||
|
<span id="email-error" class="error-message">
|
||||||
|
<svg aria-hidden="true"><!-- error icon --></svg>
|
||||||
|
Please enter a valid email address
|
||||||
|
</span>
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Media alternatives (1.2)
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- Video with captions -->
|
||||||
|
<video controls>
|
||||||
|
<source src="video.mp4" type="video/mp4">
|
||||||
|
<track kind="captions" src="captions.vtt" srclang="en" label="English" default>
|
||||||
|
<track kind="descriptions" src="descriptions.vtt" srclang="en" label="Descriptions">
|
||||||
|
</video>
|
||||||
|
|
||||||
|
<!-- Audio with transcript -->
|
||||||
|
<audio controls>
|
||||||
|
<source src="podcast.mp3" type="audio/mp3">
|
||||||
|
</audio>
|
||||||
|
<details>
|
||||||
|
<summary>Transcript</summary>
|
||||||
|
<p>Full transcript text...</p>
|
||||||
|
</details>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Operable
|
||||||
|
|
||||||
|
### Keyboard accessible (2.1)
|
||||||
|
|
||||||
|
**All functionality must be keyboard accessible:**
|
||||||
|
```javascript
|
||||||
|
// ❌ Only handles click
|
||||||
|
element.addEventListener('click', handleAction);
|
||||||
|
|
||||||
|
// ✅ Handles both click and keyboard
|
||||||
|
element.addEventListener('click', handleAction);
|
||||||
|
element.addEventListener('keydown', (e) => {
|
||||||
|
if (e.key === 'Enter' || e.key === ' ') {
|
||||||
|
e.preventDefault();
|
||||||
|
handleAction();
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
**No keyboard traps.** Users must be able to Tab into and out of every component. Use the [modal focus trap pattern](references/A11Y-PATTERNS.md#modal-focus-trap) for dialogs—the native `<dialog>` element handles this automatically.
|
||||||
|
|
||||||
|
### Focus visible (2.4.7)
|
||||||
|
|
||||||
|
```css
|
||||||
|
/* ❌ Never remove focus outlines */
|
||||||
|
*:focus { outline: none; }
|
||||||
|
|
||||||
|
/* ✅ Use :focus-visible for keyboard-only focus */
|
||||||
|
:focus {
|
||||||
|
outline: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
:focus-visible {
|
||||||
|
outline: 2px solid #005fcc;
|
||||||
|
outline-offset: 2px;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* ✅ Or custom focus styles */
|
||||||
|
button:focus-visible {
|
||||||
|
box-shadow: 0 0 0 3px rgba(0, 95, 204, 0.5);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Focus not obscured (2.4.11) — new in 2.2
|
||||||
|
|
||||||
|
When an element receives keyboard focus, it must not be entirely hidden by other author-created content such as sticky headers, footers, or overlapping panels. At Level AAA (2.4.12), no part of the focused element may be hidden.
|
||||||
|
|
||||||
|
```css
|
||||||
|
/* ✅ Account for sticky headers when scrolling to focused elements */
|
||||||
|
:target {
|
||||||
|
scroll-margin-top: 80px;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* ✅ Ensure focused items clear fixed/sticky bars */
|
||||||
|
:focus {
|
||||||
|
scroll-margin-top: 80px;
|
||||||
|
scroll-margin-bottom: 60px;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Skip links (2.4.1)
|
||||||
|
|
||||||
|
Provide a skip link so keyboard users can bypass repetitive navigation. See the [skip link pattern](references/A11Y-PATTERNS.md#skip-link) for full markup and styles.
|
||||||
|
|
||||||
|
### Target size (2.5.8) — new in 2.2
|
||||||
|
|
||||||
|
Interactive targets must be at least **24 × 24 CSS pixels** (AA). Exceptions: inline text links, elements where the browser controls the size, and targets where a 24px circle centered on the bounding box does not overlap another target.
|
||||||
|
|
||||||
|
```css
|
||||||
|
/* ✅ Minimum target size */
|
||||||
|
button,
|
||||||
|
[role="button"],
|
||||||
|
input[type="checkbox"] + label,
|
||||||
|
input[type="radio"] + label {
|
||||||
|
min-width: 24px;
|
||||||
|
min-height: 24px;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* ✅ Comfortable target size (recommended 44×44) */
|
||||||
|
.touch-target {
|
||||||
|
min-width: 44px;
|
||||||
|
min-height: 44px;
|
||||||
|
display: inline-flex;
|
||||||
|
align-items: center;
|
||||||
|
justify-content: center;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Dragging movements (2.5.7) — new in 2.2
|
||||||
|
|
||||||
|
Any action that requires dragging must have a single-pointer alternative (e.g., buttons, inputs). See the [dragging movements pattern](references/A11Y-PATTERNS.md#dragging-movements) for a sortable-list example.
|
||||||
|
|
||||||
|
### Timing (2.2)
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// Allow users to extend time limits
|
||||||
|
function showSessionWarning() {
|
||||||
|
const modal = createModal({
|
||||||
|
title: 'Session Expiring',
|
||||||
|
content: 'Your session will expire in 2 minutes.',
|
||||||
|
actions: [
|
||||||
|
{ label: 'Extend session', action: extendSession },
|
||||||
|
{ label: 'Log out', action: logout }
|
||||||
|
],
|
||||||
|
timeout: 120000
|
||||||
|
});
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Motion (2.3)
|
||||||
|
|
||||||
|
```css
|
||||||
|
/* Respect reduced motion preference */
|
||||||
|
@media (prefers-reduced-motion: reduce) {
|
||||||
|
*,
|
||||||
|
*::before,
|
||||||
|
*::after {
|
||||||
|
animation-duration: 0.01ms !important;
|
||||||
|
animation-iteration-count: 1 !important;
|
||||||
|
transition-duration: 0.01ms !important;
|
||||||
|
scroll-behavior: auto !important;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Understandable
|
||||||
|
|
||||||
|
### Page language (3.1.1)
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- ❌ No language specified -->
|
||||||
|
<html>
|
||||||
|
|
||||||
|
<!-- ✅ Language specified -->
|
||||||
|
<html lang="en">
|
||||||
|
|
||||||
|
<!-- ✅ Language changes within page -->
|
||||||
|
<p>The French word for hello is <span lang="fr">bonjour</span>.</p>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Consistent navigation (3.2.3)
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- Navigation should be consistent across pages -->
|
||||||
|
<nav aria-label="Main">
|
||||||
|
<ul>
|
||||||
|
<li><a href="/" aria-current="page">Home</a></li>
|
||||||
|
<li><a href="/products">Products</a></li>
|
||||||
|
<li><a href="/about">About</a></li>
|
||||||
|
</ul>
|
||||||
|
</nav>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Consistent help (3.2.6) — new in 2.2
|
||||||
|
|
||||||
|
If a help mechanism (contact info, chat widget, FAQ link, self-help option) is repeated across multiple pages, it must appear in the **same relative order** each time. Users who rely on consistent placement shouldn't have to hunt for help on every page.
|
||||||
|
|
||||||
|
### Form labels (3.3.2)
|
||||||
|
|
||||||
|
Every input needs a programmatically associated label. See the [form labels pattern](references/A11Y-PATTERNS.md#form-labels) for explicit, implicit, and instructional examples.
|
||||||
|
|
||||||
|
### Error handling (3.3.1, 3.3.3)
|
||||||
|
|
||||||
|
Announce errors to screen readers with `role="alert"` or `aria-live`, set `aria-invalid="true"` on invalid fields, and focus the first error on submit. See the [error handling pattern](references/A11Y-PATTERNS.md#error-handling) for full markup and JS.
|
||||||
|
|
||||||
|
### Redundant entry (3.3.7) — new in 2.2
|
||||||
|
|
||||||
|
Don't force users to re-enter information they already provided in the same session. Auto-populate from earlier steps, or let users select from previously entered values. Exceptions: security re-confirmation and content that has expired.
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- ✅ Auto-fill shipping address from billing -->
|
||||||
|
<fieldset>
|
||||||
|
<legend>Shipping address</legend>
|
||||||
|
<label>
|
||||||
|
<input type="checkbox" id="same-as-billing" checked>
|
||||||
|
Same as billing address
|
||||||
|
</label>
|
||||||
|
<!-- Fields auto-populated when checked -->
|
||||||
|
</fieldset>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Accessible authentication (3.3.8) — new in 2.2
|
||||||
|
|
||||||
|
Login flows must not rely on cognitive function tests (e.g., remembering a password, solving a puzzle) unless at least one of:
|
||||||
|
- A copy-paste or autofill mechanism is available
|
||||||
|
- An alternative method exists (e.g., passkey, SSO, email link)
|
||||||
|
- The test uses object recognition or personal content (AA only; AAA removes this exception)
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- ✅ Allow paste in password fields -->
|
||||||
|
<input type="password" id="password" autocomplete="current-password">
|
||||||
|
|
||||||
|
<!-- ✅ Offer passwordless alternatives -->
|
||||||
|
<button type="button">Sign in with passkey</button>
|
||||||
|
<button type="button">Email me a login link</button>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Robust
|
||||||
|
|
||||||
|
### ARIA usage (4.1.2)
|
||||||
|
|
||||||
|
**Prefer native elements:**
|
||||||
|
```html
|
||||||
|
<!-- ❌ ARIA role on div -->
|
||||||
|
<div role="button" tabindex="0">Click me</div>
|
||||||
|
|
||||||
|
<!-- ✅ Native button -->
|
||||||
|
<button>Click me</button>
|
||||||
|
|
||||||
|
<!-- ❌ ARIA checkbox -->
|
||||||
|
<div role="checkbox" aria-checked="false">Option</div>
|
||||||
|
|
||||||
|
<!-- ✅ Native checkbox -->
|
||||||
|
<label><input type="checkbox"> Option</label>
|
||||||
|
```
|
||||||
|
|
||||||
|
**When ARIA is needed,** use the correct roles and states. See the [ARIA tabs pattern](references/A11Y-PATTERNS.md#aria-tabs) for a complete tablist example.
|
||||||
|
|
||||||
|
### Live regions (4.1.3)
|
||||||
|
|
||||||
|
Use `aria-live` regions to announce dynamic content changes without moving focus. See the [live regions pattern](references/A11Y-PATTERNS.md#live-regions-and-notifications) for markup and a `showNotification()` helper.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Testing checklist
|
||||||
|
|
||||||
|
### Automated testing
|
||||||
|
```bash
|
||||||
|
# Lighthouse accessibility audit
|
||||||
|
npx lighthouse https://example.com --only-categories=accessibility
|
||||||
|
|
||||||
|
# axe-core
|
||||||
|
npm install @axe-core/cli -g
|
||||||
|
axe https://example.com
|
||||||
|
```
|
||||||
|
|
||||||
|
### Manual testing
|
||||||
|
|
||||||
|
- [ ] **Keyboard navigation:** Tab through entire page, use Enter/Space to activate
|
||||||
|
- [ ] **Screen reader:** Test with VoiceOver (Mac), NVDA (Windows), or TalkBack (Android)
|
||||||
|
- [ ] **Zoom:** Content usable at 200% zoom
|
||||||
|
- [ ] **High contrast:** Test with Windows High Contrast Mode
|
||||||
|
- [ ] **Reduced motion:** Test with `prefers-reduced-motion: reduce`
|
||||||
|
- [ ] **Focus order:** Logical and follows visual order
|
||||||
|
- [ ] **Target size:** Interactive elements meet 24×24px minimum
|
||||||
|
|
||||||
|
See the [screen reader commands reference](references/A11Y-PATTERNS.md#screen-reader-commands) for VoiceOver and NVDA shortcuts.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Common issues by impact
|
||||||
|
|
||||||
|
### Critical (fix immediately)
|
||||||
|
1. Missing form labels
|
||||||
|
2. Missing image alt text
|
||||||
|
3. Insufficient color contrast
|
||||||
|
4. Keyboard traps
|
||||||
|
5. No focus indicators
|
||||||
|
|
||||||
|
### Serious (fix before launch)
|
||||||
|
1. Missing page language
|
||||||
|
2. Missing heading structure
|
||||||
|
3. Non-descriptive link text
|
||||||
|
4. Auto-playing media
|
||||||
|
5. Missing skip links
|
||||||
|
|
||||||
|
### Moderate (fix soon)
|
||||||
|
1. Missing ARIA labels on icons
|
||||||
|
2. Inconsistent navigation
|
||||||
|
3. Missing error identification
|
||||||
|
4. Timing without controls
|
||||||
|
5. Missing landmark regions
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
- [WCAG 2.2 Quick Reference](https://www.w3.org/WAI/WCAG22/quickref/)
|
||||||
|
- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
|
||||||
|
- [Deque axe Rules](https://dequeuniversity.com/rules/axe/)
|
||||||
|
- [Web Quality Audit](../web-quality-audit/SKILL.md)
|
||||||
|
- [WCAG criteria reference](references/WCAG.md)
|
||||||
|
- [Accessibility code patterns](references/A11Y-PATTERNS.md)
|
||||||
233
.agents/skills/accessibility/references/A11Y-PATTERNS.md
Normal file
233
.agents/skills/accessibility/references/A11Y-PATTERNS.md
Normal file
@@ -0,0 +1,233 @@
|
|||||||
|
# Accessibility Code Patterns
|
||||||
|
|
||||||
|
Practical, copy-paste-ready patterns for common accessibility requirements. Each pattern is self-contained and linked from the main [SKILL.md](../SKILL.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Modal focus trap
|
||||||
|
|
||||||
|
Trap keyboard focus inside a modal dialog so Tab/Shift+Tab cycle through its focusable elements and Escape closes it.
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
function openModal(modal) {
|
||||||
|
const focusableElements = modal.querySelectorAll(
|
||||||
|
'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
|
||||||
|
);
|
||||||
|
const firstElement = focusableElements[0];
|
||||||
|
const lastElement = focusableElements[focusableElements.length - 1];
|
||||||
|
|
||||||
|
modal.addEventListener('keydown', (e) => {
|
||||||
|
if (e.key === 'Tab') {
|
||||||
|
if (e.shiftKey && document.activeElement === firstElement) {
|
||||||
|
e.preventDefault();
|
||||||
|
lastElement.focus();
|
||||||
|
} else if (!e.shiftKey && document.activeElement === lastElement) {
|
||||||
|
e.preventDefault();
|
||||||
|
firstElement.focus();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
if (e.key === 'Escape') {
|
||||||
|
closeModal();
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
firstElement.focus();
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The native `<dialog>` element handles focus trapping automatically—prefer it when browser support allows.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Skip link
|
||||||
|
|
||||||
|
Allows keyboard users to bypass repetitive navigation and jump straight to main content.
|
||||||
|
|
||||||
|
```html
|
||||||
|
<body>
|
||||||
|
<a href="#main-content" class="skip-link">Skip to main content</a>
|
||||||
|
<header><!-- navigation --></header>
|
||||||
|
<main id="main-content" tabindex="-1">
|
||||||
|
<!-- main content -->
|
||||||
|
</main>
|
||||||
|
</body>
|
||||||
|
```
|
||||||
|
|
||||||
|
```css
|
||||||
|
.skip-link {
|
||||||
|
position: absolute;
|
||||||
|
top: -40px;
|
||||||
|
left: 0;
|
||||||
|
background: #000;
|
||||||
|
color: #fff;
|
||||||
|
padding: 8px 16px;
|
||||||
|
z-index: 100;
|
||||||
|
}
|
||||||
|
|
||||||
|
.skip-link:focus {
|
||||||
|
top: 0;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Error handling
|
||||||
|
|
||||||
|
Announce errors to screen readers and focus the first invalid field on submit.
|
||||||
|
|
||||||
|
```html
|
||||||
|
<form novalidate>
|
||||||
|
<div class="field" aria-live="polite">
|
||||||
|
<label for="email">Email</label>
|
||||||
|
<input type="email" id="email"
|
||||||
|
aria-invalid="true"
|
||||||
|
aria-describedby="email-error">
|
||||||
|
<p id="email-error" class="error" role="alert">
|
||||||
|
Please enter a valid email address (e.g., name@example.com)
|
||||||
|
</p>
|
||||||
|
</div>
|
||||||
|
</form>
|
||||||
|
```
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
form.addEventListener('submit', (e) => {
|
||||||
|
const firstError = form.querySelector('[aria-invalid="true"]');
|
||||||
|
if (firstError) {
|
||||||
|
e.preventDefault();
|
||||||
|
firstError.focus();
|
||||||
|
|
||||||
|
const errorSummary = document.getElementById('error-summary');
|
||||||
|
errorSummary.textContent =
|
||||||
|
`${errors.length} errors found. Please fix them and try again.`;
|
||||||
|
errorSummary.focus();
|
||||||
|
}
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Form labels
|
||||||
|
|
||||||
|
Every input needs an associated label—either explicit (`for`/`id`) or implicit (wrapping `<label>`).
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- ❌ No label association -->
|
||||||
|
<input type="email" placeholder="Email">
|
||||||
|
|
||||||
|
<!-- ✅ Explicit label -->
|
||||||
|
<label for="email">Email address</label>
|
||||||
|
<input type="email" id="email" name="email"
|
||||||
|
autocomplete="email" required>
|
||||||
|
|
||||||
|
<!-- ✅ Implicit label -->
|
||||||
|
<label>
|
||||||
|
Email address
|
||||||
|
<input type="email" name="email" autocomplete="email" required>
|
||||||
|
</label>
|
||||||
|
|
||||||
|
<!-- ✅ With instructions -->
|
||||||
|
<label for="password">Password</label>
|
||||||
|
<input type="password" id="password"
|
||||||
|
aria-describedby="password-requirements">
|
||||||
|
<p id="password-requirements">
|
||||||
|
Must be at least 8 characters with one number.
|
||||||
|
</p>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Dragging movements
|
||||||
|
|
||||||
|
Any action triggered by dragging must offer a single-pointer alternative (WCAG 2.5.7).
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- ❌ Drag-only reorder -->
|
||||||
|
<ul class="sortable-list" draggable="true">
|
||||||
|
<li>Item 1</li>
|
||||||
|
<li>Item 2</li>
|
||||||
|
</ul>
|
||||||
|
|
||||||
|
<!-- ✅ Drag + button alternatives -->
|
||||||
|
<ul class="sortable-list">
|
||||||
|
<li>
|
||||||
|
<span>Item 1</span>
|
||||||
|
<button aria-label="Move Item 1 up">↑</button>
|
||||||
|
<button aria-label="Move Item 1 down">↓</button>
|
||||||
|
</li>
|
||||||
|
<li>
|
||||||
|
<span>Item 2</span>
|
||||||
|
<button aria-label="Move Item 2 up">↑</button>
|
||||||
|
<button aria-label="Move Item 2 down">↓</button>
|
||||||
|
</li>
|
||||||
|
</ul>
|
||||||
|
```
|
||||||
|
|
||||||
|
Also applies to sliders, map panning, colour pickers, and similar drag-based widgets—always provide an equivalent click/tap or keyboard path.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ARIA tabs
|
||||||
|
|
||||||
|
Tabs require `role="tablist"`, `role="tab"`, and `role="tabpanel"` with proper `aria-selected`, `aria-controls`, and keyboard support.
|
||||||
|
|
||||||
|
```html
|
||||||
|
<div role="tablist" aria-label="Product information">
|
||||||
|
<button role="tab" id="tab-1" aria-selected="true"
|
||||||
|
aria-controls="panel-1">Description</button>
|
||||||
|
<button role="tab" id="tab-2" aria-selected="false"
|
||||||
|
aria-controls="panel-2" tabindex="-1">Reviews</button>
|
||||||
|
</div>
|
||||||
|
<div role="tabpanel" id="panel-1" aria-labelledby="tab-1">
|
||||||
|
<!-- Panel content -->
|
||||||
|
</div>
|
||||||
|
<div role="tabpanel" id="panel-2" aria-labelledby="tab-2" hidden>
|
||||||
|
<!-- Panel content -->
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
Arrow keys should move focus between tabs; the active tab receives `tabindex="0"` while inactive tabs use `tabindex="-1"`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Live regions and notifications
|
||||||
|
|
||||||
|
Use `aria-live` to announce dynamic content changes to screen readers without moving focus.
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- Status updates (polite — waits for pause in speech) -->
|
||||||
|
<div aria-live="polite" aria-atomic="true" class="status">
|
||||||
|
<!-- Content updates announced to screen readers -->
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<!-- Urgent alerts (assertive — interrupts) -->
|
||||||
|
<div role="alert" aria-live="assertive">
|
||||||
|
<!-- Interrupts current announcement -->
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
function showNotification(message, type = 'polite') {
|
||||||
|
const container = document.getElementById(`${type}-announcer`);
|
||||||
|
container.textContent = '';
|
||||||
|
requestAnimationFrame(() => {
|
||||||
|
container.textContent = message;
|
||||||
|
});
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Clear the container before writing to ensure the same message triggers a new announcement.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Screen reader commands
|
||||||
|
|
||||||
|
Quick reference for the most common screen reader shortcuts.
|
||||||
|
|
||||||
|
| Action | VoiceOver (Mac) | NVDA (Windows) |
|
||||||
|
|--------|-----------------|----------------|
|
||||||
|
| Start/Stop | ⌘ + F5 | Ctrl + Alt + N |
|
||||||
|
| Next item | VO + → | ↓ |
|
||||||
|
| Previous item | VO + ← | ↑ |
|
||||||
|
| Activate | VO + Space | Enter |
|
||||||
|
| Headings list | VO + U, then arrows | H / Shift + H |
|
||||||
|
| Links list | VO + U | K / Shift + K |
|
||||||
191
.agents/skills/accessibility/references/WCAG.md
Normal file
191
.agents/skills/accessibility/references/WCAG.md
Normal file
@@ -0,0 +1,191 @@
|
|||||||
|
# WCAG 2.2 Quick Reference
|
||||||
|
|
||||||
|
## Success criteria by level
|
||||||
|
|
||||||
|
### Level A (minimum)
|
||||||
|
|
||||||
|
| Criterion | Description |
|
||||||
|
|-----------|-------------|
|
||||||
|
| **1.1.1** Non-text Content | All images, icons have text alternatives |
|
||||||
|
| **1.2.1** Audio-only/Video-only | Provide transcript or audio description |
|
||||||
|
| **1.2.2** Captions | Video with audio has captions |
|
||||||
|
| **1.2.3** Audio Description | Video has audio description |
|
||||||
|
| **1.3.1** Info and Relationships | Information conveyed through presentation is available programmatically |
|
||||||
|
| **1.3.2** Meaningful Sequence | Reading order is logical |
|
||||||
|
| **1.3.3** Sensory Characteristics | Instructions don't rely solely on shape, color, size, location, orientation, or sound |
|
||||||
|
| **1.4.1** Use of Color | Color is not the only visual means of conveying information |
|
||||||
|
| **1.4.2** Audio Control | Audio playing automatically can be paused/stopped |
|
||||||
|
| **2.1.1** Keyboard | All functionality available via keyboard |
|
||||||
|
| **2.1.2** No Keyboard Trap | Keyboard focus can be moved away from any component |
|
||||||
|
| **2.1.4** Character Key Shortcuts | Single-key shortcuts can be turned off or remapped |
|
||||||
|
| **2.2.1** Timing Adjustable | Time limits can be extended |
|
||||||
|
| **2.2.2** Pause, Stop, Hide | Moving/blinking content can be paused |
|
||||||
|
| **2.3.1** Three Flashes | Nothing flashes more than 3 times per second |
|
||||||
|
| **2.4.1** Bypass Blocks | Skip link or landmark navigation available |
|
||||||
|
| **2.4.2** Page Titled | Pages have descriptive titles |
|
||||||
|
| **2.4.3** Focus Order | Focus order preserves meaning |
|
||||||
|
| **2.4.4** Link Purpose | Link purpose clear from link text or context |
|
||||||
|
| **2.5.1** Pointer Gestures | Multi-point gestures have single-pointer alternatives |
|
||||||
|
| **2.5.2** Pointer Cancellation | Down-event doesn't trigger action (use up-event or click) |
|
||||||
|
| **2.5.3** Label in Name | Accessible name contains visible label text |
|
||||||
|
| **2.5.4** Motion Actuation | Motion-triggered functions have alternatives |
|
||||||
|
| **3.1.1** Language of Page | Default language specified in HTML |
|
||||||
|
| **3.2.1** On Focus | Focus doesn't trigger unexpected changes |
|
||||||
|
| **3.2.2** On Input | Input doesn't trigger unexpected changes |
|
||||||
|
| **3.2.6** Consistent Help | Help mechanisms appear in the same relative order across pages |
|
||||||
|
| **3.3.1** Error Identification | Input errors clearly described |
|
||||||
|
| **3.3.2** Labels or Instructions | Form inputs have labels or instructions |
|
||||||
|
| **3.3.7** Redundant Entry | Information previously entered is auto-populated or available to select |
|
||||||
|
| **4.1.2** Name, Role, Value | UI components have accessible names and correct roles |
|
||||||
|
|
||||||
|
### Level AA (standard)
|
||||||
|
|
||||||
|
| Criterion | Description |
|
||||||
|
|-----------|-------------|
|
||||||
|
| **1.2.4** Captions (Live) | Live audio has captions |
|
||||||
|
| **1.2.5** Audio Description | Pre-recorded video has audio description |
|
||||||
|
| **1.3.4** Orientation | Content doesn't restrict orientation |
|
||||||
|
| **1.3.5** Identify Input Purpose | Input purpose can be programmatically determined |
|
||||||
|
| **1.4.3** Contrast (Minimum) | 4.5:1 for normal text, 3:1 for large text |
|
||||||
|
| **1.4.4** Resize Text | Text can be resized to 200% without loss of functionality |
|
||||||
|
| **1.4.5** Images of Text | Text used instead of images of text |
|
||||||
|
| **1.4.10** Reflow | Content reflows at 320px width without horizontal scroll |
|
||||||
|
| **1.4.11** Non-text Contrast | UI components have 3:1 contrast |
|
||||||
|
| **1.4.12** Text Spacing | Content adapts to text spacing changes |
|
||||||
|
| **1.4.13** Content on Hover/Focus | Additional content is dismissible, hoverable, persistent |
|
||||||
|
| **2.4.5** Multiple Ways | Multiple ways to find pages |
|
||||||
|
| **2.4.6** Headings and Labels | Headings and labels are descriptive |
|
||||||
|
| **2.4.7** Focus Visible | Focus indicator is visible |
|
||||||
|
| **2.4.11** Focus Not Obscured (Minimum) | Focused element is not entirely hidden by author-created content |
|
||||||
|
| **2.5.7** Dragging Movements | Dragging actions have single-pointer alternatives |
|
||||||
|
| **2.5.8** Target Size (Minimum) | Interactive targets are at least 24×24 CSS pixels (with exceptions) |
|
||||||
|
| **3.1.2** Language of Parts | Language changes are marked |
|
||||||
|
| **3.2.3** Consistent Navigation | Navigation is consistent across pages |
|
||||||
|
| **3.2.4** Consistent Identification | Same functionality uses same labels |
|
||||||
|
| **3.3.3** Error Suggestion | Error corrections suggested when known |
|
||||||
|
| **3.3.4** Error Prevention (Legal) | Actions can be reversed or confirmed |
|
||||||
|
| **3.3.8** Accessible Authentication (Minimum) | No cognitive function test for login unless an alternative or assistance is provided |
|
||||||
|
| **4.1.3** Status Messages | Status messages announced to screen readers |
|
||||||
|
|
||||||
|
### Level AAA (enhanced)
|
||||||
|
|
||||||
|
| Criterion | Description |
|
||||||
|
|-----------|-------------|
|
||||||
|
| **1.4.6** Contrast (Enhanced) | 7:1 for normal text, 4.5:1 for large text |
|
||||||
|
| **1.4.8** Visual Presentation | Foreground/background colors can be selected |
|
||||||
|
| **1.4.9** Images of Text (No Exception) | No images of text |
|
||||||
|
| **2.1.3** Keyboard (No Exception) | All functionality keyboard accessible |
|
||||||
|
| **2.2.3** No Timing | No time limits |
|
||||||
|
| **2.2.4** Interruptions | Interruptions can be postponed |
|
||||||
|
| **2.2.5** Re-authenticating | Data preserved on re-authentication |
|
||||||
|
| **2.2.6** Timeouts | Users warned about data loss from inactivity |
|
||||||
|
| **2.3.2** Three Flashes | No content flashes more than 3 times |
|
||||||
|
| **2.3.3** Animation from Interactions | Motion animation can be disabled |
|
||||||
|
| **2.4.8** Location | User location within site is available |
|
||||||
|
| **2.4.9** Link Purpose (Link Only) | Link purpose clear from link text alone |
|
||||||
|
| **2.4.10** Section Headings | Sections have headings |
|
||||||
|
| **2.4.12** Focus Not Obscured (Enhanced) | No part of the focused element is hidden by author-created content |
|
||||||
|
| **2.4.13** Focus Appearance | Focus indicator has sufficient area, contrast, and is not obscured |
|
||||||
|
| **3.1.3** Unusual Words | Definitions available for unusual words |
|
||||||
|
| **3.1.4** Abbreviations | Abbreviations expanded |
|
||||||
|
| **3.1.5** Reading Level | Alternative content for complex text |
|
||||||
|
| **3.1.6** Pronunciation | Pronunciation available where needed |
|
||||||
|
| **3.2.5** Change on Request | Changes initiated only by user |
|
||||||
|
| **3.3.5** Help | Context-sensitive help available |
|
||||||
|
| **3.3.6** Error Prevention (All) | All form submissions can be reviewed |
|
||||||
|
| **3.3.9** Accessible Authentication (Enhanced) | No cognitive function test for login (no object or personal content recognition exceptions) |
|
||||||
|
|
||||||
|
## Common ARIA patterns
|
||||||
|
|
||||||
|
### Buttons
|
||||||
|
```html
|
||||||
|
<button>Label</button>
|
||||||
|
<!-- or -->
|
||||||
|
<button aria-label="Close dialog">×</button>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Links
|
||||||
|
```html
|
||||||
|
<a href="/page">Descriptive link text</a>
|
||||||
|
<!-- External links -->
|
||||||
|
<a href="https://external.com" target="_blank" rel="noopener">
|
||||||
|
External site
|
||||||
|
<span class="visually-hidden">(opens in new tab)</span>
|
||||||
|
</a>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Form fields
|
||||||
|
```html
|
||||||
|
<label for="email">Email address</label>
|
||||||
|
<input type="email" id="email" aria-describedby="email-hint">
|
||||||
|
<p id="email-hint">We'll never share your email.</p>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Error states
|
||||||
|
```html
|
||||||
|
<label for="email">Email</label>
|
||||||
|
<input type="email" id="email" aria-invalid="true" aria-describedby="email-error">
|
||||||
|
<p id="email-error" role="alert">Please enter a valid email address.</p>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Navigation
|
||||||
|
```html
|
||||||
|
<nav aria-label="Main">
|
||||||
|
<ul>
|
||||||
|
<li><a href="/" aria-current="page">Home</a></li>
|
||||||
|
<li><a href="/about">About</a></li>
|
||||||
|
</ul>
|
||||||
|
</nav>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Modals
|
||||||
|
```html
|
||||||
|
<div role="dialog" aria-modal="true" aria-labelledby="dialog-title">
|
||||||
|
<h2 id="dialog-title">Confirm Action</h2>
|
||||||
|
<!-- content -->
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Live regions
|
||||||
|
```html
|
||||||
|
<!-- Polite (waits for pause in speech) -->
|
||||||
|
<div aria-live="polite">Status update here</div>
|
||||||
|
|
||||||
|
<!-- Assertive (interrupts immediately) -->
|
||||||
|
<div aria-live="assertive" role="alert">Error message here</div>
|
||||||
|
|
||||||
|
<!-- Status (polite, implicit) -->
|
||||||
|
<div role="status">Loading complete</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
## What changed from 2.1 to 2.2
|
||||||
|
|
||||||
|
| Change | Criterion | Level |
|
||||||
|
|--------|-----------|-------|
|
||||||
|
| **Removed** | 4.1.1 Parsing | A |
|
||||||
|
| **Added** | 2.4.11 Focus Not Obscured (Minimum) | AA |
|
||||||
|
| **Added** | 2.4.12 Focus Not Obscured (Enhanced) | AAA |
|
||||||
|
| **Added** | 2.4.13 Focus Appearance | AAA |
|
||||||
|
| **Added** | 2.5.7 Dragging Movements | AA |
|
||||||
|
| **Added** | 2.5.8 Target Size (Minimum) | AA |
|
||||||
|
| **Added** | 3.2.6 Consistent Help | A |
|
||||||
|
| **Added** | 3.3.7 Redundant Entry | A |
|
||||||
|
| **Added** | 3.3.8 Accessible Authentication (Minimum) | AA |
|
||||||
|
| **Added** | 3.3.9 Accessible Authentication (Enhanced) | AAA |
|
||||||
|
|
||||||
|
## Testing tools
|
||||||
|
|
||||||
|
| Tool | Type | URL |
|
||||||
|
|------|------|-----|
|
||||||
|
| axe DevTools | Browser extension | [deque.com/axe](https://www.deque.com/axe/) |
|
||||||
|
| WAVE | Browser extension | [wave.webaim.org](https://wave.webaim.org/) |
|
||||||
|
| Lighthouse | Built into Chrome | DevTools → Lighthouse |
|
||||||
|
| NVDA | Screen reader (Windows) | [nvaccess.org](https://www.nvaccess.org/) |
|
||||||
|
| VoiceOver | Screen reader (Mac) | Built into macOS |
|
||||||
|
| Colour Contrast Analyser | Desktop app | [tpgi.com](https://www.tpgi.com/color-contrast-checker/) |
|
||||||
|
|
||||||
|
## Sources
|
||||||
|
|
||||||
|
- [WCAG 2.2 W3C Recommendation](https://www.w3.org/TR/WCAG22/)
|
||||||
|
- [WCAG 2.2 Quick Reference](https://www.w3.org/WAI/WCAG22/quickref/)
|
||||||
|
- [What's New in WCAG 2.2](https://www.w3.org/WAI/standards-guidelines/wcag/new-in-22/)
|
||||||
167
.agents/skills/discord-bot/SKILL.md
Normal file
167
.agents/skills/discord-bot/SKILL.md
Normal file
@@ -0,0 +1,167 @@
|
|||||||
|
---
|
||||||
|
name: discord-bot
|
||||||
|
description: Discord bot development on Cloudflare Workers — Discord API, Developer Portal, slash commands, Gateway WebSocket, Interactions Endpoint, bot permissions, intents, and Ed25519 verification.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Discord Bot Development
|
||||||
|
|
||||||
|
Use this skill when working on Discord bots, Discord API integration, bot setup/configuration, or slash command registration. Triggered by mentions of Discord bots, Discord Developer Portal, Discord API, slash commands, Gateway, or Interactions Endpoint.
|
||||||
|
|
||||||
|
## Search before giving portal instructions
|
||||||
|
|
||||||
|
The Discord Developer Portal UI changes often, so web-search current instructions before describing:
|
||||||
|
* Where settings are located in the Developer Portal
|
||||||
|
* OAuth2 flow steps
|
||||||
|
* Bot permission configuration
|
||||||
|
* Interactions Endpoint setup
|
||||||
|
* Install link generation
|
||||||
|
|
||||||
|
Useful queries:
|
||||||
|
* `Discord Developer Portal [specific task] <current year>`
|
||||||
|
* `Discord bot setup [specific feature] latest`
|
||||||
|
|
||||||
|
If search results are older than 6 months, note this to the user and suggest they verify in the portal.
|
||||||
|
|
||||||
|
## Discord Bot Architecture on Cloudflare Workers
|
||||||
|
|
||||||
|
Two models for receiving Discord events:
|
||||||
|
|
||||||
|
### Interactions Endpoint (HTTP)
|
||||||
|
* Discord POSTs slash commands and component interactions to your Worker URL
|
||||||
|
* No persistent connection needed — pure request/response
|
||||||
|
* Set the URL in Developer Portal → General Information → Interactions Endpoint URL
|
||||||
|
* Requires Ed25519 signature verification on every request (`discord-interactions` npm package)
|
||||||
|
* Supports: slash commands, buttons, select menus, modals, autocomplete
|
||||||
|
|
||||||
|
### Gateway (WebSocket)
|
||||||
|
* Persistent WebSocket connection to `wss://gateway.discord.gg`
|
||||||
|
* Required for: reaction events, message events, presence, voice state, typing indicators
|
||||||
|
* On Cloudflare Workers: use a **Durable Object** with `new WebSocket(url)` for the outbound connection
|
||||||
|
* NOT `fetch()` with `Upgrade: websocket` — that doesn't work for `wss://` URLs
|
||||||
|
* DO won't hibernate while outbound WS is open — use alarm-based keepalive (30s interval)
|
||||||
|
* Deploys evict the DO; alarm reconnects within ~30 seconds
|
||||||
|
|
||||||
|
### Which Do You Need?
|
||||||
|
|
||||||
|
| Feature | Interactions Endpoint | Gateway |
|
||||||
|
|---------|----------------------|---------|
|
||||||
|
| Slash commands | Yes | Not needed |
|
||||||
|
| Message reactions | No | Required |
|
||||||
|
| Message content | No | Required (with intent) |
|
||||||
|
| Typing indicators | No | Required |
|
||||||
|
| Presence updates | No | Required |
|
||||||
|
| Voice state | No | Required |
|
||||||
|
|
||||||
|
Most bots need both: Interactions Endpoint for slash commands, Gateway for real-time events.
|
||||||
|
|
||||||
|
## Setting Up a New Discord Bot
|
||||||
|
|
||||||
|
### 1. Create Application
|
||||||
|
* Go to https://discord.com/developers/applications
|
||||||
|
* Click **New Application**, name it, click Create
|
||||||
|
* Copy **Application ID** and **Public Key** from General Information page
|
||||||
|
|
||||||
|
### 2. Get Bot Token
|
||||||
|
* Sidebar → **Bot**
|
||||||
|
* Click **Reset Token**, copy immediately (shown once)
|
||||||
|
* Toggle privileged intents as needed (see Intents section below)
|
||||||
|
|
||||||
|
### 3. Configure Installation
|
||||||
|
* Sidebar → **Installation**
|
||||||
|
* Enable **Guild Install**
|
||||||
|
* Select **Discord Provided Link**
|
||||||
|
* Under Default Install Settings → Guild Install:
|
||||||
|
* **Scopes:** `bot`, `applications.commands`
|
||||||
|
* **Permissions:** Select based on your bot's needs (see Permissions section)
|
||||||
|
|
||||||
|
### 4. Set Interactions Endpoint
|
||||||
|
* Sidebar → **General Information**
|
||||||
|
* Set **Interactions Endpoint URL** to your Worker's `/interactions` path
|
||||||
|
* Discord sends a PING to verify — your code must handle it (return Pong)
|
||||||
|
* Save — if verification fails, your endpoint isn't working
|
||||||
|
|
||||||
|
### 5. Register Slash Commands
|
||||||
|
* Use `PUT https://discord.com/api/v10/applications/{app_id}/commands`
|
||||||
|
* Global commands can take up to an hour to propagate
|
||||||
|
* Guild-specific commands update instantly (useful for testing)
|
||||||
|
|
||||||
|
### 6. Install to Server
|
||||||
|
* Copy the Install Link from the Installation page
|
||||||
|
* Paste in browser, select server, authorize
|
||||||
|
|
||||||
|
## Intents
|
||||||
|
|
||||||
|
Gateway intents control which events Discord sends to your bot.
|
||||||
|
|
||||||
|
**Standard intents** (no approval needed):
|
||||||
|
* `GUILDS` (1 << 0) — guild create/update/delete, role changes
|
||||||
|
* `GUILD_MESSAGES` (1 << 9) — message create/update/delete in guilds
|
||||||
|
* `GUILD_MESSAGE_REACTIONS` (1 << 10) — reaction add/remove
|
||||||
|
|
||||||
|
**Privileged intents** (must be enabled in Developer Portal → Bot):
|
||||||
|
* `MESSAGE_CONTENT` (1 << 15) — access to message content via Gateway AND REST API. Without this, `message.content` is empty for messages the bot didn't send or wasn't mentioned in.
|
||||||
|
* `GUILD_MEMBERS` (1 << 1) — member join/leave/update events
|
||||||
|
* `GUILD_PRESENCES` (1 << 8) — presence (online/offline) updates
|
||||||
|
|
||||||
|
**No approval needed for bots in <100 servers.** Over 100 servers requires Discord review.
|
||||||
|
|
||||||
|
## Common Permissions
|
||||||
|
|
||||||
|
| Permission | Bit | When needed |
|
||||||
|
|-----------|-----|-------------|
|
||||||
|
| View Channels | 1 << 10 | See channels and receive events from them |
|
||||||
|
| Send Messages | 1 << 11 | Send messages (DMs, channel messages) |
|
||||||
|
| Read Message History | 1 << 16 | Fetch messages via REST API |
|
||||||
|
| Use Slash Commands | 1 << 31 | Use application commands |
|
||||||
|
| Manage Roles | 1 << 28 | Assign/remove roles from members |
|
||||||
|
| Add Reactions | 1 << 6 | Add reactions to messages |
|
||||||
|
|
||||||
|
## Common Gotchas
|
||||||
|
|
||||||
|
### Bot doesn't receive reaction events
|
||||||
|
* **Missing intent:** Must request `GUILD_MESSAGE_REACTIONS` in Gateway IDENTIFY
|
||||||
|
* **Missing VIEW_CHANNEL:** The bot's role needs View Channels permission. Public channels inherit from @everyone, but **private channels require the bot role to be explicitly added** to the channel's permissions
|
||||||
|
|
||||||
|
### Empty message.content from REST API
|
||||||
|
* **Missing MESSAGE_CONTENT intent:** Must be enabled in Developer Portal → Bot → Privileged Gateway Intents. Also include `MESSAGE_CONTENT` (1 << 15) in the Gateway IDENTIFY intents value
|
||||||
|
|
||||||
|
### Slash command not visible
|
||||||
|
* **Propagation delay:** Global commands take up to an hour. Use guild-specific commands for testing
|
||||||
|
* **Permission restriction:** `default_member_permissions` hides commands from users without the specified permission
|
||||||
|
* **Subcommand required:** If a command has subcommands defined, the base command can't be run alone — Discord requires picking a subcommand
|
||||||
|
|
||||||
|
### "The application did not respond" on a slash command that actually worked
|
||||||
|
* Discord gives an interaction **3 seconds** to receive a response. A handler that runs its side effects synchronously before responding (REST calls, role changes, D1 writes) blows the deadline — Discord shows the error, but the Worker invocation keeps running, so the side effects still complete. Looks like a failure, is usually a success with a lost reply.
|
||||||
|
* For any command doing more than ~1 REST round trip: immediately return type 5 (`DeferredChannelMessageWithSource`, keep the ephemeral flag if needed), run the work in `ctx.waitUntil()`, then PATCH the result to `/webhooks/{application_id}/{interaction_token}/messages/@original`.
|
||||||
|
|
||||||
|
### WebSocket connection drops on Cloudflare Workers
|
||||||
|
* **DO eviction:** Use alarm-based keepalive (30s interval) to prevent idle eviction
|
||||||
|
* **Deploy:** Deploys always evict the DO. Alarm reconnects within ~30s. Use `/gateway/reconnect` for immediate recovery
|
||||||
|
* **Use `new WebSocket(url)` not `fetch()` with Upgrade header** for `wss://` URLs
|
||||||
|
|
||||||
|
### Discord rate limits
|
||||||
|
* REST API returns 429 with `retry_after` field (seconds). Wait and retry.
|
||||||
|
* Gateway has identify rate limits (1 per 5 seconds). Don't reconnect in a tight loop.
|
||||||
|
|
||||||
|
## Verification Checklist
|
||||||
|
|
||||||
|
When setting up or debugging a Discord bot:
|
||||||
|
|
||||||
|
- [ ] Bot token is set and valid (test with `GET /api/v10/users/@me`)
|
||||||
|
- [ ] Interactions Endpoint URL is set and verified (Developer Portal shows success)
|
||||||
|
- [ ] Slash commands are registered (`PUT .../commands` returns 200)
|
||||||
|
- [ ] Bot is installed to the target server (visible in member list)
|
||||||
|
- [ ] Bot role has necessary permissions (check via REST API `GET /guilds/{id}/members/{bot_id}`)
|
||||||
|
- [ ] Privileged intents are enabled in Developer Portal if needed
|
||||||
|
- [ ] Gateway intents in IDENTIFY include all needed flags
|
||||||
|
- [ ] VIEW_CHANNEL permission is set for private channels
|
||||||
|
- [ ] Gateway connection is alive (`/gateway/status` returns `connected: true`)
|
||||||
|
|
||||||
|
## Reference: Elereada v2
|
||||||
|
|
||||||
|
Working example of a Discord bot on Cloudflare Workers: `github.com/rianvdm/elereada-v2`
|
||||||
|
* Durable Object outbound WebSocket for Gateway
|
||||||
|
* Hono for HTTP routing + Interactions Endpoint
|
||||||
|
* D1 for storage
|
||||||
|
* Alarm-based keepalive for DO persistence
|
||||||
|
* Ed25519 verification via `discord-interactions` package
|
||||||
177
.agents/skills/frontend-design/LICENSE.txt
Normal file
177
.agents/skills/frontend-design/LICENSE.txt
Normal file
@@ -0,0 +1,177 @@
|
|||||||
|
|
||||||
|
Apache License
|
||||||
|
Version 2.0, January 2004
|
||||||
|
http://www.apache.org/licenses/
|
||||||
|
|
||||||
|
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||||
|
|
||||||
|
1. Definitions.
|
||||||
|
|
||||||
|
"License" shall mean the terms and conditions for use, reproduction,
|
||||||
|
and distribution as defined by Sections 1 through 9 of this document.
|
||||||
|
|
||||||
|
"Licensor" shall mean the copyright owner or entity authorized by
|
||||||
|
the copyright owner that is granting the License.
|
||||||
|
|
||||||
|
"Legal Entity" shall mean the union of the acting entity and all
|
||||||
|
other entities that control, are controlled by, or are under common
|
||||||
|
control with that entity. For the purposes of this definition,
|
||||||
|
"control" means (i) the power, direct or indirect, to cause the
|
||||||
|
direction or management of such entity, whether by contract or
|
||||||
|
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||||
|
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||||
|
|
||||||
|
"You" (or "Your") shall mean an individual or Legal Entity
|
||||||
|
exercising permissions granted by this License.
|
||||||
|
|
||||||
|
"Source" form shall mean the preferred form for making modifications,
|
||||||
|
including but not limited to software source code, documentation
|
||||||
|
source, and configuration files.
|
||||||
|
|
||||||
|
"Object" form shall mean any form resulting from mechanical
|
||||||
|
transformation or translation of a Source form, including but
|
||||||
|
not limited to compiled object code, generated documentation,
|
||||||
|
and conversions to other media types.
|
||||||
|
|
||||||
|
"Work" shall mean the work of authorship, whether in Source or
|
||||||
|
Object form, made available under the License, as indicated by a
|
||||||
|
copyright notice that is included in or attached to the work
|
||||||
|
(an example is provided in the Appendix below).
|
||||||
|
|
||||||
|
"Derivative Works" shall mean any work, whether in Source or Object
|
||||||
|
form, that is based on (or derived from) the Work and for which the
|
||||||
|
editorial revisions, annotations, elaborations, or other modifications
|
||||||
|
represent, as a whole, an original work of authorship. For the purposes
|
||||||
|
of this License, Derivative Works shall not include works that remain
|
||||||
|
separable from, or merely link (or bind by name) to the interfaces of,
|
||||||
|
the Work and Derivative Works thereof.
|
||||||
|
|
||||||
|
"Contribution" shall mean any work of authorship, including
|
||||||
|
the original version of the Work and any modifications or additions
|
||||||
|
to that Work or Derivative Works thereof, that is intentionally
|
||||||
|
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||||
|
or by an individual or Legal Entity authorized to submit on behalf of
|
||||||
|
the copyright owner. For the purposes of this definition, "submitted"
|
||||||
|
means any form of electronic, verbal, or written communication sent
|
||||||
|
to the Licensor or its representatives, including but not limited to
|
||||||
|
communication on electronic mailing lists, source code control systems,
|
||||||
|
and issue tracking systems that are managed by, or on behalf of, the
|
||||||
|
Licensor for the purpose of discussing and improving the Work, but
|
||||||
|
excluding communication that is conspicuously marked or otherwise
|
||||||
|
designated in writing by the copyright owner as "Not a Contribution."
|
||||||
|
|
||||||
|
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||||
|
on behalf of whom a Contribution has been received by Licensor and
|
||||||
|
subsequently incorporated within the Work.
|
||||||
|
|
||||||
|
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||||
|
this License, each Contributor hereby grants to You a perpetual,
|
||||||
|
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||||
|
copyright license to reproduce, prepare Derivative Works of,
|
||||||
|
publicly display, publicly perform, sublicense, and distribute the
|
||||||
|
Work and such Derivative Works in Source or Object form.
|
||||||
|
|
||||||
|
3. Grant of Patent License. Subject to the terms and conditions of
|
||||||
|
this License, each Contributor hereby grants to You a perpetual,
|
||||||
|
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||||
|
(except as stated in this section) patent license to make, have made,
|
||||||
|
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||||
|
where such license applies only to those patent claims licensable
|
||||||
|
by such Contributor that are necessarily infringed by their
|
||||||
|
Contribution(s) alone or by combination of their Contribution(s)
|
||||||
|
with the Work to which such Contribution(s) was submitted. If You
|
||||||
|
institute patent litigation against any entity (including a
|
||||||
|
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||||
|
or a Contribution incorporated within the Work constitutes direct
|
||||||
|
or contributory patent infringement, then any patent licenses
|
||||||
|
granted to You under this License for that Work shall terminate
|
||||||
|
as of the date such litigation is filed.
|
||||||
|
|
||||||
|
4. Redistribution. You may reproduce and distribute copies of the
|
||||||
|
Work or Derivative Works thereof in any medium, with or without
|
||||||
|
modifications, and in Source or Object form, provided that You
|
||||||
|
meet the following conditions:
|
||||||
|
|
||||||
|
(a) You must give any other recipients of the Work or
|
||||||
|
Derivative Works a copy of this License; and
|
||||||
|
|
||||||
|
(b) You must cause any modified files to carry prominent notices
|
||||||
|
stating that You changed the files; and
|
||||||
|
|
||||||
|
(c) You must retain, in the Source form of any Derivative Works
|
||||||
|
that You distribute, all copyright, patent, trademark, and
|
||||||
|
attribution notices from the Source form of the Work,
|
||||||
|
excluding those notices that do not pertain to any part of
|
||||||
|
the Derivative Works; and
|
||||||
|
|
||||||
|
(d) If the Work includes a "NOTICE" text file as part of its
|
||||||
|
distribution, then any Derivative Works that You distribute must
|
||||||
|
include a readable copy of the attribution notices contained
|
||||||
|
within such NOTICE file, excluding those notices that do not
|
||||||
|
pertain to any part of the Derivative Works, in at least one
|
||||||
|
of the following places: within a NOTICE text file distributed
|
||||||
|
as part of the Derivative Works; within the Source form or
|
||||||
|
documentation, if provided along with the Derivative Works; or,
|
||||||
|
within a display generated by the Derivative Works, if and
|
||||||
|
wherever such third-party notices normally appear. The contents
|
||||||
|
of the NOTICE file are for informational purposes only and
|
||||||
|
do not modify the License. You may add Your own attribution
|
||||||
|
notices within Derivative Works that You distribute, alongside
|
||||||
|
or as an addendum to the NOTICE text from the Work, provided
|
||||||
|
that such additional attribution notices cannot be construed
|
||||||
|
as modifying the License.
|
||||||
|
|
||||||
|
You may add Your own copyright statement to Your modifications and
|
||||||
|
may provide additional or different license terms and conditions
|
||||||
|
for use, reproduction, or distribution of Your modifications, or
|
||||||
|
for any such Derivative Works as a whole, provided Your use,
|
||||||
|
reproduction, and distribution of the Work otherwise complies with
|
||||||
|
the conditions stated in this License.
|
||||||
|
|
||||||
|
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||||
|
any Contribution intentionally submitted for inclusion in the Work
|
||||||
|
by You to the Licensor shall be under the terms and conditions of
|
||||||
|
this License, without any additional terms or conditions.
|
||||||
|
Notwithstanding the above, nothing herein shall supersede or modify
|
||||||
|
the terms of any separate license agreement you may have executed
|
||||||
|
with Licensor regarding such Contributions.
|
||||||
|
|
||||||
|
6. Trademarks. This License does not grant permission to use the trade
|
||||||
|
names, trademarks, service marks, or product names of the Licensor,
|
||||||
|
except as required for reasonable and customary use in describing the
|
||||||
|
origin of the Work and reproducing the content of the NOTICE file.
|
||||||
|
|
||||||
|
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||||
|
agreed to in writing, Licensor provides the Work (and each
|
||||||
|
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||||
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||||
|
implied, including, without limitation, any warranties or conditions
|
||||||
|
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||||
|
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||||
|
appropriateness of using or redistributing the Work and assume any
|
||||||
|
risks associated with Your exercise of permissions under this License.
|
||||||
|
|
||||||
|
8. Limitation of Liability. In no event and under no legal theory,
|
||||||
|
whether in tort (including negligence), contract, or otherwise,
|
||||||
|
unless required by applicable law (such as deliberate and grossly
|
||||||
|
negligent acts) or agreed to in writing, shall any Contributor be
|
||||||
|
liable to You for damages, including any direct, indirect, special,
|
||||||
|
incidental, or consequential damages of any character arising as a
|
||||||
|
result of this License or out of the use or inability to use the
|
||||||
|
Work (including but not limited to damages for loss of goodwill,
|
||||||
|
work stoppage, computer failure or malfunction, or any and all
|
||||||
|
other commercial damages or losses), even if such Contributor
|
||||||
|
has been advised of the possibility of such damages.
|
||||||
|
|
||||||
|
9. Accepting Warranty or Additional Liability. While redistributing
|
||||||
|
the Work or Derivative Works thereof, You may choose to offer,
|
||||||
|
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||||
|
or other liability obligations and/or rights consistent with this
|
||||||
|
License. However, in accepting such obligations, You may act only
|
||||||
|
on Your own behalf and on Your sole responsibility, not on behalf
|
||||||
|
of any other Contributor, and only if You agree to indemnify,
|
||||||
|
defend, and hold each Contributor harmless for any liability
|
||||||
|
incurred by, or claims asserted against, such Contributor by reason
|
||||||
|
of your accepting any such warranty or additional liability.
|
||||||
|
|
||||||
|
END OF TERMS AND CONDITIONS
|
||||||
42
.agents/skills/frontend-design/SKILL.md
Normal file
42
.agents/skills/frontend-design/SKILL.md
Normal file
@@ -0,0 +1,42 @@
|
|||||||
|
---
|
||||||
|
name: frontend-design
|
||||||
|
description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
|
||||||
|
license: Complete terms in LICENSE.txt
|
||||||
|
---
|
||||||
|
|
||||||
|
This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
|
||||||
|
|
||||||
|
The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
|
||||||
|
|
||||||
|
## Design Thinking
|
||||||
|
|
||||||
|
Before coding, understand the context and commit to a BOLD aesthetic direction:
|
||||||
|
- **Purpose**: What problem does this interface solve? Who uses it?
|
||||||
|
- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
|
||||||
|
- **Constraints**: Technical requirements (framework, performance, accessibility).
|
||||||
|
- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
|
||||||
|
|
||||||
|
**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
|
||||||
|
|
||||||
|
Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
|
||||||
|
- Production-grade and functional
|
||||||
|
- Visually striking and memorable
|
||||||
|
- Cohesive with a clear aesthetic point-of-view
|
||||||
|
- Meticulously refined in every detail
|
||||||
|
|
||||||
|
## Frontend Aesthetics Guidelines
|
||||||
|
|
||||||
|
Focus on:
|
||||||
|
- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
|
||||||
|
- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
|
||||||
|
- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
|
||||||
|
- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
|
||||||
|
- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
|
||||||
|
|
||||||
|
NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
|
||||||
|
|
||||||
|
Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
|
||||||
|
|
||||||
|
**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
|
||||||
|
|
||||||
|
Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
|
||||||
639
.agents/skills/nodejs-backend-patterns/SKILL.md
Normal file
639
.agents/skills/nodejs-backend-patterns/SKILL.md
Normal file
@@ -0,0 +1,639 @@
|
|||||||
|
---
|
||||||
|
name: nodejs-backend-patterns
|
||||||
|
description: Build production-ready Node.js backend services with Express/Fastify, implementing middleware patterns, error handling, authentication, database integration, and API design best practices. Use when creating Node.js servers, REST APIs, GraphQL backends, or microservices architectures.
|
||||||
|
---
|
||||||
|
|
||||||
|
# Node.js Backend Patterns
|
||||||
|
|
||||||
|
Comprehensive guidance for building scalable, maintainable, and production-ready Node.js backend applications with modern frameworks, architectural patterns, and best practices.
|
||||||
|
|
||||||
|
## When to Use This Skill
|
||||||
|
|
||||||
|
- Building REST APIs or GraphQL servers
|
||||||
|
- Creating microservices with Node.js
|
||||||
|
- Implementing authentication and authorization
|
||||||
|
- Designing scalable backend architectures
|
||||||
|
- Setting up middleware and error handling
|
||||||
|
- Integrating databases (SQL and NoSQL)
|
||||||
|
- Building real-time applications with WebSockets
|
||||||
|
- Implementing background job processing
|
||||||
|
|
||||||
|
## Core Frameworks
|
||||||
|
|
||||||
|
### Express.js - Minimalist Framework
|
||||||
|
|
||||||
|
**Basic Setup:**
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import express, { Request, Response, NextFunction } from "express";
|
||||||
|
import helmet from "helmet";
|
||||||
|
import cors from "cors";
|
||||||
|
import compression from "compression";
|
||||||
|
|
||||||
|
const app = express();
|
||||||
|
|
||||||
|
// Security middleware
|
||||||
|
app.use(helmet());
|
||||||
|
app.use(cors({ origin: process.env.ALLOWED_ORIGINS?.split(",") }));
|
||||||
|
app.use(compression());
|
||||||
|
|
||||||
|
// Body parsing
|
||||||
|
app.use(express.json({ limit: "10mb" }));
|
||||||
|
app.use(express.urlencoded({ extended: true, limit: "10mb" }));
|
||||||
|
|
||||||
|
// Request logging
|
||||||
|
app.use((req: Request, res: Response, next: NextFunction) => {
|
||||||
|
console.log(`${req.method} ${req.path}`);
|
||||||
|
next();
|
||||||
|
});
|
||||||
|
|
||||||
|
const PORT = process.env.PORT || 3000;
|
||||||
|
app.listen(PORT, () => {
|
||||||
|
console.log(`Server running on port ${PORT}`);
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Fastify - High Performance Framework
|
||||||
|
|
||||||
|
**Basic Setup:**
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
import Fastify from "fastify";
|
||||||
|
import helmet from "@fastify/helmet";
|
||||||
|
import cors from "@fastify/cors";
|
||||||
|
import compress from "@fastify/compress";
|
||||||
|
|
||||||
|
const fastify = Fastify({
|
||||||
|
logger: {
|
||||||
|
level: process.env.LOG_LEVEL || "info",
|
||||||
|
transport: {
|
||||||
|
target: "pino-pretty",
|
||||||
|
options: { colorize: true },
|
||||||
|
},
|
||||||
|
},
|
||||||
|
});
|
||||||
|
|
||||||
|
// Plugins
|
||||||
|
await fastify.register(helmet);
|
||||||
|
await fastify.register(cors, { origin: true });
|
||||||
|
await fastify.register(compress);
|
||||||
|
|
||||||
|
// Type-safe routes with schema validation
|
||||||
|
fastify.post<{
|
||||||
|
Body: { name: string; email: string };
|
||||||
|
Reply: { id: string; name: string };
|
||||||
|
}>(
|
||||||
|
"/users",
|
||||||
|
{
|
||||||
|
schema: {
|
||||||
|
body: {
|
||||||
|
type: "object",
|
||||||
|
required: ["name", "email"],
|
||||||
|
properties: {
|
||||||
|
name: { type: "string", minLength: 1 },
|
||||||
|
email: { type: "string", format: "email" },
|
||||||
|
},
|
||||||
|
},
|
||||||
|
},
|
||||||
|
},
|
||||||
|
async (request, reply) => {
|
||||||
|
const { name, email } = request.body;
|
||||||
|
return { id: "123", name };
|
||||||
|
},
|
||||||
|
);
|
||||||
|
|
||||||
|
await fastify.listen({ port: 3000, host: "0.0.0.0" });
|
||||||
|
```
|
||||||
|
|
||||||
|
## Architectural Patterns
|
||||||
|
|
||||||
|
### Pattern 1: Layered Architecture
|
||||||
|
|
||||||
|
**Structure:**
|
||||||
|
|
||||||
|
```
|
||||||
|
src/
|
||||||
|
├── controllers/ # Handle HTTP requests/responses
|
||||||
|
├── services/ # Business logic
|
||||||
|
├── repositories/ # Data access layer
|
||||||
|
├── models/ # Data models
|
||||||
|
├── middleware/ # Express/Fastify middleware
|
||||||
|
├── routes/ # Route definitions
|
||||||
|
├── utils/ # Helper functions
|
||||||
|
├── config/ # Configuration
|
||||||
|
└── types/ # TypeScript types
|
||||||
|
```
|
||||||
|
|
||||||
|
**Controller Layer:**
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// controllers/user.controller.ts
|
||||||
|
import { Request, Response, NextFunction } from "express";
|
||||||
|
import { UserService } from "../services/user.service";
|
||||||
|
import { CreateUserDTO, UpdateUserDTO } from "../types/user.types";
|
||||||
|
|
||||||
|
export class UserController {
|
||||||
|
constructor(private userService: UserService) {}
|
||||||
|
|
||||||
|
async createUser(req: Request, res: Response, next: NextFunction) {
|
||||||
|
try {
|
||||||
|
const userData: CreateUserDTO = req.body;
|
||||||
|
const user = await this.userService.createUser(userData);
|
||||||
|
res.status(201).json(user);
|
||||||
|
} catch (error) {
|
||||||
|
next(error);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
async getUser(req: Request, res: Response, next: NextFunction) {
|
||||||
|
try {
|
||||||
|
const { id } = req.params;
|
||||||
|
const user = await this.userService.getUserById(id);
|
||||||
|
res.json(user);
|
||||||
|
} catch (error) {
|
||||||
|
next(error);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
async updateUser(req: Request, res: Response, next: NextFunction) {
|
||||||
|
try {
|
||||||
|
const { id } = req.params;
|
||||||
|
const updates: UpdateUserDTO = req.body;
|
||||||
|
const user = await this.userService.updateUser(id, updates);
|
||||||
|
res.json(user);
|
||||||
|
} catch (error) {
|
||||||
|
next(error);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
async deleteUser(req: Request, res: Response, next: NextFunction) {
|
||||||
|
try {
|
||||||
|
const { id } = req.params;
|
||||||
|
await this.userService.deleteUser(id);
|
||||||
|
res.status(204).send();
|
||||||
|
} catch (error) {
|
||||||
|
next(error);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Service Layer:**
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// services/user.service.ts
|
||||||
|
import { UserRepository } from "../repositories/user.repository";
|
||||||
|
import { CreateUserDTO, UpdateUserDTO, User } from "../types/user.types";
|
||||||
|
import { NotFoundError, ValidationError } from "../utils/errors";
|
||||||
|
import bcrypt from "bcrypt";
|
||||||
|
|
||||||
|
export class UserService {
|
||||||
|
constructor(private userRepository: UserRepository) {}
|
||||||
|
|
||||||
|
async createUser(userData: CreateUserDTO): Promise<User> {
|
||||||
|
// Validation
|
||||||
|
const existingUser = await this.userRepository.findByEmail(userData.email);
|
||||||
|
if (existingUser) {
|
||||||
|
throw new ValidationError("Email already exists");
|
||||||
|
}
|
||||||
|
|
||||||
|
// Hash password
|
||||||
|
const hashedPassword = await bcrypt.hash(userData.password, 10);
|
||||||
|
|
||||||
|
// Create user
|
||||||
|
const user = await this.userRepository.create({
|
||||||
|
...userData,
|
||||||
|
password: hashedPassword,
|
||||||
|
});
|
||||||
|
|
||||||
|
// Remove password from response
|
||||||
|
const { password, ...userWithoutPassword } = user;
|
||||||
|
return userWithoutPassword as User;
|
||||||
|
}
|
||||||
|
|
||||||
|
async getUserById(id: string): Promise<User> {
|
||||||
|
const user = await this.userRepository.findById(id);
|
||||||
|
if (!user) {
|
||||||
|
throw new NotFoundError("User not found");
|
||||||
|
}
|
||||||
|
const { password, ...userWithoutPassword } = user;
|
||||||
|
return userWithoutPassword as User;
|
||||||
|
}
|
||||||
|
|
||||||
|
async updateUser(id: string, updates: UpdateUserDTO): Promise<User> {
|
||||||
|
const user = await this.userRepository.update(id, updates);
|
||||||
|
if (!user) {
|
||||||
|
throw new NotFoundError("User not found");
|
||||||
|
}
|
||||||
|
const { password, ...userWithoutPassword } = user;
|
||||||
|
return userWithoutPassword as User;
|
||||||
|
}
|
||||||
|
|
||||||
|
async deleteUser(id: string): Promise<void> {
|
||||||
|
const deleted = await this.userRepository.delete(id);
|
||||||
|
if (!deleted) {
|
||||||
|
throw new NotFoundError("User not found");
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Repository Layer:**
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// repositories/user.repository.ts
|
||||||
|
import { Pool } from "pg";
|
||||||
|
import { CreateUserDTO, UpdateUserDTO, UserEntity } from "../types/user.types";
|
||||||
|
|
||||||
|
export class UserRepository {
|
||||||
|
constructor(private db: Pool) {}
|
||||||
|
|
||||||
|
async create(
|
||||||
|
userData: CreateUserDTO & { password: string },
|
||||||
|
): Promise<UserEntity> {
|
||||||
|
const query = `
|
||||||
|
INSERT INTO users (name, email, password)
|
||||||
|
VALUES ($1, $2, $3)
|
||||||
|
RETURNING id, name, email, password, created_at, updated_at
|
||||||
|
`;
|
||||||
|
const { rows } = await this.db.query(query, [
|
||||||
|
userData.name,
|
||||||
|
userData.email,
|
||||||
|
userData.password,
|
||||||
|
]);
|
||||||
|
return rows[0];
|
||||||
|
}
|
||||||
|
|
||||||
|
async findById(id: string): Promise<UserEntity | null> {
|
||||||
|
const query = "SELECT * FROM users WHERE id = $1";
|
||||||
|
const { rows } = await this.db.query(query, [id]);
|
||||||
|
return rows[0] || null;
|
||||||
|
}
|
||||||
|
|
||||||
|
async findByEmail(email: string): Promise<UserEntity | null> {
|
||||||
|
const query = "SELECT * FROM users WHERE email = $1";
|
||||||
|
const { rows } = await this.db.query(query, [email]);
|
||||||
|
return rows[0] || null;
|
||||||
|
}
|
||||||
|
|
||||||
|
async update(id: string, updates: UpdateUserDTO): Promise<UserEntity | null> {
|
||||||
|
const fields = Object.keys(updates);
|
||||||
|
const values = Object.values(updates);
|
||||||
|
|
||||||
|
const setClause = fields
|
||||||
|
.map((field, idx) => `${field} = $${idx + 2}`)
|
||||||
|
.join(", ");
|
||||||
|
|
||||||
|
const query = `
|
||||||
|
UPDATE users
|
||||||
|
SET ${setClause}, updated_at = CURRENT_TIMESTAMP
|
||||||
|
WHERE id = $1
|
||||||
|
RETURNING *
|
||||||
|
`;
|
||||||
|
|
||||||
|
const { rows } = await this.db.query(query, [id, ...values]);
|
||||||
|
return rows[0] || null;
|
||||||
|
}
|
||||||
|
|
||||||
|
async delete(id: string): Promise<boolean> {
|
||||||
|
const query = "DELETE FROM users WHERE id = $1";
|
||||||
|
const { rowCount } = await this.db.query(query, [id]);
|
||||||
|
return rowCount > 0;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pattern 2: Dependency Injection
|
||||||
|
|
||||||
|
Use a DI container to wire up repositories, services, and controllers. For a full container implementation, see [references/advanced-patterns.md](references/advanced-patterns.md).
|
||||||
|
|
||||||
|
## Middleware Patterns
|
||||||
|
|
||||||
|
### Authentication Middleware
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// middleware/auth.middleware.ts
|
||||||
|
import { Request, Response, NextFunction } from "express";
|
||||||
|
import jwt from "jsonwebtoken";
|
||||||
|
import { UnauthorizedError } from "../utils/errors";
|
||||||
|
|
||||||
|
interface JWTPayload {
|
||||||
|
userId: string;
|
||||||
|
email: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
declare global {
|
||||||
|
namespace Express {
|
||||||
|
interface Request {
|
||||||
|
user?: JWTPayload;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
export const authenticate = async (
|
||||||
|
req: Request,
|
||||||
|
res: Response,
|
||||||
|
next: NextFunction,
|
||||||
|
) => {
|
||||||
|
try {
|
||||||
|
const token = req.headers.authorization?.replace("Bearer ", "");
|
||||||
|
|
||||||
|
if (!token) {
|
||||||
|
throw new UnauthorizedError("No token provided");
|
||||||
|
}
|
||||||
|
|
||||||
|
const payload = jwt.verify(token, process.env.JWT_SECRET!) as JWTPayload;
|
||||||
|
|
||||||
|
req.user = payload;
|
||||||
|
next();
|
||||||
|
} catch (error) {
|
||||||
|
next(new UnauthorizedError("Invalid token"));
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
export const authorize = (...roles: string[]) => {
|
||||||
|
return async (req: Request, res: Response, next: NextFunction) => {
|
||||||
|
if (!req.user) {
|
||||||
|
return next(new UnauthorizedError("Not authenticated"));
|
||||||
|
}
|
||||||
|
|
||||||
|
// Check if user has required role
|
||||||
|
const hasRole = roles.some((role) => req.user?.roles?.includes(role));
|
||||||
|
|
||||||
|
if (!hasRole) {
|
||||||
|
return next(new UnauthorizedError("Insufficient permissions"));
|
||||||
|
}
|
||||||
|
|
||||||
|
next();
|
||||||
|
};
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### Validation Middleware
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// middleware/validation.middleware.ts
|
||||||
|
import { Request, Response, NextFunction } from "express";
|
||||||
|
import { AnyZodObject, ZodError } from "zod";
|
||||||
|
import { ValidationError } from "../utils/errors";
|
||||||
|
|
||||||
|
export const validate = (schema: AnyZodObject) => {
|
||||||
|
return async (req: Request, res: Response, next: NextFunction) => {
|
||||||
|
try {
|
||||||
|
await schema.parseAsync({
|
||||||
|
body: req.body,
|
||||||
|
query: req.query,
|
||||||
|
params: req.params,
|
||||||
|
});
|
||||||
|
next();
|
||||||
|
} catch (error) {
|
||||||
|
if (error instanceof ZodError) {
|
||||||
|
const errors = error.errors.map((err) => ({
|
||||||
|
field: err.path.join("."),
|
||||||
|
message: err.message,
|
||||||
|
}));
|
||||||
|
next(new ValidationError("Validation failed", errors));
|
||||||
|
} else {
|
||||||
|
next(error);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
};
|
||||||
|
};
|
||||||
|
|
||||||
|
// Usage with Zod
|
||||||
|
import { z } from "zod";
|
||||||
|
|
||||||
|
const createUserSchema = z.object({
|
||||||
|
body: z.object({
|
||||||
|
name: z.string().min(1),
|
||||||
|
email: z.string().email(),
|
||||||
|
password: z.string().min(8),
|
||||||
|
}),
|
||||||
|
});
|
||||||
|
|
||||||
|
router.post("/users", validate(createUserSchema), userController.createUser);
|
||||||
|
```
|
||||||
|
|
||||||
|
### Rate Limiting Middleware
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// middleware/rate-limit.middleware.ts
|
||||||
|
import rateLimit from "express-rate-limit";
|
||||||
|
import RedisStore from "rate-limit-redis";
|
||||||
|
import Redis from "ioredis";
|
||||||
|
|
||||||
|
const redis = new Redis({
|
||||||
|
host: process.env.REDIS_HOST,
|
||||||
|
port: parseInt(process.env.REDIS_PORT || "6379"),
|
||||||
|
});
|
||||||
|
|
||||||
|
export const apiLimiter = rateLimit({
|
||||||
|
store: new RedisStore({
|
||||||
|
client: redis,
|
||||||
|
prefix: "rl:",
|
||||||
|
}),
|
||||||
|
windowMs: 15 * 60 * 1000, // 15 minutes
|
||||||
|
max: 100, // Limit each IP to 100 requests per windowMs
|
||||||
|
message: "Too many requests from this IP, please try again later",
|
||||||
|
standardHeaders: true,
|
||||||
|
legacyHeaders: false,
|
||||||
|
});
|
||||||
|
|
||||||
|
export const authLimiter = rateLimit({
|
||||||
|
store: new RedisStore({
|
||||||
|
client: redis,
|
||||||
|
prefix: "rl:auth:",
|
||||||
|
}),
|
||||||
|
windowMs: 15 * 60 * 1000,
|
||||||
|
max: 5, // Stricter limit for auth endpoints
|
||||||
|
skipSuccessfulRequests: true,
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Request Logging Middleware
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// middleware/logger.middleware.ts
|
||||||
|
import { Request, Response, NextFunction } from "express";
|
||||||
|
import pino from "pino";
|
||||||
|
|
||||||
|
const logger = pino({
|
||||||
|
level: process.env.LOG_LEVEL || "info",
|
||||||
|
transport: {
|
||||||
|
target: "pino-pretty",
|
||||||
|
options: { colorize: true },
|
||||||
|
},
|
||||||
|
});
|
||||||
|
|
||||||
|
export const requestLogger = (
|
||||||
|
req: Request,
|
||||||
|
res: Response,
|
||||||
|
next: NextFunction,
|
||||||
|
) => {
|
||||||
|
const start = Date.now();
|
||||||
|
|
||||||
|
// Log response when finished
|
||||||
|
res.on("finish", () => {
|
||||||
|
const duration = Date.now() - start;
|
||||||
|
logger.info({
|
||||||
|
method: req.method,
|
||||||
|
url: req.url,
|
||||||
|
status: res.statusCode,
|
||||||
|
duration: `${duration}ms`,
|
||||||
|
userAgent: req.headers["user-agent"],
|
||||||
|
ip: req.ip,
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
next();
|
||||||
|
};
|
||||||
|
|
||||||
|
export { logger };
|
||||||
|
```
|
||||||
|
|
||||||
|
## Error Handling
|
||||||
|
|
||||||
|
### Custom Error Classes
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// utils/errors.ts
|
||||||
|
export class AppError extends Error {
|
||||||
|
constructor(
|
||||||
|
public message: string,
|
||||||
|
public statusCode: number = 500,
|
||||||
|
public isOperational: boolean = true,
|
||||||
|
) {
|
||||||
|
super(message);
|
||||||
|
Object.setPrototypeOf(this, AppError.prototype);
|
||||||
|
Error.captureStackTrace(this, this.constructor);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
export class ValidationError extends AppError {
|
||||||
|
constructor(
|
||||||
|
message: string,
|
||||||
|
public errors?: any[],
|
||||||
|
) {
|
||||||
|
super(message, 400);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
export class NotFoundError extends AppError {
|
||||||
|
constructor(message: string = "Resource not found") {
|
||||||
|
super(message, 404);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
export class UnauthorizedError extends AppError {
|
||||||
|
constructor(message: string = "Unauthorized") {
|
||||||
|
super(message, 401);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
export class ForbiddenError extends AppError {
|
||||||
|
constructor(message: string = "Forbidden") {
|
||||||
|
super(message, 403);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
export class ConflictError extends AppError {
|
||||||
|
constructor(message: string) {
|
||||||
|
super(message, 409);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Global Error Handler
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// middleware/error-handler.ts
|
||||||
|
import { Request, Response, NextFunction } from "express";
|
||||||
|
import { AppError } from "../utils/errors";
|
||||||
|
import { logger } from "./logger.middleware";
|
||||||
|
|
||||||
|
export const errorHandler = (
|
||||||
|
err: Error,
|
||||||
|
req: Request,
|
||||||
|
res: Response,
|
||||||
|
next: NextFunction,
|
||||||
|
) => {
|
||||||
|
if (err instanceof AppError) {
|
||||||
|
return res.status(err.statusCode).json({
|
||||||
|
status: "error",
|
||||||
|
message: err.message,
|
||||||
|
...(err instanceof ValidationError && { errors: err.errors }),
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
// Log unexpected errors
|
||||||
|
logger.error({
|
||||||
|
error: err.message,
|
||||||
|
stack: err.stack,
|
||||||
|
url: req.url,
|
||||||
|
method: req.method,
|
||||||
|
});
|
||||||
|
|
||||||
|
// Don't leak error details in production
|
||||||
|
const message =
|
||||||
|
process.env.NODE_ENV === "production"
|
||||||
|
? "Internal server error"
|
||||||
|
: err.message;
|
||||||
|
|
||||||
|
res.status(500).json({
|
||||||
|
status: "error",
|
||||||
|
message,
|
||||||
|
});
|
||||||
|
};
|
||||||
|
|
||||||
|
// Async error wrapper
|
||||||
|
export const asyncHandler = (
|
||||||
|
fn: (req: Request, res: Response, next: NextFunction) => Promise<any>,
|
||||||
|
) => {
|
||||||
|
return (req: Request, res: Response, next: NextFunction) => {
|
||||||
|
Promise.resolve(fn(req, res, next)).catch(next);
|
||||||
|
};
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
## Database Patterns
|
||||||
|
|
||||||
|
Node.js supports both SQL and NoSQL databases. Use connection pooling for all production databases.
|
||||||
|
|
||||||
|
Key patterns covered in [references/advanced-patterns.md](references/advanced-patterns.md):
|
||||||
|
- **PostgreSQL with connection pool** — `pg` Pool configuration and graceful shutdown
|
||||||
|
- **MongoDB with Mongoose** — connection management and schema definition
|
||||||
|
- **Transaction pattern** — `BEGIN`/`COMMIT`/`ROLLBACK` with `pg` client
|
||||||
|
|
||||||
|
## Authentication & Authorization
|
||||||
|
|
||||||
|
JWT-based auth with access tokens (short-lived, 15m) and refresh tokens (7d). Full `AuthService` implementation with `bcrypt` password comparison in [references/advanced-patterns.md](references/advanced-patterns.md).
|
||||||
|
|
||||||
|
## Caching Strategies
|
||||||
|
|
||||||
|
Redis-backed `CacheService` with get/set/delete/invalidatePattern, plus a `@Cacheable` decorator for method-level caching. See [references/advanced-patterns.md](references/advanced-patterns.md).
|
||||||
|
|
||||||
|
## API Response Format
|
||||||
|
|
||||||
|
Standardized `ApiResponse` helper with `success`, `error`, and `paginated` static methods. See [references/advanced-patterns.md](references/advanced-patterns.md).
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
1. **Use TypeScript**: Type safety prevents runtime errors
|
||||||
|
2. **Implement proper error handling**: Use custom error classes
|
||||||
|
3. **Validate input**: Use libraries like Zod or Joi
|
||||||
|
4. **Use environment variables**: Never hardcode secrets
|
||||||
|
5. **Implement logging**: Use structured logging (Pino, Winston)
|
||||||
|
6. **Add rate limiting**: Prevent abuse
|
||||||
|
7. **Use HTTPS**: Always in production
|
||||||
|
8. **Implement CORS properly**: Don't use `*` in production
|
||||||
|
9. **Use dependency injection**: Easier testing and maintenance
|
||||||
|
10. **Write tests**: Unit, integration, and E2E tests
|
||||||
|
11. **Handle graceful shutdown**: Clean up resources
|
||||||
|
12. **Use connection pooling**: For databases
|
||||||
|
13. **Implement health checks**: For monitoring
|
||||||
|
14. **Use compression**: Reduce response size
|
||||||
|
15. **Monitor performance**: Use APM tools
|
||||||
|
|
||||||
|
## Testing Patterns
|
||||||
|
|
||||||
|
See `javascript-testing-patterns` skill for comprehensive testing guidance.
|
||||||
@@ -0,0 +1,430 @@
|
|||||||
|
# Node.js Advanced Patterns
|
||||||
|
|
||||||
|
Advanced patterns for dependency injection, database integration, authentication, caching, and API response formatting.
|
||||||
|
|
||||||
|
## Dependency Injection
|
||||||
|
|
||||||
|
### DI Container
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// di-container.ts
|
||||||
|
import { Pool } from "pg";
|
||||||
|
import { UserRepository } from "./repositories/user.repository";
|
||||||
|
import { UserService } from "./services/user.service";
|
||||||
|
import { UserController } from "./controllers/user.controller";
|
||||||
|
import { AuthService } from "./services/auth.service";
|
||||||
|
|
||||||
|
class Container {
|
||||||
|
private instances = new Map<string, any>();
|
||||||
|
|
||||||
|
register<T>(key: string, factory: () => T): void {
|
||||||
|
this.instances.set(key, factory);
|
||||||
|
}
|
||||||
|
|
||||||
|
resolve<T>(key: string): T {
|
||||||
|
const factory = this.instances.get(key);
|
||||||
|
if (!factory) {
|
||||||
|
throw new Error(`No factory registered for ${key}`);
|
||||||
|
}
|
||||||
|
return factory();
|
||||||
|
}
|
||||||
|
|
||||||
|
singleton<T>(key: string, factory: () => T): void {
|
||||||
|
let instance: T;
|
||||||
|
this.instances.set(key, () => {
|
||||||
|
if (!instance) {
|
||||||
|
instance = factory();
|
||||||
|
}
|
||||||
|
return instance;
|
||||||
|
});
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
export const container = new Container();
|
||||||
|
|
||||||
|
// Register dependencies
|
||||||
|
container.singleton(
|
||||||
|
"db",
|
||||||
|
() =>
|
||||||
|
new Pool({
|
||||||
|
host: process.env.DB_HOST,
|
||||||
|
port: parseInt(process.env.DB_PORT || "5432"),
|
||||||
|
database: process.env.DB_NAME,
|
||||||
|
user: process.env.DB_USER,
|
||||||
|
password: process.env.DB_PASSWORD,
|
||||||
|
max: 20,
|
||||||
|
idleTimeoutMillis: 30000,
|
||||||
|
connectionTimeoutMillis: 2000,
|
||||||
|
}),
|
||||||
|
);
|
||||||
|
|
||||||
|
container.singleton(
|
||||||
|
"userRepository",
|
||||||
|
() => new UserRepository(container.resolve("db")),
|
||||||
|
);
|
||||||
|
|
||||||
|
container.singleton(
|
||||||
|
"userService",
|
||||||
|
() => new UserService(container.resolve("userRepository")),
|
||||||
|
);
|
||||||
|
|
||||||
|
container.register(
|
||||||
|
"userController",
|
||||||
|
() => new UserController(container.resolve("userService")),
|
||||||
|
);
|
||||||
|
|
||||||
|
container.singleton(
|
||||||
|
"authService",
|
||||||
|
() => new AuthService(container.resolve("userRepository")),
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
## Database Patterns
|
||||||
|
|
||||||
|
### PostgreSQL with Connection Pool
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// config/database.ts
|
||||||
|
import { Pool, PoolConfig } from "pg";
|
||||||
|
|
||||||
|
const poolConfig: PoolConfig = {
|
||||||
|
host: process.env.DB_HOST,
|
||||||
|
port: parseInt(process.env.DB_PORT || "5432"),
|
||||||
|
database: process.env.DB_NAME,
|
||||||
|
user: process.env.DB_USER,
|
||||||
|
password: process.env.DB_PASSWORD,
|
||||||
|
max: 20,
|
||||||
|
idleTimeoutMillis: 30000,
|
||||||
|
connectionTimeoutMillis: 2000,
|
||||||
|
};
|
||||||
|
|
||||||
|
export const pool = new Pool(poolConfig);
|
||||||
|
|
||||||
|
// Test connection
|
||||||
|
pool.on("connect", () => {
|
||||||
|
console.log("Database connected");
|
||||||
|
});
|
||||||
|
|
||||||
|
pool.on("error", (err) => {
|
||||||
|
console.error("Unexpected database error", err);
|
||||||
|
process.exit(-1);
|
||||||
|
});
|
||||||
|
|
||||||
|
// Graceful shutdown
|
||||||
|
export const closeDatabase = async () => {
|
||||||
|
await pool.end();
|
||||||
|
console.log("Database connection closed");
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### MongoDB with Mongoose
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// config/mongoose.ts
|
||||||
|
import mongoose from "mongoose";
|
||||||
|
|
||||||
|
const connectDB = async () => {
|
||||||
|
try {
|
||||||
|
await mongoose.connect(process.env.MONGODB_URI!, {
|
||||||
|
maxPoolSize: 10,
|
||||||
|
serverSelectionTimeoutMS: 5000,
|
||||||
|
socketTimeoutMS: 45000,
|
||||||
|
});
|
||||||
|
|
||||||
|
console.log("MongoDB connected");
|
||||||
|
} catch (error) {
|
||||||
|
console.error("MongoDB connection error:", error);
|
||||||
|
process.exit(1);
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
mongoose.connection.on("disconnected", () => {
|
||||||
|
console.log("MongoDB disconnected");
|
||||||
|
});
|
||||||
|
|
||||||
|
mongoose.connection.on("error", (err) => {
|
||||||
|
console.error("MongoDB error:", err);
|
||||||
|
});
|
||||||
|
|
||||||
|
export { connectDB };
|
||||||
|
|
||||||
|
// Model example
|
||||||
|
import { Schema, model, Document } from "mongoose";
|
||||||
|
|
||||||
|
interface IUser extends Document {
|
||||||
|
name: string;
|
||||||
|
email: string;
|
||||||
|
password: string;
|
||||||
|
createdAt: Date;
|
||||||
|
updatedAt: Date;
|
||||||
|
}
|
||||||
|
|
||||||
|
const userSchema = new Schema<IUser>(
|
||||||
|
{
|
||||||
|
name: { type: String, required: true },
|
||||||
|
email: { type: String, required: true, unique: true },
|
||||||
|
password: { type: String, required: true },
|
||||||
|
},
|
||||||
|
{
|
||||||
|
timestamps: true,
|
||||||
|
},
|
||||||
|
);
|
||||||
|
|
||||||
|
// Indexes
|
||||||
|
userSchema.index({ email: 1 });
|
||||||
|
|
||||||
|
export const User = model<IUser>("User", userSchema);
|
||||||
|
```
|
||||||
|
|
||||||
|
### Transaction Pattern
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// services/order.service.ts
|
||||||
|
import { Pool } from "pg";
|
||||||
|
|
||||||
|
export class OrderService {
|
||||||
|
constructor(private db: Pool) {}
|
||||||
|
|
||||||
|
async createOrder(userId: string, items: any[]) {
|
||||||
|
const client = await this.db.connect();
|
||||||
|
|
||||||
|
try {
|
||||||
|
await client.query("BEGIN");
|
||||||
|
|
||||||
|
// Create order
|
||||||
|
const orderResult = await client.query(
|
||||||
|
"INSERT INTO orders (user_id, total) VALUES ($1, $2) RETURNING id",
|
||||||
|
[userId, calculateTotal(items)],
|
||||||
|
);
|
||||||
|
const orderId = orderResult.rows[0].id;
|
||||||
|
|
||||||
|
// Create order items
|
||||||
|
for (const item of items) {
|
||||||
|
await client.query(
|
||||||
|
"INSERT INTO order_items (order_id, product_id, quantity, price) VALUES ($1, $2, $3, $4)",
|
||||||
|
[orderId, item.productId, item.quantity, item.price],
|
||||||
|
);
|
||||||
|
|
||||||
|
// Update inventory
|
||||||
|
await client.query(
|
||||||
|
"UPDATE products SET stock = stock - $1 WHERE id = $2",
|
||||||
|
[item.quantity, item.productId],
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
await client.query("COMMIT");
|
||||||
|
return orderId;
|
||||||
|
} catch (error) {
|
||||||
|
await client.query("ROLLBACK");
|
||||||
|
throw error;
|
||||||
|
} finally {
|
||||||
|
client.release();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Authentication & Authorization
|
||||||
|
|
||||||
|
### JWT Authentication
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// services/auth.service.ts
|
||||||
|
import jwt from "jsonwebtoken";
|
||||||
|
import bcrypt from "bcrypt";
|
||||||
|
import { UserRepository } from "../repositories/user.repository";
|
||||||
|
import { UnauthorizedError } from "../utils/errors";
|
||||||
|
|
||||||
|
export class AuthService {
|
||||||
|
constructor(private userRepository: UserRepository) {}
|
||||||
|
|
||||||
|
async login(email: string, password: string) {
|
||||||
|
const user = await this.userRepository.findByEmail(email);
|
||||||
|
|
||||||
|
if (!user) {
|
||||||
|
throw new UnauthorizedError("Invalid credentials");
|
||||||
|
}
|
||||||
|
|
||||||
|
const isValid = await bcrypt.compare(password, user.password);
|
||||||
|
|
||||||
|
if (!isValid) {
|
||||||
|
throw new UnauthorizedError("Invalid credentials");
|
||||||
|
}
|
||||||
|
|
||||||
|
const token = this.generateToken({
|
||||||
|
userId: user.id,
|
||||||
|
email: user.email,
|
||||||
|
});
|
||||||
|
|
||||||
|
const refreshToken = this.generateRefreshToken({
|
||||||
|
userId: user.id,
|
||||||
|
});
|
||||||
|
|
||||||
|
return {
|
||||||
|
token,
|
||||||
|
refreshToken,
|
||||||
|
user: {
|
||||||
|
id: user.id,
|
||||||
|
name: user.name,
|
||||||
|
email: user.email,
|
||||||
|
},
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
async refreshToken(refreshToken: string) {
|
||||||
|
try {
|
||||||
|
const payload = jwt.verify(
|
||||||
|
refreshToken,
|
||||||
|
process.env.REFRESH_TOKEN_SECRET!,
|
||||||
|
) as { userId: string };
|
||||||
|
|
||||||
|
const user = await this.userRepository.findById(payload.userId);
|
||||||
|
|
||||||
|
if (!user) {
|
||||||
|
throw new UnauthorizedError("User not found");
|
||||||
|
}
|
||||||
|
|
||||||
|
const token = this.generateToken({
|
||||||
|
userId: user.id,
|
||||||
|
email: user.email,
|
||||||
|
});
|
||||||
|
|
||||||
|
return { token };
|
||||||
|
} catch (error) {
|
||||||
|
throw new UnauthorizedError("Invalid refresh token");
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
private generateToken(payload: any): string {
|
||||||
|
return jwt.sign(payload, process.env.JWT_SECRET!, {
|
||||||
|
expiresIn: "15m",
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
private generateRefreshToken(payload: any): string {
|
||||||
|
return jwt.sign(payload, process.env.REFRESH_TOKEN_SECRET!, {
|
||||||
|
expiresIn: "7d",
|
||||||
|
});
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Caching Strategies
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// utils/cache.ts
|
||||||
|
import Redis from "ioredis";
|
||||||
|
|
||||||
|
const redis = new Redis({
|
||||||
|
host: process.env.REDIS_HOST,
|
||||||
|
port: parseInt(process.env.REDIS_PORT || "6379"),
|
||||||
|
retryStrategy: (times) => {
|
||||||
|
const delay = Math.min(times * 50, 2000);
|
||||||
|
return delay;
|
||||||
|
},
|
||||||
|
});
|
||||||
|
|
||||||
|
export class CacheService {
|
||||||
|
async get<T>(key: string): Promise<T | null> {
|
||||||
|
const data = await redis.get(key);
|
||||||
|
return data ? JSON.parse(data) : null;
|
||||||
|
}
|
||||||
|
|
||||||
|
async set(key: string, value: any, ttl?: number): Promise<void> {
|
||||||
|
const serialized = JSON.stringify(value);
|
||||||
|
if (ttl) {
|
||||||
|
await redis.setex(key, ttl, serialized);
|
||||||
|
} else {
|
||||||
|
await redis.set(key, serialized);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
async delete(key: string): Promise<void> {
|
||||||
|
await redis.del(key);
|
||||||
|
}
|
||||||
|
|
||||||
|
async invalidatePattern(pattern: string): Promise<void> {
|
||||||
|
const keys = await redis.keys(pattern);
|
||||||
|
if (keys.length > 0) {
|
||||||
|
await redis.del(...keys);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Cache decorator
|
||||||
|
export function Cacheable(ttl: number = 300) {
|
||||||
|
return function (
|
||||||
|
target: any,
|
||||||
|
propertyKey: string,
|
||||||
|
descriptor: PropertyDescriptor,
|
||||||
|
) {
|
||||||
|
const originalMethod = descriptor.value;
|
||||||
|
|
||||||
|
descriptor.value = async function (...args: any[]) {
|
||||||
|
const cache = new CacheService();
|
||||||
|
const cacheKey = `${propertyKey}:${JSON.stringify(args)}`;
|
||||||
|
|
||||||
|
const cached = await cache.get(cacheKey);
|
||||||
|
if (cached) {
|
||||||
|
return cached;
|
||||||
|
}
|
||||||
|
|
||||||
|
const result = await originalMethod.apply(this, args);
|
||||||
|
await cache.set(cacheKey, result, ttl);
|
||||||
|
|
||||||
|
return result;
|
||||||
|
};
|
||||||
|
|
||||||
|
return descriptor;
|
||||||
|
};
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## API Response Format
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// utils/response.ts
|
||||||
|
import { Response } from "express";
|
||||||
|
|
||||||
|
export class ApiResponse {
|
||||||
|
static success<T>(
|
||||||
|
res: Response,
|
||||||
|
data: T,
|
||||||
|
message?: string,
|
||||||
|
statusCode = 200,
|
||||||
|
) {
|
||||||
|
return res.status(statusCode).json({
|
||||||
|
status: "success",
|
||||||
|
message,
|
||||||
|
data,
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
static error(res: Response, message: string, statusCode = 500, errors?: any) {
|
||||||
|
return res.status(statusCode).json({
|
||||||
|
status: "error",
|
||||||
|
message,
|
||||||
|
...(errors && { errors }),
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
static paginated<T>(
|
||||||
|
res: Response,
|
||||||
|
data: T[],
|
||||||
|
page: number,
|
||||||
|
limit: number,
|
||||||
|
total: number,
|
||||||
|
) {
|
||||||
|
return res.json({
|
||||||
|
status: "success",
|
||||||
|
data,
|
||||||
|
pagination: {
|
||||||
|
page,
|
||||||
|
limit,
|
||||||
|
total,
|
||||||
|
pages: Math.ceil(total / limit),
|
||||||
|
},
|
||||||
|
});
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
343
.agents/skills/nodejs-best-practices/SKILL.md
Normal file
343
.agents/skills/nodejs-best-practices/SKILL.md
Normal file
@@ -0,0 +1,343 @@
|
|||||||
|
---
|
||||||
|
name: nodejs-best-practices
|
||||||
|
description: "Node.js development principles and decision-making. Framework selection, async patterns, security, and architecture. Teaches thinking, not copying."
|
||||||
|
risk: unknown
|
||||||
|
source: community
|
||||||
|
date_added: "2026-02-27"
|
||||||
|
---
|
||||||
|
|
||||||
|
# Node.js Best Practices
|
||||||
|
|
||||||
|
> Principles and decision-making for Node.js development in 2025.
|
||||||
|
> **Learn to THINK, not memorize code patterns.**
|
||||||
|
|
||||||
|
## When to Use
|
||||||
|
Use this skill when making Node.js architecture decisions, choosing frameworks, designing async patterns, or applying security and deployment best practices.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ⚠️ How to Use This Skill
|
||||||
|
|
||||||
|
This skill teaches **decision-making principles**, not fixed code to copy.
|
||||||
|
|
||||||
|
- ASK user for preferences when unclear
|
||||||
|
- Choose framework/pattern based on CONTEXT
|
||||||
|
- Don't default to same solution every time
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Framework Selection (2025)
|
||||||
|
|
||||||
|
### Decision Tree
|
||||||
|
|
||||||
|
```
|
||||||
|
What are you building?
|
||||||
|
│
|
||||||
|
├── Edge/Serverless (Cloudflare, Vercel)
|
||||||
|
│ └── Hono (zero-dependency, ultra-fast cold starts)
|
||||||
|
│
|
||||||
|
├── High Performance API
|
||||||
|
│ └── Fastify (2-3x faster than Express)
|
||||||
|
│
|
||||||
|
├── Enterprise/Team familiarity
|
||||||
|
│ └── NestJS (structured, DI, decorators)
|
||||||
|
│
|
||||||
|
├── Legacy/Stable/Maximum ecosystem
|
||||||
|
│ └── Express (mature, most middleware)
|
||||||
|
│
|
||||||
|
└── Full-stack with frontend
|
||||||
|
└── Next.js API Routes or tRPC
|
||||||
|
```
|
||||||
|
|
||||||
|
### Comparison Principles
|
||||||
|
|
||||||
|
| Factor | Hono | Fastify | Express |
|
||||||
|
|--------|------|---------|---------|
|
||||||
|
| **Best for** | Edge, serverless | Performance | Legacy, learning |
|
||||||
|
| **Cold start** | Fastest | Fast | Moderate |
|
||||||
|
| **Ecosystem** | Growing | Good | Largest |
|
||||||
|
| **TypeScript** | Native | Excellent | Good |
|
||||||
|
| **Learning curve** | Low | Medium | Low |
|
||||||
|
|
||||||
|
### Selection Questions to Ask:
|
||||||
|
1. What's the deployment target?
|
||||||
|
2. Is cold start time critical?
|
||||||
|
3. Does team have existing experience?
|
||||||
|
4. Is there legacy code to maintain?
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Runtime Considerations (2025)
|
||||||
|
|
||||||
|
### Native TypeScript
|
||||||
|
|
||||||
|
```
|
||||||
|
Node.js 22+: --experimental-strip-types
|
||||||
|
├── Run .ts files directly
|
||||||
|
├── No build step needed for simple projects
|
||||||
|
└── Consider for: scripts, simple APIs
|
||||||
|
```
|
||||||
|
|
||||||
|
### Module System Decision
|
||||||
|
|
||||||
|
```
|
||||||
|
ESM (import/export)
|
||||||
|
├── Modern standard
|
||||||
|
├── Better tree-shaking
|
||||||
|
├── Async module loading
|
||||||
|
└── Use for: new projects
|
||||||
|
|
||||||
|
CommonJS (require)
|
||||||
|
├── Legacy compatibility
|
||||||
|
├── More npm packages support
|
||||||
|
└── Use for: existing codebases, some edge cases
|
||||||
|
```
|
||||||
|
|
||||||
|
### Runtime Selection
|
||||||
|
|
||||||
|
| Runtime | Best For |
|
||||||
|
|---------|----------|
|
||||||
|
| **Node.js** | General purpose, largest ecosystem |
|
||||||
|
| **Bun** | Performance, built-in bundler |
|
||||||
|
| **Deno** | Security-first, built-in TypeScript |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Architecture Principles
|
||||||
|
|
||||||
|
### Layered Structure Concept
|
||||||
|
|
||||||
|
```
|
||||||
|
Request Flow:
|
||||||
|
│
|
||||||
|
├── Controller/Route Layer
|
||||||
|
│ ├── Handles HTTP specifics
|
||||||
|
│ ├── Input validation at boundary
|
||||||
|
│ └── Calls service layer
|
||||||
|
│
|
||||||
|
├── Service Layer
|
||||||
|
│ ├── Business logic
|
||||||
|
│ ├── Framework-agnostic
|
||||||
|
│ └── Calls repository layer
|
||||||
|
│
|
||||||
|
└── Repository Layer
|
||||||
|
├── Data access only
|
||||||
|
├── Database queries
|
||||||
|
└── ORM interactions
|
||||||
|
```
|
||||||
|
|
||||||
|
### Why This Matters:
|
||||||
|
- **Testability**: Mock layers independently
|
||||||
|
- **Flexibility**: Swap database without touching business logic
|
||||||
|
- **Clarity**: Each layer has single responsibility
|
||||||
|
|
||||||
|
### When to Simplify:
|
||||||
|
- Small scripts → Single file OK
|
||||||
|
- Prototypes → Less structure acceptable
|
||||||
|
- Always ask: "Will this grow?"
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Error Handling Principles
|
||||||
|
|
||||||
|
### Centralized Error Handling
|
||||||
|
|
||||||
|
```
|
||||||
|
Pattern:
|
||||||
|
├── Create custom error classes
|
||||||
|
├── Throw from any layer
|
||||||
|
├── Catch at top level (middleware)
|
||||||
|
└── Format consistent response
|
||||||
|
```
|
||||||
|
|
||||||
|
### Error Response Philosophy
|
||||||
|
|
||||||
|
```
|
||||||
|
Client gets:
|
||||||
|
├── Appropriate HTTP status
|
||||||
|
├── Error code for programmatic handling
|
||||||
|
├── User-friendly message
|
||||||
|
└── NO internal details (security!)
|
||||||
|
|
||||||
|
Logs get:
|
||||||
|
├── Full stack trace
|
||||||
|
├── Request context
|
||||||
|
├── User ID (if applicable)
|
||||||
|
└── Timestamp
|
||||||
|
```
|
||||||
|
|
||||||
|
### Status Code Selection
|
||||||
|
|
||||||
|
| Situation | Status | When |
|
||||||
|
|-----------|--------|------|
|
||||||
|
| Bad input | 400 | Client sent invalid data |
|
||||||
|
| No auth | 401 | Missing or invalid credentials |
|
||||||
|
| No permission | 403 | Valid auth, but not allowed |
|
||||||
|
| Not found | 404 | Resource doesn't exist |
|
||||||
|
| Conflict | 409 | Duplicate or state conflict |
|
||||||
|
| Validation | 422 | Schema valid but business rules fail |
|
||||||
|
| Server error | 500 | Our fault, log everything |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Async Patterns Principles
|
||||||
|
|
||||||
|
### When to Use Each
|
||||||
|
|
||||||
|
| Pattern | Use When |
|
||||||
|
|---------|----------|
|
||||||
|
| `async/await` | Sequential async operations |
|
||||||
|
| `Promise.all` | Parallel independent operations |
|
||||||
|
| `Promise.allSettled` | Parallel where some can fail |
|
||||||
|
| `Promise.race` | Timeout or first response wins |
|
||||||
|
|
||||||
|
### Event Loop Awareness
|
||||||
|
|
||||||
|
```
|
||||||
|
I/O-bound (async helps):
|
||||||
|
├── Database queries
|
||||||
|
├── HTTP requests
|
||||||
|
├── File system
|
||||||
|
└── Network operations
|
||||||
|
|
||||||
|
CPU-bound (async doesn't help):
|
||||||
|
├── Crypto operations
|
||||||
|
├── Image processing
|
||||||
|
├── Complex calculations
|
||||||
|
└── → Use worker threads or offload
|
||||||
|
```
|
||||||
|
|
||||||
|
### Avoiding Event Loop Blocking
|
||||||
|
|
||||||
|
- Never use sync methods in production (fs.readFileSync, etc.)
|
||||||
|
- Offload CPU-intensive work
|
||||||
|
- Use streaming for large data
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Validation Principles
|
||||||
|
|
||||||
|
### Validate at Boundaries
|
||||||
|
|
||||||
|
```
|
||||||
|
Where to validate:
|
||||||
|
├── API entry point (request body/params)
|
||||||
|
├── Before database operations
|
||||||
|
├── External data (API responses, file uploads)
|
||||||
|
└── Environment variables (startup)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Validation Library Selection
|
||||||
|
|
||||||
|
| Library | Best For |
|
||||||
|
|---------|----------|
|
||||||
|
| **Zod** | TypeScript first, inference |
|
||||||
|
| **Valibot** | Smaller bundle (tree-shakeable) |
|
||||||
|
| **ArkType** | Performance critical |
|
||||||
|
| **Yup** | Existing React Form usage |
|
||||||
|
|
||||||
|
### Validation Philosophy
|
||||||
|
|
||||||
|
- Fail fast: Validate early
|
||||||
|
- Be specific: Clear error messages
|
||||||
|
- Don't trust: Even "internal" data
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Security Principles
|
||||||
|
|
||||||
|
### Security Checklist (Not Code)
|
||||||
|
|
||||||
|
- [ ] **Input validation**: All inputs validated
|
||||||
|
- [ ] **Parameterized queries**: No string concatenation for SQL
|
||||||
|
- [ ] **Password hashing**: bcrypt or argon2
|
||||||
|
- [ ] **JWT verification**: Always verify signature and expiry
|
||||||
|
- [ ] **Rate limiting**: Protect from abuse
|
||||||
|
- [ ] **Security headers**: Helmet.js or equivalent
|
||||||
|
- [ ] **HTTPS**: Everywhere in production
|
||||||
|
- [ ] **CORS**: Properly configured
|
||||||
|
- [ ] **Secrets**: Environment variables only
|
||||||
|
- [ ] **Dependencies**: Regularly audited
|
||||||
|
|
||||||
|
### Security Mindset
|
||||||
|
|
||||||
|
```
|
||||||
|
Trust nothing:
|
||||||
|
├── Query params → validate
|
||||||
|
├── Request body → validate
|
||||||
|
├── Headers → verify
|
||||||
|
├── Cookies → validate
|
||||||
|
├── File uploads → scan
|
||||||
|
└── External APIs → validate response
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Testing Principles
|
||||||
|
|
||||||
|
### Test Strategy Selection
|
||||||
|
|
||||||
|
| Type | Purpose | Tools |
|
||||||
|
|------|---------|-------|
|
||||||
|
| **Unit** | Business logic | node:test, Vitest |
|
||||||
|
| **Integration** | API endpoints | Supertest |
|
||||||
|
| **E2E** | Full flows | Playwright |
|
||||||
|
|
||||||
|
### What to Test (Priorities)
|
||||||
|
|
||||||
|
1. **Critical paths**: Auth, payments, core business
|
||||||
|
2. **Edge cases**: Empty inputs, boundaries
|
||||||
|
3. **Error handling**: What happens when things fail?
|
||||||
|
4. **Not worth testing**: Framework code, trivial getters
|
||||||
|
|
||||||
|
### Built-in Test Runner (Node.js 22+)
|
||||||
|
|
||||||
|
```
|
||||||
|
node --test src/**/*.test.ts
|
||||||
|
├── No external dependency
|
||||||
|
├── Good coverage reporting
|
||||||
|
└── Watch mode available
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. Anti-Patterns to Avoid
|
||||||
|
|
||||||
|
### ❌ DON'T:
|
||||||
|
- Use Express for new edge projects (use Hono)
|
||||||
|
- Use sync methods in production code
|
||||||
|
- Put business logic in controllers
|
||||||
|
- Skip input validation
|
||||||
|
- Hardcode secrets
|
||||||
|
- Trust external data without validation
|
||||||
|
- Block event loop with CPU work
|
||||||
|
|
||||||
|
### ✅ DO:
|
||||||
|
- Choose framework based on context
|
||||||
|
- Ask user for preferences when unclear
|
||||||
|
- Use layered architecture for growing projects
|
||||||
|
- Validate all inputs
|
||||||
|
- Use environment variables for secrets
|
||||||
|
- Profile before optimizing
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. Decision Checklist
|
||||||
|
|
||||||
|
Before implementing:
|
||||||
|
|
||||||
|
- [ ] **Asked user about stack preference?**
|
||||||
|
- [ ] **Chosen framework for THIS context?** (not just default)
|
||||||
|
- [ ] **Considered deployment target?**
|
||||||
|
- [ ] **Planned error handling strategy?**
|
||||||
|
- [ ] **Identified validation points?**
|
||||||
|
- [ ] **Considered security requirements?**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
> **Remember**: Node.js best practices are about decision-making, not memorizing patterns. Every project deserves fresh consideration based on its requirements.
|
||||||
|
|
||||||
|
## Limitations
|
||||||
|
- Use this skill only when the task clearly matches the scope described above.
|
||||||
|
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
|
||||||
|
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
|
||||||
513
.agents/skills/seo/SKILL.md
Normal file
513
.agents/skills/seo/SKILL.md
Normal file
@@ -0,0 +1,513 @@
|
|||||||
|
---
|
||||||
|
name: seo
|
||||||
|
description: Optimize for search engine visibility and ranking. Use when asked to "improve SEO", "optimize for search", "fix meta tags", "add structured data", "sitemap optimization", or "search engine optimization".
|
||||||
|
license: MIT
|
||||||
|
metadata:
|
||||||
|
author: web-quality-skills
|
||||||
|
version: "1.0"
|
||||||
|
---
|
||||||
|
|
||||||
|
# SEO optimization
|
||||||
|
|
||||||
|
Search engine optimization based on Lighthouse SEO audits and Google Search guidelines. Focus on technical SEO, on-page optimization, and structured data.
|
||||||
|
|
||||||
|
## SEO fundamentals
|
||||||
|
|
||||||
|
Search ranking factors (approximate influence):
|
||||||
|
|
||||||
|
| Factor | Influence | This Skill |
|
||||||
|
|--------|-----------|------------|
|
||||||
|
| Content quality & relevance | ~40% | Partial (structure) |
|
||||||
|
| Backlinks & authority | ~25% | ✗ |
|
||||||
|
| Technical SEO | ~15% | ✓ |
|
||||||
|
| Page experience (Core Web Vitals) | ~10% | See [Core Web Vitals](../core-web-vitals/SKILL.md) |
|
||||||
|
| On-page SEO | ~10% | ✓ |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Technical SEO
|
||||||
|
|
||||||
|
### Crawlability
|
||||||
|
|
||||||
|
**robots.txt:**
|
||||||
|
```text
|
||||||
|
# /robots.txt
|
||||||
|
User-agent: *
|
||||||
|
Allow: /
|
||||||
|
|
||||||
|
# Block admin/private areas
|
||||||
|
Disallow: /admin/
|
||||||
|
Disallow: /api/
|
||||||
|
Disallow: /private/
|
||||||
|
|
||||||
|
# Don't block resources needed for rendering
|
||||||
|
# ❌ Disallow: /static/
|
||||||
|
|
||||||
|
Sitemap: https://example.com/sitemap.xml
|
||||||
|
```
|
||||||
|
|
||||||
|
**Meta robots:**
|
||||||
|
```html
|
||||||
|
<!-- Default: indexable, followable -->
|
||||||
|
<meta name="robots" content="index, follow">
|
||||||
|
|
||||||
|
<!-- Noindex specific pages -->
|
||||||
|
<meta name="robots" content="noindex, nofollow">
|
||||||
|
|
||||||
|
<!-- Indexable but don't follow links -->
|
||||||
|
<meta name="robots" content="index, nofollow">
|
||||||
|
|
||||||
|
<!-- Control snippets -->
|
||||||
|
<meta name="robots" content="max-snippet:150, max-image-preview:large">
|
||||||
|
```
|
||||||
|
|
||||||
|
**Canonical URLs:**
|
||||||
|
```html
|
||||||
|
<!-- Prevent duplicate content issues -->
|
||||||
|
<link rel="canonical" href="https://example.com/page">
|
||||||
|
|
||||||
|
<!-- Self-referencing canonical (recommended) -->
|
||||||
|
<link rel="canonical" href="https://example.com/current-page">
|
||||||
|
|
||||||
|
<!-- For paginated content -->
|
||||||
|
<link rel="canonical" href="https://example.com/products">
|
||||||
|
<!-- Or use rel="prev" / rel="next" for explicit pagination -->
|
||||||
|
```
|
||||||
|
|
||||||
|
### XML sitemap
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
|
||||||
|
<url>
|
||||||
|
<loc>https://example.com/</loc>
|
||||||
|
<lastmod>2024-01-15</lastmod>
|
||||||
|
<changefreq>daily</changefreq>
|
||||||
|
<priority>1.0</priority>
|
||||||
|
</url>
|
||||||
|
<url>
|
||||||
|
<loc>https://example.com/products</loc>
|
||||||
|
<lastmod>2024-01-14</lastmod>
|
||||||
|
<changefreq>weekly</changefreq>
|
||||||
|
<priority>0.8</priority>
|
||||||
|
</url>
|
||||||
|
</urlset>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Sitemap best practices:**
|
||||||
|
- Maximum 50,000 URLs or 50MB per sitemap
|
||||||
|
- Use sitemap index for larger sites
|
||||||
|
- Include only canonical, indexable URLs
|
||||||
|
- Update `lastmod` when content changes
|
||||||
|
- Submit to Google Search Console
|
||||||
|
|
||||||
|
### URL structure
|
||||||
|
|
||||||
|
```
|
||||||
|
✅ Good URLs:
|
||||||
|
https://example.com/products/blue-widget
|
||||||
|
https://example.com/blog/how-to-use-widgets
|
||||||
|
|
||||||
|
❌ Poor URLs:
|
||||||
|
https://example.com/p?id=12345
|
||||||
|
https://example.com/products/item/category/subcategory/blue-widget-2024-sale-discount
|
||||||
|
```
|
||||||
|
|
||||||
|
**URL guidelines:**
|
||||||
|
- Use hyphens, not underscores
|
||||||
|
- Lowercase only
|
||||||
|
- Keep short (< 75 characters)
|
||||||
|
- Include target keywords naturally
|
||||||
|
- Avoid parameters when possible
|
||||||
|
- Use HTTPS always
|
||||||
|
|
||||||
|
### HTTPS & security
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- Ensure all resources use HTTPS -->
|
||||||
|
<img src="https://example.com/image.jpg">
|
||||||
|
|
||||||
|
<!-- Not: -->
|
||||||
|
<img src="http://example.com/image.jpg">
|
||||||
|
```
|
||||||
|
|
||||||
|
**Security headers for SEO trust signals:**
|
||||||
|
```
|
||||||
|
Strict-Transport-Security: max-age=31536000; includeSubDomains
|
||||||
|
X-Content-Type-Options: nosniff
|
||||||
|
X-Frame-Options: DENY
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## On-page SEO
|
||||||
|
|
||||||
|
### Title tags
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- ❌ Missing or generic -->
|
||||||
|
<title>Page</title>
|
||||||
|
<title>Home</title>
|
||||||
|
|
||||||
|
<!-- ✅ Descriptive with primary keyword -->
|
||||||
|
<title>Blue Widgets for Sale | Premium Quality | Example Store</title>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Title tag guidelines:**
|
||||||
|
- 50-60 characters (Google truncates ~60)
|
||||||
|
- Primary keyword near the beginning
|
||||||
|
- Unique for every page
|
||||||
|
- Brand name at end (unless homepage)
|
||||||
|
- Action-oriented when appropriate
|
||||||
|
|
||||||
|
### Meta descriptions
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- ❌ Missing or duplicate -->
|
||||||
|
<meta name="description" content="">
|
||||||
|
|
||||||
|
<!-- ✅ Compelling and unique -->
|
||||||
|
<meta name="description" content="Shop premium blue widgets with free shipping. 30-day returns. Rated 4.9/5 by 10,000+ customers. Order today and save 20%.">
|
||||||
|
```
|
||||||
|
|
||||||
|
**Meta description guidelines:**
|
||||||
|
- 150-160 characters
|
||||||
|
- Include primary keyword naturally
|
||||||
|
- Compelling call-to-action
|
||||||
|
- Unique for every page
|
||||||
|
- Matches page content
|
||||||
|
|
||||||
|
### Heading structure
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- ❌ Poor structure -->
|
||||||
|
<h2>Welcome to Our Store</h2>
|
||||||
|
<h4>Products</h4>
|
||||||
|
<h1>Contact Us</h1>
|
||||||
|
|
||||||
|
<!-- ✅ Proper hierarchy -->
|
||||||
|
<h1>Blue Widgets - Premium Quality</h1>
|
||||||
|
<h2>Product Features</h2>
|
||||||
|
<h3>Durability</h3>
|
||||||
|
<h3>Design</h3>
|
||||||
|
<h2>Customer Reviews</h2>
|
||||||
|
<h2>Pricing</h2>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Heading guidelines:**
|
||||||
|
- Single `<h1>` per page (the main topic)
|
||||||
|
- Logical hierarchy (don't skip levels)
|
||||||
|
- Include keywords naturally
|
||||||
|
- Descriptive, not generic
|
||||||
|
|
||||||
|
### Image SEO
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- ❌ Poor image SEO -->
|
||||||
|
<img src="IMG_12345.jpg">
|
||||||
|
|
||||||
|
<!-- ✅ Optimized image -->
|
||||||
|
<img src="blue-widget-product-photo.webp"
|
||||||
|
alt="Blue widget with chrome finish, side view showing control panel"
|
||||||
|
width="800"
|
||||||
|
height="600"
|
||||||
|
loading="lazy">
|
||||||
|
```
|
||||||
|
|
||||||
|
**Image guidelines:**
|
||||||
|
- Descriptive filenames with keywords
|
||||||
|
- Alt text describes the image content
|
||||||
|
- Compressed and properly sized
|
||||||
|
- WebP/AVIF with fallbacks
|
||||||
|
- Lazy load below-fold images
|
||||||
|
|
||||||
|
### Internal linking
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- ❌ Non-descriptive -->
|
||||||
|
<a href="/products">Click here</a>
|
||||||
|
<a href="/widgets">Read more</a>
|
||||||
|
|
||||||
|
<!-- ✅ Descriptive anchor text -->
|
||||||
|
<a href="/products/blue-widgets">Browse our blue widget collection</a>
|
||||||
|
<a href="/guides/widget-maintenance">Learn how to maintain your widgets</a>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Linking guidelines:**
|
||||||
|
- Descriptive anchor text with keywords
|
||||||
|
- Link to relevant internal pages
|
||||||
|
- Reasonable number of links per page
|
||||||
|
- Fix broken links promptly
|
||||||
|
- Use breadcrumbs for hierarchy
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Structured data (JSON-LD)
|
||||||
|
|
||||||
|
### Organization
|
||||||
|
|
||||||
|
```html
|
||||||
|
<script type="application/ld+json">
|
||||||
|
{
|
||||||
|
"@context": "https://schema.org",
|
||||||
|
"@type": "Organization",
|
||||||
|
"name": "Example Company",
|
||||||
|
"url": "https://example.com",
|
||||||
|
"logo": "https://example.com/logo.png",
|
||||||
|
"sameAs": [
|
||||||
|
"https://twitter.com/example",
|
||||||
|
"https://linkedin.com/company/example"
|
||||||
|
],
|
||||||
|
"contactPoint": {
|
||||||
|
"@type": "ContactPoint",
|
||||||
|
"telephone": "+1-555-123-4567",
|
||||||
|
"contactType": "customer service"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
</script>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Article
|
||||||
|
|
||||||
|
```html
|
||||||
|
<script type="application/ld+json">
|
||||||
|
{
|
||||||
|
"@context": "https://schema.org",
|
||||||
|
"@type": "Article",
|
||||||
|
"headline": "How to Choose the Right Widget",
|
||||||
|
"description": "Complete guide to selecting widgets for your needs.",
|
||||||
|
"image": "https://example.com/article-image.jpg",
|
||||||
|
"author": {
|
||||||
|
"@type": "Person",
|
||||||
|
"name": "Jane Smith",
|
||||||
|
"url": "https://example.com/authors/jane-smith"
|
||||||
|
},
|
||||||
|
"publisher": {
|
||||||
|
"@type": "Organization",
|
||||||
|
"name": "Example Blog",
|
||||||
|
"logo": {
|
||||||
|
"@type": "ImageObject",
|
||||||
|
"url": "https://example.com/logo.png"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"datePublished": "2024-01-15",
|
||||||
|
"dateModified": "2024-01-20"
|
||||||
|
}
|
||||||
|
</script>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Product
|
||||||
|
|
||||||
|
```html
|
||||||
|
<script type="application/ld+json">
|
||||||
|
{
|
||||||
|
"@context": "https://schema.org",
|
||||||
|
"@type": "Product",
|
||||||
|
"name": "Blue Widget Pro",
|
||||||
|
"image": "https://example.com/blue-widget.jpg",
|
||||||
|
"description": "Premium blue widget with advanced features.",
|
||||||
|
"brand": {
|
||||||
|
"@type": "Brand",
|
||||||
|
"name": "WidgetCo"
|
||||||
|
},
|
||||||
|
"offers": {
|
||||||
|
"@type": "Offer",
|
||||||
|
"price": "49.99",
|
||||||
|
"priceCurrency": "USD",
|
||||||
|
"availability": "https://schema.org/InStock",
|
||||||
|
"url": "https://example.com/products/blue-widget"
|
||||||
|
},
|
||||||
|
"aggregateRating": {
|
||||||
|
"@type": "AggregateRating",
|
||||||
|
"ratingValue": "4.8",
|
||||||
|
"reviewCount": "1250"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
</script>
|
||||||
|
```
|
||||||
|
|
||||||
|
### FAQ
|
||||||
|
|
||||||
|
```html
|
||||||
|
<script type="application/ld+json">
|
||||||
|
{
|
||||||
|
"@context": "https://schema.org",
|
||||||
|
"@type": "FAQPage",
|
||||||
|
"mainEntity": [
|
||||||
|
{
|
||||||
|
"@type": "Question",
|
||||||
|
"name": "What colors are available?",
|
||||||
|
"acceptedAnswer": {
|
||||||
|
"@type": "Answer",
|
||||||
|
"text": "Our widgets come in blue, red, and green."
|
||||||
|
}
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"@type": "Question",
|
||||||
|
"name": "What is the warranty?",
|
||||||
|
"acceptedAnswer": {
|
||||||
|
"@type": "Answer",
|
||||||
|
"text": "All widgets include a 2-year warranty."
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
</script>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Breadcrumbs
|
||||||
|
|
||||||
|
```html
|
||||||
|
<script type="application/ld+json">
|
||||||
|
{
|
||||||
|
"@context": "https://schema.org",
|
||||||
|
"@type": "BreadcrumbList",
|
||||||
|
"itemListElement": [
|
||||||
|
{
|
||||||
|
"@type": "ListItem",
|
||||||
|
"position": 1,
|
||||||
|
"name": "Home",
|
||||||
|
"item": "https://example.com"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"@type": "ListItem",
|
||||||
|
"position": 2,
|
||||||
|
"name": "Products",
|
||||||
|
"item": "https://example.com/products"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"@type": "ListItem",
|
||||||
|
"position": 3,
|
||||||
|
"name": "Blue Widgets",
|
||||||
|
"item": "https://example.com/products/blue-widgets"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
</script>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Validation
|
||||||
|
|
||||||
|
Test structured data at:
|
||||||
|
- [Google Rich Results Test](https://search.google.com/test/rich-results)
|
||||||
|
- [Schema.org Validator](https://validator.schema.org/)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Mobile SEO
|
||||||
|
|
||||||
|
### Responsive design
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- ❌ Not mobile-friendly -->
|
||||||
|
<meta name="viewport" content="width=1024">
|
||||||
|
|
||||||
|
<!-- ✅ Responsive viewport -->
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||||
|
```
|
||||||
|
|
||||||
|
### Tap targets
|
||||||
|
|
||||||
|
```css
|
||||||
|
/* ❌ Too small for mobile */
|
||||||
|
.small-link {
|
||||||
|
padding: 4px;
|
||||||
|
font-size: 12px;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* ✅ Adequate tap target */
|
||||||
|
.mobile-friendly-link {
|
||||||
|
padding: 12px;
|
||||||
|
font-size: 16px;
|
||||||
|
min-height: 48px;
|
||||||
|
min-width: 48px;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Font sizes
|
||||||
|
|
||||||
|
```css
|
||||||
|
/* ❌ Too small on mobile */
|
||||||
|
body {
|
||||||
|
font-size: 10px;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* ✅ Readable without zooming */
|
||||||
|
body {
|
||||||
|
font-size: 16px;
|
||||||
|
line-height: 1.5;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## International SEO
|
||||||
|
|
||||||
|
### Hreflang tags
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- For multi-language sites -->
|
||||||
|
<link rel="alternate" hreflang="en" href="https://example.com/page">
|
||||||
|
<link rel="alternate" hreflang="es" href="https://example.com/es/page">
|
||||||
|
<link rel="alternate" hreflang="fr" href="https://example.com/fr/page">
|
||||||
|
<link rel="alternate" hreflang="x-default" href="https://example.com/page">
|
||||||
|
```
|
||||||
|
|
||||||
|
### Language declaration
|
||||||
|
|
||||||
|
```html
|
||||||
|
<html lang="en">
|
||||||
|
<!-- or -->
|
||||||
|
<html lang="es-MX">
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## SEO audit checklist
|
||||||
|
|
||||||
|
### Critical
|
||||||
|
- [ ] HTTPS enabled
|
||||||
|
- [ ] robots.txt allows crawling
|
||||||
|
- [ ] No `noindex` on important pages
|
||||||
|
- [ ] Title tags present and unique
|
||||||
|
- [ ] Single `<h1>` per page
|
||||||
|
|
||||||
|
### High priority
|
||||||
|
- [ ] Meta descriptions present
|
||||||
|
- [ ] Sitemap submitted
|
||||||
|
- [ ] Canonical URLs set
|
||||||
|
- [ ] Mobile-responsive
|
||||||
|
- [ ] Core Web Vitals passing
|
||||||
|
|
||||||
|
### Medium priority
|
||||||
|
- [ ] Structured data implemented
|
||||||
|
- [ ] Internal linking strategy
|
||||||
|
- [ ] Image alt text
|
||||||
|
- [ ] Descriptive URLs
|
||||||
|
- [ ] Breadcrumb navigation
|
||||||
|
|
||||||
|
### Ongoing
|
||||||
|
- [ ] Fix crawl errors in Search Console
|
||||||
|
- [ ] Update sitemap when content changes
|
||||||
|
- [ ] Monitor ranking changes
|
||||||
|
- [ ] Check for broken links
|
||||||
|
- [ ] Review Search Console insights
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tools
|
||||||
|
|
||||||
|
| Tool | Use |
|
||||||
|
|------|-----|
|
||||||
|
| Google Search Console | Monitor indexing, fix issues |
|
||||||
|
| Google PageSpeed Insights | Performance + Core Web Vitals |
|
||||||
|
| Rich Results Test | Validate structured data |
|
||||||
|
| Lighthouse | Full SEO audit |
|
||||||
|
| Screaming Frog | Crawl analysis |
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
- [Google Search Central](https://developers.google.com/search)
|
||||||
|
- [Schema.org](https://schema.org/)
|
||||||
|
- [Core Web Vitals](../core-web-vitals/SKILL.md)
|
||||||
|
- [Web Quality Audit](../web-quality-audit/SKILL.md)
|
||||||
69
AGENTS.md
69
AGENTS.md
@@ -12,8 +12,10 @@ dice widgets, shared markdown, sounds). It is a two-app monorepo:
|
|||||||
- `backend/` — Node + **Express 5** + **Mongoose 9** (MongoDB) REST API, JWT auth. CommonJS.
|
- `backend/` — Node + **Express 5** + **Mongoose 9** (MongoDB) REST API, JWT auth. CommonJS.
|
||||||
- `frontend/` — **Nuxt 4 / Vue 3** client (Composition API, `<script setup>`), SCSS, axios, marked, mitt, motion.
|
- `frontend/` — **Nuxt 4 / Vue 3** client (Composition API, `<script setup>`), SCSS, axios, marked, mitt, motion.
|
||||||
|
|
||||||
There is **no** database seeding, no ORM migrations, no test suite, no linter/formatter config, no
|
There is **no** database seeding, no ORM migrations, no linter/formatter config, no Pinia/Vuex, and no
|
||||||
Pinia/Vuex, and no Vue Router pages (see §5.1 — the UI is a window manager, not routed pages).
|
Vue Router pages (see §5.1 — the UI is a window manager, not routed pages). The only automated tests
|
||||||
|
are `tests/*.test.js` (`npm test`, Node's built-in runner), which exercise the Foundry module's sync
|
||||||
|
logic against stubbed Foundry globals.
|
||||||
|
|
||||||
Git: default branch `master`, hosted on a self-hosted Gitea (`git.aranroig.com/BinarySandia04/Dragonroll`).
|
Git: default branch `master`, hosted on a self-hosted Gitea (`git.aranroig.com/BinarySandia04/Dragonroll`).
|
||||||
CI (`.gitea/workflows/deploy.yml`) builds two Docker images on every push to `master`, pushes them to
|
CI (`.gitea/workflows/deploy.yml`) builds two Docker images on every push to `master`, pushes them to
|
||||||
@@ -26,11 +28,13 @@ CI (`.gitea/workflows/deploy.yml`) builds two Docker images on every push to `ma
|
|||||||
dragonroll/
|
dragonroll/
|
||||||
├── backend/ Express API (CommonJS, entry: src/index.js)
|
├── backend/ Express API (CommonJS, entry: src/index.js)
|
||||||
├── frontend/ Nuxt 4 app (entry: app/app.vue)
|
├── frontend/ Nuxt 4 app (entry: app/app.vue)
|
||||||
|
├── obsidian-plugin/ Plain JavaScript Obsidian plugin for campaign note import/push
|
||||||
├── docker-compose.yml nginx :3000 -> frontend :3000, /api -> backend :5000
|
├── docker-compose.yml nginx :3000 -> frontend :3000, /api -> backend :5000
|
||||||
├── nginx.conf reverse proxy rules for the compose stack
|
├── nginx.conf reverse proxy rules for the compose stack
|
||||||
├── ecosystem.config.js PM2 config (stale: runs `npm start`, which does not exist — see §9)
|
├── ecosystem.config.js PM2 config (stale: runs `npm start`, which does not exist — see §9)
|
||||||
├── .gitea/workflows/deploy.yml
|
├── .gitea/workflows/deploy.yml
|
||||||
├── static/media/ README logo images only
|
├── static/media/ README logo images only
|
||||||
|
├── tests/ `node --test` tests (Foundry module sync toggle)
|
||||||
├── package.json root: only `concurrently`, used by `npm run dev`
|
├── package.json root: only `concurrently`, used by `npm run dev`
|
||||||
└── README.md install/run instructions are STALE (see §9)
|
└── README.md install/run instructions are STALE (see §9)
|
||||||
```
|
```
|
||||||
@@ -49,10 +53,13 @@ npm --prefix backend run dev # backend only
|
|||||||
npm --prefix frontend run dev # frontend only
|
npm --prefix frontend run dev # frontend only
|
||||||
npm --prefix frontend run build # nuxt build --dotenv .env.production
|
npm --prefix frontend run build # nuxt build --dotenv .env.production
|
||||||
npm --prefix frontend run preview
|
npm --prefix frontend run preview
|
||||||
|
|
||||||
|
npm test # node --test tests/ (Foundry module sync logic, no dependencies)
|
||||||
```
|
```
|
||||||
|
|
||||||
There is no `start` script in either package, no test command, and no lint command.
|
There is no `start` script in either package and no lint command.
|
||||||
Verification = run the dev server and exercise the flow (`/api/test` returns a JSON hello).
|
Verification = run the dev server and exercise the flow (`/api/test` returns a JSON hello);
|
||||||
|
`npm test` covers the Foundry character/item sync toggle and per-actor force sync.
|
||||||
|
|
||||||
### Environment files
|
### Environment files
|
||||||
|
|
||||||
@@ -152,7 +159,7 @@ User ──< Campaign ──< Note ──?> Folder ──?> Folder (parentFolder
|
|||||||
| `Folder` | `models/Folder.js` | `name*`, `campaign*` → Campaign, `parentFolder` → Folder (null = root), `color` (hex string, sidebar entry background), `date` |
|
| `Folder` | `models/Folder.js` | `name*`, `campaign*` → Campaign, `parentFolder` → Folder (null = root), `color` (hex string, sidebar entry background), `date` |
|
||||||
| `Actor` | `models/Actor.js` | `name*`, `type` (`character`\|`npc`\|`creature`), `species`, `className`, `subclass`, `level`, `background`, `challengeRating`, `description`, `image`, `abilityScores{str..cha}`, `armorClass`, `speed`, `proficiencies`, `inventory[{name,quantity,weight}]` (flattened Foundry items, embedded — not `Item` docs), `traits`, `spells` (newline text), `campaign*` → Campaign, `foundryActorId` (unique per campaign), `date` |
|
| `Actor` | `models/Actor.js` | `name*`, `type` (`character`\|`npc`\|`creature`), `species`, `className`, `subclass`, `level`, `background`, `challengeRating`, `description`, `image`, `abilityScores{str..cha}`, `armorClass`, `speed`, `proficiencies`, `inventory[{name,quantity,weight}]` (flattened Foundry items, embedded — not `Item` docs), `traits`, `spells` (newline text), `campaign*` → Campaign, `foundryActorId` (unique per campaign), `date` |
|
||||||
| `Item` | `models/Item.js` | `name*`, `category` (`weapon`\|`armor`\|`shield`\|`adventuring-gear`\|`magic-item`\|`consumable`\|`tool`\|`treasure`\|`other`), `rarity` (`common`…`artifact`), `quantity`, `weight`, `properties`, `description`, `campaign*` → Campaign, `foundryItemId` (unique per campaign), `foundryNames` (names Foundry uses for it, keeps dedup stable across a Dragonroll rename), `date` |
|
| `Item` | `models/Item.js` | `name*`, `category` (`weapon`\|`armor`\|`shield`\|`adventuring-gear`\|`magic-item`\|`consumable`\|`tool`\|`treasure`\|`other`), `rarity` (`common`…`artifact`), `quantity`, `weight`, `properties`, `description`, `campaign*` → Campaign, `foundryItemId` (unique per campaign), `foundryNames` (names Foundry uses for it, keeps dedup stable across a Dragonroll rename), `date` |
|
||||||
| `Map` | `models/Map.js` | `name*`, `image` (filename in `src/uploads`), `gridSize` (cell size in image px), `offsetX`/`offsetY` (grid origin in image px), `scale` (distance one cell stands for), `campaign*` → Campaign, `date` |
|
| `Map` | `models/Map.js` | `name*`, `image` (filename in `src/uploads`), `gridSize` (cell size in image px), `offsetX`/`offsetY` (grid origin in image px), `scale` (distance one cell stands for), `pins[{note → Note, x, y}]` (a note pinned at image px coordinates, addressed by its own `_id`), `campaign*` → Campaign, `date` |
|
||||||
|
|
||||||
`*` = required. Notes and folders are ordered by `date: -1` everywhere.
|
`*` = required. Notes and folders are ordered by `date: -1` everywhere.
|
||||||
|
|
||||||
@@ -183,11 +190,15 @@ Fetch the file from `/api/public/<filename>`.
|
|||||||
`GET /api/campaign/list` → `{status:'ok',campaigns}`
|
`GET /api/campaign/list` → `{status:'ok',campaigns}`
|
||||||
`GET /api/campaign/retrieve/:id` → `{status:'ok',campaign}` (401 when no `req.user.id`)
|
`GET /api/campaign/retrieve/:id` → `{status:'ok',campaign}` (401 when no `req.user.id`)
|
||||||
|
|
||||||
`GET /api/note/list?campaign=` → `{status:'ok', folders, notes}` — notes with `folder: null` (roots)
|
`GET /api/note/list?campaign=` → `{status:'ok', folders, notes}` — notes with `folder: null` (roots);
|
||||||
|
folder entries include `parentFolder` so clients can rebuild nested folder paths
|
||||||
`GET /api/note/subfolder/list?campaign=&folder=` → `{status:'ok', subfolders, notes}`
|
`GET /api/note/subfolder/list?campaign=&folder=` → `{status:'ok', subfolders, notes}`
|
||||||
|
`GET /api/note/all?campaign=` → `{status:'ok', notes, folders}` — every note of the campaign, titles
|
||||||
|
only (no `content`); the map viewer's note picker and its pin labels
|
||||||
|
`GET /api/note/retrieve/:id` → `{status:'ok',note}` — one note with its content, ownership checked
|
||||||
`POST /api/note/create` — `{title*,content,campaign*,folder?}` (folder validated against campaign)
|
`POST /api/note/create` — `{title*,content,campaign*,folder?}` (folder validated against campaign)
|
||||||
`POST /api/note/update` — `{id*, title?, content?, folder?, color?}` — partial, ownership checked
|
`POST /api/note/update` — `{id*, title?, content?, folder?, color?}` — partial, ownership checked
|
||||||
`POST /api/note/delete` — `{id}` — **no ownership check** (§9)
|
`POST /api/note/delete` — `{id}` — **no ownership check** (§9); pulls the note off every map's `pins`
|
||||||
|
|
||||||
`GET /api/folder/list?campaign=` → `{status:'ok',folders}`
|
`GET /api/folder/list?campaign=` → `{status:'ok',folders}`
|
||||||
`POST /api/folder/create` — `{name*,campaign*}`
|
`POST /api/folder/create` — `{name*,campaign*}`
|
||||||
@@ -214,6 +225,9 @@ subfolders re-parented to null then deleted.
|
|||||||
`POST /api/map/update` — `{id*, name?, gridSize?, offsetX?, offsetY?, scale?}`, partial, ownership checked. Send it as
|
`POST /api/map/update` — `{id*, name?, gridSize?, offsetX?, offsetY?, scale?}`, partial, ownership checked. Send it as
|
||||||
multipart with an `image` field to replace the photo (multer reads the other fields from the form; JSON works too).
|
multipart with an `image` field to replace the photo (multer reads the other fields from the form; JSON works too).
|
||||||
`POST /api/map/delete` — `{id}`
|
`POST /api/map/delete` — `{id}`
|
||||||
|
`POST /api/map/pin` — `{id*, note*, x, y}` — pins a note of the same campaign at those image px;
|
||||||
|
pinning a note that is pinned already moves that marker → `{status:'ok',map}`
|
||||||
|
`POST /api/map/unpin` — `{id*, pin*}` (`pin` is the subdocument `_id`) → `{status:'ok',map}`
|
||||||
|
|
||||||
### 4.1 Foundry integration (actors, items)
|
### 4.1 Foundry integration (actors, items)
|
||||||
|
|
||||||
@@ -233,6 +247,7 @@ not `Campaign.foundryWorldId` (`syncCampaign` / `requestMatchesWorld`). CORS is
|
|||||||
| `POST /sync/item-delete` | `{worldId, foundryItemId}` — a world item was deleted |
|
| `POST /sync/item-delete` | `{worldId, foundryItemId}` — a world item was deleted |
|
||||||
| `GET /sync/characters` | Actors the module applies back into Foundry |
|
| `GET /sync/characters` | Actors the module applies back into Foundry |
|
||||||
| `GET /sync/items` | Items the module applies back into Foundry (creates world items for Dragonroll-authored ones) |
|
| `GET /sync/items` | Items the module applies back into Foundry (creates world items for Dragonroll-authored ones) |
|
||||||
|
| `GET /sync/status` | The campaign a sync token belongs to; the module shows it in its **Dragonroll Pairing Status** setting and treats `unauthorized` as the campaign having unlinked the world |
|
||||||
| `POST /sync/map` / `POST /sync/map-item` | Store the id mapping after the module creates a document |
|
| `POST /sync/map` / `POST /sync/map-item` | Store the id mapping after the module creates a document |
|
||||||
| `POST /sync/delete` | `{worldId, foundryActorId}` |
|
| `POST /sync/delete` | `{worldId, foundryActorId}` |
|
||||||
|
|
||||||
@@ -248,6 +263,13 @@ Rules worth knowing before editing this:
|
|||||||
which the sync skips.
|
which the sync skips.
|
||||||
- **`fullSync` preserves Dragonroll edits** (only new rows are overwritten); live Foundry events
|
- **`fullSync` preserves Dragonroll edits** (only new rows are overwritten); live Foundry events
|
||||||
overwrite. Item pruning requires the full snapshot, since only it sees world items and actor copies.
|
overwrite. Item pruning requires the full snapshot, since only it sees world items and actor copies.
|
||||||
|
- **Autosync is a Foundry-side switch** (`autoSync` client setting, on by default): when off, the
|
||||||
|
module queues no CRUD push, runs no periodic reconcile and sends no startup snapshot; the actor
|
||||||
|
directory's `Dragonroll: Force Sync` entry still pushes the selected actors as an upsert
|
||||||
|
(`fullSync:false`, so it never prunes). The read-only bridge snapshot is not gated by it.
|
||||||
|
- **`pairingStatus` is a setting the module writes, not the GM**: the module settings sentence about
|
||||||
|
whether this world is connected comes from the stored sync token plus the answer from
|
||||||
|
`/sync/status` (checked at world start and every minute), and anything typed into it is replaced.
|
||||||
- `Actor.inventory` stays a flattened copy of the actor's embedded items; it is not linked to `Item`.
|
- `Actor.inventory` stays a flattened copy of the actor's embedded items; it is not linked to `Item`.
|
||||||
- `GET /api/foundry/*` (`routes/foundry.js`) is unrelated: a JWT-protected proxy over the read-only
|
- `GET /api/foundry/*` (`routes/foundry.js`) is unrelated: a JWT-protected proxy over the read-only
|
||||||
bridge, only useful when `FOUNDRY_API_URL` is configured.
|
bridge, only useful when `FOUNDRY_API_URL` is configured.
|
||||||
@@ -276,7 +298,7 @@ frontend/
|
|||||||
│ │ VersionRender
|
│ │ VersionRender
|
||||||
│ ├── layouts/ IconButton, Dropdown, Tabs, ColorPicker (reusable UI atoms)
|
│ ├── layouts/ IconButton, Dropdown, Tabs, ColorPicker (reusable UI atoms)
|
||||||
│ └── viewer/ TopBar, statusbar/{StatusBar,FetchStatus}, topbar/{TopSearchBar,SearchResult},
|
│ └── viewer/ TopBar, statusbar/{StatusBar,FetchStatus}, topbar/{TopSearchBar,SearchResult},
|
||||||
│ content/{Content,NoteContainer,Note}, widgets/{TableWidget,TestWidget,
|
│ content/{Content,NoteContainer,Note}, map/MapViewerPane, widgets/{TableWidget,TestWidget,
|
||||||
│ inline/RollWidgetInline,display/RollWidgetDisplay}
|
│ inline/RollWidgetInline,display/RollWidgetDisplay}
|
||||||
├── composables/ useTheme.ts (theme+accent singletons, localStorage, data-* attrs),
|
├── composables/ useTheme.ts (theme+accent singletons, localStorage, data-* attrs),
|
||||||
│ useEmitter.ts (BROKEN, see §9)
|
│ useEmitter.ts (BROKEN, see §9)
|
||||||
@@ -290,7 +312,13 @@ There is no `app/pages/`. `app/app.vue` renders a fixed shell of managers. "Scre
|
|||||||
|
|
||||||
- **Windows** — floating, draggable/resizable overlays (login, main menu, settings…), or
|
- **Windows** — floating, draggable/resizable overlays (login, main menu, settings…), or
|
||||||
- **Content** — the campaign workspace (`TopBar` + `ContentSidebar` + note column + `StatusBar`),
|
- **Content** — the campaign workspace (`TopBar` + `ContentSidebar` + note column + `StatusBar`),
|
||||||
shown when `Campaign` state is non-null.
|
shown when `Campaign` state is non-null. The note column shows the open notes, or the map anchored
|
||||||
|
on it (`AnchorMap` / `ActivePane` in `services/Content.js`); the sidebar's notes and maps buttons
|
||||||
|
switch between the two while both keep their state, and `viewer/map/MapViewerPane.vue` renders the
|
||||||
|
map there and inside the `map_viewer` window (a detached anchored map). Right clicking that map pins
|
||||||
|
one of the campaign notes at the spot (`services/MapPins.js` translates between image pixels and
|
||||||
|
the screen and labels the note picker); clicking the marker opens `pinned_note`
|
||||||
|
(`PinnedNoteWindow.vue`), which reads the note itself through `/note/retrieve/:id`.
|
||||||
|
|
||||||
Boot sequence (`app.vue` → `start()`):
|
Boot sequence (`app.vue` → `start()`):
|
||||||
|
|
||||||
@@ -353,7 +381,7 @@ Plain modules with module-scope `ref()`s imported directly. No DI, no Pinia. Sin
|
|||||||
| `Server.js` | axios instance (fallback baseURL `http://localhost:5000/api`), `initApi(baseURL)` called by `plugins/api.ts`, request interceptor adding `Authorization: Bearer <localStorage.token>`, `getBaseUrl()`. Default export is a factory: call `Server()` then `.get/.post`. |
|
| `Server.js` | axios instance (fallback baseURL `http://localhost:5000/api`), `initApi(baseURL)` called by `plugins/api.ts`, request interceptor adding `Authorization: Bearer <localStorage.token>`, `getBaseUrl()`. Default export is a factory: call `Server()` then `.get/.post`. |
|
||||||
| `User.js` | `UserStatus` ref, `GetUser()` (decodes JWT, auto-logout on `exp`), `SetUser(token)`, `LoadUser`, `LogoutUser`, `IsAdmin`, `HasAdmin()`, `GetUserSetting(key)` / `SetUserSetting(key,value)` (server-backed, in `User.settings`) |
|
| `User.js` | `UserStatus` ref, `GetUser()` (decodes JWT, auto-logout on `exp`), `SetUser(token)`, `LoadUser`, `LogoutUser`, `IsAdmin`, `HasAdmin()`, `GetUserSetting(key)` / `SetUserSetting(key,value)` (server-backed, in `User.settings`) |
|
||||||
| `Campaign.js` | `useCampaignService()` → `Campaign` (`useState('campaign')`), `SetCampaign(data)` (also writes `localStorage.selectedCampaignId`), `RestoreCampaign()` |
|
| `Campaign.js` | `useCampaignService()` → `Campaign` (`useState('campaign')`), `SetCampaign(data)` (also writes `localStorage.selectedCampaignId`), `RestoreCampaign()` |
|
||||||
| `Content.js` | `ShowContent` ref (drives the campaign workspace). `SetShowContent` is exported but unused — `ContentManager.vue` sets it from a `watch(Campaign)` and never turns it back off |
|
| `Content.js` | `ShowContent` ref (drives the campaign workspace: `ContentManager.vue` turns it on from a `watch(Campaign)`, `TopBar` off when leaving a campaign) and the anchored map: `ActivePane` (`'notes'`\|`'map'`), `AnchoredMap`, `SetActivePane`, `AnchorMap`, `ClearAnchoredMap` |
|
||||||
| `Emitter.js` | `export const emitter = mitt()` — the app-wide event bus |
|
| `Emitter.js` | `export const emitter = mitt()` — the app-wide event bus |
|
||||||
| `Toaster.js` | `DisplayToast(color, text, duration)` → emits `toast`; `ToastManager.vue` renders it |
|
| `Toaster.js` | `DisplayToast(color, text, duration)` → emits `toast`; `ToastManager.vue` renders it |
|
||||||
| `Tooltip.js` | `SetupTooltip()`, `AddTooltip(el, text, {max_width})` (stores on `el._dr_tooltip`), polled visibility via `elementsFromPoint` |
|
| `Tooltip.js` | `SetupTooltip()`, `AddTooltip(el, text, {max_width})` (stores on `el._dr_tooltip`), polled visibility via `elementsFromPoint` |
|
||||||
@@ -409,8 +437,8 @@ Every listener in the app (there are only these six `emitter.on` call sites):
|
|||||||
| `toast` | `{color,text,duration}` | `ToastManager.vue` |
|
| `toast` | `{color,text,duration}` | `ToastManager.vue` |
|
||||||
| `push-note` | `{key,title,text,date}` | `NoteContainer.vue` |
|
| `push-note` | `{key,title,text,date}` | `NoteContainer.vue` |
|
||||||
| `close-note` | note key (string) | `NoteContainer.vue` (removes the note from the open column only) |
|
| `close-note` | note key (string) | `NoteContainer.vue` (removes the note from the open column only) |
|
||||||
| `delete-note` | note key (string) | `NoteContainer.vue`, `ContentSidebar.vue`, `NestedNoteList.vue` (real deletion: closes the note **and** removes it from the sidebar) |
|
| `delete-note` | note key (string) | `NoteContainer.vue`, `ContentSidebar.vue`, `NestedNoteList.vue` (real deletion: closes the note **and** removes it from the sidebar), `MapViewerPane.vue` (drops the markers pinned to that note) |
|
||||||
| `title-updated` | `{key,title}` | `Note.vue`, `NoteContainer.vue` |
|
| `title-updated` | `{key,title}` | `Note.vue`, `NoteContainer.vue`, `MapViewerPane.vue` (relabels the map pins of that note) |
|
||||||
| `status-bar-update` | `{text,icon}` | `FetchStatus.vue` |
|
| `status-bar-update` | `{text,icon}` | `FetchStatus.vue` |
|
||||||
|
|
||||||
Emitters: `Toaster.js` (`toast`), `ContentSidebar` / `TopSearchBar` (`push-note`), `Note.vue`
|
Emitters: `Toaster.js` (`toast`), `ContentSidebar` / `TopSearchBar` (`push-note`), `Note.vue`
|
||||||
@@ -463,6 +491,23 @@ script; `WindowDefinitions` stores raw keys (`title: 'windows.login'`) and `Wind
|
|||||||
configured (`nuxt.config.ts`, `langDir: 'locales/'`, `vueI18n: './i18n.config.ts'`) but its locale files
|
configured (`nuxt.config.ts`, `langDir: 'locales/'`, `vueI18n: './i18n.config.ts'`) but its locale files
|
||||||
(`locales/en.json` etc.) are empty `{}` — the custom plugin is what components actually consume.
|
(`locales/en.json` etc.) are empty `{}` — the custom plugin is what components actually consume.
|
||||||
|
|
||||||
|
### 5.9 Obsidian plugin
|
||||||
|
|
||||||
|
`obsidian-plugin/` is a plain JavaScript community plugin; copy `main.js` and `manifest.json` into
|
||||||
|
`<vault>/.obsidian/plugins/dragonroll-sync/` (details in its README). It signs in through
|
||||||
|
`POST /api/user/login`, saves the 48-hour JWT token in plugin data, and does not save the password.
|
||||||
|
The user selects a campaign from `GET /api/campaign/list`.
|
||||||
|
|
||||||
|
- **Import or refresh campaign notes** reads `/api/note/list` plus `/api/note/subfolder/list` and
|
||||||
|
creates/updates Markdown files under `Dragonroll/<Campaign>/`, preserving Dragonroll's folder tree.
|
||||||
|
- **Push active note to Dragonroll** creates a root campaign note or updates the note linked in its
|
||||||
|
frontmatter.
|
||||||
|
- `dragonrollId`, `dragonrollCampaign`, and `dragonrollTitle` frontmatter properties link imported
|
||||||
|
notes. They are omitted from content sent to Dragonroll. Per-note signatures detect local edits;
|
||||||
|
imports preserve modified local files, and push is explicit.
|
||||||
|
|
||||||
|
The plugin uses Obsidian's `requestUrl` helper, so the request path does not depend on browser CORS.
|
||||||
|
|
||||||
## 6. Conventions
|
## 6. Conventions
|
||||||
|
|
||||||
- **Backend**: CommonJS `require`/`module.exports`; files in `services/` are shared infra, `routes/`
|
- **Backend**: CommonJS `require`/`module.exports`; files in `services/` are shared infra, `routes/`
|
||||||
|
|||||||
@@ -24,6 +24,7 @@ Dragonroll is an open source connector for role-playing games.
|
|||||||
- Play music during physical campaings
|
- Play music during physical campaings
|
||||||
- Plan different encounters
|
- Plan different encounters
|
||||||
- Manage different items and spells
|
- Manage different items and spells
|
||||||
|
- Import and edit campaign notes in Obsidian with the [Dragonroll Sync plugin](obsidian-plugin/README.md)
|
||||||
- And so much more!
|
- And so much more!
|
||||||
|
|
||||||
## Installation 🛠️
|
## Installation 🛠️
|
||||||
@@ -55,7 +56,6 @@ if you want to start the development environments
|
|||||||
|
|
||||||
- Dragonroll <-> Foundry integration
|
- Dragonroll <-> Foundry integration
|
||||||
- Dragonroll <-> Discord Bot integration
|
- Dragonroll <-> Discord Bot integration
|
||||||
- Dragonroll <-> Obsidian integration
|
|
||||||
|
|
||||||
What to sync:
|
What to sync:
|
||||||
|
|
||||||
|
|||||||
@@ -12,6 +12,13 @@ const MapSchema = new Schema({
|
|||||||
offsetY: { type: Number, default: 0 },
|
offsetY: { type: Number, default: 0 },
|
||||||
// Distance each grid cell stands for (feet, metres...)
|
// Distance each grid cell stands for (feet, metres...)
|
||||||
scale: { type: Number, min: 0.01, default: 5 },
|
scale: { type: Number, min: 0.01, default: 5 },
|
||||||
|
// Notes pinned onto the map like markers. x/y are image pixels from the top left corner of the
|
||||||
|
// image, so a pin keeps its place whatever the zoom or the grid settings are.
|
||||||
|
pins: [{
|
||||||
|
note: { type: Schema.Types.ObjectId, ref: 'Note', required: true },
|
||||||
|
x: { type: Number, default: 0 },
|
||||||
|
y: { type: Number, default: 0 }
|
||||||
|
}],
|
||||||
campaign: {
|
campaign: {
|
||||||
type: Schema.Types.ObjectId,
|
type: Schema.Types.ObjectId,
|
||||||
ref: 'Campaign',
|
ref: 'Campaign',
|
||||||
|
|||||||
@@ -225,6 +225,7 @@ router.post('/link/complete', linkRateLimit, async (req, res) => {
|
|||||||
res.set('Cache-Control', 'no-store');
|
res.set('Cache-Control', 'no-store');
|
||||||
res.json({
|
res.json({
|
||||||
status: 'ok',
|
status: 'ok',
|
||||||
|
campaign: { id: campaign.id, name: campaign.name },
|
||||||
world: { id: world.worldId, title: world.worldTitle, system: world.system },
|
world: { id: world.worldId, title: world.worldTitle, system: world.system },
|
||||||
syncToken,
|
syncToken,
|
||||||
bridgeConfig: bridgeUrl && pushToken ? { url: bridgeUrl, pushToken } : null
|
bridgeConfig: bridgeUrl && pushToken ? { url: bridgeUrl, pushToken } : null
|
||||||
@@ -236,6 +237,26 @@ router.post('/link/complete', linkRateLimit, async (req, res) => {
|
|||||||
}
|
}
|
||||||
});
|
});
|
||||||
|
|
||||||
|
// The Foundry module shows this in its settings: the sync token alone only proves
|
||||||
|
// a link was made once, so the module asks which campaign it belongs to and hears
|
||||||
|
// back nothing but `unauthorized` once that campaign unlinks the world again.
|
||||||
|
router.get('/sync/status', async (req, res) => {
|
||||||
|
try {
|
||||||
|
const campaign = await syncCampaign(req, res);
|
||||||
|
if (!campaign) return;
|
||||||
|
|
||||||
|
res.set('Cache-Control', 'no-store');
|
||||||
|
res.json({
|
||||||
|
status: 'ok',
|
||||||
|
campaign: { id: campaign.id, name: campaign.name },
|
||||||
|
worldId: campaign.foundryWorldId
|
||||||
|
});
|
||||||
|
} catch (err) {
|
||||||
|
console.error(err);
|
||||||
|
res.json({ status: 'error', msg: 'errors.internal' });
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
router.post('/sync/snapshot', async (req, res) => {
|
router.post('/sync/snapshot', async (req, res) => {
|
||||||
try {
|
try {
|
||||||
const campaign = await syncCampaign(req, res);
|
const campaign = await syncCampaign(req, res);
|
||||||
|
|||||||
@@ -5,6 +5,7 @@ const upload = require('../services/storage');
|
|||||||
|
|
||||||
const Campaign = require('../models/Campaign');
|
const Campaign = require('../models/Campaign');
|
||||||
const Map = require('../models/Map');
|
const Map = require('../models/Map');
|
||||||
|
const Note = require('../models/Note');
|
||||||
|
|
||||||
async function userOwnsCampaign(campaignId, userId) {
|
async function userOwnsCampaign(campaignId, userId) {
|
||||||
const campaign = await Campaign.findOne({ _id: campaignId, createdBy: userId }).lean();
|
const campaign = await Campaign.findOne({ _id: campaignId, createdBy: userId }).lean();
|
||||||
@@ -92,4 +93,63 @@ router.post('/delete', async (req, res) => {
|
|||||||
}
|
}
|
||||||
});
|
});
|
||||||
|
|
||||||
|
// A pin is a note placed at a spot of the map, in image pixels. Coordinates arrive as strings with
|
||||||
|
// multipart requests and are never negative: the viewer clamps them to the image already.
|
||||||
|
function toCoordinate(value) {
|
||||||
|
const number = Number(value);
|
||||||
|
if (!Number.isFinite(number)) return 0;
|
||||||
|
return Math.max(0, Math.round(number));
|
||||||
|
}
|
||||||
|
|
||||||
|
router.post('/pin', async (req, res) => {
|
||||||
|
try {
|
||||||
|
const { id, note, x, y } = req.body;
|
||||||
|
if (!id || !note) return res.json({ status: 'error', msg: 'errors.missing-data' });
|
||||||
|
|
||||||
|
const map = await Map.findById(id);
|
||||||
|
if (!map) return res.json({ status: 'error', msg: 'errors.notfound' });
|
||||||
|
if (!(await userOwnsCampaign(map.campaign, req.user.id))) return res.json({ status: 'error', msg: 'unauthorized' });
|
||||||
|
|
||||||
|
// Only a note of the same campaign can be pinned onto one of its maps.
|
||||||
|
const noteDoc = await Note.findOne({ _id: note, campaign: map.campaign }).select('_id').lean();
|
||||||
|
if (!noteDoc) return res.json({ status: 'error', msg: 'errors.notfound' });
|
||||||
|
|
||||||
|
// A note is pinned once per map: pinning it again moves the marker instead of adding a twin.
|
||||||
|
const pin = map.pins.find((current) => String(current.note) === String(note));
|
||||||
|
if (pin) {
|
||||||
|
pin.x = toCoordinate(x);
|
||||||
|
pin.y = toCoordinate(y);
|
||||||
|
} else {
|
||||||
|
map.pins.push({ note, x: toCoordinate(x), y: toCoordinate(y) });
|
||||||
|
}
|
||||||
|
|
||||||
|
await map.save();
|
||||||
|
res.json({ status: 'ok', map });
|
||||||
|
} catch (err) {
|
||||||
|
console.error(err);
|
||||||
|
res.json({ status: 'error', msg: 'errors.internal' });
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
router.post('/unpin', async (req, res) => {
|
||||||
|
try {
|
||||||
|
const { id, pin } = req.body;
|
||||||
|
if (!id || !pin) return res.json({ status: 'error', msg: 'errors.missing-data' });
|
||||||
|
|
||||||
|
const map = await Map.findById(id);
|
||||||
|
if (!map) return res.json({ status: 'error', msg: 'errors.notfound' });
|
||||||
|
if (!(await userOwnsCampaign(map.campaign, req.user.id))) return res.json({ status: 'error', msg: 'unauthorized' });
|
||||||
|
|
||||||
|
// `_id` stays with the pins that remain: the viewer removes them by that id.
|
||||||
|
map.pins = map.pins
|
||||||
|
.filter((current) => String(current._id) !== String(pin))
|
||||||
|
.map((current) => ({ _id: current._id, note: current.note, x: current.x, y: current.y }));
|
||||||
|
await map.save();
|
||||||
|
res.json({ status: 'ok', map });
|
||||||
|
} catch (err) {
|
||||||
|
console.error(err);
|
||||||
|
res.json({ status: 'error', msg: 'errors.internal' });
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
module.exports = router;
|
module.exports = router;
|
||||||
|
|||||||
@@ -4,6 +4,7 @@ const router = express.Router();
|
|||||||
const Campaign = require('../models/Campaign');
|
const Campaign = require('../models/Campaign');
|
||||||
const Note = require('../models/Note');
|
const Note = require('../models/Note');
|
||||||
const Folder = require('../models/Folder');
|
const Folder = require('../models/Folder');
|
||||||
|
const Map = require('../models/Map');
|
||||||
|
|
||||||
async function userOwnsCampaign(campaignId, userId) {
|
async function userOwnsCampaign(campaignId, userId) {
|
||||||
const campaign = await Campaign.findOne({ _id: campaignId, createdBy: userId }).lean();
|
const campaign = await Campaign.findOne({ _id: campaignId, createdBy: userId }).lean();
|
||||||
@@ -19,7 +20,7 @@ router.get('/list', async (req, res) => {
|
|||||||
if (!hasAccess) return res.json({ status: 'error', msg: 'unauthorized' });
|
if (!hasAccess) return res.json({ status: 'error', msg: 'unauthorized' });
|
||||||
|
|
||||||
const folders = await Folder.find({ campaign })
|
const folders = await Folder.find({ campaign })
|
||||||
.select('_id name date color')
|
.select('_id name parentFolder date color')
|
||||||
.sort({ date: -1 })
|
.sort({ date: -1 })
|
||||||
.lean();
|
.lean();
|
||||||
|
|
||||||
@@ -64,6 +65,49 @@ router.get('/subfolder/list', async (req, res) => {
|
|||||||
}
|
}
|
||||||
});
|
});
|
||||||
|
|
||||||
|
// Every note of the campaign, folders included, without their content: enough to offer a note
|
||||||
|
// picker and to label the pins other screens put on a map.
|
||||||
|
router.get('/all', async (req, res) => {
|
||||||
|
try {
|
||||||
|
const { campaign } = req.query;
|
||||||
|
if (!campaign) return res.json({ status: 'error', msg: 'errors.missing-data' });
|
||||||
|
|
||||||
|
const hasAccess = await userOwnsCampaign(campaign, req.user.id);
|
||||||
|
if (!hasAccess) return res.json({ status: 'error', msg: 'unauthorized' });
|
||||||
|
|
||||||
|
const notes = await Note.find({ campaign })
|
||||||
|
.select('_id title folder date')
|
||||||
|
.sort({ title: 1 })
|
||||||
|
.lean();
|
||||||
|
|
||||||
|
const folders = await Folder.find({ campaign })
|
||||||
|
.select('_id name parentFolder')
|
||||||
|
.lean();
|
||||||
|
|
||||||
|
res.json({ status: 'ok', notes, folders });
|
||||||
|
} catch (err) {
|
||||||
|
console.error(err);
|
||||||
|
res.json({ status: 'error', msg: 'errors.internal' });
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
// One note with its content, for the screens that show a note on their own (a map pin, for
|
||||||
|
// instance) instead of from the sidebar's note list.
|
||||||
|
router.get('/retrieve/:id', async (req, res) => {
|
||||||
|
try {
|
||||||
|
const note = await Note.findById(req.params.id).lean();
|
||||||
|
if (!note) return res.json({ status: 'error', msg: 'errors.notfound' });
|
||||||
|
|
||||||
|
const hasAccess = await userOwnsCampaign(note.campaign, req.user.id);
|
||||||
|
if (!hasAccess) return res.json({ status: 'error', msg: 'unauthorized' });
|
||||||
|
|
||||||
|
res.json({ status: 'ok', note });
|
||||||
|
} catch (err) {
|
||||||
|
console.error(err);
|
||||||
|
res.json({ status: 'error', msg: 'errors.internal' });
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
router.post('/create', async (req, res) => {
|
router.post('/create', async (req, res) => {
|
||||||
try {
|
try {
|
||||||
const { title, content, campaign, folder } = req.body;
|
const { title, content, campaign, folder } = req.body;
|
||||||
@@ -119,6 +163,9 @@ router.post('/delete', async (req, res) => {
|
|||||||
const result = await Note.deleteOne({ _id: id });
|
const result = await Note.deleteOne({ _id: id });
|
||||||
if (result.deletedCount === 0) return res.json({ status: 'error', msg: 'errors.notfound' });
|
if (result.deletedCount === 0) return res.json({ status: 'error', msg: 'errors.notfound' });
|
||||||
|
|
||||||
|
// A pin pointing at a note that is gone would open nothing: drop those along with the note.
|
||||||
|
await Map.updateMany({ 'pins.note': id }, { $pull: { pins: { note: id } } });
|
||||||
|
|
||||||
res.json({ status: 'ok' });
|
res.json({ status: 'ok' });
|
||||||
} catch (err) {
|
} catch (err) {
|
||||||
console.error(err);
|
console.error(err);
|
||||||
|
|||||||
@@ -41,6 +41,14 @@ For a local backend, use `http://localhost:5000`; the module omits `/api` and th
|
|||||||
the local pairing route at its root. Character synchronization works without the optional snapshot
|
the local pairing route at its root. Character synchronization works without the optional snapshot
|
||||||
bridge. Configure that bridge only if you also need the read-only world snapshot API described below.
|
bridge. Configure that bridge only if you also need the read-only world snapshot API described below.
|
||||||
|
|
||||||
|
**Dragonroll Pairing Status** in the module settings always says whether this browser holds a pairing
|
||||||
|
and, once Dragonroll has answered `GET /api/foundry/sync/status`, which campaign the world is
|
||||||
|
connected to. It is written by the module, not by the GM: it appears as not connected until the world
|
||||||
|
is paired, names the campaign after a pairing or a check on world start and every minute afterwards,
|
||||||
|
gives the reason when a pairing code can never be redeemed, and says the world is no longer linked
|
||||||
|
once the campaign unlinks it. Because both the pairing code and the sync token are client settings,
|
||||||
|
another browser of the same world reads as not paired.
|
||||||
|
|
||||||
The campaign settings show the linked world's title and system. A Foundry world can be linked to
|
The campaign settings show the linked world's title and system. A Foundry world can be linked to
|
||||||
only one campaign at a time. The pairing endpoint accepts cross-origin requests from the Foundry
|
only one campaign at a time. The pairing endpoint accepts cross-origin requests from the Foundry
|
||||||
client and uses the one-time code instead of a Dragonroll login token.
|
client and uses the one-time code instead of a Dragonroll login token.
|
||||||
@@ -53,6 +61,25 @@ within about five seconds. The module currently creates Dragonroll characters in
|
|||||||
worlds. After updating an already-linked world to a version with character sync, create a fresh
|
worlds. After updating an already-linked world to a version with character sync, create a fresh
|
||||||
pairing code and enter it in Foundry once to issue the sync token.
|
pairing code and enter it in Foundry once to issue the sync token.
|
||||||
|
|
||||||
|
### Auto-sync, and sending one actor on purpose
|
||||||
|
|
||||||
|
**Dragonroll Auto-sync** in the module settings (on by default) is what keeps the campaign and this
|
||||||
|
world in step: actors and world items the GM creates, updates or deletes are sent to Dragonroll, and
|
||||||
|
both sides reconcile every few seconds. Turn it off to stop synchronizing altogether — nothing is
|
||||||
|
sent to the campaign, and Dragonroll stops rewriting those documents in Foundry, so the campaign
|
||||||
|
keeps whatever it already holds. Turn it back on to reconcile both sides again; the Foundry edits
|
||||||
|
queued while it was off are sent as the world catches up.
|
||||||
|
|
||||||
|
With autosync off — or any time a single character needs to cross over right now — right-click an
|
||||||
|
actor (or several selected ones) in the Foundry actor directory and pick **Dragonroll: Force Sync**.
|
||||||
|
Those actors, together with the gear carried inside them, are pushed to the campaign immediately even
|
||||||
|
when autosync is off. It is an upsert only: it never prunes the campaign's other actors, which a full
|
||||||
|
snapshot does and a forced sync never claims to. Actors Dragonroll does not import (anything that is
|
||||||
|
not a character, NPC or creature) are refused with a notification.
|
||||||
|
|
||||||
|
The optional read-only snapshot bridge is not affected: it keeps publishing the world snapshot behind
|
||||||
|
`/api/foundry/*`, which is never written into the campaign.
|
||||||
|
|
||||||
### Items
|
### Items
|
||||||
|
|
||||||
The campaign's Item list is synchronized with the world's gear, both ways:
|
The campaign's Item list is synchronized with the world's gear, both ways:
|
||||||
@@ -84,6 +111,7 @@ The module calls these Dragonroll routes with the campaign sync token (no Dragon
|
|||||||
| `POST /api/foundry/sync/item-delete` | A world item was deleted |
|
| `POST /api/foundry/sync/item-delete` | A world item was deleted |
|
||||||
| `GET /api/foundry/sync/characters` | Characters to apply back in Foundry |
|
| `GET /api/foundry/sync/characters` | Characters to apply back in Foundry |
|
||||||
| `GET /api/foundry/sync/items` | Items to apply back in Foundry |
|
| `GET /api/foundry/sync/items` | Items to apply back in Foundry |
|
||||||
|
| `GET /api/foundry/sync/status` | The campaign this world's token belongs to, for the module's pairing status |
|
||||||
| `POST /api/foundry/sync/map` / `map-item` | Store an id mapping after creating a document |
|
| `POST /api/foundry/sync/map` / `map-item` | Store an id mapping after creating a document |
|
||||||
| `POST /api/foundry/sync/delete` | An actor was deleted |
|
| `POST /api/foundry/sync/delete` | An actor was deleted |
|
||||||
|
|
||||||
|
|||||||
@@ -2,7 +2,7 @@
|
|||||||
"id": "dragonroll-foundry",
|
"id": "dragonroll-foundry",
|
||||||
"title": "Dragonroll Foundry API",
|
"title": "Dragonroll Foundry API",
|
||||||
"description": "Links a Foundry world to a Dragonroll campaign and exposes a client-side API for world data.",
|
"description": "Links a Foundry world to a Dragonroll campaign and exposes a client-side API for world data.",
|
||||||
"version": "0.3.0",
|
"version": "0.4.0",
|
||||||
"library": true,
|
"library": true,
|
||||||
"compatibility": {
|
"compatibility": {
|
||||||
"minimum": "12",
|
"minimum": "12",
|
||||||
|
|||||||
@@ -4,7 +4,9 @@ const SETTING_PUSH_TOKEN = "pushToken";
|
|||||||
const SETTING_BRIDGE_CONFIG = "bridgeConfig";
|
const SETTING_BRIDGE_CONFIG = "bridgeConfig";
|
||||||
const SETTING_DRAGONROLL_API_URL = "dragonrollApiUrl";
|
const SETTING_DRAGONROLL_API_URL = "dragonrollApiUrl";
|
||||||
const SETTING_LINK_CODE = "linkCode";
|
const SETTING_LINK_CODE = "linkCode";
|
||||||
|
const SETTING_PAIRING_STATUS = "pairingStatus";
|
||||||
const SETTING_SYNC_TOKEN = "syncToken";
|
const SETTING_SYNC_TOKEN = "syncToken";
|
||||||
|
const SETTING_AUTO_SYNC = "autoSync";
|
||||||
let syncTimeout;
|
let syncTimeout;
|
||||||
let syncInProgress = false;
|
let syncInProgress = false;
|
||||||
let syncRequested = false;
|
let syncRequested = false;
|
||||||
@@ -15,6 +17,12 @@ const FATAL_LINK_ERRORS = new Set([
|
|||||||
"foundry.errors.link-expired",
|
"foundry.errors.link-expired",
|
||||||
"foundry.errors.world-already-linked",
|
"foundry.errors.world-already-linked",
|
||||||
]);
|
]);
|
||||||
|
// Marks a pairing Dragonroll honoured once and no longer accepts: the campaign
|
||||||
|
// unlinked this world, so the token this client holds is dead.
|
||||||
|
const PAIRING_REVOKED = "revoked";
|
||||||
|
let updatingPairingStatus = false;
|
||||||
|
let linkedCampaignName = "";
|
||||||
|
let pairingProblem = "";
|
||||||
let actorSyncTimeout;
|
let actorSyncTimeout;
|
||||||
let characterSyncRunning = false;
|
let characterSyncRunning = false;
|
||||||
let actorSyncErrorLogged = false;
|
let actorSyncErrorLogged = false;
|
||||||
@@ -139,6 +147,26 @@ Hooks.once("init", () => {
|
|||||||
onChange: handleLinkCodeChange,
|
onChange: handleLinkCodeChange,
|
||||||
});
|
});
|
||||||
|
|
||||||
|
game.settings.register(MODULE_ID, SETTING_PAIRING_STATUS, {
|
||||||
|
name: "Dragonroll Pairing Status",
|
||||||
|
hint: "Whether this world is connected to a Dragonroll campaign. The module keeps this text up to date and the pairing lives in the browser of whoever linked the world: there is nothing to set here.",
|
||||||
|
scope: "client",
|
||||||
|
config: true,
|
||||||
|
type: String,
|
||||||
|
default: "",
|
||||||
|
onChange: handlePairingStatusChange,
|
||||||
|
});
|
||||||
|
|
||||||
|
game.settings.register(MODULE_ID, SETTING_AUTO_SYNC, {
|
||||||
|
name: "Dragonroll Auto-sync",
|
||||||
|
hint: "Keep the linked Dragonroll campaign in step with this world as its actors and items change. Turn this off to stop synchronizing; the actor directory's Dragonroll: Force Sync entry then sends an actor over only when you ask for it.",
|
||||||
|
scope: "client",
|
||||||
|
config: true,
|
||||||
|
type: Boolean,
|
||||||
|
default: true,
|
||||||
|
onChange: handleAutoSyncChange,
|
||||||
|
});
|
||||||
|
|
||||||
const module = game.modules.get(MODULE_ID);
|
const module = game.modules.get(MODULE_ID);
|
||||||
if (!module) {
|
if (!module) {
|
||||||
console.warn(`${MODULE_ID} | Could not register the public API: module was not found.`);
|
console.warn(`${MODULE_ID} | Could not register the public API: module was not found.`);
|
||||||
@@ -210,6 +238,9 @@ async function setLinkCode(value) {
|
|||||||
function handleLinkCodeChange(value) {
|
function handleLinkCodeChange(value) {
|
||||||
if (updatingLinkCodeSetting || handlingLinkCode || !value?.trim()) return;
|
if (updatingLinkCodeSetting || handlingLinkCode || !value?.trim()) return;
|
||||||
linkRetriesDisabled = false;
|
linkRetriesDisabled = false;
|
||||||
|
// A code typed by hand supersedes whatever went wrong with the last one.
|
||||||
|
pairingProblem = "";
|
||||||
|
setPairingStatus(pairingStatusText());
|
||||||
completeDragonrollCampaignLink(value.trim());
|
completeDragonrollCampaignLink(value.trim());
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -246,13 +277,19 @@ async function completeDragonrollCampaignLink(code, options = {}) {
|
|||||||
scheduleSnapshotSync(0);
|
scheduleSnapshotSync(0);
|
||||||
setTimeout(initializeCharacterSync, 0);
|
setTimeout(initializeCharacterSync, 0);
|
||||||
setTimeout(reconcileDragonrollItems, 2000);
|
setTimeout(reconcileDragonrollItems, 2000);
|
||||||
|
linkedCampaignName = String(result.campaign?.name || "").trim();
|
||||||
ui.notifications?.info("This Foundry world is now linked to the Dragonroll campaign.");
|
ui.notifications?.info("This Foundry world is now linked to the Dragonroll campaign.");
|
||||||
|
await setPairingStatus(pairingStatusText());
|
||||||
} catch (error) {
|
} catch (error) {
|
||||||
console.error(`${MODULE_ID} | Could not complete the campaign link.`, error);
|
console.error(`${MODULE_ID} | Could not complete the campaign link.`, error);
|
||||||
// Expired or already-used codes will never redeem, so stop the background
|
// Expired or already-used codes will never redeem, so stop the background
|
||||||
// retry; any error keeps retrying (the Dragonroll server may be restarting).
|
// retry; any error keeps retrying (the Dragonroll server may be restarting).
|
||||||
linkRetriesDisabled = FATAL_LINK_ERRORS.has(error.message);
|
linkRetriesDisabled = FATAL_LINK_ERRORS.has(error.message);
|
||||||
|
// Only a code that can never be redeemed belongs in the status: while the
|
||||||
|
// retry is still running, waiting for Dragonroll is the honest text.
|
||||||
|
if (linkRetriesDisabled) pairingProblem = linkErrorMessage(error);
|
||||||
if (notifyOnError) ui.notifications?.error(linkErrorMessage(error));
|
if (notifyOnError) ui.notifications?.error(linkErrorMessage(error));
|
||||||
|
await setPairingStatus(pairingStatusText());
|
||||||
} finally {
|
} finally {
|
||||||
handlingLinkCode = false;
|
handlingLinkCode = false;
|
||||||
}
|
}
|
||||||
@@ -267,6 +304,69 @@ async function resumePendingDragonrollLink(options = {}) {
|
|||||||
if (code) await completeDragonrollCampaignLink(code, options);
|
if (code) await completeDragonrollCampaignLink(code, options);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// --- Pairing status --------------------------------------------------------
|
||||||
|
// The pairing status is the sentence the module settings show. Everything in it
|
||||||
|
// comes from this client plus what Dragonroll last said about its token, so it
|
||||||
|
// reads correctly from the first frame and is corrected by refreshPairingStatus.
|
||||||
|
|
||||||
|
function pairingStatusText() {
|
||||||
|
if (pairingProblem === PAIRING_REVOKED) {
|
||||||
|
return "Not connected: this world is no longer linked to the Dragonroll campaign it was paired with. Create a new pairing code there to link it again.";
|
||||||
|
}
|
||||||
|
if (getSyncToken()) {
|
||||||
|
return linkedCampaignName
|
||||||
|
? `Connected to the Dragonroll campaign "${linkedCampaignName}".`
|
||||||
|
: "Connected to a Dragonroll campaign.";
|
||||||
|
}
|
||||||
|
if (pairingProblem) return `Not connected: Dragonroll did not accept that pairing code (${pairingProblem})`;
|
||||||
|
if (game.settings.get(MODULE_ID, SETTING_LINK_CODE)?.trim()) {
|
||||||
|
return "Not connected yet: waiting for Dragonroll to accept this pairing code.";
|
||||||
|
}
|
||||||
|
return "Not connected to a Dragonroll campaign. Paste a pairing code from that campaign's settings to link this world.";
|
||||||
|
}
|
||||||
|
|
||||||
|
async function setPairingStatus(text) {
|
||||||
|
if (game.settings.get(MODULE_ID, SETTING_PAIRING_STATUS) === text) return;
|
||||||
|
updatingPairingStatus = true;
|
||||||
|
try {
|
||||||
|
await game.settings.set(MODULE_ID, SETTING_PAIRING_STATUS, text);
|
||||||
|
} catch (error) {
|
||||||
|
console.warn(`${MODULE_ID} | Could not store the Dragonroll pairing status.`, error);
|
||||||
|
} finally {
|
||||||
|
updatingPairingStatus = false;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Nothing is configured here: anything typed into the status is replaced by the
|
||||||
|
// status the module actually has.
|
||||||
|
function handlePairingStatusChange() {
|
||||||
|
if (updatingPairingStatus) return;
|
||||||
|
setPairingStatus(pairingStatusText());
|
||||||
|
}
|
||||||
|
|
||||||
|
// A token in this client only proves the world was paired once. Ask Dragonroll
|
||||||
|
// which campaign that token belongs to, and hear back when the campaign has
|
||||||
|
// unlinked this world again in the meantime.
|
||||||
|
async function refreshPairingStatus() {
|
||||||
|
const token = getSyncToken();
|
||||||
|
if (!token) {
|
||||||
|
linkedCampaignName = "";
|
||||||
|
await setPairingStatus(pairingStatusText());
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
try {
|
||||||
|
const result = await getDragonroll("foundry/sync/status", token);
|
||||||
|
linkedCampaignName = String(result.campaign?.name || "").trim();
|
||||||
|
if (pairingProblem === PAIRING_REVOKED) pairingProblem = "";
|
||||||
|
} catch (error) {
|
||||||
|
// An unauthorized token is a campaign that unlinked this world. Any other
|
||||||
|
// failure (an unreachable Dragonroll, or one old enough to have no status
|
||||||
|
// route) says nothing about the pairing, so keep showing what we know.
|
||||||
|
if (error.message === "unauthorized") pairingProblem = PAIRING_REVOKED;
|
||||||
|
}
|
||||||
|
await setPairingStatus(pairingStatusText());
|
||||||
|
}
|
||||||
|
|
||||||
function scheduleSnapshotSync(delay = 500) {
|
function scheduleSnapshotSync(delay = 500) {
|
||||||
clearTimeout(syncTimeout);
|
clearTimeout(syncTimeout);
|
||||||
syncTimeout = setTimeout(publishSnapshot, delay);
|
syncTimeout = setTimeout(publishSnapshot, delay);
|
||||||
@@ -287,6 +387,35 @@ function getSyncToken() {
|
|||||||
return game.settings.get(MODULE_ID, SETTING_SYNC_TOKEN)?.trim() || "";
|
return game.settings.get(MODULE_ID, SETTING_SYNC_TOKEN)?.trim() || "";
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// Autosync is what the module has always done: every Foundry create, update and
|
||||||
|
// delete pushes to Dragonroll, and both sides reconcile on a timer. When it is
|
||||||
|
// off, nothing syncs on its own and only a forced actor sync reaches Dragonroll.
|
||||||
|
function isAutoSyncEnabled() {
|
||||||
|
return game.settings.get(MODULE_ID, SETTING_AUTO_SYNC) !== false;
|
||||||
|
}
|
||||||
|
|
||||||
|
function handleAutoSyncChange(value) {
|
||||||
|
if (value === false) {
|
||||||
|
clearTimeout(actorSyncTimeout);
|
||||||
|
clearTimeout(itemSyncTimeout);
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
if (!game.user?.isGM || !getSyncToken()) return;
|
||||||
|
|
||||||
|
// Switching it back on converges both sides again, then the changes queued
|
||||||
|
// while autosync was off are pushed so this world's state wins over them.
|
||||||
|
initializeCharacterSync();
|
||||||
|
reconcileDragonrollItems();
|
||||||
|
if (queuedActorChanges.size) {
|
||||||
|
clearTimeout(actorSyncTimeout);
|
||||||
|
actorSyncTimeout = setTimeout(flushActorChanges, 400);
|
||||||
|
}
|
||||||
|
if (queuedItemChanges.size) {
|
||||||
|
clearTimeout(itemSyncTimeout);
|
||||||
|
itemSyncTimeout = setTimeout(flushItemChanges, 400);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
function dragonrollActorId(actor) {
|
function dragonrollActorId(actor) {
|
||||||
return actor.getFlag?.(MODULE_ID, "actorId") || actor.flags?.[MODULE_ID]?.actorId || "";
|
return actor.getFlag?.(MODULE_ID, "actorId") || actor.flags?.[MODULE_ID]?.actorId || "";
|
||||||
}
|
}
|
||||||
@@ -380,6 +509,34 @@ async function deleteDragonrollActor(foundryActorId) {
|
|||||||
}, token);
|
}, token);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// Sending actors on purpose, whether or not autosync is on: this is the push the
|
||||||
|
// GM asks for. It upserts those actors only, so unlike a full snapshot it never
|
||||||
|
// prunes anything else the campaign holds.
|
||||||
|
async function forceSyncActorsToDragonroll(actors) {
|
||||||
|
if (!game.user?.isGM || !game.world || !actors.length) return;
|
||||||
|
if (!getSyncToken()) {
|
||||||
|
ui.notifications?.warn("Link this world to a Dragonroll campaign before syncing actors to it.");
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
const supported = actors.filter(isSupportedCharacterActor);
|
||||||
|
const refused = actors.filter((actor) => !supported.includes(actor));
|
||||||
|
if (refused.length) {
|
||||||
|
ui.notifications?.warn(`${refused.map((actor) => actor.name).join(", ")} ${refused.length === 1 ? "is" : "are"} not a character, NPC or creature: Dragonroll does not import ${refused.length === 1 ? "it" : "them"}.`);
|
||||||
|
}
|
||||||
|
if (!supported.length) return;
|
||||||
|
|
||||||
|
try {
|
||||||
|
await pushFoundryActors(supported);
|
||||||
|
ui.notifications?.info(supported.length === 1
|
||||||
|
? `${supported[0].name} was sent to the Dragonroll campaign.`
|
||||||
|
: `${supported.length} actors were sent to the Dragonroll campaign.`);
|
||||||
|
} catch (error) {
|
||||||
|
console.error(`${MODULE_ID} | Could not force sync the selected actors.`, error);
|
||||||
|
ui.notifications?.error(`Dragonroll sync failed: ${error.message}`);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
function queueActorChange(kind, actor) {
|
function queueActorChange(kind, actor) {
|
||||||
if (!actor || !game.user?.isGM || !getSyncToken()) return;
|
if (!actor || !game.user?.isGM || !getSyncToken()) return;
|
||||||
if (syncingActorIds.has(actor.id) || actor.flags?.[MODULE_ID]?.syncMutation) return;
|
if (syncingActorIds.has(actor.id) || actor.flags?.[MODULE_ID]?.syncMutation) return;
|
||||||
@@ -389,6 +546,9 @@ function queueActorChange(kind, actor) {
|
|||||||
actorSyncTimeout = setTimeout(flushActorChanges, 400);
|
actorSyncTimeout = setTimeout(flushActorChanges, 400);
|
||||||
}
|
}
|
||||||
async function flushActorChanges() {
|
async function flushActorChanges() {
|
||||||
|
// Autosync may have been switched off while changes were queued: keep them
|
||||||
|
// waiting so turning it back on still sends them.
|
||||||
|
if (!isAutoSyncEnabled()) return;
|
||||||
const changes = [...queuedActorChanges.values()];
|
const changes = [...queuedActorChanges.values()];
|
||||||
queuedActorChanges.clear();
|
queuedActorChanges.clear();
|
||||||
const deleted = changes.filter((change) => change.kind === "delete");
|
const deleted = changes.filter((change) => change.kind === "delete");
|
||||||
@@ -518,6 +678,8 @@ function queueFoundryItemChange(kind, item) {
|
|||||||
}
|
}
|
||||||
|
|
||||||
async function flushItemChanges() {
|
async function flushItemChanges() {
|
||||||
|
// Autosync off: the queued edits wait here, like the actor changes do.
|
||||||
|
if (!isAutoSyncEnabled()) return;
|
||||||
const changes = [...queuedItemChanges.values()];
|
const changes = [...queuedItemChanges.values()];
|
||||||
queuedItemChanges.clear();
|
queuedItemChanges.clear();
|
||||||
const deleted = changes.filter((change) => change.kind === "delete");
|
const deleted = changes.filter((change) => change.kind === "delete");
|
||||||
@@ -616,7 +778,7 @@ async function createFoundryWorldItem(entry) {
|
|||||||
|
|
||||||
async function reconcileDragonrollItems() {
|
async function reconcileDragonrollItems() {
|
||||||
const token = getSyncToken();
|
const token = getSyncToken();
|
||||||
if (!token || !game.user?.isGM || !game.world || itemSyncRunning) return;
|
if (!token || !game.user?.isGM || !game.world || itemSyncRunning || !isAutoSyncEnabled()) return;
|
||||||
itemSyncRunning = true;
|
itemSyncRunning = true;
|
||||||
try {
|
try {
|
||||||
if (game.system.id !== "dnd5e") {
|
if (game.system.id !== "dnd5e") {
|
||||||
@@ -847,7 +1009,7 @@ async function createFoundryCharacter(entry) {
|
|||||||
|
|
||||||
async function reconcileDragonrollCharacters() {
|
async function reconcileDragonrollCharacters() {
|
||||||
const token = getSyncToken();
|
const token = getSyncToken();
|
||||||
if (!token || !game.user?.isGM || !game.world || characterSyncRunning) return;
|
if (!token || !game.user?.isGM || !game.world || characterSyncRunning || !isAutoSyncEnabled()) return;
|
||||||
characterSyncRunning = true;
|
characterSyncRunning = true;
|
||||||
try {
|
try {
|
||||||
if (game.system.id !== "dnd5e") {
|
if (game.system.id !== "dnd5e") {
|
||||||
@@ -887,7 +1049,7 @@ async function reconcileDragonrollCharacters() {
|
|||||||
}
|
}
|
||||||
|
|
||||||
async function initializeCharacterSync() {
|
async function initializeCharacterSync() {
|
||||||
if (!getSyncToken() || !game.user?.isGM || !game.world) return;
|
if (!getSyncToken() || !game.user?.isGM || !game.world || !isAutoSyncEnabled()) return;
|
||||||
try {
|
try {
|
||||||
await pushFoundryActors(game.actors.contents, true);
|
await pushFoundryActors(game.actors.contents, true);
|
||||||
await reconcileDragonrollCharacters();
|
await reconcileDragonrollCharacters();
|
||||||
@@ -978,11 +1140,12 @@ async function publishHeartbeat() {
|
|||||||
}
|
}
|
||||||
|
|
||||||
Hooks.once("ready", () => {
|
Hooks.once("ready", () => {
|
||||||
resumePendingDragonrollLink();
|
resumePendingDragonrollLink().then(refreshPairingStatus);
|
||||||
setInterval(() => {
|
setInterval(() => {
|
||||||
if (linkRetriesDisabled) return;
|
if (linkRetriesDisabled) return;
|
||||||
resumePendingDragonrollLink({ notifyOnError: false });
|
resumePendingDragonrollLink({ notifyOnError: false });
|
||||||
}, 60000);
|
}, 60000);
|
||||||
|
setInterval(refreshPairingStatus, 60000);
|
||||||
scheduleSnapshotSync(0);
|
scheduleSnapshotSync(0);
|
||||||
setInterval(publishHeartbeat, 60000);
|
setInterval(publishHeartbeat, 60000);
|
||||||
setTimeout(initializeCharacterSync, 1000);
|
setTimeout(initializeCharacterSync, 1000);
|
||||||
@@ -1016,3 +1179,21 @@ Hooks.once("ready", () => {
|
|||||||
});
|
});
|
||||||
}
|
}
|
||||||
});
|
});
|
||||||
|
|
||||||
|
// A GM sends selected actors to Dragonroll from the actor directory's context
|
||||||
|
// menu. This works with autosync on and off: it is the one push done on purpose.
|
||||||
|
Hooks.on("getActorDirectoryEntryContext", (html, options) => {
|
||||||
|
if (!game.user?.isGM || !getSyncToken()) return;
|
||||||
|
|
||||||
|
options.push({
|
||||||
|
name: "Dragonroll: Force Sync",
|
||||||
|
icon: '<i class="fa-solid fa-rotate"></i>',
|
||||||
|
// Array.from: the selected entries are jQuery in Foundry 12 and a plain
|
||||||
|
// array afterwards, and both are array-like.
|
||||||
|
callback: (entries) => forceSyncActorsToDragonroll(
|
||||||
|
Array.from(entries || [])
|
||||||
|
.map((entry) => game.actors?.get(entry.dataset?.actorId))
|
||||||
|
.filter(Boolean),
|
||||||
|
),
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|||||||
@@ -3,6 +3,7 @@ import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue'
|
|||||||
import { useI18n } from 'vue-i18n';
|
import { useI18n } from 'vue-i18n';
|
||||||
|
|
||||||
import { useCampaignService } from '~/services/Campaign.js';
|
import { useCampaignService } from '~/services/Campaign.js';
|
||||||
|
import { AnchorMap, AnchoredMap, ClearAnchoredMap, SetActivePane } from '~/services/Content.js';
|
||||||
import { emitter } from '~/services/Emitter';
|
import { emitter } from '~/services/Emitter';
|
||||||
import Server from '~/services/Server';
|
import Server from '~/services/Server';
|
||||||
import { ClearWindow, CreateWindow, GetFirstWindowId } from '~/services/Windows';
|
import { ClearWindow, CreateWindow, GetFirstWindowId } from '~/services/Windows';
|
||||||
@@ -119,6 +120,9 @@ function handleCampaignEntryUpdated({ entityType, entry }) {
|
|||||||
if (!list) return;
|
if (!list) return;
|
||||||
list.value = list.value.map((current) => current._id === entry._id ? entry : current)
|
list.value = list.value.map((current) => current._id === entry._id ? entry : current)
|
||||||
.sort((a, b) => a.name.localeCompare(b.name));
|
.sort((a, b) => a.name.localeCompare(b.name));
|
||||||
|
// The anchored map is this very entry (its pins changed, say): write it back without touching
|
||||||
|
// the pane, so switching back from the notes still shows what is on the map.
|
||||||
|
if (entityType === 'map' && AnchoredMap.value?._id === entry._id) AnchoredMap.value = entry;
|
||||||
}
|
}
|
||||||
|
|
||||||
const campaignId = computed(() => {
|
const campaignId = computed(() => {
|
||||||
@@ -207,6 +211,9 @@ async function fetchCampaignEntries(entityType = activeSection.value, silent = f
|
|||||||
function selectSection(section) {
|
function selectSection(section) {
|
||||||
activeSection.value = section;
|
activeSection.value = section;
|
||||||
if (isEntrySection(section)) fetchCampaignEntries(section);
|
if (isEntrySection(section)) fetchCampaignEntries(section);
|
||||||
|
// The content area follows the sidebar: maps shows the anchored map, everything else the
|
||||||
|
// notes that are currently open.
|
||||||
|
SetActivePane(section === 'maps' && AnchoredMap.value ? 'map' : 'notes');
|
||||||
}
|
}
|
||||||
|
|
||||||
function createEntry(entityType) {
|
function createEntry(entityType) {
|
||||||
@@ -272,6 +279,7 @@ function showEntryMenu(entry, entityType) {
|
|||||||
const response = await Server().post(`/${entityType}/delete`, { id: entry._id });
|
const response = await Server().post(`/${entityType}/delete`, { id: entry._id });
|
||||||
if (response.data.status === 'ok' && list) {
|
if (response.data.status === 'ok' && list) {
|
||||||
list.value = list.value.filter((current) => current._id !== entry._id);
|
list.value = list.value.filter((current) => current._id !== entry._id);
|
||||||
|
if (entityType === 'map' && isAnchoredMap(entry)) ClearAnchoredMap();
|
||||||
}
|
}
|
||||||
} catch (error) {} finally { HideContextMenu(); }
|
} catch (error) {} finally { HideContextMenu(); }
|
||||||
}
|
}
|
||||||
@@ -294,13 +302,17 @@ async function openCharacterSheet(actor) {
|
|||||||
CreateWindow('character_sheet', { actor });
|
CreateWindow('character_sheet', { actor });
|
||||||
}
|
}
|
||||||
|
|
||||||
async function openMapViewer(map) {
|
// Maps are anchored on the note container instead of opening a window: the notes that were open
|
||||||
const existingWindowId = GetFirstWindowId('map_viewer');
|
// stay open, and the sidebar's notes/maps buttons switch between the two.
|
||||||
if (existingWindowId !== undefined) {
|
function openMapViewer(map) {
|
||||||
ClearWindow({ id: existingWindowId });
|
if (!map) return;
|
||||||
await nextTick();
|
const floatingViewer = GetFirstWindowId('map_viewer');
|
||||||
}
|
if (floatingViewer !== undefined) ClearWindow({ id: floatingViewer });
|
||||||
CreateWindow('map_viewer', { map, campaign: campaignId.value });
|
AnchorMap(map);
|
||||||
|
}
|
||||||
|
|
||||||
|
function isAnchoredMap(map) {
|
||||||
|
return AnchoredMap.value?._id === map._id;
|
||||||
}
|
}
|
||||||
|
|
||||||
function createNote() {
|
function createNote() {
|
||||||
@@ -324,6 +336,7 @@ watch(campaignId, (newVal) => {
|
|||||||
actors.value = [];
|
actors.value = [];
|
||||||
items.value = [];
|
items.value = [];
|
||||||
maps.value = [];
|
maps.value = [];
|
||||||
|
ClearAnchoredMap();
|
||||||
fetchCampaignNotes();
|
fetchCampaignNotes();
|
||||||
if (isEntrySection(activeSection.value)) fetchCampaignEntries(activeSection.value);
|
if (isEntrySection(activeSection.value)) fetchCampaignEntries(activeSection.value);
|
||||||
} else {
|
} else {
|
||||||
@@ -334,6 +347,7 @@ watch(campaignId, (newVal) => {
|
|||||||
maps.value = [];
|
maps.value = [];
|
||||||
notesError.value = '';
|
notesError.value = '';
|
||||||
entriesError.value = '';
|
entriesError.value = '';
|
||||||
|
ClearAnchoredMap();
|
||||||
}
|
}
|
||||||
});
|
});
|
||||||
|
|
||||||
@@ -502,8 +516,11 @@ onBeforeUnmount(() => {
|
|||||||
<div v-if="loadingEntries" class="sidebar-state">{{ t('campaigns.states.loading') }}</div>
|
<div v-if="loadingEntries" class="sidebar-state">{{ t('campaigns.states.loading') }}</div>
|
||||||
<div v-else-if="entriesError" class="sidebar-state error">{{ entriesError }}</div>
|
<div v-else-if="entriesError" class="sidebar-state error">{{ entriesError }}</div>
|
||||||
<div v-else-if="maps.length === 0" class="sidebar-state">{{ t('campaigns.states.empty-maps') }}</div>
|
<div v-else-if="maps.length === 0" class="sidebar-state">{{ t('campaigns.states.empty-maps') }}</div>
|
||||||
<div v-for="map in maps" :key="map._id" class="entity-entry" role="button" tabindex="0" @click="openMapViewer(map)" @keydown.enter="openMapViewer(map)" @keydown.space.prevent="openMapViewer(map)" @contextmenu.prevent="showEntryMenu(map, 'map')">
|
<div v-for="map in maps" :key="map._id" class="entity-entry" :class="{ anchored: isAnchoredMap(map) }" role="button" tabindex="0" @click="openMapViewer(map)" @keydown.enter="openMapViewer(map)" @keydown.space.prevent="openMapViewer(map)" @contextmenu.prevent="showEntryMenu(map, 'map')">
|
||||||
|
<span class="entity-entry-name-row">
|
||||||
<span class="entity-entry-name">{{ map.name }}</span>
|
<span class="entity-entry-name">{{ map.name }}</span>
|
||||||
|
<span v-if="isAnchoredMap(map)" class="entity-entry-sync">{{ t('campaigns.map.anchored') }}</span>
|
||||||
|
</span>
|
||||||
<span class="entity-entry-meta">{{ mapSummary(map) }}</span>
|
<span class="entity-entry-meta">{{ mapSummary(map) }}</span>
|
||||||
<span v-if="!map.image" class="entity-entry-description">{{ t('campaigns.map.no-image') }}</span>
|
<span v-if="!map.image" class="entity-entry-description">{{ t('campaigns.map.no-image') }}</span>
|
||||||
</div>
|
</div>
|
||||||
@@ -654,6 +671,8 @@ onBeforeUnmount(() => {
|
|||||||
}
|
}
|
||||||
.entity-entry:hover { border-color: var(--color-border); background: var(--color-background-soft); }
|
.entity-entry:hover { border-color: var(--color-border); background: var(--color-background-soft); }
|
||||||
.entity-entry:focus-visible { outline: 1px solid var(--color-link); }
|
.entity-entry:focus-visible { outline: 1px solid var(--color-link); }
|
||||||
|
/* The map currently anchored on the note container. */
|
||||||
|
.entity-entry.anchored { border-color: var(--color-link); background: var(--color-background-soft); }
|
||||||
.entity-entry-name-row { display: flex; align-items: baseline; gap: 6px; }
|
.entity-entry-name-row { display: flex; align-items: baseline; gap: 6px; }
|
||||||
.entity-entry-name { font-weight: bold; }
|
.entity-entry-name { font-weight: bold; }
|
||||||
.entity-entry-sync {
|
.entity-entry-sync {
|
||||||
|
|||||||
@@ -1,13 +1,30 @@
|
|||||||
<script setup>
|
<script setup>
|
||||||
import NoteContainer from './NoteContainer.vue';
|
import NoteContainer from './NoteContainer.vue';
|
||||||
|
import MapViewerPane from '../map/MapViewerPane.vue';
|
||||||
|
|
||||||
|
import { ActivePane, AnchoredMap, ClearAnchoredMap } from '~/services/Content.js';
|
||||||
|
import { useCampaignService } from '~/services/Campaign.js';
|
||||||
|
import { CreateWindow } from '~/services/Windows';
|
||||||
|
|
||||||
|
const { Campaign } = useCampaignService();
|
||||||
|
|
||||||
|
// Detaching gives the map back a floating window and shows the open notes again.
|
||||||
|
function DetachMap() {
|
||||||
|
const map = AnchoredMap.value;
|
||||||
|
if (!map) return;
|
||||||
|
ClearAnchoredMap();
|
||||||
|
CreateWindow('map_viewer', { map, campaign: Campaign.value?._id ?? null });
|
||||||
|
}
|
||||||
</script>
|
</script>
|
||||||
|
|
||||||
<template>
|
<template>
|
||||||
<div class="content">
|
<div class="content">
|
||||||
<NoteContainer>
|
<NoteContainer v-show="ActivePane !== 'map'">
|
||||||
|
|
||||||
</NoteContainer>
|
</NoteContainer>
|
||||||
|
<div v-if="AnchoredMap" v-show="ActivePane === 'map'" class="anchored-map">
|
||||||
|
<MapViewerPane :map="AnchoredMap" anchored @detach="DetachMap"></MapViewerPane>
|
||||||
|
</div>
|
||||||
<!-- PowerMod -->
|
<!-- PowerMod -->
|
||||||
</div>
|
</div>
|
||||||
</template>
|
</template>
|
||||||
@@ -21,4 +38,14 @@ import NoteContainer from './NoteContainer.vue';
|
|||||||
align-items: center;
|
align-items: center;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/* Hidden with v-show so the open notes stay mounted while the anchored map is displayed. */
|
||||||
|
.anchored-map {
|
||||||
|
width: 100%;
|
||||||
|
height: 100%;
|
||||||
|
min-width: 0;
|
||||||
|
flex-grow: 1;
|
||||||
|
display: flex;
|
||||||
|
flex-direction: column;
|
||||||
|
}
|
||||||
|
|
||||||
</style>
|
</style>
|
||||||
@@ -2,6 +2,7 @@
|
|||||||
import { onMounted, onUnmounted, ref } from 'vue';
|
import { onMounted, onUnmounted, ref } from 'vue';
|
||||||
import Note from './Note.vue';
|
import Note from './Note.vue';
|
||||||
import { emitter } from '~/services/Emitter';
|
import { emitter } from '~/services/Emitter';
|
||||||
|
import { SetActivePane } from '~/services/Content.js';
|
||||||
|
|
||||||
let noteData = ref([]);
|
let noteData = ref([]);
|
||||||
|
|
||||||
@@ -34,6 +35,9 @@ function pushNote(note){
|
|||||||
}
|
}
|
||||||
|
|
||||||
function handlePushNote(note) {
|
function handlePushNote(note) {
|
||||||
|
// A note opened from the sidebar or the search palette always comes to the front, even when
|
||||||
|
// the content area is showing an anchored map.
|
||||||
|
SetActivePane('notes');
|
||||||
pushNote(note);
|
pushNote(note);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
410
frontend/app/components/viewer/map/MapViewerPane.vue
Normal file
410
frontend/app/components/viewer/map/MapViewerPane.vue
Normal file
@@ -0,0 +1,410 @@
|
|||||||
|
<script setup>
|
||||||
|
import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue';
|
||||||
|
import { useI18n } from 'vue-i18n';
|
||||||
|
import { ClearWindow, CreateWindow, GetFirstWindowId } from '@/services/Windows';
|
||||||
|
import { HideContextMenu, ShowContextMenu } from '~/services/ContextMenu';
|
||||||
|
import { BuildNoteOptions, OptionLabel, ToImagePoint, ToScreenPoint } from '~/services/MapPins';
|
||||||
|
import { DisplayToast } from '~/services/Toaster';
|
||||||
|
import Server, { getBaseUrl } from '~/services/Server';
|
||||||
|
import { emitter } from '~/services/Emitter';
|
||||||
|
import { useCampaignService } from '~/services/Campaign.js';
|
||||||
|
|
||||||
|
// The map viewer without window chrome: it fills whatever flex column holds it, so the same
|
||||||
|
// component works inside MapViewerWindow.vue and anchored on the campaign content area.
|
||||||
|
const props = defineProps({
|
||||||
|
map: { type: Object, default: null },
|
||||||
|
// Anchored maps can be detached into a floating window; the window itself does not offer it.
|
||||||
|
anchored: { type: Boolean, default: false }
|
||||||
|
});
|
||||||
|
const emit = defineEmits(['detach']);
|
||||||
|
|
||||||
|
const { Campaign } = useCampaignService();
|
||||||
|
const campaignId = computed(() => Campaign.value?._id ?? Campaign.value?.id ?? null);
|
||||||
|
|
||||||
|
const map = ref(props.map ? { ...props.map } : null);
|
||||||
|
const viewport = ref(null);
|
||||||
|
|
||||||
|
const zoom = ref(1);
|
||||||
|
const pan = ref({ x: 0, y: 0 });
|
||||||
|
const imageSize = ref({ width: 0, height: 0 });
|
||||||
|
const showGrid = ref(true);
|
||||||
|
const dragging = ref(false);
|
||||||
|
|
||||||
|
const minZoom = 0.05;
|
||||||
|
const maxZoom = 8;
|
||||||
|
|
||||||
|
const imageUrl = computed(() => {
|
||||||
|
const image = map.value?.image;
|
||||||
|
if (!image) return '';
|
||||||
|
return /^(https?:|data:|\/\/)/i.test(image) ? image : `${getBaseUrl()}/public/${image}`;
|
||||||
|
});
|
||||||
|
|
||||||
|
const stageStyle = computed(() => ({
|
||||||
|
transform: `translate3d(${pan.value.x}px, ${pan.value.y}px, 0) scale(${zoom.value})`
|
||||||
|
}));
|
||||||
|
|
||||||
|
// The grid is drawn in screen space over the image so its lines stay one pixel wide at any zoom.
|
||||||
|
const gridStyle = computed(() => {
|
||||||
|
if (!showGrid.value || !imageSize.value.width) return { display: 'none' };
|
||||||
|
const cell = `${Math.max(1, Number(map.value?.gridSize) || 50) * zoom.value}px`;
|
||||||
|
return {
|
||||||
|
width: `${imageSize.value.width * zoom.value}px`,
|
||||||
|
height: `${imageSize.value.height * zoom.value}px`,
|
||||||
|
transform: `translate3d(${pan.value.x + (Number(map.value?.offsetX) || 0) * zoom.value}px, ${pan.value.y + (Number(map.value?.offsetY) || 0) * zoom.value}px, 0)`,
|
||||||
|
backgroundImage: `linear-gradient(to right, var(--color-link) 1px, transparent 1px), linear-gradient(to bottom, var(--color-link) 1px, transparent 1px)`,
|
||||||
|
backgroundSize: `${cell} ${cell}`
|
||||||
|
};
|
||||||
|
});
|
||||||
|
|
||||||
|
const zoomPercent = computed(() => `${Math.round(zoom.value * 100)}%`);
|
||||||
|
|
||||||
|
function clampZoom(value) {
|
||||||
|
if (!Number.isFinite(value)) return minZoom;
|
||||||
|
return Math.min(maxZoom, Math.max(minZoom, value));
|
||||||
|
}
|
||||||
|
|
||||||
|
function fitToWindow() {
|
||||||
|
const bounds = viewport.value?.getBoundingClientRect();
|
||||||
|
if (!bounds || !imageSize.value.width) return;
|
||||||
|
zoom.value = clampZoom(Math.min(bounds.width / imageSize.value.width, bounds.height / imageSize.value.height));
|
||||||
|
centerOn();
|
||||||
|
}
|
||||||
|
|
||||||
|
function centerOn() {
|
||||||
|
const bounds = viewport.value?.getBoundingClientRect();
|
||||||
|
if (!bounds || !imageSize.value.width) return;
|
||||||
|
pan.value = {
|
||||||
|
x: (bounds.width - imageSize.value.width * zoom.value) / 2,
|
||||||
|
y: (bounds.height - imageSize.value.height * zoom.value) / 2
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
function onImageLoaded(event) {
|
||||||
|
imageSize.value = { width: event.target.naturalWidth, height: event.target.naturalHeight };
|
||||||
|
fitToWindow();
|
||||||
|
}
|
||||||
|
|
||||||
|
// Zoom keeping the map point under `point` where it is.
|
||||||
|
function zoomAt(factor, point) {
|
||||||
|
const next = clampZoom(zoom.value * factor);
|
||||||
|
if (next === zoom.value) return;
|
||||||
|
const ratio = next / zoom.value;
|
||||||
|
pan.value = {
|
||||||
|
x: point.x - (point.x - pan.value.x) * ratio,
|
||||||
|
y: point.y - (point.y - pan.value.y) * ratio
|
||||||
|
};
|
||||||
|
zoom.value = next;
|
||||||
|
}
|
||||||
|
|
||||||
|
function onWheel(event) {
|
||||||
|
const bounds = viewport.value?.getBoundingClientRect();
|
||||||
|
if (!bounds) return;
|
||||||
|
zoomAt(event.deltaY < 0 ? 1.15 : 1 / 1.15, { x: event.clientX - bounds.left, y: event.clientY - bounds.top });
|
||||||
|
}
|
||||||
|
|
||||||
|
function zoomFromToolbar(incoming) {
|
||||||
|
const bounds = viewport.value?.getBoundingClientRect();
|
||||||
|
if (!bounds) return;
|
||||||
|
zoomAt(incoming ? 1.25 : 1 / 1.25, { x: bounds.width / 2, y: bounds.height / 2 });
|
||||||
|
}
|
||||||
|
|
||||||
|
let pointerId = null;
|
||||||
|
let lastPointer = { x: 0, y: 0 };
|
||||||
|
|
||||||
|
function onPointerDown(event) {
|
||||||
|
if (event.button !== 0 || !viewport.value) return;
|
||||||
|
dragging.value = true;
|
||||||
|
pointerId = event.pointerId;
|
||||||
|
lastPointer = { x: event.clientX, y: event.clientY };
|
||||||
|
viewport.value.setPointerCapture?.(event.pointerId);
|
||||||
|
}
|
||||||
|
|
||||||
|
function onPointerMove(event) {
|
||||||
|
if (!dragging.value || event.pointerId !== pointerId) return;
|
||||||
|
pan.value = { x: pan.value.x + (event.clientX - lastPointer.x), y: pan.value.y + (event.clientY - lastPointer.y) };
|
||||||
|
lastPointer = { x: event.clientX, y: event.clientY };
|
||||||
|
}
|
||||||
|
|
||||||
|
function onPointerUp(event) {
|
||||||
|
if (event.pointerId !== pointerId) return;
|
||||||
|
dragging.value = false;
|
||||||
|
pointerId = null;
|
||||||
|
viewport.value?.releasePointerCapture?.(event.pointerId);
|
||||||
|
}
|
||||||
|
|
||||||
|
function editMap() {
|
||||||
|
if (!map.value || !campaignId.value) return;
|
||||||
|
CreateWindow('create_map', { campaign: campaignId.value, entry: map.value });
|
||||||
|
}
|
||||||
|
|
||||||
|
function handleMapUpdated({ entityType, entry }) {
|
||||||
|
if (entityType !== 'map' || entry?._id !== map.value?._id) return;
|
||||||
|
const imageChanged = entry.image !== map.value.image;
|
||||||
|
map.value = { ...entry };
|
||||||
|
// A new image is fitted again by onImageLoaded; grid-only changes just move the overlay.
|
||||||
|
if (imageChanged) imageSize.value = { width: 0, height: 0 };
|
||||||
|
}
|
||||||
|
|
||||||
|
// --- Notes pinned onto the map ---
|
||||||
|
// Right clicking the map pins one of the campaign notes at that spot, and clicking the marker reads
|
||||||
|
// it in a window of its own.
|
||||||
|
|
||||||
|
const { t } = useI18n();
|
||||||
|
const noteOptions = ref([]);
|
||||||
|
const pins = computed(() => map.value?.pins ?? []);
|
||||||
|
const labelByNoteId = computed(() => new Map(noteOptions.value.map((option) => [option.value, option.label])));
|
||||||
|
|
||||||
|
// What the pin helpers need to know about the current view to translate between image and screen.
|
||||||
|
function viewState() {
|
||||||
|
return { zoom: zoom.value, pan: pan.value, width: imageSize.value.width, height: imageSize.value.height };
|
||||||
|
}
|
||||||
|
|
||||||
|
function pinStyle(pin) {
|
||||||
|
const point = ToScreenPoint(pin, viewState());
|
||||||
|
return { left: `${point.x}px`, top: `${point.y}px` };
|
||||||
|
}
|
||||||
|
|
||||||
|
function pinLabel(pin) {
|
||||||
|
return labelByNoteId.value.get(String(pin?.note)) ?? '';
|
||||||
|
}
|
||||||
|
|
||||||
|
// Every note of the campaign, so notes living in a folder can be pinned too and every marker can
|
||||||
|
// say which note it is.
|
||||||
|
async function fetchPinnableNotes() {
|
||||||
|
if (!campaignId.value) {
|
||||||
|
noteOptions.value = [];
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
try {
|
||||||
|
const response = await Server().get('/note/all', { params: { campaign: campaignId.value } });
|
||||||
|
noteOptions.value = response.data.status === 'ok'
|
||||||
|
? BuildNoteOptions(response.data.notes, response.data.folders)
|
||||||
|
: [];
|
||||||
|
} catch (error) {
|
||||||
|
noteOptions.value = [];
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
function onMapContextMenu(event) {
|
||||||
|
// A pin marks a spot on the image, so there is nothing to pin while the map has no image.
|
||||||
|
const bounds = viewport.value?.getBoundingClientRect();
|
||||||
|
if (!imageUrl.value || !bounds) return;
|
||||||
|
|
||||||
|
// Reaching a submenu moves the mouse away from the spot, so it is kept for the menu actions.
|
||||||
|
const spot = ToImagePoint({ x: event.clientX - bounds.left, y: event.clientY - bounds.top }, viewState());
|
||||||
|
if (!spot) return;
|
||||||
|
|
||||||
|
if (!noteOptions.value.length) {
|
||||||
|
ShowContextMenu([{ name: t('campaigns.map.pins.none'), action: () => HideContextMenu() }]);
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
ShowContextMenu([{
|
||||||
|
name: t('campaigns.map.pins.add'),
|
||||||
|
icon: '/icons/iconoir/regular/map-pin-plus.svg',
|
||||||
|
context: noteOptions.value.map((option) => ({
|
||||||
|
name: option.label,
|
||||||
|
icon: '/icons/iconoir/regular/notes.svg',
|
||||||
|
action: () => { HideContextMenu(); savePin(option.value, spot); }
|
||||||
|
}))
|
||||||
|
}]);
|
||||||
|
}
|
||||||
|
|
||||||
|
function onPinContextMenu(pin) {
|
||||||
|
ShowContextMenu([
|
||||||
|
{
|
||||||
|
name: t('campaigns.map.pins.open'),
|
||||||
|
icon: '/icons/iconoir/regular/notes.svg',
|
||||||
|
action: () => { HideContextMenu(); openPinnedNote(pin); }
|
||||||
|
},
|
||||||
|
{ divider: true },
|
||||||
|
{
|
||||||
|
name: t('campaigns.map.pins.remove'),
|
||||||
|
icon: '/icons/iconoir/regular/map-pin-xmark.svg',
|
||||||
|
action: () => { HideContextMenu(); removePin(pin); }
|
||||||
|
}
|
||||||
|
]);
|
||||||
|
}
|
||||||
|
|
||||||
|
async function savePin(noteId, spot) {
|
||||||
|
await updatePins('/map/pin', { id: map.value?._id, note: noteId, x: spot.x, y: spot.y });
|
||||||
|
}
|
||||||
|
|
||||||
|
async function removePin(pin) {
|
||||||
|
await updatePins('/map/unpin', { id: map.value?._id, pin: pin?._id });
|
||||||
|
}
|
||||||
|
|
||||||
|
// Both pin changes answer with the whole map, which keeps the sidebar entry and the anchored map in
|
||||||
|
// step with what is on screen.
|
||||||
|
async function updatePins(route, body) {
|
||||||
|
if (!body.id) return;
|
||||||
|
try {
|
||||||
|
const response = await Server().post(route, body);
|
||||||
|
if (response.data.status !== 'ok') {
|
||||||
|
DisplayToast('red', t('campaigns.map.pins.error'), 3000);
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
map.value = { ...response.data.map };
|
||||||
|
emitter.emit('campaign-entry-updated', { entityType: 'map', entry: response.data.map });
|
||||||
|
} catch (error) {
|
||||||
|
DisplayToast('red', t('campaigns.map.pins.error'), 3000);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
async function openPinnedNote(pin) {
|
||||||
|
if (!pin?.note) return;
|
||||||
|
// One window reads the pinned notes; opening another one replaces it, like the character sheet.
|
||||||
|
const existingWindowId = GetFirstWindowId('pinned_note');
|
||||||
|
if (existingWindowId !== undefined) ClearWindow({ id: existingWindowId });
|
||||||
|
await nextTick();
|
||||||
|
CreateWindow('pinned_note', { note: pin.note });
|
||||||
|
}
|
||||||
|
|
||||||
|
// The backend drops the pins of a note along with it; the markers on this open map follow at once.
|
||||||
|
function handlePinnedNoteDeleted(noteKey) {
|
||||||
|
if (!pins.value.length) return;
|
||||||
|
const remaining = map.value.pins.filter((pin) => String(pin.note) !== String(noteKey));
|
||||||
|
if (remaining.length !== map.value.pins.length) map.value = { ...map.value, pins: remaining };
|
||||||
|
}
|
||||||
|
|
||||||
|
function handlePinnedNoteRenamed({ key, title }) {
|
||||||
|
const option = noteOptions.value.find((current) => current.value === String(key));
|
||||||
|
if (!option) return;
|
||||||
|
option.title = title;
|
||||||
|
option.label = OptionLabel(option);
|
||||||
|
}
|
||||||
|
|
||||||
|
// A different map was anchored while this pane was already mounted.
|
||||||
|
watch(() => props.map, (incoming, previous) => {
|
||||||
|
if (incoming === previous) return;
|
||||||
|
map.value = incoming ? { ...incoming } : null;
|
||||||
|
imageSize.value = { width: 0, height: 0 };
|
||||||
|
});
|
||||||
|
|
||||||
|
watch(campaignId, () => {
|
||||||
|
noteOptions.value = [];
|
||||||
|
fetchPinnableNotes();
|
||||||
|
});
|
||||||
|
|
||||||
|
onMounted(() => {
|
||||||
|
emitter.on('campaign-entry-updated', handleMapUpdated);
|
||||||
|
emitter.on('delete-note', handlePinnedNoteDeleted);
|
||||||
|
emitter.on('title-updated', handlePinnedNoteRenamed);
|
||||||
|
fetchPinnableNotes();
|
||||||
|
});
|
||||||
|
|
||||||
|
onBeforeUnmount(() => {
|
||||||
|
emitter.off('campaign-entry-updated', handleMapUpdated);
|
||||||
|
emitter.off('delete-note', handlePinnedNoteDeleted);
|
||||||
|
emitter.off('title-updated', handlePinnedNoteRenamed);
|
||||||
|
});
|
||||||
|
</script>
|
||||||
|
|
||||||
|
<template>
|
||||||
|
<div class="map-pane">
|
||||||
|
<div class="viewer-bar">
|
||||||
|
<div class="viewer-identity">
|
||||||
|
<strong>{{ map?.name }}</strong>
|
||||||
|
<span class="viewer-meta">{{ $t('campaigns.map.summary', { size: map?.gridSize, scale: map?.scale }) }}</span>
|
||||||
|
</div>
|
||||||
|
<div class="viewer-tools">
|
||||||
|
<button class="viewer-tool" :class="{ selected: showGrid }" type="button" :title="$t('campaigns.map.toggle-grid')"
|
||||||
|
:aria-label="$t('campaigns.map.toggle-grid')" :aria-pressed="showGrid.toString()" @click="showGrid = !showGrid">
|
||||||
|
<img class="tool-icon" src="/icons/iconoir/regular/view-grid.svg" alt="" aria-hidden="true">
|
||||||
|
</button>
|
||||||
|
<button class="viewer-tool" type="button" :title="$t('campaigns.map.zoom-out')" :aria-label="$t('campaigns.map.zoom-out')" @click="zoomFromToolbar(false)">
|
||||||
|
<img class="tool-icon" src="/icons/iconoir/regular/minus.svg" alt="" aria-hidden="true">
|
||||||
|
</button>
|
||||||
|
<span class="zoom-readout">{{ zoomPercent }}</span>
|
||||||
|
<button class="viewer-tool" type="button" :title="$t('campaigns.map.zoom-in')" :aria-label="$t('campaigns.map.zoom-in')" @click="zoomFromToolbar(true)">
|
||||||
|
<img class="tool-icon" src="/icons/iconoir/regular/plus.svg" alt="" aria-hidden="true">
|
||||||
|
</button>
|
||||||
|
<button class="viewer-tool" type="button" :title="$t('campaigns.map.fit')" :aria-label="$t('campaigns.map.fit')" @click="fitToWindow">
|
||||||
|
<img class="tool-icon" src="/icons/iconoir/regular/expand.svg" alt="" aria-hidden="true">
|
||||||
|
</button>
|
||||||
|
<button class="viewer-tool" type="button" :title="$t('campaigns.map.edit')" :aria-label="$t('campaigns.map.edit')" @click="editMap">
|
||||||
|
<img class="tool-icon" src="/icons/iconoir/regular/edit.svg" alt="" aria-hidden="true">
|
||||||
|
</button>
|
||||||
|
<button v-if="anchored" class="viewer-tool" type="button" :title="$t('campaigns.map.open-window')" :aria-label="$t('campaigns.map.open-window')"
|
||||||
|
@click="emit('detach')">
|
||||||
|
<img class="tool-icon" src="/icons/iconoir/regular/open-in-window.svg" alt="" aria-hidden="true">
|
||||||
|
</button>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
|
||||||
|
<div
|
||||||
|
ref="viewport"
|
||||||
|
class="map-viewport"
|
||||||
|
:class="{ dragging }"
|
||||||
|
@wheel.prevent="onWheel"
|
||||||
|
@pointerdown="onPointerDown"
|
||||||
|
@pointermove="onPointerMove"
|
||||||
|
@pointerup="onPointerUp"
|
||||||
|
@pointercancel="onPointerUp"
|
||||||
|
@contextmenu.prevent="onMapContextMenu"
|
||||||
|
>
|
||||||
|
<template v-if="imageUrl">
|
||||||
|
<img class="map-image" :src="imageUrl" :style="stageStyle" :alt="map?.name" draggable="false" @load="onImageLoaded">
|
||||||
|
<div class="map-grid" :style="gridStyle" aria-hidden="true"></div>
|
||||||
|
<div class="map-pins">
|
||||||
|
<button
|
||||||
|
v-for="pin in pins"
|
||||||
|
:key="pin._id"
|
||||||
|
class="map-pin"
|
||||||
|
type="button"
|
||||||
|
:style="pinStyle(pin)"
|
||||||
|
:title="pinLabel(pin) || $t('campaigns.map.pins.open')"
|
||||||
|
:aria-label="pinLabel(pin) || $t('campaigns.map.pins.open')"
|
||||||
|
@pointerdown.stop
|
||||||
|
@click="openPinnedNote(pin)"
|
||||||
|
@contextmenu.stop.prevent="onPinContextMenu(pin)"
|
||||||
|
>
|
||||||
|
<img class="pin-icon" src="/icons/iconoir/solid/pin.svg" alt="" aria-hidden="true">
|
||||||
|
<span class="pin-label">{{ pinLabel(pin) }}</span>
|
||||||
|
</button>
|
||||||
|
</div>
|
||||||
|
</template>
|
||||||
|
<div v-else class="map-empty">
|
||||||
|
{{ $t('campaigns.map.no-image') }}
|
||||||
|
<button class="map-edit" type="button" @click="editMap">{{ $t('campaigns.map.upload-photo') }}</button>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</template>
|
||||||
|
|
||||||
|
<style scoped>
|
||||||
|
.map-pane { width: 100%; flex: 1; min-width: 0; min-height: 0; display: flex; flex-direction: column; overflow: hidden; }
|
||||||
|
.viewer-bar { width: 100%; box-sizing: border-box; display: flex; align-items: center; justify-content: space-between; gap: 10px; padding: 8px 10px; border-bottom: 1px solid var(--color-border); background: var(--color-background-light); }
|
||||||
|
.viewer-identity { min-width: 0; display: flex; flex-direction: column; gap: 2px; }
|
||||||
|
.viewer-identity strong { font-family: MrEavesRemake; overflow-wrap: anywhere; }
|
||||||
|
.viewer-meta { font-size: 11px; opacity: .72; }
|
||||||
|
.viewer-tools { display: flex; align-items: center; gap: 4px; }
|
||||||
|
.viewer-tool { width: 30px; height: 30px; margin: 0; padding: 0; border: 1px solid var(--color-border); border-radius: 7px; background: var(--color-background-soft); display: flex; align-items: center; justify-content: center; cursor: pointer; }
|
||||||
|
.viewer-tool:hover { background: var(--color-button-hover); }
|
||||||
|
.viewer-tool.selected { border-color: var(--color-link); background: var(--color-button-hover); }
|
||||||
|
.tool-icon { width: 16px; height: 16px; filter: invert(var(--color-icon-invert)); }
|
||||||
|
.zoom-readout { min-width: 46px; text-align: center; font-size: 12px; }
|
||||||
|
.map-viewport { position: relative; width: 100%; flex: 1; min-height: 0; overflow: hidden; background-color: var(--color-background); cursor: grab; touch-action: none; }
|
||||||
|
.map-viewport.dragging { cursor: grabbing; }
|
||||||
|
.map-image { position: absolute; top: 0; left: 0; max-width: none; transform-origin: top left; user-select: none; }
|
||||||
|
.map-grid { position: absolute; top: 0; left: 0; opacity: .55; pointer-events: none; }
|
||||||
|
/* Pins live in image pixels but are drawn in screen space (see ToScreenPoint), so the overlay stays
|
||||||
|
unscaled and their markers are readable at every zoom. Only the markers catch the mouse. */
|
||||||
|
.map-pins { position: absolute; inset: 0; pointer-events: none; }
|
||||||
|
.map-pin {
|
||||||
|
position: absolute; transform: translate(-50%, -100%); pointer-events: auto;
|
||||||
|
display: flex; align-items: center; gap: 4px; margin: 0; padding: 3px 6px;
|
||||||
|
border: 1px solid var(--color-link); border-radius: 7px;
|
||||||
|
background: var(--color-background-soft); color: var(--color-text);
|
||||||
|
font-size: 11px; cursor: pointer; box-shadow: 0px 0px 6px -1px rgba(0,0,0,0.55);
|
||||||
|
}
|
||||||
|
.map-pin:hover { background: var(--color-button-hover); }
|
||||||
|
.map-pin:focus-visible { outline: 1px solid var(--color-link); }
|
||||||
|
.pin-icon { width: 12px; height: 12px; filter: invert(var(--color-icon-invert)); }
|
||||||
|
/* The note's name only when it is asked for: a map full of labels is a map nobody can read. */
|
||||||
|
.pin-label { display: none; max-width: 200px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
|
||||||
|
.map-pin:hover .pin-label, .map-pin:focus-visible .pin-label { display: inline; }
|
||||||
|
.map-empty { width: 100%; height: 100%; display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 8px; font-size: 13px; opacity: .8; }
|
||||||
|
.map-edit { border: 1px solid var(--color-border); border-radius: 7px; padding: 6px 11px; background: var(--color-background-soft); color: var(--color-text); font-size: 12px; cursor: pointer; }
|
||||||
|
.map-edit:hover { background: var(--color-button-hover); }
|
||||||
|
</style>
|
||||||
@@ -129,7 +129,8 @@ async function saveMap() {
|
|||||||
</label>
|
</label>
|
||||||
<label class="form-field">
|
<label class="form-field">
|
||||||
<span>{{ $t('campaigns.map.scale') }}</span>
|
<span>{{ $t('campaigns.map.scale') }}</span>
|
||||||
<input v-model.number="form.scale" type="number" min="0.01" step="0.5">
|
<!-- step="any": any decimal works, the 0.01 minimum alone keeps it positive -->
|
||||||
|
<input v-model.number="form.scale" type="number" min="0.01" step="any" inputmode="decimal">
|
||||||
</label>
|
</label>
|
||||||
<label class="form-field">
|
<label class="form-field">
|
||||||
<span>{{ $t('campaigns.map.offset-x') }}</span>
|
<span>{{ $t('campaigns.map.offset-x') }}</span>
|
||||||
@@ -154,7 +155,16 @@ async function saveMap() {
|
|||||||
|
|
||||||
<style scoped>
|
<style scoped>
|
||||||
.window-wrapper { display: flex; align-items: center; flex-direction: column; }
|
.window-wrapper { display: flex; align-items: center; flex-direction: column; }
|
||||||
.body { width: 100%; padding: 10px 18px 16px; overflow-y: auto; }
|
/* Stretch so the outer margin insets the content instead of overflowing the window. */
|
||||||
|
.body {
|
||||||
|
flex: 1;
|
||||||
|
min-height: 0;
|
||||||
|
align-self: stretch;
|
||||||
|
box-sizing: border-box;
|
||||||
|
margin: 10px;
|
||||||
|
padding: 8px;
|
||||||
|
overflow-y: auto;
|
||||||
|
}
|
||||||
h3 { margin: 0 0 12px; font-family: MrEavesRemake; }
|
h3 { margin: 0 0 12px; font-family: MrEavesRemake; }
|
||||||
form { display: flex; flex-direction: column; gap: 10px; }
|
form { display: flex; flex-direction: column; gap: 10px; }
|
||||||
.form-field { min-width: 0; display: flex; flex-direction: column; gap: 4px; font-size: 13px; }
|
.form-field { min-width: 0; display: flex; flex-direction: column; gap: 4px; font-size: 13px; }
|
||||||
|
|||||||
@@ -1,139 +1,14 @@
|
|||||||
<script setup>
|
<script setup>
|
||||||
import { computed, onBeforeUnmount, onMounted, ref } from 'vue';
|
import { onMounted, ref } from 'vue';
|
||||||
import { SetupHandle, SetSize, ResetPosition, ClearWindow, Top, CreateWindow } from '@/services/Windows';
|
import { SetupHandle, SetSize, ResetPosition, Top } from '@/services/Windows';
|
||||||
import WindowHandle from './partials/WindowHandle.vue';
|
import WindowHandle from './partials/WindowHandle.vue';
|
||||||
import { getBaseUrl } from '~/services/Server';
|
import MapViewerPane from '../viewer/map/MapViewerPane.vue';
|
||||||
import { emitter } from '~/services/Emitter';
|
|
||||||
|
|
||||||
const props = defineProps(['data']);
|
const props = defineProps(['data']);
|
||||||
const id = props.data.id;
|
const id = props.data.id;
|
||||||
const campaignId = props.data.campaign;
|
|
||||||
const handle = ref(null);
|
const handle = ref(null);
|
||||||
const wrapper = ref(null);
|
const wrapper = ref(null);
|
||||||
|
const map = props.data.map ? { ...props.data.map } : null;
|
||||||
const map = ref(props.data.map ? { ...props.data.map } : null);
|
|
||||||
const viewport = ref(null);
|
|
||||||
|
|
||||||
const zoom = ref(1);
|
|
||||||
const pan = ref({ x: 0, y: 0 });
|
|
||||||
const imageSize = ref({ width: 0, height: 0 });
|
|
||||||
const showGrid = ref(true);
|
|
||||||
const dragging = ref(false);
|
|
||||||
|
|
||||||
const minZoom = 0.05;
|
|
||||||
const maxZoom = 8;
|
|
||||||
|
|
||||||
const imageUrl = computed(() => {
|
|
||||||
const image = map.value?.image;
|
|
||||||
if (!image) return '';
|
|
||||||
return /^(https?:|data:|\/\/)/i.test(image) ? image : `${getBaseUrl()}/public/${image}`;
|
|
||||||
});
|
|
||||||
|
|
||||||
const stageStyle = computed(() => ({
|
|
||||||
transform: `translate3d(${pan.value.x}px, ${pan.value.y}px, 0) scale(${zoom.value})`
|
|
||||||
}));
|
|
||||||
|
|
||||||
// The grid is drawn in screen space over the image so its lines stay one pixel wide at any zoom.
|
|
||||||
const gridStyle = computed(() => {
|
|
||||||
if (!showGrid.value || !imageSize.value.width) return { display: 'none' };
|
|
||||||
const cell = `${Math.max(1, Number(map.value?.gridSize) || 50) * zoom.value}px`;
|
|
||||||
return {
|
|
||||||
width: `${imageSize.value.width * zoom.value}px`,
|
|
||||||
height: `${imageSize.value.height * zoom.value}px`,
|
|
||||||
transform: `translate3d(${pan.value.x + (Number(map.value?.offsetX) || 0) * zoom.value}px, ${pan.value.y + (Number(map.value?.offsetY) || 0) * zoom.value}px, 0)`,
|
|
||||||
backgroundImage: `linear-gradient(to right, var(--color-link) 1px, transparent 1px), linear-gradient(to bottom, var(--color-link) 1px, transparent 1px)`,
|
|
||||||
backgroundSize: `${cell} ${cell}`
|
|
||||||
};
|
|
||||||
});
|
|
||||||
|
|
||||||
const zoomPercent = computed(() => `${Math.round(zoom.value * 100)}%`);
|
|
||||||
|
|
||||||
function clampZoom(value) {
|
|
||||||
if (!Number.isFinite(value)) return minZoom;
|
|
||||||
return Math.min(maxZoom, Math.max(minZoom, value));
|
|
||||||
}
|
|
||||||
|
|
||||||
function fitToWindow() {
|
|
||||||
const bounds = viewport.value?.getBoundingClientRect();
|
|
||||||
if (!bounds || !imageSize.value.width) return;
|
|
||||||
zoom.value = clampZoom(Math.min(bounds.width / imageSize.value.width, bounds.height / imageSize.value.height));
|
|
||||||
centerOn();
|
|
||||||
}
|
|
||||||
|
|
||||||
function centerOn() {
|
|
||||||
const bounds = viewport.value?.getBoundingClientRect();
|
|
||||||
if (!bounds || !imageSize.value.width) return;
|
|
||||||
pan.value = {
|
|
||||||
x: (bounds.width - imageSize.value.width * zoom.value) / 2,
|
|
||||||
y: (bounds.height - imageSize.value.height * zoom.value) / 2
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
function onImageLoaded(event) {
|
|
||||||
imageSize.value = { width: event.target.naturalWidth, height: event.target.naturalHeight };
|
|
||||||
fitToWindow();
|
|
||||||
}
|
|
||||||
|
|
||||||
// Zoom keeping the map point under `point` where it is.
|
|
||||||
function zoomAt(factor, point) {
|
|
||||||
const next = clampZoom(zoom.value * factor);
|
|
||||||
if (next === zoom.value) return;
|
|
||||||
const ratio = next / zoom.value;
|
|
||||||
pan.value = {
|
|
||||||
x: point.x - (point.x - pan.value.x) * ratio,
|
|
||||||
y: point.y - (point.y - pan.value.y) * ratio
|
|
||||||
};
|
|
||||||
zoom.value = next;
|
|
||||||
}
|
|
||||||
|
|
||||||
function onWheel(event) {
|
|
||||||
const bounds = viewport.value?.getBoundingClientRect();
|
|
||||||
if (!bounds) return;
|
|
||||||
zoomAt(event.deltaY < 0 ? 1.15 : 1 / 1.15, { x: event.clientX - bounds.left, y: event.clientY - bounds.top });
|
|
||||||
}
|
|
||||||
|
|
||||||
function zoomFromToolbar(incoming) {
|
|
||||||
const bounds = viewport.value?.getBoundingClientRect();
|
|
||||||
if (!bounds) return;
|
|
||||||
zoomAt(incoming ? 1.25 : 1 / 1.25, { x: bounds.width / 2, y: bounds.height / 2 });
|
|
||||||
}
|
|
||||||
|
|
||||||
let pointerId = null;
|
|
||||||
let lastPointer = { x: 0, y: 0 };
|
|
||||||
|
|
||||||
function onPointerDown(event) {
|
|
||||||
if (event.button !== 0 || !viewport.value) return;
|
|
||||||
dragging.value = true;
|
|
||||||
pointerId = event.pointerId;
|
|
||||||
lastPointer = { x: event.clientX, y: event.clientY };
|
|
||||||
viewport.value.setPointerCapture?.(event.pointerId);
|
|
||||||
}
|
|
||||||
|
|
||||||
function onPointerMove(event) {
|
|
||||||
if (!dragging.value || event.pointerId !== pointerId) return;
|
|
||||||
pan.value = { x: pan.value.x + (event.clientX - lastPointer.x), y: pan.value.y + (event.clientY - lastPointer.y) };
|
|
||||||
lastPointer = { x: event.clientX, y: event.clientY };
|
|
||||||
}
|
|
||||||
|
|
||||||
function onPointerUp(event) {
|
|
||||||
if (event.pointerId !== pointerId) return;
|
|
||||||
dragging.value = false;
|
|
||||||
pointerId = null;
|
|
||||||
viewport.value?.releasePointerCapture?.(event.pointerId);
|
|
||||||
}
|
|
||||||
|
|
||||||
function editMap() {
|
|
||||||
if (!map.value) return;
|
|
||||||
CreateWindow('create_map', { campaign: campaignId, entry: map.value });
|
|
||||||
}
|
|
||||||
|
|
||||||
function handleMapUpdated({ entityType, entry }) {
|
|
||||||
if (entityType !== 'map' || entry?._id !== map.value?._id) return;
|
|
||||||
const imageChanged = entry.image !== map.value.image;
|
|
||||||
map.value = { ...entry };
|
|
||||||
// A new image is fitted again by onImageLoaded; grid-only changes just move the overlay.
|
|
||||||
if (imageChanged) imageSize.value = { width: 0, height: 0 };
|
|
||||||
}
|
|
||||||
|
|
||||||
onMounted(() => {
|
onMounted(() => {
|
||||||
Top(wrapper);
|
Top(wrapper);
|
||||||
@@ -143,82 +18,16 @@ onMounted(() => {
|
|||||||
height: Math.max(360, Math.min(760, window.innerHeight - 32))
|
height: Math.max(360, Math.min(760, window.innerHeight - 32))
|
||||||
});
|
});
|
||||||
ResetPosition(id, 'center');
|
ResetPosition(id, 'center');
|
||||||
emitter.on('campaign-entry-updated', handleMapUpdated);
|
|
||||||
});
|
|
||||||
|
|
||||||
onBeforeUnmount(() => {
|
|
||||||
emitter.off('campaign-entry-updated', handleMapUpdated);
|
|
||||||
});
|
});
|
||||||
</script>
|
</script>
|
||||||
|
|
||||||
<template>
|
<template>
|
||||||
<div class="window-wrapper viewer-window" :id="'window-wrapper-' + id" ref="wrapper">
|
<div class="window-wrapper viewer-window" :id="'window-wrapper-' + id" ref="wrapper">
|
||||||
<WindowHandle :window="id" ref="handle" />
|
<WindowHandle :window="id" ref="handle" />
|
||||||
<div class="viewer-bar">
|
<MapViewerPane :map="map" />
|
||||||
<div class="viewer-identity">
|
|
||||||
<strong>{{ map?.name }}</strong>
|
|
||||||
<span class="viewer-meta">{{ $t('campaigns.map.summary', { size: map?.gridSize, scale: map?.scale }) }}</span>
|
|
||||||
</div>
|
|
||||||
<div class="viewer-tools">
|
|
||||||
<button class="viewer-tool" :class="{ selected: showGrid }" type="button" :title="$t('campaigns.map.toggle-grid')"
|
|
||||||
:aria-label="$t('campaigns.map.toggle-grid')" :aria-pressed="showGrid.toString()" @click="showGrid = !showGrid">
|
|
||||||
<img class="tool-icon" src="/icons/iconoir/regular/view-grid.svg" alt="" aria-hidden="true">
|
|
||||||
</button>
|
|
||||||
<button class="viewer-tool" type="button" :title="$t('campaigns.map.zoom-out')" :aria-label="$t('campaigns.map.zoom-out')" @click="zoomFromToolbar(false)">
|
|
||||||
<img class="tool-icon" src="/icons/iconoir/regular/minus.svg" alt="" aria-hidden="true">
|
|
||||||
</button>
|
|
||||||
<span class="zoom-readout">{{ zoomPercent }}</span>
|
|
||||||
<button class="viewer-tool" type="button" :title="$t('campaigns.map.zoom-in')" :aria-label="$t('campaigns.map.zoom-in')" @click="zoomFromToolbar(true)">
|
|
||||||
<img class="tool-icon" src="/icons/iconoir/regular/plus.svg" alt="" aria-hidden="true">
|
|
||||||
</button>
|
|
||||||
<button class="viewer-tool" type="button" :title="$t('campaigns.map.fit')" :aria-label="$t('campaigns.map.fit')" @click="fitToWindow">
|
|
||||||
<img class="tool-icon" src="/icons/iconoir/regular/expand.svg" alt="" aria-hidden="true">
|
|
||||||
</button>
|
|
||||||
<button class="viewer-tool" type="button" :title="$t('campaigns.map.edit')" :aria-label="$t('campaigns.map.edit')" @click="editMap">
|
|
||||||
<img class="tool-icon" src="/icons/iconoir/regular/edit.svg" alt="" aria-hidden="true">
|
|
||||||
</button>
|
|
||||||
</div>
|
|
||||||
</div>
|
|
||||||
|
|
||||||
<div
|
|
||||||
ref="viewport"
|
|
||||||
class="map-viewport"
|
|
||||||
:class="{ dragging }"
|
|
||||||
@wheel.prevent="onWheel"
|
|
||||||
@pointerdown="onPointerDown"
|
|
||||||
@pointermove="onPointerMove"
|
|
||||||
@pointerup="onPointerUp"
|
|
||||||
@pointercancel="onPointerUp"
|
|
||||||
>
|
|
||||||
<template v-if="imageUrl">
|
|
||||||
<img class="map-image" :src="imageUrl" :style="stageStyle" :alt="map?.name" draggable="false" @load="onImageLoaded">
|
|
||||||
<div class="map-grid" :style="gridStyle" aria-hidden="true"></div>
|
|
||||||
</template>
|
|
||||||
<div v-else class="map-empty">
|
|
||||||
{{ $t('campaigns.map.no-image') }}
|
|
||||||
<button class="map-edit" type="button" @click="editMap">{{ $t('campaigns.map.upload-photo') }}</button>
|
|
||||||
</div>
|
|
||||||
</div>
|
|
||||||
</div>
|
</div>
|
||||||
</template>
|
</template>
|
||||||
|
|
||||||
<style scoped>
|
<style scoped>
|
||||||
.viewer-window { min-width: 320px; min-height: 0; }
|
.viewer-window { min-width: 320px; min-height: 0; }
|
||||||
.viewer-bar { width: 100%; box-sizing: border-box; display: flex; align-items: center; justify-content: space-between; gap: 10px; padding: 8px 10px; border-bottom: 1px solid var(--color-border); background: var(--color-background-light); }
|
|
||||||
.viewer-identity { min-width: 0; display: flex; flex-direction: column; gap: 2px; }
|
|
||||||
.viewer-identity strong { font-family: MrEavesRemake; overflow-wrap: anywhere; }
|
|
||||||
.viewer-meta { font-size: 11px; opacity: .72; }
|
|
||||||
.viewer-tools { display: flex; align-items: center; gap: 4px; }
|
|
||||||
.viewer-tool { width: 30px; height: 30px; margin: 0; padding: 0; border: 1px solid var(--color-border); border-radius: 7px; background: var(--color-background-soft); display: flex; align-items: center; justify-content: center; cursor: pointer; }
|
|
||||||
.viewer-tool:hover { background: var(--color-button-hover); }
|
|
||||||
.viewer-tool.selected { border-color: var(--color-link); background: var(--color-button-hover); }
|
|
||||||
.tool-icon { width: 16px; height: 16px; filter: invert(var(--color-icon-invert)); }
|
|
||||||
.zoom-readout { min-width: 46px; text-align: center; font-size: 12px; }
|
|
||||||
.map-viewport { position: relative; width: 100%; flex: 1; min-height: 0; overflow: hidden; background-color: var(--color-background); cursor: grab; touch-action: none; }
|
|
||||||
.map-viewport.dragging { cursor: grabbing; }
|
|
||||||
.map-image { position: absolute; top: 0; left: 0; max-width: none; transform-origin: top left; user-select: none; }
|
|
||||||
.map-grid { position: absolute; top: 0; left: 0; opacity: .55; pointer-events: none; }
|
|
||||||
.map-empty { width: 100%; height: 100%; display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 8px; font-size: 13px; opacity: .8; }
|
|
||||||
.map-edit { border: 1px solid var(--color-border); border-radius: 7px; padding: 6px 11px; background: var(--color-background-soft); color: var(--color-text); font-size: 12px; cursor: pointer; }
|
|
||||||
.map-edit:hover { background: var(--color-button-hover); }
|
|
||||||
</style>
|
</style>
|
||||||
|
|||||||
122
frontend/app/components/windows/PinnedNoteWindow.vue
Normal file
122
frontend/app/components/windows/PinnedNoteWindow.vue
Normal file
@@ -0,0 +1,122 @@
|
|||||||
|
<script setup>
|
||||||
|
import { createApp, onBeforeUnmount, onMounted, ref } from 'vue';
|
||||||
|
import { SetupHandle, SetSize, ResetPosition, ClearWindow, Top } from '@/services/Windows';
|
||||||
|
import WindowHandle from './partials/WindowHandle.vue';
|
||||||
|
import { GetWidget, ParseMarkdown } from '~/services/Marker';
|
||||||
|
import Server from '~/services/Server';
|
||||||
|
|
||||||
|
// The note a map pin points at (see MapViewerPane.vue). The note is fetched here instead of being
|
||||||
|
// carried over from the map, so a pin works whatever the note column shows and always reads fresh.
|
||||||
|
const props = defineProps(['data']);
|
||||||
|
const id = props.data.id;
|
||||||
|
const noteId = props.data.note;
|
||||||
|
const handle = ref(null);
|
||||||
|
const wrapper = ref(null);
|
||||||
|
const renderedContent = ref(null);
|
||||||
|
const note = ref(null);
|
||||||
|
const displayText = ref('');
|
||||||
|
const loading = ref(true);
|
||||||
|
const failed = ref(false);
|
||||||
|
|
||||||
|
// Widgets mounted over this note, kept to unmount them again the way Note.vue does: re-rendering
|
||||||
|
// would otherwise leave the apps of the nodes it replaced behind.
|
||||||
|
const mountedApps = [];
|
||||||
|
|
||||||
|
function unmountWidgets() {
|
||||||
|
for (const app of mountedApps) {
|
||||||
|
try {
|
||||||
|
app.unmount();
|
||||||
|
} catch (error) {
|
||||||
|
// The container may already be off the DOM; ignore and drop it all the same.
|
||||||
|
}
|
||||||
|
}
|
||||||
|
mountedApps.length = 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
function mountWidgets() {
|
||||||
|
const root = renderedContent.value;
|
||||||
|
if (!root) return;
|
||||||
|
|
||||||
|
['display', 'inline'].forEach((widgetType) => {
|
||||||
|
root.querySelectorAll('.vue-component-' + widgetType).forEach((el) => {
|
||||||
|
const widget = GetWidget(widgetType, el.dataset.component);
|
||||||
|
if (!widget) return;
|
||||||
|
try {
|
||||||
|
const app = createApp(widget, { content: el.dataset.content });
|
||||||
|
app.config.errorHandler = (error) => console.error('Widget error', el.dataset.component, error);
|
||||||
|
app.mount(el);
|
||||||
|
mountedApps.push(app);
|
||||||
|
} catch (error) {
|
||||||
|
console.error('Failed to mount widget', el.dataset.component, error);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
async function fetchNote() {
|
||||||
|
loading.value = true;
|
||||||
|
failed.value = false;
|
||||||
|
try {
|
||||||
|
const response = await Server().get(`/note/retrieve/${noteId}`);
|
||||||
|
if (response.data.status !== 'ok' || !response.data.note) {
|
||||||
|
failed.value = true;
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
note.value = response.data.note;
|
||||||
|
unmountWidgets();
|
||||||
|
displayText.value = ParseMarkdown(response.data.note.content ?? '');
|
||||||
|
setTimeout(() => mountWidgets(), 0);
|
||||||
|
} catch (error) {
|
||||||
|
failed.value = true;
|
||||||
|
} finally {
|
||||||
|
loading.value = false;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
onMounted(() => {
|
||||||
|
Top(wrapper);
|
||||||
|
SetupHandle(id, handle);
|
||||||
|
SetSize(id, {
|
||||||
|
width: Math.max(360, Math.min(720, window.innerWidth - 24)),
|
||||||
|
height: Math.max(360, Math.min(720, window.innerHeight - 32))
|
||||||
|
});
|
||||||
|
ResetPosition(id, 'center');
|
||||||
|
fetchNote();
|
||||||
|
});
|
||||||
|
|
||||||
|
onBeforeUnmount(() => {
|
||||||
|
unmountWidgets();
|
||||||
|
ClearWindow({ type: 'pinned_note' });
|
||||||
|
});
|
||||||
|
</script>
|
||||||
|
|
||||||
|
<template>
|
||||||
|
<div class="window-wrapper pinned-note-window" :id="'window-wrapper-' + id" ref="wrapper">
|
||||||
|
<WindowHandle :window="id" ref="handle" />
|
||||||
|
<div class="body">
|
||||||
|
<div v-if="loading" class="note-state">{{ $t('campaigns.states.loading') }}</div>
|
||||||
|
<div v-else-if="failed" class="note-state">{{ $t('campaigns.map.pins.note-error') }}</div>
|
||||||
|
<template v-else>
|
||||||
|
<h1 v-if="note.title" class="note-title">{{ note.title }}</h1>
|
||||||
|
<div ref="renderedContent" class="note-content" v-html="displayText"></div>
|
||||||
|
</template>
|
||||||
|
</div>
|
||||||
|
</div>
|
||||||
|
</template>
|
||||||
|
|
||||||
|
<style scoped>
|
||||||
|
.window-wrapper { display: flex; align-items: center; flex-direction: column; }
|
||||||
|
/* Stretch so the outer margin insets the content instead of overflowing the window. */
|
||||||
|
.body {
|
||||||
|
flex: 1;
|
||||||
|
min-height: 0;
|
||||||
|
align-self: stretch;
|
||||||
|
box-sizing: border-box;
|
||||||
|
margin: 10px;
|
||||||
|
padding: 8px;
|
||||||
|
overflow-y: auto;
|
||||||
|
}
|
||||||
|
.note-title { margin: 0 0 10px; font-family: MrEavesRemake; overflow-wrap: anywhere; }
|
||||||
|
.note-state { padding: 10px; font-size: 13px; opacity: .8; }
|
||||||
|
.note-content :deep(img) { max-width: 100%; height: auto; display: block; }
|
||||||
|
</style>
|
||||||
@@ -2,11 +2,38 @@ import { ref } from 'vue';
|
|||||||
|
|
||||||
const ShowContent = ref(false);
|
const ShowContent = ref(false);
|
||||||
|
|
||||||
|
// What the campaign workspace shows where the notes live: the open notes, or the map the
|
||||||
|
// sidebar anchored on the note container. 'notes' | 'map'
|
||||||
|
const ActivePane = ref('notes');
|
||||||
|
|
||||||
|
// The map anchored on the note container (a campaign entry of the sidebar's maps section).
|
||||||
|
const AnchoredMap = ref(null);
|
||||||
|
|
||||||
function SetShowContent(value) {
|
function SetShowContent(value) {
|
||||||
ShowContent.value = value;
|
ShowContent.value = value;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
function SetActivePane(value) {
|
||||||
|
ActivePane.value = value;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Anchoring shows the map where the open notes are; they stay open and come back on 'notes'.
|
||||||
|
function AnchorMap(map) {
|
||||||
|
AnchoredMap.value = map ?? null;
|
||||||
|
ActivePane.value = AnchoredMap.value ? 'map' : 'notes';
|
||||||
|
}
|
||||||
|
|
||||||
|
function ClearAnchoredMap() {
|
||||||
|
AnchoredMap.value = null;
|
||||||
|
if (ActivePane.value === 'map') ActivePane.value = 'notes';
|
||||||
|
}
|
||||||
|
|
||||||
export {
|
export {
|
||||||
ShowContent,
|
ShowContent,
|
||||||
SetShowContent
|
SetShowContent,
|
||||||
|
ActivePane,
|
||||||
|
AnchoredMap,
|
||||||
|
SetActivePane,
|
||||||
|
AnchorMap,
|
||||||
|
ClearAnchoredMap
|
||||||
}
|
}
|
||||||
77
frontend/app/services/MapPins.js
Normal file
77
frontend/app/services/MapPins.js
Normal file
@@ -0,0 +1,77 @@
|
|||||||
|
// The rules behind the note pins of a map (right click a map, pin one of the campaign notes at that
|
||||||
|
// spot, click the pin to read it). Pins are stored in image pixels, so these helpers only translate
|
||||||
|
// between the image and what the map viewer shows; they hold no state and talk to no API.
|
||||||
|
|
||||||
|
const PATH_SEPARATOR = ' / ';
|
||||||
|
|
||||||
|
// Screen pixels (relative to the top left corner of the map viewport) → image pixels, or null when
|
||||||
|
// the point is not over the image: nothing gets pinned outside of it.
|
||||||
|
function ToImagePoint(point, view) {
|
||||||
|
const zoom = Number(view?.zoom);
|
||||||
|
const width = Number(view?.width);
|
||||||
|
const height = Number(view?.height);
|
||||||
|
if (!zoom || !width || !height) return null;
|
||||||
|
|
||||||
|
const x = (Number(point?.x) - Number(view?.pan?.x ?? 0)) / zoom;
|
||||||
|
const y = (Number(point?.y) - Number(view?.pan?.y ?? 0)) / zoom;
|
||||||
|
if (!Number.isFinite(x) || !Number.isFinite(y)) return null;
|
||||||
|
if (x < 0 || y < 0 || x > width || y > height) return null;
|
||||||
|
|
||||||
|
return { x: Math.round(x), y: Math.round(y) };
|
||||||
|
}
|
||||||
|
|
||||||
|
// A pin (image pixels) → screen pixels of the map viewport. Pins are drawn in screen space instead
|
||||||
|
// of inside the scaled stage, so their marker keeps the same size whatever the zoom is.
|
||||||
|
function ToScreenPoint(pin, view) {
|
||||||
|
const zoom = Number(view?.zoom) || 0;
|
||||||
|
return {
|
||||||
|
x: Number(view?.pan?.x ?? 0) + Number(pin?.x ?? 0) * zoom,
|
||||||
|
y: Number(view?.pan?.y ?? 0) + Number(pin?.y ?? 0) * zoom
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
// The path of the folder a note lives in, so two notes sharing a name can still be told apart.
|
||||||
|
function FolderPath(folderId, folderById) {
|
||||||
|
const names = [];
|
||||||
|
const seen = new Set();
|
||||||
|
let folder = folderId ? folderById.get(String(folderId)) : null;
|
||||||
|
// Folder trees are acyclic by construction; `seen` only keeps a broken parent chain from
|
||||||
|
// looping forever.
|
||||||
|
while (folder && !seen.has(String(folder._id))) {
|
||||||
|
seen.add(String(folder._id));
|
||||||
|
if (folder.name) names.unshift(String(folder.name));
|
||||||
|
folder = folder.parentFolder ? folderById.get(String(folder.parentFolder)) : null;
|
||||||
|
}
|
||||||
|
return names.join(PATH_SEPARATOR);
|
||||||
|
}
|
||||||
|
|
||||||
|
// 'Folder / Subfolder / Note title' out of the picker option's folder path and title.
|
||||||
|
function OptionLabel(option) {
|
||||||
|
const path = option?.path ? `${option.path}${PATH_SEPARATOR}` : '';
|
||||||
|
return `${path}${option?.title ?? ''}`;
|
||||||
|
}
|
||||||
|
|
||||||
|
// The note picker of a campaign: `{ value, title, path, label }` per note, sorted by label. Notes
|
||||||
|
// without a title are left out, they would show as an empty menu entry.
|
||||||
|
function BuildNoteOptions(notes, folders) {
|
||||||
|
const folderById = new Map((folders ?? []).map((folder) => [String(folder._id), folder]));
|
||||||
|
|
||||||
|
return (notes ?? [])
|
||||||
|
.filter((note) => note?._id && String(note.title ?? '').trim())
|
||||||
|
.map((note) => {
|
||||||
|
const option = {
|
||||||
|
value: String(note._id),
|
||||||
|
title: String(note.title).trim(),
|
||||||
|
path: FolderPath(note.folder, folderById)
|
||||||
|
};
|
||||||
|
return { ...option, label: OptionLabel(option) };
|
||||||
|
})
|
||||||
|
.sort((a, b) => a.label.localeCompare(b.label));
|
||||||
|
}
|
||||||
|
|
||||||
|
export {
|
||||||
|
BuildNoteOptions,
|
||||||
|
OptionLabel,
|
||||||
|
ToImagePoint,
|
||||||
|
ToScreenPoint
|
||||||
|
};
|
||||||
@@ -82,6 +82,12 @@ const defWindows = {
|
|||||||
component: () => import('~/components/windows/MapViewerWindow.vue'),
|
component: () => import('~/components/windows/MapViewerWindow.vue'),
|
||||||
close: () => ClearWindow({type: 'map_viewer'}),
|
close: () => ClearWindow({type: 'map_viewer'}),
|
||||||
movable: true
|
movable: true
|
||||||
|
},
|
||||||
|
pinned_note: {
|
||||||
|
title: 'windows.pinned-note',
|
||||||
|
component: () => import('~/components/windows/PinnedNoteWindow.vue'),
|
||||||
|
close: () => ClearWindow({type: 'pinned_note'}),
|
||||||
|
movable: true
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
@@ -17,6 +17,7 @@
|
|||||||
"saved": "S'ha desat la configuració de la campanya.",
|
"saved": "S'ha desat la configuració de la campanya.",
|
||||||
"linked": "S'ha enllaçat el món de Foundry amb aquesta campanya.",
|
"linked": "S'ha enllaçat el món de Foundry amb aquesta campanya.",
|
||||||
"unlinked": "S'ha desenllaçat el món de Foundry d'aquesta campanya.",
|
"unlinked": "S'ha desenllaçat el món de Foundry d'aquesta campanya.",
|
||||||
|
"copy-code": "Copia el codi",
|
||||||
"code-copied": "S'ha copiat el codi d'enllaç.",
|
"code-copied": "S'ha copiat el codi d'enllaç.",
|
||||||
"saving": "Desant...",
|
"saving": "Desant...",
|
||||||
"errors": {
|
"errors": {
|
||||||
@@ -67,7 +68,14 @@
|
|||||||
"summary": "Quadrícula de {size} px · {scale} per cel·la",
|
"summary": "Quadrícula de {size} px · {scale} per cel·la",
|
||||||
"save-error": "No s'ha pogut desar aquest mapa.",
|
"save-error": "No s'ha pogut desar aquest mapa.",
|
||||||
"no-image": "Aquest mapa encara no té imatge.",
|
"no-image": "Aquest mapa encara no té imatge.",
|
||||||
"zoom-in": "Apropar", "zoom-out": "Allunyar", "fit": "Ajustar a la finestra", "toggle-grid": "Mostrar la quadrícula"
|
"zoom-in": "Apropar", "zoom-out": "Allunyar", "fit": "Ajustar a la finestra", "toggle-grid": "Mostrar la quadrícula",
|
||||||
|
"open-window": "Obre en una finestra", "anchored": "Ancorat",
|
||||||
|
"pins": {
|
||||||
|
"add": "Fixa una nota aquí", "none": "Encara no hi ha notes per fixar",
|
||||||
|
"open": "Obre la nota", "remove": "Treu el marcador",
|
||||||
|
"error": "No s'han pogut canviar els marcadors d'aquest mapa.",
|
||||||
|
"note-error": "No s'ha pogut llegir aquesta nota. Potser s'ha suprimit."
|
||||||
|
}
|
||||||
},
|
},
|
||||||
"character-sheet": {
|
"character-sheet": {
|
||||||
"title": "Fitxa de personatge", "name": "Nom del personatge", "class": "Classe", "subclass": "Subclasse", "unset-class": "Classe sense definir",
|
"title": "Fitxa de personatge", "name": "Nom del personatge", "class": "Classe", "subclass": "Subclasse", "unset-class": "Classe sense definir",
|
||||||
|
|||||||
@@ -7,5 +7,6 @@
|
|||||||
"settings": "Configuració",
|
"settings": "Configuració",
|
||||||
"create-campaign": "Crear campanya",
|
"create-campaign": "Crear campanya",
|
||||||
"create-map": "Crear mapa",
|
"create-map": "Crear mapa",
|
||||||
"map-viewer": "Mapa"
|
"map-viewer": "Mapa",
|
||||||
|
"pinned-note": "Nota fixada"
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -21,6 +21,7 @@
|
|||||||
"saved": "Campaign settings saved.",
|
"saved": "Campaign settings saved.",
|
||||||
"linked": "Foundry world linked to this campaign.",
|
"linked": "Foundry world linked to this campaign.",
|
||||||
"unlinked": "Foundry world unlinked from this campaign.",
|
"unlinked": "Foundry world unlinked from this campaign.",
|
||||||
|
"copy-code": "Copy code",
|
||||||
"code-copied": "Pairing code copied.",
|
"code-copied": "Pairing code copied.",
|
||||||
"saving": "Saving...",
|
"saving": "Saving...",
|
||||||
"errors": {
|
"errors": {
|
||||||
@@ -71,7 +72,14 @@
|
|||||||
"summary": "{size} px grid · {scale} per cell",
|
"summary": "{size} px grid · {scale} per cell",
|
||||||
"save-error": "Unable to save this map.",
|
"save-error": "Unable to save this map.",
|
||||||
"no-image": "This map has no image yet.",
|
"no-image": "This map has no image yet.",
|
||||||
"zoom-in": "Zoom in", "zoom-out": "Zoom out", "fit": "Fit to window", "toggle-grid": "Show grid"
|
"zoom-in": "Zoom in", "zoom-out": "Zoom out", "fit": "Fit to window", "toggle-grid": "Show grid",
|
||||||
|
"open-window": "Open in window", "anchored": "Anchored",
|
||||||
|
"pins": {
|
||||||
|
"add": "Pin a note here", "none": "No notes to pin yet",
|
||||||
|
"open": "Open note", "remove": "Remove pin",
|
||||||
|
"error": "Unable to change the pins of this map.",
|
||||||
|
"note-error": "This note could not be read. It may have been deleted."
|
||||||
|
}
|
||||||
},
|
},
|
||||||
"character-sheet": {
|
"character-sheet": {
|
||||||
"title": "Character Sheet", "name": "Character name", "class": "Class", "subclass": "Subclass", "unset-class": "Class not set",
|
"title": "Character Sheet", "name": "Character name", "class": "Class", "subclass": "Subclass", "unset-class": "Class not set",
|
||||||
|
|||||||
@@ -7,5 +7,6 @@
|
|||||||
"settings": "Settings",
|
"settings": "Settings",
|
||||||
"create-campaign": "Create Campaign",
|
"create-campaign": "Create Campaign",
|
||||||
"create-map": "Create Map",
|
"create-map": "Create Map",
|
||||||
"map-viewer": "Map"
|
"map-viewer": "Map",
|
||||||
|
"pinned-note": "Pinned note"
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -17,6 +17,7 @@
|
|||||||
"saved": "Se han guardado los ajustes de la campaña.",
|
"saved": "Se han guardado los ajustes de la campaña.",
|
||||||
"linked": "El mundo de Foundry se ha vinculado a esta campaña.",
|
"linked": "El mundo de Foundry se ha vinculado a esta campaña.",
|
||||||
"unlinked": "Se ha desvinculado el mundo de Foundry de esta campaña.",
|
"unlinked": "Se ha desvinculado el mundo de Foundry de esta campaña.",
|
||||||
|
"copy-code": "Copiar código",
|
||||||
"code-copied": "Código de vinculación copiado.",
|
"code-copied": "Código de vinculación copiado.",
|
||||||
"saving": "Guardando...",
|
"saving": "Guardando...",
|
||||||
"errors": {
|
"errors": {
|
||||||
@@ -67,7 +68,14 @@
|
|||||||
"summary": "Cuadrícula de {size} px · {scale} por celda",
|
"summary": "Cuadrícula de {size} px · {scale} por celda",
|
||||||
"save-error": "No se pudo guardar este mapa.",
|
"save-error": "No se pudo guardar este mapa.",
|
||||||
"no-image": "Este mapa aún no tiene imagen.",
|
"no-image": "Este mapa aún no tiene imagen.",
|
||||||
"zoom-in": "Acercar", "zoom-out": "Alejar", "fit": "Ajustar a la ventana", "toggle-grid": "Mostrar cuadrícula"
|
"zoom-in": "Acercar", "zoom-out": "Alejar", "fit": "Ajustar a la ventana", "toggle-grid": "Mostrar cuadrícula",
|
||||||
|
"open-window": "Abrir en una ventana", "anchored": "Anclado",
|
||||||
|
"pins": {
|
||||||
|
"add": "Fija una nota aquí", "none": "Aún no hay notas que fijar",
|
||||||
|
"open": "Abrir nota", "remove": "Quitar el marcador",
|
||||||
|
"error": "No se pudieron cambiar los marcadores de este mapa.",
|
||||||
|
"note-error": "No se pudo leer esta nota. Puede que se haya eliminado."
|
||||||
|
}
|
||||||
},
|
},
|
||||||
"character-sheet": {
|
"character-sheet": {
|
||||||
"title": "Hoja de personaje", "name": "Nombre del personaje", "class": "Clase", "subclass": "Subclase", "unset-class": "Clase sin definir",
|
"title": "Hoja de personaje", "name": "Nombre del personaje", "class": "Clase", "subclass": "Subclase", "unset-class": "Clase sin definir",
|
||||||
|
|||||||
@@ -7,5 +7,6 @@
|
|||||||
"settings": "Configuración",
|
"settings": "Configuración",
|
||||||
"create-campaign": "Crear campanya",
|
"create-campaign": "Crear campanya",
|
||||||
"create-map": "Crear mapa",
|
"create-map": "Crear mapa",
|
||||||
"map-viewer": "Mapa"
|
"map-viewer": "Mapa",
|
||||||
|
"pinned-note": "Nota fijada"
|
||||||
}
|
}
|
||||||
|
|||||||
43
obsidian-plugin/README.md
Normal file
43
obsidian-plugin/README.md
Normal file
@@ -0,0 +1,43 @@
|
|||||||
|
# Dragonroll Sync for Obsidian
|
||||||
|
|
||||||
|
An Obsidian community plugin that imports notes from a Dragonroll campaign and pushes the active
|
||||||
|
Markdown note back to Dragonroll.
|
||||||
|
|
||||||
|
## Install from this repository
|
||||||
|
|
||||||
|
Copy `main.js` and `manifest.json` into:
|
||||||
|
|
||||||
|
```text
|
||||||
|
<vault>/.obsidian/plugins/dragonroll-sync/
|
||||||
|
```
|
||||||
|
|
||||||
|
Then enable **Dragonroll Sync** in Obsidian's Community Plugins settings. The plugin is plain
|
||||||
|
JavaScript and does not need a build step.
|
||||||
|
|
||||||
|
## Connect your account
|
||||||
|
|
||||||
|
Open **Settings → Community plugins → Dragonroll Sync**, enter the Dragonroll API URL and sign in
|
||||||
|
with your Dragonroll username/email and password. The default API URL is
|
||||||
|
`https://dragonroll.aranroig.com/api`; a local server can use `http://localhost:5000/api`.
|
||||||
|
Choose a campaign after signing in. The plugin saves the Dragonroll session token in this vault;
|
||||||
|
Dragonroll sessions expire after 48 hours. The password is not saved.
|
||||||
|
|
||||||
|
## Commands
|
||||||
|
|
||||||
|
- **Import or refresh campaign notes** fetches all campaign notes, including notes inside nested
|
||||||
|
Dragonroll folders, into `Dragonroll/<Campaign>/`. Imported notes keep their folder hierarchy.
|
||||||
|
- **Push active note to Dragonroll** creates the active Markdown note as a root campaign note, or
|
||||||
|
updates its linked Dragonroll note. A note linked to a different campaign cannot be pushed while
|
||||||
|
another campaign is selected.
|
||||||
|
|
||||||
|
The import command adds `dragonrollId`, `dragonrollCampaign`, and `dragonrollTitle` properties to
|
||||||
|
each imported note's frontmatter. These properties link the local file to its remote record and are
|
||||||
|
omitted from the Markdown content sent back to Dragonroll. Pushing a new local note adds those
|
||||||
|
properties as well.
|
||||||
|
|
||||||
|
Import protects local edits. It updates a linked note only when the local copy still matches the
|
||||||
|
last imported/pushed version. If the local copy changed, or both copies changed since the last sync,
|
||||||
|
the plugin keeps the local file and reports it for review. Push is explicit and updates Dragonroll
|
||||||
|
with the active note's current title and content.
|
||||||
|
|
||||||
|
This is an explicit import/push workflow; it does not sync in the background or delete notes.
|
||||||
497
obsidian-plugin/main.js
Normal file
497
obsidian-plugin/main.js
Normal file
@@ -0,0 +1,497 @@
|
|||||||
|
const {
|
||||||
|
Notice,
|
||||||
|
Plugin,
|
||||||
|
PluginSettingTab,
|
||||||
|
Setting,
|
||||||
|
normalizePath,
|
||||||
|
requestUrl,
|
||||||
|
} = require('obsidian');
|
||||||
|
|
||||||
|
const DEFAULT_SETTINGS = {
|
||||||
|
apiBaseUrl: 'https://dragonroll.aranroig.com/api',
|
||||||
|
token: '',
|
||||||
|
campaignId: '',
|
||||||
|
snapshots: {},
|
||||||
|
};
|
||||||
|
|
||||||
|
const NOTE_ID_PROPERTY = 'dragonrollId';
|
||||||
|
const CAMPAIGN_PROPERTY = 'dragonrollCampaign';
|
||||||
|
const REMOTE_TITLE_PROPERTY = 'dragonrollTitle';
|
||||||
|
|
||||||
|
module.exports = class DragonrollSyncPlugin extends Plugin {
|
||||||
|
async onload() {
|
||||||
|
await this.loadSettings();
|
||||||
|
|
||||||
|
this.status = this.addStatusBarItem();
|
||||||
|
this.updateStatus();
|
||||||
|
this.addRibbonIcon('refresh-cw', 'Import Dragonroll campaign notes', () => this.importCampaignNotes());
|
||||||
|
this.addCommand({
|
||||||
|
id: 'import-campaign-notes',
|
||||||
|
name: 'Import or refresh campaign notes',
|
||||||
|
callback: () => this.importCampaignNotes(),
|
||||||
|
});
|
||||||
|
this.addCommand({
|
||||||
|
id: 'push-active-note',
|
||||||
|
name: 'Push active note to Dragonroll',
|
||||||
|
checkCallback: (checking) => {
|
||||||
|
const file = this.app.workspace.getActiveFile();
|
||||||
|
if (!file || file.extension !== 'md') return false;
|
||||||
|
if (!checking) void this.pushActiveNote();
|
||||||
|
return true;
|
||||||
|
},
|
||||||
|
});
|
||||||
|
this.addSettingTab(new DragonrollSettingTab(this.app, this));
|
||||||
|
|
||||||
|
if (this.settings.token && this.settings.campaignId) {
|
||||||
|
this.status.setText('Dragonroll: ready');
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
async loadSettings() {
|
||||||
|
this.settings = Object.assign({}, DEFAULT_SETTINGS, await this.loadData());
|
||||||
|
if (!this.settings.snapshots || typeof this.settings.snapshots !== 'object') {
|
||||||
|
this.settings.snapshots = {};
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
async saveSettings() {
|
||||||
|
await this.saveData(this.settings);
|
||||||
|
this.updateStatus();
|
||||||
|
}
|
||||||
|
|
||||||
|
updateStatus() {
|
||||||
|
if (!this.status) return;
|
||||||
|
if (!this.settings.token) this.status.setText('Dragonroll: signed out');
|
||||||
|
else if (!this.settings.campaignId) this.status.setText('Dragonroll: choose campaign');
|
||||||
|
else this.status.setText('Dragonroll: ready');
|
||||||
|
}
|
||||||
|
|
||||||
|
apiBaseUrl() {
|
||||||
|
let url = String(this.settings.apiBaseUrl || '').trim().replace(/\/+$/, '');
|
||||||
|
if (!url) throw new Error('Enter the Dragonroll API URL in settings.');
|
||||||
|
if (!/\/api$/i.test(url)) url += '/api';
|
||||||
|
return url;
|
||||||
|
}
|
||||||
|
|
||||||
|
async request(path, { method = 'GET', body, authenticated = true } = {}) {
|
||||||
|
const headers = { Accept: 'application/json' };
|
||||||
|
if (authenticated && this.settings.token) {
|
||||||
|
headers.Authorization = `Bearer ${this.settings.token}`;
|
||||||
|
}
|
||||||
|
if (body !== undefined) headers['Content-Type'] = 'application/json';
|
||||||
|
|
||||||
|
let response;
|
||||||
|
try {
|
||||||
|
response = await requestUrl({
|
||||||
|
url: `${this.apiBaseUrl()}${path}`,
|
||||||
|
method,
|
||||||
|
headers,
|
||||||
|
body: body === undefined ? undefined : JSON.stringify(body),
|
||||||
|
throw: false,
|
||||||
|
});
|
||||||
|
} catch (error) {
|
||||||
|
throw new Error(`Could not reach Dragonroll: ${error.message || error}`);
|
||||||
|
}
|
||||||
|
|
||||||
|
let data;
|
||||||
|
try {
|
||||||
|
data = response.json;
|
||||||
|
} catch {
|
||||||
|
throw new Error(`Dragonroll returned an unreadable response (HTTP ${response.status}).`);
|
||||||
|
}
|
||||||
|
if (response.status < 200 || response.status >= 300 || data?.status !== 'ok') {
|
||||||
|
const message = data?.msg || `HTTP ${response.status}`;
|
||||||
|
if (response.status === 401 || message === 'unauthorized') {
|
||||||
|
throw new Error('Dragonroll rejected this session. Sign in again in plugin settings.');
|
||||||
|
}
|
||||||
|
throw new Error(`Dragonroll: ${message}`);
|
||||||
|
}
|
||||||
|
return data;
|
||||||
|
}
|
||||||
|
|
||||||
|
async login(usermail, password) {
|
||||||
|
const data = await this.request('/user/login', {
|
||||||
|
method: 'POST',
|
||||||
|
body: { usermail, password },
|
||||||
|
authenticated: false,
|
||||||
|
});
|
||||||
|
this.settings.token = data.token;
|
||||||
|
this.settings.campaignId = '';
|
||||||
|
await this.saveSettings();
|
||||||
|
return this.getCampaigns();
|
||||||
|
}
|
||||||
|
|
||||||
|
async getCampaigns() {
|
||||||
|
const data = await this.request('/campaign/list');
|
||||||
|
return data.campaigns || [];
|
||||||
|
}
|
||||||
|
|
||||||
|
async selectedCampaign() {
|
||||||
|
if (!this.settings.token) throw new Error('Sign in to Dragonroll in plugin settings first.');
|
||||||
|
if (!this.settings.campaignId) throw new Error('Choose a campaign in plugin settings first.');
|
||||||
|
const campaigns = await this.getCampaigns();
|
||||||
|
const campaign = campaigns.find((item) => String(item._id) === String(this.settings.campaignId));
|
||||||
|
if (!campaign) throw new Error('The selected campaign is unavailable. Choose a campaign in settings.');
|
||||||
|
return campaign;
|
||||||
|
}
|
||||||
|
|
||||||
|
async fetchCampaignNotes(campaignId) {
|
||||||
|
const root = await this.request(`/note/list?campaign=${encodeURIComponent(campaignId)}`);
|
||||||
|
const folders = root.folders || [];
|
||||||
|
const folderById = new Map(folders.map((folder) => [String(folder._id), folder]));
|
||||||
|
const pathCache = new Map();
|
||||||
|
|
||||||
|
const folderPath = (folderId, visiting = new Set()) => {
|
||||||
|
const id = String(folderId || '');
|
||||||
|
if (!id || !folderById.has(id)) return [];
|
||||||
|
if (pathCache.has(id)) return pathCache.get(id);
|
||||||
|
if (visiting.has(id)) return [];
|
||||||
|
const folder = folderById.get(id);
|
||||||
|
const nextVisiting = new Set(visiting);
|
||||||
|
nextVisiting.add(id);
|
||||||
|
const parent = folder.parentFolder ? String(folder.parentFolder) : '';
|
||||||
|
const path = [...folderPath(parent, nextVisiting), safeSegment(folder.name, 'Folder')];
|
||||||
|
pathCache.set(id, path);
|
||||||
|
return path;
|
||||||
|
};
|
||||||
|
|
||||||
|
const nestedResults = await Promise.all(folders.map(async (folder) => {
|
||||||
|
const data = await this.request(
|
||||||
|
`/note/subfolder/list?campaign=${encodeURIComponent(campaignId)}&folder=${encodeURIComponent(folder._id)}`
|
||||||
|
);
|
||||||
|
return (data.notes || []).map((note) => ({ note, folders: folderPath(folder._id) }));
|
||||||
|
}));
|
||||||
|
|
||||||
|
const notes = (root.notes || []).map((note) => ({ note, folders: [] }));
|
||||||
|
for (const result of nestedResults) notes.push(...result);
|
||||||
|
return notes;
|
||||||
|
}
|
||||||
|
|
||||||
|
async importCampaignNotes() {
|
||||||
|
try {
|
||||||
|
const campaign = await this.selectedCampaign();
|
||||||
|
const notes = await this.fetchCampaignNotes(campaign._id);
|
||||||
|
const existingById = await this.findFilesByDragonrollId();
|
||||||
|
const baseFolder = normalizePath(`Dragonroll/${safeSegment(campaign.name, 'Campaign')}`);
|
||||||
|
let created = 0;
|
||||||
|
let updated = 0;
|
||||||
|
let unchanged = 0;
|
||||||
|
let protectedNotes = 0;
|
||||||
|
|
||||||
|
for (const entry of notes) {
|
||||||
|
const remote = entry.note;
|
||||||
|
const id = String(remote._id);
|
||||||
|
const title = String(remote.title || 'Untitled');
|
||||||
|
const content = String(remote.content || '');
|
||||||
|
const remoteSignature = await signature(title, content);
|
||||||
|
const file = existingById.get(id);
|
||||||
|
|
||||||
|
if (!file) {
|
||||||
|
const targetFolder = normalizePath([baseFolder, ...entry.folders].join('/'));
|
||||||
|
await this.ensureFolder(targetFolder);
|
||||||
|
const path = await this.availableMarkdownPath(targetFolder, title, id);
|
||||||
|
const newFile = await this.app.vault.create(path, content);
|
||||||
|
await this.setNoteIdentity(newFile, id, campaign._id, title);
|
||||||
|
this.settings.snapshots[id] = remoteSignature;
|
||||||
|
created += 1;
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
|
||||||
|
const localContent = await this.app.vault.read(file);
|
||||||
|
const frontmatter = this.app.metadataCache.getFileCache(file)?.frontmatter || {};
|
||||||
|
const storedTitle = frontmatter[REMOTE_TITLE_PROPERTY];
|
||||||
|
const localTitle = storedTitle && safeSegment(storedTitle, 'Untitled') === file.basename
|
||||||
|
? String(storedTitle)
|
||||||
|
: file.basename;
|
||||||
|
const localSignature = await signature(localTitle, stripPluginMetadata(localContent));
|
||||||
|
const baseline = this.settings.snapshots[id];
|
||||||
|
|
||||||
|
if (!baseline) {
|
||||||
|
if (localSignature === remoteSignature) {
|
||||||
|
this.settings.snapshots[id] = remoteSignature;
|
||||||
|
unchanged += 1;
|
||||||
|
} else {
|
||||||
|
protectedNotes += 1;
|
||||||
|
}
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
|
||||||
|
const localChanged = localSignature !== baseline;
|
||||||
|
const remoteChanged = remoteSignature !== baseline;
|
||||||
|
if (localChanged && remoteChanged) {
|
||||||
|
protectedNotes += 1;
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
if (localChanged) {
|
||||||
|
protectedNotes += 1;
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
if (!remoteChanged) {
|
||||||
|
unchanged += 1;
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
|
||||||
|
await this.app.vault.modify(file, content);
|
||||||
|
await this.setNoteIdentity(file, id, campaign._id, title);
|
||||||
|
const renamed = await this.renameImportedFile(file, title, id);
|
||||||
|
this.settings.snapshots[id] = remoteSignature;
|
||||||
|
updated += 1;
|
||||||
|
if (renamed) existingById.set(id, renamed);
|
||||||
|
}
|
||||||
|
|
||||||
|
await this.saveSettings();
|
||||||
|
const details = protectedNotes ? `; ${protectedNotes} local edit(s) kept for review` : '';
|
||||||
|
new Notice(`Dragonroll import: ${created} added, ${updated} updated, ${unchanged} unchanged${details}.`);
|
||||||
|
} catch (error) {
|
||||||
|
new Notice(error.message || 'Could not import Dragonroll notes.');
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
async pushActiveNote() {
|
||||||
|
try {
|
||||||
|
const campaign = await this.selectedCampaign();
|
||||||
|
const file = this.app.workspace.getActiveFile();
|
||||||
|
if (!file || file.extension !== 'md') throw new Error('Open a Markdown note to push it.');
|
||||||
|
|
||||||
|
const cache = this.app.metadataCache.getFileCache(file);
|
||||||
|
const frontmatter = cache?.frontmatter || {};
|
||||||
|
const linkedCampaign = frontmatter[CAMPAIGN_PROPERTY];
|
||||||
|
const noteId = frontmatter[NOTE_ID_PROPERTY];
|
||||||
|
if (noteId && String(linkedCampaign || '') !== String(campaign._id)) {
|
||||||
|
throw new Error('This note is linked to another Dragonroll campaign. Select that campaign to push it.');
|
||||||
|
}
|
||||||
|
|
||||||
|
const markdown = stripPluginMetadata(await this.app.vault.read(file));
|
||||||
|
let remote;
|
||||||
|
if (noteId) {
|
||||||
|
const data = await this.request('/note/update', {
|
||||||
|
method: 'POST',
|
||||||
|
body: { id: String(noteId), title: file.basename, content: markdown },
|
||||||
|
});
|
||||||
|
remote = data.note;
|
||||||
|
} else {
|
||||||
|
const data = await this.request('/note/create', {
|
||||||
|
method: 'POST',
|
||||||
|
body: { title: file.basename, content: markdown, campaign: campaign._id },
|
||||||
|
});
|
||||||
|
remote = data.note;
|
||||||
|
}
|
||||||
|
|
||||||
|
const id = String(remote._id || noteId);
|
||||||
|
await this.setNoteIdentity(file, id, campaign._id, file.basename);
|
||||||
|
this.settings.snapshots[id] = await signature(file.basename, markdown);
|
||||||
|
await this.saveSettings();
|
||||||
|
new Notice(`Pushed “${file.basename}” to Dragonroll.`);
|
||||||
|
} catch (error) {
|
||||||
|
new Notice(error.message || 'Could not push this note to Dragonroll.');
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
async findFilesByDragonrollId() {
|
||||||
|
const result = new Map();
|
||||||
|
for (const file of this.app.vault.getMarkdownFiles()) {
|
||||||
|
const frontmatter = this.app.metadataCache.getFileCache(file)?.frontmatter;
|
||||||
|
const id = frontmatter?.[NOTE_ID_PROPERTY];
|
||||||
|
if (id && !result.has(String(id))) result.set(String(id), file);
|
||||||
|
}
|
||||||
|
return result;
|
||||||
|
}
|
||||||
|
|
||||||
|
async setNoteIdentity(file, noteId, campaignId, title) {
|
||||||
|
await this.app.fileManager.processFrontMatter(file, (frontmatter) => {
|
||||||
|
frontmatter[NOTE_ID_PROPERTY] = String(noteId);
|
||||||
|
frontmatter[CAMPAIGN_PROPERTY] = String(campaignId);
|
||||||
|
frontmatter[REMOTE_TITLE_PROPERTY] = String(title || file.basename);
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
async ensureFolder(path) {
|
||||||
|
const normalized = normalizePath(path);
|
||||||
|
if (!normalized || normalized === '.') return;
|
||||||
|
const parts = normalized.split('/');
|
||||||
|
let current = '';
|
||||||
|
for (const part of parts) {
|
||||||
|
current = current ? `${current}/${part}` : part;
|
||||||
|
if (!this.app.vault.getAbstractFileByPath(current)) {
|
||||||
|
await this.app.vault.createFolder(current);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
async availableMarkdownPath(folder, title, noteId) {
|
||||||
|
const base = safeSegment(title, 'Untitled');
|
||||||
|
let path = normalizePath(`${folder}/${base}.md`);
|
||||||
|
if (!this.app.vault.getAbstractFileByPath(path)) return path;
|
||||||
|
const suffix = String(noteId).slice(-6);
|
||||||
|
path = normalizePath(`${folder}/${base} (${suffix}).md`);
|
||||||
|
let counter = 2;
|
||||||
|
while (this.app.vault.getAbstractFileByPath(path)) {
|
||||||
|
path = normalizePath(`${folder}/${base} (${suffix}-${counter}).md`);
|
||||||
|
counter += 1;
|
||||||
|
}
|
||||||
|
return path;
|
||||||
|
}
|
||||||
|
|
||||||
|
async renameImportedFile(file, title, noteId) {
|
||||||
|
const parent = file.parent?.path || '';
|
||||||
|
const base = safeSegment(title, 'Untitled');
|
||||||
|
let targetPath = normalizePath(parent ? `${parent}/${base}.md` : `${base}.md`);
|
||||||
|
if (targetPath === file.path) return file;
|
||||||
|
if (this.app.vault.getAbstractFileByPath(targetPath)) {
|
||||||
|
targetPath = await this.availableMarkdownPath(parent || '.', title, noteId);
|
||||||
|
}
|
||||||
|
await this.app.fileManager.renameFile(file, targetPath);
|
||||||
|
return this.app.vault.getAbstractFileByPath(targetPath);
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
class DragonrollSettingTab extends PluginSettingTab {
|
||||||
|
constructor(app, plugin) {
|
||||||
|
super(app, plugin);
|
||||||
|
this.plugin = plugin;
|
||||||
|
this.campaigns = [];
|
||||||
|
this.loginName = '';
|
||||||
|
this.password = '';
|
||||||
|
}
|
||||||
|
|
||||||
|
display() {
|
||||||
|
const { containerEl } = this;
|
||||||
|
containerEl.empty();
|
||||||
|
containerEl.createEl('h2', { text: 'Dragonroll Sync' });
|
||||||
|
containerEl.createEl('p', {
|
||||||
|
text: 'Sign in with your Dragonroll account, choose a campaign, then use the import and push commands. Your password is used only to sign in; the 48-hour session token is stored in this vault.',
|
||||||
|
});
|
||||||
|
|
||||||
|
new Setting(containerEl)
|
||||||
|
.setName('Dragonroll API URL')
|
||||||
|
.setDesc('Use the server address, with or without /api.')
|
||||||
|
.addText((text) => text
|
||||||
|
.setPlaceholder('https://dragonroll.aranroig.com/api')
|
||||||
|
.setValue(this.plugin.settings.apiBaseUrl)
|
||||||
|
.onChange(async (value) => {
|
||||||
|
const previous = this.plugin.settings.apiBaseUrl.trim().replace(/\/+$/, '');
|
||||||
|
const next = value.trim().replace(/\/+$/, '');
|
||||||
|
if (previous !== next) {
|
||||||
|
this.plugin.settings.token = '';
|
||||||
|
this.plugin.settings.campaignId = '';
|
||||||
|
this.campaigns = [];
|
||||||
|
}
|
||||||
|
this.plugin.settings.apiBaseUrl = value.trim();
|
||||||
|
await this.plugin.saveSettings();
|
||||||
|
}));
|
||||||
|
|
||||||
|
new Setting(containerEl)
|
||||||
|
.setName('Username or email')
|
||||||
|
.addText((text) => text
|
||||||
|
.setPlaceholder('Dragonroll username or email')
|
||||||
|
.onChange((value) => { this.loginName = value.trim(); }));
|
||||||
|
|
||||||
|
new Setting(containerEl)
|
||||||
|
.setName('Password')
|
||||||
|
.addText((text) => {
|
||||||
|
text.inputEl.type = 'password';
|
||||||
|
text.inputEl.autocomplete = 'off';
|
||||||
|
text.onChange((value) => { this.password = value; });
|
||||||
|
});
|
||||||
|
|
||||||
|
new Setting(containerEl)
|
||||||
|
.setName(this.plugin.settings.token ? 'Session' : 'Sign in')
|
||||||
|
.setDesc(this.plugin.settings.token ? 'The stored session expires after 48 hours.' : 'Password is not saved by this plugin.')
|
||||||
|
.addButton((button) => button
|
||||||
|
.setButtonText('Sign in')
|
||||||
|
.setCta()
|
||||||
|
.onClick(async () => {
|
||||||
|
if (!this.loginName || !this.password) {
|
||||||
|
new Notice('Enter your Dragonroll username/email and password.');
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
button.setDisabled(true);
|
||||||
|
try {
|
||||||
|
this.campaigns = await this.plugin.login(this.loginName, this.password);
|
||||||
|
this.password = '';
|
||||||
|
this.display();
|
||||||
|
new Notice(`Signed in. Found ${this.campaigns.length} campaign(s).`);
|
||||||
|
} catch (error) {
|
||||||
|
new Notice(error.message || 'Could not sign in to Dragonroll.');
|
||||||
|
} finally {
|
||||||
|
button.setDisabled(false);
|
||||||
|
}
|
||||||
|
}));
|
||||||
|
|
||||||
|
if (this.plugin.settings.token) {
|
||||||
|
new Setting(containerEl)
|
||||||
|
.setName('Campaign')
|
||||||
|
.setDesc('The campaign used by import and push commands.')
|
||||||
|
.addDropdown((dropdown) => {
|
||||||
|
dropdown.addOption('', 'Choose a campaign');
|
||||||
|
for (const campaign of this.campaigns) {
|
||||||
|
dropdown.addOption(String(campaign._id), campaign.name);
|
||||||
|
}
|
||||||
|
dropdown.setValue(this.plugin.settings.campaignId || '');
|
||||||
|
dropdown.onChange(async (value) => {
|
||||||
|
this.plugin.settings.campaignId = value;
|
||||||
|
await this.plugin.saveSettings();
|
||||||
|
});
|
||||||
|
})
|
||||||
|
.addButton((button) => button
|
||||||
|
.setButtonText('Load campaigns')
|
||||||
|
.onClick(async () => {
|
||||||
|
button.setDisabled(true);
|
||||||
|
try {
|
||||||
|
this.campaigns = await this.plugin.getCampaigns();
|
||||||
|
this.display();
|
||||||
|
new Notice(`Loaded ${this.campaigns.length} campaign(s).`);
|
||||||
|
} catch (error) {
|
||||||
|
new Notice(error.message || 'Could not load campaigns.');
|
||||||
|
} finally {
|
||||||
|
button.setDisabled(false);
|
||||||
|
}
|
||||||
|
}));
|
||||||
|
|
||||||
|
new Setting(containerEl)
|
||||||
|
.setName('Sign out')
|
||||||
|
.setDesc('Remove the saved Dragonroll session from this vault.')
|
||||||
|
.addButton((button) => button
|
||||||
|
.setButtonText('Sign out')
|
||||||
|
.onClick(async () => {
|
||||||
|
this.plugin.settings.token = '';
|
||||||
|
this.plugin.settings.campaignId = '';
|
||||||
|
await this.plugin.saveSettings();
|
||||||
|
this.display();
|
||||||
|
}));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
function safeSegment(value, fallback) {
|
||||||
|
const safe = String(value || '')
|
||||||
|
.replace(/[\\\/:*?"<>|#^\[\]]/g, '-')
|
||||||
|
.replace(/[. ]+$/g, '')
|
||||||
|
.trim();
|
||||||
|
return safe || fallback;
|
||||||
|
}
|
||||||
|
|
||||||
|
function stripPluginMetadata(markdown) {
|
||||||
|
const text = String(markdown || '');
|
||||||
|
const match = text.match(/^(---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/);
|
||||||
|
if (!match) return text;
|
||||||
|
const keptLines = match[2].split(/\r?\n/).filter((line) =>
|
||||||
|
!/^(dragonrollId|dragonrollCampaign|dragonrollTitle):\s*/.test(line)
|
||||||
|
);
|
||||||
|
const frontmatter = keptLines.join('\n').trim();
|
||||||
|
const body = text.slice(match[0].length);
|
||||||
|
return frontmatter ? `---\n${frontmatter}\n---\n${body}` : body;
|
||||||
|
}
|
||||||
|
|
||||||
|
async function signature(title, content) {
|
||||||
|
const value = `${title}\u0000${String(content).replace(/\r\n/g, '\n')}`;
|
||||||
|
if (globalThis.crypto?.subtle) {
|
||||||
|
const digest = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(value));
|
||||||
|
return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('');
|
||||||
|
}
|
||||||
|
let hash = 2166136261;
|
||||||
|
for (let index = 0; index < value.length; index += 1) {
|
||||||
|
hash = Math.imul(hash ^ value.charCodeAt(index), 16777619);
|
||||||
|
}
|
||||||
|
return (hash >>> 0).toString(16);
|
||||||
|
}
|
||||||
9
obsidian-plugin/manifest.json
Normal file
9
obsidian-plugin/manifest.json
Normal file
@@ -0,0 +1,9 @@
|
|||||||
|
{
|
||||||
|
"id": "dragonroll-sync",
|
||||||
|
"name": "Dragonroll Sync",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"minAppVersion": "1.5.0",
|
||||||
|
"description": "Import Dragonroll campaign notes into Obsidian and push edits back.",
|
||||||
|
"author": "Dragonroll",
|
||||||
|
"isDesktopOnly": false
|
||||||
|
}
|
||||||
@@ -3,6 +3,7 @@
|
|||||||
"concurrently": "^9.2.1"
|
"concurrently": "^9.2.1"
|
||||||
},
|
},
|
||||||
"scripts": {
|
"scripts": {
|
||||||
"dev": "concurrently -k -n BACKEND,FRONTEND,DISCORD-BOT,FOUNDRY -c blue,green,yellow,magenta \"DEBUG=* npm --prefix backend run dev\" \"npm --prefix frontend run dev\" \"npm --prefix discord-bot start\" \"node scripts/run-foundry.js\""
|
"dev": "concurrently -k -n BACKEND,FRONTEND,DISCORD-BOT,FOUNDRY -c blue,green,yellow,magenta \"DEBUG=* npm --prefix backend run dev\" \"npm --prefix frontend run dev\" \"npm --prefix discord-bot start\" \"node scripts/run-foundry.js\"",
|
||||||
|
"test": "node --test tests/"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
230
tests/foundry-pairing-status.test.js
Normal file
230
tests/foundry-pairing-status.test.js
Normal file
@@ -0,0 +1,230 @@
|
|||||||
|
// Tests for the pairing status the Dragonroll Foundry module shows in its
|
||||||
|
// settings (Syndria98/dragonroll#17). Like foundry-sync-toggle.test.js, the module
|
||||||
|
// script runs inside a `node:vm` context of stubbed Foundry globals; here each
|
||||||
|
// test also decides what Dragonroll answers, because the status is that answer
|
||||||
|
// plus what this client holds (its sync token and any pairing code).
|
||||||
|
//
|
||||||
|
// Run with `npm test` from the repository root, or `node --test tests/`.
|
||||||
|
|
||||||
|
const { test } = require("node:test");
|
||||||
|
const assert = require("node:assert/strict");
|
||||||
|
const fs = require("node:fs");
|
||||||
|
const path = require("node:path");
|
||||||
|
const vm = require("node:vm");
|
||||||
|
|
||||||
|
const MODULE_ID = "dragonroll-foundry";
|
||||||
|
const MODULE_SOURCE = fs.readFileSync(
|
||||||
|
path.join(__dirname, "..", "dragonroll-foundry", "scripts", "api.js"),
|
||||||
|
"utf8",
|
||||||
|
);
|
||||||
|
|
||||||
|
const LINKED_CAMPAIGN = { id: "campaign-1", name: "Curse of Strahd" };
|
||||||
|
|
||||||
|
// The stub starts as a world that finished pairing (`syncToken: ""` is one that
|
||||||
|
// never did). `answers` maps a route fragment to the JSON Dragonroll replies
|
||||||
|
// with; a route that is not listed answers `{status:"ok"}`, and one mapped to
|
||||||
|
// null answers HTML, like a Dragonroll old enough not to have that route at all.
|
||||||
|
function makeStubWorld({ syncToken = "sync-token-1", linkCode = "", answers = {} } = {}) {
|
||||||
|
const state = {
|
||||||
|
hooks: new Map(),
|
||||||
|
registered: new Map(),
|
||||||
|
requests: [],
|
||||||
|
notifications: [],
|
||||||
|
};
|
||||||
|
|
||||||
|
const settingsStore = {
|
||||||
|
autoSync: true,
|
||||||
|
syncToken,
|
||||||
|
linkCode,
|
||||||
|
dragonrollApiUrl: "http://backend.test:5000",
|
||||||
|
};
|
||||||
|
|
||||||
|
const sandbox = {
|
||||||
|
console: { log() {}, info() {}, warn() {}, error() {} },
|
||||||
|
URL,
|
||||||
|
CONFIG: {},
|
||||||
|
window: { location: { origin: "http://vtt.test" } },
|
||||||
|
ui: {
|
||||||
|
notifications: {
|
||||||
|
info: (text) => state.notifications.push(["info", text]),
|
||||||
|
warn: (text) => state.notifications.push(["warn", text]),
|
||||||
|
error: (text) => state.notifications.push(["error", text]),
|
||||||
|
},
|
||||||
|
},
|
||||||
|
Hooks: {
|
||||||
|
once(name, fn) { state.hooks.set(name, [fn]); },
|
||||||
|
on(name, fn) {
|
||||||
|
const handlers = state.hooks.get(name) || [];
|
||||||
|
handlers.push(fn);
|
||||||
|
state.hooks.set(name, handlers);
|
||||||
|
},
|
||||||
|
},
|
||||||
|
// The pairing status never waits on a timer: it is written when the world is
|
||||||
|
// ready and whenever a pairing attempt answers, so dropping these keeps the
|
||||||
|
// snapshot and reconcile loops out of these tests.
|
||||||
|
setTimeout: () => 0,
|
||||||
|
clearTimeout: () => {},
|
||||||
|
setInterval: () => 0,
|
||||||
|
clearInterval: () => {},
|
||||||
|
fetch: async (url, options = {}) => {
|
||||||
|
const href = String(url);
|
||||||
|
state.requests.push({
|
||||||
|
href,
|
||||||
|
method: options.method,
|
||||||
|
authorization: options.headers?.Authorization || "",
|
||||||
|
});
|
||||||
|
const route = Object.keys(answers).find((fragment) => href.includes(fragment));
|
||||||
|
const payload = route ? answers[route] : { status: "ok" };
|
||||||
|
if (payload === null) {
|
||||||
|
return { ok: false, status: 404, json: async () => { throw new SyntaxError("Unexpected token < in JSON."); } };
|
||||||
|
}
|
||||||
|
return { ok: true, status: 200, json: async () => payload };
|
||||||
|
},
|
||||||
|
Actor: { async create() { return null; } },
|
||||||
|
Item: { async create() { return null; } },
|
||||||
|
};
|
||||||
|
|
||||||
|
sandbox.game = {
|
||||||
|
user: { isGM: true },
|
||||||
|
world: { id: "world-1", title: "Test World" },
|
||||||
|
system: { id: "dnd5e" },
|
||||||
|
modules: { get: () => ({}) },
|
||||||
|
actors: { contents: [], get: () => null },
|
||||||
|
items: { contents: [], get: () => null },
|
||||||
|
settings: {
|
||||||
|
register(module, key, definition) {
|
||||||
|
state.registered.set(key, definition);
|
||||||
|
if (!(key in settingsStore)) settingsStore[key] = definition.default;
|
||||||
|
},
|
||||||
|
get(module, key) { return settingsStore[key]; },
|
||||||
|
async set(module, key, value) {
|
||||||
|
settingsStore[key] = value;
|
||||||
|
await state.registered.get(key)?.onChange?.(value);
|
||||||
|
},
|
||||||
|
},
|
||||||
|
};
|
||||||
|
|
||||||
|
vm.createContext(sandbox);
|
||||||
|
vm.runInContext(MODULE_SOURCE, sandbox);
|
||||||
|
|
||||||
|
state.game = sandbox.game;
|
||||||
|
state.status = () => settingsStore.pairingStatus;
|
||||||
|
state.statusRequests = () => state.requests.filter((request) => request.href.includes("foundry/sync/status"));
|
||||||
|
|
||||||
|
// The module's own awaits run in the vm's promise intrinsics, so a few turns of
|
||||||
|
// the event loop are what it takes for a written status to be observable.
|
||||||
|
state.settle = async () => {
|
||||||
|
for (let round = 0; round < 10; round += 1) await new Promise((resolve) => setImmediate(resolve));
|
||||||
|
};
|
||||||
|
|
||||||
|
state.fire = async (name, ...args) => {
|
||||||
|
for (const handler of state.hooks.get(name) || []) await handler(...args);
|
||||||
|
await state.settle();
|
||||||
|
};
|
||||||
|
|
||||||
|
state.configure = async (key, value) => {
|
||||||
|
await sandbox.game.settings.set(MODULE_ID, key, value);
|
||||||
|
await state.settle();
|
||||||
|
};
|
||||||
|
|
||||||
|
state.start = async () => {
|
||||||
|
await state.fire("init");
|
||||||
|
await state.fire("ready");
|
||||||
|
return state;
|
||||||
|
};
|
||||||
|
|
||||||
|
return state;
|
||||||
|
}
|
||||||
|
|
||||||
|
test("the pairing status is a setting the module configures", async () => {
|
||||||
|
const world = await makeStubWorld().start();
|
||||||
|
|
||||||
|
const setting = world.registered.get("pairingStatus");
|
||||||
|
assert.equal(setting.config, true, "the pairing status appears in the module settings");
|
||||||
|
assert.equal(setting.type.name, "String", "the pairing status is a sentence");
|
||||||
|
assert.equal(setting.scope, "client", "the pairing status belongs to this client, like the token it comes from");
|
||||||
|
});
|
||||||
|
|
||||||
|
test("a world that was never paired says it is not connected", async () => {
|
||||||
|
const world = await makeStubWorld({ syncToken: "" }).start();
|
||||||
|
|
||||||
|
assert.match(world.status(), /^Not connected/, "an unpaired world says so plainly");
|
||||||
|
assert.match(world.status(), /Dragonroll campaign/, "and names what it is not connected to");
|
||||||
|
assert.deepEqual(world.statusRequests(), [], "there is nothing to verify without a sync token");
|
||||||
|
});
|
||||||
|
|
||||||
|
test("a paired world names the Dragonroll campaign it is connected to", async () => {
|
||||||
|
const world = await makeStubWorld({
|
||||||
|
answers: { "foundry/sync/status": { status: "ok", campaign: LINKED_CAMPAIGN, worldId: "world-1" } },
|
||||||
|
}).start();
|
||||||
|
|
||||||
|
assert.equal(world.status(), `Connected to the Dragonroll campaign "${LINKED_CAMPAIGN.name}".`);
|
||||||
|
assert.equal(world.statusRequests()[0].authorization, "Bearer sync-token-1", "the campaign is asked with the sync token");
|
||||||
|
});
|
||||||
|
|
||||||
|
test("a campaign that unlinked this world stops being reported as connected", async () => {
|
||||||
|
const world = await makeStubWorld({
|
||||||
|
answers: { "foundry/sync/status": { status: "error", msg: "unauthorized" } },
|
||||||
|
}).start();
|
||||||
|
|
||||||
|
assert.match(world.status(), /^Not connected/);
|
||||||
|
assert.match(world.status(), /no longer linked/);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("an unreachable Dragonroll keeps the pairing this client already knows", async () => {
|
||||||
|
const world = await makeStubWorld({ answers: { "foundry/sync/status": null } }).start();
|
||||||
|
|
||||||
|
assert.equal(world.status(), "Connected to a Dragonroll campaign.",
|
||||||
|
"a Dragonroll without the status route says nothing, so the token speaks");
|
||||||
|
});
|
||||||
|
|
||||||
|
test("a code that cannot be redeemed explains why the world is not connected", async () => {
|
||||||
|
const world = await makeStubWorld({
|
||||||
|
syncToken: "",
|
||||||
|
answers: { "foundry/link/complete": { status: "error", msg: "foundry.errors.link-expired" } },
|
||||||
|
});
|
||||||
|
await world.start();
|
||||||
|
|
||||||
|
await world.configure("linkCode", "AN-EXPIRED-CODE");
|
||||||
|
|
||||||
|
assert.match(world.status(), /^Not connected/);
|
||||||
|
assert.match(world.status(), /pairing code is invalid, expired, or already used/);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("a code still waiting on Dragonroll says the pairing is not finished", async () => {
|
||||||
|
const world = await makeStubWorld({
|
||||||
|
syncToken: "",
|
||||||
|
answers: { "foundry/link/complete": { status: "error", msg: "errors.internal" } },
|
||||||
|
});
|
||||||
|
await world.start();
|
||||||
|
|
||||||
|
await world.configure("linkCode", "A-CODE-TO-RETRY");
|
||||||
|
|
||||||
|
assert.equal(world.status(), "Not connected yet: waiting for Dragonroll to accept this pairing code.");
|
||||||
|
});
|
||||||
|
|
||||||
|
test("redeeming a pairing code connects the world to its campaign", async () => {
|
||||||
|
const world = await makeStubWorld({
|
||||||
|
syncToken: "",
|
||||||
|
answers: {
|
||||||
|
"foundry/link/complete": { status: "ok", campaign: LINKED_CAMPAIGN, syncToken: "sync-token-2" },
|
||||||
|
},
|
||||||
|
});
|
||||||
|
await world.start();
|
||||||
|
|
||||||
|
await world.configure("linkCode", "A-FRESH-CODE");
|
||||||
|
|
||||||
|
assert.equal(world.status(), `Connected to the Dragonroll campaign "${LINKED_CAMPAIGN.name}".`);
|
||||||
|
assert.equal(world.game.settings.get(MODULE_ID, "linkCode"), "", "a redeemed code is not kept");
|
||||||
|
});
|
||||||
|
|
||||||
|
test("whatever is typed into the status is replaced by the real one", async () => {
|
||||||
|
const world = await makeStubWorld({
|
||||||
|
answers: { "foundry/sync/status": { status: "ok", campaign: LINKED_CAMPAIGN, worldId: "world-1" } },
|
||||||
|
});
|
||||||
|
await world.start();
|
||||||
|
|
||||||
|
await world.configure("pairingStatus", "My own status text");
|
||||||
|
|
||||||
|
assert.equal(world.status(), `Connected to the Dragonroll campaign "${LINKED_CAMPAIGN.name}".`);
|
||||||
|
});
|
||||||
312
tests/foundry-sync-toggle.test.js
Normal file
312
tests/foundry-sync-toggle.test.js
Normal file
@@ -0,0 +1,312 @@
|
|||||||
|
// Tests for the Dragonroll Foundry module's sync toggle and per-actor force sync
|
||||||
|
// (Syndria98/dragonroll#8). The module is a Foundry client script with no module
|
||||||
|
// wrapper, so it is loaded into a `node:vm` context holding stubbed Foundry
|
||||||
|
// globals (`game`, `Hooks`, `ui`, `fetch`) with fake timers: that makes every
|
||||||
|
// queued push, retry and reconcile observable without a running Foundry VTT.
|
||||||
|
//
|
||||||
|
// Run with `npm test` from the repository root, or `node --test tests/`.
|
||||||
|
|
||||||
|
const { test } = require("node:test");
|
||||||
|
const assert = require("node:assert/strict");
|
||||||
|
const fs = require("node:fs");
|
||||||
|
const path = require("node:path");
|
||||||
|
const vm = require("node:vm");
|
||||||
|
|
||||||
|
const MODULE_ID = "dragonroll-foundry";
|
||||||
|
const MODULE_SOURCE = fs.readFileSync(
|
||||||
|
path.join(__dirname, "..", "dragonroll-foundry", "scripts", "api.js"),
|
||||||
|
"utf8",
|
||||||
|
);
|
||||||
|
|
||||||
|
function stubDocument(id, name, extra = {}) {
|
||||||
|
return {
|
||||||
|
id,
|
||||||
|
name,
|
||||||
|
flags: {},
|
||||||
|
getFlag(module, key) { return this.flags?.[module]?.[key]; },
|
||||||
|
async update(data) {
|
||||||
|
for (const [key, value] of Object.entries(data)) {
|
||||||
|
const parts = key.split(".");
|
||||||
|
const last = parts.pop();
|
||||||
|
let target = this;
|
||||||
|
for (const part of parts) target = target[part] ??= {};
|
||||||
|
target[last] = value;
|
||||||
|
}
|
||||||
|
return this;
|
||||||
|
},
|
||||||
|
toObject() {
|
||||||
|
return {
|
||||||
|
_id: this.id,
|
||||||
|
name: this.name,
|
||||||
|
type: this.type,
|
||||||
|
img: "icons/svg/mystery-man.svg",
|
||||||
|
flags: this.flags,
|
||||||
|
...(this.system ? { system: this.system } : {}),
|
||||||
|
};
|
||||||
|
},
|
||||||
|
...extra,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
function makeWorldItem(id, name) {
|
||||||
|
return stubDocument(id, name, {
|
||||||
|
documentName: "Item",
|
||||||
|
type: "weapon",
|
||||||
|
parent: null,
|
||||||
|
system: { properties: { value: [] }, quantity: 1, weight: 3, rarity: "common" },
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
function makeStubWorld({ autoSync = true } = {}) {
|
||||||
|
const state = {
|
||||||
|
hooks: new Map(),
|
||||||
|
registered: new Map(),
|
||||||
|
requests: [],
|
||||||
|
notifications: [],
|
||||||
|
timers: new Map(),
|
||||||
|
nextTimerId: 1,
|
||||||
|
};
|
||||||
|
|
||||||
|
const actors = [
|
||||||
|
stubDocument("actor-1", "Thalia", { documentName: "Actor", type: "character", items: { contents: [] } }),
|
||||||
|
stubDocument("actor-2", "Grunt", { documentName: "Actor", type: "npc", items: { contents: [] } }),
|
||||||
|
];
|
||||||
|
const settingsStore = {
|
||||||
|
autoSync,
|
||||||
|
syncToken: "sync-token-1",
|
||||||
|
dragonrollApiUrl: "http://backend.test:5000",
|
||||||
|
};
|
||||||
|
|
||||||
|
const sandbox = {
|
||||||
|
console: { log() {}, info() {}, warn() {}, error() {} },
|
||||||
|
URL,
|
||||||
|
CONFIG: {},
|
||||||
|
window: { location: { origin: "http://vtt.test" } },
|
||||||
|
ui: {
|
||||||
|
notifications: {
|
||||||
|
info: (text) => state.notifications.push(["info", text]),
|
||||||
|
warn: (text) => state.notifications.push(["warn", text]),
|
||||||
|
error: (text) => state.notifications.push(["error", text]),
|
||||||
|
},
|
||||||
|
},
|
||||||
|
Hooks: {
|
||||||
|
once(name, fn) { state.hooks.set(name, [fn]); },
|
||||||
|
on(name, fn) {
|
||||||
|
const handlers = state.hooks.get(name) || [];
|
||||||
|
handlers.push(fn);
|
||||||
|
state.hooks.set(name, handlers);
|
||||||
|
},
|
||||||
|
},
|
||||||
|
// Fake timers: the module debounces and retries with setTimeout, so the tests
|
||||||
|
// decide when those callbacks run instead of waiting on the wall clock.
|
||||||
|
setTimeout: (fn, delay = 0) => {
|
||||||
|
const id = state.nextTimerId++;
|
||||||
|
state.timers.set(id, { fn, delay });
|
||||||
|
return id;
|
||||||
|
},
|
||||||
|
clearTimeout: (id) => state.timers.delete(id),
|
||||||
|
setInterval: () => 0,
|
||||||
|
clearInterval: () => {},
|
||||||
|
fetch: async (url, options = {}) => {
|
||||||
|
state.requests.push({
|
||||||
|
href: String(url),
|
||||||
|
method: options.method,
|
||||||
|
body: options.body ? JSON.parse(options.body) : null,
|
||||||
|
});
|
||||||
|
return { ok: true, status: 200, json: async () => ({ status: "ok", actors: [], items: [] }) };
|
||||||
|
},
|
||||||
|
Actor: { async create() { return null; } },
|
||||||
|
Item: { async create() { return null; } },
|
||||||
|
};
|
||||||
|
|
||||||
|
sandbox.game = {
|
||||||
|
user: { isGM: true },
|
||||||
|
world: { id: "world-1", title: "Test World" },
|
||||||
|
system: { id: "dnd5e" },
|
||||||
|
modules: { get: () => ({}) },
|
||||||
|
actors: { contents: actors, get: (id) => actors.find((actor) => actor.id === id) },
|
||||||
|
items: { contents: [], get: () => null },
|
||||||
|
settings: {
|
||||||
|
register(module, key, definition) {
|
||||||
|
state.registered.set(key, definition);
|
||||||
|
if (!(key in settingsStore)) settingsStore[key] = definition.default;
|
||||||
|
},
|
||||||
|
get(module, key) { return settingsStore[key]; },
|
||||||
|
async set(module, key, value) {
|
||||||
|
settingsStore[key] = value;
|
||||||
|
await state.registered.get(key)?.onChange?.(value);
|
||||||
|
},
|
||||||
|
},
|
||||||
|
};
|
||||||
|
|
||||||
|
vm.createContext(sandbox);
|
||||||
|
vm.runInContext(MODULE_SOURCE, sandbox);
|
||||||
|
|
||||||
|
state.game = sandbox.game;
|
||||||
|
state.actor = (id) => actors.find((document) => document.id === id);
|
||||||
|
// Sync pushes only: the pairing status read lives under the same prefix, and it
|
||||||
|
// tells nothing about what the world sent.
|
||||||
|
state.syncRequests = () => state.requests.filter((request) => request.href.includes("foundry/sync")
|
||||||
|
&& !request.href.includes("foundry/sync/status"));
|
||||||
|
|
||||||
|
state.fire = async (name, ...args) => {
|
||||||
|
for (const handler of state.hooks.get(name) || []) await handler(...args);
|
||||||
|
await drain();
|
||||||
|
};
|
||||||
|
|
||||||
|
state.runTimers = async () => {
|
||||||
|
for (let round = 0; round < 6; round += 1) {
|
||||||
|
if (!state.timers.size && round > 2) break;
|
||||||
|
const due = [...state.timers.values()];
|
||||||
|
state.timers.clear();
|
||||||
|
for (const timer of due) await timer.fn();
|
||||||
|
await drain();
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
async function drain() {
|
||||||
|
await new Promise((resolve) => setImmediate(resolve));
|
||||||
|
}
|
||||||
|
|
||||||
|
state.linkedSetup = async () => {
|
||||||
|
await state.fire("init");
|
||||||
|
await state.fire("ready");
|
||||||
|
await state.runTimers();
|
||||||
|
state.requests.length = 0;
|
||||||
|
return state;
|
||||||
|
};
|
||||||
|
|
||||||
|
return state;
|
||||||
|
}
|
||||||
|
|
||||||
|
async function forceSyncActors(world, ...actorIds) {
|
||||||
|
const options = [];
|
||||||
|
await world.fire("getActorDirectoryEntryContext", null, options);
|
||||||
|
const entry = options.find((option) => option.name === "Dragonroll: Force Sync");
|
||||||
|
assert.ok(entry, "Dragonroll: Force Sync is offered in the actor directory context menu");
|
||||||
|
await entry.callback(actorIds.map((actorId) => ({ dataset: { actorId } })));
|
||||||
|
await world.runTimers();
|
||||||
|
}
|
||||||
|
|
||||||
|
test("auto-sync is a module setting that is on by default", async () => {
|
||||||
|
const world = makeStubWorld();
|
||||||
|
await world.fire("init");
|
||||||
|
|
||||||
|
const setting = world.registered.get("autoSync");
|
||||||
|
assert.equal(setting.default, true, "autosync is on by default");
|
||||||
|
assert.equal(setting.config, true, "autosync appears in the module settings");
|
||||||
|
assert.equal(world.game.settings.get(MODULE_ID, "autoSync"), true);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("autosync on: Foundry CRUD events keep syncing with Dragonroll", async () => {
|
||||||
|
const world = await makeStubWorld().linkedSetup();
|
||||||
|
|
||||||
|
await world.fire("updateActor", world.actor("actor-1"));
|
||||||
|
await world.runTimers();
|
||||||
|
|
||||||
|
const pushes = world.syncRequests();
|
||||||
|
assert.equal(pushes.length, 1);
|
||||||
|
assert.equal(pushes[0].body.actors[0]._id, "actor-1");
|
||||||
|
});
|
||||||
|
|
||||||
|
test("autosync off: CRUD requests stop syncing", async () => {
|
||||||
|
const world = await makeStubWorld().linkedSetup();
|
||||||
|
|
||||||
|
await world.game.settings.set(MODULE_ID, "autoSync", false);
|
||||||
|
await world.fire("updateActor", world.actor("actor-1"));
|
||||||
|
await world.fire("deleteActor", world.actor("actor-2"));
|
||||||
|
await world.fire("createItem", makeWorldItem("item-1", "Longsword"));
|
||||||
|
await world.runTimers();
|
||||||
|
|
||||||
|
assert.deepEqual(world.syncRequests(), []);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("edits made while autosync is off are delivered when it is turned back on", async () => {
|
||||||
|
const world = await makeStubWorld().linkedSetup();
|
||||||
|
|
||||||
|
await world.game.settings.set(MODULE_ID, "autoSync", false);
|
||||||
|
await world.fire("updateActor", world.actor("actor-1"));
|
||||||
|
await world.fire("createItem", makeWorldItem("item-1", "Longsword"));
|
||||||
|
await world.runTimers();
|
||||||
|
assert.deepEqual(world.syncRequests(), []);
|
||||||
|
|
||||||
|
await world.game.settings.set(MODULE_ID, "autoSync", true);
|
||||||
|
await world.runTimers();
|
||||||
|
|
||||||
|
const pushes = world.syncRequests();
|
||||||
|
assert.ok(pushes.some((request) => request.body?.fullSync === false
|
||||||
|
&& request.body.actors?.some((actor) => actor._id === "actor-1")),
|
||||||
|
"the actor edit queued while autosync was off is sent");
|
||||||
|
assert.ok(pushes.some((request) => request.href.includes("foundry/sync/item-snapshot")
|
||||||
|
&& request.body.items.some((item) => item._id === "item-1")),
|
||||||
|
"the item edit queued while autosync was off is sent");
|
||||||
|
});
|
||||||
|
|
||||||
|
test("autosync off at world start: no snapshot and no reconcile", async () => {
|
||||||
|
const world = makeStubWorld({ autoSync: false });
|
||||||
|
await world.fire("init");
|
||||||
|
await world.fire("ready");
|
||||||
|
await world.runTimers();
|
||||||
|
|
||||||
|
assert.deepEqual(world.syncRequests(), []);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("force sync sends selected actors to Dragonroll even with autosync off", async () => {
|
||||||
|
const world = await makeStubWorld().linkedSetup();
|
||||||
|
await world.game.settings.set(MODULE_ID, "autoSync", false);
|
||||||
|
|
||||||
|
await forceSyncActors(world, "actor-2");
|
||||||
|
|
||||||
|
const pushes = world.syncRequests();
|
||||||
|
assert.equal(pushes.length, 1);
|
||||||
|
assert.equal(pushes[0].body.fullSync, false, "a forced actor never prunes the campaign");
|
||||||
|
assert.deepEqual(pushes[0].body.actors.map((actor) => actor._id), ["actor-2"]);
|
||||||
|
assert.deepEqual(world.notifications.filter(([kind]) => kind !== "info"), []);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("force sync sends every selected actor in one push", async () => {
|
||||||
|
const world = await makeStubWorld().linkedSetup();
|
||||||
|
await world.game.settings.set(MODULE_ID, "autoSync", false);
|
||||||
|
|
||||||
|
await forceSyncActors(world, "actor-1", "actor-2");
|
||||||
|
|
||||||
|
const pushes = world.syncRequests();
|
||||||
|
assert.equal(pushes.length, 1);
|
||||||
|
assert.deepEqual(pushes[0].body.actors.map((actor) => actor._id), ["actor-1", "actor-2"]);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("force sync also works while autosync is on", async () => {
|
||||||
|
const world = await makeStubWorld().linkedSetup();
|
||||||
|
|
||||||
|
await forceSyncActors(world, "actor-1");
|
||||||
|
|
||||||
|
assert.deepEqual(world.syncRequests()[0]?.body.actors.map((actor) => actor._id), ["actor-1"]);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("force sync refuses an actor Dragonroll does not import", async () => {
|
||||||
|
const world = makeStubWorld({ autoSync: false });
|
||||||
|
await world.fire("init");
|
||||||
|
const cart = stubDocument("actor-3", "Cart", { documentName: "Actor", type: "vehicle", items: { contents: [] } });
|
||||||
|
world.game.actors.contents.push(cart);
|
||||||
|
|
||||||
|
await forceSyncActors(world, "actor-3");
|
||||||
|
|
||||||
|
assert.deepEqual(world.syncRequests(), []);
|
||||||
|
assert.ok(world.notifications.some(([kind, text]) => kind === "warn" && text.includes("Cart")));
|
||||||
|
});
|
||||||
|
|
||||||
|
test("turning autosync back on reconciles both sides again", async () => {
|
||||||
|
const world = makeStubWorld({ autoSync: false });
|
||||||
|
await world.fire("init");
|
||||||
|
await world.fire("ready");
|
||||||
|
await world.runTimers();
|
||||||
|
assert.deepEqual(world.syncRequests(), []);
|
||||||
|
|
||||||
|
await world.game.settings.set(MODULE_ID, "autoSync", true);
|
||||||
|
await world.runTimers();
|
||||||
|
|
||||||
|
assert.ok(world.syncRequests().some((request) => request.body?.fullSync === true),
|
||||||
|
"the world sends its full snapshot again");
|
||||||
|
assert.ok(world.requests.some((request) => request.href.includes("foundry/sync/characters")),
|
||||||
|
"Dragonroll documents are applied back into the world");
|
||||||
|
});
|
||||||
379
tests/map-pins.test.js
Normal file
379
tests/map-pins.test.js
Normal file
@@ -0,0 +1,379 @@
|
|||||||
|
// Tests for the notes pinned onto a map (Syndria98/dragonroll#20): right clicking a map pins one of
|
||||||
|
// the campaign notes at that spot, and clicking the marker reads the linked note in a window.
|
||||||
|
//
|
||||||
|
// The repository root installs no dependencies, so both sides are loaded into `node:vm` contexts.
|
||||||
|
// The express routers run against a stubbed `require` (express itself, multer and the mongoose
|
||||||
|
// models) answering with plain objects: that keeps the ownership, same-campaign and dedup rules of
|
||||||
|
// POST /map/pin observable without a database. `frontend/app/services/MapPins.js` holds the image ↔
|
||||||
|
// screen translation and the note picker labels, and is loaded the way map-viewer.test.js loads
|
||||||
|
// Content.js. The last checks read the template of the map viewer, because there the wiring itself
|
||||||
|
// is what has to stay right.
|
||||||
|
//
|
||||||
|
// Run with `npm test` from the repository root, or `node --test tests/`.
|
||||||
|
|
||||||
|
const { test } = require("node:test");
|
||||||
|
const assert = require("node:assert/strict");
|
||||||
|
const fs = require("node:fs");
|
||||||
|
const path = require("node:path");
|
||||||
|
const vm = require("node:vm");
|
||||||
|
|
||||||
|
function readRepoFile(...parts) {
|
||||||
|
return fs.readFileSync(path.join(__dirname, "..", ...parts), "utf8");
|
||||||
|
}
|
||||||
|
|
||||||
|
// A mongoose query answers whatever `await query` and `query.lean()` answer with, and lets `select()`
|
||||||
|
// and `sort()` sit in between.
|
||||||
|
function mongooseQuery(value) {
|
||||||
|
const result = {
|
||||||
|
select: () => result,
|
||||||
|
sort: () => result,
|
||||||
|
lean: () => Promise.resolve(value),
|
||||||
|
then: (onFulfilled, onRejected) => Promise.resolve(value).then(onFulfilled, onRejected),
|
||||||
|
};
|
||||||
|
return result;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Loads an express router file with every module it requires stubbed out: `stubs` maps a require
|
||||||
|
// path ("../models/Map") to the module the route should see.
|
||||||
|
function loadRouter(relativeParts, stubs) {
|
||||||
|
const routes = new Map();
|
||||||
|
const router = {
|
||||||
|
get: (route, ...handlers) => routes.set(`GET ${route}`, handlers),
|
||||||
|
post: (route, ...handlers) => routes.set(`POST ${route}`, handlers),
|
||||||
|
};
|
||||||
|
|
||||||
|
const requireStub = (id) => {
|
||||||
|
if (id === "express") return { Router: () => router };
|
||||||
|
if (id === "../services/storage") return { single: () => (req, res, next) => next() };
|
||||||
|
if (!(id in stubs)) throw new Error(`require("${id}") is not stubbed`);
|
||||||
|
return stubs[id];
|
||||||
|
};
|
||||||
|
|
||||||
|
// Both files only need `require`, `module` and `exports`, so they are compiled as functions in
|
||||||
|
// the realm of the tests: the objects the routes build are then plain host objects to assert on.
|
||||||
|
const moduleStub = { exports: {} };
|
||||||
|
vm.compileFunction(readRepoFile(...relativeParts), ["require", "module", "exports"])(
|
||||||
|
requireStub, moduleStub, moduleStub.exports
|
||||||
|
);
|
||||||
|
|
||||||
|
async function call(route, { body = {}, query = {}, params = {}, user = { id: "user-1" } } = {}) {
|
||||||
|
const handlers = routes.get(route);
|
||||||
|
assert.ok(handlers, `${route} is not mounted`);
|
||||||
|
const res = { payload: null, json(payload) { this.payload = payload; } };
|
||||||
|
// The multer middleware the routes mount is stubbed away, so the handler is the last one.
|
||||||
|
await handlers[handlers.length - 1]({ body, query, params, user }, res);
|
||||||
|
return res.payload;
|
||||||
|
}
|
||||||
|
|
||||||
|
return { routes, call };
|
||||||
|
}
|
||||||
|
|
||||||
|
function makeMap(pins = []) {
|
||||||
|
return { _id: "map-1", campaign: "campaign-1", pins, save: async () => {} };
|
||||||
|
}
|
||||||
|
|
||||||
|
function loadMapRoutes({ ownsCampaign = true, maps = [], notes = [] } = {}) {
|
||||||
|
return loadRouter(["backend", "src", "routes", "map.js"], {
|
||||||
|
"../models/Campaign": { findOne: () => mongooseQuery(ownsCampaign ? { _id: "campaign-1" } : null) },
|
||||||
|
"../models/Map": { findById: (id) => mongooseQuery(maps.find((map) => map._id === id) ?? null) },
|
||||||
|
"../models/Note": {
|
||||||
|
findOne: (filter) => mongooseQuery(
|
||||||
|
notes.some((note) => note._id === String(filter._id) && String(note.campaign) === String(filter.campaign))
|
||||||
|
? { _id: String(filter._id) }
|
||||||
|
: null
|
||||||
|
),
|
||||||
|
},
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
function mapPinRouteTests() {
|
||||||
|
test("pinning a note stores it at the spot that was clicked", async () => {
|
||||||
|
const map = makeMap();
|
||||||
|
const api = loadMapRoutes({ maps: [map], notes: [{ _id: "note-1", campaign: "campaign-1" }] });
|
||||||
|
|
||||||
|
const response = await api.call("POST /pin", { body: { id: "map-1", note: "note-1", x: 420, y: 96 } });
|
||||||
|
|
||||||
|
assert.equal(response.status, "ok");
|
||||||
|
assert.deepEqual(map.pins, [{ note: "note-1", x: 420, y: 96 }]);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("a pin keeps whole image pixels and never goes off the top left corner", async () => {
|
||||||
|
const map = makeMap();
|
||||||
|
const api = loadMapRoutes({ maps: [map], notes: [{ _id: "note-1", campaign: "campaign-1" }] });
|
||||||
|
|
||||||
|
// Coordinates arrive as strings from a multipart form, and a drag can leave the image.
|
||||||
|
await api.call("POST /pin", { body: { id: "map-1", note: "note-1", x: "120.6", y: -8 } });
|
||||||
|
|
||||||
|
assert.deepEqual(map.pins, [{ note: "note-1", x: 121, y: 0 }]);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("a note of another campaign cannot be pinned onto a map", async () => {
|
||||||
|
const map = makeMap();
|
||||||
|
const api = loadMapRoutes({ maps: [map], notes: [{ _id: "note-2", campaign: "campaign-2" }] });
|
||||||
|
|
||||||
|
const response = await api.call("POST /pin", { body: { id: "map-1", note: "note-2", x: 10, y: 10 } });
|
||||||
|
|
||||||
|
assert.equal(response.msg, "errors.notfound");
|
||||||
|
assert.deepEqual(map.pins, []);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("a map of somebody else's campaign answers unauthorized", async () => {
|
||||||
|
const map = makeMap();
|
||||||
|
const api = loadMapRoutes({ ownsCampaign: false, maps: [map], notes: [{ _id: "note-1", campaign: "campaign-1" }] });
|
||||||
|
|
||||||
|
const response = await api.call("POST /pin", { body: { id: "map-1", note: "note-1", x: 10, y: 10 } });
|
||||||
|
|
||||||
|
assert.equal(response.msg, "unauthorized");
|
||||||
|
assert.deepEqual(map.pins, []);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("pinning a note again moves its marker instead of adding a twin", async () => {
|
||||||
|
const map = makeMap([{ _id: "pin-1", note: "note-1", x: 10, y: 10 }]);
|
||||||
|
const api = loadMapRoutes({ maps: [map], notes: [{ _id: "note-1", campaign: "campaign-1" }] });
|
||||||
|
|
||||||
|
await api.call("POST /pin", { body: { id: "map-1", note: "note-1", x: 300, y: 220 } });
|
||||||
|
|
||||||
|
assert.equal(map.pins.length, 1);
|
||||||
|
assert.deepEqual({ ...map.pins[0] }, { _id: "pin-1", note: "note-1", x: 300, y: 220 });
|
||||||
|
});
|
||||||
|
|
||||||
|
test("pinning needs both a map and a note", async () => {
|
||||||
|
const map = makeMap();
|
||||||
|
const api = loadMapRoutes({ maps: [map], notes: [{ _id: "note-1", campaign: "campaign-1" }] });
|
||||||
|
|
||||||
|
assert.equal((await api.call("POST /pin", { body: { note: "note-1", x: 1, y: 1 } })).msg, "errors.missing-data");
|
||||||
|
assert.equal((await api.call("POST /pin", { body: { id: "map-1", x: 1, y: 1 } })).msg, "errors.missing-data");
|
||||||
|
assert.deepEqual(map.pins, []);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("unpin removes the pin it is given and keeps the others", async () => {
|
||||||
|
const map = makeMap([
|
||||||
|
{ _id: "pin-1", note: "note-1", x: 10, y: 10 },
|
||||||
|
{ _id: "pin-2", note: "note-2", x: 20, y: 20 },
|
||||||
|
]);
|
||||||
|
const api = loadMapRoutes({ maps: [map], notes: [] });
|
||||||
|
|
||||||
|
const response = await api.call("POST /unpin", { body: { id: "map-1", pin: "pin-1" } });
|
||||||
|
|
||||||
|
assert.equal(response.status, "ok");
|
||||||
|
assert.deepEqual(map.pins.map((pin) => pin._id), ["pin-2"]);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("unpin of a map of somebody else keeps its pins", async () => {
|
||||||
|
const map = makeMap([{ _id: "pin-1", note: "note-1", x: 10, y: 10 }]);
|
||||||
|
const api = loadMapRoutes({ ownsCampaign: false, maps: [map] });
|
||||||
|
|
||||||
|
const response = await api.call("POST /unpin", { body: { id: "map-1", pin: "pin-1" } });
|
||||||
|
|
||||||
|
assert.equal(response.msg, "unauthorized");
|
||||||
|
assert.equal(map.pins.length, 1);
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
function loadNoteRoutes({ ownsCampaign = true, notes = [], folders = [], deletedCount = 1 } = {}) {
|
||||||
|
const pinsPulled = [];
|
||||||
|
const api = loadRouter(["backend", "src", "routes", "note.js"], {
|
||||||
|
"../models/Campaign": { findOne: () => mongooseQuery(ownsCampaign ? { _id: "campaign-1" } : null) },
|
||||||
|
"../models/Note": {
|
||||||
|
find: () => mongooseQuery(notes),
|
||||||
|
findById: (id) => mongooseQuery(notes.find((note) => note._id === id) ?? null),
|
||||||
|
deleteOne: () => mongooseQuery({ deletedCount }),
|
||||||
|
},
|
||||||
|
"../models/Folder": { find: () => mongooseQuery(folders) },
|
||||||
|
"../models/Map": {
|
||||||
|
// The driver drops the pins of the note from every map holding one; what is worth
|
||||||
|
// keeping here is the filter it is asked to do that with.
|
||||||
|
updateMany: async (filter, update) => {
|
||||||
|
pinsPulled.push({ filter, update });
|
||||||
|
return { modifiedCount: 1 };
|
||||||
|
},
|
||||||
|
},
|
||||||
|
});
|
||||||
|
return { api, pinsPulled };
|
||||||
|
}
|
||||||
|
|
||||||
|
function campaignNotesTests() {
|
||||||
|
const notes = [
|
||||||
|
{ _id: "note-1", title: "The Altar", folder: "folder-2" },
|
||||||
|
{ _id: "note-2", title: "The Inn", folder: null },
|
||||||
|
];
|
||||||
|
const folders = [
|
||||||
|
{ _id: "folder-1", name: "Undercity" },
|
||||||
|
{ _id: "folder-2", name: "Temple", parentFolder: "folder-1" },
|
||||||
|
];
|
||||||
|
|
||||||
|
test("the note picker answers with every note and the folders they live in", async () => {
|
||||||
|
const { api } = loadNoteRoutes({ notes, folders });
|
||||||
|
|
||||||
|
const response = await api.call("GET /all", { query: { campaign: "campaign-1" } });
|
||||||
|
|
||||||
|
assert.equal(response.status, "ok");
|
||||||
|
assert.deepEqual(response.notes.map((note) => note.title), ["The Altar", "The Inn"]);
|
||||||
|
assert.deepEqual(response.folders.map((folder) => folder.name), ["Undercity", "Temple"]);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("the note picker needs a campaign, and only of one's own", async () => {
|
||||||
|
const { api } = loadNoteRoutes({ notes, folders });
|
||||||
|
const { api: foreignCampaign } = loadNoteRoutes({ ownsCampaign: false, notes, folders });
|
||||||
|
|
||||||
|
assert.equal((await api.call("GET /all")).msg, "errors.missing-data");
|
||||||
|
assert.equal((await foreignCampaign.call("GET /all", { query: { campaign: "campaign-1" } })).msg, "unauthorized");
|
||||||
|
});
|
||||||
|
|
||||||
|
test("a note can be read on its own, the way a map pin asks for it", async () => {
|
||||||
|
const { api } = loadNoteRoutes({ notes: [{ _id: "note-1", title: "The Altar", content: "## The altar" }] });
|
||||||
|
|
||||||
|
const response = await api.call("GET /retrieve/:id", { params: { id: "note-1" } });
|
||||||
|
|
||||||
|
assert.equal(response.status, "ok");
|
||||||
|
assert.equal(response.note.content, "## The altar");
|
||||||
|
});
|
||||||
|
|
||||||
|
test("a note of a campaign the user does not own cannot be read", async () => {
|
||||||
|
const { api } = loadNoteRoutes({ ownsCampaign: false, notes: [{ _id: "note-1", title: "The Altar" }] });
|
||||||
|
|
||||||
|
const response = await api.call("GET /retrieve/:id", { params: { id: "note-1" } });
|
||||||
|
|
||||||
|
assert.equal(response.msg, "unauthorized");
|
||||||
|
});
|
||||||
|
|
||||||
|
test("deleting a note pulls the pins pointing at it", async () => {
|
||||||
|
const { api, pinsPulled } = loadNoteRoutes({ notes: [{ _id: "note-1", title: "The Altar" }] });
|
||||||
|
|
||||||
|
const response = await api.call("POST /delete", { body: { id: "note-1" } });
|
||||||
|
|
||||||
|
assert.equal(response.status, "ok");
|
||||||
|
assert.deepEqual(pinsPulled, [{ filter: { "pins.note": "note-1" }, update: { $pull: { pins: { note: "note-1" } } } }]);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("deleting a note that is not there does not touch any map", async () => {
|
||||||
|
const { api, pinsPulled } = loadNoteRoutes({ notes: [], deletedCount: 0 });
|
||||||
|
|
||||||
|
const response = await api.call("POST /delete", { body: { id: "note-9" } });
|
||||||
|
|
||||||
|
assert.equal(response.msg, "errors.notfound");
|
||||||
|
assert.deepEqual(pinsPulled, []);
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
function loadMapPinsService() {
|
||||||
|
const source = readRepoFile("frontend", "app", "services", "MapPins.js");
|
||||||
|
const body = source
|
||||||
|
.replace(/import\s*\{[^}]*\}\s*from\s*['"]vue['"];?/, "")
|
||||||
|
.replace(/export\s*\{/, "return {")
|
||||||
|
.concat("\n;");
|
||||||
|
|
||||||
|
return vm.compileFunction(body, [])();
|
||||||
|
}
|
||||||
|
|
||||||
|
function mapPinsServiceTests() {
|
||||||
|
const service = loadMapPinsService();
|
||||||
|
// 800x600 image, shown at 200% and panned so its top left corner sits at (20, 10) of the viewport.
|
||||||
|
const view = { zoom: 2, pan: { x: 20, y: 10 }, width: 800, height: 600 };
|
||||||
|
|
||||||
|
test("a spot of the viewport becomes the pixel of the image it stands for", () => {
|
||||||
|
assert.deepEqual(service.ToImagePoint({ x: 100, y: 50 }, view), { x: 40, y: 20 });
|
||||||
|
});
|
||||||
|
|
||||||
|
test("spots outside the image pin nothing", () => {
|
||||||
|
assert.equal(service.ToImagePoint({ x: 10, y: 50 }, view), null);
|
||||||
|
assert.equal(service.ToImagePoint({ x: 100, y: -5 }, view), null);
|
||||||
|
assert.equal(service.ToImagePoint({ x: 1700, y: 50 }, view), null);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("without a loaded image there is no spot to pin", () => {
|
||||||
|
assert.equal(service.ToImagePoint({ x: 100, y: 50 }, { zoom: 1, pan: { x: 0, y: 0 }, width: 0, height: 0 }), null);
|
||||||
|
assert.equal(service.ToImagePoint({ x: 100, y: 50 }, undefined), null);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("a pin lands on the same spot of the screen it was placed at", () => {
|
||||||
|
// An even spot: the image pixels of a pin are rounded, so the round trip is exact there.
|
||||||
|
const spot = service.ToImagePoint({ x: 370, y: 124 }, view);
|
||||||
|
assert.deepEqual(spot, { x: 175, y: 57 });
|
||||||
|
assert.deepEqual(service.ToScreenPoint(spot, view), { x: 370, y: 124 });
|
||||||
|
});
|
||||||
|
|
||||||
|
test("pins follow the map but keep their own size", () => {
|
||||||
|
// Only the position scales: the marker itself is drawn outside of the scaled stage.
|
||||||
|
assert.deepEqual(service.ToScreenPoint({ x: 40, y: 20 }, { ...view, zoom: 4 }), { x: 180, y: 90 });
|
||||||
|
assert.deepEqual(service.ToScreenPoint({ x: 40, y: 20 }, { ...view, pan: { x: -40, y: 0 } }), { x: 40, y: 40 });
|
||||||
|
});
|
||||||
|
|
||||||
|
test("notes of a folder are labelled with where they live", () => {
|
||||||
|
const options = service.BuildNoteOptions(
|
||||||
|
[{ _id: "note-1", title: "The Altar", folder: "folder-2" }, { _id: "note-2", title: "The Inn", folder: null }],
|
||||||
|
[{ _id: "folder-1", name: "Undercity" }, { _id: "folder-2", name: "Temple", parentFolder: "folder-1" }]
|
||||||
|
);
|
||||||
|
|
||||||
|
assert.deepEqual(options.map((option) => option.label), ["The Inn", "Undercity / Temple / The Altar"]);
|
||||||
|
assert.equal(options.find((option) => option.value === "note-1").path, "Undercity / Temple");
|
||||||
|
});
|
||||||
|
|
||||||
|
test("the picker is sorted by the label it shows, not by the bare title", () => {
|
||||||
|
const options = service.BuildNoteOptions(
|
||||||
|
[{ _id: "note-1", title: "Bridge", folder: null }, { _id: "note-2", title: "Altar", folder: "folder-1" }],
|
||||||
|
[{ _id: "folder-1", name: "Cave" }]
|
||||||
|
);
|
||||||
|
|
||||||
|
// "Altar" would lead the menu by title, but it is nowhere near it once its folder is named.
|
||||||
|
assert.deepEqual(options.map((option) => option.value), ["note-1", "note-2"]);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("a note without a title is left out of the picker", () => {
|
||||||
|
const options = service.BuildNoteOptions([{ _id: "note-1", title: " " }], []);
|
||||||
|
|
||||||
|
assert.deepEqual(options, []);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("a broken folder chain cannot loop the picker", () => {
|
||||||
|
const options = service.BuildNoteOptions(
|
||||||
|
[{ _id: "note-1", title: "The Altar", folder: "folder-1" }],
|
||||||
|
[{ _id: "folder-1", name: "One", parentFolder: "folder-2" }, { _id: "folder-2", name: "Two", parentFolder: "folder-1" }]
|
||||||
|
);
|
||||||
|
|
||||||
|
assert.equal(options[0].label, "Two / One / The Altar");
|
||||||
|
});
|
||||||
|
|
||||||
|
test("renaming a note keeps the folder path of its label", () => {
|
||||||
|
const option = { value: "note-1", title: "The Altar", path: "Undercity / Temple" };
|
||||||
|
option.title = "The Ruined Altar";
|
||||||
|
|
||||||
|
assert.equal(service.OptionLabel(option), "Undercity / Temple / The Ruined Altar");
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
function mapViewerWiringTests() {
|
||||||
|
const pane = readRepoFile("frontend", "app", "components", "viewer", "map", "MapViewerPane.vue");
|
||||||
|
const definitions = readRepoFile("frontend", "app", "services", "WindowDefinitions.js");
|
||||||
|
const windowSource = readRepoFile("frontend", "app", "components", "windows", "PinnedNoteWindow.vue");
|
||||||
|
|
||||||
|
test("right clicking the map opens the pin menu", () => {
|
||||||
|
const viewport = /<div[^>]*ref="viewport"[^>]*>/.exec(pane)?.[0];
|
||||||
|
assert.ok(viewport, "expected the map viewport element");
|
||||||
|
assert.match(viewport, /@contextmenu\.prevent="onMapContextMenu"/);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("pins are drawn in screen space and only they catch the mouse", () => {
|
||||||
|
// Inside the scaled stage the markers would shrink and grow with the map instead of staying
|
||||||
|
// where they were placed; the overlay must not take the mouse away from panning.
|
||||||
|
assert.match(pane, /class="map-pin"[^>]*:style="pinStyle\(pin\)"/);
|
||||||
|
assert.match(pane, /\.map-pins\s*\{[^}]*pointer-events:\s*none/);
|
||||||
|
assert.match(pane, /\.map-pin\s*\{[^}]*pointer-events:\s*auto/);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("a pin opens the linked note and does not start a pan", () => {
|
||||||
|
assert.match(pane, /@pointerdown\.stop/);
|
||||||
|
assert.match(pane, /@click="openPinnedNote\(pin\)"/);
|
||||||
|
assert.match(pane, /CreateWindow\('pinned_note'/);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("the pinned note window is registered and reads the note from the server", () => {
|
||||||
|
assert.match(definitions, /pinned_note:\s*\{[^}]*windows\.pinned-note[^}]*PinnedNoteWindow\.vue/s);
|
||||||
|
assert.match(windowSource, /get\(`\/note\/retrieve\/\$\{noteId\}`\)/);
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
mapPinRouteTests();
|
||||||
|
campaignNotesTests();
|
||||||
|
mapPinsServiceTests();
|
||||||
|
mapViewerWiringTests();
|
||||||
116
tests/map-viewer.test.js
Normal file
116
tests/map-viewer.test.js
Normal file
@@ -0,0 +1,116 @@
|
|||||||
|
// Tests for the map viewer adjustments of Syndria98/dragonroll#15:
|
||||||
|
// * the campaign workspace can show an anchored map where the open notes are, and the sidebar's
|
||||||
|
// notes/maps buttons switch between the two without losing either,
|
||||||
|
// * the create map window no longer snaps the scale to `min + n * step` values and insets its
|
||||||
|
// content from the window edges.
|
||||||
|
//
|
||||||
|
// `frontend/app/services/Content.js` is a Vue module and the repository root installs no
|
||||||
|
// dependencies, so it is loaded into a `node:vm` context with a minimal `ref` stub: the anchor and
|
||||||
|
// pane rules are plain state transitions and stay fully observable that way. The create map window
|
||||||
|
// checks read its template, because both requirements are about the input element itself.
|
||||||
|
//
|
||||||
|
// Run with `npm test` from the repository root, or `node --test tests/`.
|
||||||
|
|
||||||
|
const { test } = require("node:test");
|
||||||
|
const assert = require("node:assert/strict");
|
||||||
|
const fs = require("node:fs");
|
||||||
|
const path = require("node:path");
|
||||||
|
const vm = require("node:vm");
|
||||||
|
|
||||||
|
function readRepoFile(...parts) {
|
||||||
|
return fs.readFileSync(path.join(__dirname, "..", ...parts), "utf8");
|
||||||
|
}
|
||||||
|
|
||||||
|
function loadContentService() {
|
||||||
|
const source = readRepoFile("frontend", "app", "services", "Content.js");
|
||||||
|
const body = source
|
||||||
|
.replace(/import\s*\{[^}]*\}\s*from\s*['"]vue['"];?/, "")
|
||||||
|
.replace(/export\s*\{/, "return {")
|
||||||
|
.concat("\n;");
|
||||||
|
|
||||||
|
const context = vm.createContext({ ref: (value) => ({ value }) });
|
||||||
|
return vm.compileFunction(body, [], { parsingContext: context })();
|
||||||
|
}
|
||||||
|
|
||||||
|
function anchoredMapTests() {
|
||||||
|
test("the workspace starts on the open notes with no map anchored", () => {
|
||||||
|
const service = loadContentService();
|
||||||
|
assert.equal(service.ActivePane.value, "notes");
|
||||||
|
assert.equal(service.AnchoredMap.value, null);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("anchoring a map shows it instead of the notes", () => {
|
||||||
|
const service = loadContentService();
|
||||||
|
service.AnchorMap({ _id: "map-1", name: "Dungeon" });
|
||||||
|
assert.equal(service.ActivePane.value, "map");
|
||||||
|
assert.equal(service.AnchoredMap.value._id, "map-1");
|
||||||
|
});
|
||||||
|
|
||||||
|
test("switching back to the notes keeps the map anchored", () => {
|
||||||
|
const service = loadContentService();
|
||||||
|
service.AnchorMap({ _id: "map-1" });
|
||||||
|
service.SetActivePane("notes");
|
||||||
|
assert.equal(service.ActivePane.value, "notes");
|
||||||
|
assert.equal(service.AnchoredMap.value._id, "map-1");
|
||||||
|
});
|
||||||
|
|
||||||
|
test("clearing the anchor shows the notes again", () => {
|
||||||
|
const service = loadContentService();
|
||||||
|
service.AnchorMap({ _id: "map-1" });
|
||||||
|
service.ClearAnchoredMap();
|
||||||
|
assert.equal(service.AnchoredMap.value, null);
|
||||||
|
assert.equal(service.ActivePane.value, "notes");
|
||||||
|
});
|
||||||
|
|
||||||
|
test("anchoring nothing falls back to the notes", () => {
|
||||||
|
const service = loadContentService();
|
||||||
|
service.AnchorMap({ _id: "map-1" });
|
||||||
|
service.AnchorMap(null);
|
||||||
|
assert.equal(service.AnchoredMap.value, null);
|
||||||
|
assert.equal(service.ActivePane.value, "notes");
|
||||||
|
});
|
||||||
|
|
||||||
|
test("hiding a pane does not disturb the other one", () => {
|
||||||
|
const service = loadContentService();
|
||||||
|
service.AnchorMap({ _id: "map-1" });
|
||||||
|
service.SetShowContent(false);
|
||||||
|
assert.equal(service.ShowContent.value, false);
|
||||||
|
assert.equal(service.ActivePane.value, "map");
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
function createMapWindowTests() {
|
||||||
|
const source = readRepoFile("frontend", "app", "components", "windows", "CreateMapWindow.vue");
|
||||||
|
const scaleInput = /<input[^>]*v-model\.number="form\.scale"[^>]*>/.exec(source);
|
||||||
|
|
||||||
|
test("the create map window has a scale input", () => {
|
||||||
|
assert.ok(scaleInput, "expected a v-model.number=\"form.scale\" input");
|
||||||
|
});
|
||||||
|
|
||||||
|
test("the scale input accepts any decimal number", () => {
|
||||||
|
const step = /step="([^"]*)"/.exec(scaleInput[0])?.[1];
|
||||||
|
// A number input only accepts `min + n * step`, so a 0.5 step on the 0.01 minimum only
|
||||||
|
// ever offered 5.01, 5.51, 6.01... instead of the number that was typed.
|
||||||
|
assert.ok(
|
||||||
|
step === undefined || step === "any",
|
||||||
|
`the scale input must not snap values, found step="${step}"`
|
||||||
|
);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("the scale input keeps the positive minimum shared with the backend", () => {
|
||||||
|
const min = /min="([^"]*)"/.exec(scaleInput[0])?.[1];
|
||||||
|
assert.equal(min, "0.01");
|
||||||
|
});
|
||||||
|
|
||||||
|
test("the create map window insets its content with an outer margin", () => {
|
||||||
|
const body = /\.body\s*\{[^}]*\}/.exec(source)?.[0];
|
||||||
|
assert.ok(body, "expected a .body style rule");
|
||||||
|
assert.match(body, /margin:\s*[^;]*\d+px/, ".body needs an outer margin");
|
||||||
|
// Without border-box the horizontal margin is added outside the full width and the
|
||||||
|
// content overflows the window instead of being inset by it.
|
||||||
|
assert.match(body, /box-sizing:\s*border-box/, ".body needs box-sizing: border-box");
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
anchoredMapTests();
|
||||||
|
createMapWindowTests();
|
||||||
Reference in New Issue
Block a user