personal memory agent
1# Third-Party Vendor Libraries
2
3This directory contains third-party JavaScript libraries used across solstone apps.
4
5## Purpose
6
7The `vendor/` directory provides:
8- Centralized location for third-party libraries
9- Version tracking and documentation
10- Consistent access pattern for all apps
11- Local copies for reliability (no CDN dependencies)
12
13## Available Libraries
14
15### marked (v15.0.12)
16
17**Purpose**: Markdown parsing and rendering
18
19**License**: MIT (included in file header)
20
21**Source**: https://github.com/markedjs/marked
22
23**CDN Alternative**: `https://cdn.jsdelivr.net/npm/marked/marked.min.js`
24
25**Usage in App Templates**:
26```html
27<!-- Using helper function (recommended) -->
28<script src="{{ vendor_lib('marked') }}"></script>
29
30<!-- Using explicit path -->
31<script src="{{ url_for('static', filename='vendor/marked/marked.min.js') }}"></script>
32```
33
34**Example**:
35```javascript
36// Basic markdown rendering
37const html = marked.parse('# Hello World');
38
39// With options
40const html = marked.parse(markdown, {
41 breaks: true, // Convert \n to <br>
42 gfm: true, // GitHub Flavored Markdown
43 headerIds: false, // Disable auto-generated header IDs
44 mangle: false // Disable email mangling
45});
46```
47
48**Currently Used By** (legacy references):
49- `convey/templates/chat.html` (via `convey/static/marked.min.js`)
50- `convey/templates/facet_detail.html` (via CDN)
51- `convey/templates/agents.html` (via CDN)
52
53### DOMPurify (v3.4.0)
54
55**Purpose**: HTML sanitization for untrusted markdown output (defense against XSS in rendered model-emitted content).
56
57**License**: Apache-2.0 OR MPL-2.0 (dual-licensed; either license can be chosen. Compatible with AGPL-3.0-only via MPL-2.0.)
58
59**Source**: https://github.com/cure53/DOMPurify (v3.4.0 — `dist/purify.min.js`, renamed to `dompurify.min.js`)
60
61**CDN Alternative**: `https://cdn.jsdelivr.net/npm/dompurify@3.4.0/dist/purify.min.js`
62
63**Usage in App Templates**:
64```html
65<script src="{{ vendor_lib('dompurify') }}"></script>
66<script>
67 const safeHtml = DOMPurify.sanitize(marked.parse(userInput));
68</script>
69```
70
71**Example**:
72```javascript
73const dirty = 'Hello <img src=x onerror=alert(1)>';
74const clean = DOMPurify.sanitize(marked.parse(dirty));
75// clean => '<p>Hello <img src="x"></p>'
76```
77
78**Currently Used By**:
79- All apps (shell-level include via `convey/templates/app.html`)
80
81## Adding New Libraries
82
83When adding a new third-party library:
84
851. **Create subdirectory**: `vendor/{library_name}/`
862. **Add minified file**: Copy production-ready `.min.js` file
873. **Check license**: Ensure license is AGPL-compatible and included
884. **Update this manifest**: Add entry with version, purpose, and usage
895. **Test**: Verify library loads and works in development
90
91## Updating Libraries
92
93When updating a library version:
94
951. **Replace file** in vendor directory
962. **Update version** in this manifest
973. **Test all apps**: Check apps listed in "Currently Used By"
984. **Commit**: Use message format: `chore: update {library} to v{version}`
99
100## Guidelines
101
102- **Prefer local copies** over CDN for reliability and offline development
103- **Use minified versions** for production-ready performance
104- **Include licenses** either in file headers or separate LICENSE files
105- **Document usage patterns** in this manifest
106- **Track versions** to enable security updates
107- **One library per subdirectory** for clean organization