Widget Dashboard: keep removed widget instances and offer them in the inserter

[retrofox]

Part of #79231. Related to #83441.

What problem does this address?

Removing a widget deletes its instance from the layout (packages/widget-dashboard/src/components/widget-layout-controls/widget-layout-controls.tsx:67-73).

Its attributes and size go with it: to get the widget back, you insert the type again and configure it from scratch.

The layout records nothing about what happened to an instance, so neither the inserter nor a host can tell a widget the user removed from one they never placed.

What is your proposed solution?

Give each instance a small record of what happened to it. DashboardWidget gains __meta with inserted (date, and who placed it: the user through the inserter, or the host) and removed (date); each key keeps only the last occurrence. A removed instance stays in the layout marked as removed.

The engine skips removed instances everywhere it reads the layout (rendering, policy requests, the insert request layout) and emits them in onLayoutChange, so a host stores the layout as it comes and needs no reconciliation of its own.

The first use is the inserter: a "Removed" group lists the removed instances of the current layout; restoring one clears removed and places it again with its previous attributes and width.

To keep the record small, we keep only the latest removed instance per type, and we drop a removed instance whose type is no longer registered after a grace period.

resized, moved, and other keys can join later when something reads them; the record grows only with a consumer.

Tasks

• __meta on DashboardWidget, written on insert and remove; canonicalization, staging and the policy backstop preserve it.
• Skip removed instances in rendering, policy requests and the insert request layout; keep one per type; drop after the grace period.
• "Removed" group in the inserter that restores an instance with its attributes and width.
• Tests (jsdom and browser mode), stories, README and CHANGELOG.

[prasadkarmalkar]

Hi, I worked on a POC for this and wanted to share it here first to get feedback on the approach before opening a PR.

Recording

Screen.Recording.2026-10-01.at.4.36.50.PM.mov

How it works

Each DashboardWidget can carry a small __meta record, written by the dashboard:

• inserted: { date, by }: when it was placed, and whether by the user (through the inserter) or the host
• removed: { date }: when the user removed it

Most of the logic lives in the staging layer (dashboard-context.tsx), so the rest of the dashboard didn't need to change:

• Staging keeps the full layout but only shares the visible part. The grid, the empty state, the commands and the "Remove" action keep working with a list of visible widgets, the same as before.
• Removing. The "Remove" action still filters the widget out. Staging runs the existing policy check first. Then any widget that's missing gets marked with __meta.removed instead of being dropped. A remove the policy blocks is still undone, and never marked.
• Restoring. This clears removed and adds the widget back through the same path as inserting, it adds the old widget with modified layout to the end.
• Keeping it small. Only the latest removed widget of each type is kept. A removed widget whose type is no longer registered is cleaned up 30 days after removal, but never while widget types are still loading.

Main changes

• types.ts: adds the __meta field and its types
• utils/widget-meta.ts (new): helpers to split, mark, restore and clean up removed widgets
• utils/canonicalize-layout.ts: keeps removed widgets after the visible ones.
• context/dashboard-context.tsx: handles removal and restore, and adds removedWidgets and restoreWidget to the context
• utils/create-dashboard-widget: Added optional insertedBy, which the inserter sets to 'user'
• widget-inserter/removed-widgets.tsx (new): the "Removed" section shown in the inserter

Open questions

1. Grace period: For now I have keep it 30days as a constant?
2. Removing everything: removed widgets are saved, so the stored layout is never empty and the default layout doesn't come back on reload. Is that okay?
3. Placement in the inserter: is a section above the widget list the right spot, or would a filter inside the picker be better?

If this direction looks good, I'm happy to open a PR.

Use of AI

• Claude code
• Model - Opus 5.5
• Use - To prepare plan and POC (manually tested and reviewed locally)