@antelopejs/dms-marketing 0.6.1 → 0.7.1

package/frontend-vue/tests/website-settings.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from 'vitest'
+import type { MarketingWebsiteCard } from '../app/composables/useMarketingApi'
+import {
+  blankRequiredFields,
+  draftAsksBeforeSaving,
+  draftDiscardsSnapshots,
+  isWebsiteDraftDirty,
+  requestWebsiteSetting,
+  takeWebsiteSetting,
+  websiteDraftOf,
+  websitePatchOf,
+} from '../app/utils/website-settings'
+
+function card(
+  overrides: Partial<MarketingWebsiteCard> = {},
+): MarketingWebsiteCard {
+  return {
+    id: 'site-1',
+    name: 'Shop',
+    domain: 'shop.example.com',
+    state: 'live',
+    lastActivityAt: 1,
+    extraDomains: ['staging.example.com'],
+    snapshotsEnabled: true,
+    snapshotMaskText: false,
+    createdAt: 1,
+    sessions: 0,
+    pages: 0,
+    funnels: 0,
+    snapshots: 4,
+    sampleRate: 0.1,
+    rejected: [],
+    dashboard: false,
+    ...overrides,
+  }
+}
+
+describe('the settings draft', () => {
+  it('starts from the site, a paused one with tracking off', () => {
+    expect(websiteDraftOf(card())).toEqual({
+      name: 'Shop',
+      domain: 'shop.example.com',
+      hosts: ['staging.example.com'],
+      tracking: true,
+      snapshots: true,
+      mask: false,
+    })
+    expect(websiteDraftOf(card({ state: 'paused' })).tracking).toBe(false)
+  })
+
+  it('copies the hosts, so typing never edits the card', () => {
+    const site = card()
+    websiteDraftOf(site).hosts.push('other.example.com')
+    expect(site.extraDomains).toEqual(['staging.example.com'])
+  })
+
+  it('saves trimmed values, empty hosts dropped', () => {
+    expect(
+      websitePatchOf({
+        name: ' Shop ',
+        domain: ' shop.example.com',
+        hosts: [' a.example.com ', '  '],
+        tracking: false,
+        snapshots: false,
+        mask: false,
+      }),
+    ).toEqual({
+      name: 'Shop',
+      domain: 'shop.example.com',
+      extraDomains: ['a.example.com'],
+      trackingEnabled: false,
+      snapshotsEnabled: false,
+      snapshotMaskText: false,
+    })
+  })
+
+  it('requires the domain and the name, domain first', () => {
+    expect(blankRequiredFields({ name: ' ', domain: '' })).toEqual([
+      'domain',
+      'name',
+    ])
+    expect(blankRequiredFields({ name: 'Shop', domain: 'a.b' })).toEqual([])
+  })
+
+  it('is dirty once a value differs, not for spaces around one', () => {
+    const site = card()
+    const draft = websiteDraftOf(site)
+    expect(isWebsiteDraftDirty(site, draft)).toBe(false)
+    expect(isWebsiteDraftDirty(site, { ...draft, name: ' Shop ' })).toBe(false)
+    expect(isWebsiteDraftDirty(site, { ...draft, tracking: false })).toBe(true)
+  })
+})
+
+describe('snapshot options in the modal', () => {
+  it('warns when a site holding snapshots changes them', () => {
+    const site = card()
+    const draft = websiteDraftOf(site)
+    expect(draftDiscardsSnapshots(site, draft)).toBe(false)
+    expect(draftDiscardsSnapshots(site, { ...draft, mask: true })).toBe(true)
+    expect(
+      draftDiscardsSnapshots(card({ snapshots: 0 }), { ...draft, mask: true }),
+    ).toBe(false)
+  })
+
+  it('asks before saving a change, unless it turns them on for a site with none', () => {
+    const site = card()
+    const draft = websiteDraftOf(site)
+    expect(draftAsksBeforeSaving(site, draft)).toBe(false)
+    expect(draftAsksBeforeSaving(site, { ...draft, snapshots: false })).toBe(
+      true,
+    )
+    const none = card({ snapshotsEnabled: false, snapshots: 0 })
+    expect(
+      draftAsksBeforeSaving(none, { ...websiteDraftOf(none), snapshots: true }),
+    ).toBe(false)
+    // No snapshots yet, still a change of what later captures keep.
+    expect(
+      draftAsksBeforeSaving(card({ snapshots: 0 }), { ...draft, mask: true }),
+    ).toBe(true)
+  })
+})
+
+describe('the setting a card opens the modal on', () => {
+  it('is taken once, by the modal of its own site', () => {
+    requestWebsiteSetting('site-1', 'snapshots')
+    // The modal of another site drops the request.
+    expect(takeWebsiteSetting('site-2')).toBeUndefined()
+    expect(takeWebsiteSetting('site-1')).toBeUndefined()
+    requestWebsiteSetting('site-1', 'snapshots')
+    expect(takeWebsiteSetting('site-1')).toBe('snapshots')
+    expect(takeWebsiteSetting('site-1')).toBeUndefined()
+  })
+})

