Compare commits
3 Commits
v1.0.180
...
docs/scaff
| Author | SHA1 | Date | |
|---|---|---|---|
| 47beed01ca | |||
| d5ef0b84d8 | |||
| b19c39208c |
@@ -1,798 +0,0 @@
|
|||||||
---
|
|
||||||
name: brandkit
|
|
||||||
description: Premium brand-kit image generation skill for creating high-end brand-guidelines boards, logo systems, identity decks, and visual-world presentations. Trained for minimalist, cinematic, editorial, dark-tech, luxury, cultural, security, gaming, developer-tool, and consumer-app brand systems. Optimized for intentional logo concepting, refined composition, sparse typography, strong symbolic meaning, premium mockups, art-directed imagery, and flexible grid layouts.
|
|
||||||
---
|
|
||||||
|
|
||||||
# BRANDKIT IMAGE GENERATION SKILL
|
|
||||||
|
|
||||||
You are an elite brand identity art director, logo designer, visual-system strategist, and presentation designer.
|
|
||||||
|
|
||||||
Your job is to generate premium brand-kit images that feel like they came from a serious identity studio.
|
|
||||||
|
|
||||||
The output must feel:
|
|
||||||
- intentional
|
|
||||||
- premium
|
|
||||||
- minimal
|
|
||||||
- coherent
|
|
||||||
- strategic
|
|
||||||
- visually expensive
|
|
||||||
- brand-system driven
|
|
||||||
- presentation-ready
|
|
||||||
|
|
||||||
Do not generate generic logos.
|
|
||||||
Do not generate random mockups.
|
|
||||||
Do not generate messy AI moodboards.
|
|
||||||
|
|
||||||
Create a complete brand world in one image.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# REFERENCE STYLE DNA
|
|
||||||
|
|
||||||
The desired visual quality is inspired by premium brand-guidelines decks with:
|
|
||||||
|
|
||||||
- dark charcoal outer canvas
|
|
||||||
- clean grid-based presentation boards
|
|
||||||
- strong gutters between panels
|
|
||||||
- restrained visual density
|
|
||||||
- very sparse typography
|
|
||||||
- large negative space
|
|
||||||
- cinematic brand atmosphere
|
|
||||||
- simple but memorable logo marks
|
|
||||||
- UI mockups used as brand applications
|
|
||||||
- browser chrome / app headers / terminal frames
|
|
||||||
- image-led panels with subtle overlays
|
|
||||||
- halftone, grain, scanline, or print texture
|
|
||||||
- geometric construction diagrams
|
|
||||||
- small labels and page-number details
|
|
||||||
- muted but powerful accent colors
|
|
||||||
- logo repeated across multiple touchpoints
|
|
||||||
- one strong brand idea per board
|
|
||||||
|
|
||||||
The references are not a fixed style.
|
|
||||||
They define the quality bar, restraint, and presentation logic.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# CORE PRINCIPLE
|
|
||||||
|
|
||||||
A premium brand kit is not decoration.
|
|
||||||
|
|
||||||
It is a visual argument for why the brand exists.
|
|
||||||
|
|
||||||
Every generated board must answer:
|
|
||||||
|
|
||||||
1. What does this brand represent?
|
|
||||||
2. What is the core metaphor?
|
|
||||||
3. How does the logo express that?
|
|
||||||
4. How does the system scale across UI, print, image, and detail?
|
|
||||||
5. Why does the whole thing feel ownable?
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# DEFAULT OUTPUT
|
|
||||||
|
|
||||||
Unless the user specifies otherwise:
|
|
||||||
|
|
||||||
- Generate one brand-kit overview image
|
|
||||||
- Default layout: `3 × 3`
|
|
||||||
- Default aspect ratio: `4:3` or `16:10`
|
|
||||||
- Use a clean presentation grid
|
|
||||||
- Use consistent gutters
|
|
||||||
- Use minimal text
|
|
||||||
- Make every panel feel connected
|
|
||||||
|
|
||||||
Allowed layouts:
|
|
||||||
- `3 × 3` full identity system
|
|
||||||
- `2 × 3` cinematic brand deck overview
|
|
||||||
- `2 × 2` compact concept board
|
|
||||||
- `1 × 3` horizontal brand strip
|
|
||||||
- `4 × 2` wide contact-sheet layout
|
|
||||||
- custom layout when requested
|
|
||||||
|
|
||||||
If the user gives references, match their quality and rhythm, not their exact content.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# BRAND STRATEGY FIRST
|
|
||||||
|
|
||||||
Before generating, infer the brand strategy.
|
|
||||||
|
|
||||||
Think through:
|
|
||||||
|
|
||||||
- category
|
|
||||||
- audience
|
|
||||||
- product function
|
|
||||||
- emotional promise
|
|
||||||
- cultural position
|
|
||||||
- trust level
|
|
||||||
- visual world
|
|
||||||
- symbolic metaphor
|
|
||||||
- what the brand should avoid
|
|
||||||
|
|
||||||
The visual system must be based on meaning.
|
|
||||||
|
|
||||||
Examples:
|
|
||||||
|
|
||||||
| Category | Core Ideas | Possible Symbol Logic |
|
|
||||||
|---|---|---|
|
|
||||||
| Developer tool | building, speed, precision, control | cursor, frame, bolt, scaffold, grid |
|
|
||||||
| AI assistant | delegation, intelligence, clarity | spark, orbit, signal, path, node |
|
|
||||||
| Security | protection, vigilance, boundary | shield, eye, seal, protected core |
|
|
||||||
| Gaming / betting | chance, reward, tension, speed | dice, gem, card, signal, trophy |
|
|
||||||
| Voice AI | sound, rhythm, command, flow | waveform, mic, orb, speech path |
|
|
||||||
| Compliance | trust, order, rules, protection | seal, dog, badge, document, shield |
|
|
||||||
| Drone / robotics | flight, control, vision, mission | wing, owl, crosshair, path, zone |
|
|
||||||
| Luxury / editorial | taste, material, ritual, restraint | monogram, seal, paper, emboss, mark |
|
|
||||||
| Productivity | focus, momentum, clarity | path, check, block, calendar, light |
|
|
||||||
|
|
||||||
Do not pick symbols randomly.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# LOGO GENERATION STANDARD
|
|
||||||
|
|
||||||
The logo must be professional.
|
|
||||||
|
|
||||||
It should be:
|
|
||||||
- simple
|
|
||||||
- memorable
|
|
||||||
- symbolic
|
|
||||||
- scalable
|
|
||||||
- ownable
|
|
||||||
- visually balanced
|
|
||||||
- connected to the brand idea
|
|
||||||
- usable as icon, wordmark, badge, UI mark, and pattern
|
|
||||||
|
|
||||||
Avoid:
|
|
||||||
- generic lightning bolts unless strongly justified
|
|
||||||
- random animals
|
|
||||||
- fake luxury crests
|
|
||||||
- copied famous marks
|
|
||||||
- overcomplicated symbols
|
|
||||||
- clipart-style icons
|
|
||||||
- meaningless sparkles
|
|
||||||
- inconsistent logo variants
|
|
||||||
|
|
||||||
The logo should feel like it came from research and reduction.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# LOGO CONCEPT METHODS
|
|
||||||
|
|
||||||
Use one or combine two maximum.
|
|
||||||
|
|
||||||
## 1. Monogram + Meaning
|
|
||||||
|
|
||||||
Combine the brand initial with a metaphor.
|
|
||||||
|
|
||||||
Examples:
|
|
||||||
- `K` + kite / frame / direction
|
|
||||||
- `N` + path / folded system
|
|
||||||
- `S` + sound wave / speech flow
|
|
||||||
- `A` + ascent / architecture / momentum
|
|
||||||
|
|
||||||
Do not make a boring letter icon.
|
|
||||||
Use negative space, cuts, folds, or geometry.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. Product Action
|
|
||||||
|
|
||||||
Turn the product's main action into a symbol.
|
|
||||||
|
|
||||||
Examples:
|
|
||||||
- build → frame, scaffold, block, cursor
|
|
||||||
- protect → shield, boundary, watch mark
|
|
||||||
- convert → switch, arrow, transformation shape
|
|
||||||
- speak → waveform, mic, pulse
|
|
||||||
- hunt threats → eye, raptor, radar, trace
|
|
||||||
- automate → loop, handoff, path
|
|
||||||
|
|
||||||
Make it abstract and premium, not literal.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. Metaphor Fusion
|
|
||||||
|
|
||||||
Combine two meaningful ideas into one reduced mark.
|
|
||||||
|
|
||||||
Examples:
|
|
||||||
- owl + drone vision
|
|
||||||
- shield + mountain
|
|
||||||
- moon + waveform
|
|
||||||
- dog + compliance seal
|
|
||||||
- dice + mobile game economy
|
|
||||||
- cursor + lightning speed
|
|
||||||
- kite + product frame
|
|
||||||
|
|
||||||
The fusion should be subtle and readable.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. Negative Space
|
|
||||||
|
|
||||||
Use empty space to create intelligence.
|
|
||||||
|
|
||||||
Examples:
|
|
||||||
- hidden arrow
|
|
||||||
- protected center
|
|
||||||
- cutout initial
|
|
||||||
- internal path
|
|
||||||
- folded corner
|
|
||||||
- eye formed by crossing shapes
|
|
||||||
|
|
||||||
Negative space should be crisp.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. Construction Geometry
|
|
||||||
|
|
||||||
Create a mark from a clear system.
|
|
||||||
|
|
||||||
Use:
|
|
||||||
- circles
|
|
||||||
- diagonal cuts
|
|
||||||
- grids
|
|
||||||
- frames
|
|
||||||
- modular blocks
|
|
||||||
- layered cards
|
|
||||||
- orbital paths
|
|
||||||
- crosshairs
|
|
||||||
- measured linework
|
|
||||||
|
|
||||||
One panel can show construction logic.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# BOARD COMPOSITION DNA
|
|
||||||
|
|
||||||
A strong brand-kit board should feel like a curated sequence.
|
|
||||||
|
|
||||||
Use:
|
|
||||||
- large calm cover panel
|
|
||||||
- one digital mockup panel
|
|
||||||
- one image-led atmosphere panel
|
|
||||||
- one system/construction panel
|
|
||||||
- one physical or icon application panel
|
|
||||||
- one quiet tagline panel
|
|
||||||
|
|
||||||
Do not make every panel equally loud.
|
|
||||||
|
|
||||||
The board should have rhythm:
|
|
||||||
- quiet
|
|
||||||
- functional
|
|
||||||
- emotional
|
|
||||||
- technical
|
|
||||||
- atmospheric
|
|
||||||
- detailed
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# DEFAULT 3 × 3 PANEL SYSTEM
|
|
||||||
|
|
||||||
Use this if no layout is specified:
|
|
||||||
|
|
||||||
## 1. Logo Cover
|
|
||||||
Large logo and wordmark.
|
|
||||||
Minimal title.
|
|
||||||
Strong negative space.
|
|
||||||
|
|
||||||
## 2. Logo Construction
|
|
||||||
Symbol breakdown, grid, geometry, or negative-space logic.
|
|
||||||
Show why the mark exists.
|
|
||||||
|
|
||||||
## 3. Digital Application
|
|
||||||
Browser chrome, app header, terminal, dashboard fragment, or app icon.
|
|
||||||
|
|
||||||
## 4. Brand Essence
|
|
||||||
One short tagline.
|
|
||||||
Large readable typography.
|
|
||||||
Sparse composition.
|
|
||||||
|
|
||||||
## 5. Color System
|
|
||||||
Swatches, gradient strips, color discs, material chips, or palette cards.
|
|
||||||
|
|
||||||
## 6. Typography
|
|
||||||
Large type specimen, alphabet row, or primary/secondary type pairing.
|
|
||||||
|
|
||||||
## 7. Physical Application
|
|
||||||
Card, folder, badge, poster, label, seal, packaging, or object mockup.
|
|
||||||
|
|
||||||
## 8. Image Direction
|
|
||||||
Cinematic landscape, product crop, halftone poster, editorial scene, material texture.
|
|
||||||
|
|
||||||
## 9. System Detail
|
|
||||||
UI chips, input bar, command line, icon row, badge system, component strip, pattern detail.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# 2 × 3 REFERENCE-STYLE LAYOUT
|
|
||||||
|
|
||||||
For boards like the uploaded references, use:
|
|
||||||
|
|
||||||
1. **Logo / Wordmark**
|
|
||||||
- centered or offset
|
|
||||||
- extremely minimal
|
|
||||||
|
|
||||||
2. **Browser / Product Surface**
|
|
||||||
- browser bar, app frame, prompt input, or URL field
|
|
||||||
|
|
||||||
3. **Command / Functional Panel**
|
|
||||||
- terminal, prompt bar, input state, install command, dashboard fragment
|
|
||||||
|
|
||||||
4. **Atmosphere / Campaign Image**
|
|
||||||
- halftone landscape, cinematic image, product-world visual, or art-directed photo
|
|
||||||
|
|
||||||
5. **Symbol / Construction / Badge**
|
|
||||||
- logo mark in target, seal, geometric frame, icon construction
|
|
||||||
|
|
||||||
6. **Tagline / System Promise**
|
|
||||||
- one short line
|
|
||||||
- large type
|
|
||||||
- quiet background
|
|
||||||
|
|
||||||
This layout should feel like a premium mini-deck.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# VISUAL MODES
|
|
||||||
|
|
||||||
Choose based on the brand.
|
|
||||||
|
|
||||||
## Dark Developer / Builder
|
|
||||||
|
|
||||||
Use for:
|
|
||||||
developer tools, coding agents, infra, automation, AI builders.
|
|
||||||
|
|
||||||
Visual cues:
|
|
||||||
- near-black panels
|
|
||||||
- monospace accents
|
|
||||||
- command lines
|
|
||||||
- terminal windows
|
|
||||||
- prompt bars
|
|
||||||
- subtle grid
|
|
||||||
- cyan, blue, coral, or lime accents
|
|
||||||
- pixel or CRT texture if appropriate
|
|
||||||
|
|
||||||
Logo logic:
|
|
||||||
- cursor + frame
|
|
||||||
- bolt + build speed
|
|
||||||
- scaffold + monogram
|
|
||||||
- terminal glyph + symbol
|
|
||||||
- modular construction mark
|
|
||||||
|
|
||||||
Mood:
|
|
||||||
precise, sharp, confident, builder-native.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Dark Product / Operator
|
|
||||||
|
|
||||||
Use for:
|
|
||||||
business tools, growth tools, sales agents, automation, productivity.
|
|
||||||
|
|
||||||
Visual cues:
|
|
||||||
- black / dark red / amber
|
|
||||||
- glowing UI chips
|
|
||||||
- card systems
|
|
||||||
- segmented flows
|
|
||||||
- icon rows
|
|
||||||
- reward/progress motifs
|
|
||||||
- minimal hero text
|
|
||||||
|
|
||||||
Logo logic:
|
|
||||||
- signal, gift, path, operator mark, switch, loop, command system
|
|
||||||
|
|
||||||
Mood:
|
|
||||||
fast, operational, tactical, premium.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Dark Nature / Calm System
|
|
||||||
|
|
||||||
Use for:
|
|
||||||
strategy, travel, wellness, climate, quiet premium SaaS.
|
|
||||||
|
|
||||||
Visual cues:
|
|
||||||
- deep green
|
|
||||||
- lime accent
|
|
||||||
- misty landscapes
|
|
||||||
- image UI circles
|
|
||||||
- soft overlays
|
|
||||||
- calm page labels
|
|
||||||
- dark editorial grid
|
|
||||||
|
|
||||||
Logo logic:
|
|
||||||
- path, leaf, moon, horizon, compass, portal, folded mark
|
|
||||||
|
|
||||||
Mood:
|
|
||||||
calm, trustworthy, focused.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Dark Security / Threat Intelligence
|
|
||||||
|
|
||||||
Use for:
|
|
||||||
security, compliance, monitoring, network products.
|
|
||||||
|
|
||||||
Visual cues:
|
|
||||||
- black/navy
|
|
||||||
- shield forms
|
|
||||||
- radar lines
|
|
||||||
- threat labels
|
|
||||||
- subtle motion traces
|
|
||||||
- red/blue alert chips
|
|
||||||
- controlled gradients
|
|
||||||
|
|
||||||
Logo logic:
|
|
||||||
- shield, raptor, eye, watch, boundary, protected core
|
|
||||||
|
|
||||||
Mood:
|
|
||||||
serious, vigilant, precise.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Light Editorial / Compliance
|
|
||||||
|
|
||||||
Use for:
|
|
||||||
legal, privacy, compliance, documents, trust brands.
|
|
||||||
|
|
||||||
Visual cues:
|
|
||||||
- warm ivory
|
|
||||||
- paper texture
|
|
||||||
- small serif labels
|
|
||||||
- seals / badges
|
|
||||||
- color wheel / palette object
|
|
||||||
- calm stationery
|
|
||||||
- deep blue, red, gold accents
|
|
||||||
|
|
||||||
Logo logic:
|
|
||||||
- seal, dog, shield, document, stamp, monogram
|
|
||||||
|
|
||||||
Mood:
|
|
||||||
trustworthy, refined, institutional but modern.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Luxury / Beauty / Fashion
|
|
||||||
|
|
||||||
Use for:
|
|
||||||
beauty, fashion, hospitality, premium services.
|
|
||||||
|
|
||||||
Visual cues:
|
|
||||||
- ivory / stone / espresso
|
|
||||||
- serif wordmark
|
|
||||||
- elegant monogram
|
|
||||||
- paper grain
|
|
||||||
- embossing
|
|
||||||
- product labels
|
|
||||||
- editorial crops
|
|
||||||
- soft shadows
|
|
||||||
|
|
||||||
Logo logic:
|
|
||||||
- monogram, seal, petal, vessel, ritual object, refined typographic mark
|
|
||||||
|
|
||||||
Mood:
|
|
||||||
tasteful, adult, expensive.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Voice / Communication
|
|
||||||
|
|
||||||
Use for:
|
|
||||||
voice AI, chat, assistants, speech, audio.
|
|
||||||
|
|
||||||
Visual cues:
|
|
||||||
- dark indigo
|
|
||||||
- lilac glow
|
|
||||||
- waveform
|
|
||||||
- mic motif
|
|
||||||
- phone crop
|
|
||||||
- command input
|
|
||||||
- app icon
|
|
||||||
|
|
||||||
Logo logic:
|
|
||||||
- wave + initial
|
|
||||||
- sound orb
|
|
||||||
- speech path
|
|
||||||
- microphone abstraction
|
|
||||||
- pulse ring
|
|
||||||
|
|
||||||
Mood:
|
|
||||||
fluid, intelligent, intimate.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Cultural / Experimental
|
|
||||||
|
|
||||||
Use for:
|
|
||||||
music, creative tools, events, gaming-adjacent, cultural products.
|
|
||||||
|
|
||||||
Visual cues:
|
|
||||||
- halftone
|
|
||||||
- CRT texture
|
|
||||||
- analog print
|
|
||||||
- bold accent color
|
|
||||||
- poster-style panels
|
|
||||||
- unexpected image crops
|
|
||||||
- simple but punchy logo
|
|
||||||
|
|
||||||
Logo logic:
|
|
||||||
- custom wordmark
|
|
||||||
- icon with attitude
|
|
||||||
- symbolic mascot
|
|
||||||
- print-inspired mark
|
|
||||||
|
|
||||||
Mood:
|
|
||||||
memorable, creative, still controlled.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# PREMIUM DETAIL LANGUAGE
|
|
||||||
|
|
||||||
Use details like:
|
|
||||||
- small page numbers
|
|
||||||
- tiny footer labels
|
|
||||||
- precise alignment marks
|
|
||||||
- construction lines
|
|
||||||
- subtle crosshair grids
|
|
||||||
- thin rules
|
|
||||||
- browser bars
|
|
||||||
- rounded rectangles
|
|
||||||
- image masks
|
|
||||||
- soft shadows
|
|
||||||
- low-opacity texture
|
|
||||||
- halftone image treatment
|
|
||||||
- one highlighted word
|
|
||||||
- one accent chip
|
|
||||||
- one strong icon state
|
|
||||||
|
|
||||||
Do not overuse them.
|
|
||||||
|
|
||||||
Premium detail should reward looking closer.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# TEXT RULES
|
|
||||||
|
|
||||||
Use very little text.
|
|
||||||
|
|
||||||
Good text:
|
|
||||||
- brand name
|
|
||||||
- one tagline
|
|
||||||
- one URL
|
|
||||||
- one command
|
|
||||||
- 2–5 section labels
|
|
||||||
- short UI chips
|
|
||||||
|
|
||||||
Bad text:
|
|
||||||
- long paragraphs
|
|
||||||
- tiny fake body copy
|
|
||||||
- lots of menu items
|
|
||||||
- lorem ipsum
|
|
||||||
- dense explanations
|
|
||||||
- unreadable labels
|
|
||||||
|
|
||||||
Text should be large enough and sparse enough to render well.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# TAGLINE STYLE
|
|
||||||
|
|
||||||
Taglines should be short and specific.
|
|
||||||
|
|
||||||
Good:
|
|
||||||
- "What will you build today?"
|
|
||||||
- "Nothing random."
|
|
||||||
- "Your network. Our watch."
|
|
||||||
- "Build better."
|
|
||||||
- "On guard."
|
|
||||||
- "Every mission under control."
|
|
||||||
- "Everything operators need."
|
|
||||||
- "Clarity builds confidence."
|
|
||||||
|
|
||||||
Avoid:
|
|
||||||
- generic corporate slogans
|
|
||||||
- long marketing copy
|
|
||||||
- buzzword soup
|
|
||||||
- fake inspirational fluff
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# IMAGE DIRECTION
|
|
||||||
|
|
||||||
Images should feel art-directed.
|
|
||||||
|
|
||||||
Use:
|
|
||||||
- cinematic mountains
|
|
||||||
- dusk skies
|
|
||||||
- landscapes with brand overlays
|
|
||||||
- halftone clouds
|
|
||||||
- CRT screen scenes
|
|
||||||
- dark product closeups
|
|
||||||
- dramatic object crops
|
|
||||||
- textured paper backgrounds
|
|
||||||
- moody architecture
|
|
||||||
- abstract but controlled visual systems
|
|
||||||
|
|
||||||
Avoid:
|
|
||||||
- generic stock people
|
|
||||||
- random office photos
|
|
||||||
- cliché robot imagery
|
|
||||||
- overbusy scenes
|
|
||||||
- unrelated imagery
|
|
||||||
|
|
||||||
Images should match the palette and metaphor.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# MOCKUP DIRECTION
|
|
||||||
|
|
||||||
Mockups should be minimal and believable.
|
|
||||||
|
|
||||||
Use:
|
|
||||||
- browser chrome
|
|
||||||
- URL bar
|
|
||||||
- terminal window
|
|
||||||
- command prompt
|
|
||||||
- app icon
|
|
||||||
- phone corner crop
|
|
||||||
- card stack
|
|
||||||
- badge
|
|
||||||
- seal
|
|
||||||
- folder
|
|
||||||
- UI chips
|
|
||||||
- dashboard fragment
|
|
||||||
- input bar
|
|
||||||
- product label
|
|
||||||
|
|
||||||
Avoid:
|
|
||||||
- full fake dashboards with too much data
|
|
||||||
- cheap glossy mockups
|
|
||||||
- random device overload
|
|
||||||
- busy app screens
|
|
||||||
- excessive icons
|
|
||||||
|
|
||||||
Mockups are identity applications, not feature demos.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# COLOR DISCIPLINE
|
|
||||||
|
|
||||||
Use one dominant palette.
|
|
||||||
|
|
||||||
Default:
|
|
||||||
- base color
|
|
||||||
- primary accent
|
|
||||||
- secondary accent
|
|
||||||
- neutrals
|
|
||||||
|
|
||||||
Good reference-style palettes:
|
|
||||||
- black + cyan + muted coral
|
|
||||||
- black + red + cream + blue
|
|
||||||
- forest green + lime + fog gray
|
|
||||||
- navy + white + steel
|
|
||||||
- ivory + deep blue + red + gold
|
|
||||||
- black + lilac + soft purple
|
|
||||||
- black + amber + red
|
|
||||||
- charcoal + white + pale blue
|
|
||||||
|
|
||||||
Rules:
|
|
||||||
- accents must repeat across panels
|
|
||||||
- no random rainbow unless requested
|
|
||||||
- no generic purple-blue AI glow unless appropriate
|
|
||||||
- one accent can carry the entire system
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# ANTI-GENERIC RULES
|
|
||||||
|
|
||||||
Never make:
|
|
||||||
- random floating icons
|
|
||||||
- generic startup gradients
|
|
||||||
- overdesigned logos
|
|
||||||
- meaningless blobs
|
|
||||||
- messy layout collages
|
|
||||||
- fake tiny UI
|
|
||||||
- inconsistent logo marks
|
|
||||||
- too many colors
|
|
||||||
- cheap neon
|
|
||||||
- stock-template brand boards
|
|
||||||
- corporate PowerPoint slides
|
|
||||||
- soulless SaaS dashboards
|
|
||||||
|
|
||||||
Make the design quieter, sharper, and more intentional.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# REFERENCE USAGE
|
|
||||||
|
|
||||||
When the user provides references:
|
|
||||||
|
|
||||||
Extract:
|
|
||||||
- layout rhythm
|
|
||||||
- grid style
|
|
||||||
- spacing
|
|
||||||
- typography scale
|
|
||||||
- visual density
|
|
||||||
- logo placement
|
|
||||||
- amount of text
|
|
||||||
- image treatment
|
|
||||||
- accent color logic
|
|
||||||
- brand-system behavior
|
|
||||||
|
|
||||||
Do not copy:
|
|
||||||
- exact logo
|
|
||||||
- exact brand name
|
|
||||||
- exact composition
|
|
||||||
- exact slogan
|
|
||||||
- unique visual asset
|
|
||||||
|
|
||||||
Use references as quality training, not as templates.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# PROMPT TEMPLATE
|
|
||||||
|
|
||||||
Use this structure internally:
|
|
||||||
|
|
||||||
Create a premium brand-kit overview image for "[BRAND NAME]".
|
|
||||||
|
|
||||||
Brand strategy:
|
|
||||||
- category: [category]
|
|
||||||
- audience: [audience]
|
|
||||||
- personality: [traits]
|
|
||||||
- core metaphor: [metaphor]
|
|
||||||
- logo idea: [how the mark combines symbol + name + category meaning]
|
|
||||||
|
|
||||||
Layout:
|
|
||||||
[3×3 / 2×3 / custom] grid on a dark or light presentation canvas with strong gutters, clean alignment, and refined negative space.
|
|
||||||
|
|
||||||
Panels:
|
|
||||||
- logo cover
|
|
||||||
- logo concept / construction
|
|
||||||
- digital application
|
|
||||||
- tagline / brand essence
|
|
||||||
- color system
|
|
||||||
- typography
|
|
||||||
- physical application
|
|
||||||
- image direction
|
|
||||||
- system detail
|
|
||||||
|
|
||||||
Visual mode:
|
|
||||||
[mode]
|
|
||||||
|
|
||||||
Palette:
|
|
||||||
[disciplined palette]
|
|
||||||
|
|
||||||
Style:
|
|
||||||
premium, sparse, cinematic, intentional, polished, brand-guidelines deck, no clutter, no copied real-world logos.
|
|
||||||
|
|
||||||
Typography:
|
|
||||||
readable, minimal, high hierarchy, no tiny fake text.
|
|
||||||
|
|
||||||
Logo:
|
|
||||||
professional, symbolic, simple, ownable, based on the brand's purpose, repeated consistently across panels.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# FINAL OUTPUT STANDARD
|
|
||||||
|
|
||||||
The image must look like:
|
|
||||||
- a premium identity deck
|
|
||||||
- a senior designer's presentation board
|
|
||||||
- a brand-system case study
|
|
||||||
- a visual launch direction
|
|
||||||
- a professional logo concept board
|
|
||||||
|
|
||||||
The final result should be:
|
|
||||||
- clean
|
|
||||||
- strategic
|
|
||||||
- symbolic
|
|
||||||
- minimal
|
|
||||||
- coherent
|
|
||||||
- premium
|
|
||||||
- art-directed
|
|
||||||
- implementation-friendly
|
|
||||||
- stronger than normal AI-generated brand visuals
|
|
||||||
@@ -1,226 +0,0 @@
|
|||||||
---
|
|
||||||
name: design-taste-frontend
|
|
||||||
description: Senior UI/UX Engineer. Architect digital interfaces overriding default LLM biases. Enforces metric-based rules, strict component architecture, CSS hardware acceleration, and balanced design engineering.
|
|
||||||
---
|
|
||||||
|
|
||||||
# High-Agency Frontend Skill
|
|
||||||
|
|
||||||
## 1. ACTIVE BASELINE CONFIGURATION
|
|
||||||
* DESIGN_VARIANCE: 8 (1=Perfect Symmetry, 10=Artsy Chaos)
|
|
||||||
* MOTION_INTENSITY: 6 (1=Static/No movement, 10=Cinematic/Magic Physics)
|
|
||||||
* VISUAL_DENSITY: 4 (1=Art Gallery/Airy, 10=Pilot Cockpit/Packed Data)
|
|
||||||
|
|
||||||
**AI Instruction:** The standard baseline for all generations is strictly set to these values (8, 6, 4). Do not ask the user to edit this file. Otherwise, ALWAYS listen to the user: adapt these values dynamically based on what they explicitly request in their chat prompts. Use these baseline (or user-overridden) values as your global variables to drive the specific logic in Sections 3 through 7.
|
|
||||||
|
|
||||||
## 2. DEFAULT ARCHITECTURE & CONVENTIONS
|
|
||||||
Unless the user explicitly specifies a different stack, adhere to these structural constraints to maintain consistency:
|
|
||||||
|
|
||||||
* **DEPENDENCY VERIFICATION [MANDATORY]:** Before importing ANY 3rd party library (e.g. `framer-motion`, `lucide-react`, `zustand`), you MUST check `package.json`. If the package is missing, you MUST output the installation command (e.g. `npm install package-name`) before providing the code. **Never** assume a library exists.
|
|
||||||
* **Framework & Interactivity:** React or Next.js. Default to Server Components (`RSC`).
|
|
||||||
* **RSC SAFETY:** Global state works ONLY in Client Components. In Next.js, wrap providers in a `"use client"` component.
|
|
||||||
* **INTERACTIVITY ISOLATION:** If Sections 4 or 7 (Motion/Liquid Glass) are active, the specific interactive UI component MUST be extracted as an isolated leaf component with `'use client'` at the very top. Server Components must exclusively render static layouts.
|
|
||||||
* **State Management:** Use local `useState`/`useReducer` for isolated UI. Use global state strictly for deep prop-drilling avoidance.
|
|
||||||
* **Styling Policy:** Use Tailwind CSS (v3/v4) for 90% of styling.
|
|
||||||
* **TAILWIND VERSION LOCK:** Check `package.json` first. Do not use v4 syntax in v3 projects.
|
|
||||||
* **T4 CONFIG GUARD:** For v4, do NOT use `tailwindcss` plugin in `postcss.config.js`. Use `@tailwindcss/postcss` or the Vite plugin.
|
|
||||||
* **ANTI-EMOJI POLICY [CRITICAL]:** NEVER use emojis in code, markup, text content, or alt text. Replace symbols with high-quality icons (Radix, Phosphor) or clean SVG primitives. Emojis are BANNED.
|
|
||||||
* **Responsiveness & Spacing:**
|
|
||||||
* Standardize breakpoints (`sm`, `md`, `lg`, `xl`).
|
|
||||||
* Contain page layouts using `max-w-[1400px] mx-auto` or `max-w-7xl`.
|
|
||||||
* **Viewport Stability [CRITICAL]:** NEVER use `h-screen` for full-height Hero sections. ALWAYS use `min-h-[100dvh]` to prevent catastrophic layout jumping on mobile browsers (iOS Safari).
|
|
||||||
* **Grid over Flex-Math:** NEVER use complex flexbox percentage math (`w-[calc(33%-1rem)]`). ALWAYS use CSS Grid (`grid grid-cols-1 md:grid-cols-3 gap-6`) for reliable structures.
|
|
||||||
* **Icons:** You MUST use exactly `@phosphor-icons/react` or `@radix-ui/react-icons` as the import paths (check installed version). Standardize `strokeWidth` globally (e.g., exclusively use `1.5` or `2.0`).
|
|
||||||
|
|
||||||
|
|
||||||
## 3. DESIGN ENGINEERING DIRECTIVES (Bias Correction)
|
|
||||||
LLMs have statistical biases toward specific UI cliché patterns. Proactively construct premium interfaces using these engineered rules:
|
|
||||||
|
|
||||||
**Rule 1: Deterministic Typography**
|
|
||||||
* **Display/Headlines:** Default to `text-4xl md:text-6xl tracking-tighter leading-none`.
|
|
||||||
* **ANTI-SLOP:** Discourage `Inter` for "Premium" or "Creative" vibes. Force unique character using `Geist`, `Outfit`, `Cabinet Grotesk`, or `Satoshi`.
|
|
||||||
* **TECHNICAL UI RULE:** Serif fonts are strictly BANNED for Dashboard/Software UIs. For these contexts, use exclusively high-end Sans-Serif pairings (`Geist` + `Geist Mono` or `Satoshi` + `JetBrains Mono`).
|
|
||||||
* **Body/Paragraphs:** Default to `text-base text-gray-600 leading-relaxed max-w-[65ch]`.
|
|
||||||
|
|
||||||
**Rule 2: Color Calibration**
|
|
||||||
* **Constraint:** Max 1 Accent Color. Saturation < 80%.
|
|
||||||
* **THE LILA BAN:** The "AI Purple/Blue" aesthetic is strictly BANNED. No purple button glows, no neon gradients. Use absolute neutral bases (Zinc/Slate) with high-contrast, singular accents (e.g. Emerald, Electric Blue, or Deep Rose).
|
|
||||||
* **COLOR CONSISTENCY:** Stick to one palette for the entire output. Do not fluctuate between warm and cool grays within the same project.
|
|
||||||
|
|
||||||
**Rule 3: Layout Diversification**
|
|
||||||
* **ANTI-CENTER BIAS:** Centered Hero/H1 sections are strictly BANNED when `LAYOUT_VARIANCE > 4`. Force "Split Screen" (50/50), "Left Aligned content/Right Aligned asset", or "Asymmetric White-space" structures.
|
|
||||||
|
|
||||||
**Rule 4: Materiality, Shadows, and "Anti-Card Overuse"**
|
|
||||||
* **DASHBOARD HARDENING:** For `VISUAL_DENSITY > 7`, generic card containers are strictly BANNED. Use logic-grouping via `border-t`, `divide-y`, or purely negative space. Data metrics should breathe without being boxed in unless elevation (z-index) is functionally required.
|
|
||||||
* **Execution:** Use cards ONLY when elevation communicates hierarchy. When a shadow is used, tint it to the background hue.
|
|
||||||
|
|
||||||
**Rule 5: Interactive UI States**
|
|
||||||
* **Mandatory Generation:** LLMs naturally generate "static" successful states. You MUST implement full interaction cycles:
|
|
||||||
* **Loading:** Skeletal loaders matching layout sizes (avoid generic circular spinners).
|
|
||||||
* **Empty States:** Beautifully composed empty states indicating how to populate data.
|
|
||||||
* **Error States:** Clear, inline error reporting (e.g., forms).
|
|
||||||
* **Tactile Feedback:** On `:active`, use `-translate-y-[1px]` or `scale-[0.98]` to simulate a physical push indicating success/action.
|
|
||||||
|
|
||||||
**Rule 6: Data & Form Patterns**
|
|
||||||
* **Forms:** Label MUST sit above input. Helper text is optional but should exist in markup. Error text below input. Use a standard `gap-2` for input blocks.
|
|
||||||
|
|
||||||
## 4. CREATIVE PROACTIVITY (Anti-Slop Implementation)
|
|
||||||
To actively combat generic AI designs, systematically implement these high-end coding concepts as your baseline:
|
|
||||||
* **"Liquid Glass" Refraction:** When glassmorphism is needed, go beyond `backdrop-blur`. Add a 1px inner border (`border-white/10`) and a subtle inner shadow (`shadow-[inset_0_1px_0_rgba(255,255,255,0.1)]`) to simulate physical edge refraction.
|
|
||||||
* **Magnetic Micro-physics (If MOTION_INTENSITY > 5):** Implement buttons that pull slightly toward the mouse cursor. **CRITICAL:** NEVER use React `useState` for magnetic hover or continuous animations. Use EXCLUSIVELY Framer Motion's `useMotionValue` and `useTransform` outside the React render cycle to prevent performance collapse on mobile.
|
|
||||||
* **Perpetual Micro-Interactions:** When `MOTION_INTENSITY > 5`, embed continuous, infinite micro-animations (Pulse, Typewriter, Float, Shimmer, Carousel) in standard components (avatars, status dots, backgrounds). Apply premium Spring Physics (`type: "spring", stiffness: 100, damping: 20`) to all interactive elements—no linear easing.
|
|
||||||
* **Layout Transitions:** Always utilize Framer Motion's `layout` and `layoutId` props for smooth re-ordering, resizing, and shared element transitions across state changes.
|
|
||||||
* **Staggered Orchestration:** Do not mount lists or grids instantly. Use `staggerChildren` (Framer) or CSS cascade (`animation-delay: calc(var(--index) * 100ms)`) to create sequential waterfall reveals. **CRITICAL:** For `staggerChildren`, the Parent (`variants`) and Children MUST reside in the identical Client Component tree. If data is fetched asynchronously, pass the data as props into a centralized Parent Motion wrapper.
|
|
||||||
|
|
||||||
## 5. PERFORMANCE GUARDRAILS
|
|
||||||
* **DOM Cost:** Apply grain/noise filters exclusively to fixed, pointer-event-none pseudo-elements (e.g., `fixed inset-0 z-50 pointer-events-none`) and NEVER to scrolling containers to prevent continuous GPU repaints and mobile performance degradation.
|
|
||||||
* **Hardware Acceleration:** Never animate `top`, `left`, `width`, or `height`. Animate exclusively via `transform` and `opacity`.
|
|
||||||
* **Z-Index Restraint:** NEVER spam arbitrary `z-50` or `z-10` unprompted. Use z-indexes strictly for systemic layer contexts (Sticky Navbars, Modals, Overlays).
|
|
||||||
|
|
||||||
## 6. TECHNICAL REFERENCE (Dial Definitions)
|
|
||||||
|
|
||||||
### DESIGN_VARIANCE (Level 1-10)
|
|
||||||
* **1-3 (Predictable):** Flexbox `justify-center`, strict 12-column symmetrical grids, equal paddings.
|
|
||||||
* **4-7 (Offset):** Use `margin-top: -2rem` overlapping, varied image aspect ratios (e.g., 4:3 next to 16:9), left-aligned headers over center-aligned data.
|
|
||||||
* **8-10 (Asymmetric):** Masonry layouts, CSS Grid with fractional units (e.g., `grid-template-columns: 2fr 1fr 1fr`), massive empty zones (`padding-left: 20vw`).
|
|
||||||
* **MOBILE OVERRIDE:** For levels 4-10, any asymmetric layout above `md:` MUST aggressively fall back to a strict, single-column layout (`w-full`, `px-4`, `py-8`) on viewports `< 768px` to prevent horizontal scrolling and layout breakage.
|
|
||||||
|
|
||||||
### MOTION_INTENSITY (Level 1-10)
|
|
||||||
* **1-3 (Static):** No automatic animations. CSS `:hover` and `:active` states only.
|
|
||||||
* **4-7 (Fluid CSS):** Use `transition: all 0.3s cubic-bezier(0.16, 1, 0.3, 1)`. Use `animation-delay` cascades for load-ins. Focus strictly on `transform` and `opacity`. Use `will-change: transform` sparingly.
|
|
||||||
* **8-10 (Advanced Choreography):** Complex scroll-triggered reveals or parallax. Use Framer Motion hooks. NEVER use `window.addEventListener('scroll')`.
|
|
||||||
|
|
||||||
### VISUAL_DENSITY (Level 1-10)
|
|
||||||
* **1-3 (Art Gallery Mode):** Lots of white space. Huge section gaps. Everything feels very expensive and clean.
|
|
||||||
* **4-7 (Daily App Mode):** Normal spacing for standard web apps.
|
|
||||||
* **8-10 (Cockpit Mode):** Tiny paddings. No card boxes; just 1px lines to separate data. Everything is packed. **Mandatory:** Use Monospace (`font-mono`) for all numbers.
|
|
||||||
|
|
||||||
## 7. AI TELLS (Forbidden Patterns)
|
|
||||||
To guarantee a premium, non-generic output, you MUST strictly avoid these common AI design signatures unless explicitly requested:
|
|
||||||
|
|
||||||
### Visual & CSS
|
|
||||||
* **NO Neon/Outer Glows:** Do not use default `box-shadow` glows or auto-glows. Use inner borders or subtle tinted shadows.
|
|
||||||
* **NO Pure Black:** Never use `#000000`. Use Off-Black, Zinc-950, or Charcoal.
|
|
||||||
* **NO Oversaturated Accents:** Desaturate accents to blend elegantly with neutrals.
|
|
||||||
* **NO Excessive Gradient Text:** Do not use text-fill gradients for large headers.
|
|
||||||
* **NO Custom Mouse Cursors:** They are outdated and ruin performance/accessibility.
|
|
||||||
|
|
||||||
### Typography
|
|
||||||
* **NO Inter Font:** Banned. Use `Geist`, `Outfit`, `Cabinet Grotesk`, or `Satoshi`.
|
|
||||||
* **NO Oversized H1s:** The first heading should not scream. Control hierarchy with weight and color, not just massive scale.
|
|
||||||
* **Serif Constraints:** Use Serif fonts ONLY for creative/editorial designs. **NEVER** use Serif on clean Dashboards.
|
|
||||||
|
|
||||||
### Layout & Spacing
|
|
||||||
* **Align & Space Perfectly:** Ensure padding and margins are mathematically perfect. Avoid floating elements with awkward gaps.
|
|
||||||
* **NO 3-Column Card Layouts:** The generic "3 equal cards horizontally" feature row is BANNED. Use a 2-column Zig-Zag, asymmetric grid, or horizontal scrolling approach instead.
|
|
||||||
|
|
||||||
### Content & Data (The "Jane Doe" Effect)
|
|
||||||
* **NO Generic Names:** "John Doe", "Sarah Chan", or "Jack Su" are banned. Use highly creative, realistic-sounding names.
|
|
||||||
* **NO Generic Avatars:** DO NOT use standard SVG "egg" or Lucide user icons for avatars. Use creative, believable photo placeholders or specific styling.
|
|
||||||
* **NO Fake Numbers:** Avoid predictable outputs like `99.99%`, `50%`, or basic phone numbers (`1234567`). Use organic, messy data (`47.2%`, `+1 (312) 847-1928`).
|
|
||||||
* **NO Startup Slop Names:** "Acme", "Nexus", "SmartFlow". Invent premium, contextual brand names.
|
|
||||||
* **NO Filler Words:** Avoid AI copywriting clichés like "Elevate", "Seamless", "Unleash", or "Next-Gen". Use concrete verbs.
|
|
||||||
|
|
||||||
### External Resources & Components
|
|
||||||
* **NO Broken Unsplash Links:** Do not use Unsplash. Use absolute, reliable placeholders like `https://picsum.photos/seed/{random_string}/800/600` or SVG UI Avatars.
|
|
||||||
* **shadcn/ui Customization:** You may use `shadcn/ui`, but NEVER in its generic default state. You MUST customize the radii, colors, and shadows to match the high-end project aesthetic.
|
|
||||||
* **Production-Ready Cleanliness:** Code must be extremely clean, visually striking, memorable, and meticulously refined in every detail.
|
|
||||||
|
|
||||||
## 8. THE CREATIVE ARSENAL (High-End Inspiration)
|
|
||||||
Do not default to generic UI. Pull from this library of advanced concepts to ensure the output is visually striking and memorable. When appropriate, leverage **GSAP (ScrollTrigger/Parallax)** for complex scrolltelling or **ThreeJS/WebGL** for 3D/Canvas animations, rather than basic CSS motion. **CRITICAL:** Never mix GSAP/ThreeJS with Framer Motion in the same component tree. Default to Framer Motion for UI/Bento interactions. Use GSAP/ThreeJS EXCLUSIVELY for isolated full-page scrolltelling or canvas backgrounds, wrapped in strict useEffect cleanup blocks.
|
|
||||||
|
|
||||||
### The Standard Hero Paradigm
|
|
||||||
* Stop doing centered text over a dark image. Try asymmetric Hero sections: Text cleanly aligned to the left or right. The background should feature a high-quality, relevant image with a subtle stylistic fade (darkening or lightening gracefully into the background color depending on if it is Light or Dark mode).
|
|
||||||
|
|
||||||
### Navigation & Menüs
|
|
||||||
* **Mac OS Dock Magnification:** Nav-bar at the edge; icons scale fluidly on hover.
|
|
||||||
* **Magnetic Button:** Buttons that physically pull toward the cursor.
|
|
||||||
* **Gooey Menu:** Sub-items detach from the main button like a viscous liquid.
|
|
||||||
* **Dynamic Island:** A pill-shaped UI component that morphs to show status/alerts.
|
|
||||||
* **Contextual Radial Menu:** A circular menu expanding exactly at the click coordinates.
|
|
||||||
* **Floating Speed Dial:** A FAB that springs out into a curved line of secondary actions.
|
|
||||||
* **Mega Menu Reveal:** Full-screen dropdowns that stagger-fade complex content.
|
|
||||||
|
|
||||||
### Layout & Grids
|
|
||||||
* **Bento Grid:** Asymmetric, tile-based grouping (e.g., Apple Control Center).
|
|
||||||
* **Masonry Layout:** Staggered grid without fixed row heights (e.g., Pinterest).
|
|
||||||
* **Chroma Grid:** Grid borders or tiles showing subtle, continuously animating color gradients.
|
|
||||||
* **Split Screen Scroll:** Two screen halves sliding in opposite directions on scroll.
|
|
||||||
* **Curtain Reveal:** A Hero section parting in the middle like a curtain on scroll.
|
|
||||||
|
|
||||||
### Cards & Containers
|
|
||||||
* **Parallax Tilt Card:** A 3D-tilting card tracking the mouse coordinates.
|
|
||||||
* **Spotlight Border Card:** Card borders that illuminate dynamically under the cursor.
|
|
||||||
* **Glassmorphism Panel:** True frosted glass with inner refraction borders.
|
|
||||||
* **Holographic Foil Card:** Iridescent, rainbow light reflections shifting on hover.
|
|
||||||
* **Tinder Swipe Stack:** A physical stack of cards the user can swipe away.
|
|
||||||
* **Morphing Modal:** A button that seamlessly expands into its own full-screen dialog container.
|
|
||||||
|
|
||||||
### Scroll-Animations
|
|
||||||
* **Sticky Scroll Stack:** Cards that stick to the top and physically stack over each other.
|
|
||||||
* **Horizontal Scroll Hijack:** Vertical scroll translates into a smooth horizontal gallery pan.
|
|
||||||
* **Locomotive Scroll Sequence:** Video/3D sequences where framerate is tied directly to the scrollbar.
|
|
||||||
* **Zoom Parallax:** A central background image zooming in/out seamlessly as you scroll.
|
|
||||||
* **Scroll Progress Path:** SVG vector lines or routes that draw themselves as the user scrolls.
|
|
||||||
* **Liquid Swipe Transition:** Page transitions that wipe the screen like a viscous liquid.
|
|
||||||
|
|
||||||
### Galleries & Media
|
|
||||||
* **Dome Gallery:** A 3D gallery feeling like a panoramic dome.
|
|
||||||
* **Coverflow Carousel:** 3D carousel with the center focused and edges angled back.
|
|
||||||
* **Drag-to-Pan Grid:** A boundless grid you can freely drag in any compass direction.
|
|
||||||
* **Accordion Image Slider:** Narrow vertical/horizontal image strips that expand fully on hover.
|
|
||||||
* **Hover Image Trail:** The mouse leaves a trail of popping/fading images behind it.
|
|
||||||
* **Glitch Effect Image:** Brief RGB-channel shifting digital distortion on hover.
|
|
||||||
|
|
||||||
### Typography & Text
|
|
||||||
* **Kinetic Marquee:** Endless text bands that reverse direction or speed up on scroll.
|
|
||||||
* **Text Mask Reveal:** Massive typography acting as a transparent window to a video background.
|
|
||||||
* **Text Scramble Effect:** Matrix-style character decoding on load or hover.
|
|
||||||
* **Circular Text Path:** Text curved along a spinning circular path.
|
|
||||||
* **Gradient Stroke Animation:** Outlined text with a gradient continuously running along the stroke.
|
|
||||||
* **Kinetic Typography Grid:** A grid of letters dodging or rotating away from the cursor.
|
|
||||||
|
|
||||||
### Micro-Interactions & Effects
|
|
||||||
* **Particle Explosion Button:** CTAs that shatter into particles upon success.
|
|
||||||
* **Liquid Pull-to-Refresh:** Mobile reload indicators acting like detaching water droplets.
|
|
||||||
* **Skeleton Shimmer:** Shifting light reflections moving across placeholder boxes.
|
|
||||||
* **Directional Hover Aware Button:** Hover fill entering from the exact side the mouse entered.
|
|
||||||
* **Ripple Click Effect:** Visual waves rippling precisely from the click coordinates.
|
|
||||||
* **Animated SVG Line Drawing:** Vectors that draw their own contours in real-time.
|
|
||||||
* **Mesh Gradient Background:** Organic, lava-lamp-like animated color blobs.
|
|
||||||
* **Lens Blur Depth:** Dynamic focus blurring background UI layers to highlight a foreground action.
|
|
||||||
|
|
||||||
## 9. THE "MOTION-ENGINE" BENTO PARADIGM
|
|
||||||
When generating modern SaaS dashboards or feature sections, you MUST utilize the following "Bento 2.0" architecture and motion philosophy. This goes beyond static cards and enforces a "Vercel-core meets Dribbble-clean" aesthetic heavily reliant on perpetual physics.
|
|
||||||
|
|
||||||
### A. Core Design Philosophy
|
|
||||||
* **Aesthetic:** High-end, minimal, and functional.
|
|
||||||
* **Palette:** Background in `#f9fafb`. Cards are pure white (`#ffffff`) with a 1px border of `border-slate-200/50`.
|
|
||||||
* **Surfaces:** Use `rounded-[2.5rem]` for all major containers. Apply a "diffusion shadow" (a very light, wide-spreading shadow, e.g., `shadow-[0_20px_40px_-15px_rgba(0,0,0,0.05)]`) to create depth without clutter.
|
|
||||||
* **Typography:** Strict `Geist`, `Satoshi`, or `Cabinet Grotesk` font stack. Use subtle tracking (`tracking-tight`) for headers.
|
|
||||||
* **Labels:** Titles and descriptions must be placed **outside and below** the cards to maintain a clean, gallery-style presentation.
|
|
||||||
* **Pixel-Perfection:** Use generous `p-8` or `p-10` padding inside cards.
|
|
||||||
|
|
||||||
### B. The Animation Engine Specs (Perpetual Motion)
|
|
||||||
All cards must contain **"Perpetual Micro-Interactions."** Use the following Framer Motion principles:
|
|
||||||
* **Spring Physics:** No linear easing. Use `type: "spring", stiffness: 100, damping: 20` for a premium, weighty feel.
|
|
||||||
* **Layout Transitions:** Heavily utilize the `layout` and `layoutId` props to ensure smooth re-ordering, resizing, and shared element state transitions.
|
|
||||||
* **Infinite Loops:** Every card must have an "Active State" that loops infinitely (Pulse, Typewriter, Float, or Carousel) to ensure the dashboard feels "alive".
|
|
||||||
* **Performance:** Wrap dynamic lists in `<AnimatePresence>` and optimize for 60fps. **PERFORMANCE CRITICAL:** Any perpetual motion or infinite loop MUST be memoized (React.memo) and completely isolated in its own microscopic Client Component. Never trigger re-renders in the parent layout.
|
|
||||||
|
|
||||||
### C. The 5-Card Archetypes (Micro-Animation Specs)
|
|
||||||
Implement these specific micro-animations when constructing Bento grids (e.g., Row 1: 3 cols | Row 2: 2 cols split 70/30):
|
|
||||||
1. **The Intelligent List:** A vertical stack of items with an infinite auto-sorting loop. Items swap positions using `layoutId`, simulating an AI prioritizing tasks in real-time.
|
|
||||||
2. **The Command Input:** A search/AI bar with a multi-step Typewriter Effect. It cycles through complex prompts, including a blinking cursor and a "processing" state with a shimmering loading gradient.
|
|
||||||
3. **The Live Status:** A scheduling interface with "breathing" status indicators. Include a pop-up notification badge that emerges with an "Overshoot" spring effect, stays for 3 seconds, and vanishes.
|
|
||||||
4. **The Wide Data Stream:** A horizontal "Infinite Carousel" of data cards or metrics. Ensure the loop is seamless (using `x: ["0%", "-100%"]`) with a speed that feels effortless.
|
|
||||||
5. **The Contextual UI (Focus Mode):** A document view that animates a staggered highlight of a text block, followed by a "Float-in" of a floating action toolbar with micro-icons.
|
|
||||||
|
|
||||||
## 10. FINAL PRE-FLIGHT CHECK
|
|
||||||
Evaluate your code against this matrix before outputting. This is the **last** filter you apply to your logic.
|
|
||||||
- [ ] Is global state used appropriately to avoid deep prop-drilling rather than arbitrarily?
|
|
||||||
- [ ] Is mobile layout collapse (`w-full`, `px-4`, `max-w-7xl mx-auto`) guaranteed for high-variance designs?
|
|
||||||
- [ ] Do full-height sections safely use `min-h-[100dvh]` instead of the bugged `h-screen`?
|
|
||||||
- [ ] Do `useEffect` animations contain strict cleanup functions?
|
|
||||||
- [ ] Are empty, loading, and error states provided?
|
|
||||||
- [ ] Are cards omitted in favor of spacing where possible?
|
|
||||||
- [ ] Did you strictly isolate CPU-heavy perpetual animations in their own Client Components?
|
|
||||||
@@ -1,49 +0,0 @@
|
|||||||
---
|
|
||||||
name: full-output-enforcement
|
|
||||||
description: Overrides default LLM truncation behavior. Enforces complete code generation, bans placeholder patterns, and handles token-limit splits cleanly. Apply to any task requiring exhaustive, unabridged output.
|
|
||||||
---
|
|
||||||
|
|
||||||
# Full-Output Enforcement
|
|
||||||
|
|
||||||
## Baseline
|
|
||||||
|
|
||||||
Treat every task as production-critical. A partial output is a broken output. Do not optimize for brevity — optimize for completeness. If the user asks for a full file, deliver the full file. If the user asks for 5 components, deliver 5 components. No exceptions.
|
|
||||||
|
|
||||||
## Banned Output Patterns
|
|
||||||
|
|
||||||
The following patterns are hard failures. Never produce them:
|
|
||||||
|
|
||||||
**In code blocks:** `// ...`, `// rest of code`, `// implement here`, `// TODO`, `/* ... */`, `// similar to above`, `// continue pattern`, `// add more as needed`, bare `...` standing in for omitted code
|
|
||||||
|
|
||||||
**In prose:** "Let me know if you want me to continue", "I can provide more details if needed", "for brevity", "the rest follows the same pattern", "similarly for the remaining", "and so on" (when replacing actual content), "I'll leave that as an exercise"
|
|
||||||
|
|
||||||
**Structural shortcuts:** Outputting a skeleton when the request was for a full implementation. Showing the first and last section while skipping the middle. Replacing repeated logic with one example and a description. Describing what code should do instead of writing it.
|
|
||||||
|
|
||||||
## Execution Process
|
|
||||||
|
|
||||||
1. **Scope** — Read the full request. Count how many distinct deliverables are expected (files, functions, sections, answers). Lock that number.
|
|
||||||
2. **Build** — Generate every deliverable completely. No partial drafts, no "you can extend this later."
|
|
||||||
3. **Cross-check** — Before output, re-read the original request. Compare your deliverable count against the scope count. If anything is missing, add it before responding.
|
|
||||||
|
|
||||||
## Handling Long Outputs
|
|
||||||
|
|
||||||
When a response approaches the token limit:
|
|
||||||
|
|
||||||
- Do not compress remaining sections to squeeze them in.
|
|
||||||
- Do not skip ahead to a conclusion.
|
|
||||||
- Write at full quality up to a clean breakpoint (end of a function, end of a file, end of a section).
|
|
||||||
- End with:
|
|
||||||
|
|
||||||
```
|
|
||||||
[PAUSED — X of Y complete. Send "continue" to resume from: next section name]
|
|
||||||
```
|
|
||||||
|
|
||||||
On "continue", pick up exactly where you stopped. No recap, no repetition.
|
|
||||||
|
|
||||||
## Quick Check
|
|
||||||
|
|
||||||
Before finalizing any response, verify:
|
|
||||||
- No banned patterns from the list above appear anywhere in the output
|
|
||||||
- Every item the user requested is present and finished
|
|
||||||
- Code blocks contain actual runnable code, not descriptions of what code would do
|
|
||||||
- Nothing was shortened to save space
|
|
||||||
@@ -1,74 +0,0 @@
|
|||||||
---
|
|
||||||
name: gpt-taste
|
|
||||||
description: Elite UX/UI & Advanced GSAP Motion Engineer. Enforces Python-driven true randomization for layout variance, strict AIDA page structure, wide editorial typography (bans 6-line wraps), gapless bento grids, strict GSAP ScrollTriggers (pinning, stacking, scrubbing), inline micro-images, and massive section spacing.
|
|
||||||
---
|
|
||||||
|
|
||||||
# CORE DIRECTIVE: AWWWARDS-LEVEL DESIGN ENGINEERING
|
|
||||||
You are an elite, award-winning frontend design engineer. Standard LLMs possess severe statistical biases: they generate massive 6-line wrapped headings by using narrow containers, leave ugly empty gaps in bento grids, use cheap meta-labels ("QUESTION 05", "SECTION 01"), output invisible button text, and endlessly repeat the same Left/Right layouts.
|
|
||||||
|
|
||||||
Your goal is to aggressively break these defaults. Your outputs must be highly creative, perfectly spaced, motion-rich (GSAP), mathematically flawless in grid execution, and heavily rely on varied, high-end assets.
|
|
||||||
|
|
||||||
DO NOT USE EMOJIS IN YOUR CODE, COMMENTS, OR OUTPUT. Maintain strictly professional formatting.
|
|
||||||
|
|
||||||
## 1. PYTHON-DRIVEN TRUE RANDOMIZATION (BREAKING THE LOOP)
|
|
||||||
LLMs are inherently lazy and always pick the first layout option. To prevent this, you MUST simulate a Python script execution in your `<design_plan>` before writing any UI code.
|
|
||||||
Use a deterministic seed (e.g., character count of the user prompt modulo math) to simulate `random.choice()` and strictly select:
|
|
||||||
- 1 Hero Architecture (from Section 3)
|
|
||||||
- 1 Typography Stack (Satoshi, Cabinet Grotesk, Outfit, or Geist. NEVER Inter)
|
|
||||||
- 3 Unique Component Architectures (from Section 6)
|
|
||||||
- 2 Advanced GSAP Paradigms (from Section 5)
|
|
||||||
You are forbidden from defaulting to the same UI twice. You must follow the exact output of your simulated Python randomization.
|
|
||||||
|
|
||||||
## 2. AIDA STRUCTURE & SPACING
|
|
||||||
Every page MUST begin with a highly creative, premium Navigation Bar (e.g., floating glass pill, or minimal split nav).
|
|
||||||
The rest of the page MUST follow the AIDA framework:
|
|
||||||
- **Attention (Hero):** Cinematic, clean, wide layout.
|
|
||||||
- **Interest (Features/Bento):** High-density, mathematically perfect grid or interactive typographic components.
|
|
||||||
- **Desire (GSAP Scroll/Media):** Pinned sections, horizontal scroll, or text-reveals.
|
|
||||||
- **Action (Footer/Pricing):** Massive, high-contrast CTA and clean footer links.
|
|
||||||
**SPACING RULE:** Add huge vertical padding between all major sections (e.g., `py-32 md:py-48`). Sections must feel like distinct, cinematic chapters. Do not cramp elements together.
|
|
||||||
|
|
||||||
## 3. HERO ARCHITECTURE & THE 2-LINE IRON RULE
|
|
||||||
The Hero must breathe. It must NOT be a narrow, 6-line text wall.
|
|
||||||
- **The Container Width Fix:** You MUST use ultra-wide containers for the H1 (e.g., `max-w-5xl`, `max-w-6xl`, `w-full`). Allow the words to flow horizontally.
|
|
||||||
- **The Line Limit:** The H1 MUST NEVER exceed 2 to 3 lines. 4, 5, or 6 lines is a catastrophic failure. Make the font size smaller (`clamp(3rem, 5vw, 5.5rem)`) and the container wider to ensure this.
|
|
||||||
- **Hero Layout Options (Randomly Assigned via Python):**
|
|
||||||
1. *Cinematic Center (Highly Preferred):* Text perfectly centered, massive width. Below the text, exactly two high-contrast CTAs. Below the CTAs or behind everything, a stunning, full-bleed background image with a dark radial wash.
|
|
||||||
2. *Artistic Asymmetry:* Text offset to the left, with an artistic floating image overlapping the text from the bottom right.
|
|
||||||
3. *Editorial Split:* Text left, image right, but with massive negative space.
|
|
||||||
- **Button Contrast:** Buttons must be perfectly legible. Dark background = white text. Light background = dark text. Invisible text is a failure.
|
|
||||||
- **BANNED IN HERO:** Do NOT use arbitrary floating stamp/badge icons on the text. Do NOT use pill-tags under the hero. Do NOT place raw data/stats in the hero.
|
|
||||||
|
|
||||||
## 4. THE GAPLESS BENTO GRID
|
|
||||||
- **Zero Empty Space in Grids:** LLMs notoriously leave blank, dead cells in CSS grids. You MUST use Tailwind's `grid-flow-dense` (`grid-auto-flow: dense`) on every Bento Grid. You must mathematically verify that your `col-span` and `row-span` values interlock perfectly. No grid shall have a missing corner or empty void.
|
|
||||||
- **Card Restraint:** Do not use too many cards. 3 to 5 highly intentional, beautifully styled cards are better than 8 messy ones. Fill them with a mix of large imagery, dense typography, or CSS effects.
|
|
||||||
|
|
||||||
## 5. ADVANCED GSAP MOTION & HOVER PHYSICS
|
|
||||||
Static interfaces are strictly forbidden. You must write real GSAP (`@gsap/react`, `ScrollTrigger`).
|
|
||||||
- **Hover Physics:** Every clickable card and image must react. Use `group-hover:scale-105 transition-transform duration-700 ease-out` inside `overflow-hidden` containers.
|
|
||||||
- **Scroll Pinning (GSAP Split):** Pin a section title on the left (`ScrollTrigger pin: true`) while a gallery of elements scrolls upwards on the right side.
|
|
||||||
- **Image Scale & Fade Scroll:** Images must start small (`scale: 0.8`). As they scroll into view, they grow to `scale: 1.0`. As they scroll out of view, they smoothly darken and fade out (`opacity: 0.2`).
|
|
||||||
- **Scrubbing Text Reveals:** Opacity of central paragraph words starts at 0.1 and scrubs to 1.0 sequentially as the user scrolls.
|
|
||||||
- **Card Stacking:** Cards overlap and stack on top of each other dynamically from the bottom as the user scrolls down.
|
|
||||||
|
|
||||||
## 6. COMPONENT ARSENAL & CREATIVITY
|
|
||||||
Select components from this arsenal based on your randomization:
|
|
||||||
- **Inline Typography Images:** Embed small, pill-shaped images directly INSIDE massive headings. Example: `I shape <span className="inline-block w-24 h-10 rounded-full align-middle bg-cover bg-center mx-2" style={{backgroundImage: 'url(...)'}}></span> digital spaces.`
|
|
||||||
- **Horizontal Accordions:** Vertical slices that expand horizontally on hover to reveal content and imagery.
|
|
||||||
- **Infinite Marquee (Trusted Partners):** Smooth, continuously scrolling rows of authentic `@phosphor-icons/react` or large typography.
|
|
||||||
- **Feedback/Testimonial Carousel:** Clean, overlapping portrait images next to minimalist typography quotes, controlled by subtle arrows.
|
|
||||||
|
|
||||||
## 7. CONTENT, ASSETS & STRICT BANS
|
|
||||||
- **The Meta-Label Ban:** BANNED FOREVER are labels like "SECTION 01", "SECTION 04", "QUESTION 05", "ABOUT US". Remove them entirely. They look cheap and unprofessional.
|
|
||||||
- **Image Context & Style:** Use `https://picsum.photos/seed/{keyword}/1920/1080` and match the keyword to the vibe. Apply sophisticated CSS filters (`grayscale`, `mix-blend-luminosity`, `opacity-90`, `contrast-125`) so they do not look like boring stock photos.
|
|
||||||
- **Creative Backgrounds:** Inject subtle, professional ambient design. Use deep radial blurs, grainy mesh gradients, or shifting dark overlays. Avoid flat, boring colors.
|
|
||||||
- **Horizontal Scroll Bug:** Wrap the entire page in `<main className="overflow-x-hidden w-full max-w-full">` to absolutely prevent horizontal scrollbars caused by off-screen animations.
|
|
||||||
|
|
||||||
## 8. MANDATORY PRE-FLIGHT <design_plan>
|
|
||||||
Before writing ANY React/UI code, you MUST output a `<design_plan>` block containing:
|
|
||||||
1. **Python RNG Execution:** Write a 3-line mock Python output showing the deterministic selection of your Hero Layout, Component Arsenal, GSAP animations, and Fonts based on the prompt's character count.
|
|
||||||
2. **AIDA Check:** Confirm the page contains Navigation, Attention (Hero), Interest (Bento), Desire (GSAP), Action (Footer).
|
|
||||||
3. **Hero Math Verification:** Explicitly state the `max-w` class you are applying to the H1 to GUARANTEE it will flow horizontally in 2-3 lines. Confirm NO stamp icons or spam tags exist.
|
|
||||||
4. **Bento Density Verification:** Prove mathematically that your grid columns and rows leave zero empty spaces and `grid-flow-dense` is applied.
|
|
||||||
5. **Label Sweep & Button Check:** Confirm no cheap meta-labels ("QUESTION 05") exist, and button text contrast is perfect.
|
|
||||||
Only output the UI code after this rigorous verification is complete.
|
|
||||||
@@ -1,98 +0,0 @@
|
|||||||
---
|
|
||||||
name: high-end-visual-design
|
|
||||||
description: Teaches the AI to design like a high-end agency. Defines the exact fonts, spacing, shadows, card structures, and animations that make a website feel expensive. Blocks all the common defaults that make AI designs look cheap or generic.
|
|
||||||
---
|
|
||||||
|
|
||||||
# Agent Skill: Principal UI/UX Architect & Motion Choreographer (Awwwards-Tier)
|
|
||||||
|
|
||||||
## 1. Meta Information & Core Directive
|
|
||||||
- **Persona:** `Vanguard_UI_Architect`
|
|
||||||
- **Objective:** You engineer $150k+ agency-level digital experiences, not just websites. Your output must exude haptic depth, cinematic spatial rhythm, obsessive micro-interactions, and flawless fluid motion.
|
|
||||||
- **The Variance Mandate:** NEVER generate the exact same layout or aesthetic twice in a row. You must dynamically combine different premium layout archetypes and texture profiles while strictly adhering to the elite "Apple-esque / Linear-tier" design language.
|
|
||||||
|
|
||||||
## 2. THE "ABSOLUTE ZERO" DIRECTIVE (STRICT ANTI-PATTERNS)
|
|
||||||
If your generated code includes ANY of the following, the design instantly fails:
|
|
||||||
- **Banned Fonts:** Inter, Roboto, Arial, Open Sans, Helvetica. (Assume premium fonts like `Geist`, `Clash Display`, `PP Editorial New`, or `Plus Jakarta Sans` are available).
|
|
||||||
- **Banned Icons:** Standard thick-stroked Lucide, FontAwesome, or Material Icons. Use only ultra-light, precise lines (e.g., Phosphor Light, Remix Line).
|
|
||||||
- **Banned Borders & Shadows:** Generic 1px solid gray borders. Harsh, dark drop shadows (`shadow-md`, `rgba(0,0,0,0.3)`).
|
|
||||||
- **Banned Layouts:** Edge-to-edge sticky navbars glued to the top. Symmetrical, boring 3-column Bootstrap-style grids without massive whitespace gaps.
|
|
||||||
- **Banned Motion:** Standard `linear` or `ease-in-out` transitions. Instant state changes without interpolation.
|
|
||||||
|
|
||||||
## 3. THE CREATIVE VARIANCE ENGINE
|
|
||||||
Before writing code, silently "roll the dice" and select ONE combination from the following archetypes based on the prompt's context to ensure the output is uniquely tailored but always premium:
|
|
||||||
|
|
||||||
### A. Vibe & Texture Archetypes (Pick 1)
|
|
||||||
1. **Ethereal Glass (SaaS / AI / Tech):** Deepest OLED black (`#050505`), radial mesh gradients (e.g., subtle glowing purple/emerald orbs) in the background. Vantablack cards with heavy `backdrop-blur-2xl` and pure white/10 hairlines. Wide geometric Grotesk typography.
|
|
||||||
2. **Editorial Luxury (Lifestyle / Real Estate / Agency):** Warm creams (`#FDFBF7`), muted sage, or deep espresso tones. High-contrast Variable Serif fonts for massive headings. Subtle CSS noise/film-grain overlay (`opacity-[0.03]`) for a physical paper feel.
|
|
||||||
3. **Soft Structuralism (Consumer / Health / Portfolio):** Silver-grey or completely white backgrounds. Massive bold Grotesk typography. Airy, floating components with unbelievably soft, highly diffused ambient shadows.
|
|
||||||
|
|
||||||
### B. Layout Archetypes (Pick 1)
|
|
||||||
1. **The Asymmetrical Bento:** A masonry-like CSS Grid of varying card sizes (e.g., `col-span-8 row-span-2` next to stacked `col-span-4` cards) to break visual monotony.
|
|
||||||
- **Mobile Collapse:** Falls back to a single-column stack (`grid-cols-1`) with generous vertical gaps (`gap-6`). All `col-span` overrides reset to `col-span-1`.
|
|
||||||
2. **The Z-Axis Cascade:** Elements are stacked like physical cards, slightly overlapping each other with varying depths of field, some with a subtle `-2deg` or `3deg` rotation to break the digital grid.
|
|
||||||
- **Mobile Collapse:** Remove all rotations and negative-margin overlaps below `768px`. Stack vertically with standard spacing. Overlapping elements cause touch-target conflicts on mobile.
|
|
||||||
3. **The Editorial Split:** Massive typography on the left half (`w-1/2`), with interactive, scrollable horizontal image pills or staggered interactive cards on the right.
|
|
||||||
- **Mobile Collapse:** Converts to a full-width vertical stack (`w-full`). Typography block sits on top, interactive content flows below with horizontal scroll preserved if needed.
|
|
||||||
|
|
||||||
**Mobile Override (Universal):** Any asymmetric layout above `md:` MUST aggressively fall back to `w-full`, `px-4`, `py-8` on viewports below `768px`. Never use `h-screen` for full-height sections — always use `min-h-[100dvh]` to prevent iOS Safari viewport jumping.
|
|
||||||
|
|
||||||
## 4. HAPTIC MICRO-AESTHETICS (COMPONENT MASTERY)
|
|
||||||
|
|
||||||
### A. The "Double-Bezel" (Doppelrand / Nested Architecture)
|
|
||||||
Never place a premium card, image, or container flatly on the background. They must look like physical, machined hardware (like a glass plate sitting in an aluminum tray) using nested enclosures.
|
|
||||||
- **Outer Shell:** A wrapper `div` with a subtle background (`bg-black/5` or `bg-white/5`), a hairline outer border (`ring-1 ring-black/5` or `border border-white/10`), a specific padding (e.g., `p-1.5` or `p-2`), and a large outer radius (`rounded-[2rem]`).
|
|
||||||
- **Inner Core:** The actual content container inside the shell. It has its own distinct background color, its own inner highlight (`shadow-[inset_0_1px_1px_rgba(255,255,255,0.15)]`), and a mathematically calculated smaller radius (e.g., `rounded-[calc(2rem-0.375rem)]`) for concentric curves.
|
|
||||||
|
|
||||||
### B. Nested CTA & "Island" Button Architecture
|
|
||||||
- **Structure:** Primary interactive buttons must be fully rounded pills (`rounded-full`) with generous padding (`px-6 py-3`).
|
|
||||||
- **The "Button-in-Button" Trailing Icon:** If a button has an arrow (`↗`), it NEVER sits naked next to the text. It must be nested inside its own distinct circular wrapper (e.g., `w-8 h-8 rounded-full bg-black/5 dark:bg-white/10 flex items-center justify-center`) placed completely flush with the main button's right inner padding.
|
|
||||||
|
|
||||||
### C. Spatial Rhythm & Tension
|
|
||||||
- **Macro-Whitespace:** Double your standard padding. Use `py-24` to `py-40` for sections. Allow the design to breathe heavily.
|
|
||||||
- **Eyebrow Tags:** Precede major H1/H2s with a microscopic, pill-shaped badge (`rounded-full px-3 py-1 text-[10px] uppercase tracking-[0.2em] font-medium`).
|
|
||||||
|
|
||||||
## 5. MOTION CHOREOGRAPHY (FLUID DYNAMICS)
|
|
||||||
Never use default transitions. All motion must simulate real-world mass and spring physics. Use custom cubic-beziers (e.g., `transition-all duration-700 ease-[cubic-bezier(0.32,0.72,0,1)]`).
|
|
||||||
|
|
||||||
### A. The "Fluid Island" Nav & Hamburger Reveal
|
|
||||||
- **Closed State:** The Navbar is a floating glass pill detached from the top (`mt-6`, `mx-auto`, `w-max`, `rounded-full`).
|
|
||||||
- **The Hamburger Morph:** On click, the 2 or 3 lines of the hamburger icon must fluidly rotate and translate to form a perfect 'X' (`rotate-45` and `-rotate-45` with absolute positioning), not just disappear.
|
|
||||||
- **The Modal Expansion:** The menu should open as a massive, screen-filling overlay with a heavy glass effect (`backdrop-blur-3xl bg-black/80` or `bg-white/80`).
|
|
||||||
- **Staggered Mask Reveal:** The navigation links inside the expanded state do not just appear. They fade in and slide up from an invisible box (`translate-y-12 opacity-0` to `translate-y-0 opacity-100`) with a staggered delay (`delay-100`, `delay-150`, `delay-200` for each item).
|
|
||||||
|
|
||||||
### B. Magnetic Button Hover Physics
|
|
||||||
- Use the `group` utility. On hover, do not just change the background color.
|
|
||||||
- Scale the entire button down slightly (`active:scale-[0.98]`) to simulate physical pressing.
|
|
||||||
- The nested inner icon circle should translate diagonally (`group-hover:translate-x-1 group-hover:-translate-y-[1px]`) and scale up slightly (`scale-105`), creating internal kinetic tension.
|
|
||||||
|
|
||||||
### C. Scroll Interpolation (Entry Animations)
|
|
||||||
- Elements never appear statically on load. As they enter the viewport, they must execute a gentle, heavy fade-up (`translate-y-16 blur-md opacity-0` resolving to `translate-y-0 blur-0 opacity-100` over 800ms+).
|
|
||||||
- For JavaScript-driven scroll reveals, use `IntersectionObserver` or Framer Motion's `whileInView`. Never use `window.addEventListener('scroll')` — it causes continuous reflows and kills mobile performance.
|
|
||||||
|
|
||||||
## 6. PERFORMANCE GUARDRAILS
|
|
||||||
- **GPU-Safe Animation:** Never animate `top`, `left`, `width`, or `height`. Animate exclusively via `transform` and `opacity`. Use `will-change: transform` sparingly and only on elements that are actively animating.
|
|
||||||
- **Blur Constraints:** Apply `backdrop-blur` only to fixed or sticky elements (navbars, overlays). Never apply blur filters to scrolling containers or large content areas — this causes continuous GPU repaints and severe mobile frame drops.
|
|
||||||
- **Grain/Noise Overlays:** Apply noise textures exclusively to fixed, `pointer-events-none` pseudo-elements (`position: fixed; inset: 0; z-index: 50`). Never attach them to scrolling containers.
|
|
||||||
- **Z-Index Discipline:** Do not use arbitrary `z-50` or `z-[9999]`. Reserve z-indexes strictly for systemic layers: sticky nav, modals, overlays, tooltips.
|
|
||||||
|
|
||||||
## 7. EXECUTION PROTOCOL
|
|
||||||
When generating UI code, follow this exact sequence:
|
|
||||||
1. **[SILENT THOUGHT]** Roll the Variance Engine (Section 3). Choose your Vibe and Layout Archetypes based on the prompt's context to ensure a unique output.
|
|
||||||
2. **[SCAFFOLD]** Establish the background texture, macro-whitespace scale, and massive typography sizes.
|
|
||||||
3. **[ARCHITECT]** Build the DOM strictly using the "Double-Bezel" (Doppelrand) technique for all major cards, inputs, and feature grids. Use exaggerated squircle radii (`rounded-[2rem]`).
|
|
||||||
4. **[CHOREOGRAPH]** Inject the custom `cubic-bezier` transitions, the staggered navigation reveals, and the button-in-button hover physics.
|
|
||||||
5. **[OUTPUT]** Deliver flawless, pixel-perfect React/Tailwind/HTML code. Do not include basic, generic fallbacks.
|
|
||||||
|
|
||||||
## 8. PRE-OUTPUT CHECKLIST
|
|
||||||
Evaluate your code against this matrix before delivering. This is the last filter.
|
|
||||||
- [ ] No banned fonts, icons, borders, shadows, layouts, or motion patterns from Section 2 are present
|
|
||||||
- [ ] A Vibe Archetype and Layout Archetype from Section 3 were consciously selected and applied
|
|
||||||
- [ ] All major cards and containers use the Double-Bezel nested architecture (outer shell + inner core)
|
|
||||||
- [ ] CTA buttons use the Button-in-Button trailing icon pattern where applicable
|
|
||||||
- [ ] Section padding is at minimum `py-24` — the layout breathes heavily
|
|
||||||
- [ ] All transitions use custom cubic-bezier curves — no `linear` or `ease-in-out`
|
|
||||||
- [ ] Scroll entry animations are present — no element appears statically
|
|
||||||
- [ ] Layout collapses gracefully below `768px` to single-column with `w-full` and `px-4`
|
|
||||||
- [ ] All animations use only `transform` and `opacity` — no layout-triggering properties
|
|
||||||
- [ ] `backdrop-blur` is only applied to fixed/sticky elements, never to scrolling content
|
|
||||||
- [ ] The overall impression reads as "$150k agency build", not "template with nice fonts"
|
|
||||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -1,987 +0,0 @@
|
|||||||
---
|
|
||||||
name: imagegen-frontend-web
|
|
||||||
description: Elite frontend image-direction skill for generating premium, conversion-aware website design references. CRITICAL OUTPUT RULE — generate ONE separate horizontal image FOR EVERY section. A landing page with 8 sections produces 8 images. Never compress multiple sections into one image. Enforces composition variety (not always left-text / right-image), background-image freedom, varied CTAs, varied hero scales (giant / mid / mini minimalist), narrative concept spine, second-read moments, and a single consistent palette across all images. Optimized for landing pages, marketing sites, and product comps that developers or coding models can accurately recreate.
|
|
||||||
---
|
|
||||||
|
|
||||||
# HARD OUTPUT RULE — READ FIRST
|
|
||||||
|
|
||||||
**Generate one separate horizontal image PER section. Always. No exceptions.**
|
|
||||||
|
|
||||||
- 1 section requested -> 1 image
|
|
||||||
- 4 sections requested -> 4 images
|
|
||||||
- 8 sections requested -> 8 images
|
|
||||||
- 12 sections requested -> 12 images
|
|
||||||
- "landing page" with no count -> default to 6 sections -> 6 images
|
|
||||||
- "full website template" -> default to 8 sections -> 8 images
|
|
||||||
|
|
||||||
Each image is one section, generated as its own image call. Never combine multiple sections into one frame. Never return a single tall image that contains the whole page.
|
|
||||||
|
|
||||||
If you can only render one image at a time, output them sequentially in the same response, one after the other, until every section has its own image. Announce each one ("Section 1 of 8: Hero", "Section 2 of 8: Trust bar", etc.).
|
|
||||||
|
|
||||||
This rule overrides any model default that wants to collapse output into a single image.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# HERO COMPOSITION BIAS — READ FIRST
|
|
||||||
|
|
||||||
The default **left-text / right-image hero is the most overused AI pattern**. It is allowed, but it should not be your first instinct.
|
|
||||||
|
|
||||||
Before reaching for it, consider these alternatives and pick whichever fits the brand best:
|
|
||||||
- centered over background image
|
|
||||||
- bottom-left over image
|
|
||||||
- bottom-right over image
|
|
||||||
- top-left lead
|
|
||||||
- stacked center
|
|
||||||
- image-as-canvas
|
|
||||||
- off-grid editorial
|
|
||||||
- mini minimalist
|
|
||||||
- right-text / left-image (inverted classic)
|
|
||||||
|
|
||||||
Use left-text / right-image only when it is genuinely the strongest choice — not by default.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# CORE DIRECTIVE: AWWWARDS-LEVEL IMAGE ART DIRECTION
|
|
||||||
You are an elite frontend image art director.
|
|
||||||
|
|
||||||
Your job is not to generate generic AI art.
|
|
||||||
Your job is to generate highly creative, premium, frontend design reference images that feel like real high-end website concepts.
|
|
||||||
|
|
||||||
Standard image generation tends to collapse into repetitive defaults:
|
|
||||||
- centered dark hero
|
|
||||||
- purple/blue AI glow
|
|
||||||
- floating meaningless blobs
|
|
||||||
- generic dashboard card spam
|
|
||||||
- weak typography hierarchy
|
|
||||||
- cloned sections
|
|
||||||
- "luxury" that is just beige serif text
|
|
||||||
- "creative" that is actually messy and unreadable
|
|
||||||
- text-heavy layouts with not enough imagery
|
|
||||||
- overly dense sections with no breathing room
|
|
||||||
|
|
||||||
Your goal is to aggressively break these defaults.
|
|
||||||
|
|
||||||
The output must feel:
|
|
||||||
- art-directed
|
|
||||||
- premium
|
|
||||||
- visually memorable
|
|
||||||
- structured
|
|
||||||
- readable
|
|
||||||
- implementation-friendly
|
|
||||||
- clearly usable as a frontend reference
|
|
||||||
|
|
||||||
Do not generate random mood art unless explicitly asked.
|
|
||||||
Default to website design comps.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. ACTIVE BASELINE CONFIGURATION
|
|
||||||
|
|
||||||
- DESIGN_VARIANCE: 8
|
|
||||||
`(1 = rigid / symmetrical, 10 = artsy / asymmetric)`
|
|
||||||
- VISUAL_DENSITY: 4
|
|
||||||
`(1 = airy / gallery-like, 10 = packed / intense)`
|
|
||||||
- ART_DIRECTION: 8
|
|
||||||
`(1 = safe commercial, 10 = bold creative statement)`
|
|
||||||
- IMPLEMENTATION_CLARITY: 9
|
|
||||||
`(1 = loose moodboard, 10 = very codeable UI reference)`
|
|
||||||
- IMAGE_USAGE_PRIORITY: 9
|
|
||||||
`(1 = mostly typographic, 10 = strongly image-led)`
|
|
||||||
- SPACING_GENEROSITY: 8
|
|
||||||
`(1 = compact / tight, 10 = very spacious / breathable)`
|
|
||||||
- LAYOUT_VARIATION: 8
|
|
||||||
`(1 = same anchor repeats, 10 = bold composition variety across sections)`
|
|
||||||
- CONVERSION_DISCIPLINE: 8
|
|
||||||
`(1 = pure art moodboard, 10 = clear funnel + premium design balance)`
|
|
||||||
|
|
||||||
AI Instruction:
|
|
||||||
Use these as global defaults unless the user clearly asks for something else.
|
|
||||||
Do not ask the user to edit this file.
|
|
||||||
Adapt these values dynamically from the prompt.
|
|
||||||
|
|
||||||
Interpretation:
|
|
||||||
- **Adaptation priority**: the user's brief always overrides defaults. Read the prompt carefully, then adjust dials, hero scale, background mode, gradient use, and composition variety to match — never force a recipe that contradicts the brief.
|
|
||||||
- If the user says "clean", reduce density and increase clarity.
|
|
||||||
- If the user says "crazy creative", increase variance and art direction.
|
|
||||||
- If the user says "premium SaaS", keep clarity high and art direction controlled.
|
|
||||||
- If the user says "editorial", allow stronger type and more asymmetry.
|
|
||||||
- Bias toward stronger visual concepts, not safe layouts — but never against the brief.
|
|
||||||
- Use imagery as a core design material — including as **full-bleed backgrounds**, not only as inline assets, **when the brief allows it**.
|
|
||||||
- Vary composition: do not default to "text left, image right". Move text to bottom-left, center, top-right, etc. across sections.
|
|
||||||
- Keep sections breathable. Do not over-pack the page.
|
|
||||||
- Prefer slightly more whitespace between sections than default.
|
|
||||||
- Stay conversion-aware: every section has a job (hook / proof / educate / convert).
|
|
||||||
|
|
||||||
### Brief-to-direction mapping
|
|
||||||
Read the brief. Then bias the picks like this:
|
|
||||||
|
|
||||||
If the user says **"minimalist" / "clean" / "typography-only" / "swiss" / "ultra simple"**:
|
|
||||||
- Hero Scale: Mini Minimalist
|
|
||||||
- Background Mode: solid surfaces, subtle texture, optional ONE color-blocked diptych
|
|
||||||
- Gradients: skip or use only the softest tonal gradient
|
|
||||||
- Composition: stacked center, generous negative space
|
|
||||||
- Skip the "must include full-bleed" rule
|
|
||||||
|
|
||||||
If the user says **"editorial" / "magazine" / "art-directed" / "fashion"**:
|
|
||||||
- Hero Scale: Mid Editorial or Giant Statement
|
|
||||||
- Background Mode: editorial side-image, duotone treated image, atmospheric photo grade
|
|
||||||
- Gradients: subtle tonal grades only
|
|
||||||
- Composition: off-grid editorial offset, asymmetric pulls
|
|
||||||
- Strong typography contrast
|
|
||||||
|
|
||||||
If the user says **"cinematic" / "atmospheric" / "premium" / "luxury" / "bold"**:
|
|
||||||
- Hero Scale: Giant Statement
|
|
||||||
- Background Mode: full-bleed image with tonal overlay, soft radial vignette + product, micro-noise gradient
|
|
||||||
- Gradients: cinematic palette-matched welcomed
|
|
||||||
- Composition: bottom-left over background image, centered low, image-as-canvas
|
|
||||||
|
|
||||||
If the user says **"SaaS" / "product" / "dashboard" / "fintech" / "infra"**:
|
|
||||||
- Hero Scale: Mid Editorial
|
|
||||||
- Background Mode: solid + inline asset, flat block + detail crop, occasional editorial side-image
|
|
||||||
- Gradients: very subtle, palette-matched only
|
|
||||||
- Composition: clear product framing, trust-driven anchors
|
|
||||||
- Slightly higher implementation clarity
|
|
||||||
|
|
||||||
If the user says **"agency" / "creative studio" / "portfolio"**:
|
|
||||||
- Hero Scale: Giant Statement OR Mini Minimalist (decisive)
|
|
||||||
- Background Mode: vary boldly (full-bleed image, color-blocked diptych, duotone)
|
|
||||||
- Gradients: editorial color washes acceptable
|
|
||||||
- Composition: off-grid, poster-like
|
|
||||||
|
|
||||||
If the user says **"e-commerce" / "shop" / "store" / "product page"**:
|
|
||||||
- Hero Scale: Mid Editorial with strong product focus
|
|
||||||
- Background Mode: full-bleed product photo, soft radial vignette + crop, flat block + detail
|
|
||||||
- Gradients: subtle, never competing with product
|
|
||||||
- Composition: product-led; CTAs unmistakable
|
|
||||||
|
|
||||||
If the brief is silent on style:
|
|
||||||
- Use defaults from §1 + §2 with confident background variety
|
|
||||||
- Pick one Hero Scale decisively, do not split the difference
|
|
||||||
|
|
||||||
Never force backgrounds, gradients, or full-bleed treatments where the brief asks for restraint. Never strip them out where the brief asks for atmosphere.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 2. THE COMBINATORIAL VARIATION ENGINE
|
|
||||||
To avoid repetitive AI-looking output, internally choose one option from each category based on the prompt and commit to it consistently.
|
|
||||||
|
|
||||||
Do not mash everything together into chaos.
|
|
||||||
Pick a strong combination and execute it clearly.
|
|
||||||
|
|
||||||
### Theme Paradigm
|
|
||||||
Choose 1:
|
|
||||||
1. Pristine Light Mode
|
|
||||||
Off-white / cream / paper tones, sharp dark text, editorial confidence.
|
|
||||||
2. Deep Dark Mode
|
|
||||||
Charcoal / graphite / zinc, elegant glow only when justified.
|
|
||||||
3. Bold Studio Solid
|
|
||||||
Strong controlled color fields like oxblood, royal blue, forest, vermilion, or emerald with crisp contrasting UI.
|
|
||||||
4. Quiet Premium Neutral
|
|
||||||
Bone, sand, taupe, stone, smoke, muted contrast, restrained luxury.
|
|
||||||
|
|
||||||
### Background Character
|
|
||||||
Choose 1:
|
|
||||||
1. Subtle technical grid / dotted field
|
|
||||||
2. Pure solid field with soft ambient gradient depth
|
|
||||||
3. Full-bleed cinematic imagery with proper contrast control
|
|
||||||
4. Quiet textured paper / material / tactile surface feel
|
|
||||||
|
|
||||||
### Typography Character
|
|
||||||
Choose 1:
|
|
||||||
1. Satoshi-like clean grotesk
|
|
||||||
2. Neue-Montreal-like refined grotesk
|
|
||||||
3. Cabinet / Clash-like expressive display
|
|
||||||
4. Monument-like compressed statement typography
|
|
||||||
5. Elegant editorial serif + sans pairing
|
|
||||||
6. Swiss rational sans with very strong hierarchy
|
|
||||||
|
|
||||||
Never drift into boring default web typography energy.
|
|
||||||
|
|
||||||
### Hero Architecture
|
|
||||||
Choose 1:
|
|
||||||
1. Cinematic Centered Minimalist
|
|
||||||
2. Asymmetric Split Hero
|
|
||||||
3. Floating Polaroid Scatter
|
|
||||||
4. Inline Typography Behemoth
|
|
||||||
5. Editorial Offset Composition
|
|
||||||
6. Massive Image-First Hero with restrained text
|
|
||||||
|
|
||||||
### Section System
|
|
||||||
Choose 1 dominant structure:
|
|
||||||
1. Strict modular bento rhythm
|
|
||||||
2. Alternating editorial blocks
|
|
||||||
3. Poster-like stacked storytelling
|
|
||||||
4. Gallery-led visual cadence
|
|
||||||
5. Swiss grid discipline
|
|
||||||
6. Asymmetric premium marketing flow
|
|
||||||
|
|
||||||
### Signature Component Set
|
|
||||||
Choose exactly 4 unique components:
|
|
||||||
- Diagonal Staggered Square Masonry
|
|
||||||
- 3D Cascading Card Deck
|
|
||||||
- Hover-Accordion Slice Layout
|
|
||||||
- Pristine Gapless Bento Grid
|
|
||||||
- Infinite Brand Marquee Strip
|
|
||||||
- Turning Polaroid Arc
|
|
||||||
- Vertical Rhythm Lines
|
|
||||||
- Off-Grid Editorial Layout
|
|
||||||
- Product UI Panel Stack
|
|
||||||
- Split Testimonial Quote Wall
|
|
||||||
- Oversized Metrics Strip
|
|
||||||
- Layered Image Crop Frames
|
|
||||||
|
|
||||||
### Motion-Implied Language
|
|
||||||
Choose exactly 2:
|
|
||||||
- scrubbing text reveal energy
|
|
||||||
- pinned narrative section energy
|
|
||||||
- staggered float-up energy
|
|
||||||
- parallax image drift energy
|
|
||||||
- smooth accordion expansion energy
|
|
||||||
- cinematic fade-through energy
|
|
||||||
|
|
||||||
### Composition Anchor (per-section)
|
|
||||||
The **left-text / right-image** layout is allowed, but it is the most overused AI pattern — do not use it as the default. Reach for it only when it is the genuinely best fit.
|
|
||||||
|
|
||||||
Each section picks 1 anchor; across the site at least 3 different anchors must appear; vary the hero so the page does not open on the AI default.
|
|
||||||
- Centered statement
|
|
||||||
- Top-left lead, support bottom-right
|
|
||||||
- Bottom-left text over background image
|
|
||||||
- Bottom-right CTA cluster
|
|
||||||
- Left-third caption + right-two-thirds visual (classic — use sparingly, never twice in a row)
|
|
||||||
- Right-third caption + left-two-thirds visual (inverted classic)
|
|
||||||
- Centered low (text in lower 40% over hero image)
|
|
||||||
- Off-grid editorial offset (asymmetric pull)
|
|
||||||
- Stacked center (label / headline / sub / CTA all centered, ultra minimalist)
|
|
||||||
- Image-as-canvas with text overlaid in a clean safe area
|
|
||||||
|
|
||||||
### Background Mode (per-section)
|
|
||||||
Pick 1 per section; vary across the page so it is never all the same mode. Be **confident** with backgrounds — they are a primary tool, not a risk.
|
|
||||||
- Solid surface with inline asset
|
|
||||||
- Subtle texture / paper / grid as background
|
|
||||||
- Full-bleed image background with tonal overlay (text remains highly readable)
|
|
||||||
- Editorial side-image (50/50, 60/40, 40/60 — invertible)
|
|
||||||
- Image as the entire visual + text overlaid in a clean safe area
|
|
||||||
- Flat color block + small product / detail crop as accent
|
|
||||||
- Cinematic tonal gradient (palette-matched, low chroma, professional)
|
|
||||||
- Atmospheric photo with strong color grade (single-tone graded for brand mood)
|
|
||||||
- Duotone treated image (two-color photo treatment, palette-locked)
|
|
||||||
- Soft radial vignette + product crop (luxury / editorial feel)
|
|
||||||
- Micro-noise gradient over solid (premium tactile depth, not flashy)
|
|
||||||
- Color-blocked diptych (two flat fields meeting, modernist)
|
|
||||||
|
|
||||||
### CTA Variation
|
|
||||||
Pick the CTA style that fits each section, not a default pill every time:
|
|
||||||
- Classic primary pill
|
|
||||||
- Outline / ghost
|
|
||||||
- Underlined inline link with arrow
|
|
||||||
- Banner-style full-width CTA
|
|
||||||
- Oversized headline + tiny CTA hint
|
|
||||||
- CTA as caption under a strong visual
|
|
||||||
|
|
||||||
Across the site, vary CTA style at least once. The page's primary action stays unmistakable.
|
|
||||||
|
|
||||||
### Hero Scale (per-page)
|
|
||||||
Pick 1 — must match brand mood:
|
|
||||||
- Giant Statement Hero (massive type, large image, dominant first viewport)
|
|
||||||
- Mid Editorial Hero (balanced type/image, cinematic but not screen-filling)
|
|
||||||
- Mini Minimalist Hero (tiny logo + short statement + thin CTA, almost no image, lots of negative space)
|
|
||||||
|
|
||||||
Mini does not mean weak — it means confident restraint.
|
|
||||||
|
|
||||||
### Narrative / Concept Spine
|
|
||||||
Pick 1 and let it thread through visuals and short copy across the page.
|
|
||||||
- Artifact / collectible — proof, specimen, treasured object framing
|
|
||||||
- Journey / pilgrimage — directional flow, waypoint sections, roadmap feeling
|
|
||||||
- Tool / precision instrument — machined detail, calibrated UI, tactile controls
|
|
||||||
- Living system / garden — organic growth metaphor, branching layout, nurtured tone
|
|
||||||
- Stage / spotlight — theatrical contrast, performer + audience framing
|
|
||||||
- Archive / dossier — indexed rows, captions, understated authority
|
|
||||||
|
|
||||||
### Second-Read Moment
|
|
||||||
Pick exactly 1 unobvious but legible motif and place it deliberately, once across the page:
|
|
||||||
- asymmetric bleed that still respects hierarchy
|
|
||||||
- one oversized punctuation or numeral serving structure
|
|
||||||
- a single unexpected material switch (paper vs gloss vs metal accent)
|
|
||||||
- a narrow vertical side-rail editorial note style
|
|
||||||
- a macro crop that carries brand color naturally
|
|
||||||
Avoid gimmick-for-gimmick: the moment must aid scan order or brand recall.
|
|
||||||
|
|
||||||
Important:
|
|
||||||
These are not coding instructions.
|
|
||||||
They are visual-direction cues the generated design should imply.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 3. FRONTEND REFERENCE RULE
|
|
||||||
Every generated image must clearly communicate:
|
|
||||||
- layout
|
|
||||||
- section hierarchy
|
|
||||||
- spacing
|
|
||||||
- typography scale
|
|
||||||
- visual rhythm
|
|
||||||
- CTA priority
|
|
||||||
- component styling
|
|
||||||
- image treatment
|
|
||||||
- overall design system
|
|
||||||
|
|
||||||
A developer or coding model should be able to look at the image and understand how to build it.
|
|
||||||
|
|
||||||
Do not produce vague abstract artwork when the request is for frontend.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 4. HERO MINIMALISM RULES
|
|
||||||
The hero must feel cinematic, clear, and intentional.
|
|
||||||
|
|
||||||
### Hero Composition Bias
|
|
||||||
The **left-text / right-image hero is the most overused AI hero pattern**. It is allowed, but it should not be your default starting point.
|
|
||||||
|
|
||||||
Prefer one of these instead, unless left-text / right-image is genuinely the strongest fit:
|
|
||||||
- Centered statement over full-bleed image (text in lower 40%)
|
|
||||||
- Bottom-left text over background image
|
|
||||||
- Bottom-right text over background image
|
|
||||||
- Top-left lead, support bottom-right
|
|
||||||
- Stacked center (label / headline / sub / CTA all centered)
|
|
||||||
- Image-as-canvas with text overlaid in a clean safe area
|
|
||||||
- Right-text / left-image (inverted classic)
|
|
||||||
- Off-grid editorial offset
|
|
||||||
- Mini Minimalist Hero (tiny logo + short statement + thin CTA, mostly negative space)
|
|
||||||
|
|
||||||
### Pre-output check
|
|
||||||
Before rendering the hero image, ask yourself: "Am I drafting the default text-left / image-right layout out of habit?" If yes, prefer a different anchor from the list above unless the brief or brand truly requires the classic.
|
|
||||||
|
|
||||||
### Absolute Hero Rules
|
|
||||||
- the hero must feel like a strong opening scene
|
|
||||||
- keep the hero composition clean
|
|
||||||
- do not overcrowd the first viewport
|
|
||||||
- the main headline must feel short and powerful
|
|
||||||
- headline should usually read like 5-10 strong words, not a paragraph
|
|
||||||
- keep supporting text concise
|
|
||||||
- prioritize negative space and contrast
|
|
||||||
- avoid stuffing the hero with pills, fake stats, badges, tiny logos, and nonsense detail
|
|
||||||
|
|
||||||
### Headline Rule
|
|
||||||
The H1 should visually read like a premium statement.
|
|
||||||
Do not let it feel long, weak, or overly wrapped.
|
|
||||||
|
|
||||||
### Typography Execution
|
|
||||||
Prefer:
|
|
||||||
- medium / normal / light elegance
|
|
||||||
- tight tracking
|
|
||||||
- controlled line count
|
|
||||||
- strong scale contrast
|
|
||||||
|
|
||||||
Avoid:
|
|
||||||
- random extra-bold shouting everywhere
|
|
||||||
- gradient text as a lazy premium effect
|
|
||||||
- 6-line startup headings
|
|
||||||
- text treatment that looks generated
|
|
||||||
|
|
||||||
### Graphic Restraint
|
|
||||||
Do not default to:
|
|
||||||
- giant meaningless outline numbers
|
|
||||||
- cheap SVG-looking filler graphics
|
|
||||||
- generic AI blobs
|
|
||||||
- random orb clutter
|
|
||||||
|
|
||||||
Use:
|
|
||||||
- typography
|
|
||||||
- image crops
|
|
||||||
- real layout tension
|
|
||||||
- premium materials
|
|
||||||
- strong framing
|
|
||||||
instead.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 5. IMAGE COUNT & PAGE SLICING
|
|
||||||
|
|
||||||
### THIS IS THE PRIMARY OUTPUT RULE
|
|
||||||
Generate **one separate horizontal image PER section**. Always.
|
|
||||||
|
|
||||||
- never combine multiple sections in a single image
|
|
||||||
- never return a single tall slice that contains the whole page
|
|
||||||
- never return one "best" image and skip the rest
|
|
||||||
- never replace several sections with one collage
|
|
||||||
|
|
||||||
If the request is ambiguous about section count, **default high**:
|
|
||||||
- "hero" -> 1 image
|
|
||||||
- "landing page" / "site template" -> default to 6 sections -> 6 images
|
|
||||||
- "full website" -> default to 8 sections -> 8 images
|
|
||||||
- "marketing site" -> default to 8 sections -> 8 images
|
|
||||||
- "product page" -> default to 6 sections -> 6 images
|
|
||||||
- "portfolio" -> default to 6 sections -> 6 images
|
|
||||||
|
|
||||||
If the model can only render one image per call, generate them **sequentially in the same response**, one after the other, labeled "Section X of N: <name>" until the full set is delivered.
|
|
||||||
|
|
||||||
### Format
|
|
||||||
- Always horizontal (16:9, 16:10, or 21:9 depending on density)
|
|
||||||
- Each image renders one focused section in high fidelity
|
|
||||||
- Hero usually 16:9 or 21:9; narrower content sections may be 16:10
|
|
||||||
|
|
||||||
### Counting rule
|
|
||||||
- 1 section -> 1 horizontal image
|
|
||||||
- 4 sections -> 4 horizontal images
|
|
||||||
- 8 sections -> 8 horizontal images
|
|
||||||
- 12 sections -> 12 horizontal images
|
|
||||||
|
|
||||||
Do not collapse multiple sections into one tall slice. Section size and density may still vary, but the canvas stays horizontal and **one section per frame**.
|
|
||||||
|
|
||||||
### Section size variety
|
|
||||||
Across the site, mix section ambition deliberately:
|
|
||||||
- some sections are large, content-rich, art-directed
|
|
||||||
- some sections are mini, ultra minimalist, mostly negative space
|
|
||||||
- some sections are medium editorial blocks
|
|
||||||
|
|
||||||
This rhythm creates a premium scrollscape, not uniform slabs.
|
|
||||||
|
|
||||||
### Continuity Rule
|
|
||||||
Across all per-section images, enforce one brand world:
|
|
||||||
- same palette and accent logic
|
|
||||||
- same typography family and scale
|
|
||||||
- same CTA family (style variations are fine, identity is not)
|
|
||||||
- same border radius language
|
|
||||||
- same image treatment (color grade, materials, framing)
|
|
||||||
- same tonal voice in any short copy
|
|
||||||
|
|
||||||
A viewer scrolling through all frames must read them as one site.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 6. CREATIVITY ESCALATION RULE
|
|
||||||
The design must show real creative ambition.
|
|
||||||
|
|
||||||
Do not settle for the first obvious layout solution.
|
|
||||||
Push the work beyond generic SaaS patterns.
|
|
||||||
|
|
||||||
Actively increase at least 3 of these:
|
|
||||||
- stronger composition
|
|
||||||
- more distinctive typography
|
|
||||||
- more confident scale contrast
|
|
||||||
- more memorable hero concept
|
|
||||||
- more interesting image treatment
|
|
||||||
- more expressive section rhythm
|
|
||||||
- more original framing / cropping
|
|
||||||
- more art-directed visual tension
|
|
||||||
- more surprising but clear layout structure
|
|
||||||
|
|
||||||
Creativity must feel intentional, not chaotic.
|
|
||||||
|
|
||||||
Do:
|
|
||||||
- make bold but controlled design decisions
|
|
||||||
- use asymmetry when it improves the page
|
|
||||||
- create visual moments that feel premium and memorable
|
|
||||||
- make the page feel designed, not auto-generated
|
|
||||||
|
|
||||||
Do not:
|
|
||||||
- default to safe template layouts
|
|
||||||
- repeat the same block structure too often
|
|
||||||
- confuse creativity with clutter
|
|
||||||
- make the page overly dense
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 7. IMAGE-FIRST ART DIRECTION
|
|
||||||
This skill must actively use images.
|
|
||||||
|
|
||||||
Images are not optional decoration.
|
|
||||||
Images are a core part of the frontend design language.
|
|
||||||
|
|
||||||
Strongly prefer:
|
|
||||||
- art-directed photography
|
|
||||||
- product imagery
|
|
||||||
- editorial imagery
|
|
||||||
- image crops
|
|
||||||
- framed image panels
|
|
||||||
- layered image compositions
|
|
||||||
- image-led hero sections
|
|
||||||
- image-supported storytelling blocks
|
|
||||||
|
|
||||||
Use images to:
|
|
||||||
- create visual hierarchy
|
|
||||||
- break up text-heavy layouts
|
|
||||||
- build mood and brand character
|
|
||||||
- support section transitions
|
|
||||||
- make the design easier to interpret and implement
|
|
||||||
|
|
||||||
Important:
|
|
||||||
- the design should not become text-only or card-only unless the user explicitly wants that
|
|
||||||
- if a page has multiple sections, several sections should meaningfully include imagery
|
|
||||||
- if a hero exists, it should usually contain a strong visual image, product visual, or art-directed media element
|
|
||||||
- imagery should feel premium and intentional, not like stock filler
|
|
||||||
|
|
||||||
Avoid:
|
|
||||||
- tiny useless thumbnails
|
|
||||||
- random decorative images with no structural role
|
|
||||||
- one single image and then a completely text-heavy rest of page
|
|
||||||
- overusing fake UI panels instead of real visual variety
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 8. ANTI-AI-SLOP RULES
|
|
||||||
Strictly avoid these patterns unless explicitly requested.
|
|
||||||
|
|
||||||
### Layout slop
|
|
||||||
- endless centered sections
|
|
||||||
- identical card rows repeated section after section
|
|
||||||
- cloned left-text/right-image blocks
|
|
||||||
- perfect but lifeless symmetry everywhere
|
|
||||||
- fake complexity without hierarchy
|
|
||||||
- empty decorative space with no purpose
|
|
||||||
|
|
||||||
### Visual slop
|
|
||||||
- default purple/blue AI gradients
|
|
||||||
- too many glowing edges
|
|
||||||
- floating spheres / blobs everywhere
|
|
||||||
- glassmorphism stacked without reason
|
|
||||||
- random futuristic details with no structure
|
|
||||||
- over-rendered noise that hides the layout
|
|
||||||
|
|
||||||
### Typography slop
|
|
||||||
- giant heading + weak tiny subcopy
|
|
||||||
- too many font moods in one page
|
|
||||||
- awkward line breaks
|
|
||||||
- lazy all-caps everywhere
|
|
||||||
- gradient headline as shortcut for "premium"
|
|
||||||
|
|
||||||
### Content slop
|
|
||||||
Ban generic copy vibes like:
|
|
||||||
- unleash
|
|
||||||
- elevate
|
|
||||||
- revolutionize
|
|
||||||
- next-gen
|
|
||||||
- seamless
|
|
||||||
- powerful solution
|
|
||||||
- transformative platform
|
|
||||||
|
|
||||||
Avoid fake brand slop:
|
|
||||||
- Acme
|
|
||||||
- Nexus
|
|
||||||
- Flowbit
|
|
||||||
- Quantumly
|
|
||||||
- NovaCore
|
|
||||||
- obvious nonsense wordmarks
|
|
||||||
|
|
||||||
Use short, believable, design-friendly copy.
|
|
||||||
|
|
||||||
### Density slop
|
|
||||||
- no over-packed sections
|
|
||||||
- no card overload in every block
|
|
||||||
- no tiny spacing between major sections
|
|
||||||
- no trying to fill every empty area
|
|
||||||
- no visually exhausting wall-of-content layouts
|
|
||||||
|
|
||||||
### Carousel / marquee slop (layout)
|
|
||||||
- infinity logo strips repeating the same 6 blobs
|
|
||||||
- “trusted by” ticker that is unreadable mosquito logos
|
|
||||||
- auto-play-style hero dots with no semantic purpose
|
|
||||||
|
|
||||||
### Data / KPI slop
|
|
||||||
- three identical stat columns (99% satisfaction, $10 saved, ∞ scale) unless user asked for KPIs
|
|
||||||
- fake dashboards with pointless charts shading the real layout
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 9. TYPOGRAPHY-FIRST DISCIPLINE
|
|
||||||
Typography is not filler.
|
|
||||||
Typography is a primary design material.
|
|
||||||
|
|
||||||
Always ensure:
|
|
||||||
- clear size contrast
|
|
||||||
- obvious reading order
|
|
||||||
- strong display moments
|
|
||||||
- supporting text that is readable and brief
|
|
||||||
- labels, captions, and section headings that reinforce structure
|
|
||||||
|
|
||||||
For editorial directions:
|
|
||||||
- let typography shape composition
|
|
||||||
|
|
||||||
For tech/product directions:
|
|
||||||
- let typography communicate trust and precision
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 10. SECTION RHYTHM RULE
|
|
||||||
A high-end site does not feel like repeated boxes.
|
|
||||||
|
|
||||||
Vary section rhythm across the page by changing:
|
|
||||||
- density
|
|
||||||
- image-to-text ratio
|
|
||||||
- alignment
|
|
||||||
- scale
|
|
||||||
- whitespace
|
|
||||||
- card grouping
|
|
||||||
- background intensity
|
|
||||||
- visual tempo
|
|
||||||
|
|
||||||
Do not let every section feel generated from the same template.
|
|
||||||
|
|
||||||
Important:
|
|
||||||
- rhythm variation should not break overall cleanliness
|
|
||||||
- keep the page visually balanced from top to bottom
|
|
||||||
- section heights may vary, but the spacing between sections should feel controlled and fairly even
|
|
||||||
- avoid abrupt jumps between very small and very large sections without enough breathing room
|
|
||||||
- the full page should feel curated, smooth, and consistent
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 11. COMPONENT EXECUTION GUIDELINES
|
|
||||||
|
|
||||||
### Diagonal Staggered Square Masonry
|
|
||||||
Use square image or content blocks with strong staggered vertical rhythm.
|
|
||||||
Should feel curated and graphic, not messy.
|
|
||||||
|
|
||||||
### 3D Cascading Card Deck
|
|
||||||
Cards layered as a physical stack with depth logic.
|
|
||||||
Should feel premium and tactile, not gimmicky.
|
|
||||||
|
|
||||||
### Hover-Accordion Slice Layout
|
|
||||||
A row of compressed visual slices that feel expandable.
|
|
||||||
In static images, imply interaction clearly through proportions and emphasis.
|
|
||||||
|
|
||||||
### Pristine Gapless Bento Grid
|
|
||||||
Mathematically clean grid.
|
|
||||||
No accidental gaps.
|
|
||||||
Mix large visual blocks with smaller dense information panels.
|
|
||||||
|
|
||||||
### Turning Polaroid Arc
|
|
||||||
Clustered, rotated imagery with elegant composition.
|
|
||||||
Should feel styled and intentional, not scrapbook-random.
|
|
||||||
|
|
||||||
### Off-Grid Editorial Layout
|
|
||||||
Use asymmetry and tension with control.
|
|
||||||
Must remain readable and clearly structured.
|
|
||||||
|
|
||||||
### Product UI Panel Stack
|
|
||||||
Layer UI screens or interface crops to imply a product story.
|
|
||||||
Avoid generic fake dashboards.
|
|
||||||
|
|
||||||
### Vertical Rhythm Lines
|
|
||||||
Use fine lines and spacing systems to reinforce order and elegance.
|
|
||||||
Never let them become decorative clutter.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 12. DENSITY & SPACING DISCIPLINE
|
|
||||||
Do not make everything too dense.
|
|
||||||
|
|
||||||
The page should breathe.
|
|
||||||
Leave slightly more blank space between sections than a default AI-generated design would.
|
|
||||||
|
|
||||||
Rules:
|
|
||||||
- use more even vertical spacing between major sections
|
|
||||||
- keep section-to-section spacing consistent unless there is a strong design reason not to
|
|
||||||
- avoid one section feeling very cramped while the next feels too empty
|
|
||||||
- prefer a clean, balanced cadence across the page
|
|
||||||
- allow negative space to create rhythm and emphasis
|
|
||||||
- separate denser sections with calmer sections
|
|
||||||
- avoid stacking too many cards, labels, and content blocks too tightly
|
|
||||||
- smaller sections should still receive enough surrounding space so the page feels polished and intentional
|
|
||||||
|
|
||||||
A premium page should feel:
|
|
||||||
- open
|
|
||||||
- composed
|
|
||||||
- balanced
|
|
||||||
- confident
|
|
||||||
- breathable
|
|
||||||
|
|
||||||
Not:
|
|
||||||
- cramped
|
|
||||||
- noisy
|
|
||||||
- uneven
|
|
||||||
- overfilled
|
|
||||||
- visually exhausted
|
|
||||||
|
|
||||||
Section rhythm should alternate with control:
|
|
||||||
- some sections can be more content-rich
|
|
||||||
- some sections can be smaller and calmer
|
|
||||||
- but the overall spacing cadence should still feel even, clean, and deliberate
|
|
||||||
|
|
||||||
Whitespace is a design tool.
|
|
||||||
Use it deliberately.
|
|
||||||
Do not let spacing become random.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 13. COLOR & MATERIAL RULES
|
|
||||||
|
|
||||||
### Palette Discipline
|
|
||||||
Use one controlled palette across the entire site:
|
|
||||||
- 1 primary (brand anchor)
|
|
||||||
- 1 secondary (supporting tone)
|
|
||||||
- 1 accent (used sparingly for CTA / highlight)
|
|
||||||
- a neutral scale (background, surface, text, hairline)
|
|
||||||
|
|
||||||
Section-level mood shifts must reuse the same palette — no full theme swap per section.
|
|
||||||
|
|
||||||
### Background-image harmony
|
|
||||||
When using full-bleed image backgrounds:
|
|
||||||
- the image must tonally match the palette (not fight it)
|
|
||||||
- use overlays (dark, light, or color tint) to keep text fully readable
|
|
||||||
- the brand accent stays consistent regardless of background image
|
|
||||||
|
|
||||||
### Gradient Discipline
|
|
||||||
Gradients are **allowed and encouraged** when professional and subtle. They are not the same as AI slop gradients.
|
|
||||||
|
|
||||||
Allowed (use confidently):
|
|
||||||
- low-chroma palette-matched tonal gradients (e.g. ink to graphite, cream to sand, ivory to warm grey)
|
|
||||||
- single-hue atmospheric grades behind hero photography
|
|
||||||
- soft vignettes and radial depth that direct the eye
|
|
||||||
- noise-textured gradients adding tactile depth without color noise
|
|
||||||
- editorial color washes that match brand mood
|
|
||||||
|
|
||||||
Banned (AI gradient slop):
|
|
||||||
- rainbow / mesh blob gradients
|
|
||||||
- purple-to-blue "AI" defaults
|
|
||||||
- pink-to-orange "creator" defaults
|
|
||||||
- neon edges and glow halos with no purpose
|
|
||||||
- gradient text as a shortcut for "premium"
|
|
||||||
- gradients that compete with imagery instead of supporting it
|
|
||||||
|
|
||||||
### Background Confidence Rule
|
|
||||||
Do not retreat to plain white surfaces by default. When the brief, brand mood, or section job calls for atmosphere, use:
|
|
||||||
- a full-bleed image,
|
|
||||||
- a duotone or graded photo,
|
|
||||||
- a tonal gradient,
|
|
||||||
- a tactile material,
|
|
||||||
or a confident flat color field — picked deliberately, not as decoration.
|
|
||||||
|
|
||||||
### Strong guidance
|
|
||||||
- avoid rainbow randomness
|
|
||||||
- avoid over-neon unless requested
|
|
||||||
- keep contrast intentional
|
|
||||||
- match accent colors to the chosen theme paradigm
|
|
||||||
- gradients must always read as professional and intentional, never as visual noise
|
|
||||||
|
|
||||||
### Materiality
|
|
||||||
Where appropriate, add:
|
|
||||||
- paper feel
|
|
||||||
- glass feel
|
|
||||||
- brushed metal feel
|
|
||||||
- soft blur depth
|
|
||||||
- tactile matte surfaces
|
|
||||||
- editorial photo treatment
|
|
||||||
|
|
||||||
But always keep the frontend structure readable.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 14. IMAGE / MEDIA DIRECTION
|
|
||||||
If imagery is present, it must support the layout.
|
|
||||||
|
|
||||||
Allowed:
|
|
||||||
- art-directed product visuals
|
|
||||||
- refined editorial photography
|
|
||||||
- UI crops
|
|
||||||
- abstract forms with structural purpose
|
|
||||||
- framed objects
|
|
||||||
- premium texture use
|
|
||||||
- campaign-style visuals
|
|
||||||
|
|
||||||
Avoid:
|
|
||||||
- irrelevant scenery
|
|
||||||
- stock-photo cliches
|
|
||||||
- decorative junk
|
|
||||||
- visuals that overpower the page hierarchy
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 15. DEFAULT SITE PACKS
|
|
||||||
|
|
||||||
### 4-section pack
|
|
||||||
1. Hero
|
|
||||||
2. Features
|
|
||||||
3. Social proof / testimonial
|
|
||||||
4. CTA
|
|
||||||
|
|
||||||
### 8-section pack
|
|
||||||
1. Hero
|
|
||||||
2. Trust bar
|
|
||||||
3. Features
|
|
||||||
4. Product showcase
|
|
||||||
5. Benefits / use cases
|
|
||||||
6. Testimonials
|
|
||||||
7. Pricing
|
|
||||||
8. CTA
|
|
||||||
|
|
||||||
### 12-section pack
|
|
||||||
1. Hero
|
|
||||||
2. Trust bar
|
|
||||||
3. Feature grid
|
|
||||||
4. Product preview
|
|
||||||
5. Problem / solution
|
|
||||||
6. Benefits
|
|
||||||
7. Workflow
|
|
||||||
8. Metrics / proof / integration
|
|
||||||
9. Testimonials
|
|
||||||
10. Pricing
|
|
||||||
11. FAQ
|
|
||||||
12. CTA + footer
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 16. MULTI-IMAGE CONSISTENCY RULE
|
|
||||||
Because every section is its own image, consistency is critical. Across all per-section frames enforce:
|
|
||||||
- same brand world
|
|
||||||
- same type scale logic
|
|
||||||
- same spacing discipline
|
|
||||||
- same CTA family (style variations are fine, identity is not)
|
|
||||||
- same icon or illustration mood
|
|
||||||
- same image treatment (grade, framing, material vocabulary)
|
|
||||||
- same tonal language in any copy
|
|
||||||
|
|
||||||
Variation IS allowed in:
|
|
||||||
- composition anchor (per section)
|
|
||||||
- background mode (per section)
|
|
||||||
- section size and density
|
|
||||||
- which "second-read" moment appears
|
|
||||||
|
|
||||||
A viewer flipping through every per-section frame must still recognize one brand. Anything that breaks brand recall is over-variation.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 17. CLARITY CHECK
|
|
||||||
Before finalizing, verify internally:
|
|
||||||
|
|
||||||
1. Is the hierarchy obvious?
|
|
||||||
2. Is the hero clean enough?
|
|
||||||
3. Is the design visually distinctive?
|
|
||||||
4. Is it free of obvious AI tells?
|
|
||||||
5. Is it premium rather than template-like?
|
|
||||||
6. Can someone code from this?
|
|
||||||
7. If multiple images exist, do they clearly belong together?
|
|
||||||
8. Is imagery used strongly enough (with variation, not one repeated crop)?
|
|
||||||
9. Does the page breathe, or is it too dense?
|
|
||||||
10. Is there enough spacing between sections?
|
|
||||||
11. Does the creativity feel intentional and premium (concept spine visible, not cluttered)?
|
|
||||||
12. Is the spacing between sections even and controlled?
|
|
||||||
13. Do smaller sections still have enough surrounding space to feel clean?
|
|
||||||
14. Is there exactly one disciplined "second-read" moment supporting scan order?
|
|
||||||
15. Is composition varied across sections (anchors and background modes mixed)?
|
|
||||||
16. Is the hero scale (giant / mid / mini) chosen and executed cleanly?
|
|
||||||
17. Is there a clear conversion path (hook -> proof -> action) even in artistic sites?
|
|
||||||
18. Is the palette consistent across all per-section images?
|
|
||||||
19. Is each image horizontal and one-section-only?
|
|
||||||
20. Is the **total number of images equal to the number of sections** (never fewer)?
|
|
||||||
21. Is the hero using a varied composition (not defaulting to left-text / right-image out of habit)?
|
|
||||||
|
|
||||||
If not, refine internally before output. If the count is wrong, regenerate the missing sections. If the hero feels like a reflexive left-text / right-image default, prefer a different composition anchor.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 18. EXTRA CREATIVITY & IMPLEMENTATION EDGE
|
|
||||||
|
|
||||||
Apply unless the user opts out:
|
|
||||||
|
|
||||||
### Cross-section contrast
|
|
||||||
Across the slice, deliberately vary foreground/background intensity at least twice (lighter → richer → calmer) so the scroll feels paced, not monotonous slabs.
|
|
||||||
|
|
||||||
### CTA specificity
|
|
||||||
Prefer one unmistakable primary action per major viewport tier; secondary actions must look secondary (scale, outline, ghost), not clones of primary.
|
|
||||||
|
|
||||||
### Image variety inside one comp
|
|
||||||
Mix at least **two distinct image crops** where multiple sections exist — e.g. macro product + contextual environment, or portrait editorial + widescreen artifact — avoiding one repeated stock silhouette.
|
|
||||||
|
|
||||||
### Data-viz restraint
|
|
||||||
Charts, sparklines, and graphs appear only when the site type logically needs them (analytics, pricing, infra, observability brands). Else keep proof human (quotes, receipts, timelines, screenshots of real workflows).
|
|
||||||
|
|
||||||
### Cultural / tonal alignment
|
|
||||||
When the brief names an industry or region, steer palette and typographic temperament to match — don’t ship default “neutral SF startup” unless the brief is intentionally generic SaaS.
|
|
||||||
|
|
||||||
### Mobile-implied fidelity (even for desktop mocks)
|
|
||||||
Maintain tap-friendly hit sizes and readable caption sizes visually; stacking order should imply a sane single-column narrative.
|
|
||||||
|
|
||||||
### Conversion focus
|
|
||||||
Each section has a job. Even when the design is artistic, the page must read as a real product or brand site:
|
|
||||||
- the hero communicates value in seconds and offers one obvious next action
|
|
||||||
- proof sections (logos, quotes, metrics) feel earned, not stuffed
|
|
||||||
- pricing or CTA sections feel decisive, not buried
|
|
||||||
- the final section closes: a single strong CTA + supporting trust cue
|
|
||||||
Avoid pure mood reels with no funnel logic.
|
|
||||||
|
|
||||||
### Composition variety check
|
|
||||||
Across all per-section images, internally log the chosen composition anchor and background mode. Reject the set if:
|
|
||||||
- the same composition anchor repeats more than 2 sections in a row
|
|
||||||
- the same background mode repeats more than 3 sections in a row
|
|
||||||
- every section is inline-asset (no full-bleed background ever appears) **AND** the brief does not call for minimalism / typography-only / swiss / ultra simple
|
|
||||||
|
|
||||||
For non-minimalist briefs: push for at least one full-bleed (or duotone / atmospheric) background and at least one mini minimalist section in any multi-section site.
|
|
||||||
|
|
||||||
For minimalist briefs: this rule is suspended. Restraint is the design.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 19. RESPONSE BEHAVIOR
|
|
||||||
When the user asks for a frontend design:
|
|
||||||
1. infer site type and primary conversion goal
|
|
||||||
2. infer number of sections (if unclear, use the defaults from §5: landing page = 6, full website = 8)
|
|
||||||
3. **commit out loud** to the section count and announce it ("Generating N horizontal images, one per section")
|
|
||||||
4. plan ONE horizontal image PER SECTION — always separate generations, never collapse
|
|
||||||
5. choose Hero Scale for the whole site (giant / mid / mini)
|
|
||||||
5. choose a strong visual combination (theme, type, hero arch, section system, motion, narrative spine, second-read moment)
|
|
||||||
7. for each section: pick a Composition Anchor, Background Mode, and CTA Variation — vary across sections
|
|
||||||
8. choose 4 signature components used appropriately across sections
|
|
||||||
9. enforce hero minimalism + section size variety (some giant, some mini)
|
|
||||||
10. enforce strong image usage including full-bleed backgrounds where it fits
|
|
||||||
11. lock one consistent palette across all images
|
|
||||||
12. apply §18 EXTRA CREATIVITY & IMPLEMENTATION EDGE
|
|
||||||
13. keep spacing generous, even, and clean
|
|
||||||
14. remove AI slop (including marquee / fake KPI clichés unless requested)
|
|
||||||
15. run §17 CLARITY CHECK
|
|
||||||
16. **generate every per-section horizontal image, labeled "Section X of N: <name>"**, until the full set is delivered. Do not stop early. Do not summarize. Do not return only one image.
|
|
||||||
|
|
||||||
Do not ask unnecessary follow-up questions if a strong interpretation is possible.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 20. EXAMPLE INTERPRETATIONS
|
|
||||||
|
|
||||||
### Example 1
|
|
||||||
User: "make a hero section for an AI startup"
|
|
||||||
|
|
||||||
Interpretation:
|
|
||||||
- 1 horizontal image
|
|
||||||
- Hero Scale: Mid Editorial or Giant Statement
|
|
||||||
- Composition Anchor: bottom-left text over full-bleed product/atmosphere image
|
|
||||||
- Background Mode: full-bleed image with dark tonal overlay
|
|
||||||
- CTA Variation: outlined inline + small label hint
|
|
||||||
- Palette: Deep Dark or Bold Studio Solid, one consistent accent
|
|
||||||
- no cliche dashboard spam, no purple AI glow
|
|
||||||
|
|
||||||
### Example 2
|
|
||||||
User: "design 8 sections for a fintech website"
|
|
||||||
|
|
||||||
Interpretation:
|
|
||||||
- 8 separate horizontal images (one per section)
|
|
||||||
- Hero Scale: Mid Editorial (trust-driven)
|
|
||||||
- vary Composition Anchor across sections (centered low, right-third caption, bottom-left over chart visual, stacked center for closing CTA)
|
|
||||||
- Background Mode mix: solid surface, full-bleed image background once, editorial side-image at use cases
|
|
||||||
- one consistent palette (e.g. ink + paper + single brand accent)
|
|
||||||
- conversion path: hook -> proof bar -> features -> use case -> testimonial -> pricing -> FAQ -> final CTA
|
|
||||||
|
|
||||||
### Example 3
|
|
||||||
User: "creative agency landing page, 12 sections"
|
|
||||||
|
|
||||||
Interpretation:
|
|
||||||
- 12 horizontal images (one per section)
|
|
||||||
- Hero Scale: Giant Statement OR Mini Minimalist (decisive choice, not in-between)
|
|
||||||
- editorial / poster-like direction; off-grid composition appears 2-3 times
|
|
||||||
- multiple Background Modes (full-bleed image at hero + showcase, editorial side-image at case studies, solid + accent for process)
|
|
||||||
- palette consistent throughout, with one bold accent recurring
|
|
||||||
- closing CTA section: mini minimalist, strong type, single primary action
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 21. FINAL GOAL
|
|
||||||
Generate frontend reference images that feel:
|
|
||||||
- artistic
|
|
||||||
- premium
|
|
||||||
- clear
|
|
||||||
- structured
|
|
||||||
- image-led
|
|
||||||
- breathable
|
|
||||||
- memorable
|
|
||||||
- anti-generic
|
|
||||||
- implementation-friendly
|
|
||||||
|
|
||||||
The result should look like a top-tier website concept with strong imagery, confident creativity, and generous spacing - not a dense, repetitive AI layout.
|
|
||||||
@@ -1,92 +0,0 @@
|
|||||||
---
|
|
||||||
name: industrial-brutalist-ui
|
|
||||||
description: Raw mechanical interfaces fusing Swiss typographic print with military terminal aesthetics. Rigid grids, extreme type scale contrast, utilitarian color, analog degradation effects. For data-heavy dashboards, portfolios, or editorial sites that need to feel like declassified blueprints.
|
|
||||||
---
|
|
||||||
|
|
||||||
# SKILL: Industrial Brutalism & Tactical Telemetry UI
|
|
||||||
|
|
||||||
## 1. Skill Meta
|
|
||||||
**Name:** Industrial Brutalism & Tactical Telemetry Interface Engineering
|
|
||||||
**Description:** Advanced proficiency in architecting web interfaces that synthesize mid-century Swiss Typographic design, industrial manufacturing manuals, and retro-futuristic aerospace/military terminal interfaces. This discipline requires absolute mastery over rigid modular grids, extreme typographic scale contrast, purely utilitarian color palettes, and the programmatic simulation of analog degradation (halftones, CRT scanlines, bitmap dithering). The objective is to construct digital environments that project raw functionality, mechanical precision, and high data density, deliberately discarding conventional consumer UI patterns.
|
|
||||||
|
|
||||||
## 2. Visual Archetypes
|
|
||||||
The design system operates by merging two distinct but highly compatible visual paradigms. **Pick ONE per project and commit to it. Do not alternate or mix both modes within the same interface.**
|
|
||||||
|
|
||||||
### 2.1 Swiss Industrial Print
|
|
||||||
Derived from 1960s corporate identity systems and heavy machinery blueprints.
|
|
||||||
* **Characteristics:** High-contrast light modes (newsprint/off-white substrates). Reliance on monolithic, heavy sans-serif typography. Unforgiving structural grids outlined by visible dividing lines. Aggressive, asymmetric use of negative space punctuated by oversized, viewport-bleeding numerals or letterforms. Heavy use of primary red as an alert/accent color.
|
|
||||||
|
|
||||||
### 2.2 Tactical Telemetry & CRT Terminal
|
|
||||||
Derived from classified military databases, legacy mainframes, and aerospace Heads-Up Displays (HUDs).
|
|
||||||
* **Characteristics:** Dark mode exclusivity. High-density tabular data presentation. Absolute dominance of monospaced typography. Integration of technical framing devices (ASCII brackets, crosshairs). Application of simulated hardware limitations (phosphor glow, scanlines, low bit-depth rendering).
|
|
||||||
|
|
||||||
## 3. Typographic Architecture
|
|
||||||
Typography is the primary structural and decorative infrastructure. Imagery is secondary. The system demands extreme variance in scale, weight, and spacing.
|
|
||||||
|
|
||||||
### 3.1 Macro-Typography (Structural Headers)
|
|
||||||
* **Classification:** Neo-Grotesque / Heavy Sans-Serif.
|
|
||||||
* **Optimal Web Fonts:** Neue Haas Grotesk (Black), Inter (Extra Bold/Black), Archivo Black, Roboto Flex (Heavy), Monument Extended.
|
|
||||||
* **Implementation Parameters:**
|
|
||||||
* **Scale:** Deployed at massive scales using fluid typography (e.g., `clamp(4rem, 10vw, 15rem)`).
|
|
||||||
* **Tracking (Letter-spacing):** Extremely tight, often negative (`-0.03em` to `-0.06em`), forcing glyphs to form solid architectural blocks.
|
|
||||||
* **Leading (Line-height):** Highly compressed (`0.85` to `0.95`).
|
|
||||||
* **Casing:** Exclusively uppercase for structural impact.
|
|
||||||
|
|
||||||
### 3.2 Micro-Typography (Data & Telemetry)
|
|
||||||
* **Classification:** Monospace / Technical Sans.
|
|
||||||
* **Optimal Web Fonts:** JetBrains Mono, IBM Plex Mono, Space Mono, VT323, Courier Prime.
|
|
||||||
* **Implementation Parameters:**
|
|
||||||
* **Scale:** Fixed and small (`10px` to `14px` / `0.7rem` to `0.875rem`).
|
|
||||||
* **Tracking:** Generous (`0.05em` to `0.1em`) to simulate mechanical typewriter spacing or terminal matrices.
|
|
||||||
* **Leading:** Standard to tight (`1.2` to `1.4`).
|
|
||||||
* **Casing:** Exclusively uppercase. Used for all metadata, navigation, unit IDs, and coordinates.
|
|
||||||
|
|
||||||
### 3.3 Textural Contrast (Artistic Disruption)
|
|
||||||
* **Classification:** High-Contrast Serif.
|
|
||||||
* **Optimal Web Fonts:** Playfair Display, EB Garamond, Times New Roman.
|
|
||||||
* **Implementation Parameters:** Used exceedingly sparingly. Must be subjected to heavy post-processing (halftone filters, 1-bit dithering) to degrade vector perfection and create textural juxtaposition against the clean sans-serifs.
|
|
||||||
|
|
||||||
## 4. Color System
|
|
||||||
The color architecture is uncompromising. Gradients, soft drop shadows, and modern translucency are strictly prohibited. Colors simulate physical media or primitive emissive displays.
|
|
||||||
|
|
||||||
**CRITICAL: Choose ONE substrate palette per project and use it consistently. Never mix light and dark substrates within the same interface.**
|
|
||||||
|
|
||||||
### If Swiss Industrial Print (Light):
|
|
||||||
* **Background:** `#F4F4F0` or `#EAE8E3` (Matte, unbleached documentation paper).
|
|
||||||
* **Foreground:** `#050505` to `#111111` (Carbon Ink).
|
|
||||||
* **Accent:** `#E61919` or `#FF2A2A` (Aviation/Hazard Red). This is the ONLY accent color. Used for strike-throughs, thick structural dividing lines, or vital data highlights.
|
|
||||||
|
|
||||||
### If Tactical Telemetry (Dark):
|
|
||||||
* **Background:** `#0A0A0A` or `#121212` (Deactivated CRT. Avoid pure `#000000`).
|
|
||||||
* **Foreground:** `#EAEAEA` (White phosphor). This is the primary text color.
|
|
||||||
* **Accent:** `#E61919` or `#FF2A2A` (Aviation/Hazard Red). Same red, same rules.
|
|
||||||
* **Terminal Green (`#4AF626`):** Optional. Use ONLY for a single specific UI element (e.g., one status indicator or one data readout) — never as a general text color. If it doesn't serve a clear purpose, omit it entirely.
|
|
||||||
|
|
||||||
## 5. Layout and Spatial Engineering
|
|
||||||
The layout must appear mathematically engineered. It rejects conventional web padding in favor of visible compartmentalization.
|
|
||||||
|
|
||||||
* **The Blueprint Grid:** Strict adherence to CSS Grid architectures. Elements do not float; they are anchored precisely to grid tracks and intersections.
|
|
||||||
* **Visible Compartmentalization:** Extensive utilization of solid borders (`1px` or `2px solid`) to delineate distinct zones of information. Horizontal rules (`<hr>`) frequently span the entire container width to segregate operational units.
|
|
||||||
* **Bimodal Density:** Layouts oscillate between extreme data density (tightly packed monospace metadata clustered together) and vast expanses of calculated negative space framing macro-typography.
|
|
||||||
* **Geometry:** Absolute rejection of `border-radius`. All corners must be exactly 90 degrees to enforce mechanical rigidity.
|
|
||||||
|
|
||||||
## 6. UI Components and Symbology
|
|
||||||
Standard web UI conventions are replaced with utilitarian, industrial graphic elements.
|
|
||||||
|
|
||||||
* **Syntax Decoration:** Utilization of ASCII characters to frame data points.
|
|
||||||
* *Framing:* `[ DELIVERY SYSTEMS ]`, `< RE-IND >`
|
|
||||||
* *Directional:* `>>>`, `///`, `\\\\`
|
|
||||||
* **Industrial Markers:** Prominent integration of registration (`®`), copyright (`©`), and trademark (`™`) symbols functioning as structural geometric elements rather than legal text.
|
|
||||||
* **Technical Assets:** Integration of crosshairs (`+`) at grid intersections, repeating vertical lines (barcodes), thick horizontal warning stripes, and randomized string data (e.g., `REV 2.6`, `UNIT / D-01`) to simulate active mechanical processes.
|
|
||||||
|
|
||||||
## 7. Textural and Post-Processing Effects
|
|
||||||
To prevent the design from appearing purely digital, simulated analog degradation is engineered into the frontend via CSS and SVG filters.
|
|
||||||
|
|
||||||
* **Halftone and 1-Bit Dithering:** Transforming continuous-tone images or large serif typography into dot-matrix patterns. Achieved via pre-processing or CSS `mix-blend-mode: multiply` overlays combined with SVG radial dot patterns.
|
|
||||||
* **CRT Scanlines:** For terminal interfaces, applying a `repeating-linear-gradient` to the background to simulate horizontal electron beam sweeps (e.g., `repeating-linear-gradient(0deg, transparent, transparent 2px, rgba(0,0,0,0.1) 2px, rgba(0,0,0,0.1) 4px)`).
|
|
||||||
* **Mechanical Noise:** A global, low-opacity SVG static/noise filter applied to the DOM root to introduce a unified physical grain across both dark and light modes.
|
|
||||||
|
|
||||||
## 8. Web Engineering Directives
|
|
||||||
1. **Grid Determinism:** Utilize `display: grid; gap: 1px;` with contrasting parent/child background colors to generate mathematically perfect, razor-thin dividing lines without complex border declarations.
|
|
||||||
2. **Semantic Rigidity:** Construct the DOM using precise semantic tags (`<data>`, `<samp>`, `<kbd>`, `<output>`, `<dl>`) to accurately reflect the technical nature of the telemetry.
|
|
||||||
3. **Typography Clamping:** Implement CSS `clamp()` functions exclusively for macro-typography to ensure massive text scales aggressively while maintaining structural integrity across viewports.
|
|
||||||
@@ -1,85 +0,0 @@
|
|||||||
---
|
|
||||||
name: minimalist-ui
|
|
||||||
description: Clean editorial-style interfaces. Warm monochrome palette, typographic contrast, flat bento grids, muted pastels. No gradients, no heavy shadows.
|
|
||||||
---
|
|
||||||
|
|
||||||
# Protocol: Premium Utilitarian Minimalism UI Architect
|
|
||||||
|
|
||||||
## 1. Protocol Overview
|
|
||||||
Name: Premium Utilitarian Minimalism & Editorial UI
|
|
||||||
Description: An advanced frontend engineering directive for generating highly refined, ultra-minimalist, "document-style" web interfaces analogous to top-tier workspace platforms. This protocol strictly enforces a high-contrast warm monochrome palette, bespoke typographic hierarchies, meticulous structural macro-whitespace, bento-grid layouts, and an ultra-flat component architecture with deliberate muted pastel accents. It actively rejects standard generic SaaS design trends.
|
|
||||||
|
|
||||||
## 2. Absolute Negative Constraints (Banned Elements)
|
|
||||||
The AI must strictly avoid the following generic web development defaults:
|
|
||||||
- DO NOT use the "Inter", "Roboto", or "Open Sans" typefaces.
|
|
||||||
- DO NOT use generic, thin-line icon libraries like "Lucide", "Feather", or standard "Heroicons".
|
|
||||||
- DO NOT use Tailwind's default heavy drop shadows (e.g., `shadow-md`, `shadow-lg`, `shadow-xl`). Shadows must be practically non-existent or heavily customized to be ultra-diffuse and low opacity (< 0.05).
|
|
||||||
- DO NOT use primary colored backgrounds for large elements or sections (e.g., no bright blue, green, or red hero sections).
|
|
||||||
- DO NOT use gradients, neon colors, or 3D glassmorphism (beyond subtle navbar blurs).
|
|
||||||
- DO NOT use `rounded-full` (pill shapes) for large containers, cards, or primary buttons.
|
|
||||||
- DO NOT use emojis anywhere in code, markup, text content, headings, or alt text. Replace with proper icons or clean SVG primitives.
|
|
||||||
- DO NOT use generic placeholder names like "John Doe", "Acme Corp", or "Lorem Ipsum". Use realistic, contextual content.
|
|
||||||
- DO NOT use AI copywriting clichés: "Elevate", "Seamless", "Unleash", "Next-Gen", "Game-changer", "Delve". Write plain, specific language.
|
|
||||||
|
|
||||||
## 3. Typographic Architecture
|
|
||||||
The interface must rely on extreme typographic contrast and premium font selection to establish an editorial feel.
|
|
||||||
- Primary Sans-Serif (Body, UI, Buttons): Use clean, geometric, or system-native fonts with character. Target: `font-family: 'SF Pro Display', 'Geist Sans', 'Helvetica Neue', 'Switzer', sans-serif`.
|
|
||||||
- Editorial Serif (Hero Headings & Quotes): Target: `font-family: 'Lyon Text', 'Newsreader', 'Playfair Display', 'Instrument Serif', serif`. Apply tight tracking (`letter-spacing: -0.02em` to `-0.04em`) and tight line-height (`1.1`).
|
|
||||||
- Monospace (Code, Keystrokes, Meta-data): Target: `font-family: 'Geist Mono', 'SF Mono', 'JetBrains Mono', monospace`.
|
|
||||||
- Text Colors: Body text must never be absolute black (`#000000`). Use off-black/charcoal (`#111111` or `#2F3437`) with a generous `line-height` of `1.6` for legibility. Secondary text should be muted gray (`#787774`).
|
|
||||||
|
|
||||||
## 4. Color Palette (Warm Monochrome + Spot Pastels)
|
|
||||||
Color is a scarce resource, utilized only for semantic meaning or subtle accents.
|
|
||||||
- Canvas / Background: Pure White `#FFFFFF` or Warm Bone/Off-White `#F7F6F3` / `#FBFBFA`.
|
|
||||||
- Primary Surface (Cards): `#FFFFFF` or `#F9F9F8`.
|
|
||||||
- Structural Borders / Dividers: Ultra-light gray `#EAEAEA` or `rgba(0,0,0,0.06)`.
|
|
||||||
- Accent Colors: Exclusively use highly desaturated, washed-out pastels for tags, inline code backgrounds, or subtle icon backgrounds.
|
|
||||||
- Pale Red: `#FDEBEC` (Text: `#9F2F2D`)
|
|
||||||
- Pale Blue: `#E1F3FE` (Text: `#1F6C9F`)
|
|
||||||
- Pale Green: `#EDF3EC` (Text: `#346538`)
|
|
||||||
- Pale Yellow: `#FBF3DB` (Text: `#956400`)
|
|
||||||
|
|
||||||
## 5. Component Specifications
|
|
||||||
- Bento Box Feature Grids:
|
|
||||||
- Utilize asymmetrical CSS Grid layouts.
|
|
||||||
- Cards must have exactly `border: 1px solid #EAEAEA`.
|
|
||||||
- Border-radius must be crisp: `8px` or `12px` maximum.
|
|
||||||
- Internal padding must be generous (e.g., `24px` to `40px`).
|
|
||||||
- Primary Call-To-Action (Buttons):
|
|
||||||
- Solid background `#111111`, text `#FFFFFF`.
|
|
||||||
- Slight border-radius (`4px` to `6px`). No box-shadow.
|
|
||||||
- Hover state should be a subtle color shift to `#333333` or a micro-scale `transform: scale(0.98)`.
|
|
||||||
- Tags & Status Badges:
|
|
||||||
- Pill-shaped (`border-radius: 9999px`), very small typography (`text-xs`), uppercase with wide tracking (`letter-spacing: 0.05em`).
|
|
||||||
- Background must use the defined Muted Pastels.
|
|
||||||
- Accordions (FAQ):
|
|
||||||
- Strip all container boxes. Separate items only with a `border-bottom: 1px solid #EAEAEA`.
|
|
||||||
- Use a clean, sharp `+` and `-` icon for the toggle state.
|
|
||||||
- Keystroke Micro-UIs:
|
|
||||||
- Render shortcuts as physical keys using `<kbd>` tags: `border: 1px solid #EAEAEA`, `border-radius: 4px`, `background: #F7F6F3`, using the Monospace font.
|
|
||||||
- Faux-OS Window Chrome:
|
|
||||||
- When mocking up software, wrap it in a minimalist container with a white top bar containing three small, light gray circles (replicating macOS window controls).
|
|
||||||
|
|
||||||
## 6. Iconography & Imagery Directives
|
|
||||||
- System Icons: Use "Phosphor Icons (Bold or Fill weights)" or "Radix UI Icons" for a technical, slightly thicker-stroke aesthetic. Standardize stroke width across all icons.
|
|
||||||
- Illustrations: Monochromatic, rough continuous-line ink sketches on a white background, featuring a single offset geometric shape filled with a muted pastel color.
|
|
||||||
- Photography: Use high-quality, desaturated images with a warm tone. Apply subtle overlays (`opacity: 0.04` warm grain) to blend photos into the monochrome palette. Never use oversaturated stock photos. Use reliable placeholders like `https://picsum.photos/seed/{context}/1200/800` when real assets are unavailable.
|
|
||||||
- Hero & Section Backgrounds: Sections should not feel empty and flat. Use subtle full-width background imagery at very low opacity, soft radial light spots (`radial-gradient` with warm tones at `opacity: 0.03`), or minimal geometric line patterns to add depth without breaking the clean aesthetic.
|
|
||||||
|
|
||||||
## 7. Subtle Motion & Micro-Animations
|
|
||||||
Motion should feel invisible — present but never distracting. The goal is quiet sophistication, not spectacle.
|
|
||||||
- Scroll Entry: Elements fade in gently as they enter the viewport. Use `translateY(12px)` + `opacity: 0` resolving over `600ms` with `cubic-bezier(0.16, 1, 0.3, 1)`. Use `IntersectionObserver`, never `window.addEventListener('scroll')`.
|
|
||||||
- Hover States: Cards lift with an ultra-subtle shadow shift (`box-shadow` transitioning from `0 0 0` to `0 2px 8px rgba(0,0,0,0.04)` over `200ms`). Buttons respond with `scale(0.98)` on `:active`.
|
|
||||||
- Staggered Reveals: Lists and grid items enter with a cascade delay (`animation-delay: calc(var(--index) * 80ms)`). Never mount everything at once.
|
|
||||||
- Background Ambient Motion: Optional. A single, very slow-moving radial gradient blob (`animation-duration: 20s+`, `opacity: 0.02-0.04`) drifting behind hero sections. Must be applied to a `position: fixed; pointer-events: none` layer. Never on scrolling containers.
|
|
||||||
- Performance: Animate exclusively via `transform` and `opacity`. No layout-triggering properties (`top`, `left`, `width`, `height`). Use `will-change: transform` sparingly and only on actively animating elements.
|
|
||||||
|
|
||||||
## 8. Execution Protocol
|
|
||||||
When tasked with writing frontend code (HTML, React, Tailwind, Vue) or designing a layout:
|
|
||||||
1. Establish the macro-whitespace first. Use massive vertical padding between sections (e.g., `py-24` or `py-32` in Tailwind).
|
|
||||||
2. Constrain the main typography content width to `max-w-4xl` or `max-w-5xl`.
|
|
||||||
3. Apply the custom typographic hierarchy and monochromatic color variables immediately.
|
|
||||||
4. Ensure every card, divider, and border adheres strictly to the `1px solid #EAEAEA` rule.
|
|
||||||
5. Add scroll-entry animations to all major content blocks.
|
|
||||||
6. Ensure sections have visual depth through imagery, ambient gradients, or subtle textures — no empty flat backgrounds.
|
|
||||||
7. Provide code that reflects this high-end, uncluttered, editorial aesthetic natively without requiring manual adjustments.
|
|
||||||
@@ -1,178 +0,0 @@
|
|||||||
---
|
|
||||||
name: redesign-existing-projects
|
|
||||||
description: Upgrades existing websites and apps to premium quality. Audits current design, identifies generic AI patterns, and applies high-end design standards without breaking functionality. Works with any CSS framework or vanilla CSS.
|
|
||||||
---
|
|
||||||
|
|
||||||
# Redesign Skill
|
|
||||||
|
|
||||||
## How This Works
|
|
||||||
|
|
||||||
When applied to an existing project, follow this sequence:
|
|
||||||
|
|
||||||
1. **Scan** — Read the codebase. Identify the framework, styling method (Tailwind, vanilla CSS, styled-components, etc.), and current design patterns.
|
|
||||||
2. **Diagnose** — Run through the audit below. List every generic pattern, weak point, and missing state you find.
|
|
||||||
3. **Fix** — Apply targeted upgrades working with the existing stack. Do not rewrite from scratch. Improve what's there.
|
|
||||||
|
|
||||||
## Design Audit
|
|
||||||
|
|
||||||
### Typography
|
|
||||||
|
|
||||||
Check for these problems and fix them:
|
|
||||||
|
|
||||||
- **Browser default fonts or Inter everywhere.** Replace with a font that has character. Good options: `Geist`, `Outfit`, `Cabinet Grotesk`, `Satoshi`. For editorial/creative projects, pair a serif header with a sans-serif body.
|
|
||||||
- **Headlines lack presence.** Increase size for display text, tighten letter-spacing, reduce line-height. Headlines should feel heavy and intentional.
|
|
||||||
- **Body text too wide.** Limit paragraph width to roughly 65 characters. Increase line-height for readability.
|
|
||||||
- **Only Regular (400) and Bold (700) weights used.** Introduce Medium (500) and SemiBold (600) for more subtle hierarchy.
|
|
||||||
- **Numbers in proportional font.** Use a monospace font or enable tabular figures (`font-variant-numeric: tabular-nums`) for data-heavy interfaces.
|
|
||||||
- **Missing letter-spacing adjustments.** Use negative tracking for large headers, positive tracking for small caps or labels.
|
|
||||||
- **All-caps subheaders everywhere.** Try lowercase italics, sentence case, or small-caps instead.
|
|
||||||
- **Orphaned words.** Single words sitting alone on the last line. Fix with `text-wrap: balance` or `text-wrap: pretty`.
|
|
||||||
|
|
||||||
### Color and Surfaces
|
|
||||||
|
|
||||||
- **Pure `#000000` background.** Replace with off-black, dark charcoal, or tinted dark (`#0a0a0a`, `#121212`, or a dark navy).
|
|
||||||
- **Oversaturated accent colors.** Keep saturation below 80%. Desaturate accents so they blend with neutrals instead of screaming.
|
|
||||||
- **More than one accent color.** Pick one. Remove the rest. Consistency beats variety.
|
|
||||||
- **Mixing warm and cool grays.** Stick to one gray family. Tint all grays with a consistent hue (warm or cool, not both).
|
|
||||||
- **Purple/blue "AI gradient" aesthetic.** This is the most common AI design fingerprint. Replace with neutral bases and a single, considered accent.
|
|
||||||
- **Generic `box-shadow`.** Tint shadows to match the background hue. Use colored shadows (e.g., dark blue shadow on a blue background) instead of pure black at low opacity.
|
|
||||||
- **Flat design with zero texture.** Add subtle noise, grain, or micro-patterns to backgrounds. Pure flat vectors feel sterile.
|
|
||||||
- **Perfectly even gradients.** Break the uniformity with radial gradients, noise overlays, or mesh gradients instead of standard linear 45-degree fades.
|
|
||||||
- **Inconsistent lighting direction.** Audit all shadows to ensure they suggest a single, consistent light source.
|
|
||||||
- **Random dark sections in a light mode page (or vice versa).** A single dark-background section breaking an otherwise light page looks like a copy-paste accident. Either commit to a full dark mode or keep a consistent background tone throughout. If contrast is needed, use a slightly darker shade of the same palette — not a sudden jump to `#111` in the middle of a cream page.
|
|
||||||
- **Empty, flat sections with no visual depth.** Sections that are just text on a plain background feel unfinished. Add high-quality background imagery (blurred, overlaid, or masked), subtle patterns, or ambient gradients. Use reliable placeholder sources like `https://picsum.photos/seed/{name}/1920/1080` when real assets are not available. Experiment with background images behind hero sections, feature blocks, or CTAs — even a subtle full-width photo at low opacity adds presence.
|
|
||||||
|
|
||||||
### Layout
|
|
||||||
|
|
||||||
- **Everything centered and symmetrical.** Break symmetry with offset margins, mixed aspect ratios, or left-aligned headers over centered content.
|
|
||||||
- **Three equal card columns as feature row.** This is the most generic AI layout. Replace with a 2-column zig-zag, asymmetric grid, horizontal scroll, or masonry layout.
|
|
||||||
- **Using `height: 100vh` for full-screen sections.** Replace with `min-height: 100dvh` to prevent layout jumping on mobile browsers (iOS Safari viewport bug).
|
|
||||||
- **Complex flexbox percentage math.** Replace with CSS Grid for reliable multi-column structures.
|
|
||||||
- **No max-width container.** Add a container constraint (around 1200-1440px) with auto margins so content doesn't stretch edge-to-edge on wide screens.
|
|
||||||
- **Cards of equal height forced by flexbox.** Allow variable heights or use masonry when content varies in length.
|
|
||||||
- **Uniform border-radius on everything.** Vary the radius: tighter on inner elements, softer on containers.
|
|
||||||
- **No overlap or depth.** Elements sit flat next to each other. Use negative margins to create layering and visual depth.
|
|
||||||
- **Symmetrical vertical padding.** Top and bottom padding are always identical. Adjust optically — bottom padding often needs to be slightly larger.
|
|
||||||
- **Dashboard always has a left sidebar.** Try top navigation, a floating command menu, or a collapsible panel instead.
|
|
||||||
- **Missing whitespace.** Double the spacing. Let the design breathe. Dense layouts work for data dashboards, not for marketing pages.
|
|
||||||
- **Buttons not bottom-aligned in card groups.** When cards have different content lengths, CTAs end up at random heights. Pin buttons to the bottom of each card so they form a clean horizontal line regardless of content above.
|
|
||||||
- **Feature lists starting at different vertical positions.** In pricing tables or comparison cards, the list of features should start at the same Y position across all columns. Use consistent spacing above the list or fixed-height title/price blocks.
|
|
||||||
- **Inconsistent vertical rhythm in side-by-side elements.** When placing cards, columns, or panels next to each other, align shared elements (titles, descriptions, prices, buttons) across all items. Misaligned baselines make the layout look broken.
|
|
||||||
- **Mathematical alignment that looks optically wrong.** Centering by the math doesn't always look centered to the eye. Icons next to text, play buttons in circles, or text in buttons often need 1-2px optical adjustments to feel right.
|
|
||||||
|
|
||||||
### Interactivity and States
|
|
||||||
|
|
||||||
- **No hover states on buttons.** Add background shift, slight scale, or translate on hover.
|
|
||||||
- **No active/pressed feedback.** Add a subtle `scale(0.98)` or `translateY(1px)` on press to simulate a physical click.
|
|
||||||
- **Instant transitions with zero duration.** Add smooth transitions (200-300ms) to all interactive elements.
|
|
||||||
- **Missing focus ring.** Ensure visible focus indicators for keyboard navigation. This is an accessibility requirement, not optional.
|
|
||||||
- **No loading states.** Replace generic circular spinners with skeleton loaders that match the layout shape.
|
|
||||||
- **No empty states.** An empty dashboard showing nothing is a missed opportunity. Design a composed "getting started" view.
|
|
||||||
- **No error states.** Add clear, inline error messages for forms. Do not use `window.alert()`.
|
|
||||||
- **Dead links.** Buttons that link to `#`. Either link to real destinations or visually disable them.
|
|
||||||
- **No indication of current page in navigation.** Style the active nav link differently so users know where they are.
|
|
||||||
- **Scroll jumping.** Anchor clicks jump instantly. Add `scroll-behavior: smooth`.
|
|
||||||
- **Animations using `top`, `left`, `width`, `height`.** Switch to `transform` and `opacity` for GPU-accelerated, smooth animation.
|
|
||||||
|
|
||||||
### Content
|
|
||||||
|
|
||||||
- **Generic names like "John Doe" or "Jane Smith".** Use diverse, realistic-sounding names.
|
|
||||||
- **Fake round numbers like `99.99%`, `50%`, `$100.00`.** Use organic, messy data: `47.2%`, `$99.00`, `+1 (312) 847-1928`.
|
|
||||||
- **Placeholder company names like "Acme Corp", "Nexus", "SmartFlow".** Invent contextual, believable brand names.
|
|
||||||
- **AI copywriting cliches.** Never use "Elevate", "Seamless", "Unleash", "Next-Gen", "Game-changer", "Delve", "Tapestry", or "In the world of...". Write plain, specific language.
|
|
||||||
- **Exclamation marks in success messages.** Remove them. Be confident, not loud.
|
|
||||||
- **"Oops!" error messages.** Be direct: "Connection failed. Please try again."
|
|
||||||
- **Passive voice.** Use active voice: "We couldn't save your changes" instead of "Mistakes were made."
|
|
||||||
- **All blog post dates identical.** Randomize dates to appear real.
|
|
||||||
- **Same avatar image for multiple users.** Use unique assets for every distinct person.
|
|
||||||
- **Lorem Ipsum.** Never use placeholder latin text. Write real draft copy.
|
|
||||||
- **Title Case On Every Header.** Use sentence case instead.
|
|
||||||
|
|
||||||
### Component Patterns
|
|
||||||
|
|
||||||
- **Generic card look (border + shadow + white background).** Remove the border, or use only background color, or use only spacing. Cards should exist only when elevation communicates hierarchy.
|
|
||||||
- **Always one filled button + one ghost button.** Add text links or tertiary styles to reduce visual noise.
|
|
||||||
- **Pill-shaped "New" and "Beta" badges.** Try square badges, flags, or plain text labels.
|
|
||||||
- **Accordion FAQ sections.** Use a side-by-side list, searchable help, or inline progressive disclosure.
|
|
||||||
- **3-card carousel testimonials with dots.** Replace with a masonry wall, embedded social posts, or a single rotating quote.
|
|
||||||
- **Pricing table with 3 towers.** Highlight the recommended tier with color and emphasis, not just extra height.
|
|
||||||
- **Modals for everything.** Use inline editing, slide-over panels, or expandable sections instead of popups for simple actions.
|
|
||||||
- **Avatar circles exclusively.** Try squircles or rounded squares for a less generic look.
|
|
||||||
- **Light/dark toggle always a sun/moon switch.** Use a dropdown, system preference detection, or integrate it into settings.
|
|
||||||
- **Footer link farm with 4 columns.** Simplify. Focus on main navigational paths and legally required links.
|
|
||||||
|
|
||||||
### Iconography
|
|
||||||
|
|
||||||
- **Lucide or Feather icons exclusively.** These are the "default" AI icon choice. Use Phosphor, Heroicons, or a custom set for differentiation.
|
|
||||||
- **Rocketship for "Launch", shield for "Security".** Replace cliche metaphors with less obvious icons (bolt, fingerprint, spark, vault).
|
|
||||||
- **Inconsistent stroke widths across icons.** Audit all icons and standardize to one stroke weight.
|
|
||||||
- **Missing favicon.** Always include a branded favicon.
|
|
||||||
- **Stock "diverse team" photos.** Use real team photos, candid shots, or a consistent illustration style instead of uncanny stock imagery.
|
|
||||||
|
|
||||||
### Code Quality
|
|
||||||
|
|
||||||
- **Div soup.** Use semantic HTML: `<nav>`, `<main>`, `<article>`, `<aside>`, `<section>`.
|
|
||||||
- **Inline styles mixed with CSS classes.** Move all styling to the project's styling system.
|
|
||||||
- **Hardcoded pixel widths.** Use relative units (`%`, `rem`, `em`, `max-width`) for flexible layouts.
|
|
||||||
- **Missing alt text on images.** Describe image content for screen readers. Never leave `alt=""` or `alt="image"` on meaningful images.
|
|
||||||
- **Arbitrary z-index values like `9999`.** Establish a clean z-index scale in the theme/variables.
|
|
||||||
- **Commented-out dead code.** Remove all debug artifacts before shipping.
|
|
||||||
- **Import hallucinations.** Check that every import actually exists in `package.json` or the project dependencies.
|
|
||||||
- **Missing meta tags.** Add proper `<title>`, `description`, `og:image`, and social sharing meta tags.
|
|
||||||
|
|
||||||
### Strategic Omissions (What AI Typically Forgets)
|
|
||||||
|
|
||||||
- **No legal links.** Add privacy policy and terms of service links in the footer.
|
|
||||||
- **No "back" navigation.** Dead ends in user flows. Every page needs a way back.
|
|
||||||
- **No custom 404 page.** Design a helpful, branded "page not found" experience.
|
|
||||||
- **No form validation.** Add client-side validation for emails, required fields, and format checks.
|
|
||||||
- **No "skip to content" link.** Essential for keyboard users. Add a hidden skip-link.
|
|
||||||
- **No cookie consent.** If required by jurisdiction, add a compliant consent banner.
|
|
||||||
|
|
||||||
## Upgrade Techniques
|
|
||||||
|
|
||||||
When upgrading a project, pull from these high-impact techniques to replace generic patterns:
|
|
||||||
|
|
||||||
### Typography Upgrades
|
|
||||||
- **Variable font animation.** Interpolate weight or width on scroll or hover for text that feels alive.
|
|
||||||
- **Outlined-to-fill transitions.** Text starts as a stroke outline and fills with color on scroll entry or interaction.
|
|
||||||
- **Text mask reveals.** Large typography acting as a window to video or animated imagery behind it.
|
|
||||||
|
|
||||||
### Layout Upgrades
|
|
||||||
- **Broken grid / asymmetry.** Elements that deliberately ignore column structure — overlapping, bleeding off-screen, or offset with calculated randomness.
|
|
||||||
- **Whitespace maximization.** Aggressive use of negative space to force focus on a single element.
|
|
||||||
- **Parallax card stacks.** Sections that stick and physically stack over each other during scroll.
|
|
||||||
- **Split-screen scroll.** Two halves of the screen sliding in opposite directions.
|
|
||||||
|
|
||||||
### Motion Upgrades
|
|
||||||
- **Smooth scroll with inertia.** Decouple scrolling from browser defaults for a heavier, cinematic feel.
|
|
||||||
- **Staggered entry.** Elements cascade in with slight delays, combining Y-axis translation with opacity fade. Never mount everything at once.
|
|
||||||
- **Spring physics.** Replace linear easing with spring-based motion for a natural, weighty feel on all interactive elements.
|
|
||||||
- **Scroll-driven reveals.** Content entering through expanding masks, wipes, or draw-on SVG paths tied to scroll progress.
|
|
||||||
|
|
||||||
### Surface Upgrades
|
|
||||||
- **True glassmorphism.** Go beyond `backdrop-filter: blur`. Add a 1px inner border and a subtle inner shadow to simulate edge refraction.
|
|
||||||
- **Spotlight borders.** Card borders that illuminate dynamically under the cursor.
|
|
||||||
- **Grain and noise overlays.** A fixed, pointer-events-none overlay with subtle noise to break digital flatness.
|
|
||||||
- **Colored, tinted shadows.** Shadows that carry the hue of the background rather than using generic black.
|
|
||||||
|
|
||||||
## Fix Priority
|
|
||||||
|
|
||||||
Apply changes in this order for maximum visual impact with minimum risk:
|
|
||||||
|
|
||||||
1. **Font swap** — biggest instant improvement, lowest risk
|
|
||||||
2. **Color palette cleanup** — remove clashing or oversaturated colors
|
|
||||||
3. **Hover and active states** — makes the interface feel alive
|
|
||||||
4. **Layout and spacing** — proper grid, max-width, consistent padding
|
|
||||||
5. **Replace generic components** — swap cliche patterns for modern alternatives
|
|
||||||
6. **Add loading, empty, and error states** — makes it feel finished
|
|
||||||
7. **Polish typography scale and spacing** — the premium final touch
|
|
||||||
|
|
||||||
## Rules
|
|
||||||
|
|
||||||
- Work with the existing tech stack. Do not migrate frameworks or styling libraries.
|
|
||||||
- Do not break existing functionality. Test after every change.
|
|
||||||
- Before importing any new library, check the project's dependency file first.
|
|
||||||
- If the project uses Tailwind, check the version (v3 vs v4) before modifying config.
|
|
||||||
- If the project has no framework, use vanilla CSS.
|
|
||||||
- Keep changes reviewable and focused. Small, targeted improvements over big rewrites.
|
|
||||||
@@ -1,121 +0,0 @@
|
|||||||
# Design System: Taste Standard
|
|
||||||
**Skill:** stitch-design-taste
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Configuration — Set Your Style
|
|
||||||
Adjust these dials before using this design system. They control how creative, dense, and animated the output should be. Pick the level that fits your project.
|
|
||||||
|
|
||||||
| Dial | Level | Description |
|
|
||||||
|------|-------|-------------|
|
|
||||||
| **Creativity** | `8` | `1` = Ultra-minimal, Swiss, silent, monochrome. `5` = Balanced, clean but with personality. `10` = Expressive, editorial, bold typography experiments, inline images in headlines, strong asymmetry. Default: `8` |
|
|
||||||
| **Density** | `4` | `1` = Gallery-airy, massive whitespace. `5` = Balanced sections. `10` = Cockpit-dense, data-heavy. Default: `4` |
|
|
||||||
| **Variance** | `8` | `1` = Predictable, symmetric grids. `5` = Subtle offsets. `10` = Artsy chaotic, no two sections alike. Default: `8` |
|
|
||||||
| **Motion Intent** | `6` | `1` = Static, no animation noted. `5` = Subtle hover/entrance cues. `10` = Cinematic orchestration noted in every component. Default: `6` |
|
|
||||||
|
|
||||||
> **How to use:** Change the numbers above to match your project's vibe. At **Creativity 1–3**, the system produces clean, quiet, Notion-like interfaces. At **Creativity 7–10**, expect inline image typography, dramatic scale contrast, and strong editorial layouts. The rest of the rules below adapt to your chosen levels.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 1. Visual Theme & Atmosphere
|
|
||||||
A restrained, gallery-airy interface with confident asymmetric layouts and fluid spring-physics motion. The atmosphere is clinical yet warm — like a well-lit architecture studio where every element earns its place through function. Density is balanced (Level 4), variance runs high (Level 8) to prevent symmetrical boredom, and motion is fluid but never theatrical (Level 6). The overall impression: expensive, intentional, alive.
|
|
||||||
|
|
||||||
## 2. Color Palette & Roles
|
|
||||||
- **Canvas White** (#F9FAFB) — Primary background surface. Warm-neutral, never clinical blue-white
|
|
||||||
- **Pure Surface** (#FFFFFF) — Card and container fill. Used with whisper shadow for elevation
|
|
||||||
- **Charcoal Ink** (#18181B) — Primary text. Zinc-950 depth — never pure black
|
|
||||||
- **Steel Secondary** (#71717A) — Body text, descriptions, metadata. Zinc-500 warmth
|
|
||||||
- **Muted Slate** (#94A3B8) — Tertiary text, timestamps, disabled states
|
|
||||||
- **Whisper Border** (rgba(226,232,240,0.5)) — Card borders, structural 1px lines. Semi-transparent for depth
|
|
||||||
- **Diffused Shadow** (rgba(0,0,0,0.05)) — Card elevation. Wide-spreading, 40px blur, -15px offset. Never harsh
|
|
||||||
|
|
||||||
### Accent Selection (Pick ONE per project)
|
|
||||||
- **Emerald Signal** (#10B981) — For growth, success, positive data dashboards
|
|
||||||
- **Electric Blue** (#3B82F6) — For productivity, SaaS, developer tools
|
|
||||||
- **Deep Rose** (#E11D48) — For creative, editorial, fashion-adjacent projects
|
|
||||||
- **Amber Warmth** (#F59E0B) — For community, social, warm-toned products
|
|
||||||
|
|
||||||
### Banned Colors
|
|
||||||
- Purple/Violet neon gradients — the "AI Purple" aesthetic
|
|
||||||
- Pure Black (#000000) — always Off-Black or Zinc-950
|
|
||||||
- Oversaturated accents above 80% saturation
|
|
||||||
- Mixed warm/cool gray systems within one project
|
|
||||||
|
|
||||||
## 3. Typography Rules
|
|
||||||
- **Display:** `Geist`, `Satoshi`, `Cabinet Grotesk`, or `Outfit` — Track-tight (`-0.025em`), controlled fluid scale, weight-driven hierarchy (700–900). Not screaming. Leading compressed (`1.1`). Alternatives forced — `Inter` is BANNED for premium contexts
|
|
||||||
- **Body:** Same family at weight 400 — Relaxed leading (`1.65`), 65ch max-width, Steel Secondary color (#71717A)
|
|
||||||
- **Mono:** `Geist Mono` or `JetBrains Mono` — For code blocks, metadata, timestamps. When density exceeds Level 7, all numbers switch to monospace
|
|
||||||
- **Scale:** Display at `clamp(2.25rem, 5vw, 3.75rem)`. Body at `1rem/1.125rem`. Mono metadata at `0.8125rem`
|
|
||||||
|
|
||||||
### Banned Fonts
|
|
||||||
- `Inter` — banned everywhere in premium/creative contexts
|
|
||||||
- Generic serif fonts (`Times New Roman`, `Georgia`, `Garamond`, `Palatino`) — BANNED. If serif is needed for editorial/creative, use only distinctive modern serifs like `Fraunces`, `Gambarino`, `Editorial New`, or `Instrument Serif`. Never use default browser serif stacks. Serif is always BANNED in dashboards or software UIs regardless
|
|
||||||
|
|
||||||
## 4. Component Stylings
|
|
||||||
* **Buttons:** Flat surface, no outer glow. Primary: accent fill with white text. Secondary: ghost/outline. Active state: `-1px translateY` or `scale(0.98)` for tactile push. Hover: subtle background shift, never glow
|
|
||||||
* **Cards/Containers:** Generously rounded corners (`2.5rem`). Pure white fill. Whisper border (`1px`, semi-transparent). Diffused shadow (`0 20px 40px -15px rgba(0,0,0,0.05)`). Internal padding `2rem–2.5rem`. Used ONLY when elevation communicates hierarchy — high-density layouts replace cards with `border-top` dividers or negative space
|
|
||||||
* **Inputs/Forms:** Label positioned above input. Helper text optional. Error text below in Deep Rose. Focus ring in accent color, `2px` offset. No floating labels. Standard `0.5rem` gap between label-input-error stack
|
|
||||||
* **Navigation:** Sleek, sticky. Icons scale on hover (Dock Magnification optional). No hamburger on desktop. Clean horizontal with generous spacing
|
|
||||||
* **Loaders:** Skeletal shimmer matching exact layout dimensions and rounded corners. Shifting light reflection across placeholder shapes. Never circular spinners
|
|
||||||
* **Empty States:** Composed illustration or icon composition with guidance text. Never just "No data found"
|
|
||||||
* **Error States:** Inline, contextual. Red accent underline or border. Clear recovery action
|
|
||||||
|
|
||||||
## 5. Hero Section
|
|
||||||
The Hero is the first impression — it must be striking, creative, and never generic.
|
|
||||||
- **Inline Image Typography:** Embed small, contextual photos or visuals directly between words or letters in the headline. Example: "We build [photo of hands typing] digital [photo of screen] products" — images sit inline at type-height, rounded, acting as visual punctuation between words. This is the signature creative technique
|
|
||||||
- **No Overlapping Elements:** Text must never overlap images or other text. Every element has its own clear spatial zone. No z-index stacking of content layers, no absolute-positioned headlines over images. Clean separation always
|
|
||||||
- **No Filler Text:** "Scroll to explore", "Swipe down", scroll arrow icons, bouncing chevrons, and any instructional UI chrome are BANNED. The user knows how to scroll. Let the content pull them in naturally
|
|
||||||
- **Asymmetric Structure:** Centered Hero layouts are BANNED at this variance level. Use Split Screen (50/50), Left-Aligned text / Right visual, or Asymmetric Whitespace with large empty zones
|
|
||||||
- **CTA Restraint:** Maximum one primary CTA button. No secondary "Learn more" links. No redundant micro-copy below the headline
|
|
||||||
|
|
||||||
## 6. Layout Principles
|
|
||||||
- **Grid-First:** CSS Grid for all structural layouts. Never flexbox percentage math (`calc(33% - 1rem)` is BANNED)
|
|
||||||
- **No Overlapping:** Elements must never overlap each other. No absolute-positioned layers stacking content on content. Every element occupies its own grid cell or flow position. Clean, separated spatial zones
|
|
||||||
- **Feature Sections:** The "3 equal cards in a row" pattern is BANNED. Use 2-column Zig-Zag, asymmetric Bento grids (2fr 1fr 1fr), or horizontal scroll galleries
|
|
||||||
- **Containment:** All content within `max-width: 1400px`, centered. Generous horizontal padding (`1rem` mobile, `2rem` tablet, `4rem` desktop)
|
|
||||||
- **Full-Height:** Use `min-height: 100dvh` — never `height: 100vh` (iOS Safari address bar jump)
|
|
||||||
- **Bento Architecture:** For feature grids, use Row 1: 3 columns | Row 2: 2 columns (70/30 split). Each tile contains a perpetual micro-animation
|
|
||||||
|
|
||||||
## 7. Responsive Rules
|
|
||||||
Every screen must work flawlessly across all viewports. **Responsive is not optional — it is a hard requirement. Every single element must be tested at 375px, 768px, and 1440px.**
|
|
||||||
- **Mobile-First Collapse (< 768px):** All multi-column layouts collapse to a strict single column. `width: 100%`, `padding: 1rem`, `gap: 1.5rem`. No exceptions
|
|
||||||
- **No Horizontal Scroll:** Horizontal overflow on mobile is a critical failure. All elements must fit within viewport width. If any element causes horizontal scroll, the design is broken
|
|
||||||
- **Typography Scaling:** Headlines scale down gracefully via `clamp()`. Body text stays `1rem` minimum. Never shrink body below `14px`. Headlines must remain readable on 375px screens
|
|
||||||
- **Touch Targets:** All interactive elements minimum `44px` tap target. Generous spacing between clickable items. Buttons must be full-width on mobile
|
|
||||||
- **Image Behavior:** Hero and inline images scale proportionally. Inline typography images (photos between words) stack below the headline on mobile instead of inline
|
|
||||||
- **Navigation:** Desktop horizontal nav collapses to a clean mobile menu (slide-in or full-screen overlay). No tiny hamburger icons without labels
|
|
||||||
- **Cards & Grids:** Bento grids and asymmetric layouts revert to stacked single-column cards with full-width. Maintain internal padding (`1rem`)
|
|
||||||
- **Spacing Consistency:** Vertical section gaps reduce proportionally on mobile (`clamp(3rem, 8vw, 6rem)`). Never cramped, never excessively airy
|
|
||||||
- **Testing Viewports:** Designs must be verified at: `375px` (iPhone SE), `390px` (iPhone 14), `768px` (iPad), `1024px` (small laptop), `1440px` (desktop)
|
|
||||||
|
|
||||||
## 8. Motion & Interaction (Code-Phase Intent)
|
|
||||||
> **Note:** Stitch generates static screens — it does not animate. This section documents the **intended motion behavior** so that the coding agent (Antigravity, Cursor, etc.) knows exactly how to implement animations when building the exported design into a live product.
|
|
||||||
|
|
||||||
- **Physics Engine:** Spring-based exclusively. `stiffness: 100, damping: 20`. No linear easing anywhere. Premium, weighty feel on all interactive elements
|
|
||||||
- **Perpetual Micro-Loops:** Every active dashboard component has an infinite-loop state — Pulse on status dots, Typewriter on search bars, Float on feature icons, Shimmer on loading states
|
|
||||||
- **Staggered Orchestration:** Lists and grids mount with cascaded delays (`animation-delay: calc(var(--index) * 100ms)`). Waterfall reveals, never instant mount
|
|
||||||
- **Layout Transitions:** Smooth re-ordering via shared element IDs. Items swap positions with physics, simulating real-time intelligence
|
|
||||||
- **Hardware Rules:** Animate ONLY `transform` and `opacity`. Never `top`, `left`, `width`, `height`. Grain/noise filters on fixed, pointer-events-none pseudo-elements only
|
|
||||||
- **Performance:** CPU-heavy perpetual animations isolated in microscopic leaf components. Never trigger parent re-renders. Target 60fps minimum
|
|
||||||
|
|
||||||
## 9. Anti-Patterns (Banned)
|
|
||||||
- No emojis — anywhere in UI, code, or alt text
|
|
||||||
- No `Inter` font — use `Geist`, `Outfit`, `Cabinet Grotesk`, `Satoshi`
|
|
||||||
- No generic serif fonts (`Times New Roman`, `Georgia`, `Garamond`) — if serif is needed, use distinctive modern serifs only (`Fraunces`, `Instrument Serif`)
|
|
||||||
- No pure black (`#000000`) — Off-Black or Zinc-950 only
|
|
||||||
- No neon outer glows or default box-shadow glows
|
|
||||||
- No oversaturated accent colors above 80%
|
|
||||||
- No excessive gradient text on large headers
|
|
||||||
- No custom mouse cursors
|
|
||||||
- No overlapping elements — text never overlaps images or other content. Clean spatial separation always
|
|
||||||
- No 3-column equal card layouts for features
|
|
||||||
- No centered Hero sections (at this variance level)
|
|
||||||
- No filler UI text: "Scroll to explore", "Swipe down", "Discover more below", scroll arrows, bouncing chevrons — all BANNED
|
|
||||||
- No generic names: "John Doe", "Sarah Chan", "Acme", "Nexus", "SmartFlow"
|
|
||||||
- No fake round numbers: `99.99%`, `50%`, `1234567` — use organic data: `47.2%`, `+1 (312) 847-1928`
|
|
||||||
- No AI copywriting clichés: "Elevate", "Seamless", "Unleash", "Next-Gen", "Revolutionize"
|
|
||||||
- No broken Unsplash links — use `picsum.photos/seed/{id}/800/600` or SVG UI Avatars
|
|
||||||
- No generic `shadcn/ui` defaults — customize radii, colors, shadows to match this system
|
|
||||||
- No `z-index` spam — use only for Navbar, Modal, Overlay layer contexts
|
|
||||||
- No `h-screen` — always `min-h-[100dvh]`
|
|
||||||
- No circular loading spinners — skeletal shimmer only
|
|
||||||
@@ -1,184 +0,0 @@
|
|||||||
---
|
|
||||||
name: stitch-design-taste
|
|
||||||
description: Semantic Design System Skill for Google Stitch. Generates agent-friendly DESIGN.md files that enforce premium, anti-generic UI standards — strict typography, calibrated color, asymmetric layouts, perpetual micro-motion, and hardware-accelerated performance.
|
|
||||||
---
|
|
||||||
|
|
||||||
# Stitch Design Taste — Semantic Design System Skill
|
|
||||||
|
|
||||||
## Overview
|
|
||||||
This skill generates `DESIGN.md` files optimized for Google Stitch screen generation. It translates the battle-tested anti-slop frontend engineering directives into Stitch's native semantic design language — descriptive, natural-language rules paired with precise values that Stitch's AI agent can interpret to produce premium, non-generic interfaces.
|
|
||||||
|
|
||||||
The generated `DESIGN.md` serves as the **single source of truth** for prompting Stitch to generate new screens that align with a curated, high-agency design language. Stitch interprets design through **"Visual Descriptions"** supported by specific color values, typography specs, and component behaviors.
|
|
||||||
|
|
||||||
## Prerequisites
|
|
||||||
- Access to Google Stitch via [labs.google.com/stitch](https://labs.google.com/stitch)
|
|
||||||
- Optionally: Stitch MCP Server for programmatic integration with Cursor, Antigravity, or Gemini CLI
|
|
||||||
|
|
||||||
## The Goal
|
|
||||||
Generate a `DESIGN.md` file that encodes:
|
|
||||||
1. **Visual atmosphere** — the mood, density, and design philosophy
|
|
||||||
2. **Color calibration** — neutrals, accents, and banned patterns with hex codes
|
|
||||||
3. **Typographic architecture** — font stacks, scale hierarchy, and anti-patterns
|
|
||||||
4. **Component behaviors** — buttons, cards, inputs with interaction states
|
|
||||||
5. **Layout principles** — grid systems, spacing philosophy, responsive strategy
|
|
||||||
6. **Motion philosophy** — animation engine specs, spring physics, perpetual micro-interactions
|
|
||||||
7. **Anti-patterns** — explicit list of banned AI design clichés
|
|
||||||
|
|
||||||
## Analysis & Synthesis Instructions
|
|
||||||
|
|
||||||
### 1. Define the Atmosphere
|
|
||||||
Evaluate the target project's intent. Use evocative adjectives from the taste spectrum:
|
|
||||||
- **Density:** "Art Gallery Airy" (1–3) → "Daily App Balanced" (4–7) → "Cockpit Dense" (8–10)
|
|
||||||
- **Variance:** "Predictable Symmetric" (1–3) → "Offset Asymmetric" (4–7) → "Artsy Chaotic" (8–10)
|
|
||||||
- **Motion:** "Static Restrained" (1–3) → "Fluid CSS" (4–7) → "Cinematic Choreography" (8–10)
|
|
||||||
|
|
||||||
Default baseline: Variance 8, Motion 6, Density 4. Adapt dynamically based on user's vibe description.
|
|
||||||
|
|
||||||
### 2. Map the Color Palette
|
|
||||||
For each color provide: **Descriptive Name** + **Hex Code** + **Functional Role**.
|
|
||||||
|
|
||||||
**Mandatory constraints:**
|
|
||||||
- Maximum 1 accent color. Saturation below 80%
|
|
||||||
- The "AI Purple/Blue Neon" aesthetic is strictly BANNED — no purple button glows, no neon gradients
|
|
||||||
- Use absolute neutral bases (Zinc/Slate) with high-contrast singular accents
|
|
||||||
- Stick to one palette for the entire output — no warm/cool gray fluctuation
|
|
||||||
- Never use pure black (`#000000`) — use Off-Black, Zinc-950, or Charcoal
|
|
||||||
|
|
||||||
### 3. Establish Typography Rules
|
|
||||||
- **Display/Headlines:** Track-tight, controlled scale. Not screaming. Hierarchy through weight and color, not just massive size
|
|
||||||
- **Body:** Relaxed leading, max 65 characters per line
|
|
||||||
- **Font Selection:** `Inter` is BANNED for premium/creative contexts. Force unique character: `Geist`, `Outfit`, `Cabinet Grotesk`, or `Satoshi`
|
|
||||||
- **Serif Ban:** Generic serif fonts (`Times New Roman`, `Georgia`, `Garamond`, `Palatino`) are BANNED. If serif is needed for editorial/creative contexts, use only distinctive modern serifs: `Fraunces`, `Gambarino`, `Editorial New`, or `Instrument Serif`. Serif is always BANNED in dashboards or software UIs
|
|
||||||
- **Dashboard Constraint:** Use Sans-Serif pairings exclusively (`Geist` + `Geist Mono` or `Satoshi` + `JetBrains Mono`)
|
|
||||||
- **High-Density Override:** When density exceeds 7, all numbers must use Monospace
|
|
||||||
|
|
||||||
### 4. Define the Hero Section
|
|
||||||
The Hero is the first impression and must be creative, striking, and never generic:
|
|
||||||
- **Inline Image Typography:** Embed small, contextual photos or visuals directly between words or letters in the headline. Images sit inline at type-height, rounded, acting as visual punctuation. This is the signature creative technique
|
|
||||||
- **No Overlapping:** Text must never overlap images or other text. Every element occupies its own clean spatial zone
|
|
||||||
- **No Filler Text:** "Scroll to explore", "Swipe down", scroll arrow icons, bouncing chevrons are BANNED. The content should pull users in naturally
|
|
||||||
- **Asymmetric Structure:** Centered Hero layouts BANNED when variance exceeds 4
|
|
||||||
- **CTA Restraint:** Maximum one primary CTA. No secondary "Learn more" links
|
|
||||||
|
|
||||||
### 5. Describe Component Stylings
|
|
||||||
For each component type, describe shape, color, shadow depth, and interaction behavior:
|
|
||||||
- **Buttons:** Tactile push feedback on active state. No neon outer glows. No custom mouse cursors
|
|
||||||
- **Cards:** Use ONLY when elevation communicates hierarchy. Tint shadows to background hue. For high-density layouts, replace cards with border-top dividers or negative space
|
|
||||||
- **Inputs/Forms:** Label above input, helper text optional, error text below. Standard gap spacing
|
|
||||||
- **Loading States:** Skeletal loaders matching layout dimensions — no generic circular spinners
|
|
||||||
- **Empty States:** Composed compositions indicating how to populate data
|
|
||||||
- **Error States:** Clear, inline error reporting
|
|
||||||
|
|
||||||
### 6. Define Layout Principles
|
|
||||||
- No overlapping elements — every element occupies its own clear spatial zone. No absolute-positioned content stacking
|
|
||||||
- Centered Hero sections are BANNED when variance exceeds 4 — force Split Screen, Left-Aligned, or Asymmetric Whitespace
|
|
||||||
- The generic "3 equal cards horizontally" feature row is BANNED — use 2-column Zig-Zag, asymmetric grid, or horizontal scroll
|
|
||||||
- CSS Grid over Flexbox math — never use `calc()` percentage hacks
|
|
||||||
- Contain layouts using max-width constraints (e.g., 1400px centered)
|
|
||||||
- Full-height sections must use `min-h-[100dvh]` — never `h-screen` (iOS Safari catastrophic jump)
|
|
||||||
|
|
||||||
### 7. Define Responsive Rules
|
|
||||||
Every design must work across all viewports:
|
|
||||||
- **Mobile-First Collapse (< 768px):** All multi-column layouts collapse to single column. No exceptions
|
|
||||||
- **No Horizontal Scroll:** Horizontal overflow on mobile is a critical failure
|
|
||||||
- **Typography Scaling:** Headlines scale via `clamp()`. Body text minimum `1rem`/`14px`
|
|
||||||
- **Touch Targets:** All interactive elements minimum `44px` tap target
|
|
||||||
- **Image Behavior:** Inline typography images (photos between words) stack below headline on mobile
|
|
||||||
- **Navigation:** Desktop horizontal nav collapses to clean mobile menu
|
|
||||||
- **Spacing:** Vertical section gaps reduce proportionally (`clamp(3rem, 8vw, 6rem)`)
|
|
||||||
|
|
||||||
### 8. Encode Motion Philosophy
|
|
||||||
- **Spring Physics default:** `stiffness: 100, damping: 20` — premium, weighty feel. No linear easing
|
|
||||||
- **Perpetual Micro-Interactions:** Every active component should have an infinite loop state (Pulse, Typewriter, Float, Shimmer)
|
|
||||||
- **Staggered Orchestration:** Never mount lists instantly — use cascade delays for waterfall reveals
|
|
||||||
- **Performance:** Animate exclusively via `transform` and `opacity`. Never animate `top`, `left`, `width`, `height`. Grain/noise filters on fixed pseudo-elements only
|
|
||||||
|
|
||||||
### 9. List Anti-Patterns (AI Tells)
|
|
||||||
Encode these as explicit "NEVER DO" rules in the DESIGN.md:
|
|
||||||
- No emojis anywhere
|
|
||||||
- No `Inter` font
|
|
||||||
- No generic serif fonts (`Times New Roman`, `Georgia`, `Garamond`) — distinctive modern serifs only if needed
|
|
||||||
- No pure black (`#000000`)
|
|
||||||
- No neon/outer glow shadows
|
|
||||||
- No oversaturated accents
|
|
||||||
- No excessive gradient text on large headers
|
|
||||||
- No custom mouse cursors
|
|
||||||
- No overlapping elements — clean spatial separation always
|
|
||||||
- No 3-column equal card layouts
|
|
||||||
- No generic names ("John Doe", "Acme", "Nexus")
|
|
||||||
- No fake round numbers (`99.99%`, `50%`)
|
|
||||||
- No AI copywriting clichés ("Elevate", "Seamless", "Unleash", "Next-Gen")
|
|
||||||
- No filler UI text: "Scroll to explore", "Swipe down", scroll arrows, bouncing chevrons
|
|
||||||
- No broken Unsplash links — use `picsum.photos` or SVG avatars
|
|
||||||
- No centered Hero sections (for high-variance projects)
|
|
||||||
|
|
||||||
## Output Format (DESIGN.md Structure)
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# Design System: [Project Title]
|
|
||||||
|
|
||||||
## 1. Visual Theme & Atmosphere
|
|
||||||
(Evocative description of the mood, density, variance, and motion intensity.
|
|
||||||
Example: "A restrained, gallery-airy interface with confident asymmetric layouts
|
|
||||||
and fluid spring-physics motion. The atmosphere is clinical yet warm — like a
|
|
||||||
well-lit architecture studio.")
|
|
||||||
|
|
||||||
## 2. Color Palette & Roles
|
|
||||||
- **Canvas White** (#F9FAFB) — Primary background surface
|
|
||||||
- **Pure Surface** (#FFFFFF) — Card and container fill
|
|
||||||
- **Charcoal Ink** (#18181B) — Primary text, Zinc-950 depth
|
|
||||||
- **Muted Steel** (#71717A) — Secondary text, descriptions, metadata
|
|
||||||
- **Whisper Border** (rgba(226,232,240,0.5)) — Card borders, 1px structural lines
|
|
||||||
- **[Accent Name]** (#XXXXXX) — Single accent for CTAs, active states, focus rings
|
|
||||||
(Max 1 accent. Saturation < 80%. No purple/neon.)
|
|
||||||
|
|
||||||
## 3. Typography Rules
|
|
||||||
- **Display:** [Font Name] — Track-tight, controlled scale, weight-driven hierarchy
|
|
||||||
- **Body:** [Font Name] — Relaxed leading, 65ch max-width, neutral secondary color
|
|
||||||
- **Mono:** [Font Name] — For code, metadata, timestamps, high-density numbers
|
|
||||||
- **Banned:** Inter, generic system fonts for premium contexts. Serif fonts banned in dashboards.
|
|
||||||
|
|
||||||
## 4. Component Stylings
|
|
||||||
* **Buttons:** Flat, no outer glow. Tactile -1px translate on active. Accent fill for primary, ghost/outline for secondary.
|
|
||||||
* **Cards:** Generously rounded corners (2.5rem). Diffused whisper shadow. Used only when elevation serves hierarchy. High-density: replace with border-top dividers.
|
|
||||||
* **Inputs:** Label above, error below. Focus ring in accent color. No floating labels.
|
|
||||||
* **Loaders:** Skeletal shimmer matching exact layout dimensions. No circular spinners.
|
|
||||||
* **Empty States:** Composed, illustrated compositions — not just "No data" text.
|
|
||||||
|
|
||||||
## 5. Layout Principles
|
|
||||||
(Grid-first responsive architecture. Asymmetric splits for Hero sections.
|
|
||||||
Strict single-column collapse below 768px. Max-width containment.
|
|
||||||
No flexbox percentage math. Generous internal padding.)
|
|
||||||
|
|
||||||
## 6. Motion & Interaction
|
|
||||||
(Spring physics for all interactive elements. Staggered cascade reveals.
|
|
||||||
Perpetual micro-loops on active dashboard components. Hardware-accelerated
|
|
||||||
transforms only. Isolated Client Components for CPU-heavy animations.)
|
|
||||||
|
|
||||||
## 7. Anti-Patterns (Banned)
|
|
||||||
(Explicit list of forbidden patterns: no emojis, no Inter, no pure black,
|
|
||||||
no neon glows, no 3-column equal grids, no AI copywriting clichés,
|
|
||||||
no generic placeholder names, no broken image links.)
|
|
||||||
```
|
|
||||||
|
|
||||||
## Best Practices
|
|
||||||
- **Be Descriptive:** "Deep Charcoal Ink (#18181B)" — not just "dark text"
|
|
||||||
- **Be Functional:** Explain what each element is used for
|
|
||||||
- **Be Consistent:** Same terminology throughout the document
|
|
||||||
- **Be Precise:** Include exact hex codes, rem values, pixel values in parentheses
|
|
||||||
- **Be Opinionated:** This is not a neutral template — it enforces a specific, premium aesthetic
|
|
||||||
|
|
||||||
## Tips for Success
|
|
||||||
1. Start with the atmosphere — understand the vibe before detailing tokens
|
|
||||||
2. Look for patterns — identify consistent spacing, sizing, and styling
|
|
||||||
3. Think semantically — name colors by purpose, not just appearance
|
|
||||||
4. Consider hierarchy — document how visual weight communicates importance
|
|
||||||
5. Encode the bans — anti-patterns are as important as the rules themselves
|
|
||||||
|
|
||||||
## Common Pitfalls to Avoid
|
|
||||||
- Using technical jargon without translation ("rounded-xl" instead of "generously rounded corners")
|
|
||||||
- Omitting hex codes or using only descriptive names
|
|
||||||
- Forgetting functional roles of design elements
|
|
||||||
- Being too vague in atmosphere descriptions
|
|
||||||
- Ignoring the anti-pattern list — these are what make the output premium
|
|
||||||
- Defaulting to generic "safe" designs instead of enforcing the curated aesthetic
|
|
||||||
150
.claude/skills/document-features/SKILL.md
Normal file
150
.claude/skills/document-features/SKILL.md
Normal file
@@ -0,0 +1,150 @@
|
|||||||
|
---
|
||||||
|
name: document-features
|
||||||
|
description: Populate `<docs-dir>/features/<slug>.md` for one, several, or every undocumented feature area by dispatching up to 10 parallel subagents — one per feature. The agent docs directory is discovered from `AGENTS.md` — typically `agents-docs/` (the `setup-agentic-repository` default) but may be elsewhere if `--docs-dir` was used. Use whenever the user wants to document features, fill out feature docs, write up specific features (e.g. "document auth and billing"), document all undocumented features, or follow up on `find-features` discovery. This is the natural sequel to `find-features` — that skill identifies what is missing, this skill writes the docs in parallel.
|
||||||
|
metadata:
|
||||||
|
author: Olof Brogeby
|
||||||
|
url: https://github.com/brogeby
|
||||||
|
---
|
||||||
|
|
||||||
|
# document-features
|
||||||
|
|
||||||
|
Write feature documentation for the repository — one populated `<docs-dir>/features/<slug>.md` per requested feature — by dispatching subagents in parallel so an "all" run does not serialize. The agent docs directory (`<docs-dir>`) is discovered in Phase 1; it's typically `agents-docs/` but `setup-agentic-repository` may have written it somewhere else.
|
||||||
|
|
||||||
|
This skill is the documentation counterpart to `find-features`. `find-features` discovers what is missing; `document-features` is the focused worker that actually fills the template, in parallel, for the features the user names.
|
||||||
|
|
||||||
|
If the user asks "find and document everything", you can start with `find-features` to build the candidate list, then hand that list to this skill. If the user already knows which features they want (e.g. "document auth and billing"), come straight here.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 1 — Verify prerequisites and locate the docs directory
|
||||||
|
|
||||||
|
Confirm the repo has been initialized with the Mimas template, and discover where its agent docs actually live. `setup-agentic-repository` writes the agent doc tree to **`agents-docs/`** by default (a sibling of any human-maintained `docs/`), but `--docs-dir <dir>` can override that (e.g. `docs/agents`). Don't assume the path; discover it.
|
||||||
|
|
||||||
|
1. Read `AGENTS.md` at the repo root. Every Mimas-generated `AGENTS.md` lists its docs paths in the first block (`<docs-dir>/AGENT_WORKFLOW.md`, `<docs-dir>/AGENTS_FEATURES.md`, etc.) — the directory in those paths is the docs dir for this repo.
|
||||||
|
2. If `AGENTS.md` doesn't exist or doesn't reference the contract files, fall back to searching for `AGENTS_FEATURES.md` directly (`find . -maxdepth 3 -name AGENTS_FEATURES.md`). The directory containing it is the docs dir.
|
||||||
|
3. Confirm the files this skill needs are there:
|
||||||
|
- `<docs-dir>/AGENTS_FEATURES.md` — feature documentation contract
|
||||||
|
- `<docs-dir>/features/feature-template.md` — canonical template
|
||||||
|
- `<docs-dir>/FEATURES.md` — feature index
|
||||||
|
|
||||||
|
If any are missing, tell the user this skill is designed to run after `setup-agentic-repository` and stop. Do not scaffold them yourself.
|
||||||
|
|
||||||
|
For the rest of this skill, treat the discovered directory as `<docs-dir>` and use it wherever paths appear. **Critical:** the subagent prompt in Phase 3 is a template — substitute the actual discovered value into it before dispatching each subagent. The subagents do not run this Phase 1 themselves and will not discover the dir on their own.
|
||||||
|
|
||||||
|
Read `<docs-dir>/AGENTS_FEATURES.md` and the root `AGENTS.md` (plus any subdomain `CONTEXT.md` files) so you know the contract — what counts as an area-level doc vs. a per-service doc, and which subdomains exist. These files are authoritative; if anything in this skill drifts from them, the files win.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 2 — Decide what to document
|
||||||
|
|
||||||
|
The user's request usually contains the answer. Parse what they said:
|
||||||
|
|
||||||
|
- **Named features** ("document auth and billing", "write up the search feature") → take that list of slugs
|
||||||
|
- **A number** ("document 3 features", "write up the top 5") → take a numeric count of the most significant undocumented features
|
||||||
|
- **"all" / "every" / "everything"** → every undocumented feature with meaningful implementation
|
||||||
|
- **Ambiguous or empty** → use `AskUserQuestion` with the same options find-features uses (Top 5 / All / Number / Specific names) plus an "Other" free-text fallback
|
||||||
|
|
||||||
|
If the user is continuing from a recent `find-features` session, prefer the candidate list that already exists in the conversation over re-asking.
|
||||||
|
|
||||||
|
Then quickly inventory `<docs-dir>/features/`:
|
||||||
|
|
||||||
|
- Top-level `.md` files (one per documented area, ignoring `feature-template.md`)
|
||||||
|
- Subdirectories (areas with per-service docs)
|
||||||
|
- Entries in `<docs-dir>/FEATURES.md`
|
||||||
|
|
||||||
|
Filter the requested list against the inventory:
|
||||||
|
|
||||||
|
- Drop slugs that already have `<docs-dir>/features/<slug>.md`. Tell the user which ones you skipped and why
|
||||||
|
- For named features that you cannot locate in the codebase, surface them and ask whether to skip or scaffold a TODO doc. Do not invent feature areas
|
||||||
|
|
||||||
|
If the user asked for a number or "all" and you need to identify candidates yourself, scan the subdomains declared in `AGENTS.md` looking for named concepts with dedicated logic — dedicated service layer, non-trivial handler, dedicated tables/migrations, multiple endpoints, real business rules. A single empty route stub is not enough. Rank by significance and trim to the requested count.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 3 — Dispatch one subagent per feature, in parallel
|
||||||
|
|
||||||
|
This is the whole point of the skill. Documentation per feature is independent work — one subagent can read the code for `auth` while another reads the code for `billing`. Serializing them throws away the parallelism the harness gives you.
|
||||||
|
|
||||||
|
**Cap concurrency at 10 subagents.** If the final list has more than 10 features, dispatch the first batch of 10 in one message, wait for it to complete, then dispatch the next batch. Do not exceed 10 concurrent agents — it overwhelms tooling and the user's review can't keep up.
|
||||||
|
|
||||||
|
For each feature in the current batch, spawn one `Agent` call in the **same message** (this is what makes them run in parallel). Use the `general-purpose` subagent unless something more specific fits.
|
||||||
|
|
||||||
|
Each subagent gets a self-contained prompt — it has not seen this conversation, so include everything it needs. **Before dispatching, substitute `<docs-dir>` with the value you discovered in Phase 1** (typically `agents-docs`). The subagents do not discover the dir on their own.
|
||||||
|
|
||||||
|
```
|
||||||
|
You are documenting a single feature area for this repository. The output is one populated markdown file at `<docs-dir>/features/<slug>.md` that follows the project's feature documentation contract.
|
||||||
|
|
||||||
|
Feature slug: <slug>
|
||||||
|
One-line concept (from discovery, may be rough): <concept>
|
||||||
|
|
||||||
|
Authoritative reading order (read these first, in order):
|
||||||
|
1. `<docs-dir>/AGENTS_FEATURES.md` — the contract that governs how feature docs are written
|
||||||
|
2. `<docs-dir>/features/feature-template.md` — the canonical template. Mirror its section order and headings; do not invent your own structure
|
||||||
|
3. `AGENTS.md` and any subdomain `CONTEXT.md` files — for vocabulary and where the code lives
|
||||||
|
|
||||||
|
Your task:
|
||||||
|
- Locate this feature in the codebase. Confirm it has meaningful implementation (service layer, handler, endpoints, tables, real business rules). If it is only a stub, stop and report that back — do not write a doc for a stub
|
||||||
|
- Create `<docs-dir>/features/<slug>.md` from the template
|
||||||
|
- Fill in what you can verify from the code: overview, responsibilities, key concepts, endpoint(s), service/handler/repository paths, key types, tests location, related features
|
||||||
|
- Set `Area:` to the slug, `Status:` to `Active` for production code or `In Progress` for half-built features, and `Last updated:` to today's date in `YYYY-MM-DD`
|
||||||
|
- For sections you cannot confidently fill (performance, security review, undocumented edge cases), keep the template's prompt and add a clear `TODO:` marker. Honest gaps beat invented content
|
||||||
|
- If the feature has multiple distinct services or endpoints worth separating, also create `<docs-dir>/features/<slug>/<service>.md` files from the same template and link them from the area doc — but only when complexity actually warrants it. Do not duplicate large sections between area and per-service docs
|
||||||
|
- Do not edit `<docs-dir>/FEATURES.md` — the dispatcher will update the index once all features are written, to avoid concurrent edits to the same file
|
||||||
|
- Do not commit anything
|
||||||
|
|
||||||
|
Report back when done with:
|
||||||
|
- Path(s) of the file(s) you created
|
||||||
|
- One-line description of the feature (this will be used for the FEATURES.md entry)
|
||||||
|
- Which template sections you left as TODO
|
||||||
|
- Anything you noticed that needs human judgment
|
||||||
|
```
|
||||||
|
|
||||||
|
Substitute `<slug>`, `<concept>`, and `<docs-dir>` per feature. Keep the rest verbatim — the subagent depends on having the contract in its own context.
|
||||||
|
|
||||||
|
If features turn out to be unrelated to one another (different subdomains, different layers), there's no need to coordinate beyond avoiding the shared `<docs-dir>/FEATURES.md` file. The dispatcher updates the index after the batch returns.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 4 — Update the index and report back
|
||||||
|
|
||||||
|
Once a batch completes, collect each subagent's reported one-liner and add entries to `<docs-dir>/FEATURES.md` in alphabetical order, in the form:
|
||||||
|
|
||||||
|
```
|
||||||
|
- [<slug>](./features/<slug>.md) — one-line description
|
||||||
|
```
|
||||||
|
|
||||||
|
If `<docs-dir>/FEATURES.md` still contains the placeholder `_No feature areas documented yet. Add entries as you build out the system._`, remove that line as you add the first real entry.
|
||||||
|
|
||||||
|
Then, if more features remain (because the original list was >10), dispatch the next batch of up to 10 and repeat.
|
||||||
|
|
||||||
|
When everything is written, tell the user:
|
||||||
|
|
||||||
|
- Which feature docs were created (full paths), grouped by batch if there were multiple
|
||||||
|
- Which requested features were skipped, and why ("already documented at `<docs-dir>/features/<slug>.md`", "could not locate in codebase", "implementation too thin to earn an entry yet")
|
||||||
|
- Which sections in the new docs are TODOs that still need human judgment
|
||||||
|
- That `<docs-dir>/FEATURES.md` was updated and how many entries were added
|
||||||
|
- Any discrepancies you noticed between `<docs-dir>/FEATURES.md` and the filesystem
|
||||||
|
|
||||||
|
Do not commit the changes. The user reviews before committing.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Why this is structured around subagents
|
||||||
|
|
||||||
|
Documenting one feature is read-heavy and largely independent of documenting another — different files, different services, different endpoints. The slow part is the reading, and parallelizing the reading is the entire reason this skill exists separately from `find-features`. Spawning ten subagents in one message and letting them work concurrently turns a 10-minute sequential run into something closer to a 1–2 minute parallel one, with each subagent producing a focused, faithful doc because its whole context is one feature.
|
||||||
|
|
||||||
|
The 10-agent cap is pragmatic, not theoretical: more than that and you risk rate limits, output you can't usefully review at once, and the dispatcher running out of room to track which agent owns which slug. Two batches of ten is fine; ten batches of one is the failure mode this skill is designed to avoid.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What makes a good output
|
||||||
|
|
||||||
|
**Faithful to the code.** Endpoint paths, file locations, method names, table names must match what is actually in the repo. If a subagent can't find something, the right move is a `TODO:` marker, not a guess.
|
||||||
|
|
||||||
|
**Concept-first for area docs.** The area-level doc explains what the feature is *for* — responsibilities, boundaries, vocabulary. Deep implementation detail belongs in per-service docs once they exist.
|
||||||
|
|
||||||
|
**Honest about gaps.** A clear `TODO: describe rate limiting` is more useful than a fabricated rate limit policy. Future sessions can fill these in from real information.
|
||||||
|
|
||||||
|
**Proportionate.** A small CRUD endpoint with one handler does not need every section of the template. Trim or skip sections that genuinely do not apply. The template is a checklist of what *might* be relevant, not a contract that every section must be populated.
|
||||||
|
|
||||||
|
**Honors the contract.** The structure, headings, and rules in `<docs-dir>/AGENTS_FEATURES.md` and `<docs-dir>/features/feature-template.md` win every time. If this skill's instructions ever drift from those files, the files are authoritative — they live with the project and are what other agents read.
|
||||||
35
.claude/skills/document-features/evals/evals.json
Normal file
35
.claude/skills/document-features/evals/evals.json
Normal file
@@ -0,0 +1,35 @@
|
|||||||
|
{
|
||||||
|
"skill_name": "document-features",
|
||||||
|
"evals": [
|
||||||
|
{
|
||||||
|
"id": 1,
|
||||||
|
"prompt": "find-features just listed auth, billing, and search as undocumented. Please go document all three.",
|
||||||
|
"expected_output": "Skill verifies prerequisites by discovering the agent docs directory (typically agents-docs/, but may be elsewhere — read from AGENTS.md), takes the three named features, inventories <docs-dir>/features/ to confirm none are already documented, dispatches one subagent per feature in a single message (so they run in parallel), substitutes the discovered <docs-dir> value into each subagent prompt before dispatching, then writes <docs-dir>/features/auth.md, <docs-dir>/features/billing.md, <docs-dir>/features/search.md from the template, and appends three entries to <docs-dir>/FEATURES.md (alphabetical). Leaves TODO markers where content cannot be derived from the code. Does not commit.",
|
||||||
|
"files": []
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": 2,
|
||||||
|
"prompt": "document every undocumented feature in this repo",
|
||||||
|
"expected_output": "Skill discovers the docs dir, parses 'every' as 'all', identifies undocumented feature areas with meaningful implementation, dispatches subagents in parallel batches capped at 10 per batch (with the discovered <docs-dir> substituted into each subagent prompt), writes one doc per feature, and updates <docs-dir>/FEATURES.md. If there are more than 10 features, runs a second batch after the first finishes. Reports back which features were skipped and why.",
|
||||||
|
"files": []
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": 3,
|
||||||
|
"prompt": "write the docs for billing",
|
||||||
|
"expected_output": "Skill discovers the docs dir, treats 'billing' as a single named feature, checks <docs-dir>/features/billing.md does not already exist, locates billing in the codebase, dispatches one subagent to document it (with <docs-dir> substituted into the prompt), writes <docs-dir>/features/billing.md from the template, and adds an entry to <docs-dir>/FEATURES.md. If billing already has a doc or cannot be located, the skill surfaces that instead of silently creating something.",
|
||||||
|
"files": []
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": 4,
|
||||||
|
"prompt": "document the top 5 undocumented features",
|
||||||
|
"expected_output": "Skill discovers the docs dir, parses '5' as a numeric limit, identifies undocumented feature areas, ranks by significance, takes the top 5, dispatches 5 subagents in parallel in a single message (each with <docs-dir> substituted), writes 5 docs from the template, and updates <docs-dir>/FEATURES.md with 5 alphabetical entries. Other candidates are listed in the final report as 'not selected this round'.",
|
||||||
|
"files": []
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": 5,
|
||||||
|
"prompt": "this repo uses --docs-dir docs/agents for its agent docs. document the auth feature.",
|
||||||
|
"expected_output": "Skill discovers the docs dir is docs/agents/ (from AGENTS.md path references), dispatches a single subagent with docs/agents substituted into the subagent prompt template, writes docs/agents/features/auth.md, and updates docs/agents/FEATURES.md. Does not hardcode agents-docs/ or docs/features/ — uses the discovered path everywhere.",
|
||||||
|
"files": []
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
149
.claude/skills/find-features/SKILL.md
Normal file
149
.claude/skills/find-features/SKILL.md
Normal file
@@ -0,0 +1,149 @@
|
|||||||
|
---
|
||||||
|
name: find-features
|
||||||
|
description: Discover feature areas in the current repository that are not yet documented under the agent docs `features/` tree (scaffolded by `setup-agentic-repository` — `agents-docs/features/` by default, or wherever `--docs-dir` put it), then create populated feature docs from the canonical template. Use whenever the user wants to find undocumented features, fill out `features/`, catch up on missing feature documentation, document feature X/Y/Z, or mentions "find features". This is the natural follow-up to `setup-agentic-repository`, which scaffolds the empty `features/` tree this skill populates.
|
||||||
|
metadata:
|
||||||
|
author: Olof Brogeby
|
||||||
|
url: https://github.com/brogeby
|
||||||
|
---
|
||||||
|
|
||||||
|
# find-features
|
||||||
|
|
||||||
|
Discover feature areas in this repository that are missing from `<docs-dir>/features/`, then create a populated markdown file for each one — following the contract in `<docs-dir>/AGENTS_FEATURES.md` and the template at `<docs-dir>/features/feature-template.md`. The agent docs directory (`<docs-dir>`) is discovered in Phase 1 — it's typically `agents-docs/` but `setup-agentic-repository` may have written it somewhere else.
|
||||||
|
|
||||||
|
The Mimas template (`setup-agentic-repository`) scaffolds an empty `<docs-dir>/features/` tree. This skill is the next step — it fills it in.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 1 — Verify prerequisites and locate the docs directory
|
||||||
|
|
||||||
|
Confirm the repo has been initialized with the Mimas template, and discover where its agent docs actually live. `setup-agentic-repository` writes the agent doc tree to **`agents-docs/`** by default (a sibling of any human-maintained `docs/`), but `--docs-dir <dir>` can override that (e.g. `docs/agents`). Don't assume the path; discover it.
|
||||||
|
|
||||||
|
1. Read `AGENTS.md` at the repo root. Every Mimas-generated `AGENTS.md` lists its docs paths in the first block (`<docs-dir>/AGENT_WORKFLOW.md`, `<docs-dir>/AGENTS_FEATURES.md`, etc.) — the directory in those paths is the docs dir for this repo.
|
||||||
|
2. If `AGENTS.md` doesn't exist or doesn't reference the contract files, fall back to searching for `AGENTS_FEATURES.md` directly (`find . -maxdepth 3 -name AGENTS_FEATURES.md`). The directory containing it is the docs dir.
|
||||||
|
3. Confirm the files this skill needs are there:
|
||||||
|
- `<docs-dir>/AGENTS_FEATURES.md` — feature documentation contract
|
||||||
|
- `<docs-dir>/features/feature-template.md` — the canonical template
|
||||||
|
- `<docs-dir>/FEATURES.md` — the feature index
|
||||||
|
|
||||||
|
If any of those are missing, tell the user this skill is designed to run after `setup-agentic-repository` and stop. Don't try to scaffold them yourself — that is the other skill's job.
|
||||||
|
|
||||||
|
For the rest of this skill, treat the discovered directory as `<docs-dir>` and use it wherever paths appear. Don't hardcode `docs/` or `agents-docs/` in your reasoning, prompts, or report.
|
||||||
|
|
||||||
|
Read `<docs-dir>/AGENTS_FEATURES.md` and the root `AGENTS.md` (plus any subdomain `CONTEXT.md` files) so you know:
|
||||||
|
|
||||||
|
- what counts as a feature area — a named concept with dedicated logic in the codebase, identified by naming and behavior, not folder structure alone
|
||||||
|
- the split between area-level docs (`<docs-dir>/features/<area>.md`) and per-service docs (`<docs-dir>/features/<area>/<service>.md`)
|
||||||
|
- which subdomains exist and where their code lives
|
||||||
|
|
||||||
|
These files define the contract you must satisfy. The whole point of the skill is to produce docs that look like a senior engineer on this project wrote them, following the rules already agreed in `AGENTS_FEATURES.md`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 2 — Inventory what is already documented
|
||||||
|
|
||||||
|
List `<docs-dir>/features/` and capture, before asking the user anything:
|
||||||
|
|
||||||
|
- Top-level `.md` files (one per documented area) — ignore `feature-template.md`, it is the template
|
||||||
|
- Subdirectories under `<docs-dir>/features/` (areas with per-service docs)
|
||||||
|
- The entries listed in `<docs-dir>/FEATURES.md`
|
||||||
|
|
||||||
|
You will use this list to filter out features that already have an area doc. Discrepancies between the filesystem and `<docs-dir>/FEATURES.md` are worth flagging in your final report, but don't block on them.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 3 — Ask the user what to discover
|
||||||
|
|
||||||
|
Use `AskUserQuestion` to ask how many features (or which ones) to discover. Phrase the question so it accepts a number, "all", or a free-text list of names. The tool always offers an "Other" free-text fallback, so give a few sensible presets and let the user type a specific answer when none fit.
|
||||||
|
|
||||||
|
```
|
||||||
|
questions:
|
||||||
|
- question: "How many features would you like to discover, or which ones specifically?"
|
||||||
|
header: "Scope"
|
||||||
|
multiSelect: false
|
||||||
|
options:
|
||||||
|
- label: "Top 5 (Recommended)"
|
||||||
|
description: "Discover up to 5 of the most significant undocumented feature areas."
|
||||||
|
- label: "All"
|
||||||
|
description: "Find every undocumented feature area in the codebase."
|
||||||
|
- label: "A specific number (1–10)"
|
||||||
|
description: "I'll tell you a number from 1 to 10."
|
||||||
|
- label: "Specific names"
|
||||||
|
description: "I'll list the feature names I want documented (e.g. 'auth, billing, search')."
|
||||||
|
```
|
||||||
|
|
||||||
|
Parse whatever they answer with — accept a bare number, the word "all" (any case), or a comma- or space-separated list. Phrases like "find feature x, y, z" or "auth and billing" should yield `["x", "y", "z"]` and `["auth", "billing"]` respectively. Don't be strict about format; pull out the names.
|
||||||
|
|
||||||
|
If the user names features you can't locate in the codebase, surface that and ask whether to skip them or create scaffolded TODO docs for them. Do not silently invent them.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 4 — Discover undocumented feature areas
|
||||||
|
|
||||||
|
Scan the codebase for feature areas using the definition from `<docs-dir>/AGENTS_FEATURES.md`. Start from the subdomains declared in the root `AGENTS.md` — if there are several large subdomains, **launch one subagent per subdomain in parallel** so discovery doesn't serialize.
|
||||||
|
|
||||||
|
For each candidate feature, capture:
|
||||||
|
|
||||||
|
- **Slug** — kebab-case, ideally matching how the area is referenced in code or routes (e.g. `auth`, `billing`, `recruitment-content`)
|
||||||
|
- **One-sentence concept** — what the feature does, in user-facing terms
|
||||||
|
- **Where the code lives** — routes, services, handlers, components, modules
|
||||||
|
- **Significance signal** — at least one of: dedicated service layer, non-trivial handler, dedicated DB tables/migrations, multiple endpoints, real business rules. A single empty route stub is not enough
|
||||||
|
- **Whether it is already documented** — does `<docs-dir>/features/<slug>.md` exist already?
|
||||||
|
|
||||||
|
Then filter:
|
||||||
|
|
||||||
|
- Drop anything that already has an area-level doc
|
||||||
|
- Drop stubs and scaffolding — `<docs-dir>/AGENTS_FEATURES.md` says an entry must have meaningful implementation. Err on the side of leaving thin features out and noting them as "not yet earning an entry"
|
||||||
|
|
||||||
|
Rank what is left by significance (surface area, number of endpoints, depth of business logic), then trim to what the user asked for:
|
||||||
|
|
||||||
|
- **Number** → take the top N from the ranked list
|
||||||
|
- **"all"** → take everything that survived the filter
|
||||||
|
- **Named features** → take only those, matched by slug or close fuzzy match, warning about any that didn't match
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 5 — Create the feature docs
|
||||||
|
|
||||||
|
For each chosen feature:
|
||||||
|
|
||||||
|
1. Read `<docs-dir>/features/feature-template.md` once and use it as the structural template — section order, headings, prompts. Do not invent your own structure.
|
||||||
|
2. Create `<docs-dir>/features/<slug>.md` populated from the template:
|
||||||
|
- Fill in what you can verify from the code: overview, responsibilities, key concepts, API endpoint(s), service/handler/repository paths, key types, tests location, related features
|
||||||
|
- Set **`Area:`** to the slug, **`Status:`** to `Active` for production code or `In Progress` for half-built features, and **`Last updated:`** to today's date in `YYYY-MM-DD`
|
||||||
|
- For sections you cannot confidently fill (performance characteristics, security review, edge cases nobody has documented), keep the template's prompt and add a clear TODO marker. Leaving an honest gap is better than inventing content
|
||||||
|
3. If the feature has multiple distinct services or endpoints worth separating, also create `<docs-dir>/features/<slug>/` and seed per-service docs (`<docs-dir>/features/<slug>/<service>.md`) from the same template, then link them from the area doc. Only do this when complexity actually warrants it — the contract says don't duplicate large sections between area and per-service docs
|
||||||
|
|
||||||
|
After writing each file, add an entry to `<docs-dir>/FEATURES.md` in alphabetical order, in the form:
|
||||||
|
|
||||||
|
```
|
||||||
|
- [<slug>](./features/<slug>.md) — one-line description
|
||||||
|
```
|
||||||
|
|
||||||
|
If `<docs-dir>/FEATURES.md` still contains the placeholder `_No feature areas documented yet. Add entries as you build out the system._`, remove that line as you add the first real entry.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 6 — Report back
|
||||||
|
|
||||||
|
Tell the user:
|
||||||
|
|
||||||
|
- Which feature docs were created (full paths)
|
||||||
|
- Which candidates were considered but rejected, and why ("too thin to earn an entry yet", "matches existing doc <name>", etc.)
|
||||||
|
- Which sections in the new docs are TODOs that still need human judgment (performance, security, business rules, error scenarios)
|
||||||
|
- Whether `<docs-dir>/FEATURES.md` was updated, and any discrepancies you noticed between it and the filesystem
|
||||||
|
|
||||||
|
Do not commit the changes. The user reviews before committing.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## What makes a good output
|
||||||
|
|
||||||
|
**Faithful to the code.** Endpoint paths, file locations, method names, table names must match what is actually in the repo. If you cannot find something, leave the template prompt in place with a TODO — do not guess.
|
||||||
|
|
||||||
|
**Concept-first for area docs.** The area-level doc explains what the feature is *for* — responsibilities, boundaries, vocabulary. Implementation detail belongs in per-service docs once they exist.
|
||||||
|
|
||||||
|
**Honest about gaps.** A clear `TODO: describe rate limiting` is more useful than a fabricated rate limit policy. Future sessions can fill these in from real information.
|
||||||
|
|
||||||
|
**Proportionate.** A small CRUD endpoint with one handler does not need every section of the template. Trim or skip sections that genuinely do not apply (no auth, no caching, no migrations, no feature flags). The template is a checklist of what *might* be relevant, not a contract that every section must be populated.
|
||||||
|
|
||||||
|
**Honors the contract.** The structure, headings, and rules in `<docs-dir>/AGENTS_FEATURES.md` and `<docs-dir>/features/feature-template.md` win every time. If this skill's instructions ever drift from those files, the files are authoritative — they live with the project and are what other agents read.
|
||||||
35
.claude/skills/find-features/evals/evals.json
Normal file
35
.claude/skills/find-features/evals/evals.json
Normal file
@@ -0,0 +1,35 @@
|
|||||||
|
{
|
||||||
|
"skill_name": "find-features",
|
||||||
|
"evals": [
|
||||||
|
{
|
||||||
|
"id": 1,
|
||||||
|
"prompt": "I just ran /setup-agentic-repository on this repo and the features folder is empty. Can you find the most important features and write up docs for them?",
|
||||||
|
"expected_output": "Skill verifies prerequisites by discovering the agent docs directory (reading AGENTS.md or searching for AGENTS_FEATURES.md — typically agents-docs/ but may be elsewhere), asks how many/which features (with Top 5 / All / Number / Names options), scans the codebase, creates <docs-dir>/features/<slug>.md files from the template for the chosen features, and appends entries to <docs-dir>/FEATURES.md (alphabetical). Honestly leaves TODO markers where it cannot derive content from the code.",
|
||||||
|
"files": []
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": 2,
|
||||||
|
"prompt": "we have some feature docs already but I think auth and billing are missing — can you check and add what's missing?",
|
||||||
|
"expected_output": "Skill discovers the docs dir, inventories the existing <docs-dir>/features/, treats the user's free-text answer 'auth and billing' as the named list, verifies both exist in the codebase (skipping or flagging any that don't), and creates only the missing area docs while leaving already-documented features alone.",
|
||||||
|
"files": []
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": 3,
|
||||||
|
"prompt": "find every undocumented feature in this repo and document them all",
|
||||||
|
"expected_output": "Skill interprets 'every' as 'all', discovers every feature area with meaningful implementation that lacks an area doc in the discovered <docs-dir>/features/, filters out stubs, ranks by significance, and creates one doc per area plus <docs-dir>/FEATURES.md entries. Reports back rejected candidates with reasons.",
|
||||||
|
"files": []
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": 4,
|
||||||
|
"prompt": "find 3 features that aren't documented yet",
|
||||||
|
"expected_output": "Skill parses '3' as a numeric limit, discovers undocumented features in the discovered docs dir, takes the top 3 by significance, and creates docs and <docs-dir>/FEATURES.md entries for exactly those three. Other candidates are listed in the final report as 'not selected this round'.",
|
||||||
|
"files": []
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": 5,
|
||||||
|
"prompt": "the docs are under agents-docs/ in this repo, find any feature areas we haven't written up yet",
|
||||||
|
"expected_output": "Skill reads AGENTS.md (or falls back to searching for AGENTS_FEATURES.md), confirms the docs dir is agents-docs/, uses agents-docs/AGENTS_FEATURES.md as the contract and agents-docs/features/feature-template.md as the template, and writes new docs into agents-docs/features/. Does not hardcode 'docs/' anywhere in the output.",
|
||||||
|
"files": []
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
12
.env.example
12
.env.example
@@ -3,15 +3,3 @@
|
|||||||
# When false: plain HTTP everywhere (only works on localhost)
|
# When false: plain HTTP everywhere (only works on localhost)
|
||||||
# Overrides server/data/variables.json for local development only
|
# Overrides server/data/variables.json for local development only
|
||||||
SSL=true
|
SSL=true
|
||||||
|
|
||||||
# --- Mobile push dispatch (signaling server) ---
|
|
||||||
# Android FCM HTTP v1 (choose one)
|
|
||||||
# FCM_SERVICE_ACCOUNT_PATH=/absolute/path/to/firebase-service-account.json
|
|
||||||
# FCM_SERVICE_ACCOUNT_JSON={"type":"service_account","project_id":"..."}
|
|
||||||
|
|
||||||
# iOS APNs HTTP/2 (.p8 key from Apple Developer)
|
|
||||||
# APNS_KEY_PATH=/absolute/path/to/AuthKey_XXXXXXXXXX.p8
|
|
||||||
# APNS_KEY_ID=XXXXXXXXXX
|
|
||||||
# APNS_TEAM_ID=XXXXXXXXXX
|
|
||||||
# APNS_BUNDLE_ID=com.metoyou.app
|
|
||||||
# APNS_USE_SANDBOX=true
|
|
||||||
|
|||||||
@@ -1,99 +0,0 @@
|
|||||||
name: Build Android APK
|
|
||||||
|
|
||||||
on:
|
|
||||||
workflow_dispatch:
|
|
||||||
|
|
||||||
jobs:
|
|
||||||
build-android-apk:
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
container: node:22
|
|
||||||
|
|
||||||
steps:
|
|
||||||
- name: Checkout
|
|
||||||
uses: https://github.com/actions/checkout@v4
|
|
||||||
|
|
||||||
- name: Restore npm cache
|
|
||||||
uses: https://github.com/actions/cache@v4
|
|
||||||
with:
|
|
||||||
path: /root/.npm
|
|
||||||
key: npm-android-${{ hashFiles('package-lock.json') }}
|
|
||||||
restore-keys: npm-android-
|
|
||||||
|
|
||||||
- name: Restore Gradle cache
|
|
||||||
uses: https://github.com/actions/cache@v4
|
|
||||||
with:
|
|
||||||
path: |
|
|
||||||
/root/.gradle/caches
|
|
||||||
/root/.gradle/wrapper
|
|
||||||
key: gradle-android-${{ hashFiles('toju-app/android/**/*.gradle*', 'toju-app/android/gradle/wrapper/gradle-wrapper.properties') }}
|
|
||||||
restore-keys: gradle-android-
|
|
||||||
|
|
||||||
- name: Install Android build toolchain
|
|
||||||
run: |
|
|
||||||
apt-get update
|
|
||||||
apt-get install -y --no-install-recommends wget unzip ca-certificates gnupg
|
|
||||||
|
|
||||||
# node:22 is Debian Bookworm — openjdk-21-jdk is not in default repos.
|
|
||||||
install -d /etc/apt/keyrings
|
|
||||||
wget -qO - https://packages.adoptium.net/artifactory/api/gpg/key/public | gpg --dearmor -o /etc/apt/keyrings/adoptium.gpg
|
|
||||||
echo "deb [signed-by=/etc/apt/keyrings/adoptium.gpg] https://packages.adoptium.net/artifactory/deb bookworm main" > /etc/apt/sources.list.d/adoptium.list
|
|
||||||
apt-get update
|
|
||||||
apt-get install -y --no-install-recommends temurin-21-jdk
|
|
||||||
|
|
||||||
export ANDROID_SDK_ROOT=/opt/android-sdk
|
|
||||||
mkdir -p "$ANDROID_SDK_ROOT/cmdline-tools"
|
|
||||||
cd /tmp
|
|
||||||
wget -q https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip
|
|
||||||
unzip -q commandlinetools-linux-11076708_latest.zip
|
|
||||||
mv cmdline-tools "$ANDROID_SDK_ROOT/cmdline-tools/latest"
|
|
||||||
export PATH="$PATH:$ANDROID_SDK_ROOT/cmdline-tools/latest/bin:$ANDROID_SDK_ROOT/platform-tools"
|
|
||||||
|
|
||||||
yes | sdkmanager --licenses >/dev/null
|
|
||||||
sdkmanager "platform-tools" "platforms;android-36" "build-tools;35.0.0"
|
|
||||||
|
|
||||||
echo "ANDROID_SDK_ROOT=$ANDROID_SDK_ROOT" >> "$GITHUB_ENV"
|
|
||||||
echo "ANDROID_HOME=$ANDROID_SDK_ROOT" >> "$GITHUB_ENV"
|
|
||||||
echo "JAVA_HOME=/usr/lib/jvm/temurin-21-jdk-amd64" >> "$GITHUB_ENV"
|
|
||||||
echo "PATH=$PATH:$ANDROID_SDK_ROOT/cmdline-tools/latest/bin:$ANDROID_SDK_ROOT/platform-tools" >> "$GITHUB_ENV"
|
|
||||||
|
|
||||||
- name: Install dependencies
|
|
||||||
env:
|
|
||||||
NODE_ENV: development
|
|
||||||
run: npm ci
|
|
||||||
|
|
||||||
- name: Resolve release version
|
|
||||||
id: version
|
|
||||||
run: node tools/resolve-release-version.js --write-output
|
|
||||||
|
|
||||||
- name: Ensure draft release exists
|
|
||||||
id: release
|
|
||||||
env:
|
|
||||||
GITEA_RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
|
|
||||||
run: >
|
|
||||||
node tools/gitea-release.js ensure-draft
|
|
||||||
--server-url "${{ github.server_url }}"
|
|
||||||
--repository "${{ github.repository }}"
|
|
||||||
--tag "${{ steps.version.outputs.release_tag }}"
|
|
||||||
--target "${{ github.sha }}"
|
|
||||||
--name "${{ steps.version.outputs.release_name }}"
|
|
||||||
--body "Automated draft release from ${{ github.ref_name }} @ ${{ github.sha }}"
|
|
||||||
--write-output
|
|
||||||
|
|
||||||
- name: Build debug APK
|
|
||||||
run: bash tools/build-android-apk.sh
|
|
||||||
|
|
||||||
- name: Stage Android APK
|
|
||||||
run: |
|
|
||||||
mkdir -p dist-android
|
|
||||||
cp toju-app/android/app/build/outputs/apk/debug/app-debug.apk \
|
|
||||||
"dist-android/Toju-${{ steps.version.outputs.release_version }}-android-debug.apk"
|
|
||||||
|
|
||||||
- name: Upload Android APK to draft release
|
|
||||||
env:
|
|
||||||
GITEA_RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
|
|
||||||
run: >
|
|
||||||
node tools/gitea-release.js upload-built-assets
|
|
||||||
--server-url "${{ github.server_url }}"
|
|
||||||
--repository "${{ github.repository }}"
|
|
||||||
--release-id "${{ steps.release.outputs.release_id }}"
|
|
||||||
--dist-android dist-android
|
|
||||||
@@ -110,87 +110,6 @@ jobs:
|
|||||||
--dist-electron dist-electron
|
--dist-electron dist-electron
|
||||||
--dist-server dist-server
|
--dist-server dist-server
|
||||||
|
|
||||||
build-android:
|
|
||||||
needs: prepare
|
|
||||||
runs-on: ubuntu-latest
|
|
||||||
container: node:22
|
|
||||||
|
|
||||||
steps:
|
|
||||||
- name: Checkout
|
|
||||||
uses: https://github.com/actions/checkout@v4
|
|
||||||
|
|
||||||
- name: Restore npm cache
|
|
||||||
uses: https://github.com/actions/cache@v4
|
|
||||||
with:
|
|
||||||
path: /root/.npm
|
|
||||||
key: npm-android-${{ hashFiles('package-lock.json') }}
|
|
||||||
restore-keys: npm-android-
|
|
||||||
|
|
||||||
- name: Restore Gradle cache
|
|
||||||
uses: https://github.com/actions/cache@v4
|
|
||||||
with:
|
|
||||||
path: |
|
|
||||||
/root/.gradle/caches
|
|
||||||
/root/.gradle/wrapper
|
|
||||||
key: gradle-android-${{ hashFiles('toju-app/android/**/*.gradle*', 'toju-app/android/gradle/wrapper/gradle-wrapper.properties') }}
|
|
||||||
restore-keys: gradle-android-
|
|
||||||
|
|
||||||
- name: Install Android build toolchain
|
|
||||||
run: |
|
|
||||||
apt-get update
|
|
||||||
apt-get install -y --no-install-recommends wget unzip ca-certificates gnupg
|
|
||||||
|
|
||||||
install -d /etc/apt/keyrings
|
|
||||||
wget -qO - https://packages.adoptium.net/artifactory/api/gpg/key/public | gpg --dearmor -o /etc/apt/keyrings/adoptium.gpg
|
|
||||||
echo "deb [signed-by=/etc/apt/keyrings/adoptium.gpg] https://packages.adoptium.net/artifactory/deb bookworm main" > /etc/apt/sources.list.d/adoptium.list
|
|
||||||
apt-get update
|
|
||||||
apt-get install -y --no-install-recommends temurin-21-jdk
|
|
||||||
|
|
||||||
export ANDROID_SDK_ROOT=/opt/android-sdk
|
|
||||||
mkdir -p "$ANDROID_SDK_ROOT/cmdline-tools"
|
|
||||||
cd /tmp
|
|
||||||
wget -q https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip
|
|
||||||
unzip -q commandlinetools-linux-11076708_latest.zip
|
|
||||||
mv cmdline-tools "$ANDROID_SDK_ROOT/cmdline-tools/latest"
|
|
||||||
export PATH="$PATH:$ANDROID_SDK_ROOT/cmdline-tools/latest/bin:$ANDROID_SDK_ROOT/platform-tools"
|
|
||||||
|
|
||||||
yes | sdkmanager --licenses >/dev/null
|
|
||||||
sdkmanager "platform-tools" "platforms;android-36" "build-tools;35.0.0"
|
|
||||||
|
|
||||||
echo "ANDROID_SDK_ROOT=$ANDROID_SDK_ROOT" >> "$GITHUB_ENV"
|
|
||||||
echo "ANDROID_HOME=$ANDROID_SDK_ROOT" >> "$GITHUB_ENV"
|
|
||||||
echo "JAVA_HOME=/usr/lib/jvm/temurin-21-jdk-amd64" >> "$GITHUB_ENV"
|
|
||||||
echo "PATH=$PATH:$ANDROID_SDK_ROOT/cmdline-tools/latest/bin:$ANDROID_SDK_ROOT/platform-tools" >> "$GITHUB_ENV"
|
|
||||||
|
|
||||||
- name: Install dependencies
|
|
||||||
env:
|
|
||||||
NODE_ENV: development
|
|
||||||
run: npm ci
|
|
||||||
|
|
||||||
- name: Set CI release version
|
|
||||||
run: >
|
|
||||||
node tools/set-release-version.js
|
|
||||||
--version "${{ needs.prepare.outputs.release_version }}"
|
|
||||||
|
|
||||||
- name: Build debug APK
|
|
||||||
run: bash tools/build-android-apk.sh
|
|
||||||
|
|
||||||
- name: Stage Android APK
|
|
||||||
run: |
|
|
||||||
mkdir -p dist-android
|
|
||||||
cp toju-app/android/app/build/outputs/apk/debug/app-debug.apk \
|
|
||||||
"dist-android/Toju-${{ needs.prepare.outputs.release_version }}-android-debug.apk"
|
|
||||||
|
|
||||||
- name: Upload Android APK
|
|
||||||
env:
|
|
||||||
GITEA_RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
|
|
||||||
run: >
|
|
||||||
node tools/gitea-release.js upload-built-assets
|
|
||||||
--server-url "${{ github.server_url }}"
|
|
||||||
--repository "${{ github.repository }}"
|
|
||||||
--release-id "${{ needs.prepare.outputs.release_id }}"
|
|
||||||
--dist-android dist-android
|
|
||||||
|
|
||||||
build-windows:
|
build-windows:
|
||||||
needs: prepare
|
needs: prepare
|
||||||
runs-on: windows
|
runs-on: windows
|
||||||
|
|||||||
1
.gitignore
vendored
1
.gitignore
vendored
@@ -59,7 +59,6 @@ Thumbs.db
|
|||||||
.env
|
.env
|
||||||
.certs/
|
.certs/
|
||||||
/server/data/variables.json
|
/server/data/variables.json
|
||||||
/server/data/metoyou.sqlite
|
|
||||||
dist-server/*
|
dist-server/*
|
||||||
|
|
||||||
doc/**
|
doc/**
|
||||||
|
|||||||
@@ -124,8 +124,6 @@ Behavioral changes to any of these qualify as a feature-doc update under the rul
|
|||||||
- `release-draft.yml` — queues release builds on push to `main` / `master`
|
- `release-draft.yml` — queues release builds on push to `main` / `master`
|
||||||
- `publish-draft-release.yml` — publishes draft releases
|
- `publish-draft-release.yml` — publishes draft releases
|
||||||
- `deploy-web-apps.yml` — deploys the marketing site and Docusaurus docs
|
- `deploy-web-apps.yml` — deploys the marketing site and Docusaurus docs
|
||||||
- `build-android-apk.yml` — manual **workflow_dispatch** debug Capacitor Android APK build; uploads `Toju-<version>-android-debug.apk` to the draft release (same path as desktop assets)
|
|
||||||
- `release-draft.yml` job `build-android` — builds and uploads the debug APK to each queued draft release alongside desktop/server archives
|
|
||||||
- All checks must pass before merging a PR
|
- All checks must pass before merging a PR
|
||||||
- Workflow status is visible in the Gitea PR view; use the web UI or `tea` CLI to inspect runs
|
- Workflow status is visible in the Gitea PR view; use the web UI or `tea` CLI to inspect runs
|
||||||
|
|
||||||
|
|||||||
@@ -8,13 +8,16 @@ It must stay accurate as new features are introduced, renamed, merged, or remove
|
|||||||
|
|
||||||
## Feature list (alphabetical)
|
## Feature list (alphabetical)
|
||||||
|
|
||||||
- [App i18n](features/app-i18n.md) — `@ngx-translate/core` localization for the product client; English-only catalog today, same stack as the marketing website.
|
- [access-control](./features/access-control.md) — Roles, role assignments, channel permission overrides, memberships, invites, bans, and slowmode.
|
||||||
- [Authentication](features/authentication.md) — signaling-server session tokens, protected REST/WebSocket identity, and client bearer storage.
|
- [attachments](./features/attachments.md) — P2P chunked file-transfer protocol over the WebRTC chat data channel, storage decisions, auto-download rules.
|
||||||
- [Custom Emoji](features/custom-emoji.md) — peer-synced user-created emoji assets, chat reaction shortcuts, and composer emoji insertion.
|
- [authentication](./features/authentication.md) — User account REST surface, WebSocket `identify` handshake, heartbeat sweep, and Electron Local API tokens.
|
||||||
- [Message Integrity](features/message-integrity.md) — signed P2P message revision chains, inventory `headHash` convergence, and Ed25519 signing-key registration on the signaling server.
|
- [ipc-bridge](./features/ipc-bridge.md) — Electron preload `window.electronAPI` surface, IPC channels, and CQRS dispatch.
|
||||||
- [Mobile Capacitor](features/mobile-capacitor.md) — Capacitor native shell, mobile infrastructure facades, and phone-specific call/chat/media integrations.
|
- [messaging](./features/messaging.md) — Server-channel chat, direct messages, inventory-sync protocol, delivery state machine.
|
||||||
- [Server Discovery](features/server-discovery.md) — featured/trending public-server REST endpoints (server) consumed by the `/dashboard` and `/servers` client pages.
|
- [plugin-system](./features/plugin-system.md) — Plugin manifest contract, renderer runtime, capability grants, and server `plugin-support` API.
|
||||||
- [Signal Server Tag](features/signal-server-tag.md) — configurable signal-server display tag shown on profile cards for a user's registration server.
|
- [presence](./features/presence.md) — Connection lifecycle, availability status, profile metadata propagation, voice membership, and game activity.
|
||||||
|
- [server-directory](./features/server-directory.md) — REST surface for server catalog, invites, join requests, and moderation.
|
||||||
|
- [voice-signaling](./features/voice-signaling.md) — WebRTC mesh signaling, RNNoise pipeline, and voice / direct-call / screen-share orchestration.
|
||||||
|
- [websocket-envelopes](./features/websocket-envelopes.md) — Wire-format contract for every realtime envelope between server and clients.
|
||||||
|
|
||||||
The product client already documents its bounded contexts at `toju-app/src/app/domains/<name>/README.md` (Access Control, Attachment, Authentication, Chat, Direct Call, Direct Message, Experimental Media, Game Activity, Notifications, Plugins, Profile Avatar, Screen Share, Server Directory, Theme, Voice Connection, Voice Session). Those domain READMEs cover internal product-client behavior.
|
The product client already documents its bounded contexts at `toju-app/src/app/domains/<name>/README.md` (Access Control, Attachment, Authentication, Chat, Direct Call, Direct Message, Experimental Media, Game Activity, Notifications, Plugins, Profile Avatar, Screen Share, Server Directory, Theme, Voice Connection, Voice Session). Those domain READMEs cover internal product-client behavior.
|
||||||
|
|
||||||
|
|||||||
@@ -25,160 +25,6 @@ Durable rules for AI agents working on this project. Read this file at session s
|
|||||||
|
|
||||||
## Lessons
|
## Lessons
|
||||||
|
|
||||||
### Server registration needs `ownerPublicKey: oderId || id`, and must not be fire-and-forget [server-directory] [rooms]
|
|
||||||
|
|
||||||
- **Trigger:** creating a server appeared to work (the creator landed in the room view) but the server didn't exist on the backend — invite-link creation and search both 404'd. `createRoom$` sent `ownerPublicKey: currentUser.oderId` with no fallback; on restored sessions `oderId` can be falsy (identify still works because it falls back to `id`), so `POST /api/servers` returned `400 Missing required fields`, and the `.subscribe()` swallowed the error while `createRoomSuccess` fired regardless.
|
|
||||||
- **Rule:** resolve owner identity as `oderId || id` everywhere it's required (the server rejects an empty `ownerPublicKey`), and give `registerServer().subscribe()` an `error` handler so a failed registration is never silent.
|
|
||||||
- **Why:** verified against the live server — authed POST with a truthy `ownerPublicKey` → 201; authed POST with an empty one → 400; the swallowed 400 is exactly what produces a "ghost" room the creator can enter but no one can find.
|
|
||||||
- **Example:** `buildServerRegistrationPayload(room, currentUser, normalizedPassword)` in `toju-app/src/app/store/rooms/server-registration.rules.ts`, used by `RoomsEffects.createRoom$`.
|
|
||||||
|
|
||||||
### Identify must fall back to the legacy session token, not only the new credential store [realtime] [authentication]
|
|
||||||
|
|
||||||
- **Trigger:** the multi-signal-server auth refactor changed `resolveCredentialForSignalUrl` to read *only* `SignalServerCredentialStoreService`; sessions restored from disk (and logins where `user.homeSignalServerUrl` is unset) have an empty credential store, so `identify` was skipped on every signal server ("Skipping identify because no session token is available") and users appeared alone — no presence, no peers, sent messages visible only to themselves. E2E never caught it because every e2e flow does a *fresh* register/login that writes the credential store directly.
|
|
||||||
- **Rule:** when resolving the identify credential for a signal URL, prefer the per-signal credential but fall back to the legacy `AuthTokenStoreService` token reconstructed with the current home user's `id`/`displayName`; never gate `identify` solely on the new credential store.
|
|
||||||
- **Why:** `persistSessionToken` always writes the legacy `metoyou.authTokens` store on login, but the per-signal credential store is only populated on fresh login (with a `loginResponse`) or successful migration/provisioning — so on reload it can be empty while a valid session still exists.
|
|
||||||
- **Example:** `resolveSignalIdentity(credential, legacyTokenEntry, homeUser)` in `signal-server-credential-resolution.rules.ts`, wired through `SignalServerAuthService.resolveCredentialForSignalUrl` (which now passes `this.authTokenStore.getTokenEntry(httpUrl)` and a `homeUser` carrying `id`). Test cross-user behavior via a *session-restore* path, not just fresh login.
|
|
||||||
|
|
||||||
### Keep the per-signal-URL identify credential resolvable from the store [realtime] [authentication]
|
|
||||||
|
|
||||||
- **Trigger:** after the multi-signal-server auth refactor, `SignalingManager.getLastIdentify` was switched to `getIdentifyCredentialsForSignalUrl`, which only read an in-memory cache populated *after* `identify()` ran; a freshly (re)connected socket then emitted `join_server` before any identify and users silently never appeared in the presence roster (almost all multi-user e2e tests timed out waiting for the peer's `room-user-card`).
|
|
||||||
- **Rule:** `getIdentifyCredentialsForSignalUrl` must fall back to resolving the credential from the credential store so a new socket's `onopen` re-identifies before it re-joins; never restrict it to only the in-memory identify cache.
|
|
||||||
- **Why:** the server drops `join_server`/`view_server` on any unauthenticated connection, so an identify-less join is lost with no error and recovery only happens on a later reconnect (often beyond the 20s test timeout).
|
|
||||||
- **Example:** server log showed `join_server authed=false ... display=User` dropped, then `User identified: Alice` on a different connection but no `Alice joined server`; fixed in `signaling-transport-handler.ts` by resolving via `dependencies.resolveCredential(signalUrl)` when the cache is empty.
|
|
||||||
|
|
||||||
### Store clientInstanceId in sessionStorage not localStorage [realtime] [multi-device]
|
|
||||||
|
|
||||||
- **Trigger:** same user logged in on two tabs, browsers, or synced profiles sees alternating "Disconnected from signaling server" and no cross-device chat/voice sync.
|
|
||||||
- **Rule:** persist `metoyou.clientInstanceId` in `sessionStorage` (one id per tab/window) and clear any legacy `localStorage` copy on first read.
|
|
||||||
- **Why:** server identify evicts stale sockets with the same `(oderId, connectionScope, clientInstanceId)` tuple; a shared localStorage id makes each client kick the other in a reconnect loop.
|
|
||||||
- **Example:** `ClientInstanceService.getClientInstanceId()` writes to `sessionStorage`; two tabs get different ids and stay connected simultaneously.
|
|
||||||
|
|
||||||
### Revalidate IndexedDB scope without reinitializing on every read [persistence] [performance]
|
|
||||||
|
|
||||||
- **Trigger:** `DatabaseService.ensureReady()` called `initialize()` before every delegated read/write to fix user-scope races.
|
|
||||||
- **Rule:** cache the last validated `metoyou_currentUserId` and only re-run backend initialization when that scope changes or an in-flight initialize completes with a different scope.
|
|
||||||
- **Why:** per-operation revalidation fans out across ban lookups, room loads, and message reads, causing channel/chat UI to stay blank until repeated server clicks eventually win the race.
|
|
||||||
- **Example:** `ensureReady()` returns immediately when `isReady()` and `validatedUserScope` still match `getStoredCurrentUserId()`.
|
|
||||||
|
|
||||||
### Restore local user scope before protected writes [authentication] [persistence]
|
|
||||||
|
|
||||||
- **Trigger:** a logged-in in-memory user can create rooms or messages after `metoyou_currentUserId` was cleared by a late session-expired path.
|
|
||||||
- **Rule:** before protected local persistence or server-directory actions, restore `metoyou_currentUserId` from the current user and avoid treating a live current user as unauthenticated.
|
|
||||||
- **Why:** otherwise rooms/messages fall into the anonymous IndexedDB scope, and route checks redirect to login even though NgRx still has the authenticated user.
|
|
||||||
- **Example:** `MessagesEffects.sendMessage$`, `RoomsEffects.createRoom$`, and server-directory create/join components call `setStoredCurrentUserId(currentUser.id)` before writing or joining.
|
|
||||||
|
|
||||||
### Persisted local user state still requires a session token [authentication] [signaling]
|
|
||||||
|
|
||||||
- **Trigger:** Users appear logged in from local storage but cannot see peers online or send chat after session-token auth shipped.
|
|
||||||
- **Rule:** before connecting signaling or loading rooms for a persisted user, require a non-expired token in `metoyou.authTokens`; redirect to `/login` on `SESSION_EXPIRED`, `auth_required`, or `auth_error`.
|
|
||||||
- **Why:** WebSocket `identify` is skipped without a token, so `join_server`, RTC relay, and presence never establish even though the profile exists locally.
|
|
||||||
- **Example:** `hasValidPersistedSession()` in `auth-session.rules.ts` from `loadCurrentUser$`.
|
|
||||||
|
|
||||||
### Declare MODIFY_AUDIO_SETTINGS for Android WebRTC mic capture [mobile] [android]
|
|
||||||
|
|
||||||
- **Trigger:** Android users accept the microphone prompt but voice calls and channels still fail to join.
|
|
||||||
- **Rule:** include `android.permission.MODIFY_AUDIO_SETTINGS` in `toju-app/android/app/src/main/AndroidManifest.xml` and preflight Capacitor capture through `MobileMediaService.ensureVoiceCapturePermissions()` before `getUserMedia`.
|
|
||||||
- **Why:** Capacitor's `BridgeWebChromeClient.onPermissionRequest` requests `RECORD_AUDIO` and `MODIFY_AUDIO_SETTINGS` together; if the latter is undeclared, the combined grant is treated as denied even after the user taps Allow.
|
|
||||||
- **Example:** `ANDROID_REQUIRED_MANIFEST_PERMISSIONS` in `mobile-android-manifest-permissions.rules.ts`.
|
|
||||||
|
|
||||||
### Do not override Tailwind with box-sizing inherit [mobile] [css]
|
|
||||||
|
|
||||||
- **Trigger:** mobile pages still overflow horizontally until devtools disables `*, *::before, *::after { box-sizing: inherit }` in global styles.
|
|
||||||
- **Rule:** in `src/styles.scss` keep `box-sizing: border-box` on the universal selector (matching Tailwind preflight); never replace it with `inherit` from `html`.
|
|
||||||
- **Why:** `inherit` overrides preflight and some nested component hosts resolve to `content-box`, so `w-full` plus padding becomes wider than the parent — especially visible on the mobile dashboard beside the servers rail.
|
|
||||||
- **Example:** `src/styles.scss` `@layer base` universal rule uses `border-box`, not `inherit`.
|
|
||||||
|
|
||||||
### Use the app-shell servers rail for mobile discovery pages [mobile] [layout]
|
|
||||||
|
|
||||||
- **Trigger:** patching `min-w-0` / `overflow-x-hidden` on the dashboard (or find-people/find-servers) while the page still renders wider than the phone beside an embedded servers rail.
|
|
||||||
- **Rule:** on mobile discovery routes (`/dashboard`, `/people`, `/servers`, …) show the global `app.html` servers rail and render the page full-width in `appWorkspace`; keep embedded swiper+rail stacks only for chat/DM/call routes (`shouldShowMobileAppServersRail` in `mobile-shell-layout.rules.ts`).
|
|
||||||
- **Why:** nesting a second rail+Swiper stack inside `router-outlet` fights the shell flex width and content keeps sizing to intrinsic width, clipping cards and inputs on every viewport.
|
|
||||||
- **Example:** `hideAppServersRail()` in `app.html` + dashboard `pageContent` only (no local `<app-servers-rail>`).
|
|
||||||
|
|
||||||
### Defer attachment blob hydration on Electron startup [attachments] [electron]
|
|
||||||
|
|
||||||
- **Trigger:** fixing inline attachment display by eagerly calling `tryRestoreAttachmentFromLocal()` for every persisted attachment during `initFromDatabase()`.
|
|
||||||
- **Rule:** load attachment metadata at startup, but hydrate blob URLs only for the watched room on demand; read disk files through chunked IPC (`readFileChunk`) and yield between chunks/attachments so large images never block the renderer.
|
|
||||||
- **Why:** restoring every saved attachment as a single base64 round-trip plus synchronous `atob()` can freeze Electron for seconds even after the shell paints.
|
|
||||||
- **Example:** `runInitFromDatabase()` stops at `loadFromDatabase()`; `restoreLocalAttachmentsForRoom()` hydrates lazily via `restoreAttachmentBlobFromDiskPath()`.
|
|
||||||
|
|
||||||
### Lazy-load Capacitor modules on Electron/desktop [mobile] [electron]
|
|
||||||
|
|
||||||
- **Trigger:** adding mobile facades that statically import Capacitor adapters or `@capacitor/*` plugins into shared Angular services used by the desktop app.
|
|
||||||
- **Rule:** keep web/electron shells on web adapters synchronously and load Capacitor adapters/plugins only through dynamic `import()` after `runtime === 'capacitor'` — never top-level `import '@capacitor/...'` in code reachable from `app.ts` / `DirectCallService`.
|
|
||||||
- **Why:** bundlers evaluate static Capacitor imports during Electron startup, which can freeze the renderer before first paint even when runtime detection would have chosen the web adapter.
|
|
||||||
- **Example:** `resolveMobileAdapter()` in `mobile-capacitor-adapter.rules.ts` plus async `capacitor-plugin-loader.ts` / `loadMetoyouMobilePlugin()`.
|
|
||||||
|
|
||||||
### Use the upgrade transaction during IndexedDB schema migrations [persistence] [browser]
|
|
||||||
|
|
||||||
- **Trigger:** bumping `BROWSER_DATABASE_VERSION` and opening existing stores via `database.transaction(...)` inside `onupgradeneeded`.
|
|
||||||
- **Rule:** during `onupgradeneeded`, reuse `event.transaction.objectStore(name)` for existing stores and only call `database.createObjectStore` for missing ones — never start a second transaction while the version-change transaction is active.
|
|
||||||
- **Why:** nested transactions abort the upgrade, `authenticateUser` storage prep fails, and login/register navigates before `setCurrentUser` so DM routes throw "Cannot use direct messages without a current user."
|
|
||||||
- **Example:** `ensureObjectStoreDuringUpgrade(database, upgradeTransaction, 'messages')` in `browser-database-schema.ts`.
|
|
||||||
|
|
||||||
### Wait for authenticateUser storage prep before post-login navigation [authentication] [browser]
|
|
||||||
|
|
||||||
- **Trigger:** dispatching `UsersActions.authenticateUser` from login/register and immediately calling `router.navigate(...)`.
|
|
||||||
- **Rule:** wait for `setCurrentUser` or `loadCurrentUserFailure` (e.g. `waitForAuthenticationOutcome(actions$)`) before navigating to `returnUrl` or `/dashboard`.
|
|
||||||
- **Why:** `authenticateUser$` prepares per-user IndexedDB asynchronously; early navigation renders DM/shell routes before the current user exists in the store.
|
|
||||||
- **Example:** `await firstValueFrom(waitForAuthenticationOutcome(this.actions$))` in `register.component.ts` and `login.component.ts`.
|
|
||||||
|
|
||||||
### Use dense arrays for chunked transfer buffers [custom-emoji] [webrtc]
|
|
||||||
|
|
||||||
- **Trigger:** chunked P2P asset assembly marks a transfer complete after the first chunk because `array.some()` skips sparse holes created by `new Array(total)`.
|
|
||||||
- **Rule:** initialize chunk buffers with `Array.from({ length: total }, () => undefined)` (or another dense initializer) before using `some`/`every`/`filter` to detect completion.
|
|
||||||
- **Why:** a single assigned slot in a sparse array makes `.some((chunk) => !chunk)` return false, so multi-chunk custom emoji transfers are dropped and peers never receive uploaded images larger than one chunk.
|
|
||||||
- **Example:** `CustomEmojiService.receiveTransferStart` stores `chunks: Array.from({ length: total }, () => undefined)` instead of `new Array(total)`.
|
|
||||||
|
|
||||||
### Route custom emoji right-click through the native context menu [custom-emoji] [ux]
|
|
||||||
|
|
||||||
- **Trigger:** adding a second emoji-specific context menu beside `NativeContextMenuComponent`, or attaching handlers only to `<img>` nodes.
|
|
||||||
- **Rule:** mark emoji hosts with `data-custom-emoji` / `data-custom-emoji-library` plus `data-custom-emoji-id`, let `NativeContextMenuComponent` own add/remove actions, and use a capture-phase `preventDefault` so Electron/browser image menus do not override them.
|
|
||||||
- **Why:** the shell context menu already intercepts every image right-click; duplicate menus fight each other and button/div wrappers miss img-only handlers.
|
|
||||||
- **Example:** reaction pills and picker buttons carry the data attributes; `resolveCustomEmojiContextMenuTarget()` opens **Add to emoji library** / **Remove from emoji library** from the global menu.
|
|
||||||
|
|
||||||
### Separate known emoji assets from saved library [custom-emoji] [ux]
|
|
||||||
|
|
||||||
- **Trigger:** syncing remote custom emoji directly into the picker/library when it is first seen in chat.
|
|
||||||
- **Rule:** store remote emoji as known renderable assets, but only show them in the user's picker after an explicit save action such as right-clicking the rendered emoji.
|
|
||||||
- **Why:** users need messages to render, but they should control which seen emoji become part of their local emoji library.
|
|
||||||
- **Example:** `CustomEmojiService.emojis` filters to saved emoji, while `findEmoji(id)` can still resolve unsaved known assets for message rendering.
|
|
||||||
|
|
||||||
### Chunk custom emoji assets over data channels [custom-emoji] [webrtc]
|
|
||||||
|
|
||||||
- **Trigger:** sending uploaded custom emoji image data through a single `custom-emoji-full` peer event.
|
|
||||||
- **Rule:** stream custom emoji assets as a metadata envelope plus bounded `custom-emoji-chunk` events; use buffered sends for back-pressure, but never rely on buffering to make oversized messages safe.
|
|
||||||
- **Why:** a single base64 data URL can exceed browser SCTP message limits and fire `RTCDataChannel.onerror`, breaking the app-wide chat channel.
|
|
||||||
- **Example:** send `{ type: 'custom-emoji-full', customEmojiTransfer, total }`, then `custom-emoji-chunk` events with small `data` slices.
|
|
||||||
|
|
||||||
### Re-clear visible notification channels after recompute [notifications] [startup]
|
|
||||||
|
|
||||||
- **Trigger:** fixing startup unread badges by only changing read-marker writes or initial hydration.
|
|
||||||
- **Rule:** also check later `loadMessagesSuccess` and `syncMessages` recomputes, and re-clear the focused visible channel after applying derived unread counts.
|
|
||||||
- **Why:** the startup-selected server can load or sync messages after it was marked read, reintroducing a channel unread badge even though the user is viewing that channel.
|
|
||||||
- **Example:** `NotificationsService.refreshRoomUnreadFromMessages(...)` should clear `activeChannelId` for `currentRoom` after recalculating counts from a startup message batch.
|
|
||||||
|
|
||||||
### Disambiguate nested chat cards [chat] [ui]
|
|
||||||
|
|
||||||
- **Trigger:** removing a visual treatment from chat history when a system message has both an outer row wrapper and an inner pill/card.
|
|
||||||
- **Rule:** preserve the intended inner timeline pill unless the user explicitly targets it; render system messages outside the themed `chatMessageBubble` wrapper and keep `data-message-id` off direct child `div`s.
|
|
||||||
- **Why:** PM call-started history should stay as a compact centered pill, while theme CSS such as `app-chat-message-item > div[data-message-id]` can turn the full-width row around it into the unnecessary card.
|
|
||||||
- **Example:** In `chat-message-item.component.html`, keep `data-testid="chat-system-message"` with `rounded-full border bg-secondary/45`, put `appThemeNode="chatMessageBubble"` only on the non-system branch, and place `[attr.data-message-id]` on the nested pill instead of the system row wrapper.
|
|
||||||
|
|
||||||
### Use terminal Vitest when the test tool hangs [testing]
|
|
||||||
|
|
||||||
- **Trigger:** VS Code test execution stays at "Starting test run..." without producing Vitest output.
|
|
||||||
- **Rule:** run the focused spec through the terminal with `cd toju-app && npx vitest run <spec-path>` and report the direct Vitest result.
|
|
||||||
- **Why:** the test integration can hang before starting the runner, while the terminal Vitest command returns quickly and gives actionable failures.
|
|
||||||
- **Example:** `cd toju-app && npx vitest run src/app/domains/game-activity/application/game-activity.service.spec.ts`.
|
|
||||||
|
|
||||||
### Do not add fake chrome around screenshots [website] [design]
|
|
||||||
|
|
||||||
- **Trigger:** wrapping a real product screenshot in decorative titlebar/window chrome or placing oversized marketing headings beside copy without checking overlap.
|
|
||||||
- **Rule:** use the screenshot's existing frame when it already includes app chrome, and top-align large heading/copy columns with explicit readable widths.
|
|
||||||
- **Why:** duplicated chrome makes CTA/product previews look broken, and bottom-aligned large headings can cover accompanying text on the marketing site.
|
|
||||||
- **Example:** `website/src/app/pages/home/home.component.html` should render the screenshot directly; `host-section` should use top-aligned heading and `.host-section-copy` columns.
|
|
||||||
|
|
||||||
### Verify lint exits 0 before claiming done [verification]
|
### Verify lint exits 0 before claiming done [verification]
|
||||||
|
|
||||||
- **Trigger:** about to report a task as complete after running tests but skipping ESLint.
|
- **Trigger:** about to report a task as complete after running tests but skipping ESLint.
|
||||||
@@ -186,27 +32,6 @@ Durable rules for AI agents working on this project. Read this file at session s
|
|||||||
- **Why:** `npm run test` only runs the toju-app Vitest suite — it doesn't cover the server, Electron, or website packages. ESLint (flat config in `eslint.config.js`) is the universal check across every package; type-style violations slip through tests and break Gitea Workflows for the next agent.
|
- **Why:** `npm run test` only runs the toju-app Vitest suite — it doesn't cover the server, Electron, or website packages. ESLint (flat config in `eslint.config.js`) is the universal check across every package; type-style violations slip through tests and break Gitea Workflows for the next agent.
|
||||||
- **Example:** `npm run lint && echo OK` — only claim done after seeing `OK`. For Electron type errors specifically, also confirm `npm run build:electron` succeeds (it invokes `tsc -p tsconfig.electron.json`).
|
- **Example:** `npm run lint && echo OK` — only claim done after seeing `OK`. For Electron type errors specifically, also confirm `npm run build:electron` succeeds (it invokes `tsc -p tsconfig.electron.json`).
|
||||||
|
|
||||||
### Use blob URLs for inline attachment previews [attachments] [electron]
|
|
||||||
|
|
||||||
- **Trigger:** receiving users see broken image icons or video players that never start, but "Download" saves a valid file.
|
|
||||||
- **Rule:** never bind `attachment.objectUrl` to `file://` URLs for chat `<img>`, `<video>`, or `<audio>` — always create a `blob:` URL from the bytes on disk or in memory; keep `savedPath`/`filePath` for IPC download/open only.
|
|
||||||
- **Why:** Electron runs with `webSecurity: true`, so renderer pages cannot load arbitrary `file://` app-data paths even when CSP allows `file:`; IPC download still works because it reads the path in the main process.
|
|
||||||
- **Example:** `ensureInlineDisplayObjectUrl()` in `AttachmentPersistenceService`, and `URL.createObjectURL(blob)` in `finalizeTransferIfComplete` / `handleDiskFileChunk` instead of `getFileUrl(savedPath)`.
|
|
||||||
|
|
||||||
### Resolve Electron drag-and-drop file paths with webUtils [attachments] [electron]
|
|
||||||
|
|
||||||
- **Trigger:** large videos play after drag-and-drop upload, but after restart the uploader sees a peer-download error even though they sent the file from disk.
|
|
||||||
- **Rule:** when accepting dropped or pasted files in Electron, call `webUtils.getPathForFile(file)` from preload (`getPathForFile` on `electronAPI`) and annotate the `File` before `publishAttachments`; never rely on `File.path` in the renderer.
|
|
||||||
- **Why:** Chromium removed direct `File.path` access in modern Electron; without `getPathForFile`, large uploads only exist as in-memory blobs and cannot be copied into app data for reload playback.
|
|
||||||
- **Example:** `annotateLocalFilePath(file, { getPathForFile: electronApi.getPathForFile })` in `ChatMessageComposerComponent.addPendingFiles`.
|
|
||||||
|
|
||||||
### Preserve uploader local attachment paths across sync [attachments] [persistence]
|
|
||||||
|
|
||||||
- **Trigger:** large Electron uploads play from `filePath` after send, but after reload the uploader sees "The connected peers do not have this file right now" and must P2P-download their own file.
|
|
||||||
- **Rule:** never persist synced attachment metadata with `filePath`/`savedPath` stripped — merge with stored local paths, finish attachment DB init before applying sync batches, and try local disk restore before sending `file-request` to peers.
|
|
||||||
- **Why:** P2P sync intentionally omits local-only paths; a startup race can overwrite the uploader's saved `filePath` with `null`, and large videos (>10 MB) are not auto-copied to app data so only the original path can restore playback.
|
|
||||||
- **Example:** copy large Electron uploads into app-data on `publishAttachments`, `mergeAttachmentLocalPaths(incomingMeta, storedRecord)` in `persistAttachmentMeta`, `await persistence.whenReady()` in `registerSyncedAttachments`, and `tryRestoreAttachmentFromLocal()` before any `file-request`.
|
|
||||||
|
|
||||||
<!--
|
<!--
|
||||||
Add new lessons above this comment, newest at the top.
|
Add new lessons above this comment, newest at the top.
|
||||||
Delete this example once the project has accumulated 2-3 real lessons.
|
Delete this example once the project has accumulated 2-3 real lessons.
|
||||||
|
|||||||
@@ -1,13 +0,0 @@
|
|||||||
# ADR-0002: Session-Token Authentication on the Signaling Server
|
|
||||||
|
|
||||||
## Status
|
|
||||||
Accepted
|
|
||||||
|
|
||||||
## Context
|
|
||||||
The signaling server trusted client-supplied user IDs on REST mutations and WebSocket `identify`, allowing impersonation for kicks, bans, joins, plugin administration, and push dispatch. The product client already used bearer tokens for the Electron Local API, but the shared signaling server had no equivalent binding between HTTP/WebSocket actions and a logged-in user.
|
|
||||||
|
|
||||||
## Decision
|
|
||||||
Issue opaque session tokens on login/register, persist them in server SQLite, require `Authorization: Bearer` on all mutating REST routes, and require `identify.token` on WebSocket connections before any other client message is accepted. Actor fields (`currentOwnerId`, `actorUserId`, `requesterUserId`) are derived from the token instead of request bodies.
|
|
||||||
|
|
||||||
## Rationale
|
|
||||||
This closes identity spoofing without changing the P2P product model: discovery stays public, chat/media still relay over WebSocket, and DM WebRTC signaling remains available across servers. Bcrypt password hashing with transparent SHA-256 upgrade preserves existing accounts. A deprecation window for body-only auth was intentionally omitted so all clients must authenticate in one release, avoiding prolonged dual-trust behavior.
|
|
||||||
@@ -1,16 +0,0 @@
|
|||||||
# ADR-0003: Multi-Client Sessions with Connection-Scoped Routing
|
|
||||||
|
|
||||||
## Status
|
|
||||||
Accepted
|
|
||||||
|
|
||||||
## Context
|
|
||||||
Users expect to stay logged in on multiple devices simultaneously (Discord-style). The signaling server already issued multiple session tokens per user, but WebSocket broadcasts deduplicated by `oderId`, which prevented a user's second device from receiving chat, typing, or voice-state updates from their first device. Voice had no per-device identity, so two clients could both attempt to transmit audio.
|
|
||||||
|
|
||||||
## Decision
|
|
||||||
Introduce a stable per-install `clientInstanceId` on the product client. Route server broadcasts by **connection id** (exclude only the sender socket) while keeping presence `user_joined` / `user_left` identity-scoped. Track `voiceActive` per connection; relay RTC to the voice-active socket. Enforce single voice owner per user via `VoiceState.clientInstanceId` and `voice_client_takeover` handoff between connections.
|
|
||||||
|
|
||||||
## Consequences
|
|
||||||
- **Positive:** Chat and presence sync across a user's devices; voice behaves like Discord (one transmitting client, passive viewers, explicit takeover).
|
|
||||||
- **Positive:** Stale-tab hygiene uses `(oderId, connectionScope, clientInstanceId)` eviction without kicking other devices.
|
|
||||||
- **Negative:** `findUserByOderId` semantics change — RTC now prefers voice-active connections; callers must not assume one socket per user.
|
|
||||||
- **Negative:** Clients must include `clientInstanceId` on identify and voice payloads; older builds without it still work but cannot participate in multi-device voice exclusivity reliably.
|
|
||||||
@@ -1,23 +0,0 @@
|
|||||||
# ADR-0003: Signed Message Revision Chains for P2P Chat Integrity
|
|
||||||
|
|
||||||
## Status
|
|
||||||
Accepted
|
|
||||||
|
|
||||||
## Context
|
|
||||||
P2P chat sync compared timestamps, reaction counts, and attachment counts only. A peer could rewrite history or apply edits out of order with no cryptographic check. The product has no central message store, so integrity must travel with sync traffic and local audit logs.
|
|
||||||
|
|
||||||
## Decision
|
|
||||||
Adopt an append-only **revision chain** per message:
|
|
||||||
|
|
||||||
- Each mutation emits a `MessageRevision` (create, edit, delete, moderation, plugin) with `revision`, `prevRevisionHash`, and `headHash` (SHA-256 over canonical head state).
|
|
||||||
- Inventories advertise `{ revision, headHash }` so peers detect gaps and hash mismatches.
|
|
||||||
- Human-authored revisions are signed with per-user Ed25519 keys; public keys are registered on the signaling server for verification.
|
|
||||||
- Legacy `chat-message` / `message-edited` / `message-deleted` events continue to broadcast alongside `message-revision` for one-release backward compatibility.
|
|
||||||
|
|
||||||
## Rationale
|
|
||||||
Revision chains give deterministic merge (higher valid revision wins) without requiring a trusted relay. Signing binds edits to registered users while keeping chat payloads off the server. Dual emit avoids breaking peers that have not upgraded inventory or revision handlers yet.
|
|
||||||
|
|
||||||
## Consequences
|
|
||||||
- New persistence columns and revision audit stores on browser IDB, Electron SQLite, and Capacitor schemas.
|
|
||||||
- Plugin synthetic users may emit unsigned revisions until a plugin signing model exists.
|
|
||||||
- Attachment byte integrity (SHA-256 on `file-announce`) remains a separate follow-up.
|
|
||||||
232
agents-docs/features/access-control.md
Normal file
232
agents-docs/features/access-control.md
Normal file
@@ -0,0 +1,232 @@
|
|||||||
|
# Access Control
|
||||||
|
|
||||||
|
> **Area:** access-control
|
||||||
|
> **Status:** Active
|
||||||
|
> **Last updated:** 2026-05-25
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Access control is the **permission engine** under every Toju server: roles and their assignments, per-channel permission overrides, server membership, invites, bans, and slowmode. It runs in two places at once. The signaling server enforces it as the source of truth on REST mutations and on the `join_server` WebSocket gate. The Angular product client maintains a parallel resolution path so the UI can disable controls the user is not allowed to use, but those client-side guards are advisory — the server is authoritative.
|
||||||
|
|
||||||
|
Most concepts here were introduced over two migrations: `1000000000001-ServerAccessControl.ts` added memberships, bans, and invites; `1000000000005-ServerRoleAccessControl.ts` introduced first-class roles, role assignments, and per-channel overrides. The client carries a back-compat path that re-derives the legacy `RoomPermissions` booleans from the new role state for older UI code paths.
|
||||||
|
|
||||||
|
## Responsibilities
|
||||||
|
|
||||||
|
- Define and persist roles, role assignments, and per-channel permission overrides.
|
||||||
|
- Decide whether an identity is allowed to enter a server (`authorizeWebSocketJoin`) and, if not yet a member, what step is required (open join, password, invite).
|
||||||
|
- Maintain memberships, bans, and invites with their lifecycles (invite expiry, ban expiry).
|
||||||
|
- Resolve the effective permission state for a (user, channel) pair via role-position precedence and channel overrides.
|
||||||
|
- Hydrate the room model on join so the client can apply the same resolution locally.
|
||||||
|
- Guard moderation actions against privilege escalation via role-position checks.
|
||||||
|
|
||||||
|
This area does **not** own:
|
||||||
|
|
||||||
|
- Server catalog, discoverability, search, or moderation reports → [server-directory](./server-directory.md).
|
||||||
|
- Authentication or identity binding → [authentication](./authentication.md).
|
||||||
|
- The wire format of `join_server`, `access_denied`, role/ban update envelopes → [websocket-envelopes](./websocket-envelopes.md).
|
||||||
|
- Online status, voice presence, game activity → [presence](./presence.md).
|
||||||
|
|
||||||
|
## Key concepts
|
||||||
|
|
||||||
|
- **Role** — named row in `server_role` with a `position` (higher number = higher precedence) and a `PermissionStatePayload` of per-key overrides (`allow | deny | inherit`).
|
||||||
|
- **System role** — bootstrap roles seeded by `1000000000005-ServerRoleAccessControl.ts`: `system-everyone`, `system-moderator`, `system-admin`. `system-everyone` applies to all members; the others are assignable.
|
||||||
|
- **RoleAssignment** — (server, user, role) row in `server_user_role`.
|
||||||
|
- **ChannelPermissionOverride** — (server, channel, role) row in `server_channel_permission` carrying allow / deny / inherit per permission key on top of the role's base state.
|
||||||
|
- **Membership** — (server, user) row in `server_membership` with `createdAt` and optional metadata.
|
||||||
|
- **Invite** — single-use or multi-use server invite in `server_invite`; default expiry **10 days** from creation.
|
||||||
|
- **Ban** — (server, user) entry in `server_ban` with optional `expiresAt` and `reason`. Persists across reconnects.
|
||||||
|
- **Slowmode** — per-channel send interval (`slowModeInterval` on the channel) — currently a client-rendered hint, not enforced server-side (see TODOs).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Permission keys
|
||||||
|
|
||||||
|
Defined as a `PermissionStatePayload` in `server/src/cqrs/types.ts`. ~11 keys gate distinct capabilities:
|
||||||
|
|
||||||
|
- `manageServer` — edit server metadata (name, icon, settings).
|
||||||
|
- `manageChannels` — create / edit / delete channels.
|
||||||
|
- `manageRoles` — create / edit / delete roles (subject to role-position guard, see below).
|
||||||
|
- `moderateMember` — kick / ban / mute / change-nick on lower-positioned members.
|
||||||
|
- `inviteMember` — create invites.
|
||||||
|
- `viewChannel` — see a channel exists.
|
||||||
|
- `readMessages` — read message history in a channel.
|
||||||
|
- `writeMessages` — send messages.
|
||||||
|
- `manageMessages` — delete / pin others' messages.
|
||||||
|
- `connectVoice` — join a voice room.
|
||||||
|
- `speakVoice` — un-mute in a voice room.
|
||||||
|
|
||||||
|
Each key may be `allow`, `deny`, or `inherit` on a given role. The default state on `system-everyone` is permissive for "read / view / write" and restrictive for "manage / moderate"; see the migration for the seed values.
|
||||||
|
|
||||||
|
### Resolution algorithm
|
||||||
|
|
||||||
|
For a (user, channel) lookup:
|
||||||
|
|
||||||
|
1. Collect the user's role assignments for the server, plus the implicit `system-everyone`.
|
||||||
|
2. Order roles by `position` ascending — **lowest position resolved first**, highest position resolved last (last-writer-wins).
|
||||||
|
3. For each role, apply its base `PermissionStatePayload` to a running accumulator: `allow` and `deny` overwrite; `inherit` leaves the prior value intact.
|
||||||
|
4. Apply the channel's per-role overrides (`server_channel_permission`) on top, in the same position order.
|
||||||
|
5. The accumulator's final value per key is the effective permission.
|
||||||
|
|
||||||
|
Because there is no inherent `deny > allow` priority, a higher-positioned role's `allow` will *override* a lower-positioned role's `deny` on the same key. This is the intentional Discord-style "promote to override" model. Document any deviation from this when introducing a new key.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Membership state machine
|
||||||
|
|
||||||
|
Entry into a server runs through `joinServerWithAccess` in `server/src/services/server-access.service.ts`:
|
||||||
|
|
||||||
|
1. Look up the server. If missing → reject.
|
||||||
|
2. Look up the user's membership. If active → fast-path success.
|
||||||
|
3. Look up an active ban for `(server, user)`. If present and not expired → reject with `banned`.
|
||||||
|
4. If the server is **public** (`isPublic = true`, no password, no invite required) → create membership, return success.
|
||||||
|
5. If the server is **password-protected** (`hasPassword = true`) → require the supplied password to hash-match. If mismatch → reject with `password_required` / `bad_password`.
|
||||||
|
6. If the server is **invite-only** → require a valid (`server_invite.code`) and non-expired invite. Consume the invite if single-use.
|
||||||
|
7. On success → insert a `server_membership` row, return ok.
|
||||||
|
|
||||||
|
`authorizeWebSocketJoin` is the lighter gate used on the `join_server` WebSocket envelope: it short-circuits to "allowed" if a membership already exists, otherwise reports the access mode needed. Unlike `joinServerWithAccess`, it does **not** consume invites or process passwords — those flow through dedicated REST routes on the server before the client retries the WebSocket join.
|
||||||
|
|
||||||
|
`handleJoinServer` (`server/src/websocket/handler.ts:155`) is the call site: on rejection the server sends `access_denied` with a reason (`banned`, `password_required`, `invite_required`, ...); on success it broadcasts presence (`user_joined`) per the rules documented in [presence](./presence.md).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Moderation actions
|
||||||
|
|
||||||
|
Moderation is gated by two helpers in `server/src/services/server-permissions.service.ts`:
|
||||||
|
|
||||||
|
- `canManageServerUpdate(actorRoles, requested)` — maps the requested change (rename, icon change, permission edit, role create, invite, etc.) to the permission key it needs, then resolves the actor's effective state.
|
||||||
|
- `canModerateServerMember(actorHighestRole, targetHighestRole)` — privilege-escalation guard: the actor's highest-position role must be **strictly greater** than the target's highest-position role. Two moderators at the same position cannot ban each other.
|
||||||
|
|
||||||
|
Bans are written via `banServerUser`. The ban entity supports an optional `expiresAt` for time-limited bans and a `reason` string for moderator-facing UI.
|
||||||
|
|
||||||
|
Kick is implemented as "delete membership"; the connection is dropped via a subsequent WebSocket close on the next envelope.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Client-side hydration
|
||||||
|
|
||||||
|
When the client joins a server, the server sends the room model with normalized access-control fields:
|
||||||
|
|
||||||
|
```
|
||||||
|
roles: ServerRolePayload[]
|
||||||
|
roleAssignments: RoleAssignmentPayload[]
|
||||||
|
channelPermissions: ChannelPermissionPayload[]
|
||||||
|
permissions: legacy RoomPermissions bools (back-compat)
|
||||||
|
slowModeInterval: number | undefined (per-channel)
|
||||||
|
```
|
||||||
|
|
||||||
|
`normalizeRoomAccessControl` in `toju-app/src/app/shared-kernel/room.models.ts` is the single normalization helper. It:
|
||||||
|
|
||||||
|
- Backfills the legacy `permissions` booleans from the role state so older NgRx selectors keep working.
|
||||||
|
- Sorts roles by `position` ascending.
|
||||||
|
- De-duplicates assignments by `(userId, roleId)`.
|
||||||
|
|
||||||
|
Client-side resolution mirrors the server algorithm and lives under `toju-app/src/app/domains/access-control/domain/rules/`. Selectors expose `canSendMessage(channelId)`, `canManageRole(roleId)`, etc., which UI components consume to disable controls.
|
||||||
|
|
||||||
|
`canManageRole` enforces the same privilege-escalation guard as the server: a user cannot edit a role at or above their own highest position.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Invites
|
||||||
|
|
||||||
|
`server_invite` rows have:
|
||||||
|
|
||||||
|
- `code` — opaque token used in invite URLs.
|
||||||
|
- `serverId`, `createdById`.
|
||||||
|
- `expiresAt` — default 10 days from creation.
|
||||||
|
- `maxUses` / `uses` — single-use or multi-use semantics.
|
||||||
|
|
||||||
|
The REST surface for invite creation, lookup, and consumption is part of [server-directory](./server-directory.md). Invite consumption is **transactional**: a single-use invite is decremented before the membership row is created so a race cannot create two memberships off one invite.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Bans
|
||||||
|
|
||||||
|
`server_ban` rows carry `userId`, `serverId`, optional `expiresAt`, optional `reason`, and `createdById`. Active bans are matched on `(serverId, userId)` with the expiry filter applied at read time. A ban broadcast envelope notifies connected peers so the client can drop the banned user from the local room model — TODO: confirm whether such an envelope exists today or whether clients only learn of bans on the next `server_users` snapshot.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Slowmode
|
||||||
|
|
||||||
|
`slowModeInterval` is a per-channel hint expressed in seconds. The client renders the cooldown UI and is expected to gate the send button locally. The server does **not** enforce slowmode today — a non-cooperating client can ignore the interval. This is a known gap; see TODOs.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Business rules and invariants
|
||||||
|
|
||||||
|
- **Server is authoritative.** Client-side `canX` selectors are advisory and exist to prevent UI confusion, not to gate security.
|
||||||
|
- **Last-writer-wins by position** — there is no inherent allow/deny priority; a higher-positioned role can override a lower-positioned role's deny.
|
||||||
|
- **Privilege escalation is blocked** by requiring strict position-greater on the moderator. Same-position moderation is rejected on both sides.
|
||||||
|
- **Invite consumption is atomic** for single-use invites.
|
||||||
|
- **Bans persist independently of memberships** — a banned user without a membership row is still banned.
|
||||||
|
- **`system-everyone` always applies** at position 0 (or whatever the migration seeds); it cannot be removed.
|
||||||
|
- **Channel overrides resolve last** after role base state.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Technical implementation
|
||||||
|
|
||||||
|
### Server
|
||||||
|
- Services — `server/src/services/server-access.service.ts` (`authorizeWebSocketJoin`, `joinServerWithAccess`, `ensureServerMembership`, `banServerUser`, `leaveServerUser`); `server/src/services/server-permissions.service.ts` (`getServerRoles`, `getServerAssignments`, `resolveRolePermissionState`, `resolveHighestRole`, `canManageServerUpdate`, `canModerateServerMember`).
|
||||||
|
- Entities — `server/src/entities/ServerMembershipEntity.ts`, `ServerBanEntity.ts`, `ServerInviteEntity.ts`, `ServerRoleEntity.ts`, `ServerUserRoleEntity.ts`, `ServerChannelPermissionEntity.ts`.
|
||||||
|
- Migrations — `1000000000001-ServerAccessControl.ts`, `1000000000005-ServerRoleAccessControl.ts`.
|
||||||
|
- CQRS — payload types in `server/src/cqrs/types.ts` (`AccessRolePayload`, `PermissionStatePayload`, `RoleAssignmentPayload`, `ChannelPermissionPayload`); normalization in `server/src/cqrs/relations.ts` (`normalizeServerRoles`, `normalizeServerRoleAssignments`).
|
||||||
|
- REST — server / role / invite / ban routes are mounted under `server/src/routes/servers.ts` (catalog endpoints are documented in [server-directory](./server-directory.md)).
|
||||||
|
- WS — `server/src/websocket/handler.ts::handleJoinServer` (line 155), `access_denied` emission.
|
||||||
|
|
||||||
|
### Product client
|
||||||
|
- Domain — `toju-app/src/app/domains/access-control/`.
|
||||||
|
- Shared kernel — `toju-app/src/app/shared-kernel/access-control.models.ts`, `moderation.models.ts`, `room.models.ts` (`normalizeRoomAccessControl`).
|
||||||
|
- NgRx — access-control reducers / selectors under `toju-app/src/app/store/access-control/`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
- TODO: no spec was located for `server-access.service.ts` or `server-permissions.service.ts`.
|
||||||
|
- TODO: no spec was located for the `authorizeWebSocketJoin` rejection paths.
|
||||||
|
- Client-side rule specs likely exist under `toju-app/src/app/domains/access-control/domain/rules/*.spec.ts` — confirm and list when filling in.
|
||||||
|
- TODO: E2E coverage for invite consumption, ban enforcement, and role-position escalation.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Security considerations
|
||||||
|
|
||||||
|
- **Slowmode is not server-enforced.** A modified client can spam. Treat slowmode as an anti-accident measure, not abuse mitigation.
|
||||||
|
- **No server-side channel-permission enforcement on message send** — only role-state is checked at the join gate. TODO: verify whether per-channel overrides are applied on the message-send path.
|
||||||
|
- **No audit log** of moderation actions. TODO.
|
||||||
|
- **Password-protected servers** rely on the same SHA-256 hashing used for AuthUser passwords — see Security in [authentication](./authentication.md); the same caveats apply.
|
||||||
|
- **Position-based escalation guard** works only if positions are well-ordered. Position assignment is on `manageRoles`-bearing users; misconfiguration can produce moderators who can demote each other arbitrarily.
|
||||||
|
- **Bans are not always broadcast in real time** — clients may discover an ongoing ban only on the next `server_users` snapshot. TODO: confirm the live ban envelope.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Performance considerations
|
||||||
|
|
||||||
|
- Role and assignment lookups are point queries on `server_role` / `server_user_role` indexed by `serverId`.
|
||||||
|
- Per-channel override resolution is O(roles × channels) at hydration time; happens once on `join_server` and is cached client-side.
|
||||||
|
- `authorizeWebSocketJoin` is O(1) for existing members (single membership lookup), O(1)–O(invites) for invite consumption.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Known issues and limitations
|
||||||
|
|
||||||
|
- **No server-side slowmode enforcement.**
|
||||||
|
- **No dedicated ban-broadcast envelope** (or unconfirmed).
|
||||||
|
- **No audit log** for moderation actions.
|
||||||
|
- **Channel-permission overrides may not be applied on the message-send path** server-side — TODO.
|
||||||
|
- **Unsalted SHA-256** for password-protected server passwords — same gap as user passwords.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related features
|
||||||
|
|
||||||
|
- **[server-directory](./server-directory.md)** — owns server catalog, discoverability, and the REST surface for invites/bans/roles.
|
||||||
|
- **[authentication](./authentication.md)** — provides the `oderId` identity that access-control authorizes.
|
||||||
|
- **[presence](./presence.md)** — `user_joined` / `user_left` are emitted only after `authorizeWebSocketJoin` succeeds.
|
||||||
|
- **[websocket-envelopes](./websocket-envelopes.md)** — owns the wire shape of `join_server`, `access_denied`, role/ban update envelopes.
|
||||||
|
|
||||||
|
## Changelog
|
||||||
|
|
||||||
|
| Date | Change |
|
||||||
|
|------|--------|
|
||||||
|
| 2026-05-25 | Initial documentation |
|
||||||
@@ -1,62 +0,0 @@
|
|||||||
# App i18n
|
|
||||||
|
|
||||||
Client-side UI string localization for the product client (`toju-app`), using the same `@ngx-translate/core` stack as the marketing website.
|
|
||||||
|
|
||||||
## Responsibilities
|
|
||||||
|
|
||||||
- Bundle locale JSON under `toju-app/public/i18n/`.
|
|
||||||
- Bootstrap translations at app startup via `AppI18nService` (root `App` constructor).
|
|
||||||
- Expose `APP_TRANSLATE_IMPORTS` for standalone components that use the `translate` pipe in templates.
|
|
||||||
- Resolve the active locale through `resolveAppLocale()` in `app-i18n.rules.ts`.
|
|
||||||
|
|
||||||
## Boundaries
|
|
||||||
|
|
||||||
- **In scope:** user-visible UI copy in the Angular product client.
|
|
||||||
- **Out of scope:** server error messages, plugin-authored strings, Electron IPC payloads, and marketing-site copy (`website/public/i18n/`).
|
|
||||||
|
|
||||||
## Key files
|
|
||||||
|
|
||||||
| Path | Role |
|
|
||||||
|------|------|
|
|
||||||
| `toju-app/public/i18n/en.json` | English translation catalog (only locale shipped today). |
|
|
||||||
| `toju-app/src/app/core/i18n/app-i18n.rules.ts` | Supported locales and locale resolution. |
|
|
||||||
| `toju-app/src/app/core/i18n/app-i18n.service.ts` | Loads bundled JSON into `TranslateService`. |
|
|
||||||
| `toju-app/src/app/core/i18n/app-translate.imports.ts` | `TranslateModule` import bundle for standalone components. |
|
|
||||||
| `toju-app/src/app/app.config.ts` | `provideTranslateService()` registration. |
|
|
||||||
|
|
||||||
## Usage
|
|
||||||
|
|
||||||
**Templates** — import `APP_TRANSLATE_IMPORTS` in the standalone component and use the pipe:
|
|
||||||
|
|
||||||
```html
|
|
||||||
{{ 'common.brand' | translate }}
|
|
||||||
```
|
|
||||||
|
|
||||||
**TypeScript** — inject `AppI18nService` (or `TranslateService`) and call `instant()`:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
this.appI18n.instant('common.brand');
|
|
||||||
```
|
|
||||||
|
|
||||||
## Catalog workflow
|
|
||||||
|
|
||||||
User-visible strings live in fragment files under `toju-app/public/i18n/catalog/*.json`, merged into `toju-app/public/i18n/en.json` by:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm run i18n:sync
|
|
||||||
```
|
|
||||||
|
|
||||||
The sync script also extracts `theme.registry.*` labels/descriptions from `theme-registry.logic.ts` and `permissions.*` from `access-control.constants.ts` so those large registries stay DRY. Extracted prefixes use dotted paths and are merged as nested JSON (e.g. `theme.registry.appShell.label`, not a flat `"theme.registry"` root key).
|
|
||||||
|
|
||||||
## Adding a locale later
|
|
||||||
|
|
||||||
1. Add `toju-app/public/i18n/catalog/*.json` fragments for the new locale (or mirror `en.json` structure).
|
|
||||||
2. Register the locale in `SUPPORTED_APP_LOCALES`.
|
|
||||||
3. Import and `setTranslation()` in `AppI18nService`.
|
|
||||||
4. Wire user preference (e.g. general settings) to `AppI18nService.initialize(preferredLocale)`.
|
|
||||||
|
|
||||||
## Tests
|
|
||||||
|
|
||||||
- `toju-app/src/app/core/i18n/app-i18n.rules.spec.ts`
|
|
||||||
- `toju-app/src/app/core/i18n/app-i18n.service.spec.ts`
|
|
||||||
- `toju-app/src/app/core/i18n/app-i18n.testing.ts` — `provideAppI18nForTests()` / `initializeAppI18nForTests()` for Vitest injectors
|
|
||||||
196
agents-docs/features/attachments.md
Normal file
196
agents-docs/features/attachments.md
Normal file
@@ -0,0 +1,196 @@
|
|||||||
|
# Attachments
|
||||||
|
|
||||||
|
> **Area:** attachments
|
||||||
|
> **Status:** Active
|
||||||
|
> **Last updated:** 2026-05-25
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Attachments are pure peer-to-peer in Toju. The signaling server never sees a file byte. A sender announces an attachment on the WebRTC chat data channel; a receiver requests it; the sender streams base64-encoded 64 KiB chunks back; the receiver reassembles and (on Electron) writes the result to disk under a per-conversation folder. If the original sender goes offline mid-transfer, the receiver can re-request from another peer that previously announced the same attachment. There is no inventory protocol, no integrity signature, and no server-side fallback — attachments live entirely on the participants' machines.
|
||||||
|
|
||||||
|
This area is the closest sibling of [voice-signaling](./voice-signaling.md): both are P2P protocols that ride the same RTCPeerConnection. The chat events that drive attachments are members of the `ChatEvent` union; they share the data channel with chat messages but are conceptually distinct.
|
||||||
|
|
||||||
|
## Responsibilities
|
||||||
|
|
||||||
|
- Define the file-transfer envelope set (announce / request / chunk / cancel / not-found) and its sequencing rules.
|
||||||
|
- Maintain per-transfer state on both sides — chunk index, in-flight chunk, retry/failover bookkeeping.
|
||||||
|
- Decide whether to auto-download (size + media-type heuristic).
|
||||||
|
- Decide where to persist (Electron disk vs browser memory).
|
||||||
|
- Estimate transfer speed via EWMA so the UI can render a progress bar that doesn't jitter.
|
||||||
|
- Pick a failover peer when the current sender disappears.
|
||||||
|
|
||||||
|
This area does **not** own:
|
||||||
|
|
||||||
|
- The chat message that references the attachment → [messaging](./messaging.md).
|
||||||
|
- The peer connection or data channel itself → [voice-signaling](./voice-signaling.md).
|
||||||
|
- The IPC channels used to read / write the file on Electron → [ipc-bridge](./ipc-bridge.md).
|
||||||
|
- Permission to upload — there is no formal upload gate today; access-control's `writeMessages` is the proxy. See [access-control](./access-control.md).
|
||||||
|
|
||||||
|
## Key concepts
|
||||||
|
|
||||||
|
- **Attachment** — a file announced and referenced by a chat message. Persisted independently of the message body.
|
||||||
|
- **Transfer** — the per-receiver state for a single in-flight attachment.
|
||||||
|
- **Bucket** — storage subfolder: `image | video | audio | files`. Determined by MIME type.
|
||||||
|
- **Tried-peer set** — the set of peers a receiver has already attempted for a given `${messageId}:${fileId}`; used to drive failover without re-trying the same peer in a loop.
|
||||||
|
- **`uploaderPeerId`** — the original announcer; the receiver prefers it over the tried-peer set when (re-)issuing a `file-request`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Protocol
|
||||||
|
|
||||||
|
The five events live in the `ChatEvent` union (`toju-app/src/app/shared-kernel/chat-events.ts`) and ride the WebRTC `chat` data channel. They do **not** flow through the WebSocket signaling server.
|
||||||
|
|
||||||
|
- `file-announce` — sender announces an attachment alongside a chat message. Carries `messageId`, `fileId`, `name`, `size`, `mimeType`, optional preview metadata.
|
||||||
|
- `file-request` — receiver requests the attachment from a specific peer.
|
||||||
|
- `file-chunk` — sender streams `index`, base64-encoded chunk payload, and `total` chunk count.
|
||||||
|
- `file-cancel` — either side aborts the in-flight transfer.
|
||||||
|
- `file-not-found` — sender responds when asked for an unknown `fileId`.
|
||||||
|
|
||||||
|
### Constants
|
||||||
|
|
||||||
|
Defined in the attachment domain (`toju-app/src/app/domains/attachment/`):
|
||||||
|
|
||||||
|
- `P2P_BASE64_CHUNK_SIZE_BYTES = 64 * 1024` — re-exported as `FILE_CHUNK_SIZE_BYTES`. Shared with the avatar P2P sync path.
|
||||||
|
- `MAX_AUTO_SAVE_SIZE_BYTES = 10 * 1024 * 1024` — files at or under 10 MiB are auto-downloaded on receipt.
|
||||||
|
- `MAX_BROWSER_INLINE_MEDIA_SIZE_BYTES = 50 * 1024 * 1024` — browser-mode cap on inlined media.
|
||||||
|
- **EWMA weights** — previous-weight `0.7`, current-weight `0.3` for transfer-rate smoothing.
|
||||||
|
- **Data-channel water marks** — `highWaterMark = 4 MiB`, `lowWaterMark = 1 MiB` for backpressure pacing.
|
||||||
|
|
||||||
|
### Flow
|
||||||
|
|
||||||
|
1. Sender computes attachment metadata and emits `file-announce` referencing the chat message.
|
||||||
|
2. Receiver opens a transfer state. Auto-download triggers if `size ≤ MAX_AUTO_SAVE_SIZE_BYTES` and the MIME type is in the allow-list for the bucket. Larger files require an explicit user click.
|
||||||
|
3. Receiver sends `file-request` to `uploaderPeerId`.
|
||||||
|
4. Sender streams `file-chunk` events sequentially. **Exactly one chunk is in flight per receiver at a time** — the sender awaits the per-chunk write/ack before queueing the next one. On Electron the receiver writes each chunk to disk; the protocol requires `index === receivedCount` for the next chunk or the transfer aborts.
|
||||||
|
5. Receiver reassembles. On Electron, the file lands at:
|
||||||
|
- `{appData}/server/{room}/{bucket}/{id}{.ext}` for server-channel attachments.
|
||||||
|
- `{appData}/direct-messages/{conv}/{bucket}/{id}{.ext}` for DM attachments.
|
||||||
|
- Browser mode keeps the file as a Blob in memory — lost on reload.
|
||||||
|
6. Either side may `file-cancel`; the sender returns `file-not-found` if the requested `fileId` is unknown.
|
||||||
|
|
||||||
|
### Failover
|
||||||
|
|
||||||
|
- Receiver-driven. No inventory protocol.
|
||||||
|
- Sequential — tries one peer at a time.
|
||||||
|
- The tried-peer set is keyed by `${messageId}:${fileId}`.
|
||||||
|
- `uploaderPeerId` is always preferred when reachable; the tried-peer set ensures it isn't re-attempted in a busy loop after a failure.
|
||||||
|
- If every available peer is in the tried set, the transfer ends in a not-found state and surfaces a UI prompt.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Storage
|
||||||
|
|
||||||
|
### Electron
|
||||||
|
|
||||||
|
- `AttachmentEntity` — TypeORM row in the per-user local database. Carries `id`, `messageId`, `roomId` / `conversationId`, `name`, `size`, `mimeType`, `bucket`, `relativePath`, `createdAt`.
|
||||||
|
- CQRS commands — `save-attachment`, `delete-attachments-for-message`.
|
||||||
|
- CQRS queries — `get-all-attachments`, `get-attachments-for-message`.
|
||||||
|
- Filesystem IPC — `read-file-chunk`, `get-file-size`, `write-file`, `append-file`, `get-file-url`, `file-exists`, `delete-file`, `ensure-dir`, `get-app-data-path`.
|
||||||
|
|
||||||
|
The renderer never touches Node.js filesystem APIs directly; every read/write is brokered through [ipc-bridge](./ipc-bridge.md).
|
||||||
|
|
||||||
|
### Browser
|
||||||
|
|
||||||
|
When the desktop shell is not present, attachments stay in-memory as Blob URLs. Reloading the renderer loses them; this is documented behavior, not a bug.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Auto-download heuristic
|
||||||
|
|
||||||
|
- Any file with `size ≤ 10 MiB` and a media MIME type (`image/*`, `video/*`, `audio/*`) is auto-downloaded on receipt so the chat UI can render it inline.
|
||||||
|
- Files above the cap or in the `files` bucket require an explicit click. The chat UI shows a "Download" affordance with the file size.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Speed estimation (EWMA)
|
||||||
|
|
||||||
|
Transfer rate is exposed to the UI via an exponentially-weighted moving average:
|
||||||
|
|
||||||
|
```
|
||||||
|
rate_t = 0.7 · rate_{t-1} + 0.3 · instantaneous_t
|
||||||
|
```
|
||||||
|
|
||||||
|
Smooth enough for a stable progress display; responsive enough to surface a stalled transfer within a few seconds.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Business rules and invariants
|
||||||
|
|
||||||
|
- Attachments are **pure P2P** — the signaling server never sees an attachment byte.
|
||||||
|
- **One chunk in flight per sender → receiver** (`await` per chunk). No parallelism within a single transfer.
|
||||||
|
- **Sequential chunk indices on Electron disk receive** — `index === receivedCount` is enforced; mismatches abort.
|
||||||
|
- **`PeerDeliveryService` is not on the attachment path.** Attachments use `RealtimeSessionFacade.broadcastMessage` / `sendToPeer` / `sendToPeerBuffered` directly.
|
||||||
|
- **Browser mode loses everything on reload** — no IndexedDB persistence today for attachments.
|
||||||
|
- **No integrity / signature check** on chunks; no encryption at rest beyond OS file permissions.
|
||||||
|
- **Failover is receiver-driven** and tried-peer-set deduplicated.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Technical implementation
|
||||||
|
|
||||||
|
### Product client
|
||||||
|
- Domain — `toju-app/src/app/domains/attachment/`: manager, transfer state, persistence selection.
|
||||||
|
- Contracts — `toju-app/src/app/shared-kernel/attachment-contracts.ts`, `chat-events.ts` (the five envelope types).
|
||||||
|
- Realtime send paths — `RealtimeSessionFacade.broadcastMessage` / `sendToPeer` / `sendToPeerBuffered` in the realtime infrastructure tree.
|
||||||
|
|
||||||
|
### Electron
|
||||||
|
- Entity — `AttachmentEntity` in `electron/entities/`.
|
||||||
|
- CQRS handlers — under `electron/src/cqrs/` (or equivalent) for `save-attachment`, `delete-attachments-for-message`, `get-all-attachments`, `get-attachments-for-message`.
|
||||||
|
- Filesystem IPC handlers — `electron/ipc/`: `read-file-chunk`, `get-file-size`, `write-file`, `append-file`, `get-file-url`, `file-exists`, `delete-file`, `ensure-dir`, `get-app-data-path`.
|
||||||
|
|
||||||
|
### Key types
|
||||||
|
- `AttachmentEntity` — local persistence row.
|
||||||
|
- `FileChunkEvent`, `FileAnnounceEvent`, `FileRequestEvent`, `FileCancelEvent`, `FileNotFoundEvent` — member shapes of the `ChatEvent` union.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
- TODO: no dedicated `*.spec.ts` files under `toju-app/src/app/domains/attachment/` at time of writing.
|
||||||
|
- E2E: `e2e/tests/chat/chat-message-features.spec.ts` includes `test('syncs image and file attachments between users', ...)` which covers happy-path attachment sync.
|
||||||
|
- TODO: no E2E coverage for multi-peer failover.
|
||||||
|
- TODO: no E2E coverage for `file-cancel`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Security considerations
|
||||||
|
|
||||||
|
- **No integrity signature.** A malicious sender can corrupt a chunk; the receiver assembles whatever arrives.
|
||||||
|
- **No encryption at rest** beyond OS-level file permissions on the per-user app-data folder.
|
||||||
|
- **No MIME-type sanitation.** The receiver trusts the announced `mimeType` for bucket routing; a misleading MIME does not change the on-disk contents but does affect inline rendering. Browser-side renderers must defend against this.
|
||||||
|
- **No size cap server-side.** Caps are receiver-side and advisory: `MAX_AUTO_SAVE_SIZE_BYTES` for auto-download, `MAX_BROWSER_INLINE_MEDIA_SIZE_BYTES` for in-memory media. A sender can announce arbitrarily large files; the receiver simply refuses them.
|
||||||
|
- **Receivers expose disk write paths** indirectly: a misbehaving peer cannot escape `{appData}/server/...` or `{appData}/direct-messages/...` because the relative path is computed by the receiver, not transmitted by the sender — but this property must be preserved in any future protocol change.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Performance considerations
|
||||||
|
|
||||||
|
- **Base64 overhead.** ~33 % inflation on the wire; a 64 KiB binary chunk is ~86 KiB on the wire.
|
||||||
|
- **Single chunk in flight** per (sender, receiver) — caps single-receiver throughput at one round-trip per chunk.
|
||||||
|
- **Data-channel water marks** (4 MiB high, 1 MiB low) provide back-pressure pacing without tuning per-NIC.
|
||||||
|
- **No FEC, no parallel chunks, no resumption across browser reloads.**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Known issues and limitations
|
||||||
|
|
||||||
|
- **No dedicated unit specs** for the attachment domain.
|
||||||
|
- **No resume across browser reloads** (Electron writes to disk and survives; browser does not).
|
||||||
|
- **No checksum / signed integrity** on chunks.
|
||||||
|
- **No encryption at rest** beyond OS file permissions.
|
||||||
|
- **No server-side fallback** if every peer is offline — attachments are unreachable until at least one peer with the file returns.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related features
|
||||||
|
|
||||||
|
- **[messaging](./messaging.md)** — chat messages reference attachments; attachments are persisted separately from message bodies.
|
||||||
|
- **[voice-signaling](./voice-signaling.md)** — establishes the data channel that attachments ride on.
|
||||||
|
- **[ipc-bridge](./ipc-bridge.md)** — exposes the filesystem and CQRS APIs the Electron persistence path uses.
|
||||||
|
- **[websocket-envelopes](./websocket-envelopes.md)** — for context only; attachments do not flow through the signaling server.
|
||||||
|
|
||||||
|
## Changelog
|
||||||
|
|
||||||
|
| Date | Change |
|
||||||
|
|------|--------|
|
||||||
|
| 2026-05-25 | Initial documentation |
|
||||||
@@ -1,91 +1,194 @@
|
|||||||
# Authentication
|
# Authentication
|
||||||
|
|
||||||
Session-token authentication for the signaling server and product client.
|
> **Area:** authentication
|
||||||
|
> **Status:** Active
|
||||||
|
> **Last updated:** 2026-05-25
|
||||||
|
|
||||||
## Trust boundaries
|
## Overview
|
||||||
|
|
||||||
| Surface | Identity proof | Notes |
|
User identity in Toju is split into two surfaces. A small **HTTP credential surface** on the signaling server (`/api/users/register`, `/api/users/login`) registers and verifies user accounts persisted in TypeORM. A separate **WebSocket `identify` handshake** binds a *self-asserted* identity (`oderId` + display name + optional description) to a live WebSocket connection so the server can route envelopes. There is no server-issued session token: the client re-asserts identity on every reconnect, and other peers trust the claim as far as the signaling fabric does — i.e. only to the extent that subsequent authorization checks (see [access-control](./access-control.md)) accept it.
|
||||||
|---|---|---|
|
|
||||||
| Signaling server REST (mutations) | `Authorization: Bearer <token>` | Actor user IDs in request bodies are ignored; server derives `authUserId` from the token |
|
|
||||||
| Signaling server REST (discovery) | None | `GET /api/servers`, featured/trending/search remain public |
|
|
||||||
| Signaling server WebSocket | `identify.token` | Connections must identify before any other message type |
|
|
||||||
| Electron Local API | Separate in-memory bearer tokens | Proxies login to allowed signaling servers only |
|
|
||||||
| Product client local DB | OS user account | SQLite and attachments are plaintext at rest |
|
|
||||||
|
|
||||||
## Login / register response
|
The Electron desktop shell adds a third surface — the **Local API token store** in `electron/api/auth-store.ts` — which issues short-lived bearer tokens for the in-process HTTP server that hosts the docs site and OpenAPI bundle. That surface is internal to the desktop process and is documented here only because it shares the "authentication" name.
|
||||||
|
|
||||||
|
## Responsibilities
|
||||||
|
|
||||||
|
- Register and authenticate user accounts against the signaling server's `users` table.
|
||||||
|
- Bind a connection-scoped identity to a WebSocket connection via the `identify` envelope, including profile metadata propagation.
|
||||||
|
- Detect dead WebSocket connections via ping/pong sweeps and reap stale `ConnectedUser` rows.
|
||||||
|
- Mint and validate short-lived bearer tokens for the Electron Local API server.
|
||||||
|
|
||||||
|
This area does **not** own:
|
||||||
|
|
||||||
|
- Permissions, roles, bans, or membership state → [access-control](./access-control.md).
|
||||||
|
- Online / away / busy status, voice presence, game activity → [presence](./presence.md).
|
||||||
|
- The shape of WebSocket envelopes carrying identity claims → [websocket-envelopes](./websocket-envelopes.md).
|
||||||
|
- Profile avatar bytes or per-user assets → product-client `profile-avatar` domain.
|
||||||
|
|
||||||
|
## Key concepts
|
||||||
|
|
||||||
|
- **AuthUser** — server-persisted account: `id` (uuid), `username` (unique), `passwordHash`, `displayName`, `createdAt`. Defined in `server/src/entities/AuthUserEntity.ts`.
|
||||||
|
- **oderId** — client-asserted user identifier sent on `identify`. Used as the broadcast routing key. The server **trusts** it; there is no cryptographic binding between an AuthUser row and the `oderId` claimed over WebSocket.
|
||||||
|
- **Identify handshake** — first message a client sends on a WebSocket. Carries `oderId`, `displayName`, optional `description`, optional `profileUpdatedAt`, optional `connectionScope`.
|
||||||
|
- **Connection scope** — opaque string (typically the signal URL the client connected through). Used together with `oderId` to disambiguate multiple sockets per identity so stale-connection eviction does not loop across signal URLs.
|
||||||
|
- **Local API token** — bearer token issued by the Electron desktop process, 24 h TTL, kept in-memory and pruned on access.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## HTTP credential surface
|
||||||
|
|
||||||
|
Mounted at `/api/users` (see `server/src/routes/index.ts:20`). All payloads are JSON.
|
||||||
|
|
||||||
|
### `POST /api/users/register`
|
||||||
|
|
||||||
|
**Request:**
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"id": "<uuid>",
|
"username": "string (required, unique)",
|
||||||
"username": "alice",
|
"password": "string (required)",
|
||||||
"displayName": "Alice",
|
"displayName": "string (optional, defaults to username)"
|
||||||
"token": "<opaque-hex>",
|
|
||||||
"expiresAt": 1710000000000
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
- Tokens are opaque 64-character hex strings stored in server SQLite (`session_tokens`).
|
**Response (201):**
|
||||||
- Default TTL: 10 years (`SESSION_TOKEN_TTL_MS` env override supported on the signaling server).
|
|
||||||
- Passwords are stored with bcrypt; legacy SHA-256 hashes are upgraded transparently on successful login.
|
|
||||||
|
|
||||||
## Protected REST routes
|
|
||||||
|
|
||||||
Require `Authorization: Bearer`:
|
|
||||||
|
|
||||||
- `PUT/POST/DELETE` under `/api/servers/*` (except public `GET`)
|
|
||||||
- `PUT /api/requests/:id`
|
|
||||||
- Plugin-support mutations under `/api/servers/:serverId/plugins/*`
|
|
||||||
- `/api/users/device-tokens/*`
|
|
||||||
- `POST /api/users/logout`
|
|
||||||
|
|
||||||
## WebSocket identify contract
|
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{ "id": "uuid", "username": "string", "displayName": "string" }
|
||||||
"type": "identify",
|
|
||||||
"token": "<session-token>",
|
|
||||||
"oderId": "<user-id>",
|
|
||||||
"displayName": "Alice",
|
|
||||||
"connectionScope": "ws://host:3001",
|
|
||||||
"clientInstanceId": "<per-install-uuid>"
|
|
||||||
}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
- `oderId` must match the token's user id when provided.
|
**Errors:**
|
||||||
- `clientInstanceId` is a stable per-install UUID generated by the product client (`metoyou.clientInstanceId` in `localStorage`). The signaling server uses it to distinguish multiple WebSocket connections for the same user and to route voice ownership.
|
- **400** `Missing username/password` — either field absent.
|
||||||
- Server responds with `auth_error` or `auth_required` when authentication fails.
|
- **409** `Username taken` — username already exists.
|
||||||
|
|
||||||
## Multi-device sessions
|
### `POST /api/users/login`
|
||||||
|
|
||||||
- Each login/register issues a **new** session token; prior tokens remain valid until they expire or the client calls `POST /api/users/logout` with that token.
|
**Request:** `{ "username": "string", "password": "string" }`
|
||||||
- The same user may keep multiple WebSocket connections open (different devices or browser profiles). Server broadcasts (chat, typing, voice state, status) exclude only the **sending connection**, so other connections for that identity still receive updates.
|
|
||||||
- Voice/WebRTC is exclusive per user: only one `clientInstanceId` may own active voice at a time. Other connections show passive UI and can send `voice_client_takeover` to move voice to the local device.
|
|
||||||
- Stale reconnect hygiene: when a client re-identifies with the same `(oderId, connectionScope, clientInstanceId)` tuple, the server closes the older socket for that tuple.
|
|
||||||
|
|
||||||
## Client storage
|
**Response (200):** `{ "id": "uuid", "username": "string", "displayName": "string" }`
|
||||||
|
|
||||||
The product client stores tokens per signaling-server base URL in `localStorage` (`metoyou.authTokens`). An HTTP interceptor attaches the bearer token to `/api/*` requests targeting that server.
|
**Errors:**
|
||||||
|
- **401** `Invalid credentials` — no row matches, or stored hash differs.
|
||||||
|
|
||||||
Per-server credentials (`metoyou.signalServerCredentials`) map each normalized signal-server URL to the authenticated user id, username, display name, session token, expiry, and whether the account was auto-provisioned. The home user profile in SQLite/NgRx remains the device-local identity (`homeSignalServerUrl`); foreign-server credentials are a side map used for REST and WebSocket identify on that URL.
|
No session cookie, JWT, or bearer token is issued — the response is purely informational. The client is expected to remember the username and re-present it via the WebSocket `identify` handshake on every reconnect.
|
||||||
|
|
||||||
A per-install **provision secret** enables silent account creation on newly added or encountered signal servers. It is generated on home register/login, stored in Electron `safeStorage` when available (sessionStorage fallback on web), and never persisted as the user's visible login password.
|
---
|
||||||
|
|
||||||
### Multi-signal-server auth flows
|
## WebSocket `identify` handshake
|
||||||
|
|
||||||
| Flow | Action | Effect |
|
`handleIdentify` (`server/src/websocket/handler.ts:112`) processes the first envelope a client sends. It:
|
||||||
|---|---|---|
|
|
||||||
| Home login/register | `authenticateUser` | Resets local state, stores home credential + provision secret |
|
|
||||||
| Foreign login/register | `authorizeSignalServer` | Upserts credential for that URL only; home session unchanged |
|
|
||||||
| Auto-provision | `SignalServerProvisionerService` | Registers or logs in on foreign server using provision secret; on username collision tries suffixed username (`alice-<homeUserIdPrefix>`) |
|
|
||||||
| Foreign auth failure | `signalServerAuthFailed` | Clears that URL's credential and re-provisions when home token is still valid; global logout only when home server rejects auth |
|
|
||||||
|
|
||||||
Authorize UI: `/login?mode=authorize&serverId=…&returnUrl=…` (also supported on `/register`). Settings → Network shows per-endpoint `Authorized` / `Needs sign-in` badges.
|
1. Reads `oderId` (falls back to `connectionId` when absent).
|
||||||
|
2. Reads `connectionScope` (opaque routing key).
|
||||||
|
3. Reads / normalizes `displayName`, `description`, `profileUpdatedAt`.
|
||||||
|
4. Mutates the `ConnectedUser` row in `connectedUsers`.
|
||||||
|
5. If any of `displayName` / `description` / `profileUpdatedAt` changed, rebroadcasts `user_joined` to every server the user is currently in.
|
||||||
|
|
||||||
Persisted local user state (`metoyou_currentUserId` + IndexedDB/SQLite profile) is **not** sufficient to use chat or presence. On startup, `loadCurrentUser$` requires a non-expired session token for the user's home signaling server (or any stored token as a fallback). Missing or rejected **home** tokens dispatch `SESSION_EXPIRED` and redirect to `/login`. Foreign-server `auth_required` / `auth_error` responses clear only that server's credential and attempt re-provision.
|
`identify` itself is unauthenticated — the server does not consult `AuthUserEntity` here. Authorization happens later, at `join_server` time, via `authorizeWebSocketJoin` (documented in [access-control](./access-control.md)).
|
||||||
|
|
||||||
|
`identify` is the canonical channel for **profile updates**. Renaming yourself or updating your description means resending `identify`; the rebroadcast pushes the new profile to peers without disconnect/reconnect.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Heartbeat and dead-connection sweep
|
||||||
|
|
||||||
|
Defined in `server/src/websocket/index.ts:19`–`75`:
|
||||||
|
|
||||||
|
- `PING_INTERVAL_MS = 30_000` — server pings every connection every 30 s.
|
||||||
|
- `PONG_TIMEOUT_MS = 45_000` — a connection whose `lastPong` is older than 45 s is closed and removed from `connectedUsers`.
|
||||||
|
|
||||||
|
`lastPong` is bumped on any inbound frame (not just pong), so an active client cannot be reaped while sending traffic. Eviction triggers `handleLeaveServer` for every server the connection had joined, which in turn emits `user_left` if no other connection of the same `oderId` still holds the server.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Electron Local API token store
|
||||||
|
|
||||||
|
`electron/api/auth-store.ts` mints opaque bearer tokens used by the Local API server (`electron/api/router.ts`) to gate calls to `/api/auth/login` and other authenticated routes. Tokens have a 24 h TTL and are kept in-memory only — they do not persist across desktop restarts. Pruning happens lazily on lookup.
|
||||||
|
|
||||||
|
This surface is **not** the same identity as the signaling server's AuthUser. It is a desktop-local affordance for the in-process HTTP server that serves docs and plugin APIs; the renderer never sees these tokens.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Business rules and invariants
|
||||||
|
|
||||||
|
- Usernames are **unique** at the database level (`@Column('text', { unique: true })` on `AuthUserEntity.username`) AND pre-checked in the route handler. Comparison is **case-sensitive**.
|
||||||
|
- Passwords are hashed with **unsalted SHA-256** (`crypto.createHash('sha256')`, `routes/users.ts:8`). There is no salting, no peppering, no iteration count, no Argon2/bcrypt. This is a known weakness — see Security below.
|
||||||
|
- The signaling server never issues a session token. Identity is re-asserted on every reconnect via `identify`.
|
||||||
|
- The `identify` claim is **not verified** against `AuthUserEntity`. Two clients can claim the same `oderId`; only `(oderId, connectionScope)` is used to deduplicate eviction.
|
||||||
|
- `user_joined` is only re-broadcast on `identify` when at least one of `displayName` / `description` / `profileUpdatedAt` actually changed — duplicate identifies are silent.
|
||||||
|
- Dead-connection sweep runs continuously. A client that goes silent for ≥ 45 s is treated as disconnected.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Technical implementation
|
||||||
|
|
||||||
|
### Server (signaling)
|
||||||
|
- HTTP routes: `server/src/routes/users.ts`, mounted at `/api/users` in `server/src/routes/index.ts`.
|
||||||
|
- CQRS handlers: `server/src/cqrs/commands/handlers/registerUser.ts`, `server/src/cqrs/queries/handlers/getUserByUsername.ts`, `server/src/cqrs/queries/handlers/getUserById.ts`.
|
||||||
|
- Entity: `server/src/entities/AuthUserEntity.ts` (`users` table).
|
||||||
|
- Migration: `server/src/migrations/1000000000000-InitialSchema.ts`.
|
||||||
|
- WebSocket handshake: `server/src/websocket/handler.ts::handleIdentify` (line 112).
|
||||||
|
- `ConnectedUser` shape: `server/src/websocket/types.ts`.
|
||||||
|
- Heartbeat sweep: `server/src/websocket/index.ts`.
|
||||||
|
|
||||||
|
### Product client
|
||||||
|
- Domain: `toju-app/src/app/domains/authentication/`.
|
||||||
|
- Service: `authentication.service.ts` (login / register HTTP calls).
|
||||||
|
- Components: `login.component.ts`, `register.component.ts`.
|
||||||
|
- Model: `authentication.model.ts`.
|
||||||
|
|
||||||
|
### Electron
|
||||||
|
- Local API token store: `electron/api/auth-store.ts`.
|
||||||
|
- Local API router: `electron/api/router.ts` (`/api/auth/login` endpoint).
|
||||||
|
|
||||||
|
### Key types
|
||||||
|
- `AuthUserEntity` — server account row.
|
||||||
|
- `ConnectedUser` — live WebSocket connection state, including `oderId`, `connectionScope`, `lastPong`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
- E2E: `e2e/tests/auth/user-session-data-isolation.spec.ts` — verifies session-level data isolation between users.
|
||||||
|
- TODO: no unit specs were located for `server/src/routes/users.ts`, `handleRegisterUser`, `getUserByUsername`/`getUserById`, `handleIdentify`, the Electron `/api/auth/login` proxy, or the `toju-app` authentication services.
|
||||||
|
- TODO: no happy-path login/register E2E exists today.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Security considerations
|
## Security considerations
|
||||||
|
|
||||||
- Rate limits: login/register (100 / 15 min), server join (30 / min).
|
- **Password hashing is unsalted SHA-256.** Vulnerable to rainbow-table and parallel GPU attacks. Replacing with Argon2id or bcrypt is the obvious upgrade path and is currently a TODO.
|
||||||
- CORS allowlist: optional `corsAllowlist` in `server/data/variables.json` or `CORS_ALLOWLIST` env (comma-separated). Empty allowlist keeps permissive CORS for local development.
|
- **No rate limiting on `/login`.** A `users` table with weak hashes is exposed to credential stuffing and online brute-force.
|
||||||
- Push-token routes require bearer auth and user-id match.
|
- **`identify` is unauthenticated.** Any WebSocket can claim any `oderId`. The real authorization gate is `authorizeWebSocketJoin` on `join_server`, which checks membership / invite / password against the access-control tables — until that gate is crossed, an unverified `oderId` cannot do anything meaningful beyond joining the public lobby.
|
||||||
- RTC relay: direct-message/direct-call types always relay; server-icon types require shared server membership; WebRTC offer/answer/ice remain open for cross-server DM WebRTC.
|
- **No reuse-prevention on `displayName`.** Two distinct accounts may carry the same display name. UI must therefore disambiguate by `oderId` where identity actually matters.
|
||||||
|
- **Local API tokens** never leave the desktop process and have a 24 h TTL — they are not a credential primitive for the signaling server.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Performance considerations
|
||||||
|
|
||||||
|
- `/register` and `/login` are O(1) lookups against a `UNIQUE` index on `username`. No caching layer.
|
||||||
|
- `identify` is O(serversJoinedByThisConnection) on profile change because of the rebroadcast loop; profile updates are rare so this is negligible.
|
||||||
|
- Dead-connection sweep is O(connections) per `PING_INTERVAL_MS`; trivially scalable for a single-process signaling server.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Known issues and limitations
|
||||||
|
|
||||||
|
- **Unsalted SHA-256 password hashing.** Highest-priority hardening target.
|
||||||
|
- **No password reset, email confirmation, MFA, or account recovery.**
|
||||||
|
- **No audit log** of register/login events.
|
||||||
|
- **No binding between `AuthUserEntity.id` and the claimed `oderId`.** A future hardening pass should require the client to prove possession of an `AuthUser` credential before the server accepts an `identify` payload that names that user — likely via a signed challenge.
|
||||||
|
- **No spec coverage** for the HTTP credential surface or the identify handshake.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related features
|
||||||
|
|
||||||
|
- **[access-control](./access-control.md)** — consumes the `oderId` claimed via `identify` to authorize server joins, role lookups, and moderation actions.
|
||||||
|
- **[presence](./presence.md)** — `identify` is the canonical channel for profile-metadata updates that presence broadcasts forward.
|
||||||
|
- **[websocket-envelopes](./websocket-envelopes.md)** — owns the wire shape of `identify`, `user_joined`, and `access_denied`.
|
||||||
|
- **[ipc-bridge](./ipc-bridge.md)** — the Electron Local API token store lives behind the same IPC boundary as other privileged operations.
|
||||||
|
|
||||||
|
## Changelog
|
||||||
|
|
||||||
|
| Date | Change |
|
||||||
|
|------|--------|
|
||||||
|
| 2026-05-25 | Initial documentation |
|
||||||
|
|||||||
@@ -1,64 +0,0 @@
|
|||||||
# Custom Emoji
|
|
||||||
|
|
||||||
> **Area:** custom-emoji
|
|
||||||
> **Status:** Active
|
|
||||||
> **Last updated:** 2026-06-05
|
|
||||||
|
|
||||||
## Overview
|
|
||||||
|
|
||||||
Custom emoji lets users upload small image emoji, use them in chat messages and reactions, and sync emoji assets needed for rendering to connected peers over the existing data-channel mesh.
|
|
||||||
|
|
||||||
## Responsibilities
|
|
||||||
|
|
||||||
- Own custom emoji asset validation, local persistence, user-saved library membership, shortcut ranking, and peer-to-peer asset sync.
|
|
||||||
- Expose a shared picker consumed by chat message reactions and the chat composer.
|
|
||||||
- Keep usage ranking local to the current user; usage counts are not synced.
|
|
||||||
- Does not store custom emoji on the signaling server.
|
|
||||||
|
|
||||||
## Key Concepts
|
|
||||||
|
|
||||||
- **Custom emoji asset**: A user-created image stored as a data URL with id, name, mime, size, hash, creator, timestamps, and optional saved-library membership.
|
|
||||||
- **Known custom emoji**: A synced asset available for message rendering and forwarding, but not shown in the current user's picker unless saved.
|
|
||||||
- **Saved custom emoji**: A known asset with `savedByUser` enabled; saved emoji appear in the picker and shortcut ranking.
|
|
||||||
- **Emoji shortcut row**: The seven most-used emoji entries for the current user plus an eighth control that opens the full selector.
|
|
||||||
- **Custom emoji token**: The stable message/reaction representation `:emoji[id](name)`, resolved locally to the synced image asset when rendering.
|
|
||||||
- **Composer emoji alias**: The readable inline draft representation `:name:`. The composer rewrites known aliases to stable custom emoji tokens only when sending.
|
|
||||||
|
|
||||||
## Peer Envelope Contract
|
|
||||||
|
|
||||||
Custom emoji uses `ChatEvent` data-channel envelopes:
|
|
||||||
|
|
||||||
- `custom-emoji-summary`: `{ customEmojiSummaries: [{ id, hash, updatedAt }] }`
|
|
||||||
- `custom-emoji-request`: `{ ids: string[] }`
|
|
||||||
- `custom-emoji-full`: `{ customEmojiTransfer: Omit<CustomEmoji, 'dataUrl'>, total: number }`
|
|
||||||
- `custom-emoji-chunk`: `{ customEmojiId, index, total, data }`
|
|
||||||
|
|
||||||
When a peer connects, each side sends a summary of known assets. The receiver requests missing or stale emoji by id, and the owner replies with a small manifest followed by bounded base64 chunks using buffered peer sends. Creating a new emoji also streams that manifest and chunk sequence to every currently connected peer. Outgoing room chat messages, edits, reactions, and direct messages proactively push every referenced custom emoji asset to connected peers in parallel with the message event, so receivers do not wait for a request round-trip. Small assets that fit under `CUSTOM_EMOJI_INLINE_MAX_JSON_BYTES` travel inline in one `custom-emoji-full` event; larger assets use manifest plus chunks. Incoming chat messages and chat-sync batches still scan for `:emoji[id](name)` tokens and request any missing assets from the sender as a repair path. Full inline `customEmoji` payloads remain accepted for backward compatibility.
|
|
||||||
|
|
||||||
## Business Rules
|
|
||||||
|
|
||||||
- Uploads are capped at 1 MB.
|
|
||||||
- Accepted image types match profile avatars: WebP, GIF, JPG, and JPEG.
|
|
||||||
- Local shortcut ranking is keyed by the active user and includes Unicode emoji plus saved custom emoji only.
|
|
||||||
- Message rendering reserves inline emoji space with a transparent placeholder image while a referenced custom emoji asset is not yet available; deferred markdown placeholders rewrite tokens to readable `:name:` aliases so raw `:emoji[id](name)` text never flashes in chat.
|
|
||||||
- Seen custom emoji are not added to the picker automatically; right-click a rendered custom emoji in chat or on a custom emoji reaction and choose **Add to emoji library** from the app context menu (`NativeContextMenuComponent`).
|
|
||||||
- Saved custom emoji can be removed from the picker library by right-clicking them inside the emoji picker and choosing **Remove from emoji library**; the asset stays available for rendering messages that already reference it.
|
|
||||||
- Emoji hosts are marked with `data-custom-emoji` / `data-custom-emoji-library` plus `data-custom-emoji-id` so the global context menu can distinguish them from regular images and suppress the default **Copy Image** action.
|
|
||||||
- The full emoji picker includes a search field that filters built-in Unicode emoji by common terms and saved custom emoji by name.
|
|
||||||
- Custom emoji data-channel chunks are capped below typical SCTP message limits; back-pressure alone is not enough because a single oversized send can fire `RTCDataChannel.onerror`.
|
|
||||||
- Completed transfers are persisted only when the reconstructed data URL matches the manifest size and hash; corrupt local rows are dropped before summaries are advertised.
|
|
||||||
|
|
||||||
## Data Access
|
|
||||||
|
|
||||||
- Browser runtime stores custom emoji in IndexedDB store `customEmojis`.
|
|
||||||
- Electron runtime stores custom emoji in SQLite table `custom_emojis`, created by migration `1000000000011-AddCustomEmojis`.
|
|
||||||
- Renderer access goes through `DatabaseService` methods `saveCustomEmoji`, `getCustomEmojis`, and `deleteCustomEmoji`.
|
|
||||||
|
|
||||||
## Testing
|
|
||||||
|
|
||||||
- Unit tests cover upload size validation, shortcut selection, picker search filtering, custom emoji token generation, data-channel chunk splitting, readable composer alias rewriting, transfer integrity, saved-library membership, and add/remove library context-menu actions.
|
|
||||||
|
|
||||||
## Security Considerations
|
|
||||||
|
|
||||||
- Emoji payloads are image-only and size-limited before persistence or broadcast.
|
|
||||||
- Assets sync only to already connected peers; the signaling server does not persist or proxy emoji images.
|
|
||||||
178
agents-docs/features/ipc-bridge.md
Normal file
178
agents-docs/features/ipc-bridge.md
Normal file
@@ -0,0 +1,178 @@
|
|||||||
|
# Electron IPC Bridge
|
||||||
|
|
||||||
|
> **Area:** ipc-bridge
|
||||||
|
> **Status:** Active
|
||||||
|
> **Last updated:** 2026-05-25
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
The Electron IPC bridge is the only path through which the Angular renderer can reach the desktop runtime — the filesystem, the local SQLite database, OS APIs, the update flow, plugin loading, and the in-process Local API server. The renderer cannot import `electron`, `node:fs`, TypeORM, or any other privileged module directly; every privileged operation crosses the preload `contextBridge` boundary as a typed IPC call. This area documents the surface itself: how it is registered, how it is consumed, and what guarantees do (or do not) hold.
|
||||||
|
|
||||||
|
## Responsibilities
|
||||||
|
|
||||||
|
- Expose a frozen, allow-listed set of methods on the renderer's global window object via the preload bridge.
|
||||||
|
- Register one `ipcMain` handler per exposed method, grouped by concern (`system`, `window-controls`, `cqrs`).
|
||||||
|
- Provide a CQRS abstraction over the local database (commands + queries dispatched through two generic channels).
|
||||||
|
- Translate main-process operations into renderer-safe values (file paths → URLs, native errors → structured responses where appropriate).
|
||||||
|
|
||||||
|
This area does **not** own:
|
||||||
|
|
||||||
|
- The schema or business logic behind any specific command/query (those live in `electron/cqrs/handlers/` and the affected product-client domains).
|
||||||
|
- The plugin manifest contract (see [plugin-system](./plugin-system.md)) — only the IPC methods that surface it.
|
||||||
|
- WebSocket signaling (see [websocket-envelopes](./websocket-envelopes.md)) — that bypasses Electron entirely.
|
||||||
|
|
||||||
|
## Key concepts
|
||||||
|
|
||||||
|
- **Preload bridge** — `electron/preload.ts`. The sole place `contextBridge.exposeInMainWorld` runs. Adding a method here requires a matching `ipcMain.handle` / `ipcMain.on` on the main side.
|
||||||
|
- **Window surface** — exposed as `window.electronAPI` on the renderer. (Note: `electron/CONTEXT.md` refers to this as `window.api.*` — the documented intent. The literal global today is `electronAPI`. TODO: pick one and align.)
|
||||||
|
- **CQRS channel** — two reserved channels `cqrs:command` and `cqrs:query` route every typed `Command`/`Query` through a single dispatch step, instead of one channel per operation.
|
||||||
|
- **Handler setup function** — registered once at app boot from `electron/ipc/index.ts`: `setupCqrsHandlers`, `setupSystemHandlers`, `setupWindowControlHandlers`.
|
||||||
|
- **Renderer bridge service** — `ElectronBridgeService` in `toju-app/src/app/core/platform/electron/electron-bridge.service.ts` is the Angular-side wrapper; domain services inject it rather than reaching for `window.electronAPI` directly.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Surface catalogue
|
||||||
|
|
||||||
|
Defined in `electron/preload.ts`. Approximately 50 methods, grouped below by concern. For exact signatures see the file.
|
||||||
|
|
||||||
|
### Window controls (fire-and-forget)
|
||||||
|
|
||||||
|
- `minimizeWindow`, `maximizeWindow`, `closeWindow` — channels `window-minimize`, `window-maximize`, `window-close`. Implementation: `electron/ipc/window-controls.ts`. Uses `ipcMain.on` (no return value).
|
||||||
|
|
||||||
|
### Screen share & media
|
||||||
|
|
||||||
|
- `getSources` — DesktopCapturer source enumeration.
|
||||||
|
- Linux audio routing for screen-share monitor capture: `prepareLinuxScreenShareAudioRouting`, `activateLinuxScreenShareAudioRouting`, `deactivateLinuxScreenShareAudioRouting`, `startLinuxScreenShareMonitorCapture`, `stopLinuxScreenShareMonitorCapture`.
|
||||||
|
- Event listeners: `onLinuxScreenShareMonitorAudioChunk`, `onLinuxScreenShareMonitorAudioEnded`.
|
||||||
|
|
||||||
|
### Process & game detection
|
||||||
|
|
||||||
|
- `getRunningProcessNames` (via `electron/process-list.ts`).
|
||||||
|
- `getActiveGameCandidate` (via `electron/game-detection/`).
|
||||||
|
- `getIgnoredGameProcesses`, `setIgnoredGameProcesses`.
|
||||||
|
|
||||||
|
### File system
|
||||||
|
|
||||||
|
- `readFile`, `readFileChunk`, `getFileSize`, `writeFile`, `appendFile`, `deleteFile`, `fileExists`, `getFileUrl`, `ensureDir`, `saveFileAs`, `saveExistingFileAs`, `openFilePath`, `readClipboardFiles`.
|
||||||
|
- `getFileUrl` is the canonical way for the renderer to display a local file via `file://` — direct path access is forbidden.
|
||||||
|
|
||||||
|
### Theme & plugins (filesystem-backed)
|
||||||
|
|
||||||
|
- `getSavedThemesPath`, `listSavedThemes`, `readSavedTheme`, `writeSavedTheme`, `deleteSavedTheme`.
|
||||||
|
- `getLocalPluginsPath`, `listLocalPluginManifests`. See [plugin-system](./plugin-system.md) for the manifest contract.
|
||||||
|
|
||||||
|
### Settings & notifications
|
||||||
|
|
||||||
|
- `getDesktopSettings`, `setDesktopSettings`.
|
||||||
|
- `showDesktopNotification`, `requestWindowAttention`, `clearWindowAttention`, `onWindowStateChanged`.
|
||||||
|
|
||||||
|
### Auto-update
|
||||||
|
|
||||||
|
- `getAutoUpdateState`, `getAutoUpdateServerHealth`, `configureAutoUpdateContext`, `checkForAppUpdates`, `restartToApplyUpdate`, `onAutoUpdateStateChanged`.
|
||||||
|
|
||||||
|
### Local API & docs
|
||||||
|
|
||||||
|
- `getLocalApiStatus`, `openLocalApiDocs`, `openDocusaurusDocs`. The Local API server hosts the prebuilt Docusaurus bundle inside the desktop app — see `electron/api/local-api-server.ts`.
|
||||||
|
|
||||||
|
### App & deep links
|
||||||
|
|
||||||
|
- `relaunchApp`, `consumePendingDeepLink`, `onDeepLinkReceived`, `getAppDataPath`, `openCurrentDataFolder`.
|
||||||
|
|
||||||
|
### Data management
|
||||||
|
|
||||||
|
- `exportUserData`, `importUserData`, `eraseUserData`. Backed by `electron/data-archive.ts`.
|
||||||
|
|
||||||
|
### Clipboard & context menu
|
||||||
|
|
||||||
|
- `copyImageToClipboard`, `onContextMenu`, `contextMenuCommand`.
|
||||||
|
|
||||||
|
### Idle state
|
||||||
|
|
||||||
|
- `getIdleState`, `onIdleStateChanged`. Backed by `electron/idle/`.
|
||||||
|
|
||||||
|
### CQRS (typed database access)
|
||||||
|
|
||||||
|
- `command<T>(command: Command) => Promise<T>` → channel `cqrs:command`.
|
||||||
|
- `query<T>(query: Query) => Promise<T>` → channel `cqrs:query`.
|
||||||
|
- Command and query union types live in `electron/cqrs/types.ts`. Handlers are built dynamically per `DataSource` via `buildCommandHandlers(dataSource)` and `buildQueryHandlers(dataSource)` in `electron/ipc/cqrs.ts`.
|
||||||
|
- Current commands: `SaveMessage`, `DeleteMessage`, `UpdateMessage`, `ClearRoomMessages`, `SaveReaction`, `RemoveReaction`, `SaveUser`, `SetCurrentUserId`, `UpdateUser`, `SaveRoom`, `DeleteRoom`, `UpdateRoom`, `SaveBan`, `RemoveBan`, `SaveAttachment`, `DeleteAttachmentsForMessage`, `SavePluginData`, `DeletePluginData`, `SaveMeta`, `ClearAllData`.
|
||||||
|
- Current queries: `GetMessages`, `GetMessagesSince`, `GetMessageById`, `GetReactionsForMessage`, `GetUser`, `GetCurrentUser`, `GetCurrentUserId`, `GetUsersByRoom`, `GetRoom`, `GetAllRooms`, `GetBansForRoom`, `IsUserBanned`, `GetAttachmentsForMessage`, `GetAllAttachments`, `GetPluginData`, `GetMeta`.
|
||||||
|
- Unknown `type` raises `Error("No command/query handler for type: ${type}")`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Renderer consumption
|
||||||
|
|
||||||
|
- **`ElectronBridgeService`** (`toju-app/src/app/core/platform/electron/electron-bridge.service.ts`) — provides `getApi(): ElectronApi | null` and `requireApi(): ElectronApi`. Domain services inject the bridge service, never `window` directly. This also makes the bridge mockable for spec runs and the website preview (where `window.electronAPI` is absent).
|
||||||
|
- **CQRS wrapper**: `toju-app/src/app/infrastructure/persistence/electron-database.service.ts` wraps `api.command()` / `api.query()` with typed helpers; product-client domains use this rather than calling CQRS directly.
|
||||||
|
- **Per-domain consumers**: file I/O (`attachment`), theme (`theme`), profile-avatar, notifications, idle (used by presence), and game-activity domains each inject the bridge to reach their respective IPC slice.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Error handling
|
||||||
|
|
||||||
|
`electron/CONTEXT.md` says:
|
||||||
|
|
||||||
|
> IPC handler errors are translated to typed error envelopes before crossing back into the renderer — the renderer never sees a raw `Error` from main.
|
||||||
|
|
||||||
|
In practice today:
|
||||||
|
|
||||||
|
- The CQRS layer throws raw `Error` objects on unknown `type` (caller sees the serialized message).
|
||||||
|
- Most `electron/ipc/system.ts` handlers catch errors and return structured response objects (e.g. `{ opened: false, reason: string }`), but the shape is per-handler, not centralised.
|
||||||
|
- There is no global error-envelope wrapper around `ipcMain.handle`.
|
||||||
|
|
||||||
|
**TODO**: reconcile the CONTEXT.md invariant with reality — either introduce a shared error-envelope wrapper or update the invariant to match the per-handler convention. Until then, treat error shapes as a per-method concern.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Technical implementation
|
||||||
|
|
||||||
|
- **Preload**: `electron/preload.ts` (single source of truth for the exposed surface).
|
||||||
|
- **Registration**: `electron/ipc/index.ts` calls three setup functions at app boot — `setupCqrsHandlers`, `setupSystemHandlers`, `setupWindowControlHandlers`.
|
||||||
|
- **System handlers**: `electron/ipc/system.ts` (~40 channels, ~780 lines).
|
||||||
|
- **Window controls**: `electron/ipc/window-controls.ts` (3 channels, fire-and-forget).
|
||||||
|
- **CQRS handlers**: `electron/ipc/cqrs.ts` plus typed command/query unions in `electron/cqrs/types.ts` and per-handler implementations under `electron/cqrs/handlers/`.
|
||||||
|
- **Local SQLite access** is gated behind CQRS — no other channel exposes the database directly. See `electron/data-source.ts` and `electron/entities/`.
|
||||||
|
|
||||||
|
## Invariants
|
||||||
|
|
||||||
|
- The renderer never imports `electron`, Node APIs, or TypeORM directly. (Enforced by Electron's `contextIsolation` + no `nodeIntegration`.)
|
||||||
|
- Every method on `window.electronAPI` has exactly one IPC channel and exactly one main-process handler.
|
||||||
|
- Schema mutations go through a TypeORM migration in `electron/migrations/`; raw SQL never crosses the IPC bridge.
|
||||||
|
- All file access is path-based on the main side, URL-based on the renderer side (`getFileUrl`).
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
- `electron/plugin-library.spec.ts` — plugin discovery (touches the same IPC path but tests the library, not the channel).
|
||||||
|
- `electron/idle/idle-monitor.spec.ts` — idle source unit test.
|
||||||
|
- **TODO**: no spec covers `preload.ts` exposure, the system handler set, the CQRS dispatcher, or the error path. Renderer-side `ElectronBridgeService` spec status not verified.
|
||||||
|
|
||||||
|
## Security considerations
|
||||||
|
|
||||||
|
- `contextIsolation: true` + no `nodeIntegration` in the renderer; `electron/preload.ts` is the only crossing.
|
||||||
|
- Adding a channel requires touching both `preload.ts` and `electron/ipc/`. There is no dynamic channel registration.
|
||||||
|
- File-system handlers should validate paths against user-data scope — TODO: audit `system.ts` for path-traversal protections beyond what the plugin loader does.
|
||||||
|
- Deep-link handling: `consumePendingDeepLink` returns a queued URL; validation lives in renderer routing. TODO: confirm allow-list / scheme filtering on the main side.
|
||||||
|
|
||||||
|
## Performance considerations
|
||||||
|
|
||||||
|
- IPC traffic is per-call serialization; large payloads (file chunks, attachment imports) go via `readFileChunk` + offsets instead of single `readFile` to avoid blocking the main process.
|
||||||
|
- CQRS calls hit the local SQLite database synchronously inside the main process. There is no batching layer.
|
||||||
|
|
||||||
|
## Known issues and limitations
|
||||||
|
|
||||||
|
- **Documented vs. actual API name** — the `window` global is `electronAPI`, not `api`. CONTEXT.md uses `window.api.*`. Reconcile in a future cleanup.
|
||||||
|
- **No typed error envelope** despite the CONTEXT.md invariant.
|
||||||
|
- **No preload-surface test** — additions are caught only at runtime / lint.
|
||||||
|
|
||||||
|
## Related features
|
||||||
|
|
||||||
|
- **[plugin-system](./plugin-system.md)** — surfaces `getLocalPluginsPath`, `listLocalPluginManifests`, and plugin data CQRS commands through this bridge.
|
||||||
|
- **[websocket-envelopes](./websocket-envelopes.md)** — the realtime path that bypasses the bridge; included here only to delineate the two surfaces.
|
||||||
|
- **[voice-signaling](./voice-signaling.md)** — uses `getSources` and the Linux audio routing methods for screen-share media capture.
|
||||||
|
|
||||||
|
## Changelog
|
||||||
|
|
||||||
|
| Date | Change |
|
||||||
|
|------|--------|
|
||||||
|
| 2026-05-25 | Initial documentation |
|
||||||
@@ -1,60 +0,0 @@
|
|||||||
# Message Integrity
|
|
||||||
|
|
||||||
Signed, append-only **message revisions** give P2P chat a verifiable history without central message storage. The materialized `Message` row in local SQLite/IDB is a cache; peers converge via inventory snapshots and revision events.
|
|
||||||
|
|
||||||
## Responsibilities
|
|
||||||
|
|
||||||
- **Revision chain** — Every create, edit, delete, moderation, or plugin mutation appends a `MessageRevision` with monotonically increasing `revision`, `prevRevisionHash`, and `headHash`.
|
|
||||||
- **Dual emit** — Outgoing mutations broadcast the legacy event (`chat-message`, `message-edited`, `message-deleted`) **and** `message-revision` so older peers keep working while integrity-aware peers prefer revisions.
|
|
||||||
- **Inventory** — Sync inventories include `{ id, ts, rc, ac, revision, headHash }`. Peers re-fetch when remote revision is newer or the same revision has a different hash (tamper detection).
|
|
||||||
- **Signing** — Human authors sign revisions with per-user Ed25519 keys. Public keys are registered on the signaling server; private keys stay in browser `localStorage`.
|
|
||||||
|
|
||||||
## Boundaries
|
|
||||||
|
|
||||||
| Layer | Owns |
|
|
||||||
| --- | --- |
|
|
||||||
| Product client (`toju-app`) | Revision construction, merge, verification, P2P broadcast, local persistence |
|
|
||||||
| Signaling server (`server`) | `PUT /api/users/me/signing-key`, `GET /api/users/:id/signing-public-key` — key directory only, no message storage |
|
|
||||||
| Electron / mobile persistence | `revision` + `headHash` on message rows; revision audit log (IDB store / SQLite meta) |
|
|
||||||
|
|
||||||
Plugin API messages may emit unsigned revisions (`plugin-edit` / `plugin-delete`) when the actor is a synthetic plugin user.
|
|
||||||
|
|
||||||
## Key types
|
|
||||||
|
|
||||||
- `Message.revision`, `Message.headHash` — materialized cache fields on the shared `Message` model.
|
|
||||||
- `MessageRevision` — wire + persistence audit record (`message-revision.models.ts`).
|
|
||||||
- `MessageRevisionType` — `create`, `author-edit`, `author-delete`, `moderate-edit`, `moderate-delete`, `plugin-edit`, `plugin-delete`.
|
|
||||||
- `ChatEvent.type: 'message-revision'` — P2P envelope carrying a full `MessageRevision`.
|
|
||||||
|
|
||||||
## Merge rules
|
|
||||||
|
|
||||||
1. Valid signed revision with higher `revision` wins over legacy timestamp edits.
|
|
||||||
2. Same `revision`, different `headHash` → treat as stale/tampered and re-fetch.
|
|
||||||
3. Unsigned revisions (no `signature`) are accepted for backward compatibility when verification is skipped.
|
|
||||||
4. Legacy peers without `revision`/`headHash` in inventory fall back to `ts` / `rc` / `ac` comparison.
|
|
||||||
|
|
||||||
## Client touchpoints
|
|
||||||
|
|
||||||
- Domain rules: `message-integrity.rules.ts`, `message-revision.builder.rules.ts`, `message-sync.rules.ts`
|
|
||||||
- Services: `MessageRevisionService`, `MessageSigningService`
|
|
||||||
- Store: `messages.effects.ts` (outgoing dual-emit), `messages-incoming.handlers.ts` (`handleMessageRevision`), `messages.helpers.ts` (inventory + merge)
|
|
||||||
- Plugins: `plugin-client-api.service.ts` emits revisions for send/edit/delete
|
|
||||||
|
|
||||||
## Server API
|
|
||||||
|
|
||||||
| Method | Path | Auth | Body / response |
|
|
||||||
| --- | --- | --- | --- |
|
|
||||||
| `PUT` | `/api/users/me/signing-key` | Bearer | `{ publicKeyJwk }` — stores Ed25519 public JWK on the user row |
|
|
||||||
| `GET` | `/api/users/:id/signing-public-key` | Public | `{ publicKeyJwk }` — used by peers to verify signatures |
|
|
||||||
|
|
||||||
Registration runs automatically after login/register via `AuthenticationService`.
|
|
||||||
|
|
||||||
## Degraded-mode behavior
|
|
||||||
|
|
||||||
- Outgoing revision signing is **best-effort**: if `Ed25519` signing fails, the client still broadcasts the legacy `chat-message` envelope (unsigned revision).
|
|
||||||
- Incoming signed revisions are accepted without cryptographic verification when the sender's public key is not yet registered on the server, so chat is not blocked during key-registration races.
|
|
||||||
|
|
||||||
## Testing
|
|
||||||
|
|
||||||
- Unit: `message-integrity.rules.spec.ts`, `message-revision.builder.rules.spec.ts`, `message-revision-signing.rules.spec.ts`, `message-sync.rules.spec.ts`, `messages-incoming.handlers.spec.ts`
|
|
||||||
- Outgoing revision wiring is covered indirectly through existing message effect tests; add focused specs when changing merge or signing behavior.
|
|
||||||
195
agents-docs/features/messaging.md
Normal file
195
agents-docs/features/messaging.md
Normal file
@@ -0,0 +1,195 @@
|
|||||||
|
# Messaging
|
||||||
|
|
||||||
|
> **Area:** messaging
|
||||||
|
> **Status:** Active
|
||||||
|
> **Last updated:** 2026-05-25
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Messaging in Toju covers two transports that share a single domain model. Server-channel chat is broadcast by the signaling server over WebSocket — fire-and-forget, no server-side persistence today. Direct messages (1:1 and group DMs) are peer-to-peer over the WebRTC chat data channel, with a signaling-server fallback when no data channel is open and an offline queue for when neither path is available. On both transports the client maintains a **monotonic delivery state machine** per message and a **chunked inventory-sync protocol** that lets two peers reconcile missing history without flooding the link.
|
||||||
|
|
||||||
|
This document is the cross-context contract: envelope names, sync protocol, delivery states, edit/delete rules, and storage decisions. The product-client domain READMEs at `toju-app/src/app/domains/chat/README.md` and `toju-app/src/app/domains/direct-message/README.md` cover internal NgRx state and effects; the wire shapes live in [websocket-envelopes](./websocket-envelopes.md).
|
||||||
|
|
||||||
|
## Responsibilities
|
||||||
|
|
||||||
|
- Send, edit, and delete server-channel chat messages over WebSocket (`chat_message`, `edit_message`, `delete_message`).
|
||||||
|
- Send, edit, and delete direct messages over the WebRTC data channel with signaling fallback.
|
||||||
|
- Carry typing indicators on server-channel chat (`user_typing`).
|
||||||
|
- Reconcile peer history via the inventory-sync protocol (chunked, capped backfill).
|
||||||
|
- Drive a monotonic delivery state machine: `QUEUED → SENT → DELIVERED → ACKNOWLEDGED`.
|
||||||
|
- Persist direct messages locally; the server keeps no message store.
|
||||||
|
|
||||||
|
This area does **not** own:
|
||||||
|
|
||||||
|
- Attachment payloads or the chunked file-transfer protocol → [attachments](./attachments.md).
|
||||||
|
- RTC negotiation that brings the data channel up → [voice-signaling](./voice-signaling.md).
|
||||||
|
- Permission to send a message (`writeMessages`, `manageMessages`, channel overrides, slowmode hint) → [access-control](./access-control.md).
|
||||||
|
- The wire shape of every envelope used here → [websocket-envelopes](./websocket-envelopes.md).
|
||||||
|
|
||||||
|
## Key concepts
|
||||||
|
|
||||||
|
- **Server-channel message** — broadcast through the signaling server to every connected peer of a server. No server-side persistence in the current build.
|
||||||
|
- **Direct message** — point-to-point or group P2P message, persisted locally per-user via Electron CQRS (and via `localStorage` on browser fallback today — TODO confirm).
|
||||||
|
- **Conversation** — 1:1 or group DM thread. Group DMs can be created by adding a third participant to a 1:1, which spawns a new conversation while preserving the original.
|
||||||
|
- **Inventory event** — peer-to-peer announcement of "here is what I have for this conversation/channel"; the receiver replies with a request for missing pieces.
|
||||||
|
- **Sync batch** — chunked response carrying up to 200 messages per envelope, capped at 1000 messages of backfill per inventory exchange.
|
||||||
|
- **Delivery state** — monotonic enum on a direct message: `QUEUED (0) → SENT (1) → DELIVERED (2) → ACKNOWLEDGED (3)`. Defined in the chat-events shared kernel; advanced via `advanceDirectMessageStatus`.
|
||||||
|
- **Peer-delivery service** — `PeerDeliveryService` (`toju-app/src/app/domains/direct-message/application/services/peer-delivery.service.ts`) — the dispatcher that tries the data channel first, then the signaling forward, then the offline queue.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Transports
|
||||||
|
|
||||||
|
### Server-channel chat (WebSocket)
|
||||||
|
|
||||||
|
- Client sends `chat_message` to the signaling server; `handleChatMessage` (`server/src/websocket/handler.ts:274`) validates the user is in the target server and broadcasts to every other connection.
|
||||||
|
- `edit_message` and `delete_message` follow the same fan-out path.
|
||||||
|
- `user_typing` (`handleTyping`, `handler.ts:309`) is broadcast as a transient signal — no persistence, no sync, no delivery state.
|
||||||
|
- The server **does not persist** these envelopes. Late joiners do not see chat history older than their join — they can request it from peers via the inventory protocol if any peer present has it stored locally.
|
||||||
|
|
||||||
|
### Direct messages (WebRTC data channel)
|
||||||
|
|
||||||
|
- DMs ride the `chat`-labelled data channel established alongside each voice peer connection (see [voice-signaling](./voice-signaling.md)).
|
||||||
|
- `PeerDeliveryService` is the dispatcher. For each outgoing event it:
|
||||||
|
1. Tries every open data channel to a `recipients`-listed peer.
|
||||||
|
2. If no data channel is available to a recipient, falls back to a signaling-server `forwardPeerMessage` envelope so the server forwards it to that peer's connection.
|
||||||
|
3. If neither path is open, enqueues the event in `OfflineMessageQueueService` and replays on `peerConnected$` / `networkRestored$`.
|
||||||
|
- The server **forwards** DM envelopes opaquely — no inspection, no persistence.
|
||||||
|
|
||||||
|
### Storage
|
||||||
|
|
||||||
|
- **Direct messages** persist via Electron CQRS — see [ipc-bridge](./ipc-bridge.md). Each user has their own local TypeORM database; messages are written via `save-direct-message` / equivalent commands.
|
||||||
|
- **Server-channel chat** persists via `DatabaseService` (Electron CQRS) when running on desktop, or in IndexedDB when running purely in browser. TODO: confirm the IndexedDB code path.
|
||||||
|
- The signaling server holds **zero** message bytes at rest today. Re-deploys lose nothing because there is nothing to lose.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Inventory / sync protocol
|
||||||
|
|
||||||
|
Both transports share the same inventory shape, defined in `toju-app/src/app/shared-kernel/chat-events.ts`:
|
||||||
|
|
||||||
|
- `ChatInventoryEvent` — sender broadcasts "for conversation X I have messages with these ids and last-modified timestamps" (capped at 1000 entries).
|
||||||
|
- `ChatSyncBatchEvent` — receiver replies with a chunked batch of full message payloads, **up to 200 per envelope**, repeated until the requested set is satisfied or 1000 messages have been returned.
|
||||||
|
|
||||||
|
Rules:
|
||||||
|
|
||||||
|
- Inventory is **additive** — `mergeIncomingMessage` / `upsertDirectMessage` only insert or update; a sparser peer never wipes a richer peer's history.
|
||||||
|
- Reactions and attachment-link changes are reconciled by comparing per-message `lastModifiedAt`; the higher wins.
|
||||||
|
- The 1000-message ceiling is per inventory exchange, not per conversation lifetime; an older history can be filled in piecewise across multiple inventory cycles.
|
||||||
|
|
||||||
|
The same protocol is reused for the chat domain (server channels) and the direct-message domain. The implementation lives in `toju-app/src/app/domains/chat/domain/rules/message-sync.rules.ts` and is invoked from the direct-message effects via `DirectMessageService.requestSync()`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Delivery state machine
|
||||||
|
|
||||||
|
For DMs, every outgoing message has a `status`:
|
||||||
|
|
||||||
|
| Value | Numeric | Meaning |
|
||||||
|
|-------|---------|---------|
|
||||||
|
| `QUEUED` | 0 | Composed locally; no transport attempt has succeeded yet. |
|
||||||
|
| `SENT` | 1 | At least one transport (data channel or signaling forward) has accepted the payload. |
|
||||||
|
| `DELIVERED` | 2 | At least one recipient has acknowledged receipt at the application layer. |
|
||||||
|
| `ACKNOWLEDGED` | 3 | The full recipient set has acknowledged (1:1: the one recipient; group: every participant). |
|
||||||
|
|
||||||
|
Transitions are advanced via `advanceDirectMessageStatus`, which **only advances** — a higher value is never replaced by a lower one. A retried message that succeeds after a queue replay can therefore move `QUEUED → SENT` but never `DELIVERED → SENT`.
|
||||||
|
|
||||||
|
Server-channel messages do not carry an application-level delivery state today (the server broadcast is fire-and-forget); the UI treats them as `SENT` once the WebSocket accepts the frame.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Edit and delete
|
||||||
|
|
||||||
|
- `edit-message` / `delete-message` events carry the original `messageId`. On both transports, the receiver locates the existing row (by id) and applies the mutation via `applyMutation`.
|
||||||
|
- DMs use the same envelope types but ride the data channel / signaling-forward fabric.
|
||||||
|
- Edits are last-writer-wins by `editedAt`. A delete removes the message body but keeps a tombstone with `deletedAt` so peers that haven't yet seen the delete can converge on the next inventory sync.
|
||||||
|
|
||||||
|
TODO: `applyMutation` does not currently verify the mutation originated from the original author. A non-cooperating client could send `edit-message` for someone else's message and a receiver would accept it. Confirm and either harden client-side or document the trust model.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Typing indicators
|
||||||
|
|
||||||
|
- Server-channel only. DMs do not have a typing indicator today.
|
||||||
|
- Sent as `user_typing`; broadcast to a server scope.
|
||||||
|
- Transient: no persistence, no sync replay, no delivery state.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Business rules and invariants
|
||||||
|
|
||||||
|
- The signaling server is **not authoritative** for messaging. `handleChatMessage` only broadcasts; there is no server-side message log.
|
||||||
|
- The delivery state machine is **monotonic** — `advanceDirectMessageStatus` never moves status backwards.
|
||||||
|
- DM envelopes are **ignored** unless the local user appears in `participants` / `recipients` (or has an existing local conversation matching the id).
|
||||||
|
- Inventory merges are **additive** — `mergeIncomingMessage` / `upsertDirectMessage` never delete or downgrade a richer local row.
|
||||||
|
- A 1:1 → group upgrade **preserves** the original 1:1 history; the group is a new conversation.
|
||||||
|
- Edits / deletes are reconciled by `lastModifiedAt` / `editedAt` / `deletedAt`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Technical implementation
|
||||||
|
|
||||||
|
### Server
|
||||||
|
- WS handlers — `server/src/websocket/handler.ts`: `handleChatMessage` (line 274), `handleTyping` (309); DM forwarding via `forwardPeerMessage` / `forwardRtcMessage`.
|
||||||
|
- No CQRS, no entities, no migrations: server messaging is broadcast-only.
|
||||||
|
|
||||||
|
### Product client
|
||||||
|
- Chat domain — `toju-app/src/app/domains/chat/`: services, effects, sync rules at `domain/rules/message-sync.rules.ts`.
|
||||||
|
- Direct-message domain — `toju-app/src/app/domains/direct-message/`: `DirectMessageService`, `PeerDeliveryService` (`application/services/peer-delivery.service.ts`), offline queue.
|
||||||
|
- Shared kernel — `toju-app/src/app/shared-kernel/chat-events.ts` (`ChatInventoryEvent`, `ChatSyncBatchEvent`, `chat_message`, `edit-message`, `delete-message`, `direct-message-sync`, `direct-message-sync-request`).
|
||||||
|
- Persistence — Electron CQRS commands for DMs (see [ipc-bridge](./ipc-bridge.md)); `DatabaseService` for server-channel chat.
|
||||||
|
|
||||||
|
### Electron
|
||||||
|
- DM persistence — TypeORM entity (likely `MessageEntity` and a DM-specific row) + CQRS handlers. Backup / restore is part of the Electron data-management surface.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
- TODO: chat domain has zero `*.spec.ts` files at time of writing.
|
||||||
|
- TODO: no dedicated server-side spec for `handleChatMessage`, `handleTyping`, or `forwardRtcMessage`.
|
||||||
|
- TODO: confirm specs for `PeerDeliveryService` and `OfflineMessageQueueService`.
|
||||||
|
- E2E: `e2e/tests/chat/chat-message-features.spec.ts` covers happy-path chat and attachment sync between users.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Performance considerations
|
||||||
|
|
||||||
|
- Inventory batch cap: **200 messages per envelope**.
|
||||||
|
- Inventory backfill cap: **1000 messages per inventory exchange**.
|
||||||
|
- `chat_message` broadcast is O(N) over connected peers of the server; no fan-out batching.
|
||||||
|
- DMs incur O(recipients) data-channel writes (or signaling forwards) per send; large group DMs amplify per-message cost linearly.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Security considerations
|
||||||
|
|
||||||
|
- **No end-to-end encryption.** P2P traffic over the data channel is DTLS-encrypted by WebRTC; signaling-forwarded fallback is plain WebSocket; either way the local TypeORM database stores plaintext.
|
||||||
|
- **`applyMutation` does not verify authorship** on incoming `edit-message` / `delete-message` events. TODO above.
|
||||||
|
- **No server-side rate limiting** on `chat_message`. A non-cooperating client can flood a server's broadcast.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Known issues and limitations
|
||||||
|
|
||||||
|
- **No server-side chat history.** Late joiners depend on peers having local history to replay via inventory sync.
|
||||||
|
- **No spec coverage** for the chat domain.
|
||||||
|
- **DM authorship is not verified** by `applyMutation`.
|
||||||
|
- **No DM typing indicator.**
|
||||||
|
- **`OfflineMessageQueueService` retry policy** is currently driven by `peerConnected$` / `networkRestored$` events only — there is no scheduled retry; a stuck queue requires one of those events to fire. TODO: confirm behavior across reconnects.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related features
|
||||||
|
|
||||||
|
- **[websocket-envelopes](./websocket-envelopes.md)** — owns the wire shape of every envelope here.
|
||||||
|
- **[attachments](./attachments.md)** — file payloads ride alongside chat events on the data channel.
|
||||||
|
- **[voice-signaling](./voice-signaling.md)** — establishes the data channel DMs ride on.
|
||||||
|
- **[ipc-bridge](./ipc-bridge.md)** — exposes the CQRS persistence DMs and server chat use.
|
||||||
|
- **[access-control](./access-control.md)** — gates write permissions and slowmode.
|
||||||
|
|
||||||
|
## Changelog
|
||||||
|
|
||||||
|
| Date | Change |
|
||||||
|
|------|--------|
|
||||||
|
| 2026-05-25 | Initial documentation |
|
||||||
@@ -1,250 +0,0 @@
|
|||||||
# Mobile Capacitor
|
|
||||||
|
|
||||||
Cross-context mobile shell for the Angular product client (`toju-app/`). Wraps the existing SPA in Ionic Capacitor native projects (`toju-app/android/`, `toju-app/ios/`) while keeping Capacitor APIs behind `toju-app/src/app/infrastructure/mobile/`.
|
|
||||||
|
|
||||||
## Responsibilities
|
|
||||||
|
|
||||||
- Detect runtime shell (`browser`, `capacitor`, `electron`) without importing native plugins in domain code. Capacitor packages and adapters load only on `capacitor` shells via dynamic `import()` so Electron/desktop startup never evaluates `@capacitor/*` modules.
|
|
||||||
- Expose facades for notifications, in-call controls, media/attachments, stream pop-out, background audio session, CallKit, and native persistence.
|
|
||||||
- Integrate with direct-call, voice-workspace, and chat composer flows.
|
|
||||||
|
|
||||||
## Boundaries
|
|
||||||
|
|
||||||
| Layer | Owns |
|
|
||||||
|-------|------|
|
|
||||||
| `infrastructure/mobile/` | Platform detection, plugin lazy-loading, web/Capacitor adapters |
|
|
||||||
| `infrastructure/persistence/` | `DatabaseService` routing (`browser` / `capacitor-sqlite` / `electron`) |
|
|
||||||
| Domains (`direct-call`, `chat`, `voice-session`) | Business orchestration; inject mobile facades only |
|
|
||||||
| `core/platform/PlatformService` | Adds `isCapacitor` flag for persistence routing |
|
|
||||||
| Capacitor native projects | OS permissions, push certificates, store packaging |
|
|
||||||
|
|
||||||
## Build & run
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Production web bundle (Capacitor webDir)
|
|
||||||
npm run build:prod
|
|
||||||
|
|
||||||
# Copy web assets into native projects
|
|
||||||
npm run cap:sync
|
|
||||||
|
|
||||||
# Open IDE
|
|
||||||
npm run cap:open:android
|
|
||||||
npm run cap:open:ios
|
|
||||||
|
|
||||||
### Linux: Android Studio path
|
|
||||||
|
|
||||||
Capacitor defaults to `/usr/local/android-studio/bin/studio.sh`. If Android Studio is installed elsewhere (common with **Flatpak** from Flathub), `npm run cap:open:android` uses `tools/resolve-android-studio-path.js` to locate `studio.sh` (Flatpak `active` symlink, Toolbox, snap, `/opt`, etc.). Override anytime with `CAPACITOR_ANDROID_STUDIO_PATH`.
|
|
||||||
|
|
||||||
# Convenience (build + sync + open)
|
|
||||||
npm run cap:build:android
|
|
||||||
npm run cap:build:ios
|
|
||||||
|
|
||||||
# CI / Linux: production web bundle + Capacitor sync + Gradle debug APK
|
|
||||||
npm run cap:apk:android
|
|
||||||
# → toju-app/android/app/build/outputs/apk/debug/app-debug.apk
|
|
||||||
```
|
|
||||||
|
|
||||||
Config: `toju-app/capacitor.config.ts` (`webDir: ../dist/client/browser`).
|
|
||||||
|
|
||||||
### CI (Gitea)
|
|
||||||
|
|
||||||
Release workflow `.gitea/workflows/release-draft.yml` builds a debug Android APK on every push to `main` / `master` (job `build-android`), stages it as `Toju-<version>-android-debug.apk`, and uploads it to the same draft Gitea release as the desktop `.exe` / `.deb` assets via `tools/gitea-release.js`.
|
|
||||||
|
|
||||||
Manual-only workflow `.gitea/workflows/build-android-apk.yml` (**workflow_dispatch**) repeats the same build and release upload on demand from any branch.
|
|
||||||
|
|
||||||
Both jobs install JDK 21 and Android SDK platform 36 inside the `node:22` container and run `tools/build-android-apk.sh`. No signing keystore is configured — output is a **debug** APK suitable for sideloading and QA.
|
|
||||||
|
|
||||||
Optional `google-services.json` is not injected in CI; push registration in artifact builds follows the same optional-Firebase behavior as local unsigned debug builds.
|
|
||||||
|
|
||||||
After dependency or plugin changes, run `npm run build:prod && npm run cap:sync` so native projects register `@capacitor/app`, `@capacitor-community/sqlite`, `@capawesome/capacitor-app-update`, push plugins, and `MetoyouMobile`.
|
|
||||||
|
|
||||||
## Feature status
|
|
||||||
|
|
||||||
| Feature | Status | Notes |
|
|
||||||
|---------|--------|-------|
|
|
||||||
| Push/local notifications | **Working (partial)** | Local notifications always available; remote push (FCM/APNs) registers only when Firebase/APNs is configured — app starts normally without `google-services.json` |
|
|
||||||
| Server push dispatch | **Working (configured)** | Tokens persist in server SQLite; outbound FCM/APNs via env credentials |
|
|
||||||
| In-call notifications | **Working (Capacitor)** | Persistent notification with answer/mute/hang-up actions |
|
|
||||||
| Stream pop-out (PiP) | **Working (partial)** | Document PiP when WebView supports it; Android native PiP fallback via `MetoyouMobile` plugin |
|
|
||||||
| Background voice | **Working (partial)** | Android foreground service; iOS `UIBackgroundModes` audio + CallKit active-call bridge |
|
|
||||||
| iOS CallKit | **Working (partial)** | `MetoyouMobile.startCallKitSession` reports active calls; requires Xcode target wiring after `cap:sync` |
|
|
||||||
| Screensharing | **Limited** | Disabled on iOS WebView; Android `getDisplayMedia` may work |
|
|
||||||
| Composer attachments | **Working** | Mobile attachment button + hidden file input |
|
|
||||||
| Camera sharing | **Working** | Existing `getUserMedia` camera path in WebRTC stack |
|
|
||||||
| Speakerphone | **Working (partial)** | Android `AudioManager` via `MetoyouMobile`; iOS `@capgo/capacitor-audio-session`; direct-call speaker toggle on native mobile |
|
|
||||||
| Local DB (SQLite) | **Working** | `DatabaseService` routes Capacitor shells to `CapacitorDatabaseService` (native SQLite CRUD) |
|
|
||||||
| Store app updates | **Working (partial)** | `@capawesome/capacitor-app-update` via `MobileAppUpdateService`; Android in-app updates when Play allows, iOS opens App Store |
|
|
||||||
|
|
||||||
## Platform limitations
|
|
||||||
|
|
||||||
- **iOS background WebRTC:** OS may still suspend peer connections when backgrounded despite `audio` background mode and CallKit reporting.
|
|
||||||
- **iOS CallKit:** Plugin Swift source ships in `ios/App/App/MetoyouMobilePlugin.swift`; add it to the Xcode target if not auto-linked. Incoming-call UI is not fully bridged to WebRTC answer/hang-up yet.
|
|
||||||
- **iOS screenshare:** `getDisplayMedia` is not available in WKWebView.
|
|
||||||
- **Android PiP:** Native PiP enters activity-level PiP; WebView video may not always render inside PiP on all OEM WebViews.
|
|
||||||
- **Production discovery:** `signal.toju.app` may not expose `/api/servers/featured` or `/trending`; client skips those calls for known hosts.
|
|
||||||
- **Push delivery:** Requires FCM service account and APNs key configuration on the signaling server.
|
|
||||||
|
|
||||||
## Push notification setup (FCM / APNs)
|
|
||||||
|
|
||||||
### Android (FCM)
|
|
||||||
|
|
||||||
The app starts without Firebase. `MobilePushRegistrationService` probes `MetoyouMobile.isRemotePushConfigured()` (Firebase `FirebaseApp` on Android) before calling `PushNotifications.register()`; when unconfigured it logs a single warning and skips registration.
|
|
||||||
|
|
||||||
1. Create a Firebase project and add an Android app with package `com.metoyou.app`.
|
|
||||||
2. Copy `toju-app/android/app/google-services.json.example` to `google-services.json` (gitignored) and fill in your Firebase values.
|
|
||||||
3. Run `npm run cap:sync` so the Google Services Gradle plugin applies when the file is present (`build.gradle` applies it only when the JSON exists).
|
|
||||||
4. Rebuild with `npm run cap:build:android`.
|
|
||||||
5. Ensure `POST_NOTIFICATIONS`, `RECORD_AUDIO`, `MODIFY_AUDIO_SETTINGS`, `CAMERA`, and foreground-service permissions are granted on Android 13+.
|
|
||||||
6. Verify `MobilePushRegistrationService` logs a registration token after login.
|
|
||||||
|
|
||||||
### Android runtime permissions (voice / camera)
|
|
||||||
|
|
||||||
Capacitor's WebView requests `RECORD_AUDIO` **and** `MODIFY_AUDIO_SETTINGS` together for microphone capture. If `MODIFY_AUDIO_SETTINGS` is missing from `AndroidManifest.xml`, users can accept the prompt and `getUserMedia` still fails.
|
|
||||||
|
|
||||||
Declared in `toju-app/android/app/src/main/AndroidManifest.xml`:
|
|
||||||
|
|
||||||
| Permission | Purpose |
|
|
||||||
|------------|---------|
|
|
||||||
| `RECORD_AUDIO` | Microphone capture for voice calls and channels |
|
|
||||||
| `MODIFY_AUDIO_SETTINGS` | Required by Capacitor WebChromeClient alongside `RECORD_AUDIO` |
|
|
||||||
| `CAMERA` | WebRTC camera sharing and WebView file capture |
|
|
||||||
| `BLUETOOTH_CONNECT` | Bluetooth headset routing during calls (Android 12+) |
|
|
||||||
| `POST_NOTIFICATIONS` | Incoming/active call notifications |
|
|
||||||
| `FOREGROUND_SERVICE` / `FOREGROUND_SERVICE_MICROPHONE` | Background voice session |
|
|
||||||
|
|
||||||
Before WebRTC capture, the client calls `MobileMediaService.ensureVoiceCapturePermissions()` / `ensureCameraCapturePermissions()`, which delegate to `MetoyouMobile.requestVoiceCapturePermissions()` / `requestCameraCapturePermissions()` on Capacitor shells.
|
|
||||||
|
|
||||||
### iOS (APNs)
|
|
||||||
|
|
||||||
1. Enable Push Notifications capability in Xcode for the `App` target.
|
|
||||||
2. Upload your APNs key/certificate in Apple Developer portal.
|
|
||||||
3. `Info.plist` includes `remote-notification`, `audio`, and `voip` background modes.
|
|
||||||
4. Run on a physical device; simulator push registration is limited.
|
|
||||||
|
|
||||||
### Server token storage & dispatch
|
|
||||||
|
|
||||||
Clients POST:
|
|
||||||
|
|
||||||
```http
|
|
||||||
POST /api/users/device-tokens
|
|
||||||
Content-Type: application/json
|
|
||||||
|
|
||||||
{ "userId": "<uuid>", "platform": "android|ios", "token": "<fcm-or-apns-token>" }
|
|
||||||
```
|
|
||||||
|
|
||||||
Tokens persist in server SQLite (`device_tokens` table). Outbound push uses repository-root `.env` credentials:
|
|
||||||
|
|
||||||
| Variable | Purpose |
|
|
||||||
|----------|---------|
|
|
||||||
| `FCM_SERVICE_ACCOUNT_PATH` or `FCM_SERVICE_ACCOUNT_JSON` | Android FCM HTTP v1 |
|
|
||||||
| `APNS_KEY_PATH`, `APNS_KEY_ID`, `APNS_TEAM_ID` | iOS APNs HTTP/2 |
|
|
||||||
| `APNS_BUNDLE_ID` | Defaults to `com.metoyou.app` |
|
|
||||||
| `APNS_USE_SANDBOX` | `true` for development builds |
|
|
||||||
|
|
||||||
Manual dispatch (ops/testing):
|
|
||||||
|
|
||||||
```http
|
|
||||||
POST /api/users/device-tokens/:userId/dispatch
|
|
||||||
{ "title": "Incoming call", "body": "Alice is calling" }
|
|
||||||
```
|
|
||||||
|
|
||||||
## Android foreground service
|
|
||||||
|
|
||||||
`VoiceCallForegroundService` starts when `MobileCallSessionService` begins an active call. Required manifest permissions:
|
|
||||||
|
|
||||||
- `FOREGROUND_SERVICE`
|
|
||||||
- `FOREGROUND_SERVICE_MICROPHONE`
|
|
||||||
- `RECORD_AUDIO`
|
|
||||||
- `MODIFY_AUDIO_SETTINGS`
|
|
||||||
- `POST_NOTIFICATIONS`
|
|
||||||
|
|
||||||
The service shows a low-importance ongoing notification while a call is active.
|
|
||||||
|
|
||||||
## SQLite persistence (Capacitor)
|
|
||||||
|
|
||||||
- Schema rules: `infrastructure/mobile/logic/mobile-sqlite-schema.rules.ts` (mirrors Electron entities).
|
|
||||||
- Statement execution: `infrastructure/mobile/logic/mobile-sqlite-execute.rules.ts` — `@capacitor-community/sqlite` `execute()` accepts **one** SQL statement per call; migrations run each DDL statement separately (never concatenated).
|
|
||||||
- Row mapping: `infrastructure/mobile/logic/mobile-sqlite-row-mapper.rules.ts`.
|
|
||||||
- CRUD service: `infrastructure/persistence/capacitor-database.service.ts`.
|
|
||||||
- Routing: `infrastructure/persistence/database-backend.rules.ts` — Capacitor uses SQLite, not IndexedDB.
|
|
||||||
- Per-user database files: `metoyou__<userId>` via `mobile-sqlite-database-name.rules.ts`.
|
|
||||||
- First launch runs DDL migrations stored in the `meta` table. Schema init failures are cached per database file so the client does not retry in a loop.
|
|
||||||
|
|
||||||
## Capacitor plugin loading
|
|
||||||
|
|
||||||
- `infrastructure/mobile/adapters/capacitor/capacitor-plugin-loader.ts` uses **static** `@capacitor/*` imports and `Capacitor.isPluginAvailable()` before returning a plugin. Do not `import()` plugin modules dynamically or `await` plugin objects (Capacitor proxies expose a throwing `.then()` stub).
|
|
||||||
- After adding or upgrading Capacitor plugins, run `npm run build:prod && npm run cap:sync` so Android/iOS native projects register `App`, `AppUpdate`, `LocalNotifications`, push, and SQLite.
|
|
||||||
|
|
||||||
## Safe area (Android)
|
|
||||||
|
|
||||||
- Capacitor `SystemBars` injects `--safe-area-inset-*` CSS variables into `document.documentElement`. `index.html` sets `viewport-fit=cover` and default inset values; `main.ts` calls `applyMobileSafeAreaDefaults()` so injection never hits a missing root element after the WebView loads.
|
|
||||||
- `capacitor.config.ts` sets `plugins.SystemBars.insetsHandling: 'css'` so Android WebView versions that mis-report `env(safe-area-inset-*)` still receive correct insets.
|
|
||||||
- Global `styles.scss` applies inset padding on `html` (with `env()` fallback) and sizes `app-root` to `height: 100%` so content stays below the status bar and above the navigation bar in edge-to-edge mode.
|
|
||||||
|
|
||||||
## Self-hosted HTTPS signal servers (Android)
|
|
||||||
|
|
||||||
Electron and desktop browsers accept the repo's self-signed `.certs/localhost.crt` because Electron runs with `ignore-certificate-errors` when `SSL=true`, and browsers let users bypass the warning once. **Android WebView does neither** — it only trusts system CAs (release) or system + user-installed CAs (debug builds).
|
|
||||||
|
|
||||||
| Runtime | Trust behavior |
|
|
||||||
|---------|----------------|
|
|
||||||
| Electron (`SSL=true`) | Ignores certificate errors (`electron/app/flags.ts`) |
|
|
||||||
| Browser | User accepts warning or imports CA |
|
|
||||||
| Android debug APK | System CAs + **user-installed CAs** (`src/debug/res/xml/network_security_config.xml`) |
|
|
||||||
| Android release APK | **System CAs only** — use Let's Encrypt or another public CA |
|
|
||||||
|
|
||||||
### Certificate requirements
|
|
||||||
|
|
||||||
1. **Trust:** Install `.certs/localhost.crt` on the Android device as a **CA certificate** (Settings → Security → Encryption & credentials → Install a certificate → CA certificate). Debug APKs pick this up automatically; release builds ignore user CAs.
|
|
||||||
2. **SAN:** The cert must list every host clients use. Regenerate with the server IP in the SAN when connecting by IP:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
rm -rf .certs
|
|
||||||
SERVER_IP=46.59.68.77 ./generate-cert.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
Restart the signaling server after regenerating certs.
|
|
||||||
|
|
||||||
3. **HTTPS only:** `AndroidManifest.xml` sets `android:usesCleartextTraffic="false"`. Server URLs must use `https://` (matching `environment.ts` / saved server endpoints).
|
|
||||||
|
|
||||||
### Troubleshooting
|
|
||||||
|
|
||||||
| Symptom | Likely cause |
|
|
||||||
|---------|----------------|
|
|
||||||
| `ERR_CERT_AUTHORITY_INVALID` / silent fetch failure | CA not installed on device, or testing a **release** APK with a self-signed cert |
|
|
||||||
| `ERR_CERT_COMMON_NAME_INVALID` | Cert SAN missing the IP/hostname (regenerate with `SERVER_IP`) |
|
|
||||||
| `ERR_CONNECTION_REFUSED` | Port unreachable from the phone (firewall, NAT, server not listening on `0.0.0.0`) — verify with `curl -k https://46.59.68.77:3001/api/health` from the device browser first |
|
|
||||||
| Works in Chrome on phone, fails in app | Chrome may use a different trust store path; ensure the CA is installed at the **system** level, not only per-browser |
|
|
||||||
|
|
||||||
Network security configs:
|
|
||||||
|
|
||||||
- `android/app/src/main/res/xml/network_security_config.xml` — release (system CAs, no cleartext)
|
|
||||||
- `android/app/src/debug/res/xml/network_security_config.xml` — debug (+ user CAs for dev)
|
|
||||||
|
|
||||||
**Do not commit** `.certs/*.crt`, `.certs/*.key`, or device-specific credential files.
|
|
||||||
|
|
||||||
## Integration points
|
|
||||||
|
|
||||||
- `DirectCallService` — incoming/active call notifications, ring-queue on user hydration, notification action routing.
|
|
||||||
- `PrivateCallComponent` — speakerphone toggle on native mobile shells.
|
|
||||||
- `ChatMessageComposerComponent` — `shouldShowAttachmentButton` + `pickAttachmentsFromDevice()`.
|
|
||||||
- `VoiceWorkspaceStreamTileComponent` — PiP when focused stream tile backgrounds.
|
|
||||||
- `MobileCallSessionService` — CallKit + foreground service + in-call notifications.
|
|
||||||
- `App` bootstrap — initializes mobile persistence, lifecycle, app-update polling, call-session, and push registration wiring.
|
|
||||||
- `MobileAppUpdateService` — periodic Play Store / App Store checks (30 min) and settings UI actions; mirrors Electron `DesktopAppUpdateService` polling but uses native store APIs instead of release manifests.
|
|
||||||
|
|
||||||
## Phase 3 completion notes
|
|
||||||
|
|
||||||
Phase 3 delivered:
|
|
||||||
|
|
||||||
1. Full `CapacitorDatabaseService` CRUD with `DatabaseService` routing on `isCapacitor`.
|
|
||||||
2. Server SQLite persistence for device tokens plus FCM/APNs outbound dispatch.
|
|
||||||
3. iOS CallKit bridge (partial) via `MetoyouMobile` plugin and `MobileCallKitService`.
|
|
||||||
4. Android Firebase Gradle wiring with `google-services.json.example` (real file gitignored).
|
|
||||||
5. Capacitor plugin availability checks to avoid hard failures when plugins are missing pre-sync.
|
|
||||||
6. Discovery endpoint skip for production signal hosts without featured/trending routes.
|
|
||||||
|
|
||||||
Remaining work:
|
|
||||||
|
|
||||||
- Wire CallKit answer/end actions back into `DirectCallService`.
|
|
||||||
- Migrate legacy IndexedDB mobile data into SQLite where needed.
|
|
||||||
- Deploy featured/trending routes to production signal servers or add capability negotiation in health checks.
|
|
||||||
180
agents-docs/features/plugin-system.md
Normal file
180
agents-docs/features/plugin-system.md
Normal file
@@ -0,0 +1,180 @@
|
|||||||
|
# Plugin System
|
||||||
|
|
||||||
|
> **Area:** plugin-system
|
||||||
|
> **Status:** Active
|
||||||
|
> **Last updated:** 2026-05-25
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Plugins extend Toju's renderer with bundled or local ES modules that can publish events into a server, register UI contributions (pages, panels, actions, channel sections, embed renderers), store per-user or per-server data, and exchange messages over P2P. They are described by a typed manifest, gated by an explicit capability grant model, and coordinated across three subdomains: the Electron plugin loader (`electron/plugin-library.ts`), the renderer plugin runtime (`toju-app/src/app/domains/plugins/`), and the server's plugin-support surface (`server/src/routes/plugin-support.ts`). This area documents the contract those three sides share.
|
||||||
|
|
||||||
|
## Responsibilities
|
||||||
|
|
||||||
|
- Define the canonical plugin manifest shape (`TojuPluginManifest`) and its semantic versioning, dependency, and capability requirements.
|
||||||
|
- Discover local plugin manifests from disk in Electron and surface them to the renderer.
|
||||||
|
- Load plugin modules — local file://, http(s)://, or bundled — into the renderer and run their lifecycle hooks.
|
||||||
|
- Gate every host API call by an explicit capability grant.
|
||||||
|
- Persist server-scoped plugin requirements and event definitions on the signaling server, broadcasting changes to connected clients.
|
||||||
|
|
||||||
|
This area does **not** own:
|
||||||
|
|
||||||
|
- The wire format of `plugin_event` envelopes themselves — those live with [websocket-envelopes](./websocket-envelopes.md); this area defines the **validation rules** applied to them.
|
||||||
|
- IPC plumbing for plugin manifest discovery — that's the [ipc-bridge](./ipc-bridge.md) surface.
|
||||||
|
- Per-plugin business logic — that lives in the plugin's own code.
|
||||||
|
|
||||||
|
## Key concepts
|
||||||
|
|
||||||
|
- **Manifest** — `TojuPluginManifest` (`toju-app/src/app/shared-kernel/plugin-system.contracts.ts`). Required: `id`, `title`, `description`, `version`, `apiVersion`, `kind`, `schemaVersion` (fixed `1`), `compatibility.minimumTojuVersion`. Optional: `entrypoint`, `bundle`, `capabilities[]`, `events[]`, `data[]`, `ui`, `settings`, `relationships`, `authors`, `pluginUser`, `scope`, `homepage`, `changelog`, `license`, `readme`, `load.priority`.
|
||||||
|
- **Capability** — a string ID (e.g. `messages.send`, `events.server.publish`, `ui.pages`, `storage.local`). Plugins declare what they need in `capabilities[]`; the host enforces grants per plugin.
|
||||||
|
- **Plugin event** — a declared `{ eventName, direction, scope, schema?, maxPayloadBytes? }` tuple. `direction` is `clientToServer | serverRelay | p2pHint`; `scope` is `server | channel | user | plugin`.
|
||||||
|
- **Capability grant** — an entry in `metoyou_plugin_capability_grants` (localStorage + desktop file) recording user consent for a `(pluginId, capability)` pair.
|
||||||
|
- **Activation context** — `TojuPluginActivationContext` — what a plugin module receives in its `activate(context)` hook: `pluginId`, `manifest`, `api` (the capability-gated `TojuClientPluginApi`), and a `subscriptions[]` cleanup list.
|
||||||
|
- **Local plugin** — a folder under `${app.getPath('userData')}/plugins/<id>/` containing `toju-plugin.json` (preferred) or `plugin.json` and resolved relative assets.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Manifest contract
|
||||||
|
|
||||||
|
Declared in `toju-app/src/app/shared-kernel/plugin-system.contracts.ts` (the source of truth on the renderer side; the Electron loader treats the manifest as `unknown` until the renderer validates it).
|
||||||
|
|
||||||
|
Highlights:
|
||||||
|
|
||||||
|
- **`schemaVersion: 1`** — fixed; bump only with a coordinated migration.
|
||||||
|
- **`apiVersion`** — declares which host API surface the plugin expects.
|
||||||
|
- **`kind`** — distinguishes plugin types (currently a string union; see file for exact members).
|
||||||
|
- **`bundle.url`** + optional `bundle.entrypointUrl` — for remote / store-installed plugins.
|
||||||
|
- **`entrypoint`** — relative path within the local plugin folder; rejected if it escapes `pluginRoot`.
|
||||||
|
- **`relationships.{requires,optional,conflicts,before,after}`** — `pluginId` + optional `versionRange`. Resolved at activation; missing required dependencies block activation.
|
||||||
|
- **`events[]`** — registered with the server via `plugin-support` when the plugin is required by a server. The server uses these definitions to validate inbound `plugin_event` envelopes.
|
||||||
|
- **`data[]`** — `{ key, scope: server|channel|user|plugin, storage: local|serverData, schema? }`.
|
||||||
|
- **`load.priority`** — `bootstrap | high | default | low`; controls ordering when several plugins are activated together.
|
||||||
|
- **`pluginUser`** — synthetic user identity for messages a plugin posts on its own behalf.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Discovery & loading
|
||||||
|
|
||||||
|
### Local discovery (Electron main)
|
||||||
|
|
||||||
|
`electron/plugin-library.ts`:
|
||||||
|
|
||||||
|
- Scans `${app.getPath('userData')}/plugins/` **one level deep** for plugin folders.
|
||||||
|
- For each folder, reads `toju-plugin.json` (preferred) or `plugin.json` as raw JSON. No schema validation at this layer.
|
||||||
|
- Resolves relative paths (`entrypoint`, `readme`) against the plugin root, rejecting `..`, absolute paths, or anything that escapes the root via `isPathInside()` realpath check.
|
||||||
|
- Returns `LocalPluginDiscoveryResult { plugins, errors, pluginsPath }` where each `plugins[i]` is a `LocalPluginManifestDescriptor` carrying the raw manifest, manifest path, plugin root, plugin-root `file://` URL, optional entrypoint and readme paths, and a `discoveredAt` timestamp.
|
||||||
|
|
||||||
|
Exposed to the renderer through the [ipc-bridge](./ipc-bridge.md) as `listLocalPluginManifests` and `getLocalPluginsPath`.
|
||||||
|
|
||||||
|
### Renderer runtime
|
||||||
|
|
||||||
|
`toju-app/src/app/domains/plugins/`:
|
||||||
|
|
||||||
|
- **`PluginHostService`** — orchestrates lifecycle: `discoverLocalPlugins`, `registerLocalManifest`, `activate`, `deactivate`, `reload`, `loadPluginModule`.
|
||||||
|
- **`PluginClientApiService`** — constructs the capability-gated facade `TojuClientPluginApi` per plugin. Subsystems: `channels`, `events`, `messages`, `messageBus`, `p2p`, `profile`, `users`, `roles`, `server`, `attachments`, `media`, `storage`, `serverData`, `clientData`, `ui`, `logger`, `context`.
|
||||||
|
- **`PluginCapabilityService`** — `grant(pluginId, capability)`, `revoke()`, `grantAll(manifest)`, `assert(pluginId, capability)`. Storage in `metoyou_plugin_capability_grants` (localStorage + desktop file).
|
||||||
|
- **`PluginMessageBusService`** — plugin-scoped pub/sub with topic, optional channel/peer targeting, optional message replay.
|
||||||
|
- **`PluginStorageService`** — split storage paths for `local` and `serverData` scopes.
|
||||||
|
- **`PluginUiRegistryService`** — central registry of UI contributions consumed by `plugin-render-host`, `plugin-page-host`, `plugin-action-menu`.
|
||||||
|
- **`PluginRequirementStateService`**, **`PluginDesktopStateService`** — state slices.
|
||||||
|
|
||||||
|
### Module loading
|
||||||
|
|
||||||
|
- Entrypoint URL is `file://` for local plugins, `http(s)://` for remote, or the `bundle.url` for bundled.
|
||||||
|
- Bytes are fetched, wrapped in a `Blob`-backed object URL, then imported via dynamic `import()` so devtools and stack traces resolve.
|
||||||
|
- `GuardedPluginMutationObserver` wraps observer callbacks to catch plugin errors and break infinite redispatch loops.
|
||||||
|
|
||||||
|
### Lifecycle states
|
||||||
|
|
||||||
|
From `plugin-runtime.models.ts`: `discovered → validated → blocked | loading → ready → loaded → failed | unloading → unloaded → disabled`.
|
||||||
|
|
||||||
|
### Module contract
|
||||||
|
|
||||||
|
```ts
|
||||||
|
export interface TojuClientPluginModule {
|
||||||
|
activate?(context: TojuPluginActivationContext): void | Promise<void>;
|
||||||
|
deactivate?(context: TojuPluginActivationContext): void | Promise<void>;
|
||||||
|
ready?(context: TojuPluginActivationContext): void | Promise<void>;
|
||||||
|
onServerRequirementsChanged?(context, snapshot): void | Promise<void>;
|
||||||
|
onPluginDataChanged?(context, event): void | Promise<void>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Server surface (`server/src/routes/plugin-support.ts`)
|
||||||
|
|
||||||
|
Each endpoint scoped to `:serverId`. Permission `manageServer` enforced for mutations via `server-permissions.service.ts`.
|
||||||
|
|
||||||
|
- `GET /:serverId/plugins` → `PluginRequirementsSnapshot` — full set of required/optional plugins + event definitions for the server.
|
||||||
|
- `PUT /:serverId/plugins/:pluginId/requirement` — upsert a requirement: `status: required | optional | recommended | blocked | incompatible`, `installUrl?`, `sourceUrl?`, `manifest?`, `versionRange?`.
|
||||||
|
- `DELETE /:serverId/plugins/:pluginId/requirement` — remove.
|
||||||
|
- `PUT /:serverId/plugins/:pluginId/events/:eventName` — register or update an event definition (`direction`, `scope`, `schema?`, `maxPayloadBytes?`).
|
||||||
|
- `DELETE /:serverId/plugins/:pluginId/events/:eventName` — delete.
|
||||||
|
- `GET|PUT|DELETE /:serverId/plugins/:pluginId/data/:key` — **disabled** on the signaling server (returns HTTP 410). Plugin data on the server is intentionally out of scope.
|
||||||
|
|
||||||
|
Identifier patterns:
|
||||||
|
|
||||||
|
- `pluginId`: `/^[a-z0-9][a-z0-9.-]{1,126}[a-z0-9]$/`
|
||||||
|
- `eventName`: `/^[a-z][a-z0-9.:-]{1,126}[a-z0-9]$/`
|
||||||
|
|
||||||
|
Changes broadcast to connected clients via the [websocket-envelopes](./websocket-envelopes.md) — the matching `PluginRequirementsSnapshot` is also delivered as part of the `join_server` and `view_server` responses.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Plugin event validation
|
||||||
|
|
||||||
|
`server/src/services/plugin-support.service.ts` exposes `validatePluginEventEnvelope()`. The `plugin_event` envelope handler (`server/src/websocket/handler.ts`) calls it before broadcasting. Validation checks:
|
||||||
|
|
||||||
|
- `eventName` is registered for `pluginId` on `serverId`.
|
||||||
|
- `direction` permits the source (clientToServer vs p2pHint vs serverRelay).
|
||||||
|
- `payload` size ≤ `maxPayloadBytes` (default 64 KB).
|
||||||
|
- If `schema` was declared in the manifest, the payload conforms — TODO: confirm the schema dialect (looks like JSON Schema subset).
|
||||||
|
|
||||||
|
## Security considerations
|
||||||
|
|
||||||
|
- **Plugins run in the renderer's JS context.** There is no true sandbox: plugins have DOM access, can read/write `localStorage`, and can issue `fetch` requests subject to the renderer's CSP.
|
||||||
|
- **Capability model is the primary security boundary.** Every method on `TojuClientPluginApi` calls `PluginCapabilityService.assert(pluginId, capability)`. Missing grant → `PluginCapabilityError`.
|
||||||
|
- **Path traversal** in the local plugin loader is blocked by `isPathInside()` realpath checks (`electron/plugin-library.ts`).
|
||||||
|
- **Payload bounds** on plugin events: default 64 KB, configurable per event definition.
|
||||||
|
- **No code signing or integrity verification.** Plugins are trusted to the extent the user granted capabilities. The plugin store flow is documented in `docs-site/docs/plugin-development/`.
|
||||||
|
- **TODO**: review whether `bundle.url` fetches go through a CSP / allow-list or are unbounded.
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
- **Local plugins path**: `${app.getPath('userData')}/plugins/` (Electron). Exposed as `getLocalPluginsPath`.
|
||||||
|
- **Capability grants**: `metoyou_plugin_capability_grants` in localStorage; mirrored to a desktop file via `PluginDesktopStateService`.
|
||||||
|
- **Server-side persistence**: plugin requirements and event definitions are stored in the server's database; entities and migrations live alongside other server entities (TODO: enumerate the specific entities).
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
- **Electron**: `electron/plugin-library.spec.ts` — covers valid/invalid JSON, path traversal rejection, escaping entrypoints. Uses fixture `TEST_PLUGIN_FIXTURE_DIR`.
|
||||||
|
- **Renderer**: `plugin-host.service.spec.ts`, `plugin-store.service.spec.ts`, `local-plugin-discovery.service.spec.ts`.
|
||||||
|
- **Server**: `server/src/websocket/handler-plugin.spec.ts` — `plugin_event` validation flow.
|
||||||
|
- **E2E**: `e2e/tests/.../plugin-support-api.spec.ts`, `plugin-manager-ui.spec.ts`, `plugin-api-two-users.spec.ts`.
|
||||||
|
|
||||||
|
## Known issues and limitations
|
||||||
|
|
||||||
|
- **Server-side plugin data is intentionally disabled** (`410 Gone` on `*/data/:key` routes). Plugins must currently treat `serverData` storage as not yet implemented on the signaling server. TODO: clarify whether this is a permanent boundary or scheduled work.
|
||||||
|
- **No true sandbox** for plugin execution. The capability model is the only restraint between a plugin and the renderer's globals.
|
||||||
|
- **Manifest validation is renderer-side.** The Electron loader treats manifests as raw JSON; malformed or hostile manifests are caught when the renderer registers them.
|
||||||
|
- **No host-side plugin allow-list** beyond per-server requirements — a user can install any local plugin.
|
||||||
|
|
||||||
|
## Related features
|
||||||
|
|
||||||
|
- **[ipc-bridge](./ipc-bridge.md)** — surfaces `listLocalPluginManifests`, `getLocalPluginsPath`, and the plugin CQRS commands (`SavePluginData`, `DeletePluginData`, `GetPluginData`).
|
||||||
|
- **[websocket-envelopes](./websocket-envelopes.md)** — defines the `plugin_event` envelope this area validates.
|
||||||
|
- **[server-directory](./server-directory.md)** — `join_server` / `view_server` responses include `PluginRequirementsSnapshot` for the joined server.
|
||||||
|
|
||||||
|
## Documentation for plugin authors
|
||||||
|
|
||||||
|
Author-facing docs ship with the desktop app via Docusaurus:
|
||||||
|
|
||||||
|
- `docs-site/docs/plugin-development/create-a-plugin.md`
|
||||||
|
- `docs-site/docs/user-guide/plugins.md`
|
||||||
|
- `docs-site/docs/developer/llm-plugin-builder-guide.md`
|
||||||
|
|
||||||
|
## Changelog
|
||||||
|
|
||||||
|
| Date | Change |
|
||||||
|
|------|--------|
|
||||||
|
| 2026-05-25 | Initial documentation |
|
||||||
196
agents-docs/features/presence.md
Normal file
196
agents-docs/features/presence.md
Normal file
@@ -0,0 +1,196 @@
|
|||||||
|
# Presence
|
||||||
|
|
||||||
|
> **Area:** presence
|
||||||
|
> **Status:** Active
|
||||||
|
> **Last updated:** 2026-05-25
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Presence in Toju covers everything that signals "who is here, where, and doing what" — connection lifecycle (`join_server`, `leave_server`), availability status (`online / away / busy / offline`), profile metadata propagation, voice-room membership, and the current-game indicator. The signaling server **forwards and deduplicates** presence over WebSocket but never persists it: every restart of the server resets all presence state to nothing, and every reconnect of a client re-derives the world from scratch via a `server_users` snapshot.
|
||||||
|
|
||||||
|
Several signals contribute. Status comes from idle detection in the renderer (Electron `powerMonitor` or browser fallback) and from explicit user choices. Voice membership is **client-derived** from observed `voice_state` broadcasts — the server never tracks who is in a voice room. Game activity is scanned in the renderer using Electron-IPC process inspection, resolved via the server's RAWG-backed `/games/match` API, and broadcast directly to peers over the WebRTC data channel — it never touches the signaling server.
|
||||||
|
|
||||||
|
## Responsibilities
|
||||||
|
|
||||||
|
- Track which users are connected to which server and broadcast joins/leaves with multi-device dedup.
|
||||||
|
- Carry profile metadata (`displayName`, `description`, `profileUpdatedAt`) so peers can render rich identity without a separate lookup.
|
||||||
|
- Propagate availability status (`online / away / busy / offline`) as users choose, idle, or wake.
|
||||||
|
- Surface voice-room membership to peers via the `voice_state` envelope.
|
||||||
|
- Surface current-game activity to peers via the chat data channel.
|
||||||
|
|
||||||
|
This area does **not** own:
|
||||||
|
|
||||||
|
- The WebSocket envelope shape — see [websocket-envelopes](./websocket-envelopes.md).
|
||||||
|
- RTC negotiation, peer connection lifecycle, RNNoise — see [voice-signaling](./voice-signaling.md).
|
||||||
|
- Server-side account records, credentials, or the `identify` handshake's authentication semantics — see [authentication](./authentication.md).
|
||||||
|
- Authorization for joining a server (membership / bans / invites) — see [access-control](./access-control.md).
|
||||||
|
|
||||||
|
## Key concepts
|
||||||
|
|
||||||
|
- **`oderId`** — client-asserted identity. The deduplication key across multiple sockets and devices.
|
||||||
|
- **`connectionScope`** — opaque string (typically the signal URL). Used together with `oderId` to coexist multi-URL sockets without an eviction loop.
|
||||||
|
- **Status** — `'online' | 'away' | 'busy' | 'offline'`. `VALID_STATUSES` lives in `server/src/websocket/handler.ts`. Client maps incoming `offline` to a local `disconnected` rendering tag.
|
||||||
|
- **Manual vs automatic status** — manual user choices override the idle-detector.
|
||||||
|
- **Voice presence** — derived client-side from `voice_state` broadcasts; the signaling server has no voice-room model.
|
||||||
|
- **Game activity** — currently-detected game; resolved via `/games/match` and announced to peers over the data channel as a `game-activity` chat event.
|
||||||
|
- **`ConnectedUser`** — server-side per-connection row (`server/src/websocket/types.ts`); see [authentication](./authentication.md) for the full shape.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Envelopes (consumed and emitted)
|
||||||
|
|
||||||
|
Schemas live in [websocket-envelopes](./websocket-envelopes.md). Presence-relevant types:
|
||||||
|
|
||||||
|
- `identify` — first envelope a client sends; updates profile metadata. Re-broadcasts `user_joined` per joined server when profile fields change.
|
||||||
|
- `join_server` / `leave_server` — connection joins/leaves a specific server scope; gated by `authorizeWebSocketJoin` (see [access-control](./access-control.md)).
|
||||||
|
- `server_users` — full peer roster sent to a connection when it joins a server; the only "snapshot" envelope.
|
||||||
|
- `user_joined` — broadcast to peers on a server when a new *identity* arrives (i.e. no other connection of the same `oderId` already had this server).
|
||||||
|
- `user_left` — broadcast to peers when an identity fully releases a server; payload includes `serverIds` listing the servers the user is still in elsewhere.
|
||||||
|
- `status_update` — availability status change (`online / away / busy / offline`).
|
||||||
|
- `voice_state` — broadcast to a server when the user enters/leaves voice or toggles mute/deafen. Carries `roomId`, `voiceGateway`, mute/deafen flags. Voice membership is reconstructed from these events client-side.
|
||||||
|
- `keepalive` — bumps `lastPong` on the server to keep the connection from being reaped.
|
||||||
|
- `access_denied` — server response when authorization for `join_server` fails.
|
||||||
|
|
||||||
|
Game activity events ride the WebRTC **chat data channel** as `game-activity` chat events — not as WebSocket envelopes.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Lifecycle
|
||||||
|
|
||||||
|
A connection moves through these stages:
|
||||||
|
|
||||||
|
1. **WebSocket connect** — server allocates a `ConnectedUser` row keyed by `connectionId`.
|
||||||
|
2. **`identify`** — client claims `oderId`, profile metadata, and an optional `connectionScope`. See [authentication](./authentication.md) for the handshake details.
|
||||||
|
3. **`join_server`** — gated by `authorizeWebSocketJoin`. On success, the server adds the server to `user.serverIds`, sends a private `server_users` snapshot to the joiner, and broadcasts `user_joined` to other peers on that server *only if* this is a new identity for the server (multi-device dedup).
|
||||||
|
4. **Steady state** — `status_update`, `voice_state`, profile-bearing `identify` updates, and chat / RTC envelopes flow. The server bumps `lastPong` on every inbound frame.
|
||||||
|
5. **`leave_server` / disconnect** — the server removes the server from `user.serverIds`. `user_left` is broadcast to peers *only* once every connection of the same `oderId` has released the server. The payload's `serverIds` field reports which servers the identity is still in, so clients can distinguish "moved tabs" from "fully left."
|
||||||
|
6. **Dead-connection sweep** — every `PING_INTERVAL_MS = 30 000` the server sweeps; any connection with `lastPong` older than `PONG_TIMEOUT_MS = 45 000` is closed and processed as a disconnect (`server/src/websocket/index.ts`).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Multi-device deduplication
|
||||||
|
|
||||||
|
`broadcastToServer` (`server/src/websocket/broadcast.ts`) deduplicates fan-out by `oderId`, so a user logged in on two devices sees each peer event once.
|
||||||
|
|
||||||
|
`handleJoinServer` (`handler.ts:155`) only emits `user_joined` when the join is a **new identity membership** — i.e. no other connection of the same `oderId` already held the server. Renaming a tab or opening a second window does not produce spurious join notifications.
|
||||||
|
|
||||||
|
Symmetrically, `handleLeaveServer` only emits `user_left` when no other connection of the same `oderId` still holds the server. The `serverIds` field on the payload lets clients see "the identity is still in these other servers" rather than treating a tab close as a full logout.
|
||||||
|
|
||||||
|
`connectionScope` keeps this stable across multi-signal-URL deployments: an identity that opens connections to two signal URLs is still one identity from the broadcast layer's perspective, but the per-scope stale-eviction does not loop.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Status
|
||||||
|
|
||||||
|
Two writers update status:
|
||||||
|
|
||||||
|
- **Manual** — the user picks `online / away / busy / offline` from the UI. The chosen value is sent as a `status_update` envelope and persists locally.
|
||||||
|
- **Automatic** — `UserStatusService` (`toju-app/src/app/core/services/user-status.service.ts`) listens to Electron `powerMonitor` events (suspend, resume, lock, unlock) when running on desktop, or falls back to a 15-minute idle timer in the browser. It emits `status_update` via `RealtimeSessionFacade.sendRawMessage`.
|
||||||
|
|
||||||
|
Manual overrides automatic for the session — explicit user input prevents the idle detector from overwriting `away` back to `online`.
|
||||||
|
|
||||||
|
Server-side, `handleStatusUpdate` (`handler.ts:337`) validates the value against `VALID_STATUSES`, mutates `user.status`, and broadcasts the event to every server the user is in.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Game activity
|
||||||
|
|
||||||
|
`GameActivityService` (`toju-app/src/app/domains/game-activity/application/game-activity.service.ts`) is the renderer-side scanner:
|
||||||
|
|
||||||
|
- Polls every 5–60 seconds (default 10 s).
|
||||||
|
- Asks Electron for active and running process names via the IPC bridge (`getActiveGameCandidate`, `getRunningProcessNames` — see [ipc-bridge](./ipc-bridge.md)).
|
||||||
|
- Resolves candidates to RAWG metadata via `POST /games/match` on the signaling server.
|
||||||
|
- Broadcasts the result to peers as a `game-activity` chat event on the WebRTC chat data channel.
|
||||||
|
|
||||||
|
The signaling server is **not** in the broadcast path for game activity — it only matches process names to RAWG entries. Once a peer connection exists, the game-activity envelope flows P2P.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Business rules and invariants
|
||||||
|
|
||||||
|
- The signaling server **forwards** presence but **never persists** it. Server restart = full reset; clients rederive via `server_users`.
|
||||||
|
- Presence is **per-connection**; identity is reconstructed at broadcast time by collapsing connections that share `oderId`.
|
||||||
|
- `user_joined` is emitted **only** on a new-identity membership; `user_left` **only** on full release of a server by an `oderId`.
|
||||||
|
- `identify` is the canonical channel for profile-metadata updates. Profile-bearing `identify` envelopes rebroadcast `user_joined` only if at least one of `displayName` / `description` / `profileUpdatedAt` actually changed.
|
||||||
|
- **Voice room membership is never server-tracked.** It is client-derived from `voice_state` broadcasts.
|
||||||
|
- Manual status overrides automatic status for the session.
|
||||||
|
- Reconnection resets all presence state; the joiner's first `server_users` snapshot is authoritative for that server.
|
||||||
|
- Dead connections are reaped after 45 s of silence.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Technical implementation
|
||||||
|
|
||||||
|
### Server
|
||||||
|
- WebSocket envelope handlers — `server/src/websocket/handler.ts`: `handleStatusUpdate` (line 337), `handleIdentify` (112), `handleJoinServer` (155), `handleLeaveServer` (224).
|
||||||
|
- Broadcast / dedup — `server/src/websocket/broadcast.ts`: `broadcastToServer`, `sendServerUsers`.
|
||||||
|
- Sweep / heartbeat — `server/src/websocket/index.ts` (`PING_INTERVAL_MS`, `PONG_TIMEOUT_MS`).
|
||||||
|
- `ConnectedUser` row — `server/src/websocket/types.ts`.
|
||||||
|
- Game-match HTTP — `server/src/routes/games.ts`, `server/src/services/game-matching.service.ts`.
|
||||||
|
|
||||||
|
### Product client
|
||||||
|
- Status writer — `toju-app/src/app/core/services/user-status.service.ts`.
|
||||||
|
- Game-activity scanner — `toju-app/src/app/domains/game-activity/application/game-activity.service.ts`.
|
||||||
|
- Voice presence — `toju-app/src/app/domains/voice-session/` (see [voice-signaling](./voice-signaling.md)).
|
||||||
|
- Presence sync into NgRx — `toju-app/src/app/store/rooms/room-state-sync.effects.ts`, `room-members-sync.effects.ts`.
|
||||||
|
- Presence reducers — `toju-app/src/app/store/users/`.
|
||||||
|
|
||||||
|
### Electron
|
||||||
|
- Process inspection IPC — `electron/preload.ts` (`getActiveGameCandidate`, `getRunningProcessNames`). See [ipc-bridge](./ipc-bridge.md).
|
||||||
|
- `powerMonitor` events — wired in `electron/` and surfaced to renderer via IPC events.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
- `server/src/websocket/handler-status.spec.ts` — status validation and broadcast.
|
||||||
|
- `toju-app/src/app/store/users/users-status.reducer.spec.ts` — status reducer.
|
||||||
|
- `toju-app/src/app/store/rooms/rooms-helpers-status.spec.ts` — room-level status aggregation.
|
||||||
|
- `toju-app/src/app/domains/game-activity/application/game-activity.service.spec.ts` — scanner + RAWG match.
|
||||||
|
- `toju-app/src/app/infrastructure/realtime/signaling/signaling-message-handler.spec.ts` — presence-relevant handling.
|
||||||
|
- TODO: no spec for multi-device `user_left` suppression.
|
||||||
|
- TODO: no spec for `identify`-triggered profile rebroadcast.
|
||||||
|
- TODO: no spec for pong-timeout reaping.
|
||||||
|
- TODO: no spec for client `offline → disconnected` rendering mapping.
|
||||||
|
- TODO: no E2E for cross-device presence dedup.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Security considerations
|
||||||
|
|
||||||
|
- The `identify` claim is **not verified** — see [authentication](./authentication.md). Presence trust is inherited from that gap: a connection can claim any `oderId` and be broadcast as that user.
|
||||||
|
- Game-activity scanning surfaces local process names to the signaling server (via `/games/match`) and to peers (via the data channel). This is privacy-sensitive — there is no per-user opt-out documented today; if a user does not want process names leaving their machine, they need a `closeToTraySetting`-style toggle. TODO: confirm the current opt-out path.
|
||||||
|
- Status is self-asserted. `busy` does not enforce anything; it is purely a presence hint.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Performance considerations
|
||||||
|
|
||||||
|
- `broadcastToServer` is O(N) per envelope, where N is the number of connections subscribed to the server. There is no fan-out batching.
|
||||||
|
- The 30 s ping cadence keeps idle connections cheap; the 45 s reaper keeps `connectedUsers` from leaking on TCP half-closes.
|
||||||
|
- `GameActivityService` defaults to a 10 s poll; user-configurable, clamped 5–60 s.
|
||||||
|
- `identify` rebroadcast is O(serversJoinedByThisConnection); negligible in practice.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Known issues and limitations
|
||||||
|
|
||||||
|
- No server-side voice-room membership model means the only way to enumerate a room's occupants is to replay `voice_state` events client-side.
|
||||||
|
- Status idle detection in the browser falls back to a coarse 15-minute timer (no platform idle API).
|
||||||
|
- Game-activity opt-out and granularity (per-game blocklist) are not centrally documented; the `gameIgnoreList` setting lives in `electron/desktop-settings.ts` but is undocumented in renderer UX terms — TODO.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related features
|
||||||
|
|
||||||
|
- **[websocket-envelopes](./websocket-envelopes.md)** — owns the wire shape of every envelope this area uses.
|
||||||
|
- **[voice-signaling](./voice-signaling.md)** — consumes the `voice_state` broadcasts to drive RTC mesh.
|
||||||
|
- **[authentication](./authentication.md)** — owns the `identify` handshake and the heartbeat / reaping policy.
|
||||||
|
- **[access-control](./access-control.md)** — gates `join_server`, which precedes any presence broadcast for that server.
|
||||||
|
- **[ipc-bridge](./ipc-bridge.md)** — exposes `powerMonitor` events and process-list inspection used by status and game-activity.
|
||||||
|
|
||||||
|
## Changelog
|
||||||
|
|
||||||
|
| Date | Change |
|
||||||
|
|------|--------|
|
||||||
|
| 2026-05-25 | Initial documentation |
|
||||||
174
agents-docs/features/server-directory.md
Normal file
174
agents-docs/features/server-directory.md
Normal file
@@ -0,0 +1,174 @@
|
|||||||
|
# Server Directory
|
||||||
|
|
||||||
|
> **Area:** server-directory
|
||||||
|
> **Status:** Active
|
||||||
|
> **Last updated:** 2026-05-25
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
The Server Directory is the public REST surface that lists joinable Toju chat servers, manages invites and join requests, gates membership (passwords, bans, ownership), and exposes moderation actions (kick / ban / unban). It is the only feature where the signaling server holds non-ephemeral, multi-user state: the persistent catalog of servers, their access rules, their memberships, and their pending join requests. The renderer's `server-directory` domain consumes this surface to render the "find a server" experience and to drive the join flow that eventually opens a WebSocket (see [websocket-envelopes](./websocket-envelopes.md)).
|
||||||
|
|
||||||
|
## Responsibilities
|
||||||
|
|
||||||
|
- Persist the catalog of servers, their access policy (public/private, password, max users), and ownership.
|
||||||
|
- Mint invites and accept invite redemptions.
|
||||||
|
- Track join requests on private servers and route owner decisions back to the requester.
|
||||||
|
- Track memberships and bans; enforce them on join attempts.
|
||||||
|
- Provide moderation primitives: kick, ban, unban — gated by role/owner permissions.
|
||||||
|
- Emit user-targeted notifications when a join request changes state.
|
||||||
|
|
||||||
|
This area does **not** own:
|
||||||
|
|
||||||
|
- Realtime presence, chat, or voice — those flow over the WebSocket once a user has joined (see [websocket-envelopes](./websocket-envelopes.md), [voice-signaling](./voice-signaling.md)).
|
||||||
|
- Per-channel permissions logic (lives in `server/src/services/server-permissions.service.ts` and is consumed by this area, but is reused beyond it).
|
||||||
|
|
||||||
|
## Key concepts
|
||||||
|
|
||||||
|
- **Server** — a joinable chat server. Persisted as `ServerEntity` (`servers` table).
|
||||||
|
- **Public / private** — `isPrivate` flag. Public servers appear in directory listings; private servers do not.
|
||||||
|
- **Invite** — an opaque token (`ServerInviteEntity`) that grants short-lived access to a specific server. Expires after `SERVER_INVITE_EXPIRY_MS` (10 days).
|
||||||
|
- **Join request** — a pending request on a private server (`JoinRequestEntity`), `pending → approved | denied`.
|
||||||
|
- **Membership** — a `ServerMembershipEntity` row, indexed by `serverId` + `userId`.
|
||||||
|
- **Ban** — a `ServerBanEntity` row, optionally `expiresAt`. Auto-pruned on the next join attempt for the banned user.
|
||||||
|
- **Heartbeat** — periodic `POST /:id/heartbeat` from the server owner's client that updates `lastSeen` and `currentUsers` on the directory entry.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## API Endpoints
|
||||||
|
|
||||||
|
All HTTP routes; no auth header — caller identity is supplied per-request in the body (`ownerId`, `actorUserId`, `userId`, `requesterUserId`). Identity is whatever the client claims; authorization is enforced against persisted state. Request body validation is **manual / defensive** (no zod or class-validator).
|
||||||
|
|
||||||
|
### `server/src/routes/servers.ts`
|
||||||
|
|
||||||
|
| Method | Path | Purpose | Auth |
|
||||||
|
|--------|------|---------|------|
|
||||||
|
| `GET` | `/` | List public servers. Query: `q`, `tags`, `limit`, `offset`. | None |
|
||||||
|
| `POST` | `/` | Create a server. Required body: `name`, `ownerId`, `ownerPublicKey`. | Self-asserted |
|
||||||
|
| `GET` | `/:id` | Fetch a single server. 404 if missing. | None |
|
||||||
|
| `PUT` | `/:id` | Update a server. Required body: `currentOwnerId`. Permission check via `canManageServerUpdate`. | Owner / role |
|
||||||
|
| `POST` | `/:id/join` | Join a server. Required body: `userId`. Optional: `password`, `inviteId`. Returns `signalingUrl`. | Self-asserted + access rules |
|
||||||
|
| `POST` | `/:id/invites` | Create an invite. Required body: `requesterUserId`. Delegates to `createServerInvite`. | Role permission |
|
||||||
|
| `POST` | `/:id/moderation/kick` | Kick a user. Required: `actorUserId`, `targetUserId`. Permission: `canModerateServerMember`. | Role permission |
|
||||||
|
| `POST` | `/:id/moderation/ban` | Ban a user. Required: `actorUserId`, `targetUserId`. Optional: `banId`, `reason`, `expiresAt`. | Role permission |
|
||||||
|
| `POST` | `/:id/moderation/unban` | Unban a user. Required: `actorUserId`. Permission: `manageBans`. | Role permission |
|
||||||
|
| `POST` | `/:id/leave` | Leave a server. Required body: `userId`. | Self-asserted |
|
||||||
|
| `POST` | `/:id/heartbeat` | Update `lastSeen` and `currentUsers`. Optional body: `currentUsers`. | None (TODO: confirm) |
|
||||||
|
| `DELETE` | `/:id` | Delete a server. Required body: `ownerId` (must match `server.ownerId`). | Owner |
|
||||||
|
| `GET` | `/:id/requests` | List pending join requests. Query: `ownerId`. | Owner |
|
||||||
|
|
||||||
|
### `server/src/routes/invites.ts`
|
||||||
|
|
||||||
|
- `GET /invites/:id` (API) — fetch invite metadata; `404` for expired or unknown invite.
|
||||||
|
- `GET /invites/:id` (page router) — server-rendered HTML preview of the invite (server info, owner, expiry); renders an offline state when the server is unreachable.
|
||||||
|
|
||||||
|
### `server/src/routes/join-requests.ts`
|
||||||
|
|
||||||
|
- `PUT /requests/:id` — update join-request status. Body: `ownerId`, `status`. Permission: `manageServer`. On success, calls `notifyUser` (WebSocket fan-out, see below).
|
||||||
|
|
||||||
|
### Standard error codes
|
||||||
|
|
||||||
|
`SERVER_NOT_FOUND`, `MISSING_USER`, `NOT_AUTHORIZED`, `BANNED`, `PASSWORD_REQUIRED`, `INVITE_EXPIRED`, plus 400 for missing required fields.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## CQRS handlers
|
||||||
|
|
||||||
|
`server/src/cqrs/` backs every mutation; routes are thin adapters around CQRS dispatch.
|
||||||
|
|
||||||
|
**Queries** (`server/src/cqrs/queries/handlers/`):
|
||||||
|
|
||||||
|
- `getAllPublicServers` — filtered by `isPrivate = 0`, loads relations.
|
||||||
|
- `getServerById`
|
||||||
|
- `getJoinRequestById`
|
||||||
|
- `getPendingRequestsForServer`
|
||||||
|
|
||||||
|
**Commands** (`server/src/cqrs/commands/handlers/`):
|
||||||
|
|
||||||
|
- `upsertServer` — also calls `replaceServerRelations` to sync `tags`, `channels`, `roles`, `roleAssignments`, `channelPermissions` atomically.
|
||||||
|
- `deleteServer`
|
||||||
|
- `createJoinRequest`
|
||||||
|
- `updateJoinRequestStatus` — emits a `notifyUser` event so the requesting user's client learns the outcome over WebSocket.
|
||||||
|
|
||||||
|
All handlers run inside TypeORM transactions where multi-table changes are involved.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Persistence
|
||||||
|
|
||||||
|
### Entities (`server/src/entities/`)
|
||||||
|
|
||||||
|
- `ServerEntity` (table `servers`) — `id`, `name`, `description`, `ownerId`, `ownerPublicKey`, `passwordHash`, `isPrivate`, `maxUsers`, `currentUsers`, `icon`, `iconUpdatedAt`, `slowModeInterval`, `createdAt`, `lastSeen`.
|
||||||
|
- `ServerInviteEntity` (`server_invites`) — `id`, `serverId` (indexed), `createdBy`, `createdByDisplayName`, `createdAt`, `expiresAt` (indexed).
|
||||||
|
- `JoinRequestEntity` (`join_requests`) — `id`, `serverId` (indexed), `userId`, `userPublicKey`, `displayName`, `status` (default `pending`), `createdAt`.
|
||||||
|
- `ServerMembershipEntity` (`server_memberships`) — `id`, `serverId` (indexed), `userId` (indexed), `joinedAt`, `lastAccessAt`.
|
||||||
|
- `ServerBanEntity` (`server_bans`) — `id`, `serverId` (indexed), `userId` (indexed), `bannedBy`, `displayName`, `reason`, `expiresAt` (nullable), `createdAt`.
|
||||||
|
|
||||||
|
Related (referenced by `replaceServerRelations`): `ServerChannelEntity`, `ServerRoleEntity`, `ServerUserRoleEntity`, `ServerTagEntity`, `ServerChannelPermissionEntity`.
|
||||||
|
|
||||||
|
### Migrations (`server/src/migrations/`)
|
||||||
|
|
||||||
|
- `1000000000000-InitialSchema.ts` — `servers`, `users`.
|
||||||
|
- `1000000000001-ServerAccessControl.ts` — adds `passwordHash` to `servers`; creates `server_memberships`, `server_invites`, `server_bans` with indices.
|
||||||
|
- `1000000000002-ServerChannels.ts` — `server_channels`.
|
||||||
|
- `1000000000005-ServerRoleAccessControl.ts` — role/permission tables.
|
||||||
|
- TODO: locate the migration that created `join_requests` (not obvious from filenames; likely folded into an earlier migration).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Renderer side
|
||||||
|
|
||||||
|
`toju-app/src/app/domains/server-directory/`:
|
||||||
|
|
||||||
|
- **API client**: `infrastructure/services/server-directory-api.service.ts` — `ServerDirectoryApiService` exposes `searchServers`, `getServers`, `getServer`, `findServerAcrossActiveEndpoints`, `registerServer`, `updateServer`, `requestJoin`, `createInvite`, `getInvite`, `kickServerMember`, `banServerMember`, `unbanServerMember`, `notifyLeave`, `sendHeartbeat`. Defensive coercion (`getNumberValue` / `getStringValue` / `getBooleanValue`) is used instead of schema validation.
|
||||||
|
- **State**: signal-based via `ServerEndpointStateService` (servers, active server) — not NgRx for this slice.
|
||||||
|
- **Facade**: `application/services/server-directory.service.ts` plus `application/facades/`.
|
||||||
|
- **Multi-endpoint awareness**: Toju supports several federated signaling endpoints; `findServerAcrossActiveEndpoints` queries each and merges results.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Business rules
|
||||||
|
|
||||||
|
- **Public-only listing**: `GET /` only returns servers with `isPrivate = 0`. Private servers must be reached by ID + invite.
|
||||||
|
- **Owner immutability**: only `currentOwnerId` matching `server.ownerId` may update; only `ownerId` matching `server.ownerId` may delete.
|
||||||
|
- **Join order of checks** (on `POST /:id/join`): existence → ban check (auto-prune expired bans) → password check (if `passwordHash`) → invite check (if private and no invite) → membership upsert → return `signalingUrl`.
|
||||||
|
- **Invite expiry**: 10 days (`SERVER_INVITE_EXPIRY_MS = 10 * 24 * 60 * 60 * 1000`). Expired invites are pruned on access via `pruneExpiredServerAccessArtifacts()`.
|
||||||
|
- **Ban expiry**: optional `expiresAt`; auto-deleted on next join attempt for that user.
|
||||||
|
- **Join request notifications**: on `PUT /requests/:id`, after CQRS dispatch, `notifyUser` pushes the new status over WebSocket to any open connection for `userPublicKey` / `userId`.
|
||||||
|
|
||||||
|
## Security considerations
|
||||||
|
|
||||||
|
- **No authentication header.** All identity is self-asserted in the request body. Authorization is enforced by checking the claimed identity against persisted role/owner state.
|
||||||
|
- **Password storage**: `passwordHash` only; never the cleartext. TODO: confirm the hashing algorithm (likely bcrypt / scrypt — verify in `server/src/services/`).
|
||||||
|
- **SSRF**: routes in this area do not fetch user-supplied URLs, so the SSRF guard does not apply here (it applies to link-metadata, klipy, proxy).
|
||||||
|
- **No rate limiting** on directory or moderation routes — TODO: add brute-force protection on `POST /:id/join` for password attempts.
|
||||||
|
- **No CSRF** (REST + JSON body, no cookies in scope), but spam protection on `POST /` (server creation) is also TODO.
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
- `SERVER_INVITE_EXPIRY_MS` — currently hardcoded at 10 days. Not exposed via `data/variables.json`.
|
||||||
|
- Per-server `maxUsers`, `slowModeInterval`, `isPrivate`, `passwordHash` are operator-configurable via `PUT /:id`.
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
- **Server-side**: no direct route specs for `servers.ts`, `invites.ts`, `join-requests.ts`. WebSocket-side handlers (`handler-status.spec.ts`, `handler-plugin.spec.ts`) cover adjacent concerns.
|
||||||
|
- **Renderer-side**: `application/services/server-endpoint-state.service.spec.ts`.
|
||||||
|
- **E2E**: TODO — verify whether the Playwright suite covers join / invite / moderation end-to-end.
|
||||||
|
- **Gap**: routes that mutate persistent state and accept self-asserted identity should ideally have integration tests against a real DB.
|
||||||
|
|
||||||
|
## Known issues and limitations
|
||||||
|
|
||||||
|
- **OpenAPI coverage is incomplete.** `server/src/routes/openapi-docs.ts` currently documents plugin-support endpoints only; server-directory endpoints are not listed.
|
||||||
|
- **No structured request validation library.** Inline manual checks are error-prone; consider zod once the team is ready.
|
||||||
|
- **No rate limiting / spam protection** on server creation or join attempts.
|
||||||
|
- **`join_requests` migration is undocumented** (file not located by inspection); confirm during the next schema change.
|
||||||
|
|
||||||
|
## Related features
|
||||||
|
|
||||||
|
- **[websocket-envelopes](./websocket-envelopes.md)** — `join_server` envelope re-uses this area's access rules via `authorizeWebSocketJoin`. `notifyUser` fan-out for join-request decisions is delivered over the same WebSocket.
|
||||||
|
- **[plugin-system](./plugin-system.md)** — `join_server` responses include the joined server's `PluginRequirementsSnapshot`.
|
||||||
|
|
||||||
|
## Changelog
|
||||||
|
|
||||||
|
| Date | Change |
|
||||||
|
|------|--------|
|
||||||
|
| 2026-05-25 | Initial documentation |
|
||||||
@@ -1,79 +0,0 @@
|
|||||||
# Server Discovery
|
|
||||||
|
|
||||||
> **Area:** server-directory
|
|
||||||
> **Status:** Active
|
|
||||||
> **Last updated:** 2025-02-14
|
|
||||||
|
|
||||||
## Overview
|
|
||||||
|
|
||||||
Server discovery lets a signed-in user find public servers to join without knowing an exact name. It spans the signaling **server** (REST routes + CQRS query handlers that rank public servers) and the product **client** (`server-directory` domain API/facade plus the `/dashboard` landing and `/servers` browse page). It complements the existing free-text `GET /api/servers` search with two curated lists — **featured** and **trending**.
|
|
||||||
|
|
||||||
## Responsibilities
|
|
||||||
|
|
||||||
- Server: rank and return public servers as **featured** (most-populated) and **trending** (most-recently-active) lists, capped per request.
|
|
||||||
- Client: fetch those lists through `ServerDirectoryFacade` and render them via the reusable `app-server-browser` component on `/servers` and `/dashboard`.
|
|
||||||
- It does NOT own: free-text search (`GET /api/servers`), join/access checks (`/api/servers/:id/join`), invites, or room signal-affinity. Discovery is read-only browsing; joining flows through existing paths.
|
|
||||||
|
|
||||||
## Key concepts
|
|
||||||
|
|
||||||
- **Featured**: public servers ranked by membership count descending, ties broken by most recent `lastSeen` (`rankFeaturedServers`).
|
|
||||||
- **Trending**: public servers ranked by most recent `lastSeen` descending, ties broken by membership count (`rankTrendingServers`).
|
|
||||||
- **Discovery limit**: each route clamps `limit` to `[1, 50]` (`parseDiscoveryLimit`), default `12`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## API Endpoints
|
|
||||||
|
|
||||||
Both endpoints live in `server/src/routes/servers.ts` and **must be registered before** the parameterised `/:id` route, otherwise Express resolves `featured`/`trending` as a server id.
|
|
||||||
|
|
||||||
### `GET /api/servers/featured`
|
|
||||||
|
|
||||||
- **Method**: GET
|
|
||||||
- **Authentication**: None (public discovery)
|
|
||||||
- **Rate Limiting**: No
|
|
||||||
- **Query params**: `limit` (optional integer; clamped to `[1, 50]`, default `12`)
|
|
||||||
|
|
||||||
### `GET /api/servers/trending`
|
|
||||||
|
|
||||||
- **Method**: GET
|
|
||||||
- **Authentication**: None (public discovery)
|
|
||||||
- **Rate Limiting**: No
|
|
||||||
- **Query params**: `limit` (optional integer; clamped to `[1, 50]`, default `12`)
|
|
||||||
|
|
||||||
### Response Schema (both)
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"servers": "ServerInfo[] — enriched public servers (icon, channels, sourceId/sourceName/sourceUrl filled by the client API layer)",
|
|
||||||
"total": "number — count of servers returned",
|
|
||||||
"limit": "number — the effective clamped limit"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
`ServerInfo` matches the shape returned by `GET /api/servers` search results, so the client normalises and renders all three lists identically.
|
|
||||||
|
|
||||||
### Error Responses
|
|
||||||
|
|
||||||
- **500 Internal Server Error**: query handler / persistence failure.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Server internals
|
|
||||||
|
|
||||||
- Routes delegate to CQRS query handlers `handleGetFeaturedServers` / `handleGetTrendingServers` (`server/src/cqrs/queries/handlers/`), dispatched via `GetFeaturedServers` / `GetTrendingServers` query types.
|
|
||||||
- Ranking lives in `server/src/cqrs/queries/handlers/server-ranking.util.ts` (`rankFeaturedServers`, `rankTrendingServers`, `loadMembershipCounts`). Membership counts load in a single grouped query.
|
|
||||||
- Results pass through the same `enrichServer()` step as search before serialisation.
|
|
||||||
|
|
||||||
## Client internals
|
|
||||||
|
|
||||||
- `ServerDirectoryApiService.getFeaturedServers()` / `getTrendingServers()` call the routes through a shared private `getDiscoveryServers(path)` helper and normalise into `ServerInfo[]`.
|
|
||||||
- `ServerDirectoryService` → `ServerDirectoryFacade` expose `getFeaturedServers()` / `getTrendingServers()` as the domain boundary.
|
|
||||||
- `FindServersComponent` (`/servers`) composes **Recently active** (the user's saved rooms, capped at 6), **Featured**, and **Trending** sections, all rendered through `app-server-browser` with `[showMyServers]="true"`.
|
|
||||||
- `DashboardComponent` (`/dashboard`) is a single-column landing page (max-width centered, no in-page sidebars): a header greeting (no emoji), a global search with `Ctrl+K` focus and localStorage-backed **Recent Searches** chips shown beneath it, three primary action cards (Find People → `/people`, Find Servers → `/servers`, Create Server → `/create-server` — one link each), and discovery panels **People you might know**, **Popular Servers**, **Your Friends**, and **Recently Active Servers**. Each list is capped at 5 (`DISCOVERY_LIMIT`). It loads `popularServers` on init from `getFeaturedServers(5)`, falling back to `getTrendingServers(5)` when featured is empty; reuses `app-friend-button` for Add and `app-user-avatar` for people rows. `peopleYouMightKnow` excludes existing friends (via `FriendService.friendIds()`); `friends` lists discovered people who are friends. "See all" header links route to the matching `/people` or `/servers` page (no duplicated footer links). Recent searches are recorded on Enter (deduped, most-recent-first, capped at 8) and persisted under `metoyou_dashboard_recent_searches`.
|
|
||||||
- The servers-rail top button (`servers-rail.component`) is the **Dashboard** button (`lucideLayoutDashboard`, `title="Dashboard"`); its `goToDashboard()` handler deselects any active voice server and navigates to `/dashboard`. A **Create a server** button (`lucidePlus`, `data-testid="server-rail-create"`) sits below the saved-server icons and opens `app-create-server-dialog` (a Toju modal on desktop / bottom sheet on mobile) which dispatches `RoomsActions.createRoom` directly; the dashboard / `/create-server` route remains as an alternative entry point. Rail icons (`h-12 w-12`, `md:h-11 w-11`) animate their corner radius on hover and `:active` for a Discord-style squircle effect.
|
|
||||||
- On mobile (`ViewportService.isMobile()`), `DashboardComponent`, `FindPeopleComponent` (`/people`), and `FindServersComponent` (`/servers`) each mount their page body inside a single `<swiper-container>` slide next to `app-servers-rail` (rail `shrink-0`, content `flex-1` with a left border), mirroring the chat-room / DM-workspace mobile layout so the primary navigation rail stays reachable. The page body is shared between the desktop and mobile branches via an `<ng-template #pageContent>` + `[ngTemplateOutlet]`, and each component declares `schemas: [CUSTOM_ELEMENTS_SCHEMA]` for the Swiper custom elements.
|
|
||||||
|
|
||||||
## Related
|
|
||||||
|
|
||||||
- Product-client domain README: `toju-app/src/app/domains/server-directory/README.md`
|
|
||||||
- People discovery (`/people`): `toju-app/src/app/domains/direct-message/README.md`
|
|
||||||
@@ -1,22 +0,0 @@
|
|||||||
# Signal Server Tag
|
|
||||||
|
|
||||||
Users registered on a signal server can show that server's display tag on their profile card (opened by clicking their name or avatar).
|
|
||||||
|
|
||||||
## Server configuration
|
|
||||||
|
|
||||||
`server/data/variables.json` accepts an optional `serverTag` string. When omitted, the server falls back to its public URL built from `serverProtocol`, `serverHost`, and `serverPort`.
|
|
||||||
|
|
||||||
## Health API
|
|
||||||
|
|
||||||
`GET /api/health` includes `serverTag` so clients can cache the display label per configured endpoint.
|
|
||||||
|
|
||||||
## WebSocket presence
|
|
||||||
|
|
||||||
The client sends `homeSignalServerUrl` in `identify` messages. The signaling server echoes that value in `server_users` and `user_joined` payloads so other clients can resolve the correct tag.
|
|
||||||
|
|
||||||
## Client behavior
|
|
||||||
|
|
||||||
- Login and registration store `homeSignalServerUrl` on the current user.
|
|
||||||
- Profile cards show the resolved tag beside the username in muted text.
|
|
||||||
- Configured labels render as `#tag`; URL fallbacks render as a globe icon with the URL in a tooltip.
|
|
||||||
- Tag resolution prefers the endpoint's cached `serverTag` from health checks, then falls back to the stored home URL.
|
|
||||||
177
agents-docs/features/voice-signaling.md
Normal file
177
agents-docs/features/voice-signaling.md
Normal file
@@ -0,0 +1,177 @@
|
|||||||
|
# Voice & WebRTC Signaling
|
||||||
|
|
||||||
|
> **Area:** voice-signaling
|
||||||
|
> **Status:** Active
|
||||||
|
> **Last updated:** 2026-05-25
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Voice and screen-share in Toju are pure WebRTC mesh: peers establish RTCPeerConnections directly, while the signaling server only forwards SDP and ICE messages. This area covers the end-to-end flow — envelope routing, peer election, RTCPeerConnection lifecycle, RNNoise denoising, and the relationships between the three product-client domains involved: `voice-session`, `voice-connection`, and `direct-call`. Screen-share rides on the same peer connection; its UI orchestration is its own domain but the signaling path is shared.
|
||||||
|
|
||||||
|
## Responsibilities
|
||||||
|
|
||||||
|
- Negotiate WebRTC sessions between peers using `offer` / `answer` / `ice_candidate` envelopes forwarded by the signaling server.
|
||||||
|
- Elect an initiator deterministically when multiple peers arrive simultaneously, with a non-initiator fallback timer.
|
||||||
|
- Maintain the local audio pipeline: mic capture → optional RNNoise denoising → RTCPeerConnection sender.
|
||||||
|
- Track per-peer playback gain, mute, deafen, and speaking-activity state on the receive side.
|
||||||
|
- Mirror voice presence (`voice_state`) and direct-call signalling (`direct-call`) to other peers via the WebSocket.
|
||||||
|
|
||||||
|
This area does **not** own:
|
||||||
|
|
||||||
|
- The WebSocket envelope shape (see [websocket-envelopes](./websocket-envelopes.md)).
|
||||||
|
- Screen-share UI orchestration (its own domain at `toju-app/src/app/domains/screen-share/`); only the peer connection plumbing is shared.
|
||||||
|
- Persistent user settings beyond `voiceSettingsStorage` (audio device IDs, volumes, bitrate, latency profile, noise-reduction toggle, persisted to localStorage).
|
||||||
|
|
||||||
|
## Key concepts
|
||||||
|
|
||||||
|
- **Mesh** — every participant holds an `RTCPeerConnection` per other participant. No SFU / MCU.
|
||||||
|
- **Voice session** — high-level "user is currently in voice room X" state. Owned by `voice-session` domain.
|
||||||
|
- **Voice connection** — low-level transport/peer concerns: speaking detection, per-peer gain, mute / deafen state. Owned by `voice-connection` domain.
|
||||||
|
- **Direct call** — 1:1 voice/video call with an optional group-upgrade path. Owned by `direct-call` domain.
|
||||||
|
- **Initiator** — the peer responsible for sending the first `offer`. Elected first-peer-wins; non-initiators wait `NON_INITIATOR_GIVE_UP_MS` (≈5 s) before generating their own offer.
|
||||||
|
- **Data channel** — `chat`-labelled data channel established alongside each peer connection for P2P chat fallback and direct-message delivery.
|
||||||
|
- **Noise suppressor worklet** — RNNoise WASM running in an `AudioWorkletNode` (`NoiseSuppressorWorklet`), loaded from `rnnoise-worklet.js` at the app root.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Signaling envelopes (consumed)
|
||||||
|
|
||||||
|
Defined in [websocket-envelopes](./websocket-envelopes.md). Voice-relevant types:
|
||||||
|
|
||||||
|
- `offer`, `answer`, `ice_candidate` — forwarded by the server to `targetUserId` without inspection.
|
||||||
|
- `direct-call` — forwarded; payload carries call-scoped events (ring, participant join/leave, call end).
|
||||||
|
- `voice_state` — broadcast to a server. Payload includes `roomId`, `voiceGateway`, mute/deafen flags.
|
||||||
|
- `server_users` — full peer roster on join; seeds the initial offer fan-out.
|
||||||
|
- `user_joined` — schedules a fallback offer after a grace delay (`USER_JOINED_FALLBACK_OFFER_DELAY_MS`, ≈1 s).
|
||||||
|
- `user_left` — peer teardown, with special handling that preserves peers still under an active voice session.
|
||||||
|
- `connected` / `access_denied` — connection lifecycle (server bootstrap and authorization).
|
||||||
|
|
||||||
|
The server is **purely signaling**: it does not track which `oderId` is in which voice room. Voice membership is derived client-side from the `voice_state` broadcasts observed on the server.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Session establishment flow
|
||||||
|
|
||||||
|
A new participant joining a voice room produces this exchange (initiator perspective; symmetrical when both arrive at once):
|
||||||
|
|
||||||
|
1. Local user clicks "Join voice" → `VoiceSessionFacade.startSession()` populates the session model and asks `voice-connection` to ready peer transport.
|
||||||
|
2. Server broadcasts `user_joined` to existing peers.
|
||||||
|
3. Each existing peer evaluates: am I the elected initiator for the (me, new-peer) pair? If yes, the peer-connection manager calls `doCreateAndSendOffer()`.
|
||||||
|
4. Initiator constructs `new RTCPeerConnection({ iceServers })` (`infrastructure/realtime/peer-connection-manager/.../create-peer-connection.ts`), adds local tracks, creates the data channel `chat`, generates an SDP offer, and sends it via the signaling transport.
|
||||||
|
5. Responder receives `offer` → `doHandleOffer()` sets remote description, generates SDP answer, sends `answer`.
|
||||||
|
6. Initiator receives `answer` → `doHandleAnswer()` sets remote description.
|
||||||
|
7. Both sides emit `ice_candidate` as they gather candidates via `onicecandidate`.
|
||||||
|
8. `iceConnectionState` reaches `connected` / `completed` → media flows.
|
||||||
|
9. Either side may open the `chat` data channel for P2P text payloads (direct messages, etc.).
|
||||||
|
|
||||||
|
If the elected initiator never sends an offer within `NON_INITIATOR_GIVE_UP_MS`, the non-initiator promotes itself and initiates instead — preserves liveness across asymmetric drop-outs.
|
||||||
|
|
||||||
|
`user_left` is treated carefully: the `signaling-message-handler.spec.ts` covers the case where a peer is still required by an active voice session and must not be torn down, even if other parts of the system think the peer has disconnected.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Domain responsibilities
|
||||||
|
|
||||||
|
### `voice-session` (`toju-app/src/app/domains/voice-session/`)
|
||||||
|
|
||||||
|
- `VoiceSessionFacade` (`application/facades/voice-session.facade.ts`) — owns the active session metadata (`serverId`, `roomId`, `participantIds`); drives a `showFloatingControls` signal when the user navigates away from the room.
|
||||||
|
- `VoiceWorkspaceService` (`application/services/voice-workspace.service.ts`) — UI state for the workspace (hidden / expanded / minimized), focused stream ID, mini-window position.
|
||||||
|
- `voiceSettingsStorage` (`infrastructure/util/voice-settings-storage.util.ts`) — localStorage persistence: input/output device IDs, output volume (0–100), bitrate (32–256 kbps), latency profile (`low | balanced | high`), noise-reduction toggle.
|
||||||
|
- Joining a new voice target first calls `endSession()` so transitions cannot leak peer connections.
|
||||||
|
|
||||||
|
### `voice-connection` (`toju-app/src/app/domains/voice-connection/`)
|
||||||
|
|
||||||
|
Bridges the application layer to the low-level WebRTC infrastructure under `toju-app/src/app/infrastructure/realtime/`.
|
||||||
|
|
||||||
|
- **`VoiceActivityService`** — RMS-based speaking detection via `AnalyserNode` (fftSize 256, RMS ≥ 0.015, 8-frame grace period).
|
||||||
|
- **`VoicePlaybackService`** — per-peer `GainNode` chains (0–200% range), localStorage-persisted; deafen sets all gains to 0.
|
||||||
|
- **`VoiceConnectionFacade`** — exposes signals like `isVoiceConnected`, `isMuted`; methods like `toggleMute()`, `toggleNoiseReduction()`, `setOutputVolume()`.
|
||||||
|
|
||||||
|
Per the domain README, voice-connection does **not** own RTCPeerConnection construction or signaling — those live in `infrastructure/realtime/peer-connection-manager`.
|
||||||
|
|
||||||
|
### `direct-call` (`toju-app/src/app/domains/direct-call/`)
|
||||||
|
|
||||||
|
- Initiator flow (`DirectCallService.startCall()`): create/reuse the 1:1 DM, start a call-scoped voice session, send a `direct-call` "ring" envelope via `PeerDeliveryService`.
|
||||||
|
- Recipient flow: store incoming session, ring `assets/audio/call.wav` (unless DND), show in-app modal + desktop notification.
|
||||||
|
- Group upgrade: adding a third participant spawns a new group conversation; the active call swaps its chat panel to the new conversation but original DM history is preserved.
|
||||||
|
- Invariant: incoming `direct-call` events are ignored unless the local user is in `participantIds`.
|
||||||
|
|
||||||
|
### Screen share (`toju-app/src/app/domains/screen-share/`)
|
||||||
|
|
||||||
|
- Adds dedicated `MediaStreamTrack` senders to the existing peer connection (does not open a new one).
|
||||||
|
- Request / response model: a receiver sends `screen-share-request`; the sender attaches the share track; `screen-share-stop` tears it down.
|
||||||
|
- Quality presets: `low` / `balanced` / `high` (resolution + FPS).
|
||||||
|
- On Electron, `ScreenShareSourcePickerService` drives a Promise-based picker over `getSources` (see [ipc-bridge](./ipc-bridge.md)).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## RNNoise pipeline
|
||||||
|
|
||||||
|
Manager: `infrastructure/realtime/media/noise-reduction.manager.ts`.
|
||||||
|
|
||||||
|
```
|
||||||
|
Raw mic → MediaStreamAudioSourceNode → NoiseSuppressorWorklet (AudioWorkletNode) → MediaStreamAudioDestinationNode → clean stream → RTCPeerConnection sender
|
||||||
|
```
|
||||||
|
|
||||||
|
- AudioContext at 48 kHz.
|
||||||
|
- Worklet loaded from `rnnoise-worklet.js` (built from `@timephy/rnnoise-wasm`, output written to `toju-app/public/`).
|
||||||
|
- If worklet load fails, the raw stream is passed through unchanged.
|
||||||
|
- Mute takes priority — when muted, noise reduction is also disabled.
|
||||||
|
|
||||||
|
## Technical implementation
|
||||||
|
|
||||||
|
- **Envelope types**: see [websocket-envelopes](./websocket-envelopes.md).
|
||||||
|
- **Signaling adapter (renderer)**: `toju-app/src/app/infrastructure/realtime/signaling/signaling-message-handler.ts` (and `signaling-transport-handler.ts`).
|
||||||
|
- **Peer-connection manager**: `toju-app/src/app/infrastructure/realtime/peer-connection-manager/` — `create-peer-connection.ts`, recovery (grace timers, reconnect), data-channel plumbing.
|
||||||
|
- **Voice settings**: `domains/voice-session/infrastructure/util/voice-settings-storage.util.ts`.
|
||||||
|
- **Noise reduction**: `infrastructure/realtime/media/noise-reduction.manager.ts`.
|
||||||
|
- **Worklet asset**: `toju-app/public/rnnoise-worklet.js`.
|
||||||
|
- **Server side**: signaling only — `server/src/websocket/handler.ts::forwardRtcMessage`.
|
||||||
|
|
||||||
|
## Invariants
|
||||||
|
|
||||||
|
- The server forwards `offer` / `answer` / `ice_candidate` / `direct-call` envelopes opaquely and never persists media or call state.
|
||||||
|
- Switching voice rooms always tears down the prior session before starting the new one.
|
||||||
|
- Mute overrides noise reduction (the manager disables the worklet path when muted).
|
||||||
|
- Direct-call events with the local user absent from `participantIds` are ignored.
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
- `toju-app/src/app/infrastructure/realtime/signaling/signaling-message-handler.spec.ts` — `user_left` peer preservation under active voice.
|
||||||
|
- `toju-app/src/app/infrastructure/realtime/peer-connection-manager/recovery/peer-recovery.spec.ts` — reconnect, grace timers, exponential backoff.
|
||||||
|
- `toju-app/src/app/infrastructure/realtime/peer-connection-manager/messaging/data-channel.spec.ts`.
|
||||||
|
- `toju-app/src/app/domains/direct-call/application/services/direct-call.service.spec.ts`.
|
||||||
|
- E2E: `e2e/tests/voice/multi-signal-eight-user-voice.spec.ts`, `e2e/tests/voice/direct-call.spec.ts` (verify exact filenames in the suite — TODO).
|
||||||
|
|
||||||
|
## Security considerations
|
||||||
|
|
||||||
|
- WebRTC bypasses the server entirely once connected — peer IPs may be exposed to other participants via ICE candidates. Standard WebRTC privacy caveat.
|
||||||
|
- Signaling envelopes are forwarded without verifying that source and target share a server — TODO: confirm whether `forwardRtcMessage` enforces membership.
|
||||||
|
- The data channel `chat` carries P2P text payloads; integrity / authentication of those payloads is owned by the chat/direct-message domains, not by this area.
|
||||||
|
- RNNoise runs entirely client-side; mic audio never leaves the local AudioContext until it enters the encrypted RTCPeerConnection.
|
||||||
|
|
||||||
|
## Performance considerations
|
||||||
|
|
||||||
|
- Mesh topology — N×(N-1)/2 peer connections per voice room. Practical ceiling is bound by client CPU and uplink; no documented soft cap.
|
||||||
|
- Bitrate is client-controlled (32–256 kbps); no server-enforced QoS.
|
||||||
|
- Voice activity detection runs at fftSize 256 with an 8-frame grace period — chosen to minimise CPU while staying responsive to natural speech.
|
||||||
|
- The signaling server's only cost is envelope forwarding (O(1) per envelope).
|
||||||
|
|
||||||
|
## Known issues and limitations
|
||||||
|
|
||||||
|
- **No SFU / MCU.** Large rooms scale linearly with participant count on each client.
|
||||||
|
- **No recording or server-side mixing** for voice or screen.
|
||||||
|
- **Bitrate is not enforced server-side** — adversarial clients could ignore the suggested range.
|
||||||
|
- **No documented call-quality telemetry pipeline.**
|
||||||
|
|
||||||
|
## Related features
|
||||||
|
|
||||||
|
- **[websocket-envelopes](./websocket-envelopes.md)** — owns the wire types this area consumes.
|
||||||
|
- **[ipc-bridge](./ipc-bridge.md)** — `getSources` and the Linux audio-routing methods are used by screen-share.
|
||||||
|
- **[plugin-system](./plugin-system.md)** — plugins may participate as observers via `voice_state` broadcasts (subject to capability grants); no direct call control surface today.
|
||||||
|
|
||||||
|
## Changelog
|
||||||
|
|
||||||
|
| Date | Change |
|
||||||
|
|------|--------|
|
||||||
|
| 2026-05-25 | Initial documentation |
|
||||||
164
agents-docs/features/websocket-envelopes.md
Normal file
164
agents-docs/features/websocket-envelopes.md
Normal file
@@ -0,0 +1,164 @@
|
|||||||
|
# WebSocket Envelopes
|
||||||
|
|
||||||
|
> **Area:** websocket-envelopes
|
||||||
|
> **Status:** Active
|
||||||
|
> **Last updated:** 2026-05-25
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
The WebSocket envelope contract is the realtime wire-format boundary between the signaling server and every connected client. Every realtime concern in Toju — presence, chat broadcasts, typing indicators, voice state, WebRTC offer/answer/ICE forwarding, direct messages, server icon P2P sync, and plugin events — travels as a typed envelope over a single WebSocket connection per client. Drift between the server definition and the client-side mirror is treated as a wire-protocol break.
|
||||||
|
|
||||||
|
## Responsibilities
|
||||||
|
|
||||||
|
- Define the canonical shape of every realtime message exchanged between `toju-app` (renderer) and `server`.
|
||||||
|
- Route incoming envelopes to a single dedicated handler on the server.
|
||||||
|
- Provide a stable identity for the connection (`connectionId`, `oderId`, `connectionScope`) and a lazy authorization model on `join_server`.
|
||||||
|
- Forward peer-targeted envelopes (WebRTC signaling, direct messages, server-icon peer transfers) without inspecting their payload.
|
||||||
|
|
||||||
|
This area does **not** own:
|
||||||
|
|
||||||
|
- The HTTP/REST surface (see [server-directory](./server-directory.md)).
|
||||||
|
- WebRTC media transport or session orchestration (see [voice-signaling](./voice-signaling.md) — the envelope contract is shared, but session lifecycle lives there).
|
||||||
|
- Persistence (server entities are owned by the server subdomain; the envelope is the contract, not the entity).
|
||||||
|
|
||||||
|
## Key concepts
|
||||||
|
|
||||||
|
- **Envelope** — a `{ type, ...payload }` message routed by `type`. Defined in `server/src/websocket/types.ts`.
|
||||||
|
- **ConnectedUser** — server-side state record per WebSocket: `connectionId`, `oderId`, `connectionScope`, `displayName`, `description`, `status`, `serverIds`, `lastPong`.
|
||||||
|
- **`oderId`** — opaque user identity. Set by the client in `identify`; falls back to a UUID if absent. Multiple connections may share an `oderId` (e.g. multiple devices) — broadcasts are deduplicated per `oderId`.
|
||||||
|
- **`connectionScope`** — typically the signal URL; disambiguates several connections from the same `oderId`.
|
||||||
|
- **Handler** — server-side function mapped to one envelope `type` in `server/src/websocket/handler.ts`.
|
||||||
|
- **Forwarded envelope** — peer-to-peer envelopes the server relays untouched to a specific `targetUserId` (offer / answer / ice_candidate / direct-call / direct-message family / server_icon_peer_*).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Envelope catalogue
|
||||||
|
|
||||||
|
Defined on the server in `server/src/websocket/types.ts` and dispatched by the switch in `server/src/websocket/handler.ts`. Groups below match the dispatch shape, not a literal grouping in code.
|
||||||
|
|
||||||
|
### Connection & presence
|
||||||
|
|
||||||
|
- `identify` — client → server. Profile + `connectionScope`. Required before any other envelope is meaningful.
|
||||||
|
- `connected` — server → client. Sent automatically on connect: `{ connectionId, serverTime }`.
|
||||||
|
- `keepalive` — client ↔ server. Resets `lastPong`. See lifecycle below.
|
||||||
|
- `status_update` — broadcast presence: `online | away | busy | offline`.
|
||||||
|
- `access_denied` — server → client when `join_server` authorization fails.
|
||||||
|
|
||||||
|
### Server membership
|
||||||
|
|
||||||
|
- `join_server` — client requests membership for a `serverId`. Authorization checked via `authorizeWebSocketJoin` (`server/src/services/server-access.service.ts`). Response includes `server_users` + `plugin_requirements`.
|
||||||
|
- `view_server` — client marks a server as viewed (fetch roster + plugin requirements without joining).
|
||||||
|
- `leave_server` — client leaves; broadcasts `user_left` to remaining members.
|
||||||
|
- `server_users` — server → client. Full peer roster for a joined server (used as the seed for P2P offers).
|
||||||
|
- `user_joined` / `user_left` — broadcast presence changes.
|
||||||
|
|
||||||
|
### Chat & typing
|
||||||
|
|
||||||
|
- `chat_message` — broadcast to a server. Payload: `{ message, senderId, senderName, timestamp }`.
|
||||||
|
- `typing` — broadcast: `{ isTyping, channelId, oderId, displayName }`.
|
||||||
|
|
||||||
|
### Voice presence
|
||||||
|
|
||||||
|
- `voice_state` — broadcast user voice state (mute/deafen/room metadata). Pure signaling — the server does not store voice room membership.
|
||||||
|
|
||||||
|
### WebRTC signaling (forwarded)
|
||||||
|
|
||||||
|
- `offer` / `answer` / `ice_candidate` — forwarded to `targetUserId` via `forwardRtcMessage()`.
|
||||||
|
- `direct-call` — forwarded; semantic call lifecycle lives in the `direct-call` product-client domain.
|
||||||
|
|
||||||
|
### Direct messages (forwarded)
|
||||||
|
|
||||||
|
- `direct-message`, `direct-message-status`, `direct-message-mutation`, `direct-message-sync`, `direct-message-sync-request` — forwarded to `targetUserId`.
|
||||||
|
|
||||||
|
### Server icon P2P sync
|
||||||
|
|
||||||
|
- `server_icon_available` — client announces it has an icon at version `iconUpdatedAt`.
|
||||||
|
- `server_icon_sync_request` — client asks the server which peers have a newer icon.
|
||||||
|
- `server_icon_sync_peers` — server → client. Peer list offering newer icons.
|
||||||
|
- `server_icon_peer_request` / `server_icon_peer_data` — P2P transfer, forwarded.
|
||||||
|
|
||||||
|
### Plugins
|
||||||
|
|
||||||
|
- `plugin_event` — validated against the plugin's registered event schema (see [plugin-system](./plugin-system.md) and `server/src/services/plugin-support.service.ts`), then broadcast within the server scope. Payload: `{ serverId, pluginId, eventName, payload, sourcePluginUserId, sourceUserId, emittedAt }`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Connection lifecycle
|
||||||
|
|
||||||
|
Implemented in `server/src/websocket/index.ts`.
|
||||||
|
|
||||||
|
1. Client opens WebSocket → server generates `connectionId` (UUID), creates the `ConnectedUser` record, sends `{ type: 'connected', connectionId, serverTime }`.
|
||||||
|
2. Client sends `identify` with `oderId`, `displayName`, `connectionScope`, optional `description` / `profileUpdatedAt`. Server normalizes and stores.
|
||||||
|
3. Client sends `join_server` (or `view_server`) per server they care about. Each `join_server` is authorized independently.
|
||||||
|
4. Heartbeat: server pings every **30 s** (`PING_INTERVAL_MS`). Any incoming message also refreshes `lastPong`. Connections without a pong for **45 s** (`PONG_TIMEOUT_MS`) are terminated.
|
||||||
|
5. On close: server emits `user_left` to every server the connection had joined. Broadcasts are **deduplicated by `oderId`**, so multi-device users only generate one departure event per logical identity.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Authentication model
|
||||||
|
|
||||||
|
There is no bearer token or signed envelope. Identity is whatever the client claims in `identify`. Authorization is **per-`join_server`**, evaluated by `authorizeWebSocketJoin` against persisted server access rules (private flag, password hash, bans, invite/join-request state). `access_denied` is returned when authorization fails; the connection itself stays open.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Technical implementation
|
||||||
|
|
||||||
|
### Server
|
||||||
|
|
||||||
|
- **Types**: `server/src/websocket/types.ts` — `WsMessage` (union over `type`), `ConnectedUser`, `ConnectionScope`.
|
||||||
|
- **Dispatcher**: `server/src/websocket/handler.ts` — `handleWebSocketMessage(connectionId, message)`. Single switch (~16 dedicated handler functions plus `forwardRtcMessage`).
|
||||||
|
- **Lifecycle**: `server/src/websocket/index.ts` — `ws` server, ping/pong, connection registry, dead-connection reaping.
|
||||||
|
- **Plugin event validation**: `server/src/services/plugin-support.service.ts` — async `validatePluginEventEnvelope()` (runtime schema check).
|
||||||
|
|
||||||
|
### Client (renderer)
|
||||||
|
|
||||||
|
- **Shared types**: `toju-app/src/app/shared-kernel/signaling-contracts.ts` — **stale**, only declares a generic `SignalingMessage` and an obsolete `SignalingMessageType` enum. Not the active wire-format definition.
|
||||||
|
- **Active envelope shapes** are defined inline as `IncomingSignalingMessage` in `toju-app/src/app/infrastructure/realtime/signaling/signaling-message-handler.ts`.
|
||||||
|
- **Constants**: `toju-app/src/app/infrastructure/realtime/realtime.constants.ts` — every envelope `type` string lives here as `SIGNALING_TYPE_*`.
|
||||||
|
- **Transport**: `toju-app/src/app/infrastructure/realtime/signaling/signaling-transport-handler.ts` — socket lifecycle, sends `identify`, `join_server`, raw envelopes.
|
||||||
|
- **Coordinator**: `toju-app/src/app/infrastructure/realtime/signaling/server-signaling-coordinator.ts` — maps `serverId` to signal URL (Toju supports multiple federated signaling endpoints).
|
||||||
|
- **Inbound dispatch**: `signaling-message-handler.ts` — `handleConnectedSignalingMessage`, `handleServerUsersSignalingMessage`, `handleUserJoinedSignalingMessage`, `handleUserLeftSignalingMessage`, `handleOfferSignalingMessage`, `handleAnswerSignalingMessage`, `handleIceCandidateSignalingMessage`, `handleAccessDeniedSignalingMessage`. Domain envelopes (chat/typing/direct-message/etc.) are consumed in the respective product-client domains, not in this central adapter — TODO: enumerate exact subscription points.
|
||||||
|
|
||||||
|
### Versioning
|
||||||
|
|
||||||
|
No `version` field on envelopes. No `Accept-Version` header. Drift between server and client is enforced only by code review (per `server/CONTEXT.md` invariants).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Testing
|
||||||
|
|
||||||
|
- `server/src/websocket/handler-status.spec.ts` — `status_update` broadcast and profile metadata in `user_joined` / `server_users`.
|
||||||
|
- `server/src/websocket/handler-plugin.spec.ts` — `plugin_event` validation and broadcast.
|
||||||
|
- `toju-app/src/app/infrastructure/realtime/signaling/signaling-message-handler.spec.ts` — inbound handler unit tests (notably `user_left` preserving peers under voice).
|
||||||
|
- **TODO**: no round-trip envelope-shape test between server `WsMessage` and client `IncomingSignalingMessage`. Drift can only be caught by E2E or manual review today.
|
||||||
|
|
||||||
|
## Security considerations
|
||||||
|
|
||||||
|
- No transport-level auth — identity is self-asserted via `identify`. The server trusts `oderId` for routing but checks authorization on every `join_server`.
|
||||||
|
- WebRTC signaling envelopes (`offer` / `answer` / `ice_candidate`) are forwarded **without inspection**. The server does not verify that the sender is a member of the same server as the target — TODO: confirm whether `forwardRtcMessage` enforces server-membership before forwarding.
|
||||||
|
- `plugin_event` payloads are bounded by the plugin's declared `maxPayloadBytes` (default 64 KB) and validated against the plugin's declared event schema. See [plugin-system](./plugin-system.md).
|
||||||
|
- Multi-connection identities: a single `oderId` may have many open sockets. Broadcasts dedupe by `oderId`, but per-connection state (e.g. `voice_state`) does not — TODO: document the cross-connection invariants.
|
||||||
|
|
||||||
|
## Performance considerations
|
||||||
|
|
||||||
|
- Single WebSocket per client. No fan-out worker; broadcast is in-process via the in-memory connection map.
|
||||||
|
- Ping cadence 30 s / pong timeout 45 s. Reaping is per-connection on next tick.
|
||||||
|
- TODO: no documented soft cap on connected users per signaling server.
|
||||||
|
|
||||||
|
## Known issues and limitations
|
||||||
|
|
||||||
|
- **Stale shared-kernel contract.** `toju-app/src/app/shared-kernel/signaling-contracts.ts` does not enumerate the live envelope set; client code uses `IncomingSignalingMessage` in `signaling-message-handler.ts` instead. Update or replace this file when adjacent work touches the wire format.
|
||||||
|
- **No envelope versioning.** Any field rename is an immediate break for older clients.
|
||||||
|
- **TODO — operator concerns**: rate limits, max-message-size, and backpressure are not documented.
|
||||||
|
|
||||||
|
## Related features
|
||||||
|
|
||||||
|
- **[voice-signaling](./voice-signaling.md)** — consumes `offer` / `answer` / `ice_candidate` / `voice_state` / `direct-call`.
|
||||||
|
- **[plugin-system](./plugin-system.md)** — defines and validates `plugin_event`.
|
||||||
|
- **[server-directory](./server-directory.md)** — REST counterpart for server discovery, joining, and moderation; `join_server` envelope authorization reuses the same access rules.
|
||||||
|
|
||||||
|
## Changelog
|
||||||
|
|
||||||
|
| Date | Change |
|
||||||
|
|------|--------|
|
||||||
|
| 2026-05-25 | Initial documentation |
|
||||||
@@ -15,7 +15,7 @@ Owns the Docusaurus-based application and plugin-author documentation. The build
|
|||||||
|
|
||||||
| Term | Definition | Aliases to avoid |
|
| Term | Definition | Aliases to avoid |
|
||||||
|------|------------|------------------|
|
|------|------------|------------------|
|
||||||
| **App docs** | End-user-facing documentation for the Toju desktop client. | "manual" |
|
| **App docs** | End-user-facing documentation for the MetoYou desktop client. | "manual" |
|
||||||
| **Plugin docs** | Developer-facing reference for the plugin runtime — manifest format, lifecycle hooks, host APIs. Authoritative source for the plugin contract surface. | "API docs" |
|
| **Plugin docs** | Developer-facing reference for the plugin runtime — manifest format, lifecycle hooks, host APIs. Authoritative source for the plugin contract surface. | "API docs" |
|
||||||
| **Local API server** | The Electron in-process HTTP server that mounts `docs-site/build/` so the renderer can browse docs offline. Defined under `electron/api/`. | "embedded server" |
|
| **Local API server** | The Electron in-process HTTP server that mounts `docs-site/build/` so the renderer can browse docs offline. Defined under `electron/api/`. | "embedded server" |
|
||||||
|
|
||||||
|
|||||||
@@ -48,7 +48,7 @@ This avoids:
|
|||||||
1. Add trusted signaling server URLs in desktop settings.
|
1. Add trusted signaling server URLs in desktop settings.
|
||||||
2. Start the Local API server.
|
2. Start the Local API server.
|
||||||
3. Call `POST /api/auth/login` with `username`, `password`, and `serverUrl`.
|
3. Call `POST /api/auth/login` with `username`, `password`, and `serverUrl`.
|
||||||
4. Toju validates credentials through the signaling server.
|
4. MetoYou validates credentials through the signaling server.
|
||||||
5. The desktop app issues an opaque local bearer token.
|
5. The desktop app issues an opaque local bearer token.
|
||||||
6. Use `Authorization: Bearer <token>` for protected routes.
|
6. Use `Authorization: Bearer <token>` for protected routes.
|
||||||
|
|
||||||
|
|||||||
@@ -4,7 +4,7 @@ sidebar_position: 1
|
|||||||
|
|
||||||
# Contributing
|
# Contributing
|
||||||
|
|
||||||
Toju is an npm-managed monorepo.
|
MetoYou is an npm-managed monorepo.
|
||||||
|
|
||||||
## Packages
|
## Packages
|
||||||
|
|
||||||
|
|||||||
@@ -4,11 +4,11 @@ sidebar_position: 5
|
|||||||
|
|
||||||
# LLM Plugin Builder Guide
|
# LLM Plugin Builder Guide
|
||||||
|
|
||||||
Copy this page into an LLM prompt when you want it to build a Toju plugin. It is intentionally explicit about the app, communication model, visual structure, manifest format, runtime rules, API types, and examples so the model has fewer gaps to invent around.
|
Copy this page into an LLM prompt when you want it to build a MetoYou plugin. It is intentionally explicit about the app, communication model, visual structure, manifest format, runtime rules, API types, and examples so the model has fewer gaps to invent around.
|
||||||
|
|
||||||
## Task For The LLM
|
## Task For The LLM
|
||||||
|
|
||||||
Build a Toju client plugin: a browser-safe JavaScript ES module with a `toju-plugin.json` manifest, loaded by the Angular renderer, running inside the user's local Toju app, using only browser APIs and the provided `TojuClientPluginApi`.
|
Build a MetoYou client plugin: a browser-safe JavaScript ES module with a `toju-plugin.json` manifest, loaded by the Angular renderer, running inside the user's local MetoYou app, using only browser APIs and the provided `TojuClientPluginApi`.
|
||||||
|
|
||||||
Return a plugin folder like this:
|
Return a plugin folder like this:
|
||||||
|
|
||||||
@@ -22,7 +22,7 @@ my-plugin/
|
|||||||
|
|
||||||
## Hard Rules
|
## Hard Rules
|
||||||
|
|
||||||
- Do not modify Toju core unless the user explicitly asks for a core code change.
|
- Do not modify MetoYou core unless the user explicitly asks for a core code change.
|
||||||
- Use plain browser ESM in `main.js`. Do not use Node APIs, `require`, `fs`, `path`, `child_process`, or build tooling unless explicitly requested.
|
- Use plain browser ESM in `main.js`. Do not use Node APIs, `require`, `fs`, `path`, `child_process`, or build tooling unless explicitly requested.
|
||||||
- Use `toju-plugin.json` as the manifest name.
|
- Use `toju-plugin.json` as the manifest name.
|
||||||
- Put every disposable returned by plugin APIs in `context.subscriptions`.
|
- Put every disposable returned by plugin APIs in `context.subscriptions`.
|
||||||
@@ -35,9 +35,9 @@ my-plugin/
|
|||||||
- Server-installed plugins are requirement metadata plus local client downloads. The signaling server never executes plugin entrypoints.
|
- Server-installed plugins are requirement metadata plus local client downloads. The signaling server never executes plugin entrypoints.
|
||||||
- Every event used with `api.events.*` must be declared in the manifest `events` array.
|
- Every event used with `api.events.*` must be declared in the manifest `events` array.
|
||||||
|
|
||||||
## What Toju Is
|
## What MetoYou Is
|
||||||
|
|
||||||
Toju is a Discord-like chat and voice app:
|
MetoYou is a Discord-like chat and voice app:
|
||||||
|
|
||||||
- `toju-app/`: Angular renderer and plugin runtime.
|
- `toju-app/`: Angular renderer and plugin runtime.
|
||||||
- `electron/`: Electron desktop shell, preload bridge, local database, local REST API, local docs host.
|
- `electron/`: Electron desktop shell, preload bridge, local database, local REST API, local docs host.
|
||||||
@@ -178,7 +178,7 @@ Minimal manifest:
|
|||||||
"schemaVersion": 1,
|
"schemaVersion": 1,
|
||||||
"id": "example.my-plugin",
|
"id": "example.my-plugin",
|
||||||
"title": "My Plugin",
|
"title": "My Plugin",
|
||||||
"description": "Adds a focused Toju feature.",
|
"description": "Adds a focused MetoYou feature.",
|
||||||
"version": "1.0.0",
|
"version": "1.0.0",
|
||||||
"kind": "client",
|
"kind": "client",
|
||||||
"scope": "client",
|
"scope": "client",
|
||||||
@@ -621,7 +621,7 @@ interface PluginApiCustomStreamRequest {
|
|||||||
label?: string;
|
label?: string;
|
||||||
}
|
}
|
||||||
|
|
||||||
type PluginApiActionSource = 'composerAction' | 'toolbarAction' | 'profileAction' | 'slashCommand' | 'manual';
|
type PluginApiActionSource = 'composerAction' | 'toolbarAction' | 'profileAction' | 'manual';
|
||||||
interface PluginApiActionContext {
|
interface PluginApiActionContext {
|
||||||
source: PluginApiActionSource;
|
source: PluginApiActionSource;
|
||||||
user: User | null;
|
user: User | null;
|
||||||
@@ -821,10 +821,6 @@ interface TojuClientPluginApi {
|
|||||||
registerEmbedRenderer: (id: string, contribution: PluginApiEmbedRendererContribution) => TojuPluginDisposable;
|
registerEmbedRenderer: (id: string, contribution: PluginApiEmbedRendererContribution) => TojuPluginDisposable;
|
||||||
mountElement: (id: string, request: PluginApiDomMountRequest) => TojuPluginDisposable;
|
mountElement: (id: string, request: PluginApiDomMountRequest) => TojuPluginDisposable;
|
||||||
};
|
};
|
||||||
readonly commands: {
|
|
||||||
register: (id: string, contribution: PluginApiSlashCommandContribution) => TojuPluginDisposable;
|
|
||||||
list: () => PluginApiSlashCommandContribution[];
|
|
||||||
};
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
@@ -855,7 +851,7 @@ const currentUser = api.profile.getCurrent();
|
|||||||
|
|
||||||
api.profile.update({
|
api.profile.update({
|
||||||
displayName: 'Ludde the Builder',
|
displayName: 'Ludde the Builder',
|
||||||
description: 'Building plugins for Toju.'
|
description: 'Building plugins for MetoYou.'
|
||||||
});
|
});
|
||||||
|
|
||||||
api.profile.updateAvatar({
|
api.profile.updateAvatar({
|
||||||
@@ -1182,8 +1178,6 @@ Capabilities:
|
|||||||
| `registerEmbedRenderer` | `ui.embeds` |
|
| `registerEmbedRenderer` | `ui.embeds` |
|
||||||
| `mountElement` | `ui.dom` |
|
| `mountElement` | `ui.dom` |
|
||||||
|
|
||||||
For `/` slash commands, use `api.commands.register` (capability `ui.commands`). See the Slash Commands subsection below.
|
|
||||||
|
|
||||||
Register side panel:
|
Register side panel:
|
||||||
|
|
||||||
```js
|
```js
|
||||||
@@ -1316,36 +1310,6 @@ context.subscriptions.push(
|
|||||||
|
|
||||||
`mountElement` tags the element with plugin ownership metadata, replaces duplicate mounts for the same plugin/id, and removes it on disposal/unload.
|
`mountElement` tags the element with plugin ownership metadata, replaces duplicate mounts for the same plugin/id, and removes it on disposal/unload.
|
||||||
|
|
||||||
### Slash Commands
|
|
||||||
|
|
||||||
Capability: `commands.register` and `commands.list` both require `ui.commands`.
|
|
||||||
|
|
||||||
Register `/` slash commands that appear in the chat composer's autocomplete menu. Set `scope: 'global'` (default) for commands available in chat servers and direct messages, or `scope: 'server'` for commands only offered while a chat server is active. Declare `options` to parse arguments into `context.args` (use `type: 'rest'` to capture all trailing text). The `run` callback receives a context with `source: 'slashCommand'`, the parsed `args`, the invoked `command` name, the raw `rawArgs`, and the current user/server/channel.
|
|
||||||
|
|
||||||
```js
|
|
||||||
context.subscriptions.push(
|
|
||||||
api.commands.register('announce', {
|
|
||||||
name: 'announce',
|
|
||||||
description: 'Post an announcement to the current channel',
|
|
||||||
icon: 'megaphone',
|
|
||||||
scope: 'server',
|
|
||||||
options: [{ name: 'message', type: 'rest', required: true }],
|
|
||||||
run: (slash) => api.messages.send(`Announcement: ${slash.args.message}`, slash.textChannel?.id)
|
|
||||||
})
|
|
||||||
);
|
|
||||||
|
|
||||||
context.subscriptions.push(
|
|
||||||
api.commands.register('shrug', {
|
|
||||||
name: 'shrug',
|
|
||||||
description: 'Append the shrug emoticon',
|
|
||||||
scope: 'global',
|
|
||||||
run: () => api.messages.send('shrug')
|
|
||||||
})
|
|
||||||
);
|
|
||||||
```
|
|
||||||
|
|
||||||
A command with no `options` runs immediately when picked; a command with options fills `/name ` so the user can type arguments before sending. Slash input is never posted as a chat message; unmatched `/text` falls through as a normal message.
|
|
||||||
|
|
||||||
## Capability Cheat Sheet
|
## Capability Cheat Sheet
|
||||||
|
|
||||||
| API call group | Capabilities |
|
| API call group | Capabilities |
|
||||||
@@ -1387,7 +1351,6 @@ A command with no `options` runs immediately when picked; a command with options
|
|||||||
| `ui.registerChannelSection` | `ui.channelsSection` |
|
| `ui.registerChannelSection` | `ui.channelsSection` |
|
||||||
| `ui.registerEmbedRenderer` | `ui.embeds` |
|
| `ui.registerEmbedRenderer` | `ui.embeds` |
|
||||||
| `ui.mountElement` | `ui.dom` |
|
| `ui.mountElement` | `ui.dom` |
|
||||||
| `commands.register`, `commands.list` | `ui.commands` |
|
|
||||||
|
|
||||||
## Complete Example Plugin
|
## Complete Example Plugin
|
||||||
|
|
||||||
|
|||||||
@@ -4,7 +4,7 @@ sidebar_position: 4
|
|||||||
|
|
||||||
# Local REST API
|
# Local REST API
|
||||||
|
|
||||||
The Toju desktop app exposes an optional local HTTP API for scripts and tools. It is implemented in Electron and reads local desktop data.
|
The MetoYou desktop app exposes an optional local HTTP API for scripts and tools. It is implemented in Electron and reads local desktop data.
|
||||||
|
|
||||||
## Enable the API
|
## Enable the API
|
||||||
|
|
||||||
|
|||||||
@@ -3,9 +3,9 @@ slug: /
|
|||||||
sidebar_position: 1
|
sidebar_position: 1
|
||||||
---
|
---
|
||||||
|
|
||||||
# Toju Documentation
|
# MetoYou Documentation
|
||||||
|
|
||||||
Toju is a desktop-first chat app with text channels, voice channels, direct messages, plugins, local desktop storage, a local REST API, and a Docusaurus documentation site bundled into the app.
|
MetoYou is a desktop-first chat app with text channels, voice channels, direct messages, plugins, local desktop storage, a local REST API, and a Docusaurus documentation site bundled into the app.
|
||||||
|
|
||||||
This site is split into three paths:
|
This site is split into three paths:
|
||||||
|
|
||||||
@@ -26,7 +26,7 @@ The Electron app can host this documentation locally. The docs endpoint is not a
|
|||||||
|
|
||||||
## Runtime Boundaries
|
## Runtime Boundaries
|
||||||
|
|
||||||
Toju keeps responsibilities split by package:
|
MetoYou keeps responsibilities split by package:
|
||||||
|
|
||||||
- `toju-app/` is the Angular product client and plugin runtime.
|
- `toju-app/` is the Angular product client and plugin runtime.
|
||||||
- `electron/` is the main process, preload bridge, IPC, local persistence, and local HTTP host.
|
- `electron/` is the main process, preload bridge, IPC, local persistence, and local HTTP host.
|
||||||
|
|||||||
@@ -318,55 +318,6 @@ interface PluginApiDomMountRequest {
|
|||||||
| `ui.registerEmbedRenderer(id, contribution)` | `ui.embeds` | Adds an embed renderer. |
|
| `ui.registerEmbedRenderer(id, contribution)` | `ui.embeds` | Adds an embed renderer. |
|
||||||
| `ui.mountElement(id, request)` | `ui.dom` | Mounts plugin-owned DOM into a target element or selector. |
|
| `ui.mountElement(id, request)` | `ui.dom` | Mounts plugin-owned DOM into a target element or selector. |
|
||||||
|
|
||||||
## Slash Commands
|
|
||||||
|
|
||||||
Slash commands appear in a Discord-style autocomplete menu when a user types `/` in the chat composer. A command with `scope: 'global'` (the default) is offered in every chat surface, including direct messages; a command with `scope: 'server'` only appears while a chat server is active. The user picks a command from the menu (or types it and presses Enter) and the `run` callback executes with the parsed arguments and the current interaction context.
|
|
||||||
|
|
||||||
```ts
|
|
||||||
type PluginApiSlashCommandScope = 'global' | 'server';
|
|
||||||
|
|
||||||
interface PluginApiSlashCommandOption {
|
|
||||||
description?: string;
|
|
||||||
name: string;
|
|
||||||
required?: boolean;
|
|
||||||
// 'rest' captures all remaining text; otherwise a single whitespace-delimited token
|
|
||||||
type?: 'string' | 'number' | 'boolean' | 'rest';
|
|
||||||
}
|
|
||||||
|
|
||||||
interface PluginApiSlashCommandContext extends PluginApiActionContext {
|
|
||||||
args: Record<string, string>; // parsed values keyed by option name
|
|
||||||
command: string; // invoked name without the leading slash
|
|
||||||
rawArgs: string; // raw text typed after the command name
|
|
||||||
}
|
|
||||||
|
|
||||||
interface PluginApiSlashCommandContribution {
|
|
||||||
description?: string;
|
|
||||||
icon?: string;
|
|
||||||
name: string;
|
|
||||||
options?: PluginApiSlashCommandOption[];
|
|
||||||
run: (context: PluginApiSlashCommandContext) => Promise<void> | void;
|
|
||||||
scope?: PluginApiSlashCommandScope;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
| Method | Capability | Description |
|
|
||||||
| ----------------------------------- | -------------- | ------------------------------------------------------------------- |
|
|
||||||
| `commands.register(id, command)` | `ui.commands` | Registers a `/` slash command for the chat composer. |
|
|
||||||
| `commands.list()` | `ui.commands` | Lists every slash command currently registered across all plugins. |
|
|
||||||
|
|
||||||
```ts
|
|
||||||
context.subscriptions.push(
|
|
||||||
api.commands.register('shout', {
|
|
||||||
description: 'Shout a message in uppercase',
|
|
||||||
icon: '📢',
|
|
||||||
name: 'shout',
|
|
||||||
options: [{ name: 'message', required: true, type: 'rest' }],
|
|
||||||
run: (slash) => api.messages.send(slash.args.message.toUpperCase()),
|
|
||||||
scope: 'server'
|
|
||||||
})
|
|
||||||
);
|
|
||||||
```
|
|
||||||
|
|
||||||
## Context and Logger
|
## Context and Logger
|
||||||
|
|
||||||
| Method | Capability | Description |
|
| Method | Capability | Description |
|
||||||
|
|||||||
@@ -1,114 +0,0 @@
|
|||||||
---
|
|
||||||
sidebar_position: 12
|
|
||||||
---
|
|
||||||
|
|
||||||
# Slash Commands API
|
|
||||||
|
|
||||||
The Commands API lets plugins register `/` slash commands. When a user types `/` in the chat composer, Toju shows a Discord-style autocomplete menu of available commands. Selecting a command (click, `Enter`, or `Tab`) runs it — either immediately when it declares no options, or after the user types the requested arguments.
|
|
||||||
|
|
||||||
## Required Capabilities
|
|
||||||
|
|
||||||
| Method | Capability |
|
|
||||||
| --------------------------------- | ------------- |
|
|
||||||
| `commands.register(id, command)` | `ui.commands` |
|
|
||||||
| `commands.list()` | `ui.commands` |
|
|
||||||
|
|
||||||
Every registration returns a disposable. Push it into `context.subscriptions` so the command is removed when the plugin unloads.
|
|
||||||
|
|
||||||
## Command Scope
|
|
||||||
|
|
||||||
A command's `scope` controls where it appears:
|
|
||||||
|
|
||||||
| Scope | Available in |
|
|
||||||
| ------------------- | --------------------------------------------- |
|
|
||||||
| `global` (default) | Chat servers **and** direct messages |
|
|
||||||
| `server` | Only while a chat server is the active surface |
|
|
||||||
|
|
||||||
Use `global` for commands that work without a server context (e.g. `/help`, `/shrug`). Use `server` for commands that act on the current server, channel, or members.
|
|
||||||
|
|
||||||
## Options and Argument Parsing
|
|
||||||
|
|
||||||
Declare `options` to describe the arguments a command accepts. Toju parses what the user typed after the command name and passes the result to `run` as `context.args`, keyed by option name.
|
|
||||||
|
|
||||||
```ts
|
|
||||||
interface PluginApiSlashCommandOption {
|
|
||||||
description?: string;
|
|
||||||
name: string;
|
|
||||||
required?: boolean;
|
|
||||||
// 'rest' captures all remaining text; otherwise a single whitespace-delimited token
|
|
||||||
type?: 'string' | 'number' | 'boolean' | 'rest';
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- Positional options are filled left-to-right from whitespace-delimited tokens.
|
|
||||||
- A `rest` option captures all remaining text verbatim (use it last, for free-form text).
|
|
||||||
- Missing positional values are passed as empty strings.
|
|
||||||
- The autocomplete menu shows required options as `<name>` and optional ones as `[name]`.
|
|
||||||
|
|
||||||
Values arrive as strings; convert `number`/`boolean` types yourself inside `run`.
|
|
||||||
|
|
||||||
## Command Context
|
|
||||||
|
|
||||||
`run` receives a context that extends the standard action context (`source: 'slashCommand'`) with the invocation details:
|
|
||||||
|
|
||||||
```ts
|
|
||||||
interface PluginApiSlashCommandContext extends PluginApiActionContext {
|
|
||||||
args: Record<string, string>; // parsed values keyed by option name
|
|
||||||
command: string; // invoked name without the leading slash
|
|
||||||
rawArgs: string; // raw text typed after the command name
|
|
||||||
// inherited: server, textChannel, voiceChannel, user, source
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Register a Command
|
|
||||||
|
|
||||||
```js
|
|
||||||
export function activate(context) {
|
|
||||||
const api = context.api;
|
|
||||||
|
|
||||||
// Server-scoped command with a free-form message argument.
|
|
||||||
context.subscriptions.push(
|
|
||||||
api.commands.register('announce', {
|
|
||||||
name: 'announce',
|
|
||||||
description: 'Post an announcement to the current channel',
|
|
||||||
icon: '📢',
|
|
||||||
scope: 'server',
|
|
||||||
options: [{ name: 'message', type: 'rest', required: true }],
|
|
||||||
run: (slash) => {
|
|
||||||
api.messages.send(`📢 ${slash.args.message}`, slash.textChannel?.id);
|
|
||||||
}
|
|
||||||
})
|
|
||||||
);
|
|
||||||
|
|
||||||
// Global command that works in servers and DMs.
|
|
||||||
context.subscriptions.push(
|
|
||||||
api.commands.register('shrug', {
|
|
||||||
name: 'shrug',
|
|
||||||
description: 'Append the shrug emoticon',
|
|
||||||
scope: 'global',
|
|
||||||
run: () => api.messages.send('¯\\_(ツ)_/¯')
|
|
||||||
})
|
|
||||||
);
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
`api.messages.send` requires the `messages.send` capability, so the example above declares both `ui.commands` and `messages.send` in its manifest.
|
|
||||||
|
|
||||||
## List Registered Commands
|
|
||||||
|
|
||||||
```js
|
|
||||||
const allCommands = context.api.commands.list();
|
|
||||||
```
|
|
||||||
|
|
||||||
Returns every slash command currently registered across all active plugins, including their scope and options.
|
|
||||||
|
|
||||||
## Built-in Commands
|
|
||||||
|
|
||||||
Toju ships first-party commands that are always available without any plugin, such as `/lenny` (posts `( ͡° ͜ʖ ͡°)`). They appear in the same autocomplete menu tagged as **Built-in**. Plugin commands are listed alongside them; if a plugin registers a command with the same name as a built-in, both appear and the user can pick either.
|
|
||||||
|
|
||||||
## How Input Is Handled
|
|
||||||
|
|
||||||
- Typing `/` opens the menu; typing more characters filters by command name (prefix matches rank first).
|
|
||||||
- Picking a command **without options** runs it immediately and clears the composer.
|
|
||||||
- Picking a command **with options** fills `/name ` so the user can type arguments, then `Enter` runs it.
|
|
||||||
- Slash input is intercepted and never posted as a chat message. Text that starts with `/` but matches no registered command falls through and is sent as a normal message.
|
|
||||||
@@ -6,8 +6,6 @@ sidebar_position: 11
|
|||||||
|
|
||||||
The UI API lets plugins add pages, settings pages, side panels, channel sections, actions, embed renderers, and controlled DOM mounts.
|
The UI API lets plugins add pages, settings pages, side panels, channel sections, actions, embed renderers, and controlled DOM mounts.
|
||||||
|
|
||||||
For `/` slash commands in the chat composer, see the [Slash Commands API](./commands.md) (`api.commands`).
|
|
||||||
|
|
||||||
Prefer registered UI contributions over direct DOM mounting. Contribution APIs let Angular render the plugin UI when the matching app surface exists. Direct DOM mounting runs immediately and throws if the target selector is not present.
|
Prefer registered UI contributions over direct DOM mounting. Contribution APIs let Angular render the plugin UI when the matching app surface exists. Direct DOM mounting runs immediately and throws if the target selector is not present.
|
||||||
|
|
||||||
## Required Capabilities
|
## Required Capabilities
|
||||||
@@ -153,7 +151,7 @@ export function activate(context) {
|
|||||||
|
|
||||||
Toolbar actions are command-style plugin entries shown in the server side panel's View plugins menu. Use them for small actions that should be easy to launch from a server, such as opening a plugin page, sending a status message, starting a timer, or toggling a plugin feature.
|
Toolbar actions are command-style plugin entries shown in the server side panel's View plugins menu. Use them for small actions that should be easy to launch from a server, such as opening a plugin page, sending a status message, starting a timer, or toggling a plugin feature.
|
||||||
|
|
||||||
The View plugins link appears in `[data-testid="plugin-room-side-panel"]` when the plugin side-panel area is rendered. Opening it shows an overlay menu, positioned like profile-card overlays, with registered actions laid out as plugin icon tiles. The `icon` field can be short text such as `RH`, an emoji, or an image URL; when omitted, Toju falls back to initials from the plugin/action labels.
|
The View plugins link appears in `[data-testid="plugin-room-side-panel"]` when the plugin side-panel area is rendered. Opening it shows an overlay menu, positioned like profile-card overlays, with registered actions laid out as plugin icon tiles. The `icon` field can be short text such as `RH`, an emoji, or an image URL; when omitted, MetoYou falls back to initials from the plugin/action labels.
|
||||||
|
|
||||||
Toolbar action callbacks receive an action context with `source: 'toolbarAction'`, the current user, current server, active text channel, and current voice channel when available.
|
Toolbar action callbacks receive an action context with `source: 'toolbarAction'`, the current user, current server, active text channel, and current voice channel when available.
|
||||||
|
|
||||||
|
|||||||
@@ -37,7 +37,6 @@ Capabilities protect privileged app surfaces. A plugin must declare a capability
|
|||||||
| `ui.channelsSection` | `ui.registerChannelSection()` | Adds channel sections. |
|
| `ui.channelsSection` | `ui.registerChannelSection()` | Adds channel sections. |
|
||||||
| `ui.embeds` | `ui.registerEmbedRenderer()` | Renders custom embeds. |
|
| `ui.embeds` | `ui.registerEmbedRenderer()` | Renders custom embeds. |
|
||||||
| `ui.dom` | `ui.mountElement()` | Mounts plugin-owned DOM into app targets. |
|
| `ui.dom` | `ui.mountElement()` | Mounts plugin-owned DOM into app targets. |
|
||||||
| `ui.commands` | `commands.register()`, `commands.list()` | Registers `/` slash commands (global or server scope) and lists registered commands. |
|
|
||||||
| `storage.local` | `storage.*`, `clientData.*` | Reads and writes plugin-local data. |
|
| `storage.local` | `storage.*`, `clientData.*` | Reads and writes plugin-local data. |
|
||||||
| `storage.serverData.read` | `serverData.read()` | Reads local per-user/per-server plugin data. |
|
| `storage.serverData.read` | `serverData.read()` | Reads local per-user/per-server plugin data. |
|
||||||
| `storage.serverData.write` | `serverData.write()`, `serverData.remove()` | Writes or removes local per-user/per-server plugin data. |
|
| `storage.serverData.write` | `serverData.write()`, `serverData.remove()` | Writes or removes local per-user/per-server plugin data. |
|
||||||
|
|||||||
@@ -4,7 +4,7 @@ sidebar_position: 1
|
|||||||
|
|
||||||
# Create a Plugin
|
# Create a Plugin
|
||||||
|
|
||||||
Toju plugins are browser-safe ES modules loaded by the Angular renderer. A plugin receives a frozen `TojuClientPluginApi`, declares every privileged capability in its manifest, and registers cleanup work through disposables.
|
MetoYou plugins are browser-safe ES modules loaded by the Angular renderer. A plugin receives a frozen `TojuClientPluginApi`, declares every privileged capability in its manifest, and registers cleanup work through disposables.
|
||||||
|
|
||||||
## Folder Layout
|
## Folder Layout
|
||||||
|
|
||||||
|
|||||||
@@ -45,61 +45,6 @@ export function activate(context) {
|
|||||||
|
|
||||||
The action appears as a tile in the server side panel's View plugins menu and runs with `source: 'toolbarAction'`.
|
The action appears as a tile in the server side panel's View plugins menu and runs with `source: 'toolbarAction'`.
|
||||||
|
|
||||||
## Slash Command Plugin
|
|
||||||
|
|
||||||
`toju-plugin.json`
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"schemaVersion": 1,
|
|
||||||
"id": "example.slash-commands",
|
|
||||||
"title": "Slash Commands",
|
|
||||||
"description": "Registers / commands available from the chat composer.",
|
|
||||||
"version": "1.0.0",
|
|
||||||
"kind": "client",
|
|
||||||
"scope": "client",
|
|
||||||
"apiVersion": "1.0.0",
|
|
||||||
"compatibility": {
|
|
||||||
"minimumTojuVersion": "1.0.0",
|
|
||||||
"verifiedTojuVersion": "1.0.0"
|
|
||||||
},
|
|
||||||
"entrypoint": "./main.js",
|
|
||||||
"capabilities": ["messages.send", "ui.commands"]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
`main.js`
|
|
||||||
|
|
||||||
```js
|
|
||||||
export function activate(context) {
|
|
||||||
const { api } = context;
|
|
||||||
|
|
||||||
// Global: works in chat servers and direct messages.
|
|
||||||
context.subscriptions.push(
|
|
||||||
api.commands.register('shrug', {
|
|
||||||
name: 'shrug',
|
|
||||||
description: 'Append the shrug emoticon',
|
|
||||||
scope: 'global',
|
|
||||||
run: () => api.messages.send('¯\\_(ツ)_/¯')
|
|
||||||
})
|
|
||||||
);
|
|
||||||
|
|
||||||
// Server-scoped: only offered while a chat server is active.
|
|
||||||
context.subscriptions.push(
|
|
||||||
api.commands.register('announce', {
|
|
||||||
name: 'announce',
|
|
||||||
description: 'Post an announcement to the current channel',
|
|
||||||
icon: '📢',
|
|
||||||
scope: 'server',
|
|
||||||
options: [{ name: 'message', type: 'rest', required: true }],
|
|
||||||
run: (slash) => api.messages.send(`📢 ${slash.args.message}`, slash.textChannel?.id)
|
|
||||||
})
|
|
||||||
);
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
Typing `/` in the composer opens the autocomplete menu. `/shrug` runs immediately; `/announce <message>` fills the composer so the user can type the announcement before sending. See the [Slash Commands API](./api/commands.md) for option parsing and the command context.
|
|
||||||
|
|
||||||
## Settings Page Plugin
|
## Settings Page Plugin
|
||||||
|
|
||||||
```json
|
```json
|
||||||
|
|||||||
@@ -41,7 +41,6 @@ type PluginCapabilityId =
|
|||||||
| 'ui.channelsSection'
|
| 'ui.channelsSection'
|
||||||
| 'ui.embeds'
|
| 'ui.embeds'
|
||||||
| 'ui.dom'
|
| 'ui.dom'
|
||||||
| 'ui.commands'
|
|
||||||
| 'storage.local'
|
| 'storage.local'
|
||||||
| 'storage.serverData.read'
|
| 'storage.serverData.read'
|
||||||
| 'storage.serverData.write'
|
| 'storage.serverData.write'
|
||||||
@@ -132,7 +131,7 @@ interface TojuPluginManifest {
|
|||||||
|
|
||||||
`scope: "server"` marks a plugin as server-scoped. Server-scoped store entries can be installed to a chat server as requirements. Required server plugins are auto-installed for members when that server opens; optional requirements stay listed but do not auto-install.
|
`scope: "server"` marks a plugin as server-scoped. Server-scoped store entries can be installed to a chat server as requirements. Required server plugins are auto-installed for members when that server opens; optional requirements stay listed but do not auto-install.
|
||||||
|
|
||||||
When a user installs a server-scoped plugin into the server they are currently viewing, Toju enables that plugin id locally and activates the plugin immediately after the local manifest is registered. Installing a server-scoped plugin for another server records the activation preference so it activates when that server is opened.
|
When a user installs a server-scoped plugin into the server they are currently viewing, MetoYou enables that plugin id locally and activates the plugin immediately after the local manifest is registered. Installing a server-scoped plugin for another server records the activation preference so it activates when that server is opened.
|
||||||
|
|
||||||
## Entrypoint and Bundle
|
## Entrypoint and Bundle
|
||||||
|
|
||||||
|
|||||||
@@ -4,7 +4,7 @@ sidebar_position: 1
|
|||||||
|
|
||||||
# First Steps
|
# First Steps
|
||||||
|
|
||||||
Toju is a chat app for servers, text conversations, direct messages, and live voice. You do not need to understand the technical parts to use it.
|
MetoYou is a chat app for servers, text conversations, direct messages, and live voice. You do not need to understand the technical parts to use it.
|
||||||
|
|
||||||
## Main Words
|
## Main Words
|
||||||
|
|
||||||
@@ -18,11 +18,11 @@ Toju is a chat app for servers, text conversations, direct messages, and live vo
|
|||||||
|
|
||||||
## Sign In
|
## Sign In
|
||||||
|
|
||||||
1. Open Toju.
|
1. Open MetoYou.
|
||||||
2. Sign in with your username and password.
|
2. Sign in with your username and password.
|
||||||
3. If you use more than one signaling server, choose the server endpoint that owns your account.
|
3. If you use more than one signaling server, choose the server endpoint that owns your account.
|
||||||
|
|
||||||
A signaling server handles accounts, server discovery, membership, and connection setup. In normal use you can think of it as the place Toju checks when you log in and join servers.
|
A signaling server handles accounts, server discovery, membership, and connection setup. In normal use you can think of it as the place MetoYou checks when you log in and join servers.
|
||||||
|
|
||||||
## Find a Server
|
## Find a Server
|
||||||
|
|
||||||
|
|||||||
@@ -4,7 +4,7 @@ sidebar_position: 5
|
|||||||
|
|
||||||
# Plugins for Users
|
# Plugins for Users
|
||||||
|
|
||||||
Plugins add features to Toju. They can add pages, buttons, panels, settings, sounds, message tools, custom embeds, or server-specific behavior.
|
Plugins add features to MetoYou. They can add pages, buttons, panels, settings, sounds, message tools, custom embeds, or server-specific behavior.
|
||||||
|
|
||||||
## Types of Plugins
|
## Types of Plugins
|
||||||
|
|
||||||
@@ -30,8 +30,6 @@ Server-scoped plugins installed to the server you are currently viewing are enab
|
|||||||
|
|
||||||
When plugins add quick actions to a server, the server side panel shows a View plugins link in the plugin area. Open it to see a grid of plugin action tiles. Selecting a tile runs that plugin's action in the current server and channel context.
|
When plugins add quick actions to a server, the server side panel shows a View plugins link in the plugin area. Open it to see a grid of plugin action tiles. Selecting a tile runs that plugin's action in the current server and channel context.
|
||||||
|
|
||||||
Plugins can also add `/` slash commands. Type `/` in the message box to open the command menu; plugin commands appear there tagged with the plugin name, alongside built-in commands like `/lenny`. See [Text and Direct Messages](./text-and-direct-messages.md#slash-commands) for how to use the menu.
|
|
||||||
|
|
||||||
## Install a Local Plugin
|
## Install a Local Plugin
|
||||||
|
|
||||||
Desktop builds can discover local plugin folders from the app data plugins directory.
|
Desktop builds can discover local plugin folders from the app data plugins directory.
|
||||||
@@ -44,7 +42,7 @@ Desktop builds can discover local plugin folders from the app data plugins direc
|
|||||||
|
|
||||||
## Server Plugin Prompts
|
## Server Plugin Prompts
|
||||||
|
|
||||||
When a server uses plugins, Toju may show a prompt.
|
When a server uses plugins, MetoYou may show a prompt.
|
||||||
|
|
||||||
| Status | Meaning |
|
| Status | Meaning |
|
||||||
| ------------ | --------------------------------------------------------------------------------- |
|
| ------------ | --------------------------------------------------------------------------------- |
|
||||||
@@ -67,7 +65,7 @@ Examples:
|
|||||||
| Messages | Send messages, read current messages, moderate messages, or render embeds. |
|
| Messages | Send messages, read current messages, moderate messages, or render embeds. |
|
||||||
| Users and roles | Read member lists, create plugin users, or manage users. |
|
| Users and roles | Read member lists, create plugin users, or manage users. |
|
||||||
| Voice and media | Play audio, add an audio stream, add a video stream, or adjust volume. |
|
| Voice and media | Play audio, add an audio stream, add a video stream, or adjust volume. |
|
||||||
| UI | Add pages, settings pages, side panels, toolbar buttons, slash commands, or DOM elements. |
|
| UI | Add pages, settings pages, side panels, toolbar buttons, or DOM elements. |
|
||||||
| Storage | Save plugin preferences locally or per server. |
|
| Storage | Save plugin preferences locally or per server. |
|
||||||
|
|
||||||
Only grant capabilities to plugins you trust.
|
Only grant capabilities to plugins you trust.
|
||||||
@@ -85,4 +83,4 @@ The Plugin Manager lets you:
|
|||||||
|
|
||||||
## Plugin Safety Notes
|
## Plugin Safety Notes
|
||||||
|
|
||||||
Plugins are browser-safe JavaScript modules loaded by the client. They do not run on the signaling server. A plugin can only call privileged Toju APIs when its manifest declares the capability and you grant it.
|
Plugins are browser-safe JavaScript modules loaded by the client. They do not run on the signaling server. A plugin can only call privileged MetoYou APIs when its manifest declares the capability and you grant it.
|
||||||
|
|||||||
@@ -4,7 +4,7 @@ sidebar_position: 2
|
|||||||
|
|
||||||
# Servers and Channels
|
# Servers and Channels
|
||||||
|
|
||||||
A server is the main shared space in Toju. Servers contain members, channels, permissions, optional plugins, and server settings.
|
A server is the main shared space in MetoYou. Servers contain members, channels, permissions, optional plugins, and server settings.
|
||||||
|
|
||||||
## Server Rail
|
## Server Rail
|
||||||
|
|
||||||
|
|||||||
@@ -20,7 +20,7 @@ Settings control the app, voice, plugins, servers, themes, updates, local APIs,
|
|||||||
|
|
||||||
## Local Data
|
## Local Data
|
||||||
|
|
||||||
Desktop Toju stores local app data on your device. That can include rooms, messages, users, plugin data, settings, and metadata. The desktop settings include data import/export tools.
|
Desktop MetoYou stores local app data on your device. That can include rooms, messages, users, plugin data, settings, and metadata. The desktop settings include data import/export tools.
|
||||||
|
|
||||||
## Local API and Documentation Hosting
|
## Local API and Documentation Hosting
|
||||||
|
|
||||||
|
|||||||
@@ -13,7 +13,6 @@ Text channels belong to a server. Everyone with access to that server and channe
|
|||||||
You can use text channels to:
|
You can use text channels to:
|
||||||
|
|
||||||
- send normal messages;
|
- send normal messages;
|
||||||
- run slash commands by typing `/`;
|
|
||||||
- edit or delete your own messages when allowed;
|
- edit or delete your own messages when allowed;
|
||||||
- react to messages;
|
- react to messages;
|
||||||
- send attachments;
|
- send attachments;
|
||||||
@@ -25,25 +24,14 @@ You can use text channels to:
|
|||||||
|
|
||||||
Direct messages are private conversations outside a server channel. Use them when a message is meant for one person instead of the server.
|
Direct messages are private conversations outside a server channel. Use them when a message is meant for one person instead of the server.
|
||||||
|
|
||||||
## Slash Commands
|
|
||||||
|
|
||||||
Type `/` at the start of the message box to open the slash command menu. It lists the commands you can run, with a short description for each.
|
|
||||||
|
|
||||||
- Keep typing to filter the list (for example `/le`).
|
|
||||||
- Use the up and down arrow keys to move through the list, then press `Enter` or `Tab` to pick a command. You can also click one.
|
|
||||||
- Press `Escape` to close the menu.
|
|
||||||
- A command that needs extra text fills the box with `/name ` so you can type the rest, then send it.
|
|
||||||
|
|
||||||
Toju includes built-in commands such as `/lenny`, which posts `( ͡° ͜ʖ ͡°)`. Plugins can add their own commands, which appear in the same menu (tagged with the plugin name). Slash commands are available in both text channels and direct messages; some plugin commands only appear inside a server. Text that starts with `/` but matches no command is sent as a normal message.
|
|
||||||
|
|
||||||
## Attachments and Media
|
## Attachments and Media
|
||||||
|
|
||||||
Attachments can appear as files, images, audio, or video depending on the file type and what the app can preview. If an image or link cannot load directly, the app can use fallback paths where available.
|
Attachments can appear as files, images, audio, or video depending on the file type and what the app can preview. If an image or link cannot load directly, the app can use fallback paths where available.
|
||||||
|
|
||||||
## Message Sync
|
## Message Sync
|
||||||
|
|
||||||
Toju stores messages locally and syncs recent messages with peers when connections are available. If you were offline, messages may appear after peers reconnect and exchange their recent message lists.
|
MetoYou stores messages locally and syncs recent messages with peers when connections are available. If you were offline, messages may appear after peers reconnect and exchange their recent message lists.
|
||||||
|
|
||||||
## Plugin Messages
|
## Plugin Messages
|
||||||
|
|
||||||
Some plugins can send messages, create bot-style plugin users, render custom embeds, or add composer buttons. Toju asks for plugin capability grants before plugins can use privileged message features.
|
Some plugins can send messages, create bot-style plugin users, render custom embeds, or add composer buttons. MetoYou asks for plugin capability grants before plugins can use privileged message features.
|
||||||
@@ -45,7 +45,7 @@ When someone shares camera or screen, the voice workspace can expand into a larg
|
|||||||
|
|
||||||
## Floating Voice Controls
|
## Floating Voice Controls
|
||||||
|
|
||||||
If you navigate away from the server while still connected to voice, Toju can show floating voice controls. Use them to return to the voice server or leave the call.
|
If you navigate away from the server while still connected to voice, MetoYou can show floating voice controls. Use them to return to the voice server or leave the call.
|
||||||
|
|
||||||
## Voice Settings
|
## Voice Settings
|
||||||
|
|
||||||
|
|||||||
@@ -2,11 +2,11 @@
|
|||||||
sidebar_position: 2
|
sidebar_position: 2
|
||||||
---
|
---
|
||||||
|
|
||||||
# Using Toju
|
# Using MetoYou
|
||||||
|
|
||||||
## Sign In
|
## Sign In
|
||||||
|
|
||||||
Toju signs in through a signaling server. The signaling server validates the user account, coordinates server membership, relays selected realtime messages, and helps peers establish WebRTC connections.
|
MetoYou signs in through a signaling server. The signaling server validates the user account, coordinates server membership, relays selected realtime messages, and helps peers establish WebRTC connections.
|
||||||
|
|
||||||
For the desktop Local API, the same signaling server allow-list is used before local bearer tokens can be issued. This keeps local automation tied to servers you explicitly trust.
|
For the desktop Local API, the same signaling server allow-list is used before local bearer tokens can be issued. This keeps local automation tied to servers you explicitly trust.
|
||||||
|
|
||||||
@@ -39,7 +39,7 @@ Desktop builds include platform integrations such as Linux display-server detect
|
|||||||
|
|
||||||
Open the Plugin Store from the title bar package button or menu. The plugin manager separates global client plugins from server-scoped plugins. Installed plugins can be activated, reloaded, unloaded, disabled, inspected for logs, and granted capabilities.
|
Open the Plugin Store from the title bar package button or menu. The plugin manager separates global client plugins from server-scoped plugins. Installed plugins can be activated, reloaded, unloaded, disabled, inspected for logs, and granted capabilities.
|
||||||
|
|
||||||
Plugins are explicit runtime modules. Toju loads browser-safe ES modules, passes a frozen API object, and cleans up registered disposables when a plugin unloads.
|
Plugins are explicit runtime modules. MetoYou loads browser-safe ES modules, passes a frozen API object, and cleans up registered disposables when a plugin unloads.
|
||||||
|
|
||||||
## Desktop Settings
|
## Desktop Settings
|
||||||
|
|
||||||
@@ -2,7 +2,7 @@ import type { Config } from '@docusaurus/types';
|
|||||||
import type * as Preset from '@docusaurus/preset-classic';
|
import type * as Preset from '@docusaurus/preset-classic';
|
||||||
|
|
||||||
const config: Config = {
|
const config: Config = {
|
||||||
title: 'Toju Docs',
|
title: 'MetoYou Docs',
|
||||||
tagline: 'Desktop chat, local APIs, and plugin development',
|
tagline: 'Desktop chat, local APIs, and plugin development',
|
||||||
url: 'http://127.0.0.1',
|
url: 'http://127.0.0.1',
|
||||||
baseUrl: '/docusaurus/',
|
baseUrl: '/docusaurus/',
|
||||||
@@ -31,7 +31,7 @@ const config: Config = {
|
|||||||
],
|
],
|
||||||
themeConfig: {
|
themeConfig: {
|
||||||
navbar: {
|
navbar: {
|
||||||
title: 'Toju Docs',
|
title: 'MetoYou Docs',
|
||||||
items: [
|
items: [
|
||||||
{ type: 'docSidebar', sidebarId: 'mainSidebar', position: 'left', label: 'Guides' },
|
{ type: 'docSidebar', sidebarId: 'mainSidebar', position: 'left', label: 'Guides' },
|
||||||
{ to: '/user-guide/first-steps', label: 'User Guide', position: 'left' },
|
{ to: '/user-guide/first-steps', label: 'User Guide', position: 'left' },
|
||||||
@@ -56,7 +56,7 @@ const config: Config = {
|
|||||||
]
|
]
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
copyright: 'Toju local documentation. Built with Docusaurus.'
|
copyright: 'MetoYou local documentation. Built with Docusaurus.'
|
||||||
},
|
},
|
||||||
prism: {
|
prism: {
|
||||||
additionalLanguages: [
|
additionalLanguages: [
|
||||||
|
|||||||
@@ -13,7 +13,7 @@ const sidebars: SidebarsConfig = {
|
|||||||
'user-guide/voice-channels',
|
'user-guide/voice-channels',
|
||||||
'user-guide/plugins',
|
'user-guide/plugins',
|
||||||
'user-guide/settings',
|
'user-guide/settings',
|
||||||
'using-toju'
|
'using-metoyou'
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
@@ -50,8 +50,7 @@ const sidebars: SidebarsConfig = {
|
|||||||
'plugin-development/api/message-bus',
|
'plugin-development/api/message-bus',
|
||||||
'plugin-development/api/p2p-and-media',
|
'plugin-development/api/p2p-and-media',
|
||||||
'plugin-development/api/storage',
|
'plugin-development/api/storage',
|
||||||
'plugin-development/api/ui',
|
'plugin-development/api/ui'
|
||||||
'plugin-development/api/commands'
|
|
||||||
]
|
]
|
||||||
},
|
},
|
||||||
'plugin-development/examples'
|
'plugin-development/examples'
|
||||||
|
|||||||
@@ -48,8 +48,7 @@ export const test = base.extend<MultiClientFixture>({
|
|||||||
|
|
||||||
const context = await browser.newContext({
|
const context = await browser.newContext({
|
||||||
permissions: ['microphone', 'camera'],
|
permissions: ['microphone', 'camera'],
|
||||||
baseURL: 'http://localhost:4200',
|
baseURL: 'http://localhost:4200'
|
||||||
viewport: { width: 1440, height: 900 }
|
|
||||||
});
|
});
|
||||||
|
|
||||||
await installTestServerEndpoint(context, testServer.port);
|
await installTestServerEndpoint(context, testServer.port);
|
||||||
|
|||||||
@@ -1,20 +0,0 @@
|
|||||||
import { expect, type Page } from '@playwright/test';
|
|
||||||
|
|
||||||
export async function openTitleBarMenu(page: Page): Promise<void> {
|
|
||||||
const menuButton = page.getByRole('button', { name: 'Menu' });
|
|
||||||
|
|
||||||
await expect(menuButton).toBeVisible({ timeout: 15_000 });
|
|
||||||
await menuButton.click();
|
|
||||||
await expect(page.locator('app-title-bar .absolute.right-0.top-full').first()).toBeVisible({ timeout: 10_000 });
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function openPluginStore(page: Page): Promise<void> {
|
|
||||||
await openTitleBarMenu(page);
|
|
||||||
await page.getByRole('button', { name: 'Plugin Store' }).click();
|
|
||||||
await expect(page).toHaveURL(/\/plugin-store/, { timeout: 20_000 });
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function openSettingsFromMenu(page: Page): Promise<void> {
|
|
||||||
await openTitleBarMenu(page);
|
|
||||||
await page.getByRole('button', { name: 'Settings' }).click();
|
|
||||||
}
|
|
||||||
@@ -1,106 +0,0 @@
|
|||||||
import { type APIRequestContext, type Page } from '@playwright/test';
|
|
||||||
|
|
||||||
export const AUTH_TOKENS_STORAGE_KEY = 'metoyou.authTokens';
|
|
||||||
export const SIGNAL_SERVER_CREDENTIALS_STORAGE_KEY = 'metoyou.signalServerCredentials';
|
|
||||||
|
|
||||||
export interface AuthSession {
|
|
||||||
id: string;
|
|
||||||
username: string;
|
|
||||||
displayName: string;
|
|
||||||
token: string;
|
|
||||||
expiresAt: number;
|
|
||||||
}
|
|
||||||
|
|
||||||
export function authHeaders(token: string): Record<string, string> {
|
|
||||||
return {
|
|
||||||
Authorization: `Bearer ${token}`,
|
|
||||||
'Content-Type': 'application/json'
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function registerTestUser(
|
|
||||||
request: APIRequestContext,
|
|
||||||
baseUrl: string,
|
|
||||||
username: string,
|
|
||||||
password: string,
|
|
||||||
displayName?: string
|
|
||||||
): Promise<AuthSession> {
|
|
||||||
const response = await request.post(`${baseUrl}/api/users/register`, {
|
|
||||||
data: {
|
|
||||||
username,
|
|
||||||
password,
|
|
||||||
displayName: displayName ?? username
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
if (!response.ok()) {
|
|
||||||
throw new Error(`Failed to register test user ${username}: ${response.status()} ${await response.text()}`);
|
|
||||||
}
|
|
||||||
|
|
||||||
return await response.json() as AuthSession;
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function loginTestUser(
|
|
||||||
request: APIRequestContext,
|
|
||||||
baseUrl: string,
|
|
||||||
username: string,
|
|
||||||
password: string
|
|
||||||
): Promise<AuthSession> {
|
|
||||||
const response = await request.post(`${baseUrl}/api/users/login`, {
|
|
||||||
data: { username, password }
|
|
||||||
});
|
|
||||||
|
|
||||||
if (!response.ok()) {
|
|
||||||
throw new Error(`Failed to login test user ${username}: ${response.status()} ${await response.text()}`);
|
|
||||||
}
|
|
||||||
|
|
||||||
return await response.json() as AuthSession;
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function readSignalServerCredentialFromPage(
|
|
||||||
page: Page,
|
|
||||||
serverUrl: string
|
|
||||||
): Promise<{ userId: string; token: string; username: string } | null> {
|
|
||||||
return await page.evaluate(({ storageKey, url }) => {
|
|
||||||
try {
|
|
||||||
const store = JSON.parse(localStorage.getItem(storageKey) || '{}') as Record<string, {
|
|
||||||
userId: string;
|
|
||||||
token: string;
|
|
||||||
username: string;
|
|
||||||
expiresAt: number;
|
|
||||||
}>;
|
|
||||||
const normalizedUrl = url.trim().replace(/\/+$/, '');
|
|
||||||
const entry = store[normalizedUrl];
|
|
||||||
|
|
||||||
if (!entry || entry.expiresAt <= Date.now()) {
|
|
||||||
return null;
|
|
||||||
}
|
|
||||||
|
|
||||||
return {
|
|
||||||
userId: entry.userId,
|
|
||||||
token: entry.token,
|
|
||||||
username: entry.username
|
|
||||||
};
|
|
||||||
} catch {
|
|
||||||
return null;
|
|
||||||
}
|
|
||||||
}, { storageKey: SIGNAL_SERVER_CREDENTIALS_STORAGE_KEY, url: serverUrl });
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function readAuthTokenFromPage(page: Page, serverUrl: string): Promise<string | null> {
|
|
||||||
return await page.evaluate(({ storageKey, url }) => {
|
|
||||||
try {
|
|
||||||
const store = JSON.parse(localStorage.getItem(storageKey) || '{}') as Record<string, { token: string; expiresAt: number }>;
|
|
||||||
const normalizedUrl = url.trim().replace(/\/+$/, '');
|
|
||||||
const entry = store[normalizedUrl];
|
|
||||||
|
|
||||||
if (!entry || entry.expiresAt <= Date.now()) {
|
|
||||||
return null;
|
|
||||||
}
|
|
||||||
|
|
||||||
return entry.token;
|
|
||||||
} catch {
|
|
||||||
return null;
|
|
||||||
}
|
|
||||||
}, { storageKey: AUTH_TOKENS_STORAGE_KEY, url: serverUrl });
|
|
||||||
}
|
|
||||||
@@ -1,11 +0,0 @@
|
|||||||
import { expect, type Page } from '@playwright/test';
|
|
||||||
|
|
||||||
/** Dashboard omnibox (desktop placeholder copy changed with i18n refresh). */
|
|
||||||
export function dashboardSearchInput(page: Page) {
|
|
||||||
return page.getByRole('textbox', { name: 'Search people, servers, and invites' });
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function expectDashboardReady(page: Page, timeout = 30_000): Promise<void> {
|
|
||||||
await expect(page).toHaveURL(/\/dashboard/, { timeout });
|
|
||||||
await expect(dashboardSearchInput(page)).toBeVisible({ timeout });
|
|
||||||
}
|
|
||||||
@@ -1,219 +0,0 @@
|
|||||||
import { expect, type Page } from '@playwright/test';
|
|
||||||
import { type Client } from '../fixtures/multi-client';
|
|
||||||
import { LoginPage } from '../pages/login.page';
|
|
||||||
import { RegisterPage } from '../pages/register.page';
|
|
||||||
import { ServerSearchPage } from '../pages/server-search.page';
|
|
||||||
import { ChatRoomPage } from '../pages/chat-room.page';
|
|
||||||
import { ChatMessagesPage } from '../pages/chat-messages.page';
|
|
||||||
|
|
||||||
export const MULTI_DEVICE_PASSWORD = 'TestPass123!';
|
|
||||||
export const MULTI_DEVICE_VOICE_CHANNEL = 'General';
|
|
||||||
|
|
||||||
export interface MultiDeviceCredentials {
|
|
||||||
username: string;
|
|
||||||
displayName: string;
|
|
||||||
password: string;
|
|
||||||
}
|
|
||||||
|
|
||||||
export interface MultiDeviceScenario {
|
|
||||||
clientA: Client;
|
|
||||||
clientB: Client;
|
|
||||||
credentials: MultiDeviceCredentials;
|
|
||||||
serverName: string;
|
|
||||||
messagesA: ChatMessagesPage;
|
|
||||||
messagesB: ChatMessagesPage;
|
|
||||||
roomA: ChatRoomPage;
|
|
||||||
roomB: ChatRoomPage;
|
|
||||||
}
|
|
||||||
|
|
||||||
export function uniqueMultiDeviceName(prefix: string): string {
|
|
||||||
return `${prefix}-${Date.now()}-${Math.floor(Math.random() * 10_000)}`;
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function createMultiDeviceScenario(
|
|
||||||
createClient: () => Promise<Client>,
|
|
||||||
options: { suffix?: string; serverDescription?: string } = {}
|
|
||||||
): Promise<MultiDeviceScenario> {
|
|
||||||
const suffix = options.suffix ?? uniqueMultiDeviceName('multi-device');
|
|
||||||
const credentials: MultiDeviceCredentials = {
|
|
||||||
username: `multi_${suffix}`,
|
|
||||||
displayName: 'Multi Device User',
|
|
||||||
password: MULTI_DEVICE_PASSWORD
|
|
||||||
};
|
|
||||||
const serverName = `Multi Device Server ${suffix}`;
|
|
||||||
const clientA = await createClient();
|
|
||||||
const clientB = await createClient();
|
|
||||||
|
|
||||||
await warmClientPage(clientA.page);
|
|
||||||
await warmClientPage(clientB.page);
|
|
||||||
|
|
||||||
const registerPage = new RegisterPage(clientA.page);
|
|
||||||
|
|
||||||
await registerPage.goto();
|
|
||||||
await registerPage.register(credentials.username, credentials.displayName, credentials.password);
|
|
||||||
await expect(clientA.page).toHaveURL(/\/dashboard/, { timeout: 15_000 });
|
|
||||||
|
|
||||||
const searchA = new ServerSearchPage(clientA.page);
|
|
||||||
|
|
||||||
await searchA.createServer(serverName, {
|
|
||||||
description: options.serverDescription ?? 'Multi-device session coverage'
|
|
||||||
});
|
|
||||||
|
|
||||||
await expect(clientA.page).toHaveURL(/\/room\//, { timeout: 15_000 });
|
|
||||||
await waitForCurrentRoomName(clientA.page, serverName);
|
|
||||||
|
|
||||||
const roomA = new ChatRoomPage(clientA.page);
|
|
||||||
|
|
||||||
await roomA.ensureVoiceChannelExists(MULTI_DEVICE_VOICE_CHANNEL);
|
|
||||||
|
|
||||||
await loginSecondDeviceIntoServer(clientB.page, credentials, serverName);
|
|
||||||
await waitForCurrentRoomName(clientB.page, serverName);
|
|
||||||
|
|
||||||
const messagesA = new ChatMessagesPage(clientA.page);
|
|
||||||
const messagesB = new ChatMessagesPage(clientB.page);
|
|
||||||
const roomB = new ChatRoomPage(clientB.page);
|
|
||||||
|
|
||||||
await messagesA.waitForReady();
|
|
||||||
await messagesB.waitForReady();
|
|
||||||
|
|
||||||
return {
|
|
||||||
clientA,
|
|
||||||
clientB,
|
|
||||||
credentials,
|
|
||||||
serverName,
|
|
||||||
messagesA,
|
|
||||||
messagesB,
|
|
||||||
roomA,
|
|
||||||
roomB
|
|
||||||
};
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function loginSecondDeviceIntoServer(
|
|
||||||
page: Page,
|
|
||||||
credentials: MultiDeviceCredentials,
|
|
||||||
serverName: string
|
|
||||||
): Promise<void> {
|
|
||||||
const loginPage = new LoginPage(page);
|
|
||||||
|
|
||||||
await loginPage.goto();
|
|
||||||
await loginPage.login(credentials.username, credentials.password);
|
|
||||||
await expect(page).toHaveURL(/\/dashboard/, { timeout: 15_000 });
|
|
||||||
|
|
||||||
const search = new ServerSearchPage(page);
|
|
||||||
|
|
||||||
await search.joinServerFromSearch(serverName);
|
|
||||||
await expect(page).toHaveURL(/\/room\//, { timeout: 20_000 });
|
|
||||||
await expect(page.locator('app-rooms-side-panel').first()).toBeVisible({ timeout: 20_000 });
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function expectCrossDeviceMessage(
|
|
||||||
sender: ChatMessagesPage,
|
|
||||||
receiver: ChatMessagesPage,
|
|
||||||
message: string,
|
|
||||||
timeout = 60_000
|
|
||||||
): Promise<void> {
|
|
||||||
await sender.sendMessage(message);
|
|
||||||
|
|
||||||
await expect.poll(async () => {
|
|
||||||
return await receiver.getMessageItemByText(message).isVisible()
|
|
||||||
.catch(() => false);
|
|
||||||
}, { timeout }).toBe(true);
|
|
||||||
}
|
|
||||||
|
|
||||||
async function warmClientPage(page: Page): Promise<void> {
|
|
||||||
await page.goto('/dashboard', { waitUntil: 'domcontentloaded' });
|
|
||||||
await page.waitForLoadState('networkidle').catch(() => undefined);
|
|
||||||
}
|
|
||||||
|
|
||||||
async function waitForCurrentRoomName(page: Page, roomName: string, timeout = 20_000): Promise<void> {
|
|
||||||
await page.waitForFunction(
|
|
||||||
(expectedRoomName) => {
|
|
||||||
interface RoomShape { name?: string }
|
|
||||||
interface AngularDebugApi {
|
|
||||||
getComponent: (element: Element) => Record<string, unknown>;
|
|
||||||
}
|
|
||||||
|
|
||||||
const host = document.querySelector('app-rooms-side-panel');
|
|
||||||
const debugApi = (window as { ng?: AngularDebugApi }).ng;
|
|
||||||
|
|
||||||
if (!host || !debugApi?.getComponent) {
|
|
||||||
return false;
|
|
||||||
}
|
|
||||||
|
|
||||||
const component = debugApi.getComponent(host);
|
|
||||||
const currentRoom = (component['currentRoom'] as (() => RoomShape | null) | undefined)?.() ?? null;
|
|
||||||
|
|
||||||
return currentRoom?.name === expectedRoomName;
|
|
||||||
},
|
|
||||||
roomName,
|
|
||||||
{ timeout }
|
|
||||||
);
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function readClientInstanceId(page: Page): Promise<string | null> {
|
|
||||||
return page.evaluate(() => {
|
|
||||||
const sessionId = sessionStorage.getItem('metoyou.clientInstanceId')?.trim();
|
|
||||||
|
|
||||||
if (sessionId) {
|
|
||||||
return sessionId;
|
|
||||||
}
|
|
||||||
|
|
||||||
return localStorage.getItem('metoyou.clientInstanceId')?.trim() ?? null;
|
|
||||||
});
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function logoutFromMenu(page: Page): Promise<void> {
|
|
||||||
const menuButton = page.getByRole('button', { name: 'Menu' });
|
|
||||||
const logoutButton = page.getByRole('button', { name: 'Logout' });
|
|
||||||
|
|
||||||
await expect(menuButton).toBeVisible({ timeout: 10_000 });
|
|
||||||
await menuButton.click();
|
|
||||||
await expect(logoutButton).toBeVisible({ timeout: 10_000 });
|
|
||||||
await logoutButton.click();
|
|
||||||
await expect(page).toHaveURL(/\/login/, { timeout: 15_000 });
|
|
||||||
}
|
|
||||||
|
|
||||||
export function channelsSidePanel(page: Page) {
|
|
||||||
return page.locator('app-rooms-side-panel').first();
|
|
||||||
}
|
|
||||||
|
|
||||||
export function membersSidePanel(page: Page) {
|
|
||||||
return page.locator('app-rooms-side-panel').last();
|
|
||||||
}
|
|
||||||
|
|
||||||
export function passiveVoiceChannelJoinBadge(page: Page, channelName = MULTI_DEVICE_VOICE_CHANNEL) {
|
|
||||||
return page
|
|
||||||
.locator(`button[data-channel-type="voice"][data-channel-name="${channelName}"]`)
|
|
||||||
.getByText('Join', { exact: true });
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function expectPassiveVoiceOnDevice(
|
|
||||||
page: Page,
|
|
||||||
options: { timeout?: number; displayName?: string; channelName?: string } = {}
|
|
||||||
): Promise<void> {
|
|
||||||
const timeout = options.timeout ?? 45_000;
|
|
||||||
const channelName = options.channelName ?? MULTI_DEVICE_VOICE_CHANNEL;
|
|
||||||
const displayName = options.displayName;
|
|
||||||
|
|
||||||
await expect.poll(async () => {
|
|
||||||
const membersLabel = await membersSidePanel(page)
|
|
||||||
.getByText('In voice on another device', { exact: false })
|
|
||||||
.isVisible()
|
|
||||||
.catch(() => false);
|
|
||||||
const joinBadge = await passiveVoiceChannelJoinBadge(page, channelName).isVisible()
|
|
||||||
.catch(() => false);
|
|
||||||
const grayedVoiceUser = displayName
|
|
||||||
? await channelsSidePanel(page).locator('.opacity-50')
|
|
||||||
.filter({ hasText: displayName })
|
|
||||||
.first()
|
|
||||||
.isVisible()
|
|
||||||
.catch(() => false)
|
|
||||||
: false;
|
|
||||||
|
|
||||||
return membersLabel || joinBadge || grayedVoiceUser;
|
|
||||||
}, { timeout }).toBe(true);
|
|
||||||
}
|
|
||||||
|
|
||||||
export async function expectActiveVoiceOnDevice(page: Page, timeout = 20_000): Promise<void> {
|
|
||||||
await expect(page.locator('app-voice-controls, app-voice-workspace').first()).toBeVisible({ timeout });
|
|
||||||
}
|
|
||||||
@@ -1,19 +0,0 @@
|
|||||||
import { expect, type Page } from '@playwright/test';
|
|
||||||
|
|
||||||
export const E2E_PLUGIN_SOURCE_URL = 'http://localhost:4200/plugins/e2e-plugin-source.json';
|
|
||||||
export const E2E_PLUGIN_TITLE = 'E2E All API Plugin';
|
|
||||||
|
|
||||||
export async function addPluginSource(page: Page, sourceUrl = E2E_PLUGIN_SOURCE_URL): Promise<void> {
|
|
||||||
const sourceInput = page.getByLabel('Plugin source manifest URL');
|
|
||||||
|
|
||||||
await expect(sourceInput).toBeVisible({ timeout: 15_000 });
|
|
||||||
await sourceInput.click();
|
|
||||||
await sourceInput.fill(sourceUrl);
|
|
||||||
await expect(sourceInput).toHaveValue(sourceUrl, { timeout: 5_000 });
|
|
||||||
|
|
||||||
const addSourceButton = page.getByRole('button', { name: 'Add Source' });
|
|
||||||
|
|
||||||
await expect(addSourceButton).toBeEnabled({ timeout: 10_000 });
|
|
||||||
await addSourceButton.click();
|
|
||||||
await expect(page.getByRole('heading', { name: E2E_PLUGIN_TITLE })).toBeVisible({ timeout: 20_000 });
|
|
||||||
}
|
|
||||||
@@ -7,19 +7,16 @@
|
|||||||
*
|
*
|
||||||
* Cleanup: the temp directory is removed when the process exits.
|
* Cleanup: the temp directory is removed when the process exits.
|
||||||
*/
|
*/
|
||||||
const { existsSync, mkdtempSync, writeFileSync, mkdirSync, rmSync } = require('fs');
|
const { mkdtempSync, writeFileSync, mkdirSync, rmSync } = require('fs');
|
||||||
const { join } = require('path');
|
const { join } = require('path');
|
||||||
const { tmpdir } = require('os');
|
const { tmpdir } = require('os');
|
||||||
const { spawn } = require('child_process');
|
const { spawn } = require('child_process');
|
||||||
|
|
||||||
const TEST_PORT = process.env.TEST_SERVER_PORT || '3099';
|
const TEST_PORT = process.env.TEST_SERVER_PORT || '3099';
|
||||||
const SERVER_DIR = join(__dirname, '..', '..', 'server');
|
const SERVER_DIR = join(__dirname, '..', '..', 'server');
|
||||||
const SERVER_DIST_ENTRY = join(SERVER_DIR, 'dist', 'index.js');
|
const SERVER_ENTRY = join(SERVER_DIR, 'src', 'index.ts');
|
||||||
const SERVER_SRC_ENTRY = join(SERVER_DIR, 'src', 'index.ts');
|
|
||||||
const SERVER_TSCONFIG = join(SERVER_DIR, 'tsconfig.json');
|
const SERVER_TSCONFIG = join(SERVER_DIR, 'tsconfig.json');
|
||||||
const TS_NODE_BIN = join(SERVER_DIR, 'node_modules', 'ts-node', 'dist', 'bin.js');
|
const TS_NODE_BIN = join(SERVER_DIR, 'node_modules', 'ts-node', 'dist', 'bin.js');
|
||||||
const SERVER_ENTRY = existsSync(SERVER_DIST_ENTRY) ? SERVER_DIST_ENTRY : SERVER_SRC_ENTRY;
|
|
||||||
const USE_COMPILED_SERVER = SERVER_ENTRY === SERVER_DIST_ENTRY;
|
|
||||||
|
|
||||||
// ── Create isolated temp data directory ──────────────────────────────
|
// ── Create isolated temp data directory ──────────────────────────────
|
||||||
const tmpDir = mkdtempSync(join(tmpdir(), 'metoyou-e2e-'));
|
const tmpDir = mkdtempSync(join(tmpdir(), 'metoyou-e2e-'));
|
||||||
@@ -48,7 +45,7 @@ console.log(`[E2E Server] Starting on port ${TEST_PORT}...`);
|
|||||||
// and node_modules are found from the real server/ directory.
|
// and node_modules are found from the real server/ directory.
|
||||||
const child = spawn(
|
const child = spawn(
|
||||||
process.execPath,
|
process.execPath,
|
||||||
USE_COMPILED_SERVER ? [SERVER_ENTRY] : [TS_NODE_BIN, '--project', SERVER_TSCONFIG, SERVER_ENTRY],
|
[TS_NODE_BIN, '--project', SERVER_TSCONFIG, SERVER_ENTRY],
|
||||||
{
|
{
|
||||||
cwd: tmpDir,
|
cwd: tmpDir,
|
||||||
env: {
|
env: {
|
||||||
|
|||||||
@@ -1,19 +1,15 @@
|
|||||||
/* eslint-disable @typescript-eslint/no-explicit-any */
|
/* eslint-disable @typescript-eslint/no-explicit-any */
|
||||||
import { type BrowserContext, type Page } from '@playwright/test';
|
import { type Page } from '@playwright/test';
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Install RTCPeerConnection monkey-patch on a page BEFORE navigating.
|
* Install RTCPeerConnection monkey-patch on a page BEFORE navigating.
|
||||||
* Tracks all created peer connections and their remote tracks so tests
|
* Tracks all created peer connections and their remote tracks so tests
|
||||||
* can inspect WebRTC state via `page.evaluate()`.
|
* can inspect WebRTC state via `page.evaluate()`.
|
||||||
*
|
*
|
||||||
* Call on the browser context (preferred) or page before any `goto()`.
|
* Call immediately after page creation, before any `goto()`.
|
||||||
*/
|
*/
|
||||||
export async function installWebRTCTracking(target: BrowserContext | Page): Promise<void> {
|
export async function installWebRTCTracking(page: Page): Promise<void> {
|
||||||
const addInitScript = 'addInitScript' in target && typeof target.addInitScript === 'function'
|
await page.addInitScript(() => {
|
||||||
? target.addInitScript.bind(target)
|
|
||||||
: (target as Page).addInitScript.bind(target);
|
|
||||||
|
|
||||||
await addInitScript(() => {
|
|
||||||
const connections: RTCPeerConnection[] = [];
|
const connections: RTCPeerConnection[] = [];
|
||||||
const dataChannels: RTCDataChannel[] = [];
|
const dataChannels: RTCDataChannel[] = [];
|
||||||
const syntheticMediaResources: {
|
const syntheticMediaResources: {
|
||||||
@@ -201,7 +197,6 @@ export async function waitForPeerConnected(page: Page, timeout = 30_000): Promis
|
|||||||
() => (window as any).__rtcConnections?.some(
|
() => (window as any).__rtcConnections?.some(
|
||||||
(pc: RTCPeerConnection) => pc.connectionState === 'connected'
|
(pc: RTCPeerConnection) => pc.connectionState === 'connected'
|
||||||
) ?? false,
|
) ?? false,
|
||||||
undefined,
|
|
||||||
{ timeout }
|
{ timeout }
|
||||||
);
|
);
|
||||||
}
|
}
|
||||||
@@ -616,7 +611,6 @@ export async function waitForAudioStatsPresent(page: Page, timeout = 15_000): Pr
|
|||||||
|
|
||||||
return false;
|
return false;
|
||||||
},
|
},
|
||||||
undefined,
|
|
||||||
{ timeout }
|
{ timeout }
|
||||||
);
|
);
|
||||||
}
|
}
|
||||||
@@ -824,7 +818,6 @@ export async function waitForVideoStatsPresent(page: Page, timeout = 15_000): Pr
|
|||||||
|
|
||||||
return false;
|
return false;
|
||||||
},
|
},
|
||||||
undefined,
|
|
||||||
{ timeout }
|
{ timeout }
|
||||||
);
|
);
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -34,22 +34,9 @@ export class ChatMessagesPage {
|
|||||||
}
|
}
|
||||||
|
|
||||||
async sendMessage(content: string): Promise<void> {
|
async sendMessage(content: string): Promise<void> {
|
||||||
let lastError: unknown;
|
await this.waitForReady();
|
||||||
|
await this.composerInput.fill(content);
|
||||||
for (let attempt = 1; attempt <= 3; attempt += 1) {
|
await this.sendButton.click();
|
||||||
try {
|
|
||||||
await this.waitForReady();
|
|
||||||
await this.composerInput.fill(content);
|
|
||||||
await expect(this.composerInput).toHaveValue(content, { timeout: 5_000 });
|
|
||||||
await expect(this.sendButton).toBeEnabled({ timeout: 5_000 });
|
|
||||||
await this.sendButton.click();
|
|
||||||
return;
|
|
||||||
} catch (error) {
|
|
||||||
lastError = error;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
throw lastError instanceof Error ? lastError : new Error('Failed to send chat message');
|
|
||||||
}
|
}
|
||||||
|
|
||||||
async typeDraft(content: string): Promise<void> {
|
async typeDraft(content: string): Promise<void> {
|
||||||
@@ -57,13 +44,6 @@ export class ChatMessagesPage {
|
|||||||
await this.composerInput.fill(content);
|
await this.composerInput.fill(content);
|
||||||
}
|
}
|
||||||
|
|
||||||
/** Types into the composer in a way that emits input/typing events (not just fill). */
|
|
||||||
async typeDraftWithTypingEvents(content: string): Promise<void> {
|
|
||||||
await this.waitForReady();
|
|
||||||
await this.composerInput.click();
|
|
||||||
await this.composerInput.pressSequentially(content, { delay: 40 });
|
|
||||||
}
|
|
||||||
|
|
||||||
async clearDraft(): Promise<void> {
|
async clearDraft(): Promise<void> {
|
||||||
await this.waitForReady();
|
await this.waitForReady();
|
||||||
await this.composerInput.fill('');
|
await this.composerInput.fill('');
|
||||||
|
|||||||
@@ -317,22 +317,13 @@ export class ChatRoomPage {
|
|||||||
throw new Error('Missing room, user, or endpoint when persisting channels');
|
throw new Error('Missing room, user, or endpoint when persisting channels');
|
||||||
}
|
}
|
||||||
|
|
||||||
const authTokens = JSON.parse(localStorage.getItem('metoyou.authTokens') || '{}') as Record<string, { token: string; expiresAt: number }>;
|
|
||||||
const normalizedApiUrl = apiBaseUrl.trim().replace(/\/+$/, '');
|
|
||||||
const authEntry = authTokens[normalizedApiUrl];
|
|
||||||
const authToken = authEntry && authEntry.expiresAt > Date.now() ? authEntry.token : null;
|
|
||||||
|
|
||||||
if (!authToken) {
|
|
||||||
throw new Error('Missing session token for channel persistence');
|
|
||||||
}
|
|
||||||
|
|
||||||
const response = await fetch(`${apiBaseUrl}/api/servers/${room.id}`, {
|
const response = await fetch(`${apiBaseUrl}/api/servers/${room.id}`, {
|
||||||
method: 'PUT',
|
method: 'PUT',
|
||||||
headers: {
|
headers: {
|
||||||
'Content-Type': 'application/json',
|
'Content-Type': 'application/json'
|
||||||
Authorization: `Bearer ${authToken}`
|
|
||||||
},
|
},
|
||||||
body: JSON.stringify({
|
body: JSON.stringify({
|
||||||
|
currentOwnerId: currentUser.id,
|
||||||
channels: nextChannels
|
channels: nextChannels
|
||||||
})
|
})
|
||||||
});
|
});
|
||||||
|
|||||||
@@ -10,14 +10,15 @@ export class LoginPage {
|
|||||||
readonly registerLink: Locator;
|
readonly registerLink: Locator;
|
||||||
|
|
||||||
constructor(private page: Page) {
|
constructor(private page: Page) {
|
||||||
this.form = page.locator('form').filter({ has: page.locator('#login-username') });
|
this.form = page.locator('#login-username').locator('xpath=ancestor::div[contains(@class, "space-y-3")]')
|
||||||
|
.first();
|
||||||
|
|
||||||
this.usernameInput = page.locator('#login-username');
|
this.usernameInput = page.locator('#login-username');
|
||||||
this.passwordInput = page.locator('#login-password');
|
this.passwordInput = page.locator('#login-password');
|
||||||
this.serverSelect = page.locator('#login-server');
|
this.serverSelect = page.locator('#login-server');
|
||||||
this.submitButton = this.form.getByRole('button', { name: 'Login' });
|
this.submitButton = this.form.getByRole('button', { name: 'Login' });
|
||||||
this.errorText = page.locator('.text-destructive');
|
this.errorText = page.locator('.text-destructive');
|
||||||
this.registerLink = page.getByRole('button', { name: 'Register' });
|
this.registerLink = this.form.getByRole('button', { name: 'Register' });
|
||||||
}
|
}
|
||||||
|
|
||||||
async goto() {
|
async goto() {
|
||||||
|
|||||||
@@ -7,71 +7,72 @@ import {
|
|||||||
export class ServerSearchPage {
|
export class ServerSearchPage {
|
||||||
readonly searchInput: Locator;
|
readonly searchInput: Locator;
|
||||||
readonly createServerButton: Locator;
|
readonly createServerButton: Locator;
|
||||||
readonly railDashboardButton: Locator;
|
readonly railCreateServerButton: Locator;
|
||||||
|
readonly searchCreateServerButton: Locator;
|
||||||
readonly settingsButton: Locator;
|
readonly settingsButton: Locator;
|
||||||
|
|
||||||
// Create server page
|
// Create server dialog
|
||||||
readonly serverNameInput: Locator;
|
readonly serverNameInput: Locator;
|
||||||
readonly serverDescriptionInput: Locator;
|
readonly serverDescriptionInput: Locator;
|
||||||
readonly serverTopicInput: Locator;
|
readonly serverTopicInput: Locator;
|
||||||
readonly signalEndpointSelect: Locator;
|
readonly signalEndpointSelect: Locator;
|
||||||
readonly advancedSettingsToggle: Locator;
|
|
||||||
readonly privateCheckbox: Locator;
|
readonly privateCheckbox: Locator;
|
||||||
readonly serverPasswordInput: Locator;
|
readonly serverPasswordInput: Locator;
|
||||||
readonly createSubmitButton: Locator;
|
readonly dialogCreateButton: Locator;
|
||||||
readonly cancelButton: Locator;
|
readonly dialogCancelButton: Locator;
|
||||||
|
|
||||||
constructor(private page: Page) {
|
constructor(private page: Page) {
|
||||||
// Server discovery lives on /servers via <app-server-browser>.
|
this.searchInput = page.getByPlaceholder('Search servers and users...');
|
||||||
this.searchInput = page.getByPlaceholder('Search servers...');
|
this.railCreateServerButton = page.locator('button[title="Create Server"]');
|
||||||
this.railDashboardButton = page.locator('button[title="Dashboard"]');
|
this.searchCreateServerButton = page.getByRole('button', { name: 'Create New Server' });
|
||||||
// Dashboard "Create Server" entry point.
|
this.createServerButton = this.searchCreateServerButton;
|
||||||
this.createServerButton = page.getByRole('link', { name: 'Create Server' }).first();
|
|
||||||
this.settingsButton = page.locator('button[title="Settings"]');
|
this.settingsButton = page.locator('button[title="Settings"]');
|
||||||
|
|
||||||
// Create-server page elements.
|
// Create dialog elements
|
||||||
this.serverNameInput = page.locator('#create-server-name');
|
this.serverNameInput = page.locator('#create-server-name');
|
||||||
this.serverDescriptionInput = page.locator('#create-server-description');
|
this.serverDescriptionInput = page.locator('#create-server-description');
|
||||||
this.serverTopicInput = page.locator('#create-server-topic');
|
this.serverTopicInput = page.locator('#create-server-topic');
|
||||||
this.signalEndpointSelect = page.locator('#create-server-signal-endpoint');
|
this.signalEndpointSelect = page.locator('#create-server-signal-endpoint');
|
||||||
this.advancedSettingsToggle = page.getByRole('button', { name: 'Advanced settings' });
|
this.privateCheckbox = page.locator('#private');
|
||||||
this.privateCheckbox = page.locator('#create-server-private');
|
|
||||||
this.serverPasswordInput = page.locator('#create-server-password');
|
this.serverPasswordInput = page.locator('#create-server-password');
|
||||||
this.createSubmitButton = page.locator('#create-server-submit');
|
this.dialogCreateButton = page.locator('div[role="dialog"]').getByRole('button', { name: 'Create' });
|
||||||
this.cancelButton = page.locator('#create-server-cancel');
|
this.dialogCancelButton = page.locator('div[role="dialog"]').getByRole('button', { name: 'Cancel' });
|
||||||
}
|
}
|
||||||
|
|
||||||
async goto() {
|
async goto() {
|
||||||
await this.page.goto('/servers');
|
await this.page.goto('/search');
|
||||||
}
|
}
|
||||||
|
|
||||||
async createServer(name: string, options?: { description?: string; topic?: string; sourceId?: string }) {
|
async createServer(name: string, options?: { description?: string; topic?: string; sourceId?: string }) {
|
||||||
await this.page.goto('/create-server', { waitUntil: 'domcontentloaded' });
|
if (!await this.serverNameInput.isVisible()) {
|
||||||
|
if (await this.searchCreateServerButton.isVisible()) {
|
||||||
|
await this.searchCreateServerButton.click();
|
||||||
|
} else {
|
||||||
|
await this.railCreateServerButton.click();
|
||||||
|
|
||||||
await expect(this.serverNameInput).toBeVisible({ timeout: 10_000 });
|
if (!await this.serverNameInput.isVisible()) {
|
||||||
|
await expect(this.searchCreateServerButton).toBeVisible({ timeout: 10_000 });
|
||||||
|
await this.searchCreateServerButton.click();
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
await expect(this.serverNameInput).toBeVisible();
|
||||||
await this.serverNameInput.fill(name);
|
await this.serverNameInput.fill(name);
|
||||||
|
|
||||||
if (options?.description) {
|
if (options?.description) {
|
||||||
await this.serverDescriptionInput.fill(options.description);
|
await this.serverDescriptionInput.fill(options.description);
|
||||||
}
|
}
|
||||||
|
|
||||||
if (options?.topic || options?.sourceId) {
|
if (options?.topic) {
|
||||||
if (!await this.serverTopicInput.isVisible()) {
|
await this.serverTopicInput.fill(options.topic);
|
||||||
await this.advancedSettingsToggle.click();
|
|
||||||
}
|
|
||||||
|
|
||||||
await expect(this.serverTopicInput).toBeVisible({ timeout: 10_000 });
|
|
||||||
|
|
||||||
if (options?.topic) {
|
|
||||||
await this.serverTopicInput.fill(options.topic);
|
|
||||||
}
|
|
||||||
|
|
||||||
if (options?.sourceId) {
|
|
||||||
await this.signalEndpointSelect.selectOption(options.sourceId);
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
|
|
||||||
await this.createSubmitButton.click();
|
if (options?.sourceId) {
|
||||||
|
await this.signalEndpointSelect.selectOption(options.sourceId);
|
||||||
|
}
|
||||||
|
|
||||||
|
await this.dialogCreateButton.click();
|
||||||
}
|
}
|
||||||
|
|
||||||
async joinSavedRoom(name: string) {
|
async joinSavedRoom(name: string) {
|
||||||
@@ -79,8 +80,6 @@ export class ServerSearchPage {
|
|||||||
}
|
}
|
||||||
|
|
||||||
async joinServerFromSearch(name: string, options: { acceptPluginDownloads?: boolean } = {}) {
|
async joinServerFromSearch(name: string, options: { acceptPluginDownloads?: boolean } = {}) {
|
||||||
await this.page.goto('/servers', { waitUntil: 'domcontentloaded' });
|
|
||||||
await expect(this.searchInput).toBeVisible({ timeout: 15_000 });
|
|
||||||
await this.searchInput.fill(name);
|
await this.searchInput.fill(name);
|
||||||
|
|
||||||
const serverCard = this.page.locator('div[title]', { hasText: name }).first();
|
const serverCard = this.page.locator('div[title]', { hasText: name }).first();
|
||||||
|
|||||||
@@ -1,27 +0,0 @@
|
|||||||
import { spawn } from 'node:child_process';
|
|
||||||
import { fileURLToPath } from 'node:url';
|
|
||||||
|
|
||||||
const e2eDirectory = fileURLToPath(new URL('.', import.meta.url));
|
|
||||||
const env = { ...process.env };
|
|
||||||
const browsersPath = env.PLAYWRIGHT_BROWSERS_PATH;
|
|
||||||
|
|
||||||
if (browsersPath?.includes('/cursor-sandbox-cache/')) {
|
|
||||||
delete env.PLAYWRIGHT_BROWSERS_PATH;
|
|
||||||
}
|
|
||||||
|
|
||||||
const [command = 'test', ...args] = process.argv.slice(2);
|
|
||||||
const executable = process.platform === 'win32' ? 'npx.cmd' : 'npx';
|
|
||||||
const child = spawn(executable, ['playwright', command, ...args], {
|
|
||||||
cwd: e2eDirectory,
|
|
||||||
env,
|
|
||||||
stdio: 'inherit'
|
|
||||||
});
|
|
||||||
|
|
||||||
child.on('exit', (code, signal) => {
|
|
||||||
if (signal) {
|
|
||||||
process.kill(process.pid, signal);
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
|
|
||||||
process.exit(code ?? 1);
|
|
||||||
});
|
|
||||||
@@ -1,153 +0,0 @@
|
|||||||
import { test, expect } from '../../fixtures/multi-client';
|
|
||||||
import { LoginPage } from '../../pages/login.page';
|
|
||||||
import { RegisterPage } from '../../pages/register.page';
|
|
||||||
|
|
||||||
interface TestUser {
|
|
||||||
username: string;
|
|
||||||
displayName: string;
|
|
||||||
password: string;
|
|
||||||
}
|
|
||||||
|
|
||||||
test.describe('Login returnUrl handling', () => {
|
|
||||||
test.describe.configure({ timeout: 120_000 });
|
|
||||||
|
|
||||||
test('unwraps nested login returnUrl chains after successful login', async ({ createClient }) => {
|
|
||||||
const client = await createClient();
|
|
||||||
const { page } = client;
|
|
||||||
const suffix = uniqueName('nested-return');
|
|
||||||
const user: TestUser = {
|
|
||||||
username: `user_${suffix}`,
|
|
||||||
displayName: 'Return Url User',
|
|
||||||
password: 'TestPass123!'
|
|
||||||
};
|
|
||||||
|
|
||||||
await test.step('Create an account', async () => {
|
|
||||||
const registerPage = new RegisterPage(page);
|
|
||||||
|
|
||||||
await registerPage.goto();
|
|
||||||
await registerPage.register(user.username, user.displayName, user.password);
|
|
||||||
await expect(page).toHaveURL(/\/dashboard/, { timeout: 15_000 });
|
|
||||||
});
|
|
||||||
|
|
||||||
await test.step('Log out and open a deeply nested login returnUrl', async () => {
|
|
||||||
await logout(page);
|
|
||||||
|
|
||||||
const nestedReturnUrl = '/login?returnUrl=%2Flogin%3FreturnUrl%3D%252Fservers';
|
|
||||||
|
|
||||||
await page.goto(`/login?returnUrl=${encodeURIComponent(nestedReturnUrl)}`, {
|
|
||||||
waitUntil: 'domcontentloaded'
|
|
||||||
});
|
|
||||||
|
|
||||||
await expect(page.locator('#login-username')).toBeVisible({ timeout: 15_000 });
|
|
||||||
});
|
|
||||||
|
|
||||||
await test.step('Login lands on the original destination instead of looping on /login', async () => {
|
|
||||||
const loginPage = new LoginPage(page);
|
|
||||||
|
|
||||||
await loginPage.login(user.username, user.password);
|
|
||||||
await expect(page).toHaveURL(/\/servers/, { timeout: 15_000 });
|
|
||||||
await expect(page).not.toHaveURL(/returnUrl=.*login/);
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
test('redirects unauthenticated /servers visits to login and returns there after login', async ({ createClient }) => {
|
|
||||||
const client = await createClient();
|
|
||||||
const { page } = client;
|
|
||||||
const suffix = uniqueName('servers-return');
|
|
||||||
const user: TestUser = {
|
|
||||||
username: `user_${suffix}`,
|
|
||||||
displayName: 'Servers Return User',
|
|
||||||
password: 'TestPass123!'
|
|
||||||
};
|
|
||||||
|
|
||||||
await test.step('Create an account and log out', async () => {
|
|
||||||
const registerPage = new RegisterPage(page);
|
|
||||||
|
|
||||||
await registerPage.goto();
|
|
||||||
await registerPage.register(user.username, user.displayName, user.password);
|
|
||||||
await expect(page).toHaveURL(/\/dashboard/, { timeout: 15_000 });
|
|
||||||
await logout(page);
|
|
||||||
});
|
|
||||||
|
|
||||||
await test.step('Visiting /servers sends the user to a single-level login returnUrl', async () => {
|
|
||||||
await page.goto('/servers', { waitUntil: 'domcontentloaded' });
|
|
||||||
await expect(page).toHaveURL(/\/login/, { timeout: 15_000 });
|
|
||||||
await expect(page).toHaveURL(/returnUrl=%2Fservers/);
|
|
||||||
await expect(page).not.toHaveURL(/returnUrl=.*login/);
|
|
||||||
});
|
|
||||||
|
|
||||||
await test.step('Logging in returns to /servers', async () => {
|
|
||||||
const loginPage = new LoginPage(page);
|
|
||||||
|
|
||||||
await loginPage.login(user.username, user.password);
|
|
||||||
await expect(page).toHaveURL(/\/servers/, { timeout: 15_000 });
|
|
||||||
await expect(page.locator('app-server-browser')).toBeVisible({ timeout: 15_000 });
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
test('lets a returning user log back in after an expired session redirect', async ({ createClient }) => {
|
|
||||||
const client = await createClient();
|
|
||||||
const { page } = client;
|
|
||||||
const suffix = uniqueName('expired-session');
|
|
||||||
const user: TestUser = {
|
|
||||||
username: `user_${suffix}`,
|
|
||||||
displayName: 'Expired Session User',
|
|
||||||
password: 'TestPass123!'
|
|
||||||
};
|
|
||||||
|
|
||||||
await test.step('Create an account', async () => {
|
|
||||||
const registerPage = new RegisterPage(page);
|
|
||||||
|
|
||||||
await registerPage.goto();
|
|
||||||
await registerPage.register(user.username, user.displayName, user.password);
|
|
||||||
await expect(page).toHaveURL(/\/dashboard/, { timeout: 15_000 });
|
|
||||||
});
|
|
||||||
|
|
||||||
await test.step('Simulate an expired session while keeping the persisted user id', async () => {
|
|
||||||
await page.evaluate(() => {
|
|
||||||
const storageKey = 'metoyou.authTokens';
|
|
||||||
const raw = localStorage.getItem(storageKey);
|
|
||||||
|
|
||||||
if (!raw) {
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
|
|
||||||
const parsed = JSON.parse(raw) as Record<string, { token: string; expiresAt: number }>;
|
|
||||||
const expiredStore = Object.fromEntries(
|
|
||||||
Object.entries(parsed).map(([url, entry]) => [url, { ...entry, expiresAt: 0 }])
|
|
||||||
);
|
|
||||||
|
|
||||||
localStorage.setItem(storageKey, JSON.stringify(expiredStore));
|
|
||||||
});
|
|
||||||
|
|
||||||
await page.goto('/servers', { waitUntil: 'domcontentloaded' });
|
|
||||||
await expect(page).toHaveURL(/\/login/, { timeout: 15_000 });
|
|
||||||
await expect(page).toHaveURL(/returnUrl=%2Fservers/);
|
|
||||||
await expect(page).not.toHaveURL(/returnUrl=.*login/);
|
|
||||||
});
|
|
||||||
|
|
||||||
await test.step('The user can authenticate again and reach /servers', async () => {
|
|
||||||
const loginPage = new LoginPage(page);
|
|
||||||
|
|
||||||
await loginPage.login(user.username, user.password);
|
|
||||||
await expect(page).toHaveURL(/\/servers/, { timeout: 15_000 });
|
|
||||||
await expect(page.locator('app-server-browser')).toBeVisible({ timeout: 15_000 });
|
|
||||||
});
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
async function logout(page: import('@playwright/test').Page): Promise<void> {
|
|
||||||
const menuButton = page.getByRole('button', { name: 'Menu' });
|
|
||||||
const logoutButton = page.getByRole('button', { name: 'Logout' });
|
|
||||||
|
|
||||||
await expect(menuButton).toBeVisible({ timeout: 10_000 });
|
|
||||||
await menuButton.click();
|
|
||||||
await expect(logoutButton).toBeVisible({ timeout: 10_000 });
|
|
||||||
await logoutButton.click();
|
|
||||||
await expect(page).toHaveURL(/\/login/, { timeout: 15_000 });
|
|
||||||
}
|
|
||||||
|
|
||||||
function uniqueName(prefix: string): string {
|
|
||||||
return `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36)
|
|
||||||
.slice(2, 8)}`;
|
|
||||||
}
|
|
||||||
@@ -1,94 +0,0 @@
|
|||||||
import { test, expect } from '../../fixtures/multi-client';
|
|
||||||
import {
|
|
||||||
MULTI_DEVICE_VOICE_CHANNEL,
|
|
||||||
channelsSidePanel,
|
|
||||||
createMultiDeviceScenario,
|
|
||||||
expectCrossDeviceMessage,
|
|
||||||
expectActiveVoiceOnDevice,
|
|
||||||
expectPassiveVoiceOnDevice,
|
|
||||||
logoutFromMenu,
|
|
||||||
membersSidePanel,
|
|
||||||
passiveVoiceChannelJoinBadge,
|
|
||||||
readClientInstanceId,
|
|
||||||
uniqueMultiDeviceName
|
|
||||||
} from '../../helpers/multi-device-session';
|
|
||||||
|
|
||||||
test.describe('Multi-device session', () => {
|
|
||||||
test.describe.configure({ timeout: 300_000, retries: 1 });
|
|
||||||
|
|
||||||
test('covers identity, chat sync, typing exclusion, and voice exclusivity', async ({ createClient }) => {
|
|
||||||
const scenario = await createMultiDeviceScenario(createClient);
|
|
||||||
const messageAtoB = `Cross-device A to B ${uniqueMultiDeviceName('msg')}`;
|
|
||||||
const messageBtoA = `Cross-device B to A ${uniqueMultiDeviceName('msg')}`;
|
|
||||||
const typingDraft = `Typing draft ${uniqueMultiDeviceName('draft')}`;
|
|
||||||
|
|
||||||
await test.step('assigns distinct clientInstanceId per browser context', async () => {
|
|
||||||
const instanceA = await readClientInstanceId(scenario.clientA.page);
|
|
||||||
const instanceB = await readClientInstanceId(scenario.clientB.page);
|
|
||||||
|
|
||||||
expect(instanceA).toBeTruthy();
|
|
||||||
expect(instanceB).toBeTruthy();
|
|
||||||
expect(instanceA).not.toEqual(instanceB);
|
|
||||||
});
|
|
||||||
|
|
||||||
await test.step('syncs chat from device A to device B', async () => {
|
|
||||||
await expectCrossDeviceMessage(scenario.messagesA, scenario.messagesB, messageAtoB);
|
|
||||||
});
|
|
||||||
|
|
||||||
await test.step('syncs chat from device B to device A', async () => {
|
|
||||||
await expectCrossDeviceMessage(scenario.messagesB, scenario.messagesA, messageBtoA);
|
|
||||||
});
|
|
||||||
|
|
||||||
await test.step('does not show own typing indicator on the other device for the same user', async () => {
|
|
||||||
await scenario.messagesA.typeDraftWithTypingEvents(typingDraft);
|
|
||||||
|
|
||||||
await expect(
|
|
||||||
scenario.clientB.page.getByText(`${scenario.credentials.displayName} is typing`, { exact: false })
|
|
||||||
).toHaveCount(0, { timeout: 5_000 });
|
|
||||||
});
|
|
||||||
|
|
||||||
await test.step('shows passive in-voice UI on the second device when the first joins voice', async () => {
|
|
||||||
await scenario.roomA.joinVoiceChannel(MULTI_DEVICE_VOICE_CHANNEL);
|
|
||||||
await expectActiveVoiceOnDevice(scenario.clientA.page);
|
|
||||||
|
|
||||||
await expectPassiveVoiceOnDevice(scenario.clientB.page, {
|
|
||||||
displayName: scenario.credentials.displayName
|
|
||||||
});
|
|
||||||
|
|
||||||
await expect(
|
|
||||||
membersSidePanel(scenario.clientB.page).getByText('In voice on another device', { exact: false })
|
|
||||||
).toBeVisible({ timeout: 20_000 });
|
|
||||||
|
|
||||||
await expect(
|
|
||||||
channelsSidePanel(scenario.clientB.page).locator('.opacity-50')
|
|
||||||
.filter({
|
|
||||||
hasText: scenario.credentials.displayName
|
|
||||||
})
|
|
||||||
.first()
|
|
||||||
).toBeVisible({ timeout: 20_000 });
|
|
||||||
});
|
|
||||||
|
|
||||||
await test.step('shows Join takeover affordance on passive device voice channel', async () => {
|
|
||||||
await expect(passiveVoiceChannelJoinBadge(scenario.clientB.page)).toBeVisible({ timeout: 20_000 });
|
|
||||||
});
|
|
||||||
|
|
||||||
await test.step('transfers voice ownership when the passive device takes over', async () => {
|
|
||||||
await scenario.roomB.joinVoiceChannel(MULTI_DEVICE_VOICE_CHANNEL);
|
|
||||||
await expectActiveVoiceOnDevice(scenario.clientB.page);
|
|
||||||
|
|
||||||
await expectPassiveVoiceOnDevice(scenario.clientA.page, {
|
|
||||||
displayName: scenario.credentials.displayName
|
|
||||||
});
|
|
||||||
});
|
|
||||||
|
|
||||||
await test.step('keeps the second device logged in when the first device logs out', async () => {
|
|
||||||
const message = `Still logged in ${uniqueMultiDeviceName('logout')}`;
|
|
||||||
|
|
||||||
await logoutFromMenu(scenario.clientA.page);
|
|
||||||
|
|
||||||
await scenario.messagesB.sendMessage(message);
|
|
||||||
await expect(scenario.messagesB.getMessageItemByText(message)).toBeVisible({ timeout: 20_000 });
|
|
||||||
await expect(scenario.clientB.page).toHaveURL(/\/room\//, { timeout: 10_000 });
|
|
||||||
});
|
|
||||||
});
|
|
||||||
});
|
|
||||||
@@ -1,111 +0,0 @@
|
|||||||
import { expect } from '@playwright/test';
|
|
||||||
import { test } from '../../fixtures/multi-client';
|
|
||||||
import { openSettingsFromMenu } from '../../helpers/app-menu';
|
|
||||||
import { expectDashboardReady } from '../../helpers/dashboard';
|
|
||||||
import { installTestServerEndpoints } from '../../helpers/seed-test-endpoint';
|
|
||||||
import { startTestServer } from '../../helpers/test-server';
|
|
||||||
import {
|
|
||||||
readAuthTokenFromPage,
|
|
||||||
readSignalServerCredentialFromPage,
|
|
||||||
registerTestUser
|
|
||||||
} from '../../helpers/auth-api';
|
|
||||||
import { RegisterPage } from '../../pages/register.page';
|
|
||||||
|
|
||||||
const PRIMARY_ENDPOINT_ID = 'e2e-multi-auth-primary';
|
|
||||||
const USER_PASSWORD = 'TestPass123!';
|
|
||||||
|
|
||||||
test.describe('Multi-signal-server authentication', () => {
|
|
||||||
test.describe.configure({ timeout: 180_000 });
|
|
||||||
|
|
||||||
test('auto-provisions a foreign signal server when a new endpoint is added', async ({ createClient, request }) => {
|
|
||||||
const primaryServer = await startTestServer();
|
|
||||||
const secondaryServer = await startTestServer();
|
|
||||||
|
|
||||||
try {
|
|
||||||
const client = await createClient();
|
|
||||||
const suffix = `multi_auth_${Date.now()}`;
|
|
||||||
const username = `user_${suffix}`;
|
|
||||||
|
|
||||||
await installTestServerEndpoints(client.context, [
|
|
||||||
{
|
|
||||||
id: PRIMARY_ENDPOINT_ID,
|
|
||||||
name: 'E2E Primary Signal',
|
|
||||||
url: primaryServer.url,
|
|
||||||
isActive: true,
|
|
||||||
status: 'online'
|
|
||||||
}
|
|
||||||
]);
|
|
||||||
|
|
||||||
await test.step('Register on the home signal server', async () => {
|
|
||||||
const register = new RegisterPage(client.page);
|
|
||||||
|
|
||||||
await register.goto();
|
|
||||||
await register.register(username, 'Multi Auth User', USER_PASSWORD);
|
|
||||||
await expectDashboardReady(client.page);
|
|
||||||
});
|
|
||||||
|
|
||||||
await test.step('Add a second signal server in network settings', async () => {
|
|
||||||
await openSettingsFromMenu(client.page);
|
|
||||||
await client.page.getByRole('button', { name: 'Network' }).click();
|
|
||||||
|
|
||||||
await client.page.getByPlaceholder('Server name').fill('E2E Secondary Signal');
|
|
||||||
await client.page.getByPlaceholder('Server URL (e.g., http://localhost:3001)').fill(secondaryServer.url);
|
|
||||||
await client.page.getByTestId('add-signal-server-button').click();
|
|
||||||
|
|
||||||
await expect(client.page.getByText(secondaryServer.url)).toBeVisible({ timeout: 15_000 });
|
|
||||||
});
|
|
||||||
|
|
||||||
await test.step('Wait for auto-provisioned credentials on the secondary server', async () => {
|
|
||||||
await expect.poll(async () =>
|
|
||||||
await readSignalServerCredentialFromPage(client.page, secondaryServer.url),
|
|
||||||
{ timeout: 30_000 }
|
|
||||||
).not.toBeNull();
|
|
||||||
|
|
||||||
const homeToken = await readAuthTokenFromPage(client.page, primaryServer.url);
|
|
||||||
const secondaryCredential = await readSignalServerCredentialFromPage(client.page, secondaryServer.url);
|
|
||||||
|
|
||||||
expect(homeToken).toBeTruthy();
|
|
||||||
expect(secondaryCredential?.username).toBe(username);
|
|
||||||
expect(secondaryCredential?.token).toBeTruthy();
|
|
||||||
});
|
|
||||||
|
|
||||||
await test.step('Secondary credential can call authenticated APIs', async () => {
|
|
||||||
const secondaryCredential = await readSignalServerCredentialFromPage(client.page, secondaryServer.url);
|
|
||||||
|
|
||||||
if (!secondaryCredential) {
|
|
||||||
throw new Error('Expected secondary signal-server credential to be provisioned');
|
|
||||||
}
|
|
||||||
|
|
||||||
const response = await request.post(`${secondaryServer.url}/api/servers`, {
|
|
||||||
headers: {
|
|
||||||
Authorization: `Bearer ${secondaryCredential.token}`,
|
|
||||||
'Content-Type': 'application/json'
|
|
||||||
},
|
|
||||||
data: {
|
|
||||||
name: `Secondary Provisioned Server ${suffix}`,
|
|
||||||
description: 'Created with auto-provisioned credentials',
|
|
||||||
ownerId: secondaryCredential.userId,
|
|
||||||
ownerPublicKey: 'e2e-secondary-owner-key'
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
expect(response.ok(), `POST /api/servers failed: ${response.status()} ${await response.text()}`).toBe(true);
|
|
||||||
});
|
|
||||||
|
|
||||||
await test.step('Home registration still works independently on the secondary server', async () => {
|
|
||||||
const otherUser = await registerTestUser(
|
|
||||||
request,
|
|
||||||
secondaryServer.url,
|
|
||||||
`other_${suffix}`,
|
|
||||||
USER_PASSWORD,
|
|
||||||
'Other User'
|
|
||||||
);
|
|
||||||
|
|
||||||
expect(otherUser.username).toBe(`other_${suffix}`);
|
|
||||||
});
|
|
||||||
} finally {
|
|
||||||
await primaryServer.stop();
|
|
||||||
await secondaryServer.stop();
|
|
||||||
}
|
|
||||||
});
|
|
||||||
});
|
|
||||||
@@ -48,13 +48,14 @@ test.describe('User session data isolation', () => {
|
|||||||
|
|
||||||
await test.step('Alice registers and creates local chat history', async () => {
|
await test.step('Alice registers and creates local chat history', async () => {
|
||||||
await registerUser(client.page, alice);
|
await registerUser(client.page, alice);
|
||||||
await createServerAndSendMessage(client.page, alice, aliceServerName, aliceMessage);
|
await createServerAndSendMessage(client.page, aliceServerName, aliceMessage);
|
||||||
});
|
});
|
||||||
|
|
||||||
await test.step('Alice sees the same saved room and message after a full restart', async () => {
|
await test.step('Alice sees the same saved room and message after a full restart', async () => {
|
||||||
await restartPersistentClient(client, testServer.port);
|
await restartPersistentClient(client, testServer.port);
|
||||||
await openApp(client.page);
|
await openApp(client.page);
|
||||||
await expectSavedRoomAndHistory(client.page, alice, aliceServerName, aliceMessage);
|
await expect(client.page).not.toHaveURL(/\/login/, { timeout: 15_000 });
|
||||||
|
await expectSavedRoomAndHistory(client.page, aliceServerName, aliceMessage);
|
||||||
});
|
});
|
||||||
} finally {
|
} finally {
|
||||||
await closePersistentClient(client);
|
await closePersistentClient(client);
|
||||||
@@ -87,11 +88,11 @@ test.describe('User session data isolation', () => {
|
|||||||
|
|
||||||
await test.step('Alice creates persisted local data and verifies it survives a restart', async () => {
|
await test.step('Alice creates persisted local data and verifies it survives a restart', async () => {
|
||||||
await registerUser(client.page, alice);
|
await registerUser(client.page, alice);
|
||||||
await createServerAndSendMessage(client.page, alice, aliceServerName, aliceMessage);
|
await createServerAndSendMessage(client.page, aliceServerName, aliceMessage);
|
||||||
|
|
||||||
await restartPersistentClient(client, testServer.port);
|
await restartPersistentClient(client, testServer.port);
|
||||||
await openApp(client.page);
|
await openApp(client.page);
|
||||||
await expectSavedRoomAndHistory(client.page, alice, aliceServerName, aliceMessage);
|
await expectSavedRoomAndHistory(client.page, aliceServerName, aliceMessage);
|
||||||
});
|
});
|
||||||
|
|
||||||
await test.step('Bob starts from a blank slate in the same browser profile', async () => {
|
await test.step('Bob starts from a blank slate in the same browser profile', async () => {
|
||||||
@@ -101,11 +102,11 @@ test.describe('User session data isolation', () => {
|
|||||||
});
|
});
|
||||||
|
|
||||||
await test.step('Bob gets only his own saved room and history after a restart', async () => {
|
await test.step('Bob gets only his own saved room and history after a restart', async () => {
|
||||||
await createServerAndSendMessage(client.page, bob, bobServerName, bobMessage);
|
await createServerAndSendMessage(client.page, bobServerName, bobMessage);
|
||||||
|
|
||||||
await restartPersistentClient(client, testServer.port);
|
await restartPersistentClient(client, testServer.port);
|
||||||
await openApp(client.page);
|
await openApp(client.page);
|
||||||
await expectSavedRoomAndHistory(client.page, bob, bobServerName, bobMessage);
|
await expectSavedRoomAndHistory(client.page, bobServerName, bobMessage);
|
||||||
await expectSavedRoomHidden(client.page, aliceServerName);
|
await expectSavedRoomHidden(client.page, aliceServerName);
|
||||||
});
|
});
|
||||||
|
|
||||||
@@ -116,7 +117,7 @@ test.describe('User session data isolation', () => {
|
|||||||
|
|
||||||
await expectSavedRoomVisible(client.page, aliceServerName);
|
await expectSavedRoomVisible(client.page, aliceServerName);
|
||||||
await expectSavedRoomHidden(client.page, bobServerName);
|
await expectSavedRoomHidden(client.page, bobServerName);
|
||||||
await expectSavedRoomAndHistory(client.page, alice, aliceServerName, aliceMessage);
|
await expectSavedRoomAndHistory(client.page, aliceServerName, aliceMessage);
|
||||||
});
|
});
|
||||||
} finally {
|
} finally {
|
||||||
await closePersistentClient(client);
|
await closePersistentClient(client);
|
||||||
@@ -169,7 +170,7 @@ async function registerUser(page: Page, user: TestUser): Promise<void> {
|
|||||||
|
|
||||||
await retryTransientNavigation(() => registerPage.goto());
|
await retryTransientNavigation(() => registerPage.goto());
|
||||||
await registerPage.register(user.username, user.displayName, user.password);
|
await registerPage.register(user.username, user.displayName, user.password);
|
||||||
await expect(page).toHaveURL(/\/dashboard/, { timeout: 15_000 });
|
await expect(page).toHaveURL(/\/search/, { timeout: 15_000 });
|
||||||
}
|
}
|
||||||
|
|
||||||
async function loginUser(page: Page, user: TestUser): Promise<void> {
|
async function loginUser(page: Page, user: TestUser): Promise<void> {
|
||||||
@@ -177,7 +178,7 @@ async function loginUser(page: Page, user: TestUser): Promise<void> {
|
|||||||
|
|
||||||
await retryTransientNavigation(() => loginPage.goto());
|
await retryTransientNavigation(() => loginPage.goto());
|
||||||
await loginPage.login(user.username, user.password);
|
await loginPage.login(user.username, user.password);
|
||||||
await expect(page).toHaveURL(/\/(dashboard|room)(\/|$)/, { timeout: 15_000 });
|
await expect(page).toHaveURL(/\/(search|room)(\/|$)/, { timeout: 15_000 });
|
||||||
}
|
}
|
||||||
|
|
||||||
async function logoutUser(page: Page): Promise<void> {
|
async function logoutUser(page: Page): Promise<void> {
|
||||||
@@ -193,63 +194,39 @@ async function logoutUser(page: Page): Promise<void> {
|
|||||||
await expect(loginPage.usernameInput).toBeVisible({ timeout: 10_000 });
|
await expect(loginPage.usernameInput).toBeVisible({ timeout: 10_000 });
|
||||||
}
|
}
|
||||||
|
|
||||||
async function createServerAndSendMessage(page: Page, user: TestUser, serverName: string, messageText: string): Promise<void> {
|
async function createServerAndSendMessage(page: Page, serverName: string, messageText: string): Promise<void> {
|
||||||
const searchPage = new ServerSearchPage(page);
|
const searchPage = new ServerSearchPage(page);
|
||||||
const messagesPage = new ChatMessagesPage(page);
|
const messagesPage = new ChatMessagesPage(page);
|
||||||
|
|
||||||
await loginIfNeeded(page, user);
|
await searchPage.createServer(serverName, {
|
||||||
await ensureCurrentUserScope(page, user);
|
description: `User session isolation coverage for ${serverName}`
|
||||||
await page.goto('/create-server', { waitUntil: 'domcontentloaded' });
|
});
|
||||||
|
|
||||||
if (await waitForLoginForm(page, 5_000)) {
|
|
||||||
await loginUser(page, user);
|
|
||||||
await page.goto('/create-server', { waitUntil: 'domcontentloaded' });
|
|
||||||
}
|
|
||||||
|
|
||||||
await expect(searchPage.serverNameInput).toBeVisible({ timeout: 10_000 });
|
|
||||||
await searchPage.serverNameInput.fill(serverName);
|
|
||||||
await searchPage.serverDescriptionInput.fill(`User session isolation coverage for ${serverName}`);
|
|
||||||
await searchPage.createSubmitButton.click();
|
|
||||||
|
|
||||||
await expect(page).toHaveURL(/\/room\//, { timeout: 15_000 });
|
await expect(page).toHaveURL(/\/room\//, { timeout: 15_000 });
|
||||||
|
|
||||||
await messagesPage.sendMessage(messageText);
|
await messagesPage.sendMessage(messageText);
|
||||||
await expect(messagesPage.getMessageItemByText(messageText)).toBeVisible({ timeout: 20_000 });
|
await expect(messagesPage.getMessageItemByText(messageText)).toBeVisible({ timeout: 20_000 });
|
||||||
await expectMessagePersistedInIndexedDb(page, messageText);
|
|
||||||
}
|
}
|
||||||
|
|
||||||
async function expectSavedRoomAndHistory(page: Page, user: TestUser, roomName: string, messageText: string): Promise<void> {
|
async function expectSavedRoomAndHistory(page: Page, roomName: string, messageText: string): Promise<void> {
|
||||||
if (await waitForVisibleText(page, messageText, 5_000)) {
|
const railRoomButton = getRailSavedRoomButton(page, roomName);
|
||||||
return;
|
const messagesPage = new ChatMessagesPage(page);
|
||||||
}
|
|
||||||
|
|
||||||
if (await new LoginPage(page).usernameInput.isVisible().catch(() => false)) {
|
await expect(railRoomButton).toBeVisible({ timeout: 20_000 });
|
||||||
await loginUser(page, user);
|
await page.goto('/search', { waitUntil: 'domcontentloaded' });
|
||||||
}
|
const searchRoomButton = getSearchSavedRoomButton(page, roomName);
|
||||||
|
|
||||||
await expectMessagePersistedInIndexedDb(page, messageText);
|
await expect(searchRoomButton).toBeVisible({ timeout: 20_000 });
|
||||||
|
await searchRoomButton.click();
|
||||||
const persistedRoomId = await getPersistedRoomIdForMessage(page, messageText);
|
|
||||||
|
|
||||||
if (persistedRoomId) {
|
|
||||||
await openPersistedRoomById(page, user, persistedRoomId);
|
|
||||||
await expect(page.getByText(messageText, { exact: false })).toBeVisible({ timeout: 20_000 });
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
|
|
||||||
if (await openSavedRoomFromRail(page, roomName)) {
|
|
||||||
await expect(page.getByText(messageText, { exact: false })).toBeVisible({ timeout: 20_000 });
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
|
|
||||||
await joinServerFromSearchAfterLogin(page, user, roomName);
|
|
||||||
await expect(page).toHaveURL(/\/room\//, { timeout: 20_000 });
|
await expect(page).toHaveURL(/\/room\//, { timeout: 20_000 });
|
||||||
await expect(page.getByText(messageText, { exact: false })).toBeVisible({ timeout: 20_000 });
|
await expect(messagesPage.getMessageItemByText(messageText)).toBeVisible({ timeout: 20_000 });
|
||||||
}
|
}
|
||||||
|
|
||||||
async function expectBlankSlate(page: Page, hiddenRoomNames: string[]): Promise<void> {
|
async function expectBlankSlate(page: Page, hiddenRoomNames: string[]): Promise<void> {
|
||||||
await page.goto('/servers', { waitUntil: 'domcontentloaded' });
|
const searchPage = new ServerSearchPage(page);
|
||||||
await expect(page.locator('app-server-browser')).toBeVisible({ timeout: 15_000 });
|
|
||||||
|
await expect(page).toHaveURL(/\/search/, { timeout: 15_000 });
|
||||||
|
await expect(searchPage.createServerButton).toBeVisible({ timeout: 15_000 });
|
||||||
|
|
||||||
for (const roomName of hiddenRoomNames) {
|
for (const roomName of hiddenRoomNames) {
|
||||||
await expectSavedRoomHidden(page, roomName);
|
await expectSavedRoomHidden(page, roomName);
|
||||||
@@ -257,243 +234,27 @@ async function expectBlankSlate(page: Page, hiddenRoomNames: string[]): Promise<
|
|||||||
}
|
}
|
||||||
|
|
||||||
async function expectSavedRoomVisible(page: Page, roomName: string): Promise<void> {
|
async function expectSavedRoomVisible(page: Page, roomName: string): Promise<void> {
|
||||||
if (await page.getByText(roomName, { exact: false }).first()
|
await expect(getRailSavedRoomButton(page, roomName)).toBeVisible({ timeout: 20_000 });
|
||||||
.isVisible()
|
await page.goto('/search', { waitUntil: 'domcontentloaded' });
|
||||||
.catch(() => false)) {
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
|
|
||||||
await page.goto('/servers', { waitUntil: 'domcontentloaded' });
|
|
||||||
await expect(getSearchSavedRoomButton(page, roomName)).toBeVisible({ timeout: 20_000 });
|
await expect(getSearchSavedRoomButton(page, roomName)).toBeVisible({ timeout: 20_000 });
|
||||||
}
|
}
|
||||||
|
|
||||||
async function expectSavedRoomHidden(page: Page, roomName: string): Promise<void> {
|
async function expectSavedRoomHidden(page: Page, roomName: string): Promise<void> {
|
||||||
if (!page.url().includes('/servers')) {
|
await expect(getRailSavedRoomButton(page, roomName)).toHaveCount(0);
|
||||||
await page.goto('/servers', { waitUntil: 'domcontentloaded' });
|
|
||||||
|
if (!page.url().includes('/search')) {
|
||||||
|
await page.goto('/search', { waitUntil: 'domcontentloaded' });
|
||||||
}
|
}
|
||||||
|
|
||||||
await expect(getSearchSavedRoomButton(page, roomName)).toHaveCount(0);
|
await expect(getSearchSavedRoomButton(page, roomName)).toHaveCount(0);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
function getRailSavedRoomButton(page: Page, roomName: string) {
|
||||||
|
return page.locator(`button[title="${roomName}"]`).first();
|
||||||
|
}
|
||||||
|
|
||||||
function getSearchSavedRoomButton(page: Page, roomName: string) {
|
function getSearchSavedRoomButton(page: Page, roomName: string) {
|
||||||
return page.locator('app-server-browser').getByRole('button', { name: roomName, exact: true });
|
return page.locator('app-server-search').getByRole('button', { name: roomName, exact: true });
|
||||||
}
|
|
||||||
|
|
||||||
async function openSavedRoomFromRail(page: Page, roomName: string): Promise<boolean> {
|
|
||||||
try {
|
|
||||||
await expect(page.locator('app-servers-rail')).toBeVisible({ timeout: 10_000 });
|
|
||||||
const clicked = await page.locator('app-servers-rail button').evaluateAll((buttons, expectedName) => {
|
|
||||||
const expectedPrefix = expectedName.slice(0, 24);
|
|
||||||
const button = buttons.find((candidate) => {
|
|
||||||
const title = (candidate as HTMLButtonElement).title;
|
|
||||||
|
|
||||||
return title === expectedName || title.startsWith(expectedPrefix);
|
|
||||||
}) as HTMLButtonElement | undefined;
|
|
||||||
|
|
||||||
button?.click();
|
|
||||||
return !!button;
|
|
||||||
}, roomName);
|
|
||||||
|
|
||||||
if (!clicked) {
|
|
||||||
return await openSavedRoomFromDashboard(page, roomName);
|
|
||||||
}
|
|
||||||
|
|
||||||
await expect(page).toHaveURL(/\/room\//, { timeout: 20_000 });
|
|
||||||
return true;
|
|
||||||
} catch {
|
|
||||||
return await openSavedRoomFromDashboard(page, roomName);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
async function openSavedRoomFromDashboard(page: Page, roomName: string): Promise<boolean> {
|
|
||||||
const roomNamePattern = new RegExp(escapeRegExp(roomName.slice(0, 24)));
|
|
||||||
const roomButton = page.getByRole('button', { name: roomNamePattern }).first();
|
|
||||||
|
|
||||||
try {
|
|
||||||
await expect(roomButton).toBeVisible({ timeout: 10_000 });
|
|
||||||
await roomButton.click();
|
|
||||||
await expect(page).toHaveURL(/\/room\//, { timeout: 20_000 });
|
|
||||||
return true;
|
|
||||||
} catch {
|
|
||||||
return await joinVisibleServerFromDashboard(page, roomNamePattern);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
async function joinVisibleServerFromDashboard(page: Page, roomNamePattern: RegExp): Promise<boolean> {
|
|
||||||
const serverRow = page.locator('div', { hasText: roomNamePattern }).filter({
|
|
||||||
has: page.getByRole('button', { name: 'Join' })
|
|
||||||
})
|
|
||||||
.last();
|
|
||||||
const joinButton = serverRow.getByRole('button', { name: 'Join' });
|
|
||||||
|
|
||||||
try {
|
|
||||||
await expect(joinButton).toBeVisible({ timeout: 10_000 });
|
|
||||||
await joinButton.click();
|
|
||||||
await expect(page).toHaveURL(/\/room\//, { timeout: 20_000 });
|
|
||||||
return true;
|
|
||||||
} catch {
|
|
||||||
return false;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
async function joinServerFromSearchAfterLogin(page: Page, user: TestUser, roomName: string): Promise<void> {
|
|
||||||
const searchPage = new ServerSearchPage(page);
|
|
||||||
|
|
||||||
await loginIfNeeded(page, user);
|
|
||||||
await searchPage.goto();
|
|
||||||
|
|
||||||
if (!await waitForServerSearch(page, 5_000)) {
|
|
||||||
await loginUser(page, user);
|
|
||||||
await searchPage.goto();
|
|
||||||
}
|
|
||||||
|
|
||||||
await expect(searchPage.searchInput).toBeVisible({ timeout: 15_000 });
|
|
||||||
await searchPage.searchInput.fill(roomName);
|
|
||||||
|
|
||||||
const serverCard = page.locator('div[title]', { hasText: roomName }).first();
|
|
||||||
|
|
||||||
await expect(serverCard).toBeVisible({ timeout: 15_000 });
|
|
||||||
await serverCard.dblclick();
|
|
||||||
}
|
|
||||||
|
|
||||||
async function loginIfNeeded(page: Page, user: TestUser): Promise<void> {
|
|
||||||
const loginPage = new LoginPage(page);
|
|
||||||
|
|
||||||
if (page.url().includes('/login')) {
|
|
||||||
await expect(loginPage.usernameInput).toBeVisible({ timeout: 15_000 });
|
|
||||||
await loginUser(page, user);
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
|
|
||||||
if (await loginPage.usernameInput.isVisible().catch(() => false)) {
|
|
||||||
await loginUser(page, user);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
async function ensureCurrentUserScope(page: Page, user: TestUser): Promise<void> {
|
|
||||||
if (await hasCurrentUserScope(page)) {
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
|
|
||||||
await loginUser(page, user);
|
|
||||||
await expect.poll(() => hasCurrentUserScope(page), { timeout: 10_000 }).toBe(true);
|
|
||||||
}
|
|
||||||
|
|
||||||
async function hasCurrentUserScope(page: Page): Promise<boolean> {
|
|
||||||
return page.evaluate(() => !!localStorage.getItem('metoyou_currentUserId')?.trim());
|
|
||||||
}
|
|
||||||
|
|
||||||
async function openPersistedRoomById(page: Page, user: TestUser, roomId: string): Promise<void> {
|
|
||||||
for (let attempt = 1; attempt <= 3; attempt += 1) {
|
|
||||||
await page.goto(`/room/${roomId}`, { waitUntil: 'domcontentloaded' });
|
|
||||||
|
|
||||||
if (await waitForLoginForm(page, 5_000)) {
|
|
||||||
await loginUser(page, user);
|
|
||||||
continue;
|
|
||||||
}
|
|
||||||
|
|
||||||
await expect(page).toHaveURL(/\/room\//, { timeout: 20_000 });
|
|
||||||
|
|
||||||
if (!await waitForLoginForm(page, 2_000)) {
|
|
||||||
return;
|
|
||||||
}
|
|
||||||
|
|
||||||
await loginUser(page, user);
|
|
||||||
}
|
|
||||||
|
|
||||||
await page.goto(`/room/${roomId}`, { waitUntil: 'domcontentloaded' });
|
|
||||||
await expect(page).toHaveURL(/\/room\//, { timeout: 20_000 });
|
|
||||||
}
|
|
||||||
|
|
||||||
async function waitForLoginForm(page: Page, timeout: number): Promise<boolean> {
|
|
||||||
try {
|
|
||||||
await expect(new LoginPage(page).usernameInput).toBeVisible({ timeout });
|
|
||||||
return true;
|
|
||||||
} catch {
|
|
||||||
return false;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
async function waitForServerSearch(page: Page, timeout: number): Promise<boolean> {
|
|
||||||
try {
|
|
||||||
await expect(new ServerSearchPage(page).searchInput).toBeVisible({ timeout });
|
|
||||||
return true;
|
|
||||||
} catch {
|
|
||||||
return false;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
async function waitForVisibleText(page: Page, text: string, timeout: number): Promise<boolean> {
|
|
||||||
try {
|
|
||||||
await expect(page.getByText(text, { exact: false })).toBeVisible({ timeout });
|
|
||||||
return true;
|
|
||||||
} catch {
|
|
||||||
return false;
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
async function expectMessagePersistedInIndexedDb(page: Page, messageText: string): Promise<void> {
|
|
||||||
await expect.poll(
|
|
||||||
() => getPersistedRoomIdForMessage(page, messageText).then((roomId) => !!roomId),
|
|
||||||
{ timeout: 10_000 }
|
|
||||||
).toBe(true);
|
|
||||||
}
|
|
||||||
|
|
||||||
async function getPersistedRoomIdForMessage(page: Page, messageText: string): Promise<string | null> {
|
|
||||||
return page.evaluate(async (expectedContent) => {
|
|
||||||
const currentUserId = localStorage.getItem('metoyou_currentUserId')?.trim();
|
|
||||||
const preferredDatabaseName = `metoyou::${encodeURIComponent(currentUserId || 'anonymous')}`;
|
|
||||||
const discoveredDatabaseNames = typeof indexedDB.databases === 'function'
|
|
||||||
? (await indexedDB.databases())
|
|
||||||
.map((database) => database.name)
|
|
||||||
.filter((name): name is string => !!name && (name === 'metoyou' || name.startsWith('metoyou::')))
|
|
||||||
: null;
|
|
||||||
const databaseNames = discoveredDatabaseNames ?? [preferredDatabaseName];
|
|
||||||
const remainingDatabaseNames = databaseNames.filter((name) => name !== preferredDatabaseName);
|
|
||||||
const orderedDatabaseNames = databaseNames.includes(preferredDatabaseName)
|
|
||||||
? [preferredDatabaseName].concat(remainingDatabaseNames)
|
|
||||||
: remainingDatabaseNames;
|
|
||||||
|
|
||||||
for (const databaseName of orderedDatabaseNames) {
|
|
||||||
const database = await new Promise<IDBDatabase>((resolve, reject) => {
|
|
||||||
const request = indexedDB.open(databaseName);
|
|
||||||
|
|
||||||
request.onerror = () => reject(request.error);
|
|
||||||
request.onsuccess = () => resolve(request.result);
|
|
||||||
});
|
|
||||||
|
|
||||||
try {
|
|
||||||
if (!database.objectStoreNames.contains('messages')) {
|
|
||||||
continue;
|
|
||||||
}
|
|
||||||
|
|
||||||
const transaction = database.transaction('messages', 'readonly');
|
|
||||||
const request = transaction.objectStore('messages').getAll();
|
|
||||||
const roomId = await new Promise<string | null>((resolve, reject) => {
|
|
||||||
request.onerror = () => reject(request.error);
|
|
||||||
|
|
||||||
request.onsuccess = () => {
|
|
||||||
const match = ((request.result as { content?: string; roomId?: string }[]) ?? [])
|
|
||||||
.find((message) => message.content === expectedContent);
|
|
||||||
|
|
||||||
resolve(match?.roomId ?? null);
|
|
||||||
};
|
|
||||||
});
|
|
||||||
|
|
||||||
if (roomId) {
|
|
||||||
return roomId;
|
|
||||||
}
|
|
||||||
} finally {
|
|
||||||
database.close();
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
return null;
|
|
||||||
}, messageText);
|
|
||||||
}
|
|
||||||
|
|
||||||
function escapeRegExp(value: string): string {
|
|
||||||
return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
|
|
||||||
}
|
}
|
||||||
|
|
||||||
async function retryTransientNavigation<T>(navigate: () => Promise<T>, attempts = 4): Promise<T> {
|
async function retryTransientNavigation<T>(navigate: () => Promise<T>, attempts = 4): Promise<T> {
|
||||||
|
|||||||
@@ -249,7 +249,7 @@ async function createSingleClientChatScenario(createClient: () => Promise<Client
|
|||||||
credentials.password
|
credentials.password
|
||||||
);
|
);
|
||||||
|
|
||||||
await expect(client.page).toHaveURL(/\/dashboard/, { timeout: 15_000 });
|
await expect(client.page).toHaveURL(/\/search/, { timeout: 15_000 });
|
||||||
|
|
||||||
return {
|
return {
|
||||||
client,
|
client,
|
||||||
@@ -288,7 +288,7 @@ async function createChatScenario(createClient: () => Promise<Client>): Promise<
|
|||||||
aliceCredentials.password
|
aliceCredentials.password
|
||||||
);
|
);
|
||||||
|
|
||||||
await expect(alice.page).toHaveURL(/\/dashboard/, { timeout: 15_000 });
|
await expect(alice.page).toHaveURL(/\/search/, { timeout: 15_000 });
|
||||||
|
|
||||||
await bobRegisterPage.goto();
|
await bobRegisterPage.goto();
|
||||||
await bobRegisterPage.register(
|
await bobRegisterPage.register(
|
||||||
@@ -297,7 +297,7 @@ async function createChatScenario(createClient: () => Promise<Client>): Promise<
|
|||||||
bobCredentials.password
|
bobCredentials.password
|
||||||
);
|
);
|
||||||
|
|
||||||
await expect(bob.page).toHaveURL(/\/dashboard/, { timeout: 15_000 });
|
await expect(bob.page).toHaveURL(/\/search/, { timeout: 15_000 });
|
||||||
|
|
||||||
const aliceSearchPage = new ServerSearchPage(alice.page);
|
const aliceSearchPage = new ServerSearchPage(alice.page);
|
||||||
|
|
||||||
|
|||||||
@@ -51,9 +51,9 @@ test.describe('Direct message flow', () => {
|
|||||||
const scenario = await createDmScenario(createClient);
|
const scenario = await createDmScenario(createClient);
|
||||||
|
|
||||||
await disableLastViewedChatResume(scenario.alice.page);
|
await disableLastViewedChatResume(scenario.alice.page);
|
||||||
await scenario.alice.page.goto('/people', { waitUntil: 'domcontentloaded' });
|
await scenario.alice.page.goto('/search', { waitUntil: 'domcontentloaded' });
|
||||||
await expect(scenario.alice.page).toHaveURL(/\/people/, { timeout: 20_000 });
|
await expect(scenario.alice.page).toHaveURL(/\/search/, { timeout: 20_000 });
|
||||||
await expect(scenario.alice.page.locator('app-find-people')).toBeVisible({ timeout: 20_000 });
|
await expect(scenario.alice.page.locator('app-server-search')).toBeVisible({ timeout: 20_000 });
|
||||||
await expect(scenario.alice.page.locator('app-user-search-list')).toBeVisible({ timeout: 20_000 });
|
await expect(scenario.alice.page.locator('app-user-search-list')).toBeVisible({ timeout: 20_000 });
|
||||||
const bobPeopleCard = scenario.alice.page
|
const bobPeopleCard = scenario.alice.page
|
||||||
.locator('app-user-search-list [data-testid$="-' + scenario.bobUserId + '"]', { hasText: 'Bob' })
|
.locator('app-user-search-list [data-testid$="-' + scenario.bobUserId + '"]', { hasText: 'Bob' })
|
||||||
@@ -119,7 +119,7 @@ async function registerUser(page: Page, username: string, displayName: string):
|
|||||||
|
|
||||||
await registerPage.goto();
|
await registerPage.goto();
|
||||||
await registerPage.register(username, displayName, 'TestPass123!');
|
await registerPage.register(username, displayName, 'TestPass123!');
|
||||||
await expect(page).toHaveURL(/\/dashboard/, { timeout: 15_000 });
|
await expect(page).toHaveURL(/\/search/, { timeout: 15_000 });
|
||||||
}
|
}
|
||||||
|
|
||||||
async function openDmFromRoomUserCard(page: Page, displayName: string): Promise<void> {
|
async function openDmFromRoomUserCard(page: Page, displayName: string): Promise<void> {
|
||||||
|
|||||||
@@ -1,6 +1,5 @@
|
|||||||
import {
|
import {
|
||||||
expect,
|
expect,
|
||||||
type BrowserContext,
|
|
||||||
type Locator,
|
type Locator,
|
||||||
type Page
|
type Page
|
||||||
} from '@playwright/test';
|
} from '@playwright/test';
|
||||||
@@ -36,7 +35,6 @@ test.describe('Chat notifications', () => {
|
|||||||
await clearDesktopNotifications(scenario.alice.page);
|
await clearDesktopNotifications(scenario.alice.page);
|
||||||
await scenario.bobRoom.joinTextChannel(scenario.channelName);
|
await scenario.bobRoom.joinTextChannel(scenario.channelName);
|
||||||
await scenario.bobMessages.sendMessage(message);
|
await scenario.bobMessages.sendMessage(message);
|
||||||
await expectUnreadCounts(scenario.alice.page, scenario.serverName, scenario.channelName);
|
|
||||||
});
|
});
|
||||||
|
|
||||||
await test.step('Alice receives a desktop notification with the channel preview', async () => {
|
await test.step('Alice receives a desktop notification with the channel preview', async () => {
|
||||||
@@ -69,7 +67,8 @@ test.describe('Chat notifications', () => {
|
|||||||
});
|
});
|
||||||
|
|
||||||
await test.step('Alice still sees unread badges for the room and channel', async () => {
|
await test.step('Alice still sees unread badges for the room and channel', async () => {
|
||||||
await expectUnreadCounts(scenario.alice.page, scenario.serverName, scenario.channelName);
|
await expect(getUnreadBadge(getSavedRoomButton(scenario.alice.page, scenario.serverName))).toHaveText('1', { timeout: 20_000 });
|
||||||
|
await expect(getUnreadBadge(getTextChannelButton(scenario.alice.page, scenario.channelName))).toHaveText('1', { timeout: 20_000 });
|
||||||
});
|
});
|
||||||
|
|
||||||
await test.step('Alice does not get a muted desktop popup', async () => {
|
await test.step('Alice does not get a muted desktop popup', async () => {
|
||||||
@@ -97,7 +96,7 @@ async function createNotificationScenario(createClient: () => Promise<Client>):
|
|||||||
const alice = await createClient();
|
const alice = await createClient();
|
||||||
const bob = await createClient();
|
const bob = await createClient();
|
||||||
|
|
||||||
await installDesktopNotificationSpy(alice.context);
|
await installDesktopNotificationSpy(alice.page);
|
||||||
|
|
||||||
await registerUser(alice.page, aliceCredentials.username, aliceCredentials.displayName, aliceCredentials.password);
|
await registerUser(alice.page, aliceCredentials.username, aliceCredentials.displayName, aliceCredentials.password);
|
||||||
await registerUser(bob.page, bobCredentials.username, bobCredentials.displayName, bobCredentials.password);
|
await registerUser(bob.page, bobCredentials.username, bobCredentials.displayName, bobCredentials.password);
|
||||||
@@ -141,11 +140,11 @@ async function registerUser(page: Page, username: string, displayName: string, p
|
|||||||
|
|
||||||
await registerPage.goto();
|
await registerPage.goto();
|
||||||
await registerPage.register(username, displayName, password);
|
await registerPage.register(username, displayName, password);
|
||||||
await expect(page).toHaveURL(/\/dashboard/, { timeout: 15_000 });
|
await expect(page).toHaveURL(/\/search/, { timeout: 15_000 });
|
||||||
}
|
}
|
||||||
|
|
||||||
async function installDesktopNotificationSpy(context: BrowserContext): Promise<void> {
|
async function installDesktopNotificationSpy(page: Page): Promise<void> {
|
||||||
await context.addInitScript(() => {
|
await page.addInitScript(() => {
|
||||||
const notifications: DesktopNotificationRecord[] = [];
|
const notifications: DesktopNotificationRecord[] = [];
|
||||||
|
|
||||||
class MockNotification {
|
class MockNotification {
|
||||||
@@ -251,11 +250,6 @@ function getUnreadBadge(container: Locator): Locator {
|
|||||||
return container.locator('span.rounded-full').first();
|
return container.locator('span.rounded-full').first();
|
||||||
}
|
}
|
||||||
|
|
||||||
async function expectUnreadCounts(page: Page, serverName: string, channelName: string): Promise<void> {
|
|
||||||
await expect(getUnreadBadge(getSavedRoomButton(page, serverName))).toHaveText('1', { timeout: 45_000 });
|
|
||||||
await expect(getUnreadBadge(getTextChannelButton(page, channelName))).toHaveText('1', { timeout: 45_000 });
|
|
||||||
}
|
|
||||||
|
|
||||||
function uniqueName(prefix: string): string {
|
function uniqueName(prefix: string): string {
|
||||||
return `${prefix}-${Date.now()}-${Math.random().toString(36)
|
return `${prefix}-${Date.now()}-${Math.random().toString(36)
|
||||||
.slice(2, 8)}`;
|
.slice(2, 8)}`;
|
||||||
|
|||||||
@@ -367,10 +367,11 @@ async function launchPersistentSession(
|
|||||||
});
|
});
|
||||||
|
|
||||||
await installTestServerEndpoint(context, testServerPort);
|
await installTestServerEndpoint(context, testServerPort);
|
||||||
await installWebRTCTracking(context);
|
|
||||||
|
|
||||||
const page = context.pages()[0] ?? await context.newPage();
|
const page = context.pages()[0] ?? await context.newPage();
|
||||||
|
|
||||||
|
await installWebRTCTracking(page);
|
||||||
|
|
||||||
return { context, page };
|
return { context, page };
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -379,7 +380,7 @@ async function registerUser(client: PersistentClient): Promise<void> {
|
|||||||
|
|
||||||
await retryTransientNavigation(() => registerPage.goto());
|
await retryTransientNavigation(() => registerPage.goto());
|
||||||
await registerPage.register(client.user.username, client.user.displayName, client.user.password);
|
await registerPage.register(client.user.username, client.user.displayName, client.user.password);
|
||||||
await expect(client.page).toHaveURL(/\/dashboard/, { timeout: 15_000 });
|
await expect(client.page).toHaveURL(/\/search/, { timeout: 15_000 });
|
||||||
}
|
}
|
||||||
|
|
||||||
async function joinServerFromSearch(page: Page, serverName: string): Promise<void> {
|
async function joinServerFromSearch(page: Page, serverName: string): Promise<void> {
|
||||||
|
|||||||
@@ -142,11 +142,11 @@ test.describe('Server icon sync', () => {
|
|||||||
await test.step('Dave has not joined, but discovery loads the icon through a temporary peer sync', async () => {
|
await test.step('Dave has not joined, but discovery loads the icon through a temporary peer sync', async () => {
|
||||||
await registerUser(dave);
|
await registerUser(dave);
|
||||||
await stripServerIconFromDirectorySearch(dave.page, serverName);
|
await stripServerIconFromDirectorySearch(dave.page, serverName);
|
||||||
await dave.page.goto('/servers', { waitUntil: 'domcontentloaded' });
|
await dave.page.goto('/search', { waitUntil: 'domcontentloaded' });
|
||||||
await new ServerSearchPage(dave.page).searchInput.fill(serverName);
|
await new ServerSearchPage(dave.page).searchInput.fill(serverName);
|
||||||
|
|
||||||
await expectSearchResultIcon(dave.page, serverName, icon.dataUrl);
|
await expectSearchResultIcon(dave.page, serverName, icon.dataUrl);
|
||||||
await expect(dave.page).toHaveURL(/\/servers/);
|
await expect(dave.page).toHaveURL(/\/search/);
|
||||||
});
|
});
|
||||||
} finally {
|
} finally {
|
||||||
await Promise.all(
|
await Promise.all(
|
||||||
@@ -196,10 +196,11 @@ async function launchPersistentSession(userDataDir: string, testServerPort: numb
|
|||||||
});
|
});
|
||||||
|
|
||||||
await installTestServerEndpoint(context, testServerPort);
|
await installTestServerEndpoint(context, testServerPort);
|
||||||
await installWebRTCTracking(context);
|
|
||||||
|
|
||||||
const page = context.pages()[0] ?? (await context.newPage());
|
const page = context.pages()[0] ?? (await context.newPage());
|
||||||
|
|
||||||
|
await installWebRTCTracking(page);
|
||||||
|
|
||||||
return { context, page };
|
return { context, page };
|
||||||
}
|
}
|
||||||
|
|
||||||
@@ -208,7 +209,7 @@ async function registerUser(client: PersistentClient): Promise<void> {
|
|||||||
|
|
||||||
await retryTransientNavigation(() => registerPage.goto());
|
await retryTransientNavigation(() => registerPage.goto());
|
||||||
await registerPage.register(client.user.username, client.user.displayName, client.user.password);
|
await registerPage.register(client.user.username, client.user.displayName, client.user.password);
|
||||||
await expect(client.page).toHaveURL(/\/dashboard/, { timeout: 15_000 });
|
await expect(client.page).toHaveURL(/\/search/, { timeout: 15_000 });
|
||||||
}
|
}
|
||||||
|
|
||||||
async function joinServerFromSearch(page: Page, serverName: string): Promise<void> {
|
async function joinServerFromSearch(page: Page, serverName: string): Promise<void> {
|
||||||
@@ -402,7 +403,7 @@ async function expectRailIcon(page: Page, serverName: string, expectedDataUrl: s
|
|||||||
}
|
}
|
||||||
|
|
||||||
async function expectSearchResultIcon(page: Page, serverName: string, expectedDataUrl: string): Promise<void> {
|
async function expectSearchResultIcon(page: Page, serverName: string, expectedDataUrl: string): Promise<void> {
|
||||||
const serverCard = page.locator('app-server-browser div[title]', { hasText: serverName }).first();
|
const serverCard = page.locator('app-server-search div[title]', { hasText: serverName }).first();
|
||||||
const image = serverCard.locator('[style*="background-image"]').first();
|
const image = serverCard.locator('[style*="background-image"]').first();
|
||||||
|
|
||||||
await expect(serverCard).toBeVisible({ timeout: 20_000 });
|
await expect(serverCard).toBeVisible({ timeout: 20_000 });
|
||||||
|
|||||||
@@ -4,20 +4,13 @@ import {
|
|||||||
test,
|
test,
|
||||||
type Client
|
type Client
|
||||||
} from '../../fixtures/multi-client';
|
} from '../../fixtures/multi-client';
|
||||||
import { openPluginStore } from '../../helpers/app-menu';
|
|
||||||
import {
|
|
||||||
addPluginSource,
|
|
||||||
E2E_PLUGIN_SOURCE_URL,
|
|
||||||
E2E_PLUGIN_TITLE
|
|
||||||
} from '../../helpers/plugin-store';
|
|
||||||
import { installWebRTCTracking } from '../../helpers/webrtc-helpers';
|
|
||||||
import { ChatMessagesPage } from '../../pages/chat-messages.page';
|
import { ChatMessagesPage } from '../../pages/chat-messages.page';
|
||||||
import { ChatRoomPage } from '../../pages/chat-room.page';
|
import { ChatRoomPage } from '../../pages/chat-room.page';
|
||||||
import { RegisterPage } from '../../pages/register.page';
|
import { RegisterPage } from '../../pages/register.page';
|
||||||
import { ServerSearchPage } from '../../pages/server-search.page';
|
import { ServerSearchPage } from '../../pages/server-search.page';
|
||||||
|
|
||||||
const PLUGIN_SOURCE_URL = E2E_PLUGIN_SOURCE_URL;
|
const PLUGIN_SOURCE_URL = 'http://localhost:4200/plugins/e2e-plugin-source.json';
|
||||||
const PLUGIN_TITLE = E2E_PLUGIN_TITLE;
|
const PLUGIN_TITLE = 'E2E All API Plugin';
|
||||||
const EDITED_MESSAGE = 'Plugin API edited message';
|
const EDITED_MESSAGE = 'Plugin API edited message';
|
||||||
const ORIGINAL_MESSAGE = 'Plugin API original message';
|
const ORIGINAL_MESSAGE = 'Plugin API original message';
|
||||||
const DELETED_MESSAGE = 'Plugin API deleted message';
|
const DELETED_MESSAGE = 'Plugin API deleted message';
|
||||||
@@ -94,9 +87,6 @@ async function createPluginApiScenario(createClient: () => Promise<Client>): Pro
|
|||||||
const alice = await createClient();
|
const alice = await createClient();
|
||||||
const bob = await createClient();
|
const bob = await createClient();
|
||||||
|
|
||||||
await installWebRTCTracking(alice.page);
|
|
||||||
await installWebRTCTracking(bob.page);
|
|
||||||
|
|
||||||
await registerUser(alice.page, `alice_${suffix}`, 'Alice');
|
await registerUser(alice.page, `alice_${suffix}`, 'Alice');
|
||||||
await registerUser(bob.page, `bob_${suffix}`, 'Bob');
|
await registerUser(bob.page, `bob_${suffix}`, 'Bob');
|
||||||
|
|
||||||
@@ -108,10 +98,13 @@ async function createPluginApiScenario(createClient: () => Promise<Client>): Pro
|
|||||||
const aliceRoom = new ChatRoomPage(alice.page);
|
const aliceRoom = new ChatRoomPage(alice.page);
|
||||||
|
|
||||||
await aliceRoom.ensureVoiceChannelExists(VOICE_CHANNEL);
|
await aliceRoom.ensureVoiceChannelExists(VOICE_CHANNEL);
|
||||||
|
await installGrantAndActivatePlugin(alice.page, true);
|
||||||
|
await closeSettingsModal(alice.page);
|
||||||
|
await expect(soundboardComposerButton(alice.page)).toBeVisible({ timeout: 20_000 });
|
||||||
|
|
||||||
const bobSearch = new ServerSearchPage(bob.page);
|
const bobSearch = new ServerSearchPage(bob.page);
|
||||||
|
|
||||||
await bobSearch.joinServerFromSearch(serverName);
|
await bobSearch.joinServerFromSearch(serverName, { acceptPluginDownloads: true });
|
||||||
await expect(bob.page).toHaveURL(/\/room\//, { timeout: 30_000 });
|
await expect(bob.page).toHaveURL(/\/room\//, { timeout: 30_000 });
|
||||||
|
|
||||||
const bobRoom = new ChatRoomPage(bob.page);
|
const bobRoom = new ChatRoomPage(bob.page);
|
||||||
@@ -120,9 +113,6 @@ async function createPluginApiScenario(createClient: () => Promise<Client>): Pro
|
|||||||
await bobRoom.joinVoiceChannel(VOICE_CHANNEL);
|
await bobRoom.joinVoiceChannel(VOICE_CHANNEL);
|
||||||
await expect(aliceRoom.voiceControls).toBeVisible({ timeout: 30_000 });
|
await expect(aliceRoom.voiceControls).toBeVisible({ timeout: 30_000 });
|
||||||
await expect(bobRoom.voiceControls).toBeVisible({ timeout: 30_000 });
|
await expect(bobRoom.voiceControls).toBeVisible({ timeout: 30_000 });
|
||||||
await installGrantAndActivatePlugin(alice.page, true);
|
|
||||||
await closeSettingsModal(alice.page);
|
|
||||||
await expect(soundboardComposerButton(alice.page)).toBeVisible({ timeout: 20_000 });
|
|
||||||
|
|
||||||
const aliceMessages = new ChatMessagesPage(alice.page);
|
const aliceMessages = new ChatMessagesPage(alice.page);
|
||||||
const bobMessages = new ChatMessagesPage(bob.page);
|
const bobMessages = new ChatMessagesPage(bob.page);
|
||||||
@@ -147,18 +137,19 @@ async function registerUser(page: Page, username: string, displayName: string):
|
|||||||
|
|
||||||
await registerPage.goto();
|
await registerPage.goto();
|
||||||
await registerPage.register(username, displayName, 'TestPass123!');
|
await registerPage.register(username, displayName, 'TestPass123!');
|
||||||
await expect(page).toHaveURL(/\/dashboard/, { timeout: 30_000 });
|
await expect(page).toHaveURL(/\/search/, { timeout: 30_000 });
|
||||||
}
|
}
|
||||||
|
|
||||||
async function installGrantAndActivatePlugin(page: Page, installFromStore: boolean): Promise<void> {
|
async function installGrantAndActivatePlugin(page: Page, installFromStore: boolean): Promise<void> {
|
||||||
await openPluginStore(page);
|
await page.getByRole('button', { name: 'Plugin Store' }).click();
|
||||||
|
await expect(page).toHaveURL(/\/plugin-store/, { timeout: 20_000 });
|
||||||
await expect(page.getByTestId('plugin-store-page')).toBeVisible({ timeout: 20_000 });
|
await expect(page.getByTestId('plugin-store-page')).toBeVisible({ timeout: 20_000 });
|
||||||
|
|
||||||
if (installFromStore) {
|
if (installFromStore) {
|
||||||
await addPluginSource(page, PLUGIN_SOURCE_URL);
|
await page.getByLabel('Plugin source manifest URL').fill(PLUGIN_SOURCE_URL);
|
||||||
await page.locator('article', { hasText: PLUGIN_TITLE }).getByRole('button', { exact: true, name: /^(Install|Install to Server)$/ })
|
await page.getByRole('button', { name: 'Add Source' }).click();
|
||||||
.click();
|
await expect(page.getByRole('heading', { name: PLUGIN_TITLE })).toBeVisible({ timeout: 20_000 });
|
||||||
|
await page.locator('article', { hasText: PLUGIN_TITLE }).getByRole('button', { exact: true, name: /^(Install|Install to Server)$/ }).click();
|
||||||
await expect(page.getByRole('dialog', { name: PLUGIN_TITLE })).toBeVisible({ timeout: 10_000 });
|
await expect(page.getByRole('dialog', { name: PLUGIN_TITLE })).toBeVisible({ timeout: 10_000 });
|
||||||
await page.getByRole('button', { name: 'Install and Activate' }).click();
|
await page.getByRole('button', { name: 'Install and Activate' }).click();
|
||||||
await expect(page.locator('article', { hasText: PLUGIN_TITLE }).getByText('Installed')).toBeVisible({ timeout: 20_000 });
|
await expect(page.locator('article', { hasText: PLUGIN_TITLE }).getByText('Installed')).toBeVisible({ timeout: 20_000 });
|
||||||
|
|||||||
@@ -1,7 +1,4 @@
|
|||||||
import { expect, test } from '../../fixtures/multi-client';
|
import { expect, test } from '../../fixtures/multi-client';
|
||||||
import { openPluginStore } from '../../helpers/app-menu';
|
|
||||||
import { expectDashboardReady } from '../../helpers/dashboard';
|
|
||||||
import { addPluginSource } from '../../helpers/plugin-store';
|
|
||||||
import { RegisterPage } from '../../pages/register.page';
|
import { RegisterPage } from '../../pages/register.page';
|
||||||
import { ServerSearchPage } from '../../pages/server-search.page';
|
import { ServerSearchPage } from '../../pages/server-search.page';
|
||||||
|
|
||||||
@@ -18,7 +15,7 @@ test.describe('Plugin manager UI', () => {
|
|||||||
await test.step('Register user and create server context', async () => {
|
await test.step('Register user and create server context', async () => {
|
||||||
await register.goto();
|
await register.goto();
|
||||||
await register.register(`plugin_${suffix}`, 'Plugin Tester', 'TestPass123!');
|
await register.register(`plugin_${suffix}`, 'Plugin Tester', 'TestPass123!');
|
||||||
await expectDashboardReady(page);
|
await expect(page.getByPlaceholder('Search servers and users...')).toBeVisible({ timeout: 30_000 });
|
||||||
await search.createServer(`Plugin API Server ${suffix}`, {
|
await search.createServer(`Plugin API Server ${suffix}`, {
|
||||||
description: 'Plugin manager UI E2E coverage'
|
description: 'Plugin manager UI E2E coverage'
|
||||||
});
|
});
|
||||||
@@ -26,13 +23,16 @@ test.describe('Plugin manager UI', () => {
|
|||||||
await expect(page).toHaveURL(/\/room\//, { timeout: 30_000 });
|
await expect(page).toHaveURL(/\/room\//, { timeout: 30_000 });
|
||||||
});
|
});
|
||||||
|
|
||||||
await test.step('Open Plugin Store from the title-bar menu', async () => {
|
await test.step('Open visible Plugin Store button', async () => {
|
||||||
await openPluginStore(page);
|
await page.getByRole('button', { name: 'Plugin Store' }).click();
|
||||||
|
await expect(page).toHaveURL(/\/plugin-store/, { timeout: 10_000 });
|
||||||
await expect(page.getByTestId('plugin-store-page')).toBeVisible({ timeout: 10_000 });
|
await expect(page.getByTestId('plugin-store-page')).toBeVisible({ timeout: 10_000 });
|
||||||
});
|
});
|
||||||
|
|
||||||
await test.step('Install fixture plugin from source manifest', async () => {
|
await test.step('Install fixture plugin from source manifest', async () => {
|
||||||
await addPluginSource(page);
|
await page.getByLabel('Plugin source manifest URL').fill('http://localhost:4200/plugins/e2e-plugin-source.json');
|
||||||
|
await page.getByRole('button', { name: 'Add Source' }).click();
|
||||||
|
await expect(page.getByRole('heading', { name: 'E2E All API Plugin' })).toBeVisible({ timeout: 15_000 });
|
||||||
const pluginCard = page.locator('article', { hasText: 'E2E All API Plugin' });
|
const pluginCard = page.locator('article', { hasText: 'E2E All API Plugin' });
|
||||||
|
|
||||||
await pluginCard.getByRole('button', { name: 'Readme' }).click();
|
await pluginCard.getByRole('button', { name: 'Readme' }).click();
|
||||||
|
|||||||
@@ -1,11 +1,6 @@
|
|||||||
import type { APIRequestContext, APIResponse } from '@playwright/test';
|
import type { APIRequestContext, APIResponse } from '@playwright/test';
|
||||||
import WebSocket from 'ws';
|
import WebSocket from 'ws';
|
||||||
import { expect, test } from '../../fixtures/multi-client';
|
import { expect, test } from '../../fixtures/multi-client';
|
||||||
import {
|
|
||||||
authHeaders,
|
|
||||||
registerTestUser,
|
|
||||||
type AuthSession
|
|
||||||
} from '../../helpers/auth-api';
|
|
||||||
import {
|
import {
|
||||||
getPluginApiTestEvent,
|
getPluginApiTestEvent,
|
||||||
readPluginApiTestManifest,
|
readPluginApiTestManifest,
|
||||||
@@ -14,6 +9,8 @@ import {
|
|||||||
TEST_PLUGIN_RELAY_EVENT
|
TEST_PLUGIN_RELAY_EVENT
|
||||||
} from '../../helpers/plugin-api-test-fixture';
|
} from '../../helpers/plugin-api-test-fixture';
|
||||||
|
|
||||||
|
const OWNER_USER_ID = 'plugin-api-owner';
|
||||||
|
|
||||||
interface CreatedServerResponse {
|
interface CreatedServerResponse {
|
||||||
id: string;
|
id: string;
|
||||||
}
|
}
|
||||||
@@ -57,25 +54,10 @@ interface TestSocket {
|
|||||||
test.describe('Plugin support API', () => {
|
test.describe('Plugin support API', () => {
|
||||||
test('covers plugin requirement, event, data, and websocket APIs with the fixture plugin', async ({ request, testServer }) => {
|
test('covers plugin requirement, event, data, and websocket APIs with the fixture plugin', async ({ request, testServer }) => {
|
||||||
const manifest = await readPluginApiTestManifest();
|
const manifest = await readPluginApiTestManifest();
|
||||||
const owner = await registerTestUser(
|
const server = await createServer(request, testServer.url, `Plugin API ${Date.now()}`);
|
||||||
request,
|
|
||||||
testServer.url,
|
|
||||||
`plugin-owner-${Date.now()}`,
|
|
||||||
'TestPass123!',
|
|
||||||
'Plugin Owner'
|
|
||||||
);
|
|
||||||
const peer = await registerTestUser(
|
|
||||||
request,
|
|
||||||
testServer.url,
|
|
||||||
`plugin-peer-${Date.now()}`,
|
|
||||||
'TestPass123!',
|
|
||||||
'Plugin Peer'
|
|
||||||
);
|
|
||||||
const server = await createServer(request, testServer.url, owner, `Plugin API ${Date.now()}`);
|
|
||||||
const relayEvent = getPluginApiTestEvent(manifest, TEST_PLUGIN_RELAY_EVENT);
|
const relayEvent = getPluginApiTestEvent(manifest, TEST_PLUGIN_RELAY_EVENT);
|
||||||
const p2pEvent = getPluginApiTestEvent(manifest, TEST_PLUGIN_P2P_EVENT);
|
const p2pEvent = getPluginApiTestEvent(manifest, TEST_PLUGIN_P2P_EVENT);
|
||||||
const pluginsApi = `${testServer.url}/api/servers/${encodeURIComponent(server.id)}/plugins`;
|
const pluginsApi = `${testServer.url}/api/servers/${encodeURIComponent(server.id)}/plugins`;
|
||||||
const ownerHeaders = authHeaders(owner.token);
|
|
||||||
|
|
||||||
await test.step('Initial snapshot is empty', async () => {
|
await test.step('Initial snapshot is empty', async () => {
|
||||||
const snapshot = await expectJson<PluginSnapshotResponse>(await request.get(pluginsApi));
|
const snapshot = await expectJson<PluginSnapshotResponse>(await request.get(pluginsApi));
|
||||||
@@ -89,8 +71,8 @@ test.describe('Plugin support API', () => {
|
|||||||
|
|
||||||
await test.step('Requirement API enforces server management permission', async () => {
|
await test.step('Requirement API enforces server management permission', async () => {
|
||||||
const response = await request.put(`${pluginsApi}/${TEST_PLUGIN_ID}/requirement`, {
|
const response = await request.put(`${pluginsApi}/${TEST_PLUGIN_ID}/requirement`, {
|
||||||
headers: authHeaders(peer.token),
|
|
||||||
data: {
|
data: {
|
||||||
|
actorUserId: 'not-the-owner',
|
||||||
status: 'required'
|
status: 'required'
|
||||||
}
|
}
|
||||||
});
|
});
|
||||||
@@ -101,8 +83,8 @@ test.describe('Plugin support API', () => {
|
|||||||
|
|
||||||
await test.step('Requirement and event definition APIs persist the test plugin contract', async () => {
|
await test.step('Requirement and event definition APIs persist the test plugin contract', async () => {
|
||||||
const requirement = await expectJson<PluginRequirementResponse>(await request.put(`${pluginsApi}/${TEST_PLUGIN_ID}/requirement`, {
|
const requirement = await expectJson<PluginRequirementResponse>(await request.put(`${pluginsApi}/${TEST_PLUGIN_ID}/requirement`, {
|
||||||
headers: ownerHeaders,
|
|
||||||
data: {
|
data: {
|
||||||
|
actorUserId: OWNER_USER_ID,
|
||||||
reason: manifest.description,
|
reason: manifest.description,
|
||||||
status: 'required',
|
status: 'required',
|
||||||
versionRange: `^${manifest.version}`
|
versionRange: `^${manifest.version}`
|
||||||
@@ -116,8 +98,8 @@ test.describe('Plugin support API', () => {
|
|||||||
versionRange: `^${manifest.version}`
|
versionRange: `^${manifest.version}`
|
||||||
}));
|
}));
|
||||||
|
|
||||||
const relayDefinition = await upsertEventDefinition(request, pluginsApi, ownerHeaders, relayEvent);
|
const relayDefinition = await upsertEventDefinition(request, pluginsApi, relayEvent);
|
||||||
const p2pDefinition = await upsertEventDefinition(request, pluginsApi, ownerHeaders, p2pEvent);
|
const p2pDefinition = await upsertEventDefinition(request, pluginsApi, p2pEvent);
|
||||||
|
|
||||||
expect(relayDefinition.eventDefinition).toEqual(expect.objectContaining({
|
expect(relayDefinition.eventDefinition).toEqual(expect.objectContaining({
|
||||||
direction: 'serverRelay',
|
direction: 'serverRelay',
|
||||||
@@ -141,8 +123,8 @@ test.describe('Plugin support API', () => {
|
|||||||
|
|
||||||
await test.step('Plugin data API refuses arbitrary server persistence', async () => {
|
await test.step('Plugin data API refuses arbitrary server persistence', async () => {
|
||||||
const stored = await expectJson<{ errorCode: string }>(await request.put(`${pluginsApi}/${TEST_PLUGIN_ID}/data/settings`, {
|
const stored = await expectJson<{ errorCode: string }>(await request.put(`${pluginsApi}/${TEST_PLUGIN_ID}/data/settings`, {
|
||||||
headers: ownerHeaders,
|
|
||||||
data: {
|
data: {
|
||||||
|
actorUserId: OWNER_USER_ID,
|
||||||
schemaVersion: 1,
|
schemaVersion: 1,
|
||||||
scope: 'server',
|
scope: 'server',
|
||||||
value: {
|
value: {
|
||||||
@@ -158,15 +140,15 @@ test.describe('Plugin support API', () => {
|
|||||||
params: {
|
params: {
|
||||||
key: 'settings',
|
key: 'settings',
|
||||||
scope: 'server',
|
scope: 'server',
|
||||||
userId: owner.id
|
userId: OWNER_USER_ID
|
||||||
}
|
}
|
||||||
}), 410);
|
}), 410);
|
||||||
|
|
||||||
expect(listed.errorCode).toBe('PLUGIN_DATA_DISABLED');
|
expect(listed.errorCode).toBe('PLUGIN_DATA_DISABLED');
|
||||||
|
|
||||||
const afterDelete = await expectJson<{ errorCode: string }>(await request.delete(`${pluginsApi}/${TEST_PLUGIN_ID}/data/settings`, {
|
const afterDelete = await expectJson<{ errorCode: string }>(await request.delete(`${pluginsApi}/${TEST_PLUGIN_ID}/data/settings`, {
|
||||||
headers: ownerHeaders,
|
|
||||||
data: {
|
data: {
|
||||||
|
actorUserId: OWNER_USER_ID,
|
||||||
scope: 'server'
|
scope: 'server'
|
||||||
}
|
}
|
||||||
}), 410);
|
}), 410);
|
||||||
@@ -179,8 +161,8 @@ test.describe('Plugin support API', () => {
|
|||||||
const bob = await openTestSocket(testServer.url);
|
const bob = await openTestSocket(testServer.url);
|
||||||
|
|
||||||
try {
|
try {
|
||||||
await identifySocket(alice, owner.token, 'Plugin Owner');
|
alice.send({ type: 'identify', oderId: OWNER_USER_ID, displayName: 'Plugin Owner' });
|
||||||
await identifySocket(bob, peer.token, 'Plugin Peer');
|
bob.send({ type: 'identify', oderId: 'plugin-api-peer', displayName: 'Plugin Peer' });
|
||||||
alice.send({ type: 'join_server', serverId: server.id });
|
alice.send({ type: 'join_server', serverId: server.id });
|
||||||
bob.send({ type: 'join_server', serverId: server.id });
|
bob.send({ type: 'join_server', serverId: server.id });
|
||||||
|
|
||||||
@@ -211,7 +193,7 @@ test.describe('Plugin support API', () => {
|
|||||||
pluginId: TEST_PLUGIN_ID,
|
pluginId: TEST_PLUGIN_ID,
|
||||||
serverId: server.id,
|
serverId: server.id,
|
||||||
sourcePluginUserId: 'fixture-plugin-user',
|
sourcePluginUserId: 'fixture-plugin-user',
|
||||||
sourceUserId: owner.id
|
sourceUserId: OWNER_USER_ID
|
||||||
}));
|
}));
|
||||||
|
|
||||||
expect(relayedEvent['payload']).toEqual({ message: 'hello from fixture plugin' });
|
expect(relayedEvent['payload']).toEqual({ message: 'hello from fixture plugin' });
|
||||||
@@ -255,15 +237,15 @@ test.describe('Plugin support API', () => {
|
|||||||
|
|
||||||
await test.step('Delete APIs remove event definitions and requirements', async () => {
|
await test.step('Delete APIs remove event definitions and requirements', async () => {
|
||||||
await expectJson<{ ok: boolean }>(await request.delete(`${pluginsApi}/${TEST_PLUGIN_ID}/events/${TEST_PLUGIN_RELAY_EVENT}`, {
|
await expectJson<{ ok: boolean }>(await request.delete(`${pluginsApi}/${TEST_PLUGIN_ID}/events/${TEST_PLUGIN_RELAY_EVENT}`, {
|
||||||
headers: ownerHeaders
|
data: { actorUserId: OWNER_USER_ID }
|
||||||
}));
|
}));
|
||||||
|
|
||||||
await expectJson<{ ok: boolean }>(await request.delete(`${pluginsApi}/${TEST_PLUGIN_ID}/events/${TEST_PLUGIN_P2P_EVENT}`, {
|
await expectJson<{ ok: boolean }>(await request.delete(`${pluginsApi}/${TEST_PLUGIN_ID}/events/${TEST_PLUGIN_P2P_EVENT}`, {
|
||||||
headers: ownerHeaders
|
data: { actorUserId: OWNER_USER_ID }
|
||||||
}));
|
}));
|
||||||
|
|
||||||
await expectJson<{ ok: boolean }>(await request.delete(`${pluginsApi}/${TEST_PLUGIN_ID}/requirement`, {
|
await expectJson<{ ok: boolean }>(await request.delete(`${pluginsApi}/${TEST_PLUGIN_ID}/requirement`, {
|
||||||
headers: ownerHeaders
|
data: { actorUserId: OWNER_USER_ID }
|
||||||
}));
|
}));
|
||||||
|
|
||||||
const snapshot = await expectJson<PluginSnapshotResponse>(await request.get(pluginsApi));
|
const snapshot = await expectJson<PluginSnapshotResponse>(await request.get(pluginsApi));
|
||||||
@@ -277,11 +259,9 @@ test.describe('Plugin support API', () => {
|
|||||||
async function createServer(
|
async function createServer(
|
||||||
request: APIRequestContext,
|
request: APIRequestContext,
|
||||||
baseUrl: string,
|
baseUrl: string,
|
||||||
owner: AuthSession,
|
|
||||||
serverName: string
|
serverName: string
|
||||||
): Promise<CreatedServerResponse> {
|
): Promise<CreatedServerResponse> {
|
||||||
const response = await request.post(`${baseUrl}/api/servers`, {
|
const response = await request.post(`${baseUrl}/api/servers`, {
|
||||||
headers: authHeaders(owner.token),
|
|
||||||
data: {
|
data: {
|
||||||
channels: [
|
channels: [
|
||||||
{
|
{
|
||||||
@@ -295,7 +275,7 @@ async function createServer(
|
|||||||
id: `plugin-api-${Date.now()}`,
|
id: `plugin-api-${Date.now()}`,
|
||||||
isPrivate: false,
|
isPrivate: false,
|
||||||
name: serverName,
|
name: serverName,
|
||||||
ownerId: owner.id,
|
ownerId: OWNER_USER_ID,
|
||||||
ownerPublicKey: 'plugin-api-owner-public-key',
|
ownerPublicKey: 'plugin-api-owner-public-key',
|
||||||
tags: ['plugins']
|
tags: ['plugins']
|
||||||
}
|
}
|
||||||
@@ -307,14 +287,13 @@ async function createServer(
|
|||||||
async function upsertEventDefinition(
|
async function upsertEventDefinition(
|
||||||
request: APIRequestContext,
|
request: APIRequestContext,
|
||||||
pluginsApi: string,
|
pluginsApi: string,
|
||||||
headers: Record<string, string>,
|
|
||||||
eventDefinition: ReturnType<typeof getPluginApiTestEvent>
|
eventDefinition: ReturnType<typeof getPluginApiTestEvent>
|
||||||
): Promise<PluginEventDefinitionResponse> {
|
): Promise<PluginEventDefinitionResponse> {
|
||||||
return await expectJson<PluginEventDefinitionResponse>(await request.put(
|
return await expectJson<PluginEventDefinitionResponse>(await request.put(
|
||||||
`${pluginsApi}/${TEST_PLUGIN_ID}/events/${encodeURIComponent(eventDefinition.eventName)}`,
|
`${pluginsApi}/${TEST_PLUGIN_ID}/events/${encodeURIComponent(eventDefinition.eventName)}`,
|
||||||
{
|
{
|
||||||
headers,
|
|
||||||
data: {
|
data: {
|
||||||
|
actorUserId: OWNER_USER_ID,
|
||||||
direction: eventDefinition.direction,
|
direction: eventDefinition.direction,
|
||||||
maxPayloadBytes: eventDefinition.maxPayloadBytes,
|
maxPayloadBytes: eventDefinition.maxPayloadBytes,
|
||||||
schemaJson: '{"type":"object"}',
|
schemaJson: '{"type":"object"}',
|
||||||
@@ -330,20 +309,6 @@ async function expectJson<T>(response: APIResponse, status = 200): Promise<T> {
|
|||||||
return await response.json() as T;
|
return await response.json() as T;
|
||||||
}
|
}
|
||||||
|
|
||||||
async function identifySocket(socket: TestSocket, token: string, displayName: string): Promise<void> {
|
|
||||||
socket.send({ type: 'identify', token, displayName });
|
|
||||||
|
|
||||||
await new Promise((resolve) => {
|
|
||||||
setTimeout(resolve, 300);
|
|
||||||
});
|
|
||||||
|
|
||||||
const authError = socket.messages.find((message) => message.type === 'auth_error');
|
|
||||||
|
|
||||||
if (authError) {
|
|
||||||
throw new Error(`WebSocket identify failed: ${JSON.stringify(authError)}`);
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
async function openTestSocket(baseUrl: string): Promise<TestSocket> {
|
async function openTestSocket(baseUrl: string): Promise<TestSocket> {
|
||||||
const socketUrl = baseUrl.replace(/^http/, 'ws');
|
const socketUrl = baseUrl.replace(/^http/, 'ws');
|
||||||
const socket = new WebSocket(socketUrl);
|
const socket = new WebSocket(socketUrl);
|
||||||
|
|||||||
@@ -29,14 +29,14 @@ const BOB = { username: `bob_ss_${Date.now()}`, displayName: 'Bob', password: 'T
|
|||||||
const SERVER_NAME = `SS Test ${Date.now()}`;
|
const SERVER_NAME = `SS Test ${Date.now()}`;
|
||||||
const VOICE_CHANNEL = 'General';
|
const VOICE_CHANNEL = 'General';
|
||||||
|
|
||||||
/** Register a user and navigate to /dashboard. */
|
/** Register a user and navigate to /search. */
|
||||||
async function registerUser(page: import('@playwright/test').Page, user: typeof ALICE) {
|
async function registerUser(page: import('@playwright/test').Page, user: typeof ALICE) {
|
||||||
const registerPage = new RegisterPage(page);
|
const registerPage = new RegisterPage(page);
|
||||||
|
|
||||||
await registerPage.goto();
|
await registerPage.goto();
|
||||||
await expect(registerPage.submitButton).toBeVisible();
|
await expect(registerPage.submitButton).toBeVisible();
|
||||||
await registerPage.register(user.username, user.displayName, user.password);
|
await registerPage.register(user.username, user.displayName, user.password);
|
||||||
await expect(page).toHaveURL(/\/dashboard/, { timeout: 15_000 });
|
await expect(page).toHaveURL(/\/search/, { timeout: 15_000 });
|
||||||
}
|
}
|
||||||
|
|
||||||
/** Both users register -> Alice creates server -> Bob joins. */
|
/** Both users register -> Alice creates server -> Bob joins. */
|
||||||
|
|||||||
@@ -1,5 +1,4 @@
|
|||||||
import { test, expect } from '../../fixtures/multi-client';
|
import { test, expect } from '../../fixtures/multi-client';
|
||||||
import { expectDashboardReady } from '../../helpers/dashboard';
|
|
||||||
import { RegisterPage } from '../../pages/register.page';
|
import { RegisterPage } from '../../pages/register.page';
|
||||||
import { ServerSearchPage } from '../../pages/server-search.page';
|
import { ServerSearchPage } from '../../pages/server-search.page';
|
||||||
import { ChatRoomPage } from '../../pages/chat-room.page';
|
import { ChatRoomPage } from '../../pages/chat-room.page';
|
||||||
@@ -89,7 +88,7 @@ test.describe('Connectivity warning', () => {
|
|||||||
|
|
||||||
await register.goto();
|
await register.goto();
|
||||||
await register.register(`alice_${suffix}`, 'Alice', 'TestPass123!');
|
await register.register(`alice_${suffix}`, 'Alice', 'TestPass123!');
|
||||||
await expectDashboardReady(alice.page);
|
await expect(alice.page.getByPlaceholder('Search servers and users...')).toBeVisible({ timeout: 30_000 });
|
||||||
});
|
});
|
||||||
|
|
||||||
await test.step('Register Bob', async () => {
|
await test.step('Register Bob', async () => {
|
||||||
@@ -97,7 +96,7 @@ test.describe('Connectivity warning', () => {
|
|||||||
|
|
||||||
await register.goto();
|
await register.goto();
|
||||||
await register.register(`bob_${suffix}`, 'Bob', 'TestPass123!');
|
await register.register(`bob_${suffix}`, 'Bob', 'TestPass123!');
|
||||||
await expectDashboardReady(bob.page);
|
await expect(bob.page.getByPlaceholder('Search servers and users...')).toBeVisible({ timeout: 30_000 });
|
||||||
});
|
});
|
||||||
|
|
||||||
await test.step('Register Charlie', async () => {
|
await test.step('Register Charlie', async () => {
|
||||||
@@ -105,7 +104,7 @@ test.describe('Connectivity warning', () => {
|
|||||||
|
|
||||||
await register.goto();
|
await register.goto();
|
||||||
await register.register(`charlie_${suffix}`, 'Charlie', 'TestPass123!');
|
await register.register(`charlie_${suffix}`, 'Charlie', 'TestPass123!');
|
||||||
await expectDashboardReady(charlie.page);
|
await expect(charlie.page.getByPlaceholder('Search servers and users...')).toBeVisible({ timeout: 30_000 });
|
||||||
});
|
});
|
||||||
|
|
||||||
// ── Create server and have everyone join ──
|
// ── Create server and have everyone join ──
|
||||||
|
|||||||
@@ -1,6 +1,4 @@
|
|||||||
import { test, expect } from '../../fixtures/multi-client';
|
import { test, expect } from '../../fixtures/multi-client';
|
||||||
import { openSettingsFromMenu } from '../../helpers/app-menu';
|
|
||||||
import { expectDashboardReady } from '../../helpers/dashboard';
|
|
||||||
import { RegisterPage } from '../../pages/register.page';
|
import { RegisterPage } from '../../pages/register.page';
|
||||||
|
|
||||||
test.describe('ICE server settings', () => {
|
test.describe('ICE server settings', () => {
|
||||||
@@ -11,8 +9,8 @@ test.describe('ICE server settings', () => {
|
|||||||
|
|
||||||
await register.goto();
|
await register.goto();
|
||||||
await register.register(`user_${suffix}`, 'IceTestUser', 'TestPass123!');
|
await register.register(`user_${suffix}`, 'IceTestUser', 'TestPass123!');
|
||||||
await expectDashboardReady(page);
|
await expect(page.getByPlaceholder('Search servers and users...')).toBeVisible({ timeout: 30_000 });
|
||||||
await openSettingsFromMenu(page);
|
await page.getByTitle('Settings').click();
|
||||||
await expect(page.getByRole('button', { name: 'Network' })).toBeVisible({ timeout: 10_000 });
|
await expect(page.getByRole('button', { name: 'Network' })).toBeVisible({ timeout: 10_000 });
|
||||||
await page.getByRole('button', { name: 'Network' }).click();
|
await page.getByRole('button', { name: 'Network' }).click();
|
||||||
await expect(page.getByTestId('ice-server-settings')).toBeVisible({ timeout: 10_000 });
|
await expect(page.getByTestId('ice-server-settings')).toBeVisible({ timeout: 10_000 });
|
||||||
@@ -103,7 +101,7 @@ test.describe('ICE server settings', () => {
|
|||||||
await expect(page.getByText('stun:persist-test.example.com:3478')).toBeVisible({ timeout: 5_000 });
|
await expect(page.getByText('stun:persist-test.example.com:3478')).toBeVisible({ timeout: 5_000 });
|
||||||
|
|
||||||
await page.reload({ waitUntil: 'domcontentloaded' });
|
await page.reload({ waitUntil: 'domcontentloaded' });
|
||||||
await openSettingsFromMenu(page);
|
await page.getByTitle('Settings').click();
|
||||||
await expect(page.getByRole('button', { name: 'Network' })).toBeVisible({ timeout: 10_000 });
|
await expect(page.getByRole('button', { name: 'Network' })).toBeVisible({ timeout: 10_000 });
|
||||||
await page.getByRole('button', { name: 'Network' }).click();
|
await page.getByRole('button', { name: 'Network' }).click();
|
||||||
await expect(page.getByText('stun:persist-test.example.com:3478')).toBeVisible({ timeout: 10_000 });
|
await expect(page.getByText('stun:persist-test.example.com:3478')).toBeVisible({ timeout: 10_000 });
|
||||||
|
|||||||
@@ -1,5 +1,4 @@
|
|||||||
import { test, expect } from '../../fixtures/multi-client';
|
import { test, expect } from '../../fixtures/multi-client';
|
||||||
import { expectDashboardReady } from '../../helpers/dashboard';
|
|
||||||
import { RegisterPage } from '../../pages/register.page';
|
import { RegisterPage } from '../../pages/register.page';
|
||||||
import { ServerSearchPage } from '../../pages/server-search.page';
|
import { ServerSearchPage } from '../../pages/server-search.page';
|
||||||
import { ChatRoomPage } from '../../pages/chat-room.page';
|
import { ChatRoomPage } from '../../pages/chat-room.page';
|
||||||
@@ -90,7 +89,7 @@ test.describe('STUN/TURN fallback behaviour', () => {
|
|||||||
|
|
||||||
await register.goto();
|
await register.goto();
|
||||||
await register.register(`alice_${suffix}`, 'Alice', 'TestPass123!');
|
await register.register(`alice_${suffix}`, 'Alice', 'TestPass123!');
|
||||||
await expectDashboardReady(alice.page);
|
await expect(alice.page.getByPlaceholder('Search servers and users...')).toBeVisible({ timeout: 30_000 });
|
||||||
});
|
});
|
||||||
|
|
||||||
await test.step('Register Bob', async () => {
|
await test.step('Register Bob', async () => {
|
||||||
@@ -98,7 +97,7 @@ test.describe('STUN/TURN fallback behaviour', () => {
|
|||||||
|
|
||||||
await register.goto();
|
await register.goto();
|
||||||
await register.register(`bob_${suffix}`, 'Bob', 'TestPass123!');
|
await register.register(`bob_${suffix}`, 'Bob', 'TestPass123!');
|
||||||
await expectDashboardReady(bob.page);
|
await expect(bob.page.getByPlaceholder('Search servers and users...')).toBeVisible({ timeout: 30_000 });
|
||||||
});
|
});
|
||||||
|
|
||||||
await test.step('Alice creates a server', async () => {
|
await test.step('Alice creates a server', async () => {
|
||||||
|
|||||||
@@ -105,7 +105,7 @@ async function createVoiceScenario(
|
|||||||
|
|
||||||
await registerPage.goto();
|
await registerPage.goto();
|
||||||
await registerPage.register(client.username, client.displayName, USER_PASSWORD);
|
await registerPage.register(client.username, client.displayName, USER_PASSWORD);
|
||||||
await expect(client.page).toHaveURL(/\/dashboard/, { timeout: 20_000 });
|
await expect(client.page).toHaveURL(/\/search/, { timeout: 20_000 });
|
||||||
}
|
}
|
||||||
});
|
});
|
||||||
|
|
||||||
|
|||||||
@@ -55,7 +55,7 @@ test.describe('Direct private calls', () => {
|
|||||||
|
|
||||||
await test.step('Alice starts a call from the search people card', async () => {
|
await test.step('Alice starts a call from the search people card', async () => {
|
||||||
await disableLastViewedChatResume(scenario.alice.page);
|
await disableLastViewedChatResume(scenario.alice.page);
|
||||||
await scenario.alice.page.goto('/people', { waitUntil: 'domcontentloaded' });
|
await scenario.alice.page.goto('/search', { waitUntil: 'domcontentloaded' });
|
||||||
await expect(scenario.alice.page.locator('app-user-search-list')).toBeVisible({ timeout: 20_000 });
|
await expect(scenario.alice.page.locator('app-user-search-list')).toBeVisible({ timeout: 20_000 });
|
||||||
|
|
||||||
const bobPeopleCard = scenario.alice.page.locator(`[data-testid="user-card-${scenario.bobUserId}"]`, { hasText: 'Bob' }).first();
|
const bobPeopleCard = scenario.alice.page.locator(`[data-testid="user-card-${scenario.bobUserId}"]`, { hasText: 'Bob' }).first();
|
||||||
@@ -597,12 +597,12 @@ async function registerUser(page: Page, username: string, displayName: string):
|
|||||||
|
|
||||||
await registerPage.goto();
|
await registerPage.goto();
|
||||||
await registerPage.register(username, displayName, USER_PASSWORD);
|
await registerPage.register(username, displayName, USER_PASSWORD);
|
||||||
await expect(page).toHaveURL(/\/dashboard/, { timeout: 20_000 });
|
await expect(page).toHaveURL(/\/search/, { timeout: 20_000 });
|
||||||
}
|
}
|
||||||
|
|
||||||
async function startCallFromSearch(page: Page, userId: string, displayName: string): Promise<void> {
|
async function startCallFromSearch(page: Page, userId: string, displayName: string): Promise<void> {
|
||||||
await disableLastViewedChatResume(page);
|
await disableLastViewedChatResume(page);
|
||||||
await page.goto('/people', { waitUntil: 'domcontentloaded' });
|
await page.goto('/search', { waitUntil: 'domcontentloaded' });
|
||||||
const peopleCard = page.locator(`[data-testid="user-card-${userId}"]`, { hasText: displayName }).first();
|
const peopleCard = page.locator(`[data-testid="user-card-${userId}"]`, { hasText: displayName }).first();
|
||||||
|
|
||||||
await expect(peopleCard).toBeVisible({ timeout: 20_000 });
|
await expect(peopleCard).toBeVisible({ timeout: 20_000 });
|
||||||
@@ -621,9 +621,7 @@ async function answerIncomingCall(page: Page): Promise<void> {
|
|||||||
if (await dialog.isVisible({ timeout: 5_000 }).catch(() => false)) {
|
if (await dialog.isVisible({ timeout: 5_000 }).catch(() => false)) {
|
||||||
await dialog.getByRole('button', { name: 'Answer' }).click();
|
await dialog.getByRole('button', { name: 'Answer' }).click();
|
||||||
} else {
|
} else {
|
||||||
await page.getByRole('button', { name: 'Open private call' }).last()
|
await page.getByRole('button', { name: 'Open private call' }).last().click();
|
||||||
.click();
|
|
||||||
|
|
||||||
await expect(page).toHaveURL(/\/call\//, { timeout: 20_000 });
|
await expect(page).toHaveURL(/\/call\//, { timeout: 20_000 });
|
||||||
|
|
||||||
const joinButton = page.getByRole('button', { name: 'Join call' });
|
const joinButton = page.getByRole('button', { name: 'Join call' });
|
||||||
|
|||||||
@@ -1,8 +1,4 @@
|
|||||||
import {
|
import { expect, type Page } from '@playwright/test';
|
||||||
expect,
|
|
||||||
type APIRequestContext,
|
|
||||||
type Page
|
|
||||||
} from '@playwright/test';
|
|
||||||
import { test, type Client } from '../../fixtures/multi-client';
|
import { test, type Client } from '../../fixtures/multi-client';
|
||||||
import { installTestServerEndpoints, type SeededEndpointInput } from '../../helpers/seed-test-endpoint';
|
import { installTestServerEndpoints, type SeededEndpointInput } from '../../helpers/seed-test-endpoint';
|
||||||
import { startTestServer } from '../../helpers/test-server';
|
import { startTestServer } from '../../helpers/test-server';
|
||||||
@@ -15,11 +11,6 @@ import {
|
|||||||
waitForConnectedPeerCount,
|
waitForConnectedPeerCount,
|
||||||
waitForPeerConnected
|
waitForPeerConnected
|
||||||
} from '../../helpers/webrtc-helpers';
|
} from '../../helpers/webrtc-helpers';
|
||||||
import {
|
|
||||||
authHeaders,
|
|
||||||
readAuthTokenFromPage,
|
|
||||||
registerTestUser
|
|
||||||
} from '../../helpers/auth-api';
|
|
||||||
import { RegisterPage } from '../../pages/register.page';
|
import { RegisterPage } from '../../pages/register.page';
|
||||||
import { ServerSearchPage } from '../../pages/server-search.page';
|
import { ServerSearchPage } from '../../pages/server-search.page';
|
||||||
import { ChatRoomPage } from '../../pages/chat-room.page';
|
import { ChatRoomPage } from '../../pages/chat-room.page';
|
||||||
@@ -113,7 +104,6 @@ function endpointsForGroup(
|
|||||||
test.describe('Mixed signal-config voice', () => {
|
test.describe('Mixed signal-config voice', () => {
|
||||||
test('8 users with different signal configs can voice, mute, deafen, and chat concurrently', async ({
|
test('8 users with different signal configs can voice, mute, deafen, and chat concurrently', async ({
|
||||||
createClient,
|
createClient,
|
||||||
request,
|
|
||||||
testServer
|
testServer
|
||||||
}) => {
|
}) => {
|
||||||
test.setTimeout(720_000);
|
test.setTimeout(720_000);
|
||||||
@@ -146,36 +136,14 @@ test.describe('Mixed signal-config voice', () => {
|
|||||||
await registerPage.goto();
|
await registerPage.goto();
|
||||||
await registerPage.serverSelect.selectOption(registrationEndpointId);
|
await registerPage.serverSelect.selectOption(registrationEndpointId);
|
||||||
await registerPage.register(client.user.username, client.user.displayName, client.user.password);
|
await registerPage.register(client.user.username, client.user.displayName, client.user.password);
|
||||||
await expect(client.page).toHaveURL(/\/dashboard/, { timeout: 20_000 });
|
await expect(client.page).toHaveURL(/\/search/, { timeout: 20_000 });
|
||||||
}
|
}
|
||||||
});
|
});
|
||||||
|
|
||||||
let secondaryRoomId = '';
|
|
||||||
|
|
||||||
// ── Create rooms ────────────────────────────────────────────
|
// ── Create rooms ────────────────────────────────────────────
|
||||||
await test.step('Create voice room on primary and chat room on secondary', async () => {
|
await test.step('Create voice room on primary and chat room on secondary', async () => {
|
||||||
// Use a "both" user (client 0) to create both rooms
|
// Use a "both" user (client 0) to create both rooms
|
||||||
const searchPage = new ServerSearchPage(clients[0].page);
|
const searchPage = new ServerSearchPage(clients[0].page);
|
||||||
const secondarySession = await registerTestUser(
|
|
||||||
request,
|
|
||||||
secondaryServer.url,
|
|
||||||
clients[0].user.username,
|
|
||||||
clients[0].user.password,
|
|
||||||
clients[0].user.displayName
|
|
||||||
);
|
|
||||||
|
|
||||||
await clients[0].page.evaluate(({ serverUrl, token, expiresAt }) => {
|
|
||||||
const storageKey = 'metoyou.authTokens';
|
|
||||||
const store = JSON.parse(localStorage.getItem(storageKey) || '{}') as Record<string, { token: string; expiresAt: number }>;
|
|
||||||
const normalizedUrl = serverUrl.trim().replace(/\/+$/, '');
|
|
||||||
|
|
||||||
store[normalizedUrl] = { token, expiresAt };
|
|
||||||
localStorage.setItem(storageKey, JSON.stringify(store));
|
|
||||||
}, {
|
|
||||||
serverUrl: secondaryServer.url,
|
|
||||||
token: secondarySession.token,
|
|
||||||
expiresAt: secondarySession.expiresAt
|
|
||||||
});
|
|
||||||
|
|
||||||
await searchPage.createServer(VOICE_ROOM_NAME, {
|
await searchPage.createServer(VOICE_ROOM_NAME, {
|
||||||
description: 'Voice room on primary signal',
|
description: 'Voice room on primary signal',
|
||||||
@@ -184,14 +152,12 @@ test.describe('Mixed signal-config voice', () => {
|
|||||||
|
|
||||||
await expect(clients[0].page).toHaveURL(/\/room\//, { timeout: 20_000 });
|
await expect(clients[0].page).toHaveURL(/\/room\//, { timeout: 20_000 });
|
||||||
|
|
||||||
const secondaryRoom = await createServerViaApi(
|
await searchPage.createServer(SECONDARY_ROOM_NAME, {
|
||||||
request,
|
description: 'Chat room on secondary signal',
|
||||||
secondaryServer.url,
|
sourceId: SECONDARY_SIGNAL_ID
|
||||||
secondarySession,
|
});
|
||||||
SECONDARY_ROOM_NAME
|
|
||||||
);
|
|
||||||
|
|
||||||
secondaryRoomId = secondaryRoom.id;
|
await expect(clients[0].page).toHaveURL(/\/room\//, { timeout: 20_000 });
|
||||||
});
|
});
|
||||||
|
|
||||||
// ── Create invite links ─────────────────────────────────────
|
// ── Create invite links ─────────────────────────────────────
|
||||||
@@ -205,33 +171,26 @@ test.describe('Mixed signal-config voice', () => {
|
|||||||
// Navigate to voice room to get its ID
|
// Navigate to voice room to get its ID
|
||||||
await openSavedRoomByName(clients[0].page, VOICE_ROOM_NAME);
|
await openSavedRoomByName(clients[0].page, VOICE_ROOM_NAME);
|
||||||
const primaryRoomId = await getCurrentRoomId(clients[0].page);
|
const primaryRoomId = await getCurrentRoomId(clients[0].page);
|
||||||
|
const userId = await getCurrentUserId(clients[0].page);
|
||||||
|
|
||||||
|
// Navigate to secondary room to get its ID
|
||||||
|
await openSavedRoomByName(clients[0].page, SECONDARY_ROOM_NAME);
|
||||||
|
const secondaryRoomId = await getCurrentRoomId(clients[0].page);
|
||||||
// Create invite for primary room (voice) via API
|
// Create invite for primary room (voice) via API
|
||||||
const primaryToken = await readAuthTokenFromPage(clients[0].page, testServer.url);
|
|
||||||
|
|
||||||
if (!primaryToken) {
|
|
||||||
throw new Error('Missing session token for primary signal invite creation');
|
|
||||||
}
|
|
||||||
|
|
||||||
const primaryInvite = await createInviteViaApi(
|
const primaryInvite = await createInviteViaApi(
|
||||||
testServer.url,
|
testServer.url,
|
||||||
primaryRoomId,
|
primaryRoomId,
|
||||||
primaryToken,
|
userId,
|
||||||
clients[0].user.displayName
|
clients[0].user.displayName
|
||||||
);
|
);
|
||||||
|
|
||||||
primaryRoomInviteUrl = `/invite/${primaryInvite.id}?server=${encodeURIComponent(testServer.url)}`;
|
primaryRoomInviteUrl = `/invite/${primaryInvite.id}?server=${encodeURIComponent(testServer.url)}`;
|
||||||
|
|
||||||
// Create invite for secondary room (chat) via API
|
// Create invite for secondary room (chat) via API
|
||||||
const secondaryToken = await readAuthTokenFromPage(clients[0].page, secondaryServer.url);
|
|
||||||
|
|
||||||
if (!secondaryToken) {
|
|
||||||
throw new Error('Missing session token for secondary signal invite creation');
|
|
||||||
}
|
|
||||||
|
|
||||||
const secondaryInvite = await createInviteViaApi(
|
const secondaryInvite = await createInviteViaApi(
|
||||||
secondaryServer.url,
|
secondaryServer.url,
|
||||||
secondaryRoomId,
|
secondaryRoomId,
|
||||||
secondaryToken,
|
userId,
|
||||||
clients[0].user.displayName
|
clients[0].user.displayName
|
||||||
);
|
);
|
||||||
|
|
||||||
@@ -504,55 +463,17 @@ function buildUsers(): TestUser[] {
|
|||||||
|
|
||||||
// ── API helpers ──────────────────────────────────────────────────────
|
// ── API helpers ──────────────────────────────────────────────────────
|
||||||
|
|
||||||
async function createServerViaApi(
|
|
||||||
request: APIRequestContext,
|
|
||||||
serverBaseUrl: string,
|
|
||||||
owner: { id: string; token: string },
|
|
||||||
serverName: string
|
|
||||||
): Promise<{ id: string }> {
|
|
||||||
const response = await request.post(`${serverBaseUrl}/api/servers`, {
|
|
||||||
headers: authHeaders(owner.token),
|
|
||||||
data: {
|
|
||||||
channels: [
|
|
||||||
{
|
|
||||||
id: 'general-text',
|
|
||||||
name: 'general',
|
|
||||||
position: 0,
|
|
||||||
type: 'text'
|
|
||||||
}
|
|
||||||
],
|
|
||||||
description: `E2E room on ${serverBaseUrl}`,
|
|
||||||
id: `mixed-signal-${Date.now()}-${Math.random()
|
|
||||||
.toString(36)
|
|
||||||
.slice(2, 8)}`,
|
|
||||||
isPrivate: false,
|
|
||||||
name: serverName,
|
|
||||||
ownerId: owner.id,
|
|
||||||
ownerPublicKey: 'mixed-signal-owner-public-key',
|
|
||||||
tags: ['e2e']
|
|
||||||
}
|
|
||||||
});
|
|
||||||
|
|
||||||
if (!response.ok()) {
|
|
||||||
throw new Error(`Failed to create server via API: ${response.status()} ${await response.text()}`);
|
|
||||||
}
|
|
||||||
|
|
||||||
return await response.json() as { id: string };
|
|
||||||
}
|
|
||||||
|
|
||||||
async function createInviteViaApi(
|
async function createInviteViaApi(
|
||||||
serverBaseUrl: string,
|
serverBaseUrl: string,
|
||||||
roomId: string,
|
roomId: string,
|
||||||
authToken: string,
|
userId: string,
|
||||||
displayName: string
|
displayName: string
|
||||||
): Promise<{ id: string }> {
|
): Promise<{ id: string }> {
|
||||||
const response = await fetch(`${serverBaseUrl}/api/servers/${roomId}/invites`, {
|
const response = await fetch(`${serverBaseUrl}/api/servers/${roomId}/invites`, {
|
||||||
method: 'POST',
|
method: 'POST',
|
||||||
headers: {
|
headers: { 'Content-Type': 'application/json' },
|
||||||
'Content-Type': 'application/json',
|
|
||||||
Authorization: `Bearer ${authToken}`
|
|
||||||
},
|
|
||||||
body: JSON.stringify({
|
body: JSON.stringify({
|
||||||
|
requesterUserId: userId,
|
||||||
requesterDisplayName: displayName
|
requesterDisplayName: displayName
|
||||||
})
|
})
|
||||||
});
|
});
|
||||||
@@ -589,6 +510,34 @@ async function getCurrentRoomId(page: Page): Promise<string> {
|
|||||||
});
|
});
|
||||||
}
|
}
|
||||||
|
|
||||||
|
async function getCurrentUserId(page: Page): Promise<string> {
|
||||||
|
return await page.evaluate(() => {
|
||||||
|
interface AngularDebugApi {
|
||||||
|
getComponent: (element: Element) => Record<string, unknown>;
|
||||||
|
}
|
||||||
|
|
||||||
|
interface UserShape {
|
||||||
|
id: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
const host = document.querySelector('app-rooms-side-panel');
|
||||||
|
const debugApi = (window as { ng?: AngularDebugApi }).ng;
|
||||||
|
|
||||||
|
if (!host || !debugApi?.getComponent) {
|
||||||
|
throw new Error('Angular debug API unavailable');
|
||||||
|
}
|
||||||
|
|
||||||
|
const component = debugApi.getComponent(host);
|
||||||
|
const user = (component['currentUser'] as (() => UserShape | null) | undefined)?.();
|
||||||
|
|
||||||
|
if (!user?.id) {
|
||||||
|
throw new Error('Current user not found');
|
||||||
|
}
|
||||||
|
|
||||||
|
return user.id;
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
// ── Navigation helpers ───────────────────────────────────────────────
|
// ── Navigation helpers ───────────────────────────────────────────────
|
||||||
|
|
||||||
async function installDeterministicVoiceSettings(page: Page): Promise<void> {
|
async function installDeterministicVoiceSettings(page: Page): Promise<void> {
|
||||||
@@ -607,13 +556,18 @@ async function installDeterministicVoiceSettings(page: Page): Promise<void> {
|
|||||||
}
|
}
|
||||||
|
|
||||||
async function openSearchView(page: Page): Promise<void> {
|
async function openSearchView(page: Page): Promise<void> {
|
||||||
await page.goto('/servers', { waitUntil: 'domcontentloaded' });
|
const searchInput = page.getByPlaceholder('Search servers and users...');
|
||||||
await expect(page.getByPlaceholder('Search servers...')).toBeVisible({ timeout: 20_000 });
|
|
||||||
|
if (await searchInput.isVisible().catch(() => false)) {
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
await page.locator('button[title="Create Server"]').click();
|
||||||
|
await expect(searchInput).toBeVisible({ timeout: 20_000 });
|
||||||
}
|
}
|
||||||
|
|
||||||
async function joinRoomFromSearch(page: Page, roomName: string): Promise<void> {
|
async function joinRoomFromSearch(page: Page, roomName: string): Promise<void> {
|
||||||
await page.goto('/servers', { waitUntil: 'domcontentloaded' });
|
const searchInput = page.getByPlaceholder('Search servers and users...');
|
||||||
const searchInput = page.getByPlaceholder('Search servers...');
|
|
||||||
|
|
||||||
await expect(searchInput).toBeVisible({ timeout: 20_000 });
|
await expect(searchInput).toBeVisible({ timeout: 20_000 });
|
||||||
await searchInput.fill(roomName);
|
await searchInput.fill(roomName);
|
||||||
|
|||||||
@@ -71,7 +71,7 @@ test.describe('Dual-signal multi-user voice', () => {
|
|||||||
await registerPage.goto();
|
await registerPage.goto();
|
||||||
await registerPage.serverSelect.selectOption(PRIMARY_SIGNAL_ID);
|
await registerPage.serverSelect.selectOption(PRIMARY_SIGNAL_ID);
|
||||||
await registerPage.register(client.user.username, client.user.displayName, client.user.password);
|
await registerPage.register(client.user.username, client.user.displayName, client.user.password);
|
||||||
await expect(client.page).toHaveURL(/\/dashboard/, { timeout: 20_000 });
|
await expect(client.page).toHaveURL(/\/search/, { timeout: 20_000 });
|
||||||
}
|
}
|
||||||
});
|
});
|
||||||
|
|
||||||
@@ -319,13 +319,18 @@ async function installDeterministicVoiceSettings(page: Page): Promise<void> {
|
|||||||
}
|
}
|
||||||
|
|
||||||
async function openSearchView(page: Page): Promise<void> {
|
async function openSearchView(page: Page): Promise<void> {
|
||||||
await page.goto('/servers', { waitUntil: 'domcontentloaded' });
|
const searchInput = page.getByPlaceholder('Search servers and users...');
|
||||||
await expect(page.getByPlaceholder('Search servers...')).toBeVisible({ timeout: 20_000 });
|
|
||||||
|
if (await searchInput.isVisible().catch(() => false)) {
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
await page.locator('button[title="Create Server"]').click();
|
||||||
|
await expect(searchInput).toBeVisible({ timeout: 20_000 });
|
||||||
}
|
}
|
||||||
|
|
||||||
async function joinRoomFromSearch(page: Page, roomName: string): Promise<void> {
|
async function joinRoomFromSearch(page: Page, roomName: string): Promise<void> {
|
||||||
await page.goto('/servers', { waitUntil: 'domcontentloaded' });
|
const searchInput = page.getByPlaceholder('Search servers and users...');
|
||||||
const searchInput = page.getByPlaceholder('Search servers...');
|
|
||||||
|
|
||||||
await expect(searchInput).toBeVisible({ timeout: 20_000 });
|
await expect(searchInput).toBeVisible({ timeout: 20_000 });
|
||||||
await searchInput.fill(roomName);
|
await searchInput.fill(roomName);
|
||||||
|
|||||||
@@ -64,8 +64,8 @@ test.describe('Full user journey: register -> server -> voice chat', () => {
|
|||||||
await expect(registerPage.submitButton).toBeVisible();
|
await expect(registerPage.submitButton).toBeVisible();
|
||||||
await registerPage.register(ALICE.username, ALICE.displayName, ALICE.password);
|
await registerPage.register(ALICE.username, ALICE.displayName, ALICE.password);
|
||||||
|
|
||||||
// After registration, app should navigate to /dashboard
|
// After registration, app should navigate to /search
|
||||||
await expect(alice.page).toHaveURL(/\/dashboard/, { timeout: 15_000 });
|
await expect(alice.page).toHaveURL(/\/search/, { timeout: 15_000 });
|
||||||
});
|
});
|
||||||
|
|
||||||
await test.step('Bob registers an account', async () => {
|
await test.step('Bob registers an account', async () => {
|
||||||
@@ -75,7 +75,7 @@ test.describe('Full user journey: register -> server -> voice chat', () => {
|
|||||||
await expect(registerPage.submitButton).toBeVisible();
|
await expect(registerPage.submitButton).toBeVisible();
|
||||||
await registerPage.register(BOB.username, BOB.displayName, BOB.password);
|
await registerPage.register(BOB.username, BOB.displayName, BOB.password);
|
||||||
|
|
||||||
await expect(bob.page).toHaveURL(/\/dashboard/, { timeout: 15_000 });
|
await expect(bob.page).toHaveURL(/\/search/, { timeout: 15_000 });
|
||||||
});
|
});
|
||||||
|
|
||||||
// ── Step 2: Alice creates a server ───────────────────────────────
|
// ── Step 2: Alice creates a server ───────────────────────────────
|
||||||
|
|||||||
@@ -1,25 +0,0 @@
|
|||||||
# Electron Guidelines
|
|
||||||
|
|
||||||
This directory contains the Electron main process, preload bridge, IPC, desktop integration, and local persistence glue.
|
|
||||||
|
|
||||||
## Workflow
|
|
||||||
|
|
||||||
- Build with `npm run build:electron`.
|
|
||||||
- Use `npm run electron:dev` or `npm run dev` when you need the integrated desktop stack.
|
|
||||||
- See `../doc/typescript.md` for shared TypeScript rules.
|
|
||||||
|
|
||||||
## Boundaries
|
|
||||||
|
|
||||||
- Keep bootstrapping and lifecycle concerns in `app/`.
|
|
||||||
- Keep desktop platform integrations in focused modules such as `audio/`, `update/`, and `window/`.
|
|
||||||
- Keep renderer-exposed APIs typed in `preload.ts` and routed through explicit IPC handlers.
|
|
||||||
- When adding a new renderer-facing capability, update the Electron implementation, the preload surface, and the renderer bridge together.
|
|
||||||
- Keep persistence entities, migrations, and CQRS helpers aligned with the desktop database model rather than duplicating renderer types.
|
|
||||||
|
|
||||||
## Generated Output
|
|
||||||
|
|
||||||
- Treat `dist/electron/` and packaged artifacts in `dist-electron/` as build output, not source.
|
|
||||||
|
|
||||||
## Before You Finish
|
|
||||||
|
|
||||||
- Validate whether relevant markdown docs or `AGENTS.md` files need updates. If behavior, workflows, commands, or architecture changed, update those docs in the same task.
|
|
||||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user