feat(notices): validated contract for host-supplied notices

[camielvs]

Why

The announcements this stack replaces are already host-installed: AnnouncementBanners reads window.__TANGLE_ANNOUNCEMENTS__ directly, and src/config/announcements.ts is nothing but the declare global for it. So the mechanism isn't new here — what's new is that it's validated, typed at the boundary as unknown, and can update after boot.

The existing global has four problems, all of them things a host page can trigger today:

• No validation. variant: announcement.variant ?? "info" passes any string through to variantStyles[variant].container — a typo'd variant is a TypeError in render, and an entry with no title renders an empty banner.
• Read during render, with new Date(). Both a mutable global read and a clock read happen inside the component body, which is why AnnouncementBanners.tsx can't be enabled for the React Compiler.
• No live update. useState(getDismissedIds) snapshots once, and the global is read with no subscription — a host that installs or replaces its data after the app mounts is invisible until a reload. There's no event, so it's a race the host can't win.
• Body is plain text. No links, no emphasis, no lists.

What you get

No behaviour change. This PR adds src/config/notices.ts and its documentation; nothing imports it yet. __TANGLE_ANNOUNCEMENTS__ and its banners are still the only thing on screen — they're replaced in #2667.

window.__TANGLE_NOTICE_SOURCE__ = {
  version: 1,
  getSnapshot: () => notices,
  subscribe: (listener) => { listeners.add(listener); return () => listeners.delete(listener); },
  refresh: () => fetchNotices(),   // optional
};
window.dispatchEvent(new CustomEvent("tangle:notice-source"));

With nothing installed the app shows nothing, exactly as it does today with the global unset. src/config/NOTICES.md is the reference for host authors.

Reviewer notes

This is a trust boundary, which is where the code goes. The global is typed unknown and everything is proven before it reaches a component: one type guard for the source, then per-field reads. The rules, all tested:

• version must be exactly 1 — a source declaring 2 is ignored wholesale, so a future contract can't half-render through this one.
• id required (a finite number is coerced); title required and non-blank. An entry failing either is dropped rather than rendered empty.
• variant falls back to info for anything unrecognised — this is the fix for the variantStyles[variant] crash above.
• body is Markdown and renders through UntrustedMarkdown from feat(markdown): shared Markdown renderer #2664. Whitespace is preserved because it's significant.
• action.url must be absolute http(s); javascript: and relative URLs drop the action and keep the notice.
• Duplicate ids collapse to the first; at most 20 entries are read per snapshot.
• A getSnapshot that throws is treated as "no notices" rather than propagating.

Two things worth a look because they're subtle rather than long:

Snapshot identity. getSnapshot is called on every render, and a host that maps/spreads its array returns a new reference each time — which would loop useSyncExternalStore. The store compares serialised content and returns the previous frozen array when it's unchanged. Tested with a rebuild-per-read source.

The required event. The app subscribes when it mounts, which may be before the host has installed anything, so subscribe alone would race. tangle:notice-source is what tells the store to (re)bind — documented as required, tested for late installation, and safe to dispatch again after replacing the global. Without it the options are a silent race (today's behaviour) or blocking app boot on the host's fetch.

Field-level differences from Announcement: expiresAt is gone — a host that can update its snapshot expires a notice by dropping it, rather than shipping an expiry the app has to evaluate with a clock read in render. action is added. id/title/body/variant/dismissible carry over.

Where this sits

	PR
1	#2664	shared Markdown renderer
2	#2666	validated host contract (you are here)
3	#2667	notice banners on the dashboard home — announcement parity
4	#2668	notices button in the header
5	#2681	hide a banner without retiring it

[camielvs]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat(notices): let a reader hide a banner without retiring it #2681
• feat(notices): notices button in the header #2668
• feat(notices): host-driven notice banners on the dashboard home #2667
• feat(notices): validated contract for host-supplied notices #2666 👈 (View in Graphite)
• feat(markdown): shared Markdown renderer #2664 : 1 other dependent PR (#2665 )
• master

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

🎩 Preview

A preview build has been created at: banners-03-contract/46d176a

[camielvs]

This is typed to unknown but guarded by isNoticeSource, so only TangleNotice will work. TangleNotice is Tangle-UI's expectation of the blind contract and thus this is the shape the source will need to provide.