package/frontend-vue/tests/website-state.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest'
+import {
+  WEBSITE_LIVE_WINDOW_MS,
+  websiteDisplayState,
+  websiteStateLine,
+  websiteStateShort,
+} from '../app/utils/website-state'
+
+const NOW = Date.UTC(2026, 9, 18, 12)
+const MINUTE = 60_000
+const HOUR = 60 * MINUTE
+
+const t = (key: string, named: Record<string, unknown> = {}) =>
+  named.ago ? `${key} ${String(named.ago)}` : key
+
+describe('a website reads live', () => {
+  it('only while its last event is recent', () => {
+    const recent = { state: 'live' as const, lastActivityAt: NOW - MINUTE }
+    expect(websiteDisplayState(recent, NOW)).toBe('live')
+    const edge = {
+      state: 'live' as const,
+      lastActivityAt: NOW - WEBSITE_LIVE_WINDOW_MS,
+    }
+    expect(websiteDisplayState(edge, NOW)).toBe('live')
+  })
+
+  // QA m10: "Live · last event 7 hours ago" with a green dot.
+  it('as idle, last event time kept, once it went quiet', () => {
+    const quiet = { state: 'live' as const, lastActivityAt: NOW - 7 * HOUR }
+    expect(websiteDisplayState(quiet, NOW)).toBe('idle')
+    const line = websiteStateLine(quiet, NOW, t, 'en-GB')
+    expect(line.startsWith('page.marketing.context.idle ')).toBe(true)
+    expect(line).toContain('7')
+  })
+
+  it('keeps the other states as the backend sends them', () => {
+    for (const state of ['imported', 'waiting', 'paused'] as const) {
+      const site = {
+        state,
+        lastActivityAt: state === 'waiting' ? null : NOW - 7 * HOUR,
+      }
+      expect(websiteDisplayState(site, NOW)).toBe(state)
+    }
+    expect(
+      websiteStateLine(
+        { state: 'paused', lastActivityAt: NOW },
+        NOW,
+        t,
+        'en-GB',
+      ),
+    ).toBe('page.marketing.context.state.paused')
+  })
+})
+
+describe('the short state of a website', () => {
+  it('is the age of its last event', () => {
+    const recent = { state: 'live' as const, lastActivityAt: NOW - 12_000 }
+    expect(websiteStateShort(recent, NOW, t, 'en-GB')).toBe('12 sec ago')
+    // Intl spaces it with a no-break space.
+    expect(websiteStateShort(recent, NOW, t, 'fr-FR')).toMatch(/^il y a 12\ss$/)
+    const quiet = { state: 'live' as const, lastActivityAt: NOW - 7 * HOUR }
+    expect(websiteStateShort(quiet, NOW, t, 'en-GB')).toBe('7 hr ago')
+  })
+
+  // QA: "● dans 3 s" right after events arrived, the server's clock ahead.
+  it('reads just now under 5 seconds, never a time ahead', () => {
+    for (const lastActivityAt of [NOW + 3_000, NOW, NOW - 4_000]) {
+      const site = { state: 'live' as const, lastActivityAt }
+      expect(websiteStateShort(site, NOW, t, 'fr-FR')).toBe(
+        'page.marketing.context.just_now',
+      )
+      expect(websiteStateLine(site, NOW, t, 'fr-FR')).toBe(
+        'page.marketing.context.live page.marketing.context.just_now',
+      )
+    }
+  })
+
+  it('is the state in a word without a last event', () => {
+    expect(
+      websiteStateShort(
+        { state: 'waiting', lastActivityAt: null },
+        NOW,
+        t,
+        'en-GB',
+      ),
+    ).toBe('page.marketing.context.state_short.waiting')
+    expect(
+      websiteStateShort(
+        { state: 'paused', lastActivityAt: NOW },
+        NOW,
+        t,
+        'en-GB',
+      ),
+    ).toBe('page.marketing.context.state_short.paused')
+  })
+})

