Mod Studio (build your own cards and looks)

What it is

A mod here is a small saved design. It can carry either or both of:

• A card design. You lay out a session card from blocks: stack, row, box, text, field, badge, tags, icon, status dot, spacer and divider. A field block shows a detail of the session (name, status, project, model, cost, last active, branch, tags and more). Any block can carry a show only when condition on one of those details, so a "Needs you" badge appears only when the session needs you.
• Style rules. Each rule picks a named part of the app and changes its look: colours, corner radius, padding, font size, borders and shadow.

A mod is data only. It holds no code, no raw style text and no web addresses, so a mod somebody sends you can change how the app looks and nothing else. Three starters ship with the app to build from: Trello card, Detailed row and Minimal.

Where to find it

1. Settings → Lab: switch on Mod Studio (build your own mods). It is still in development, and it needs the shipped Layout Mods platform.
2. Settings → Appearance → Layout Mods → Your mods. Each mod has an on/off switch plus Edit, Duplicate, Copy JSON and Delete. New mod starts blank or from a starter, and Import takes pasted mod text.
3. The editor has three tabs: Card design, Style rules and Details (name and description). It shows a live preview, and nothing is saved until you press Save (Ctrl+S works too).

How it behaves

• Where a card design shows up. It replaces the rows in the session list (the switch Also use in the session list is on by default) and the cards on Board and Grid. Selecting, the right-click menu, renaming and keyboard navigation work as on the standard row.
• One fixed row height. Each design has a Row height between 24 and 240 px. The row and the list's scroller use that same number, so rows never overlap or vanish while you scroll.
• Style rules reach every window. The main window, popped-out sessions, detached windows and the KMS window all get the same look.
• Some parts can never be restyled. Approval and permission prompts, confirmations, security warnings and the Layout Mods controls are protected. A rule also never resizes anything inside a fixed-height list row, nor any part that contains a protected element. Colours there can still change.
• Values are bounded. A size is a number inside a set range, a colour is a theme colour or a checked hex value. Anything out of range is dropped on its own and the rest of the mod still applies.
• Imports arrive as new mods. An imported mod always gets a fresh app-made id, so it can never replace one of yours or a starter. Parts that could not be used are listed as dropped.
• Limits. Up to 50 mods, 40 blocks per card, 8 levels deep, 100 style rules, and 256 KB per mod.
• Safe Mode wins. Turn it on in Settings (Safe Mode, at the bottom of Layout Mods) or press Alt+Ctrl+Shift+X, which works even while you are typing in a session. Every card and style rule goes back to standard. Turning it off brings your mods back unchanged. You can rebind the shortcut under Keyboard Shortcuts ("Mods Safe Mode").
• A crashing card turns itself off. If a card design fails while drawing, the standard card returns at once and you get exactly one inbox alert naming the card design.
• Presentation mode. While presentation mode hides a session, every identifying field the card shows is blurred.
• Switching Mod Studio off stops every user mod from applying; your saved mods stay in the list.

For agents

• Settings: modStudioEnabled (default false; unreleased feature mod-studio, status in-development), userMods (raw array, at most 50; each read re-validates), activeLayoutModBySurface (surfaces session-card and app-styles for user looks), modsSafeMode. The settings are in src/shared/types/settings/mods-settings.ts; installed mods are readable through the normal settings read as userMods.
• Routes (src/main/services/cli/cli-server-mods-routes.ts):
  • GET /mods/catalog[?q=] returns the vocabulary: blocks, session fields, condition operators, badge tones, icons, style properties with their ranges, colour tokens, limits, the starters and one example mod. q adds up to 50 matching UI anchors a style rule can target.
  • POST /mods/user with { manifest, activate? } installs a mod. A fresh user-… id is always minted. It answers 409 while the feature is off or the 50-mod limit is reached, and 400 with a plain reason for an unusable mod. The reply carries id and the list of dropped capabilities.
  • DELETE /mods/user/:id removes one of the user's own mods and un-applies it everywhere.
• The mod format is the same in the editor, import, starters and routes: a manifest with a blocks capability (slot: session-card, design: { root, rowHeight, useInSessionList }) and/or a styles capability (rules: [{ anchor, style }]). anchor is a data-ui-anchor id.
• Validation: src/shared/mods/user-mods.ts (install and read), src/shared/mods/blocks/block-schema.ts (card designs), style-rules.ts and style-props.ts (rules and the table of allowed properties), mod-payload-guard.ts (size and depth, checked before any parse).
• The renderer: src/renderer/src/features/mod-studio/ (editor, block renderer, use-mod-looks.ts, useModStyleRules.ts).
• Hotkey: toggleModsSafeMode in src/shared/keybindings/mod-studio.keybindings.ts. Contracts: mod-studio-contract and mods-platform-contract.

Related

• mods-platform.md — the Layout Mods presets Mod Studio builds on.
• safe-mode.md — the general "start clean" recovery mode.