feat(notices): validated contract for host-supplied notices by camielvs · Pull Request #2666 · TangleML/tangle-ui

camielvs · 2026-08-26T17:28:50Z

Why

An embedding page needs a way to put a notice in front of users — a maintenance window, a migration deadline — without waiting on one of our releases. That means reading data we don't control, so this PR is only the boundary, reviewable before anything renders it.

What

A host may install a notice source on the window. This module reads it and declines to trust it:

every field is validated and normalised — anything missing gets a sane default
a malformed entry is dropped rather than half-rendered
a source declaring a version we don't understand is ignored wholesale, not best-effort parsed
action links are narrowed to absolute http(s) URLs

Nothing imports this yet: no UI, no runtime surface. The test file is the argument — it walks through what the boundary does and doesn't let through, including the shapes we'd rather not crash on.

Reviewer notes

Standalone behaviour is unchanged, and stays that way. With no source installed, this returns an empty list forever, so a clean checkout behaves exactly as it does today.

knip.json gains an ignore entry, because the module has no importer until PR 4. The old announcements entry stays until the file it names is actually deleted, also in PR 4.

camielvs · 2026-08-26T17:29:08Z

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

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

github-actions · 2026-08-26T17:35:24Z

🎩 Preview

A preview build has been created at: banners-03-contract/4fb20f2

Adds the boundary an embedding page talks to: it may install a notice source on the window, and this module reads it defensively. Every field is validated and normalised, a malformed entry is dropped rather than trusted, and a source that declares an unsupported version is ignored wholesale. Headless and unreferenced — nothing renders these yet. Reviewable on its own, with the test file as the argument for what the boundary does and does not let through.

Collapse duplicate ids to the first occurrence and cap a snapshot at 20 entries, so a malformed host cannot produce duplicate React keys or unbounded per-render validation work. Freeze each banner rather than only the array — a mutated banner used to poison the signature cache for the life of the page, since the signature is computed before a consumer can reach the object. Declare __TANGLE_BANNER_SOURCE__ as unknown, which is what it is, and the cast in the test source helper disappears. Add BANNERS.md documenting the host-facing contract, in particular that the tangle:banner-source event is required after assigning the global. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Notices are the domain concept; banners are one of the two surfaces they are shown on. Renames the config module, its global and event, and the contract doc to match, before any host depends on the old names. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

camielvs · 2026-08-27T21:39:42Z

+
+declare global {
+  interface Window {
+    __TANGLE_NOTICE_SOURCE__?: unknown;


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.

camielvs mentioned this pull request Aug 26, 2026

feat(markdown): shared Markdown renderer #2664

Open

This was referenced Aug 26, 2026

refactor(layout): centralise content-area height in contentHeight() #2665

Open

feat(notices): host-driven notice banners on the dashboard home #2667

Open

feat(notices): notices button in the header #2668

Open