package/frontend-vue/tests/workspace-scope-control.test.ts

@@ -0,0 +1,113 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { createSSRApp, defineComponent, h } from 'vue'
+import { renderToString } from 'vue/server-renderer'
+import { describe, expect, it } from 'vitest'
+import WorkspaceScope from '../app/components/WorkspaceScope.vue'
+import { ALL_WORKSPACES } from '../app/utils/workspace-scope'
+
+const EXPLORER = join(process.cwd(), 'app', 'components', 'PagesExplorer.vue')
+
+const OWN = { id: 'tenant-a', name: 'Alpha', current: true }
+const OTHER = { id: 'tenant-b', name: 'Beta', current: false }
+
+/** The Nuxt UI parts, drawn as their slot; the tooltip keeps its text. */
+const UI_STUBS = {
+  UDropdownMenu: defineComponent({
+    setup:
+      (_props, { slots }) =>
+      () =>
+        h('div', slots.default?.()),
+  }),
+  UButton: defineComponent({
+    inheritAttrs: false,
+    setup:
+      (_props, { slots, attrs }) =>
+      () =>
+        h(
+          'button',
+          {
+            'aria-label': attrs['aria-label'],
+            'aria-describedby': attrs['aria-describedby'],
+          },
+          slots.default?.(),
+        ),
+  }),
+  UTooltip: defineComponent({
+    props: { text: String },
+    setup:
+      (props, { slots }) =>
+      () =>
+        h('div', { 'data-tooltip': props.text }, slots.default?.()),
+  }),
+  UIcon: defineComponent({ setup: () => () => h('i') }),
+}
+
+async function renderScope(modelValue: string): Promise<string> {
+  const app = createSSRApp(
+    defineComponent({
+      setup: () => () =>
+        h(WorkspaceScope, { workspaces: [OWN, OTHER], modelValue }),
+    }),
+  )
+  for (const [name, component] of Object.entries(UI_STUBS)) {
+    app.component(name, component)
+  }
+  return renderToString(app)
+}
+
+describe('the workspace selector', () => {
+  it('says nothing more on the own workspace', async () => {
+    const html = await renderScope('')
+    expect(html).toContain('page.marketing.pages.workspace.switch')
+    expect(html).not.toContain('page.marketing.pages.workspace.note_label')
+    expect(html).not.toContain('aria-describedby')
+  })
+
+  it('puts the read-only note in a focusable tooltip, never as a line', async () => {
+    for (const [value, note] of [
+      [ALL_WORKSPACES, 'page.marketing.pages.workspace.combined_note'],
+      [OTHER.id, 'page.marketing.pages.workspace.other_note'],
+    ]) {
+      const html = await renderScope(value!)
+      expect(html).not.toMatch(/<p\b/)
+      expect(html).toContain(`data-tooltip="${note}"`)
+      const icon = html.match(
+        /<span[^>]*tabindex="0"[^>]*aria-label="page\.marketing\.pages\.workspace\.note_label"[^>]*>/,
+      )?.[0]
+      expect(icon).toBeDefined()
+      const noteId = icon?.match(/aria-describedby="([^"]+)"/)?.[1]
+      expect(noteId).toBeTruthy()
+      // The selector and the icon both point at the note's text.
+      expect(html).toContain(`id="${noteId}" class="sr-only">${note}<`)
+      expect(html).toContain(
+        `<button aria-label="page.marketing.pages.workspace.switch" aria-describedby="${noteId}"`,
+      )
+    }
+  })
+
+  it('sits in the pages panel, above its search', () => {
+    const source = readFileSync(EXPLORER, 'utf8')
+    const template = source.slice(source.indexOf('<template>'))
+    const panel = template.indexOf('class="dms-card flex min-w-0 flex-col')
+    const scope = template.indexOf('<DmsMarketingWorkspaceScope')
+    const search = template.indexOf('v-model="search"')
+    expect(panel).toBeGreaterThan(-1)
+    expect(scope).toBeGreaterThan(panel)
+    expect(search).toBeGreaterThan(scope)
+    // Only once: no copy of it left above the panes.
+    expect(template.lastIndexOf('<DmsMarketingWorkspaceScope')).toBe(scope)
+  })
+
+  it('drops the selected row read in another workspace', () => {
+    // The header's views come from the row read for the scope on screen:
+    // a workspace switch never leaves the previous one's views in it.
+    const source = readFileSync(EXPLORER, 'utf8')
+    expect(source).toMatch(
+      /const readScope = computed\(\(\) =>\s*JSON\.stringify\(\[workspace\.value, pagesPeriod\.value\]\)/,
+    )
+    expect(source).toMatch(
+      /watch\(readScope, \(\) => \{\s*selectedPage\.value = undefined/,
+    )
+  })
+})

package/frontend-vue/tests/workspace-scope.test.ts

@@ -0,0 +1,55 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  ALL_WORKSPACES,
+  effectiveWorkspace,
+  rememberedWorkspace,
+  rememberWorkspace,
+} from '../app/utils/workspace-scope'
+
+const OWN = { id: 'tenant-a', name: 'Alpha', current: true }
+const OTHER = { id: 'tenant-b', name: 'Beta', current: false }
+
+describe('the heatmaps workspace scope', () => {
+  afterEach(() => vi.unstubAllGlobals())
+
+  it('reads the own workspace without a selector: one workspace, or none offered', () => {
+    expect(effectiveWorkspace(ALL_WORKSPACES, [])).toBe('')
+    expect(effectiveWorkspace(OTHER.id, [OWN])).toBe('')
+  })
+
+  it('applies what the selector offers, and nothing else', () => {
+    const options = [OWN, OTHER]
+    expect(effectiveWorkspace(ALL_WORKSPACES, options)).toBe(ALL_WORKSPACES)
+    expect(effectiveWorkspace(OTHER.id, options)).toBe(OTHER.id)
+    expect(effectiveWorkspace(OWN.id, options)).toBe('')
+    expect(effectiveWorkspace('tenant-gone', options)).toBe('')
+    expect(effectiveWorkspace('', options)).toBe('')
+  })
+
+  it('is remembered per browser, the own workspace clearing it', () => {
+    const store = new Map<string, string>()
+    vi.stubGlobal('localStorage', {
+      getItem: (key: string) => store.get(key) ?? null,
+      setItem: (key: string, value: string) => store.set(key, value),
+      removeItem: (key: string) => store.delete(key),
+    })
+    expect(rememberedWorkspace()).toBe('')
+    rememberWorkspace(ALL_WORKSPACES)
+    expect(rememberedWorkspace()).toBe(ALL_WORKSPACES)
+    rememberWorkspace('')
+    expect(rememberedWorkspace()).toBe('')
+  })
+
+  it('survives a blocked storage', () => {
+    vi.stubGlobal('localStorage', {
+      getItem: () => {
+        throw new Error('blocked')
+      },
+      setItem: () => {
+        throw new Error('blocked')
+      },
+    })
+    expect(rememberedWorkspace()).toBe('')
+    expect(() => rememberWorkspace(ALL_WORKSPACES)).not.toThrow()
+  })
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms-marketing",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "description": "First-party marketing analytics for the AntelopeJS DMS: traffic dashboards, conversion funnels with A/B splits and click heatmaps, without cookies or external services.",
   "keywords": [
     "ab-testing",
@@ -47,10 +47,10 @@
     "@antelopejs/interface-api": ">=0.0.15 <1.0.0",
     "@antelopejs/interface-api-util": ">=0.1.3 <1.0.0",
     "@antelopejs/interface-core": ">=0.2.4 <1.0.0",
-    "@antelopejs/interface-data-api": ">=0.2.2 <1.0.0",
-    "@antelopejs/interface-database": ">=0.1.10 <1.0.0",
-    "@antelopejs/interface-database-decorators": ">=0.1.9 <1.0.0",
-    "@antelopejs/interface-dms": ">=0.7.2 <1.0.0",
+    "@antelopejs/interface-data-api": ">=0.4.0 <1.0.0",
+    "@antelopejs/interface-database": ">=0.1.11 <1.0.0",
+    "@antelopejs/interface-database-decorators": ">=0.1.10 <1.0.0",
+    "@antelopejs/interface-dms": ">=0.9.0 <1.0.0",
     "@antelopejs/interface-dms-marketing": ">=0.5.0 <0.6.0",
     "defu": "^6.1.4",
     "maxmind": "^5.0.7",
@@ -60,9 +60,9 @@
     "zod": "~3.24.4"
   },
   "devDependencies": {
-    "@antelopejs/core": ">=1.16.0 <2",
+    "@antelopejs/core": ">=1.17.1 <2",
     "@antelopejs/interface-mongodb": ">=0.0.6 <1.0.0",
-    "@antelopejs/mongodb": "1.4.3",
+    "@antelopejs/mongodb": "1.5.0",
     "@antelopejs/tooling-configs": ">=0.0.9 <1.0.0",
     "@types/node": "^22.19.15",
     "@types/sanitize-html": "^2.16.2",
@@ -92,6 +92,7 @@
       "./skills"
     ]
   },
+  "dmsFrontend": "dist/frontend-module.js",
   "scripts": {
     "build": "pnpm --filter @antelopejs/interface-dms-marketing build && rimraf dist && tsc",
     "test": "pnpm run test:backend && pnpm run test:layer",

package/skills/dms-marketing/SKILL.md

@@ -16,15 +16,27 @@ https://dms.antelopejs.com/docs/modules/marketing (`architecture` holds the full
 ## Setup
 
 - Marketing 0.5 requires `@antelopejs/dms` >=0.9 (interface-dms 0.7, renderer `@antelopejs/dms-frontend` 0.6);
-  0.4 is the DMS 0.8 line.
+  0.4 is the DMS 0.8 line. Each analytics page declares `static toolbar = marketingToolbar()`: the DMS
+  `pageToolbar()` (website picker leading, Direct / Pause, period); it needs a DMS shipping `pageToolbar()` child options. Its period uses the DMS short codes
+  (1D / 7D / 30D / 90D); the custom range's calendar segment is icon-only, with its accessible name, from the DMS.
+  The comparison is the toolbar's default dropdown (vs previous period, vs previous year, none); the routes read the `compareFrom`/`compareTo` it sends, and "none" sends none, so no change is shown.
+- Live: the analytics pages declare `live` (`CONTEXT_PAGE_LIVE`, 15 s, 60 s past 8 days). Ingestion publishes
+  `marketing.events` (`{ count }`, batched 1/s) once a batch is in the rollup; every stock block carries it as
+  `realtimeTopic`, tables add `liveHold`, the Overview's KPI cards (no topic) are read by the bar on arrivals.
+  No module clock: Pause freezes every block. DMS page topics are not tenant-scoped yet: other tenants'
+  arrivals wake the pages and count in the paused "N new".
 - `ajs project modules add @antelopejs/dms-marketing`. Options: `trackerEnabled`, `rawEventsRetention`,
-  `statisticsRetention`, `snapshotRetention`, `sessionIdleTimeout` (all ms), `heatmapSampleRate` (0-1),
+  `statisticsRetention`, `snapshotRetention`, `sessionIdleTimeout` (all ms), `heatmapSampleRate` (0-1), `snapshotMaxBytes`,
   `visitorHashSecret` (set it when running several instances), `geoipDatabasePath` (.mmdb, opt-in),
   `dashboardTracking` (see below).
   The Settings page overrides switch, retentions and sampling at runtime for the whole deployment.
 - Behind a proxy set the DMS `auth.trustedProxies`; the old `trustedProxyHops` option is gone.
 - One website row per tracked site (Websites page or `POST /api/marketing/websites {name, domain, extraDomains?}`).
   Its `domain` gates ingestion: the beacon's Origin must be that apex, a subdomain or an extra host.
+- The Websites page is a DMS TableView (cards display, plain grid on offer) over
+  `/api/marketing/tables/websites`, whose list answers each row with its card; "Add a website" and a site's
+  settings open in modals. Link a site's settings with `/modules/marketing/websites?record=<id>`
+  (`&setting=snapshots` scrolls to the snapshot switch).
 
 ## Visitor site
 
@@ -37,34 +49,63 @@ window.dmsMarketing?.track("signup_submitted", { plan: "pro" }); // name <= 50 c
 const arm = await window.dmsMarketing?.variation("hero-cta");      // null = render the control
 ```
 
+- A site's data is purged, the site kept, with `POST /api/marketing/websites/:id/purge {scope: "heatmaps"|"all"}`
+  (tenant owner; settings modal, Danger zone): heatmaps = clicks, scroll depths and snapshots; all = every
+  event, session, rollup, snapshot and import. Funnels stay, their results start again from zero.
 - The dashboard origin forwards the scripts and beacons because the module declares them `publicEndpoints`
   (renderer 0.6 refuses other cross-origin writes); the backend origin works too.
 - Never `type="module"` (breaks `document.currentScript`). Always guard with `?.`.
-- Snapshots (heatmap backdrops) are opt-in per site; mask with `data-dms-marketing-mask` / `data-dms-marketing-block`.
+- Snapshots (heatmap backdrops) are opt-in per site (Websites page, a site's settings modal, General tab, next to Collect data); mask with
+  `data-dms-marketing-mask` / `data-dms-marketing-block`. Captures drop transient overlays on their own (top
+  layer, fixed/floating role=dialog/menu/listbox/tooltip, fixed toasts and toast viewports); block anything else
+  per element. Captures inline only the CSS rules matching the page
+  and upload gzipped; cap `snapshotMaxBytes` (default 1 MiB compressed, 64 KiB–8 MiB). One capture per
+  (path, layout) a day; a page without a snapshot (reset, option change, retention) is captured at its next
+  sampled visit (within 5 min across instances); a refused upload does not count as a capture.
+  The pages list shows each path's snapshot age ("No snapshot" when none) from one read per site. The
+  preview names the page captured: origin + path, a query string or fragment is never stored. It warns when
+  ≥ 10 % (and ≥ 5) of the anchored clicks target elements absent from the snapshot: the page changed, reset it.
+- App shells whose document does not scroll (an inner panel does): the tracker and the capture detect the
+  largest visible vertical scroller covering half the window; put `data-marketing-scroll-root` on the
+  container to name it explicitly. Scroll depth, click `dy` and the backdrop then cover the whole content.
 
 ## Tracking the dashboard itself
 
 For a demo, a playground or a back office measuring its own admin, no tag to write:
 
 ```typescript
-config: { dashboardTracking: { enabled: true, websiteName: "Dashboard", excludePaths: ["/settings/**"] } }
+config: { dashboardTracking: { enabled: true, websiteName: "Dashboard", excludePaths: ["/settings/**"],
+  snapshots: true } } // snapshots: optional, off by default
 ```
 
 - Off by default. On, the module's frontend loads the tracker on every signed-in dashboard page and
   `POST /api/marketing/dashboard-tracking` creates one website per tenant on first use (domain = the
-  dashboard's host; later hosts join `extraDomains`). Rename, pause or delete it like any site.
+  dashboard's host; later hosts join `extraDomains`). Rename or pause it like any site; it is never
+  deleted (`DELETE` answers 409): purge its data instead.
+- `snapshots: true` provisions it with page snapshots on (text masked) for heatmap backdrops. Config owns the
+  switch until a person changes it on the Websites page (`snapshotsSetBy: "owner"`): never re-enabled after.
 - `/auth/**` is never counted; signing out pauses the tag, a workspace switch retargets it. SPA navigations
   count. Restart `ajs dms dev` / rebuild the frontend after toggling the option.
+- The module area (`/modules`, `/modules/store`, `/modules/<module>/**`) is never counted either, not
+  configurable: dashboard tracking measures the owner's product, not shipped modules. Collect/snapshot drop
+  it server-side for the dashboard's website.
+- Platform owners (`users.owner`) on their own dashboard website can read other workspaces' dashboard
+  heatmaps: `GET /api/marketing/stats/workspaces?website=<own dashboard id>` lists the DMS core tenants
+  with a dashboard site (empty for anyone else or with fewer than 2), and `stats/pages|heatmap|scroll|snapshot`
+  take `workspace=<tenantId>|all` (merged per tenant; 404 for non platform owners or a customer site).
+  Snapshots outside the caller's workspace are text-masked server-side (`masked: true`). UI: `?workspace=`; the
+  selector (`WorkspaceScope.vue`) sits at the top of the pages panel, above the search, its read-only note in an
+  info tooltip (`aria-describedby`); the workspaces are read with the page (SSR, awaited) so the panel never grows.
 - Tracker attributes behind it, usable on any site: `data-exclude-paths="/x,/x/*,/x/**"`, and a live
   `data-website-id` (changing it retargets, removing it pauses).
 
 ## Content from code
 
-Never write the module's tables. From a module's `start()` (await) — or unawaited with a `.catch` in
-`construct()` / a DATABASE_INITIALIZED handler — use `@antelopejs/interface-dms-marketing`:
+Never write the module's tables. From a `Hook.TENANT_BEING_PROVISIONED` handler (once per tenant, the
+`default` one included; never `start()` or DATABASE_INITIALIZED) use `@antelopejs/interface-dms-marketing`:
 
 ```typescript
-const tenantId = "default"; // explicit, never implied
+RegisterHook(Hook.TENANT_BEING_PROVISIONED, async ({ tenantId }) => {
 await EnsureWebsite({ tenantId, id: "shop-site", name: "Shop", domain: "shop.example.com",
   snapshotsEnabled: true }); // id = data-website-id, global
 await EnsureFunnel({ tenantId, id: "shop-quote", websiteId: "shop-site", name: "Quote",
@@ -75,11 +116,12 @@ await EnsurePageSnapshot({ tenantId, websiteId: "shop-site", url: "https://shop.
   html, viewport: { width: 1280, height: 800 }, document: { width: 1280, height: 2600 } });
 await ImportAnalytics({ tenantId, importId: "shop-history", websiteId: "shop-site", sessions: [
   { visitor: "v1", userAgent, country: "BE", events: [{ kind: "pageview", at: "2026-10-01T09:00:00Z", url }] }] });
+});
 ```
 
-- Ensure* answer `created` / `unchanged` / `updated` / `kept`: a record someone changed since the last
-  declaration (hash stored on the row) is never overwritten; delete it in the dashboard to re-take it.
-  Dashboard rules apply (hostnames, 1-10 steps, 2-8 arms, draft → running ⇄ stopped, arms frozen out of draft).
+- Ensure* write once, from `Hook.TENANT_BEING_PROVISIONED`: `created`, or `kept` for an id that already exists
+  (no hash, no refresh); delete a record in the dashboard to re-take it. Dashboard rules apply (hostnames,
+  1-10 steps, 2-8 arms); a split is created draft, running (one open run) or stopped (one closed run).
 - ImportAnalytics replays through the live collect pipeline with trusted timestamps (same sessions,
   raw events and daily rows); once per importId + website, later calls `in_progress` (first still replaying, counts not final),
   then `skipped` (or `failed`); ≤ 10,000 sessions and
@@ -87,7 +129,7 @@ await ImportAnalytics({ tenantId, importId: "shop-history", websiteId: "shop-sit
   draft splits. `startedAt` on a running split makes imported exposures count.
 - EnsurePageSnapshot: the heatmap backdrop of a page the tracker cannot capture (not online, imported
   history); keyed by path + layout of `viewport` (desktop ≥ 1024, tablet ≥ 600, phone); sanitized like a
-  capture; needs `snapshotsEnabled`; a live capture replaces it and is never overwritten (`kept`).
+  capture (a `<style>` with `<` before a letter, `!`, `/` or `?` is dropped: CSS-escape that character); needs `snapshotsEnabled`; a live capture replaces it; an existing snapshot of that page and layout is `kept`.
 - `tenantId` is required on every content call: no default. Full contract: the interface package's
   `docs/1.index.md`.