domma-cms 1.1.0 → 1.3.0

package/server/routes/api/dashboard.js

@@ -12,6 +12,12 @@ import {authenticate as defaultAuthenticate, requireAdmin as defaultRequireAdmin
 import {getHealth} from '../../services/health.js';
 import {listVersions} from '../../services/versions.js';
 import {PRESET_COLLECTION_SLUGS} from '../../services/presetCollections.js';
+import {canAny as widgetCanAny, isDashboardPro} from '../../services/widgets.js';
+import {getPermissionsForRoles} from '../../services/roles.js';
+import {getEffectiveLevel, getEffectiveRoles} from '../../services/userRoles.js';
+import {getEffectiveRegistry} from '../../services/permissionRegistry.js';
+// The fixed Dashboard's own rules, so a widget says exactly what its card says.
+import {BADGE_SOURCES, activityRows, attentionFrom, chartSeries} from '../../../admin/js/lib/dashboard-arrange.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '..', '..', '..');
@@ -290,6 +296,14 @@ export async function dashboardRoutes(fastify, opts = {}) {
 
     fastify.get('/dashboard/summary', guard, async (request) => {
         const lite = request.query.lite === '1' || request.query.lite === 'true';
+        return buildSummary(lite);
+    });
+
+    /**
+     * The summary the fixed Dashboard reads - and, piece by piece, core's own
+     * widgets on the Dashboard Pro board (GET /dashboard/widget/:name below).
+     */
+    async function buildSummary(lite) {
         const warnings = [];
         const safe = async (label, fn) => {
             try { return await fn(); }
@@ -374,5 +388,76 @@ export async function dashboardRoutes(fastify, opts = {}) {
         const activity = (await safe('activity', () => buildActivity())) || [];
 
         return { traffic, topPages, journeys, spikes, realtime, health, activity, warnings };
+    }
+
+    /**
+     * Core's own widgets (services/widgets.js CORE_WIDGETS), each in its kind's
+     * shape. Dashboard Pro only - a site without it answers 404, as for every
+     * widget route. "Needs attention" asks the same sidebar badges the fixed
+     * Dashboard does, as the signed-in user, so nobody sees a Tool they cannot open.
+     */
+    fastify.get('/dashboard/widget/:name', {preHandler: [authenticate]}, async (request, reply) => {
+        if (!isDashboardPro()) return reply.status(404).send({error: 'Not found'});
+        const name = String(request.params.name || '');
+        const admin = getEffectiveLevel(request.user) <= 1;
+        if (name !== 'attention' && !admin) return reply.status(403).send({error: 'Administrators only'});
+        const fmtN = (n) => Number(n || 0).toLocaleString('en-GB');
+
+        if (name === 'attention') {
+            const permissions = getPermissionsForRoles(getEffectiveRoles(request.user), getEffectiveRegistry().map(r => r.key));
+            const want = BADGE_SOURCES.filter(src => widgetCanAny(permissions, src.permission));
+            const got = await Promise.all(want.map(src => fastify.inject({
+                method: 'GET', url: `/api${src.countUrl}`,
+                headers: {authorization: request.headers.authorization || ''}
+            }).then(r => (r.statusCode === 200 ? r.json() : null)).catch(() => null)));
+            const badges = Object.fromEntries(want.map((src, i) => [src.key, got[i]]).filter(([, b]) => b));
+            const checks = admin ? ((await getHealth().catch(() => null))?.checks || []) : [];
+            const rows = attentionFrom(badges, checks);
+            return {
+                items: rows.map(r => ({text: `${r.title}: ${r.text}`, meta: r.meta, href: r.href, tone: r.tone})),
+                empty: 'Nothing needs you right now.'
+            };
+        }
+
+        const s = await buildSummary(false);
+        if (name === 'traffic') {
+            const c = chartSeries(s.traffic?.series);
+            return {labels: c.labels, values: c.values, label: 'Page views'};
+        }
+        if (name === 'visitors') {
+            const delta = s.traffic?.deltaPct;
+            return {
+                value: fmtN(s.realtime?.activeSessions), label: 'on the site now',
+                sub: `${fmtN(s.traffic?.today)} page views today${delta == null ? '' : ` (${delta >= 0 ? '+' : ''}${Number(delta).toFixed(0)}% on yesterday)`}`
+            };
+        }
+        if (name === 'top-pages') {
+            return {
+                items: (s.topPages || []).map(p => ({
+                    text: p.url, value: fmtN(p.hits),
+                    meta: p.deltaPct == null ? '' : `${p.deltaPct >= 0 ? '+' : ''}${Number(p.deltaPct).toFixed(0)}% on the week before`,
+                    tone: p.deltaPct == null ? '' : (p.deltaPct >= 0 ? 'ok' : 'danger')
+                })),
+                empty: 'No page views in the last week.'
+            };
+        }
+        if (name === 'activity') {
+            return {
+                items: activityRows(s.activity || []).map(a => ({text: a.text, meta: a.meta, href: a.href})),
+                empty: 'Nothing has changed lately.'
+            };
+        }
+        if (name === 'health') {
+            const LEVEL = {ok: 'ok', warn: 'warn', fail: 'danger'};
+            return {
+                items: (s.health?.checks || []).map(c => ({
+                    text: String(c.label || c.id), value: String(c.value ?? ''),
+                    meta: Array.isArray(c.detail) ? c.detail.slice(0, 3).join(', ') : '',
+                    tone: LEVEL[c.level] || 'warn'
+                })),
+                empty: 'No health checks ran.'
+            };
+        }
+        return reply.status(404).send({error: 'Not found'});
     });
 }

package/server/routes/api/sidebar.js

@@ -17,6 +17,8 @@
 import {authenticate as defaultAuthenticate, checkVisibility} from '../../middleware/auth.js';
 import {getRegisteredSidebarItems} from '../../services/hooks.js';
 import {filterItemsForUser, getMenu} from '../../services/menus.js';
+import {isDashboardPro} from '../../services/widgets.js';
+import {boardName, readPrefs, readSite} from '../../services/dashboardSettings.js';
 
 export const ADMIN_SIDEBAR_SLUG = 'admin-sidebar';
 
@@ -35,7 +37,14 @@ export async function sidebarRoutes(fastify, opts = {}) {
     });
 
     fastify.get('/sidebar/registered-items', signedIn, async (request) => {
+        // Dashboard Pro: My Dashboard wears the name this person (or the site) gave it.
+        const boardLabel = isDashboardPro()
+            ? boardName(await readPrefs(request.user), await readSite())
+            : null;
         return getRegisteredSidebarItems()
+            .map(entry => (boardLabel && entry?.item?.url === '#/my-dashboard'
+                ? {...entry, item: {...entry.item, text: boardLabel}}
+                : entry))
             .filter(entry => !entry?.item?.hidden && checkVisibility(request.user, entry?.item?.visibility))
             .map(entry => Array.isArray(entry.item?.items)
                 ? {...entry, item: {...entry.item, items: filterItemsForUser(entry.item.items, request.user)}}

package/server/routes/api/widgets.js

@@ -0,0 +1,181 @@
+/**
+ * Dashboard Pro - the widget list and the board layouts.
+ *
+ *   GET    /api/dashboard/pro             {enabled} - whether this site has the board (any signed-in user)
+ *   GET    /api/widgets                   the widgets this user may add (Pro)
+ *   GET    /api/dashboard/boards          {boards: [{id, name, widgets}], active, source} (Pro)
+ *   PUT    /api/dashboard/boards          save all of mine (Pro)
+ *   GET    /api/dashboard/layout          the active board's layout {layout, source: mine|site|built-in} (Pro)
+ *   PUT    /api/dashboard/layout          save mine (Pro)
+ *   DELETE /api/dashboard/layout          go back to the site's default (Pro)
+ *   GET    /api/dashboard/layout/default  the site default (Pro, admins)
+ *   PUT    /api/dashboard/layout/default  set it (Pro, admins)
+ *   GET    /api/dashboard/settings        {mine, site, name, isAdmin, locked} - the cog (Pro)
+ *   PUT    /api/dashboard/settings        save mine (Pro)
+ *   PUT    /api/dashboard/settings/site   the name for everyone, and the layout lock (Pro, admins)
+ *
+ * A LOCKED site (settings/site `locked`) holds everyone but administrators to
+ * the site default: their GET answers it with source "locked", and their
+ * PUT / DELETE answer 423.
+ * Every route but /dashboard/pro answers 404 while no Pro Tool has switched the
+ * board on (services/widgets.js) - a free site has none of this.
+ *
+ * A layout is {version, widgets: [{id, size}]}, in board order. Mine is kept in
+ * content/dashboard/layouts/<user id>.json (ignored in a site repo - it is per
+ * user), the site default in content/dashboard/default.json (tracked).
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import {authenticate as defaultAuthenticate, requireAdmin as defaultRequireAdmin} from '../../middleware/auth.js';
+import {getPermissionsForRoles} from '../../services/roles.js';
+import {getEffectiveLevel, getEffectiveRoles} from '../../services/userRoles.js';
+import {getEffectiveRegistry} from '../../services/permissionRegistry.js';
+import {
+    DEFAULT_LAYOUT, activeBoard, boardsProblems, getWidgets, isDashboardPro, layoutProblems, normaliseBoards,
+    normaliseLayout, widgetsFor
+} from '../../services/widgets.js';
+import {boardName, prefsProblems, readPrefs, readSite, siteProblems, writePrefs, writeSite} from '../../services/dashboardSettings.js';
+
+const DIR = path.resolve('content', 'dashboard');
+const LAYOUTS = path.join(DIR, 'layouts');
+const DEFAULT_FILE = path.join(DIR, 'default.json');
+const USER_ID_RE = /^[A-Za-z0-9_-]{1,80}$/;
+
+async function readJson(file) {
+    try { return JSON.parse(await fs.readFile(file, 'utf8')); } catch { return null; }
+}
+
+/** Write via a temporary file, so a crash never leaves half a layout. */
+async function writeJson(file, data) {
+    await fs.mkdir(path.dirname(file), {recursive: true});
+    const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(data, null, 2) + '\n', 'utf8');
+    await fs.rename(tmp, file);
+}
+
+const userFile = (user) => (USER_ID_RE.test(String(user?.id || '')) ? path.join(LAYOUTS, `${user.id}.json`) : null);
+
+/** The site default, or the built-in one. */
+async function siteDefault() {
+    const stored = await readJson(DEFAULT_FILE);
+    return stored ? {layout: normaliseLayout(stored), source: 'site'} : {layout: normaliseLayout(DEFAULT_LAYOUT), source: 'built-in'};
+}
+
+/** Who is asking, in the terms widgetsFor() takes. */
+function who(user) {
+    const permissions = getPermissionsForRoles(getEffectiveRoles(user), getEffectiveRegistry().map(r => r.key));
+    return {permissions, isAdmin: getEffectiveLevel(user) <= 1};
+}
+
+export async function widgetRoutes(fastify, opts = {}) {
+    const authenticate = opts.authenticate || defaultAuthenticate;
+    const requireAdmin = opts.requireAdmin || defaultRequireAdmin;
+    const pro = async (request, reply) => {
+        if (!isDashboardPro()) return reply.status(404).send({error: 'Not found'});
+    };
+
+    // isAdmin: whether this user may set the site's default layout.
+    fastify.get('/dashboard/pro', {preHandler: [authenticate]}, async (request) => ({
+        enabled: isDashboardPro(),
+        isAdmin: getEffectiveLevel(request.user) <= 1
+    }));
+
+    fastify.get('/widgets', {preHandler: [authenticate, pro]}, async (request) => widgetsFor(getWidgets(), who(request.user)));
+
+    /** Whether this user is held to the site default (the lock, and not an admin). */
+    const heldToDefault = async (user) => !who(user).isAdmin && (await readSite()).locked;
+
+    /**
+     * This person's boards, and where they came from: their own (mine), or -
+     * before they have arranged anything - one board from the site default
+     * (site / built-in). A locked site gives a non-admin that one board only.
+     */
+    async function boardsFor(user) {
+        if (await heldToDefault(user)) {
+            const d = await siteDefault();
+            return {...normaliseBoards({boards: [{id: 'main', name: 'Main', widgets: d.layout.widgets}]}), source: 'locked'};
+        }
+        const file = userFile(user);
+        const mine = file ? await readJson(file) : null;
+        if (mine) return {...normaliseBoards(mine), source: 'mine'};
+        const d = await siteDefault();
+        return {...normaliseBoards({boards: [{id: 'main', name: 'Main', widgets: d.layout.widgets}]}), source: d.source};
+    }
+    const locked423 = (reply) => reply.status(423).send({error: 'Your administrator has locked the Dashboard layout.'});
+
+    fastify.get('/dashboard/boards', {preHandler: [authenticate, pro]}, async (request) => boardsFor(request.user));
+
+    fastify.put('/dashboard/boards', {preHandler: [authenticate, pro]}, async (request, reply) => {
+        if (await heldToDefault(request.user)) return locked423(reply);
+        const problems = boardsProblems(request.body);
+        if (problems.length) return reply.status(400).send({error: problems[0]});
+        const file = userFile(request.user);
+        if (!file) return reply.status(400).send({error: 'Your account cannot keep a layout.'});
+        const set = normaliseBoards(request.body);
+        await writeJson(file, set);
+        return {...set, source: 'mine'};
+    });
+
+    // The single-layout routes work on the ACTIVE board (what the board drew
+    // before there were several, and what a script may still call).
+    fastify.get('/dashboard/layout', {preHandler: [authenticate, pro]}, async (request) => {
+        const set = await boardsFor(request.user);
+        return {layout: {version: 1, widgets: activeBoard(set).widgets}, source: set.source};
+    });
+
+    fastify.put('/dashboard/layout', {preHandler: [authenticate, pro]}, async (request, reply) => {
+        if (await heldToDefault(request.user)) return locked423(reply);
+        const problems = layoutProblems(request.body);
+        if (problems.length) return reply.status(400).send({error: problems[0]});
+        const file = userFile(request.user);
+        if (!file) return reply.status(400).send({error: 'Your account cannot keep a layout.'});
+        const set = await boardsFor(request.user);
+        const layout = normaliseLayout(request.body);
+        activeBoard(set).widgets = layout.widgets;
+        await writeJson(file, normaliseBoards(set));
+        return {layout, source: 'mine'};
+    });
+
+    // Reset: every board goes, and the person starts again from the site default.
+    fastify.delete('/dashboard/layout', {preHandler: [authenticate, pro]}, async (request, reply) => {
+        if (await heldToDefault(request.user)) return locked423(reply);
+        const file = userFile(request.user);
+        if (file) await fs.rm(file, {force: true});
+        return siteDefault();
+    });
+
+    fastify.get('/dashboard/layout/default', {preHandler: [authenticate, pro, requireAdmin]}, async () => siteDefault());
+
+    fastify.put('/dashboard/layout/default', {preHandler: [authenticate, pro, requireAdmin]}, async (request, reply) => {
+        const problems = layoutProblems(request.body);
+        if (problems.length) return reply.status(400).send({error: problems[0]});
+        const layout = normaliseLayout(request.body);
+        await writeJson(DEFAULT_FILE, layout);
+        return {layout, source: 'site'};
+    });
+
+    // ---- The cog ----
+    fastify.get('/dashboard/settings', {preHandler: [authenticate, pro]}, async (request) => {
+        const [mine, site] = await Promise.all([readPrefs(request.user), readSite()]);
+        const isAdmin = who(request.user).isAdmin;
+        return {mine, site, name: boardName(mine, site), isAdmin, locked: site.locked && !isAdmin};
+    });
+
+    fastify.put('/dashboard/settings', {preHandler: [authenticate, pro]}, async (request, reply) => {
+        const problems = prefsProblems(request.body);
+        if (problems.length) return reply.status(400).send({error: problems[0]});
+        try {
+            const mine = await writePrefs(request.user, request.body);
+            const site = await readSite();
+            return {mine, site, name: boardName(mine, site)};
+        } catch (err) {
+            return reply.status(400).send({error: err.message});
+        }
+    });
+
+    fastify.put('/dashboard/settings/site', {preHandler: [authenticate, pro, requireAdmin]}, async (request, reply) => {
+        const problems = siteProblems(request.body);
+        if (problems.length) return reply.status(400).send({error: problems[0]});
+        return {site: await writeSite(request.body)};
+    });
+}

package/server/server.js

@@ -523,6 +523,7 @@ const {effectsRoutes} = await import('./routes/api/effects.js');
 const {searchRoutes} = await import('./routes/api/search.js');
 const {notificationsRoutes} = await import('./routes/api/notifications.js');
 const {dashboardRoutes} = await import('./routes/api/dashboard.js');
+const {widgetRoutes} = await import('./routes/api/widgets.js');
 const {cacheRoutes} = await import('./routes/api/cache.js');
 const {scaffoldRoutes} = await import('./routes/api/scaffold.js');
 
@@ -558,6 +559,7 @@ await app.register(effectsRoutes, {prefix: '/api'});
 await app.register(searchRoutes, {prefix: '/api'});
 await app.register(notificationsRoutes, {prefix: '/api'});
 await app.register(dashboardRoutes, {prefix: '/api'});
+await app.register(widgetRoutes, {prefix: '/api'});
 await app.register(cacheRoutes, {prefix: '/api'});
 await app.register(scaffoldRoutes, {prefix: '/api'});
 // Tools promoted out of plugins/ - their own prefixes, not /api/plugins/*.
@@ -668,6 +670,7 @@ registerSidebarItem({folder: 'system', item: {source: 'Built in', text: 'Content
 // sub-folders have no key in older menus; findFolder() falls back to their name.
 registerSidebarItem({folder: 'Usage', item: {source: 'Built in', text: 'Collections & Forms', url: '#/docs/usage/collections', icon: 'database'}});
 registerSidebarItem({folder: 'Usage', item: {source: 'Built in', text: 'Built-in Tools', url: '#/docs/usage/tools', icon: 'tool'}});
+registerSidebarItem({folder: 'Usage', item: {source: 'Built in', text: 'Dashboard', url: '#/docs/usage/dashboard', icon: 'home'}});
 registerSidebarItem({folder: 'Usage', item: {source: 'Built in', text: 'Editions & Licences', url: '#/docs/usage/editions', icon: 'key'}});
 registerSidebarItem({folder: 'API Reference', item: {source: 'Built in', text: 'Forms', url: '#/docs/api/forms', icon: 'layout'}});
 registerSidebarItem({folder: 'API Reference', item: {source: 'Built in', text: 'Scaffold', url: '#/docs/api/scaffold', icon: 'package'}});

package/server/services/dashboardSettings.js

@@ -0,0 +1,111 @@
+/**
+ * Dashboard Pro settings - the board's cog (admin/js/views/dashboard-board.js).
+ *
+ * Two layers:
+ *
+ *   mine  - each person's own: what their board is called, a greeting, how many
+ *           columns and how dense, how often widgets update, and whether the
+ *           admin opens on their board. content/dashboard/prefs/<user id>.json -
+ *           per user, so ignored in a site repo like the layouts beside it.
+ *   site  - an administrator's, for everyone: the board's default name and a
+ *           lock that holds everyone (but administrators) to the default
+ *           layout. content/dashboard/site.json, tracked.
+ *
+ * Pure normalisers plus small file helpers; the routes are in
+ * routes/api/widgets.js. Tested in tests/services/dashboard-settings.test.js.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+
+export const COLUMNS = [3, 4, 6];
+export const DENSITIES = ['normal', 'compact'];
+/** live = each widget's own interval; slower = three times as long; paused = only by hand. */
+export const UPDATES = ['live', 'slower', 'paused'];
+export const NAME_MAX = 40;
+
+export const DEFAULT_PREFS = {name: '', greeting: true, columns: 4, density: 'normal', updates: 'live', home: false};
+export const DEFAULT_SITE = {name: 'My Dashboard', locked: false};
+
+const cleanName = (v) => String(v ?? '').replace(/[\u0000-\u001f<>]/g, '').replace(/\s+/g, ' ').trim().slice(0, NAME_MAX);
+
+/** A person's settings, cleaned: unknown values fall back to the defaults. */
+export function normalisePrefs(input) {
+    const p = input && typeof input === 'object' ? input : {};
+    return {
+        name: cleanName(p.name),
+        greeting: p.greeting !== false,
+        columns: COLUMNS.includes(Number(p.columns)) ? Number(p.columns) : DEFAULT_PREFS.columns,
+        density: DENSITIES.includes(p.density) ? p.density : DEFAULT_PREFS.density,
+        updates: UPDATES.includes(p.updates) ? p.updates : DEFAULT_PREFS.updates,
+        home: p.home === true
+    };
+}
+
+/** The site's settings, cleaned. A blank name falls back to "My Dashboard". */
+export function normaliseSite(input) {
+    const s = input && typeof input === 'object' ? input : {};
+    return {name: cleanName(s.name) || DEFAULT_SITE.name, locked: s.locked === true};
+}
+
+/** What is wrong with submitted settings, as messages ([] when they are fine). */
+export function prefsProblems(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) return ['Settings must be an object.'];
+    const out = [];
+    if (input.name != null && String(input.name).length > NAME_MAX) out.push(`The name can be at most ${NAME_MAX} characters.`);
+    if (input.columns != null && !COLUMNS.includes(Number(input.columns))) out.push(`Columns must be one of ${COLUMNS.join(', ')}.`);
+    if (input.density != null && !DENSITIES.includes(input.density)) out.push(`Density must be ${DENSITIES.join(' or ')}.`);
+    if (input.updates != null && !UPDATES.includes(input.updates)) out.push(`Updates must be one of ${UPDATES.join(', ')}.`);
+    return out;
+}
+
+export function siteProblems(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) return ['Settings must be an object.'];
+    if (input.name != null && String(input.name).length > NAME_MAX) return [`The name can be at most ${NAME_MAX} characters.`];
+    return [];
+}
+
+/** What the board is called for this person: their own name, else the site's. */
+export function boardName(prefs, site) {
+    return cleanName(prefs?.name) || normaliseSite(site).name;
+}
+
+// ---- Files -------------------------------------------------------------------
+
+const DIR = () => path.resolve('content', 'dashboard');
+const USER_ID_RE = /^[A-Za-z0-9_-]{1,80}$/;
+
+async function readJson(file) {
+    try { return JSON.parse(await fs.readFile(file, 'utf8')); } catch { return null; }
+}
+
+async function writeJson(file, data) {
+    await fs.mkdir(path.dirname(file), {recursive: true});
+    const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(data, null, 2) + '\n', 'utf8');
+    await fs.rename(tmp, file);
+}
+
+const prefsFile = (user) => (USER_ID_RE.test(String(user?.id || '')) ? path.join(DIR(), 'prefs', `${user.id}.json`) : null);
+
+export async function readPrefs(user) {
+    const file = prefsFile(user);
+    return normalisePrefs(file ? await readJson(file) : null);
+}
+
+export async function writePrefs(user, input) {
+    const file = prefsFile(user);
+    if (!file) throw new Error('This account cannot keep settings.');
+    const prefs = normalisePrefs(input);
+    await writeJson(file, prefs);
+    return prefs;
+}
+
+export async function readSite() {
+    return normaliseSite(await readJson(path.join(DIR(), 'site.json')));
+}
+
+export async function writeSite(input) {
+    const site = normaliseSite(input);
+    await writeJson(path.join(DIR(), 'site.json'), site);
+    return site;
+}

package/server/services/docs.js

@@ -58,6 +58,7 @@ const MAP = [
     ['usage-editions',       'usage/editions',       'Editions & Licences'],
     ['usage-collections',    'usage/collections',    'Collections & Forms'],
     ['usage-tools',          'usage/tools',          'Built-in Tools'],
+    ['usage-dashboard',      'usage/dashboard',      'Dashboard'],
     ['tutorial-crud',        'tutorials/crud',       'Building a CRUD App'],
     ['tutorial-plugin',      'tutorials/plugin',     'Writing a Plugin'],
     ['tutorial-forms',       'tutorials/forms',      'Form Follow-Up'],

package/server/services/plugins.js

@@ -38,6 +38,7 @@ import {registerThemeProvider} from './themeSettings.js';
 import {classifyEntitlement, mayLoad} from './pluginEntitlement.js';
 import {notifierFor} from './notify.js';
 import {disableInstantCalls, enableInstantCalls, grantInstantCallsOnce} from './instantCalls.js';
+import {disableDashboardPro, enableDashboardPro, registerWidget, unregisterWidgetsFrom} from './widgets.js';
 import {createCollection, getCollection} from './collections.js';
 import * as defaultRolesService from './roles.js';
 import {getAdminScope, normaliseAdminScope} from './roles.js';
@@ -560,6 +561,10 @@ export async function registerPlugins(fastify) {
                   // them on at boot. Bound to the plugin's name, tier and closedSource: only a paid plugin that
                   // loads under a licence may.
                   enableInstantCalls: () => enableInstantCalls({owner: manifest.name, tier: manifest.tier || 'free', closedSource: manifest.closedSource === true}),
+                  // Dashboard Pro (services/widgets.js) - the widget board; the same contract as instant calls.
+                  enableDashboardPro: () => enableDashboardPro({owner: manifest.name, tier: manifest.tier || 'free', closedSource: manifest.closedSource === true}),
+                  // A widget from code (anything richer than a manifest's admin.widgets entry), owned by this plugin.
+                  registerWidget: (def) => registerWidget({...def, owner: manifest.name, source: manifest.displayName || manifest.name}),
                   // Who may read a contact that is not their own (Contacts Pro's sharing) - hooks.js 7b.
                   registerContactAccess: (fn) => registerContactAccess(manifest.name, fn),
                   // Direct messages between team members (Messages) - hooks.js 7c; a call's "Add people" uses it.
@@ -594,6 +599,14 @@ export async function registerPlugins(fastify) {
                 }
             }
 
+            // Dashboard widgets the manifest offers (services/widgets.js) - drawn by the admin
+            // from their `kind` and `dataUrl`, so a Tool needs no code to have one.
+            for (const def of manifest.admin?.widgets || []) {
+                if (!registerWidget({...def, owner: manifest.name, source: manifest.displayName || manifest.name})) {
+                    fastify.log.warn(`[plugins] widget "${def?.id}" for "${manifest.name}" skipped: not a valid widget`);
+                }
+            }
+
             // Ensure plugin collections exist (idempotent - skips if already present)
             await setupPlugin(manifest.name, {collections: {getCollection, createCollection}})
                 .catch(err => fastify.log.warn(`[plugins] Collection setup for "${manifest.name}" failed: ${err.message}`));
@@ -1123,6 +1136,8 @@ export async function runLifecycleHook(name, hook, fastify) {
     // A Tool with calls switched off stops keeping instant calls on - at once, not at the next restart.
     if (hook === 'onDisable') {
         disableInstantCalls(name);
+        disableDashboardPro(name);
+        unregisterWidgetsFrom(name);
         unregisterContactAccess(name);
         unregisterDirectMessenger(name);
     }

package/server/services/siteGitignore.js

@@ -317,6 +317,9 @@ export function buildGitignore({sitePlugins = [], pluginContent = {}, sitePublic
         '/content/.migrations.json',
         '/content/instances_log.json',
         '/content/preview-links.json',
+        // Each admin's own Dashboard Pro layout (keyed by user id); the site default beside it is tracked.
+        '/content/dashboard/layouts/',
+        '/content/dashboard/prefs/',
         '/config/connections.json*',
         '/config/keys/',
         '/plugins/*/data/*.jsonl',