From bd9f428a1044e2d9c42ac25a18cc11ee7ee54b48 Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Sat, 11 Jul 2026 16:35:59 +0200
Subject: [PATCH 1/2] fix(agent): make CSS edits replaceable and priority-aware

---
 docs/features/agent.md                        |  19 +-
 docs/reference/css-class-registry.md          |  26 +-
 server/ai/tools/site/systemPrompt.ts          |   5 +-
 server/ai/tools/site/writeTools.ts            |   4 +-
 src/__tests__/agent/agentSlice.test.ts        |   2 +-
 src/__tests__/agent/executor.test.ts          | 221 +++++++-
 src/__tests__/agent/renderEvidence.test.ts    |  28 +
 src/__tests__/agent/toolCallDisplay.test.ts   |  35 ++
 .../architecture/module-size-budgets.test.ts  |   1 -
 .../canvas/classStyleInjector.test.ts         |  21 +
 .../editor-store/ambientRule.test.ts          |  23 +
 .../editor-store/styleRuleSlice.test.ts       |  45 ++
 .../page-tree/scopedClassClone.test.ts        |  13 +
 .../publisher/classStyleInjector.test.ts      |  44 ++
 src/__tests__/publisher/sizesResolver.test.ts |  40 ++
 src/__tests__/siteImport/colorTokens.test.ts  |  10 +
 .../cssToStyleRules-substitution.test.ts      |   6 +
 .../siteImport/cssToStyleRules.test.ts        |  27 +
 .../siteImport/stylesheetModes.test.ts        |  28 +
 src/admin/pages/site/agent/cssTools.ts        |  88 ++++
 src/admin/pages/site/agent/executor.ts        |  67 +--
 src/admin/pages/site/agent/renderEvidence.ts  |  14 +
 src/admin/pages/site/agent/types.ts           |   4 +
 src/admin/pages/site/canvas/canvasClassCss.ts |  12 +-
 .../pages/site/panels/AgentPanel/index.ts     |   1 +
 .../site/panels/AgentPanel/toolCallDisplay.ts |  27 +-
 .../slices/styleRule/conditionActions.ts      |  11 +
 .../store/slices/styleRule/crudActions.ts     | 494 ++++++++++++++++--
 .../store/slices/styleRule/propertyActions.ts |  19 +
 .../store/slices/styleRule/registryActions.ts |  13 +
 .../site/store/slices/styleRule/types.ts      |  58 +-
 src/admin/pages/site/store/subtreeSnapshot.ts |  26 +
 src/core/ai/toolSchemas.ts                    |  38 +-
 src/core/css-substitution/index.ts            |  32 +-
 src/core/page-tree/index.ts                   |   8 +-
 src/core/page-tree/scopedClassClone.ts        |  13 +
 src/core/page-tree/styleRule.ts               |  50 +-
 src/core/publisher/classCss.ts                |  92 +++-
 src/core/publisher/index.ts                   |   6 +-
 src/core/publisher/sizesResolver.ts           |  27 +-
 src/core/siteImport/classCascades.ts          | Bin 19943 -> 19745 bytes
 src/core/siteImport/colorTokens.ts            |  13 +-
 src/core/siteImport/cssDeclarationReader.ts   |  19 +
 src/core/siteImport/cssToStyleRules.ts        |  60 +--
 src/core/siteImport/declarationCascade.ts     | 117 +++++
 src/core/siteImport/fontTokens.ts             |  19 +-
 46 files changed, 1691 insertions(+), 235 deletions(-)
 create mode 100644 src/__tests__/agent/toolCallDisplay.test.ts
 create mode 100644 src/admin/pages/site/agent/cssTools.ts
 create mode 100644 src/core/siteImport/cssDeclarationReader.ts
 create mode 100644 src/core/siteImport/declarationCascade.ts

diff --git a/docs/features/agent.md b/docs/features/agent.md
index b485b70d0..4d8bfb2d2 100644
--- a/docs/features/agent.md
+++ b/docs/features/agent.md
@@ -13,7 +13,7 @@ The agent runs on a provider-agnostic AI runtime (`server/ai/`) that can drive a
 ## TL;DR
 
 - **Structure via HTML.** `site_insert_html` and `site_replace_node_html` accept semantic HTML strings; the browser executor calls `importHtml` (the same pipeline as the paste-HTML UI) to convert them into first-class, editable `PageNode`s.
-- **Styling via CSS.** The agent emits CSS the same way a human pastes it: a `<style>` block and/or `class=` attributes inside the `site_insert_html`/`site_replace_node_html` payload, or the standalone `site_apply_css` tool. The importer (`cssToStyleRules`) classifies every selector — a bare `.foo {}` rule becomes a reusable Selectors-panel class bound to `class="foo"`; any other selector (`.hero a`, `a:hover`, `nav > li`) becomes an ambient rule; `style=` attributes land on the node's inline styles. There is no structured `classes` parameter — the agent never hand-builds classes node-by-node at insert time. `site_apply_css` is the single tool for authoring/editing CSS on its own; it **upserts**, so re-applying a selector edits the existing rule (the way descendant/pseudo rules get restyled).
+- **Styling via CSS.** The agent emits CSS the same way a human pastes it: a `<style>` block and/or `class=` attributes inside the `site_insert_html`/`site_replace_node_html` payload, or the standalone `site_apply_css` tool. The importer (`cssToStyleRules`) classifies every selector — a bare `.foo {}` rule becomes a reusable Selectors-panel class bound to `class="foo"`; any other selector (`.hero a`, `a:hover`, `nav > li`) becomes an ambient rule; `style=` attributes land on the node's inline styles. There is no structured `classes` parameter — the agent never hand-builds classes node-by-node at insert time. `site_apply_css` is the single tool for CSS on its own, with explicit merge, replace, rule-delete, and property-removal operations; exact selector identity and `!important` priority survive the round trip.
 - **Site scope: 35 tools total.** 6 server-side catalog read tools (resolved server-side from the posted snapshot / DB) + 29 browser-bridged tools.
 - **Content scope: 15 tools total.** 7 server-side content/catalog/media/user read tools + 8 browser-bridged document mutation/navigation tools.
 - **Two-endpoint bridge.** `POST /admin/api/ai/chat/:scope` opens an NDJSON stream. When the model calls a browser-bridged tool, the server emits `toolRequest`; the browser executor reads or mutates the live workspace and POSTs the `AiToolOutput` result to `POST /admin/api/ai/tool-result`.
@@ -95,6 +95,7 @@ src/admin/pages/site/agent/
 ├── siteAgentSnapshot.ts    — `SiteAgentSnapshotSchema` (TypeBox) + derived `SiteAgentSnapshot` type + `buildSiteAgentSnapshot` serializer
 ├── pageContext.ts          — editor adapter: reads active page + store scalars, calls `buildSiteAgentSnapshot`
 ├── executor.ts             — browser-side dispatcher: validates + runs write tools; auto-navigates canvas to node's owning document before each write
+├── cssTools.ts             — site_apply_css parser + exact-selector merge/replace/delete runners
 ├── documentTools.ts        — list/read/open document helpers for pages, templates, and visual components
 ├── tokenRunners.ts         — site_set_color_tokens / site_set_font_tokens / site_set_type_scale / site_set_spacing_scale runners (split from executor.ts)
 ├── renderEvidence.ts       — captureAgentRenderSnapshot (site_render_snapshot tool)
@@ -402,9 +403,14 @@ Styling rides on the `html` payload — there is no separate `classes` parameter
 
 `insertImportedNodes` then links every `class=` token on the imported nodes to its registry class id in the same undo step, so `class="hero-section"` renders and is styleable whether its styles came from a `<style>` rule or an automatically-created bare class. See [html-import.md → Class linking](html-import.md#class-linking-name--id).
 
-**Authoring CSS with `site_apply_css`.** `site_apply_css({ css })` is the single tool for CSS that isn't attached to inserted structure. The agent passes real CSS text (e.g. `".hero a:hover { color: var(--primary) }"`); it runs through the same `cssToStyleRules` classifier and is **upserted** into the registry by `upsertCssRules`: a bare `.foo {}` selector creates or edits a reusable class, any other selector (`.hero a`, `a:hover`, `nav > li`, `::before`, `h1`) creates or edits an ambient rule, `@media` folds into per-breakpoint/condition overrides, and supported `@keyframes` become ambient raw CSS rules. Re-applying a selector **merges** onto the existing rule — so the same tool both creates new styles and restyles existing descendant/pseudo rules (the case the retired `updateClassStyles` could not express). Returns `{ cssRulesCreated, cssRulesUpdated }`. Framework-generated token/utility classes are never overwritten. `site_insert_html`/`site_replace_node_html` also accept a `<style>`-only payload and route it through the same upsert as a forgiving fallback, but `site_apply_css` is the canonical path.
+**Authoring CSS with `site_apply_css`.** The required `operation` discriminator makes destructive intent explicit:
 
-Note the deliberate split: `site_apply_css` and `<style>`-only payloads **upsert** (the agent's intent is to author/edit CSS), whereas a `<style>` block that accompanies *elements* in an insert is **additive** (`mergeImportedStyleRules` — it never clobbers a shared class as a side effect of dropping in structure).
+- `{ operation: "merge", css }` creates missing selectors and patches only the supplied declarations/contexts. Touched declarations move to the end of the stored rule in authored order, so longhand/shorthand cascade order stays truthful.
+- `{ operation: "replace", css }` makes every supplied selector's complete CSS payload authoritative: omitted base declarations and contexts are removed, while stable rule id, cascade order, metadata, and class assignments survive. An empty `.foo {}` therefore clears its CSS without detaching the class.
+- `{ operation: "remove-properties", selectors, properties }` removes CSS-native property names from base plus every viewport/custom-condition bag without rebuilding unrelated CSS. Vendor names and custom properties are accepted; emitted `padding`/`margin` shorthands also clear their stored side longhands.
+- `{ operation: "delete", selectors }` removes every exact matching rule; class-kind rules are detached from page and Visual Component nodes in the same undo step.
+
+Selectors are matched by their exact emitted text across rule kinds. `.grad`, `.hero .grad`, and `.grad, .hero .grad` are separate rules—there is no unsafe attempt at semantic selector equivalence. Destructive batches preflight missing/locked targets and fail without partial mutation. Merge/replace accept real CSS through `cssToStyleRules`, including conditions, vendor/custom properties, raw keyframes, and structurally preserved `!important`. Framework-generated locked utilities are never changed. `<style>`-only `site_insert_html`/`site_replace_node_html` payloads keep merge behavior as a forgiving fallback; a `<style>` block accompanying inserted elements remains additive (`mergeImportedStyleRules`) so dropping in structure cannot clobber a shared rule.
 
 **Loops through HTML.** A repeated list is authored with the custom importer marker:
 
@@ -435,7 +441,7 @@ The agent calls `site_list_loop_sources` first to get the valid source id, data
 
 | Tool          | Input                 | Success `data`                          | What it does                                          |
 |---------------|-----------------------|-----------------------------------------|-------------------------------------------------------|
-| `site_apply_css`    | `{ css }`             | `{ cssRulesCreated, cssRulesUpdated }`  | Parse CSS text and upsert every rule — classes (bare `.foo`) and ambient rules (any other selector); re-applying a selector edits it |
+| `site_apply_css`    | `{ operation:'merge'\|'replace', css }` or `{ operation:'delete', selectors }` or `{ operation:'remove-properties', selectors, properties }` | `{ cssRulesCreated?, cssRulesUpdated?, cssRulesDeleted?, cssPropertiesRemoved? }` | Merge/replace authored CSS, delete exact rules, or remove selected properties across all contexts |
 | `site_assign_class` | `{ nodeId, classId }` | none                                    | Attach an existing class to a node; `classId` accepts id or name|
 | `site_remove_class` | `{ nodeId, classId }` | none                                    | Detach a class from a node (the class itself remains) |
 
@@ -500,7 +506,7 @@ The agent works **design-system-first**: it establishes or reuses tokens, then r
 
 | Tool              | Input                 | Success `data` | What it does                                                     |
 |-------------------|-----------------------|----------------|------------------------------------------------------------------|
-| `site_render_snapshot` | `{ breakpointId?, nodeId? }`   | `{ breakpointId, nodeId?, label, width, capturedAt, layout, screenshot }` + optional `images[]` | Inspect the rendered canvas: always returns a layout report (viewport, per-node bounding boxes, overflow / broken-image / invisible warnings); when the active provider supports native image-bearing tool results, a PNG is attached via the tool-output **image channel**. `breakpointId` picks any configured viewport at its exact configured width (defaults to active). Evidence always renders through a deterministic one-shot frame, so Live mode, collapsed frames, and `previewFrame:false` do not change the result or the user's visible canvas state. `nodeId` crops the rendered document to a smaller, sharper model image while preserving HTML/body/ancestor paint; the report covers the same section with coordinates relative to its box. Unknown breakpoint/node ids return `aiToolError` |
+| `site_render_snapshot` | `{ breakpointId?, nodeId? }`   | `{ breakpointId, nodeId?, label, width, capturedAt, layout, screenshot }` + optional `images[]` | Inspect the rendered canvas: always returns geometry, warnings, and per-node computed styles including background image/clip and WebKit text-mask values; capable providers also receive a PNG. `breakpointId` renders any configured viewport through a deterministic one-shot frame at its exact width, independent of Live mode or collapsed/disabled frames. `nodeId` crops to one subtree while preserving ancestor paint. Unknown ids error. Pair computed evidence with `site_read_document` source CSS when debugging the cascade |
 
 ### Auto-navigation
 
@@ -573,11 +579,12 @@ Drivers that support explicit prompt-cache controls (Anthropic) apply `cache_con
 - **Design system first.** Establish or reuse tokens before/while building (`site_set_color_tokens`, `site_set_type_scale`, `site_set_spacing_scale`, `site_set_font_tokens`), then reference them in CSS (`var(--<slug>)`, `var(--text-l)`, `var(--space-m)`, `var(--<font-var>)`) instead of raw hex/px/font-family. The dynamic suffix's `Tokens —` line shows what already exists; `(none …)` means no design system yet.
 - Structure as HTML (`site_insert_html` / `site_replace_node_html`); style with CSS in the same payload — a `<style>` block and/or `class=` attributes referencing the design tokens. The importer classifies selectors, so the agent never hand-builds classes at insert time.
 - `<style>` blocks inside imported HTML are parsed: a bare `.foo {}` rule becomes a Selectors-panel class bound to `class="foo"`; any other selector (`.hero a`, `a:hover`, `@media …`) becomes an ambient rule, and supported `@keyframes` publish as raw keyframes CSS. `style=` attributes land on the node's inline styles. These are applied — not stripped.
+- CSS-only edits use an explicit `site_apply_css` operation: merge for additive patches, remove-properties for stale declarations, replace only with the selector's complete desired CSS, and delete for whole exact rules. Read the document first before destructive operations; grouped and ungrouped selectors are different identities.
 - One `site_insert_html` call per logical section (nav, hero, pricing, footer = 4–6 calls); smaller chunks recover better if one fails.
 - Per-breakpoint variation: `@media` queries — in the `<style>` block of an insert or inside `site_apply_css` — with min/max-width queries that line up with the breakpoint widths in the dynamic suffix. Never invent ids like `"mobile"` or `"desktop"`.
 - Document refs come from the dynamic suffix or `site_list_documents`; never invent them. Shared chrome/layout/theme/navigation/footer requests should inspect template documents first.
 - Page ids for page operations come from the dynamic suffix; never invent them.
-- Write-tool success data uses explicit keys: `cssRulesCreated`/`cssRulesUpdated` for `site_apply_css`, `pageId` for `site_add_page`/`site_duplicate_page`, `nodeId`/`nodeIds` for `site_duplicate_node`, `nodeIds` for HTML inserts.
+- Write-tool success data uses explicit keys: `cssRulesCreated`/`cssRulesUpdated`/`cssRulesDeleted`/`cssPropertiesRemoved` for `site_apply_css`, `pageId` for `site_add_page`/`site_duplicate_page`, `nodeId`/`nodeIds` for `site_duplicate_node`, `nodeIds` for HTML inserts.
 - Editing existing content: call `site_read_document` first — it returns annotated document HTML where every element carries `uid="<nodeId>"` plus `pageInfo`; follow `pageInfo.nextPart` when more of the document is needed. Pass `uid` verbatim to write tools (`site_update_node_props`, `site_replace_node_html`, etc.). For a single subtree, `site_get_node_html` is sufficient.
 - Reply rule: 1–2 narrating sentences only. No raw HTML/CSS/JSON in the reply.
 
diff --git a/docs/reference/css-class-registry.md b/docs/reference/css-class-registry.md
index 7ec064dc1..1089fb013 100644
--- a/docs/reference/css-class-registry.md
+++ b/docs/reference/css-class-registry.md
@@ -2,7 +2,7 @@
 
 The site's style rule registry — `Record<string, StyleRule>` stored on the site shell (`site.styleRules`). Every user-defined CSS rule lives here. The publisher compiles entries to CSS at publish time; the editor's canvas injects the same CSS for live preview.
 
-Two kinds of rules:
+Three forms of rules:
 
 1. **Author-facing class rules** (`kind: 'class'`) — the user picks a name (`hero-button`, `card-meta`) and the editor applies them via `node.classIds`. Selector is `.<name>`.
 2. **Ambient rules** (`kind: 'ambient'`) — attach by CSS selector matching, not by node assignment (e.g. `h1`, `.hero .title`, `a:hover`). The publisher emits the rule but never writes to `class=` attributes. Supported stylesheet-level imports such as `@keyframes` are stored as ambient rules with `rawCss`.
@@ -39,12 +39,14 @@ interface StyleRule {
     nodeId: string
     role:   'module-style'
   }
-  styles:           Record<string, unknown>          // base CSS properties (CSSPropertyBag-shaped at write time)
-  contextStyles:     Record<string, Record<string, unknown>>  // per-context overrides, keyed by context id
-  rawCss?:          string                            // supported raw at-rule CSS, currently imported @keyframes
-  generated?:    GeneratedClassMetadata               // framework-generated flags
-  createdAt?:   number
-  updatedAt?:   number
+  styles:                  Record<string, unknown>    // base CSS properties (CSSPropertyBag-shaped at write time)
+  stylePriorities?:        Record<string, 'important'>
+  contextStyles:           Record<string, Record<string, unknown>>
+  contextStylePriorities?: Record<string, Record<string, 'important'>>
+  rawCss?:                 string                     // supported raw at-rule CSS, currently imported @keyframes
+  generated?:              GeneratedClassMetadata    // framework-generated flags
+  createdAt?:              number
+  updatedAt?:              number
 }
 ```
 
@@ -57,6 +59,8 @@ interface StyleRule {
 
 `styles` and `contextStyles` are typed `Record<string, unknown>` at the persistence boundary — narrowing happens at the publisher's `bagToCSS` (`classCss.ts`). The WRITE API (class slice, framework generators) uses the typed `CSSPropertyBag` shape from `src/core/page-tree/cssPropertyBag.ts`.
 
+Declaration priority is stored structurally, beside the scalar property value. `stylePriorities` is a sparse property-to-`'important'` map for `styles`; `contextStylePriorities` is the equivalent sparse map keyed first by context id. The CSS importer reads priority through `CSSStyleDeclaration.getPropertyPriority()`, and the publisher appends ` !important` from this metadata. Removing a value also removes its priority entry, and tolerant persistence parsing drops orphaned or invalid priority metadata. Node inline styles deliberately keep their existing value-only shape.
+
 `rawCss` is intentionally narrow. The importer uses it for sanitised `@keyframes` blocks that cannot be represented as selector declarations; the publisher emits only supported raw keyframes after its own safety gate. General arbitrary CSS strings still belong in structured `styles` / `contextStyles` entries.
 
 ---
@@ -172,7 +176,7 @@ All usage logic lives in `src/admin/pages/site/panels/selectorUsage.ts`.
 ```text
 For each rule in registry (sorted by order):
   selector = rule.selector               // e.g. '.hero-button' or 'h1 > span'
-  base CSS  = bagToCSS(rule.styles)
+  base CSS  = bagToCSS(rule.styles, options, rule.stylePriorities)
   emit:     '${selector} { ${base CSS} }'
 
   for each (contextId, bag) in rule.contextStyles:
@@ -182,7 +186,8 @@ For each rule in registry (sorted by order):
       prelude = '@media ${breakpoint.mediaQuery ?? `(max-width: ${width}px)`}'
     else:  // orphaned key — skipped
       continue
-    emit: '${prelude} { ${selector} { ${bagToCSS(bag)} } }'
+    priorities = rule.contextStylePriorities?.[contextId]
+    emit: '${prelude} { ${selector} { ${bagToCSS(bag, options, priorities)} } }'
 ```
 
 Cascade order within a rule: base → custom conditions (registry order) → viewport contexts. Pure max-width contexts emit widest first so narrower queries win; pure min-width contexts emit narrowest first so wider queries win; mixed/custom viewport queries keep registry order.
@@ -194,11 +199,12 @@ The compiled string is part of the per-page CSS bundle (see [docs/features/publi
 Translates the property bag (`{ color: '#fff', padding: { top: 16, right: 8 } }`) to CSS strings. Handles:
 
 - Plain values: `color: #fff;`
+- Sparse priority metadata: `color: #fff !important;`
 - Spacing bags: `padding: 16px 8px 0 0;` (decomposed)
 - Variable references: `color: var(--site-primary);`
 - Multi-value props (transforms, transitions): joined per CSS rules
 
-Invalid entries are silently dropped — the bag is tolerant.
+Invalid entries are silently dropped — the bag is tolerant. Four stored padding or margin sides collapse to a shorthand only when all four priorities match; mixed priorities remain longhands so the cascade is preserved.
 
 ---
 
diff --git a/server/ai/tools/site/systemPrompt.ts b/server/ai/tools/site/systemPrompt.ts
index b8548fdd0..a99002fa3 100644
--- a/server/ai/tools/site/systemPrompt.ts
+++ b/server/ai/tools/site/systemPrompt.ts
@@ -32,8 +32,9 @@ Design system first:
 Structure as HTML, styling as CSS:
 - Structure goes in site_insert_html/site_replace_node_html as semantic HTML. Style it with CSS in the SAME call: a <style> block and/or class= attributes (the importer turns these into reusable classes + ambient rules), referencing the design tokens above. This is the clean default; do NOT hand-build classes node-by-node.
 - Inline style= attributes also work: they land on the node's inline styles. Fine for one-off tweaks; reach for a <style> class when a style repeats.
-- site_apply_css is the ONE tool for authoring or editing CSS on its own — after insertion, or for any selector a class= can't express. Pass real CSS text: a bare \`.foo { … }\` selector creates/edits a reusable class; ANY other selector (\`.hero a\`, \`a:hover\`, \`nav > li\`, \`.card::before\`, \`h1\`) creates/edits an ambient rule that attaches by matching. Re-applying a selector MERGES onto it, so site_apply_css both creates AND edits — that is how you restyle an existing descendant/pseudo rule (e.g. \`site_apply_css(".hero a:hover { color: var(--primary) }")\`). There is no class-by-id patch tool; just write the CSS, referencing tokens via var(--…).
+- site_apply_css is the ONE tool for CSS on its own. Its required operation is explicit: merge + css for normal additive edits; remove-properties + exact selectors/property names to clear stale declarations; replace + css only when you are supplying each selector's COMPLETE desired base/responsive CSS; delete + exact selectors to remove whole rules. Before replace/delete/remove-properties, call site_read_document and copy the full selector exactly — \`.grad\`, \`.hero .grad\`, and \`.grad, .hero .grad\` are distinct rules. A bare \`.foo { … }\` is a reusable class; descendant/pseudo/element/grouped selectors are ambient rules. CSS priorities such as !important are preserved, but use them only when the cascade genuinely requires them.
 - Per-breakpoint variation: use @media queries — in the <style> block of an insert, or inside site_apply_css — with min/max-width queries that line up with the breakpoint widths in the dynamic suffix. Don't invent "mobile"/"tablet"/"desktop".
+- For visual/cascade debugging, scope site_render_snapshot to the affected node and inspect layout.nodes[].computed (including background image/clip and WebKit text fill); pair that computed evidence with site_read_document's source CSS before editing.
 
 Behavior and runtime code:
 - site_insert_html/site_replace_node_html deliberately strip <script> and inline event handlers (onclick/onload/etc). NEVER try to add behavior with <script>, onclick, or custom inline JS in HTML.
@@ -68,7 +69,7 @@ Templates (CMS layouts):
 
 Notes:
 - Use real ids from the suffix or prior tool results — never invent ids. Class refs accept id OR name.
-- Browser write-tool success data uses explicit keys: cssRulesCreated/cssRulesUpdated for site_apply_css, pageId for site_add_page/site_duplicate_page, nodeId/nodeIds for site_duplicate_node, and nodeIds for HTML inserts.
+- Browser write-tool success data uses explicit keys: cssRulesCreated/cssRulesUpdated/cssRulesDeleted/cssPropertiesRemoved for site_apply_css, pageId for site_add_page/site_duplicate_page, nodeId/nodeIds for site_duplicate_node, and nodeIds for HTML inserts.
 - On tool error: read the message and retry with corrected input.
 
 Reply: 1-2 sentences after acting. No raw HTML/CSS/JSON in the reply — tools change the page, the reply just narrates.`
diff --git a/server/ai/tools/site/writeTools.ts b/server/ai/tools/site/writeTools.ts
index 26faeb373..6ccd3a68f 100644
--- a/server/ai/tools/site/writeTools.ts
+++ b/server/ai/tools/site/writeTools.ts
@@ -191,7 +191,7 @@ const applyCssTool: AiTool = {
   execution: 'browser',
   requiredCapabilities: SITE_STYLE_CAPS,
   description:
-    'Author or edit CSS — the single tool for ALL styling that isn\'t attached inline. Pass real CSS text and it is parsed and UPSERTED into the site: a bare `.foo { … }` selector creates or edits a reusable class (bound to class="foo"); ANY other selector — descendant (`.hero a`), child (`nav > li`), pseudo-class/element (`a:hover`, `.card::before`), attribute, element (`h1`) — creates or edits an ambient rule that attaches by matching, no class attribute needed. `@media` queries fold into per-breakpoint overrides (matched against the site breakpoints); other `@media`/`@supports`/`@container` round-trip as reusable conditions. Re-applying a selector MERGES onto the existing rule, so this both creates new styles and edits existing ones (e.g. `.hero a:hover { color: var(--primary) }` to restyle an existing descendant rule). Reference design tokens — `var(--primary)`, `var(--text-l)`, `var(--space-m)` — not raw hex/px. A reusable class is just a bare `.name` selector (a CSS identifier, no spaces). Success data: `{ cssRulesCreated, cssRulesUpdated }`.',
+    'Author, repair, or delete CSS rules. `operation:"merge"` plus real CSS creates missing selectors and patches only authored declarations/contexts; use it for normal additive edits. `operation:"replace"` makes each supplied selector\'s COMPLETE CSS payload authoritative, removing omitted base/context declarations while preserving rule identity, cascade order, and class assignments. `operation:"remove-properties"` removes named CSS properties from base and every context without disturbing other declarations. `operation:"delete"` removes whole rules by exact emitted selector and detaches deleted classes. Selector identity is exact: `.grad`, `.hero .grad`, and `.grad, .hero .grad` are different rules; copy the full selector from site_read_document before destructive operations. Bare `.foo` rules are reusable classes; descendant/pseudo/element/grouped selectors are ambient rules. `@media`/`@supports`/`@container`, vendor properties, custom properties, and `!important` round-trip. Reference design tokens rather than repeated literals. Success data uses `cssRulesCreated`, `cssRulesUpdated`, `cssRulesDeleted`, and/or `cssPropertiesRemoved`.',
   inputSchema: ApplyCssInputSchema,
 }
 
@@ -400,7 +400,7 @@ const renderSnapshotTool: AiTool = {
   scope: 'site',
   execution: 'browser',
   description:
-    "Inspect the rendered canvas. Returns a layout report: viewport size, per-node bounding boxes, image-load status, and warnings (overflow / broken-image / invisible-node) — enough to catch most layout bugs in text. When the active provider supports native image-bearing tool results, a screenshot is also attached as an image. Pass any configured `breakpointId` to render a readiness-aware one-shot frame at that exact configured width, independent of collapsed/disabled frames or the viewport active in Live mode (defaults to active; unknown ids error). Pass `nodeId` to crop the document rendering to that node while preserving its HTML/body/ancestor background — a smaller, sharper model image with a report scoped to that section and coordinates relative to the node; omit `nodeId` to capture the full page.",
+    "Inspect the rendered canvas. Returns viewport and node geometry, image-load status, overflow/visibility warnings, and key computed styles including color, background image/clip, and WebKit text-mask values. Those computed fields expose cascade failures such as a shorthand resetting `background-clip:text`; compare them with source CSS from site_read_document. When the provider supports image-bearing tool results, a screenshot is also attached. Pass any configured `breakpointId` to render a readiness-aware one-shot frame at that exact width, independent of collapsed/disabled frames or Live mode (defaults to active; unknown ids error). Pass `nodeId` to crop the document to that node while preserving its HTML/body/ancestor paint; omit it for the full page.",
   inputSchema: RenderSnapshotInputSchema,
 }
 
diff --git a/src/__tests__/agent/agentSlice.test.ts b/src/__tests__/agent/agentSlice.test.ts
index 0026f9287..f389edadb 100644
--- a/src/__tests__/agent/agentSlice.test.ts
+++ b/src/__tests__/agent/agentSlice.test.ts
@@ -715,7 +715,7 @@ describe('sendAgentMessage — request lifecycle', () => {
           type: 'toolRequest',
           requestId: 'req-7',
           toolName: 'site_apply_css',
-          input: { css: '.pricing-card { padding: 24px; }' },
+          input: { operation: 'merge', css: '.pricing-card { padding: 24px; }' },
         },
         { type: 'done' },
       ]),
diff --git a/src/__tests__/agent/executor.test.ts b/src/__tests__/agent/executor.test.ts
index 433a66a05..44715c9b8 100644
--- a/src/__tests__/agent/executor.test.ts
+++ b/src/__tests__/agent/executor.test.ts
@@ -991,9 +991,19 @@ const findRule = (predicate: (c: { name: string; kind?: string; selector: string
   Object.values(useEditorStore.getState().site!.styleRules).find(predicate)
 
 describe('executeAgentTool — applyCss', () => {
+  it('requires an explicit operation instead of inferring destructive intent', async () => {
+    freshStore()
+    const result = await executeAgentTool('site_apply_css', {
+      css: '.legacy-shape { color: red; }',
+    })
+    expectToolError(result)
+    expect(findRule((rule) => rule.selector === '.legacy-shape')).toBeUndefined()
+  })
+
   it('creates a reusable class from a bare `.foo` selector', async () => {
     freshStore()
     const result = await executeAgentTool('site_apply_css', {
+      operation: 'merge',
       css: '.btn-primary { font-size: 14px; color: var(--primary); }',
     })
     const data = expectToolData<{ cssRulesCreated: number; cssRulesUpdated: number }>(result)
@@ -1008,8 +1018,9 @@ describe('executeAgentTool — applyCss', () => {
 
   it('EDITS an existing class when its selector is re-applied (upsert, not duplicate)', async () => {
     freshStore()
-    await executeAgentTool('site_apply_css', { css: '.card { color: red; }' })
+    await executeAgentTool('site_apply_css', { operation: 'merge', css: '.card { color: red; }' })
     const result = await executeAgentTool('site_apply_css', {
+      operation: 'merge',
       css: '.card { color: blue; font-size: 20px; }',
     })
     const data = expectToolData<{ cssRulesCreated: number; cssRulesUpdated: number }>(result)
@@ -1024,7 +1035,10 @@ describe('executeAgentTool — applyCss', () => {
 
   it('creates an ambient rule from a descendant selector', async () => {
     freshStore()
-    await executeAgentTool('site_apply_css', { css: '.hero a { color: tomato; }' })
+    await executeAgentTool('site_apply_css', {
+      operation: 'merge',
+      css: '.hero a { color: tomato; }',
+    })
     const ambient = findRule((c) => c.kind === 'ambient' && c.selector === '.hero a')!
     expect(ambient).toBeDefined()
     expect(ambient.styles.color).toBe('tomato')
@@ -1032,8 +1046,12 @@ describe('executeAgentTool — applyCss', () => {
 
   it('EDITS an existing ambient descendant/pseudo rule — the case updateClassStyles could not express', async () => {
     freshStore()
-    await executeAgentTool('site_apply_css', { css: '.hero a:hover { color: red; }' })
+    await executeAgentTool('site_apply_css', {
+      operation: 'merge',
+      css: '.hero a:hover { color: red; }',
+    })
     const result = await executeAgentTool('site_apply_css', {
+      operation: 'merge',
       css: '.hero a:hover { color: var(--primary); text-decoration: underline; }',
     })
     const data = expectToolData<{ cssRulesCreated: number; cssRulesUpdated: number }>(result)
@@ -1050,6 +1068,7 @@ describe('executeAgentTool — applyCss', () => {
   it('folds a matching @media block into the rule contextStyles', async () => {
     freshStore()
     await executeAgentTool('site_apply_css', {
+      operation: 'merge',
       css:
         '.hero-title { font-size: 56px; }' +
         '@media (max-width: 375px) { .hero-title { font-size: 32px; } }',
@@ -1059,9 +1078,193 @@ describe('executeAgentTool — applyCss', () => {
     expect(cls.contextStyles.mobile.fontSize).toBe('32px')
   })
 
+  it('replace makes one selector payload authoritative without changing its identity or assignment', async () => {
+    const { rootId } = freshStore()
+    await executeAgentTool('site_apply_css', {
+      operation: 'merge',
+      css:
+        '.card { color: red; background: var(--surface); }' +
+        '@media (max-width: 375px) { .card { color: orange; } }',
+    })
+    const before = findRule((rule) => rule.selector === '.card')!
+    const nodeId = expectNodeIds(await executeAgentTool('site_insert_html', {
+      parentId: rootId,
+      html: '<div class="card">Card</div>',
+    }))[0]
+
+    const result = await executeAgentTool('site_apply_css', {
+      operation: 'replace',
+      css: '.card { color: blue; }',
+    })
+
+    const data = expectToolData<{ cssRulesCreated: number; cssRulesUpdated: number }>(result)
+    expect(data).toEqual({ cssRulesCreated: 0, cssRulesUpdated: 1 })
+    const after = findRule((rule) => rule.selector === '.card')!
+    expect(after.id).toBe(before.id)
+    expect(after.order).toBe(before.order)
+    expect(after.styles).toEqual({ color: 'blue' })
+    expect(after.contextStyles).toEqual({})
+    expect(activePage().nodes[nodeId].classIds).toContain(after.id)
+  })
+
+  it('replace accepts an empty rule to clear declarations without detaching the class', async () => {
+    const { rootId } = freshStore()
+    await executeAgentTool('site_apply_css', {
+      operation: 'merge',
+      css: '.clear-me { color: red; }',
+    })
+    const nodeId = expectNodeIds(await executeAgentTool('site_insert_html', {
+      parentId: rootId,
+      html: '<p class="clear-me">Text</p>',
+    }))[0]
+
+    const result = await executeAgentTool('site_apply_css', {
+      operation: 'replace',
+      css: '.clear-me {}',
+    })
+
+    expectToolOk(result)
+    const rule = findRule((candidate) => candidate.selector === '.clear-me')!
+    expect(rule.styles).toEqual({})
+    expect(activePage().nodes[nodeId].classIds).toContain(rule.id)
+  })
+
+  it('merge reorders touched declarations so a longhand authored after a shorthand wins', async () => {
+    freshStore()
+    const rule = useEditorStore.getState().createClass('grad', {
+      backgroundClip: 'text',
+      background: 'linear-gradient(var(--primary), var(--accent))',
+    })
+
+    await executeAgentTool('site_apply_css', {
+      operation: 'merge',
+      css:
+        '.grad {' +
+        'background: linear-gradient(var(--primary), var(--accent));' +
+        'background-clip: text;' +
+        '}',
+    })
+
+    const keys = Object.keys(useEditorStore.getState().site!.styleRules[rule.id].styles)
+    expect(keys.indexOf('background')).toBeLessThan(keys.indexOf('backgroundClip'))
+  })
+
+  it('preserves important priority and lets a later normal merge remove it explicitly', async () => {
+    freshStore()
+    await executeAgentTool('site_apply_css', {
+      operation: 'merge',
+      css: '.priority { color: red !important; }',
+    })
+    let rule = findRule((candidate) => candidate.selector === '.priority')!
+    expect(rule.stylePriorities).toEqual({ color: 'important' })
+
+    await executeAgentTool('site_apply_css', {
+      operation: 'merge',
+      css: '.priority { color: blue; }',
+    })
+    rule = findRule((candidate) => candidate.selector === '.priority')!
+    expect(rule.styles.color).toBe('blue')
+    expect(rule.stylePriorities).toBeUndefined()
+  })
+
+  it('delete removes every exact selector match and detaches deleted classes', async () => {
+    const { rootId } = freshStore()
+    await executeAgentTool('site_apply_css', {
+      operation: 'merge',
+      css: '.doomed { color: red; }',
+    })
+    const classRule = findRule((rule) => rule.selector === '.doomed')!
+    const nodeId = expectNodeIds(await executeAgentTool('site_insert_html', {
+      parentId: rootId,
+      html: '<p class="doomed">Text</p>',
+    }))[0]
+    useEditorStore.getState().createAmbientRule({ selector: '.hero span', styles: { color: 'red' } })
+    useEditorStore.getState().createAmbientRule({ selector: '.hero span', styles: { color: 'blue' } })
+
+    const result = await executeAgentTool('site_apply_css', {
+      operation: 'delete',
+      selectors: ['.doomed', '.hero span'],
+    })
+
+    const data = expectToolData<{ cssRulesDeleted: number }>(result)
+    expect(data.cssRulesDeleted).toBe(3)
+    expect(useEditorStore.getState().site!.styleRules[classRule.id]).toBeUndefined()
+    expect(activePage().nodes[nodeId].classIds).not.toContain(classRule.id)
+    expect(Object.values(useEditorStore.getState().site!.styleRules).some(
+      (rule) => rule.selector === '.hero span',
+    )).toBe(false)
+  })
+
+  it('remove-properties clears base/context declarations, vendor/custom names, and collapsed sides', async () => {
+    freshStore()
+    await executeAgentTool('site_apply_css', {
+      operation: 'merge',
+      css:
+        '.mask {' +
+        'background: linear-gradient(var(--primary), var(--accent));' +
+        '-webkit-text-fill-color: transparent;' +
+        '--mask-token: gold;' +
+        'padding: 4px 8px;' +
+        'color: transparent;' +
+        '}' +
+        '@media (max-width: 375px) {' +
+        '.mask { background: var(--surface); -webkit-text-fill-color: currentColor; }' +
+        '}',
+    })
+
+    const result = await executeAgentTool('site_apply_css', {
+      operation: 'remove-properties',
+      selectors: ['.mask'],
+      properties: ['background', '-webkit-text-fill-color', '--mask-token', 'padding'],
+    })
+
+    const data = expectToolData<{ cssRulesUpdated: number; cssPropertiesRemoved: number }>(result)
+    expect(data.cssRulesUpdated).toBe(1)
+    expect(data.cssPropertiesRemoved).toBeGreaterThan(4)
+    const rule = findRule((candidate) => candidate.selector === '.mask')!
+    expect(rule.styles.color).toBe('transparent')
+    for (const bag of [rule.styles, ...Object.values(rule.contextStyles)]) {
+      expect('background' in bag).toBe(false)
+      expect('WebkitTextFillColor' in bag).toBe(false)
+      expect('--mask-token' in bag).toBe(false)
+      expect('padding' in bag).toBe(false)
+      expect('paddingTop' in bag).toBe(false)
+      expect('paddingRight' in bag).toBe(false)
+      expect('paddingBottom' in bag).toBe(false)
+      expect('paddingLeft' in bag).toBe(false)
+    }
+  })
+
+  it('destructive operations fail atomically when any selector or property is missing', async () => {
+    freshStore()
+    await executeAgentTool('site_apply_css', {
+      operation: 'merge',
+      css: '.safe { color: red; background: var(--surface); }',
+    })
+
+    const deleteResult = await executeAgentTool('site_apply_css', {
+      operation: 'delete',
+      selectors: ['.safe', '.missing'],
+    })
+    expectToolError(deleteResult)
+    expect(findRule((rule) => rule.selector === '.safe')).toBeDefined()
+
+    const removeResult = await executeAgentTool('site_apply_css', {
+      operation: 'remove-properties',
+      selectors: ['.safe'],
+      properties: ['background', 'border-image-source'],
+    })
+    expectToolError(removeResult)
+    const rule = findRule((candidate) => candidate.selector === '.safe')!
+    expect(rule.styles.background).toBe('var(--surface)')
+  })
+
   it('returns an error for CSS that parses to no rules', async () => {
     freshStore()
-    const result = await executeAgentTool('site_apply_css', { css: '/* just a comment */' })
+    const result = await executeAgentTool('site_apply_css', {
+      operation: 'merge',
+      css: '/* just a comment */',
+    })
     expectToolError(result)
     expect(result.error).toContain('No CSS rules parsed')
   })
@@ -1108,7 +1311,10 @@ describe('executeAgentTool — class identifier resolution', () => {
       html: '<button>Click</button>',
     })
     const nodeId = expectNodeIds(insertResult)[0]
-    await executeAgentTool('site_apply_css', { css: '.btn-hero { color: #fff; }' })
+    await executeAgentTool('site_apply_css', {
+      operation: 'merge',
+      css: '.btn-hero { color: #fff; }',
+    })
 
     const result = await executeAgentTool('site_assign_class', { nodeId, classId: 'btn-hero' })
     expectToolOk(result)
@@ -1138,7 +1344,10 @@ describe('executeAgentTool — class identifier resolution', () => {
       html: '<button>Click</button>',
     })
     const nodeId = expectNodeIds(insertResult)[0]
-    await executeAgentTool('site_apply_css', { css: '.removable { color: #fff; }' })
+    await executeAgentTool('site_apply_css', {
+      operation: 'merge',
+      css: '.removable { color: #fff; }',
+    })
     await executeAgentTool('site_assign_class', { nodeId, classId: 'removable' })
 
     const result = await executeAgentTool('site_remove_class', { nodeId, classId: 'removable' })
diff --git a/src/__tests__/agent/renderEvidence.test.ts b/src/__tests__/agent/renderEvidence.test.ts
index 6a8e48dc2..517510cb7 100644
--- a/src/__tests__/agent/renderEvidence.test.ts
+++ b/src/__tests__/agent/renderEvidence.test.ts
@@ -333,6 +333,10 @@ describe('captureAgentRenderSnapshot — on-demand browser bridge', () => {
     wrapper.dataset.nodeId = 'title'
     wrapper.dataset.moduleId = 'base.text'
     wrapper.textContent = 'Overflowing headline'
+    wrapper.style.backgroundImage = 'linear-gradient(red, blue)'
+    wrapper.style.backgroundClip = 'text'
+    wrapper.style.setProperty('-webkit-background-clip', 'text')
+    wrapper.style.setProperty('-webkit-text-fill-color', 'transparent')
     setRect(wrapper, { x: 8, y: 16, width: 420, height: 64 })
     body.appendChild(wrapper)
 
@@ -345,6 +349,12 @@ describe('captureAgentRenderSnapshot — on-demand browser bridge', () => {
     expect(snapshot!.breakpointId).toBe('mobile')
     expect(snapshot!.layout.viewport.scrollWidth).toBe(420)
     expect(snapshot!.layout.nodes[0].nodeId).toBe('title')
+    expect(snapshot!.layout.nodes[0].computed).toMatchObject({
+      backgroundImage: 'linear-gradient(red, blue)',
+      backgroundClip: 'text',
+      webkitBackgroundClip: 'text',
+      webkitTextFillColor: 'transparent',
+    })
     expect(snapshot!.layout.warnings.some((warning) =>
       warning.type === 'horizontal-overflow' && warning.nodeId === 'title',
     )).toBe(true)
@@ -387,6 +397,24 @@ describe('captureAgentRenderSnapshot — on-demand browser bridge', () => {
     expect(snapshot!.layout.images.find((image) => image.nodeId === 'deferred-image')?.complete).toBe(false)
   })
 
+  it('bounds computed background images before returning them as model-visible evidence', async () => {
+    const doc = mountFrame('desktop')
+    const node = doc.createElement('div')
+    node.dataset.nodeId = 'large-background'
+    node.style.backgroundImage = `url("data:image/png;base64,${'A'.repeat(1_000)}")`
+    setRect(node, { width: 100, height: 100 })
+    doc.body.appendChild(node)
+
+    const snapshot = await captureAgentRenderSnapshot({
+      breakpointId: 'desktop',
+      captureScreenshot: false,
+    })
+
+    const backgroundImage = snapshot!.layout.nodes[0].computed.backgroundImage
+    expect(backgroundImage).toHaveLength(500)
+    expect(backgroundImage.endsWith('...[truncated]')).toBe(true)
+  })
+
   it('scopes the capture to a node subtree when nodeId is given', async () => {
     const doc = mountFrame('desktop')
 
diff --git a/src/__tests__/agent/toolCallDisplay.test.ts b/src/__tests__/agent/toolCallDisplay.test.ts
new file mode 100644
index 000000000..0012d97fb
--- /dev/null
+++ b/src/__tests__/agent/toolCallDisplay.test.ts
@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'bun:test'
+import { getToolCallDisplay } from '@site/panels/AgentPanel'
+
+describe('site_apply_css tool-call display', () => {
+  it('distinguishes each CSS mutation operation', () => {
+    expect(getToolCallDisplay('site_apply_css', {
+      operation: 'merge',
+      css: '.card { color: red; }',
+    })).toMatchObject({ title: 'Updating CSS', detail: '.card', tone: 'style' })
+
+    expect(getToolCallDisplay('site_apply_css', {
+      operation: 'replace',
+      css: '.card { color: blue; }',
+    })).toMatchObject({ title: 'Replacing CSS', detail: '.card', tone: 'style' })
+
+    expect(getToolCallDisplay('site_apply_css', {
+      operation: 'delete',
+      selectors: ['.card', '.legacy'],
+    })).toMatchObject({
+      title: 'Deleting CSS rules',
+      detail: '.card, .legacy',
+      tone: 'danger',
+    })
+
+    expect(getToolCallDisplay('site_apply_css', {
+      operation: 'remove-properties',
+      selectors: ['.card'],
+      properties: ['background', 'background-clip'],
+    })).toMatchObject({
+      title: 'Removing CSS properties',
+      detail: '.card · background, background-clip',
+      tone: 'danger',
+    })
+  })
+})
diff --git a/src/__tests__/architecture/module-size-budgets.test.ts b/src/__tests__/architecture/module-size-budgets.test.ts
index 40638c13d..7341abce4 100644
--- a/src/__tests__/architecture/module-size-budgets.test.ts
+++ b/src/__tests__/architecture/module-size-budgets.test.ts
@@ -109,7 +109,6 @@ const GRANDFATHERED: Record<string, number> = {
   'src/core/page-tree/mutations.ts': 760,
   // server/plugins/host/handlers/content.ts graduated (786 → 661) when the
   // DB→wire projection helpers moved to contentProjection.ts.
-  'src/core/siteImport/cssToStyleRules.ts': 708,
   'src/admin/pages/site/panels/TypographyPanel/FontsSection/AddGoogleFontDialog.tsx': 751,
   'src/core/markdown/markdownDocument.ts': 748,
   'src/admin/pages/dashboard/DashboardPage.tsx': 732,
diff --git a/src/__tests__/canvas/classStyleInjector.test.ts b/src/__tests__/canvas/classStyleInjector.test.ts
index 461896bf6..bbc33ed70 100644
--- a/src/__tests__/canvas/classStyleInjector.test.ts
+++ b/src/__tests__/canvas/classStyleInjector.test.ts
@@ -112,6 +112,14 @@ describe('generateCanvasClassCSS', () => {
     expect(css).not.toContain('/uploads/hero.png')
   })
 
+  it('uses the same declaration priorities as published CSS', () => {
+    const rule = makeClass('notice', { color: 'red' })
+    rule.stylePriorities = { color: 'important' }
+    expect(generateCanvasClassCSS({ notice: rule }, [])).toContain(
+      'color: red !important;',
+    )
+  })
+
   it('emits sanitized raw @keyframes rules, matching the published output', () => {
     // Regression: the canvas used to skip `rawCss` rules entirely, so
     // imported keyframe animations published fine but never played in the
@@ -284,6 +292,19 @@ describe('generateForcedStateCSS', () => {
     expect(css).toContain('font-weight: 700')
   })
 
+  it('keeps important declarations in forced-state previews', () => {
+    const rule = hoverRule({ color: 'red' }, { mobile: { color: 'blue' } })
+    rule.stylePriorities = { color: 'important' }
+    rule.contextStylePriorities = { mobile: { color: 'important' } }
+    const css = generateForcedStateCSS(
+      'node-1',
+      rule,
+      [{ id: 'mobile', width: 375 }],
+    )
+    expect(css).toContain('color: red !important;')
+    expect(css).toContain('color: blue !important;')
+  })
+
   it('emits per-breakpoint overrides under the breakpoint media query, node-scoped', () => {
     const css = generateForcedStateCSS(
       'node-1',
diff --git a/src/__tests__/editor-store/ambientRule.test.ts b/src/__tests__/editor-store/ambientRule.test.ts
index adb0ea663..09db3c050 100644
--- a/src/__tests__/editor-store/ambientRule.test.ts
+++ b/src/__tests__/editor-store/ambientRule.test.ts
@@ -251,4 +251,27 @@ describe('parseStyleRule persisted shape', () => {
       updatedAt: 0,
     })).toBeNull()
   })
+
+  it('keeps sparse declaration priorities and drops invalid or orphaned entries', async () => {
+    const { parseStyleRule } = await import('@core/page-tree')
+    const parsed = parseStyleRule({
+      id: 'x',
+      name: 'x',
+      kind: 'class',
+      selector: '.x',
+      order: 0,
+      styles: { color: 'red' },
+      stylePriorities: { color: 'important', gap: 'important', display: 'normal' },
+      contextStyles: { mobile: { color: 'blue' } },
+      contextStylePriorities: {
+        mobile: { color: 'important', gap: 'important' },
+        orphan: { color: 'important' },
+      },
+      createdAt: 0,
+      updatedAt: 0,
+    })
+
+    expect(parsed?.stylePriorities).toEqual({ color: 'important' })
+    expect(parsed?.contextStylePriorities).toEqual({ mobile: { color: 'important' } })
+  })
 })
diff --git a/src/__tests__/editor-store/styleRuleSlice.test.ts b/src/__tests__/editor-store/styleRuleSlice.test.ts
index 1a08e9113..c18d877f6 100644
--- a/src/__tests__/editor-store/styleRuleSlice.test.ts
+++ b/src/__tests__/editor-store/styleRuleSlice.test.ts
@@ -13,6 +13,7 @@
 
 import { describe, it, expect, beforeEach } from 'bun:test'
 import { useEditorStore } from '@site/store/store'
+import type { NewStyleRule } from '@core/siteImport'
 
 // ---------------------------------------------------------------------------
 // Test helpers
@@ -220,6 +221,50 @@ describe('styleRuleSlice.setClassContextStyles', () => {
   })
 })
 
+// ---------------------------------------------------------------------------
+// applyCssRules
+// ---------------------------------------------------------------------------
+
+describe('styleRuleSlice.applyCssRules', () => {
+  it('skips identical writes and prunes priority metadata when values are cleared', () => {
+    setupSite()
+    const incoming: NewStyleRule = {
+      name: 'priority',
+      kind: 'class',
+      selector: '.priority',
+      order: 0,
+      styles: { color: 'red' },
+      stylePriorities: { color: 'important' },
+      contextStyles: { mobile: { color: 'blue' } },
+      contextStylePriorities: { mobile: { color: 'important' } },
+    }
+
+    expect(getStore().applyCssRules([incoming], [], 'merge')).toEqual({
+      created: 1,
+      updated: 0,
+      blockedSelectors: [],
+    })
+    const rule = Object.values(useEditorStore.getState().site!.styleRules)
+      .find((candidate) => candidate.selector === '.priority')!
+    const historyBeforeNoop = historyLength()
+    const updatedAtBeforeNoop = rule.updatedAt
+
+    expect(getStore().applyCssRules([incoming], [], 'merge')).toEqual({
+      created: 0,
+      updated: 0,
+      blockedSelectors: [],
+    })
+    expect(historyLength()).toBe(historyBeforeNoop)
+    expect(useEditorStore.getState().site!.styleRules[rule.id].updatedAt).toBe(updatedAtBeforeNoop)
+
+    getStore().updateClassStyles(rule.id, { color: undefined })
+    getStore().setClassContextStyles(rule.id, 'mobile', { color: undefined })
+    const cleared = useEditorStore.getState().site!.styleRules[rule.id]
+    expect(cleared.stylePriorities).toBeUndefined()
+    expect(cleared.contextStylePriorities).toBeUndefined()
+  })
+})
+
 // ---------------------------------------------------------------------------
 // removeClassStyleProperty
 // ---------------------------------------------------------------------------
diff --git a/src/__tests__/page-tree/scopedClassClone.test.ts b/src/__tests__/page-tree/scopedClassClone.test.ts
index 861b77ff0..642156aa2 100644
--- a/src/__tests__/page-tree/scopedClassClone.test.ts
+++ b/src/__tests__/page-tree/scopedClassClone.test.ts
@@ -60,6 +60,11 @@ describe('cloneScopedClassesForNodeMap', () => {
     const classes: Record<string, StyleRule> = {
       'c-scoped': makeScopedClass('c-scoped', 'n1'),
     }
+    classes['c-scoped'].stylePriorities = { backgroundColor: 'important' }
+    classes['c-scoped'].contextStyles.mobile = { color: 'red' }
+    classes['c-scoped'].contextStylePriorities = {
+      mobile: { color: 'important' },
+    }
 
     const { added, classIdRemap } = cloneScopedClassesForNodeMap(idMap, classes)
 
@@ -70,6 +75,14 @@ describe('cloneScopedClassesForNodeMap', () => {
     expect(added[0].styles).toEqual({ backgroundColor: 'red' })
     // The cloned class is a fresh object, not a reference share.
     expect(added[0].styles).not.toBe(classes['c-scoped'].styles)
+    expect(added[0].stylePriorities).toEqual({ backgroundColor: 'important' })
+    expect(added[0].stylePriorities).not.toBe(classes['c-scoped'].stylePriorities)
+    expect(added[0].contextStylePriorities).toEqual({
+      mobile: { color: 'important' },
+    })
+    expect(added[0].contextStylePriorities?.mobile).not.toBe(
+      classes['c-scoped'].contextStylePriorities?.mobile,
+    )
     // classIdRemap maps old → new id.
     expect(classIdRemap.get('c-scoped')).toBe(added[0].id)
   })
diff --git a/src/__tests__/publisher/classStyleInjector.test.ts b/src/__tests__/publisher/classStyleInjector.test.ts
index 5adb0899c..a33efc0af 100644
--- a/src/__tests__/publisher/classStyleInjector.test.ts
+++ b/src/__tests__/publisher/classStyleInjector.test.ts
@@ -73,6 +73,17 @@ describe('bagToCSS', () => {
     expect(css).toBe('  font-size: 16px;')
   })
 
+  it('emits sparse declaration priority separately from the property value', () => {
+    const css = bagToCSS(
+      { color: 'red', display: 'block' },
+      {},
+      { color: 'important' },
+    )
+    expect(css).toContain('color: red !important;')
+    expect(css).toContain('display: block;')
+    expect(css).not.toContain('display: block !important')
+  })
+
   it('converts camelCase to kebab-case', () => {
     const css = bagToCSS({ backgroundColor: '#fff', borderTopLeftRadius: '4px' })
     expect(css).toContain('background-color: #fff;')
@@ -300,6 +311,27 @@ describe('bagToCSS', () => {
     expect(css).not.toContain('margin-left')
   })
 
+  it('collapses sides only when all four declaration priorities match', () => {
+    const styles = {
+      paddingTop: '8px',
+      paddingRight: '8px',
+      paddingBottom: '8px',
+      paddingLeft: '8px',
+    }
+    const allImportant = bagToCSS(styles, {}, {
+      paddingTop: 'important',
+      paddingRight: 'important',
+      paddingBottom: 'important',
+      paddingLeft: 'important',
+    })
+    expect(allImportant).toBe('  padding: 8px !important;')
+
+    const mixed = bagToCSS(styles, {}, { paddingTop: 'important' })
+    expect(mixed).not.toMatch(/^\s*padding:/m)
+    expect(mixed).toContain('padding-top: 8px !important;')
+    expect(mixed).toContain('padding-right: 8px;')
+  })
+
   it('refuses to collapse when a side is dropped by the sanitiser', () => {
     // expression(...) is sanitised to null → the collapse must abort and the
     // remaining safe sides emit as longhand instead.
@@ -398,6 +430,18 @@ describe('generateClassCSS', () => {
     expect(css).toContain('}')
   })
 
+  it('emits base and context priorities from the style rule metadata', () => {
+    const rule = makeClass('notice', { color: 'red' }, {
+      mobile: { color: 'blue' },
+    })
+    rule.stylePriorities = { color: 'important' }
+    rule.contextStylePriorities = { mobile: { color: 'important' } }
+
+    const css = generateClassCSS({ notice: rule }, BREAKPOINTS)
+    expect(css).toContain('color: red !important;')
+    expect(css).toContain('color: blue !important;')
+  })
+
   it('uses the class name in the selector, not the generated id', () => {
     const classes = { generatedId: makeClass('generatedId', { display: 'flex' }, {}, 'hero_title') }
     const css = generateClassCSS(classes, BREAKPOINTS)
diff --git a/src/__tests__/publisher/sizesResolver.test.ts b/src/__tests__/publisher/sizesResolver.test.ts
index 20719b5ff..2371fb2b6 100644
--- a/src/__tests__/publisher/sizesResolver.test.ts
+++ b/src/__tests__/publisher/sizesResolver.test.ts
@@ -443,6 +443,25 @@ describe('resolveAutoSizes — cascade fidelity', () => {
     expect(resolveAutoSizes('img', page, site)).toBe('min(100vw, 600px)')
   })
 
+  it('an earlier important class declaration beats a later normal class declaration', () => {
+    const page = makePage({
+      root: { moduleId: 'base.body', children: ['img'] },
+      img: { moduleId: 'base.image', classIds: ['narrow', 'wide'] },
+    })
+    const site = makeSite({
+      breakpoints: DESKTOP,
+      styleRules: {
+        narrow: makeClass('narrow', {
+          order: 0,
+          styles: { width: '200px' },
+          stylePriorities: { width: 'important' },
+        }),
+        wide: makeClass('wide', { order: 1, styles: { width: '600px' } }),
+      },
+    })
+    expect(resolveAutoSizes('img', page, site)).toBe('200px')
+  })
+
   it('node inlineStyles outrank class rules', () => {
     // The publisher injects node.inlineStyles as a literal style="…"
     // attribute, which beats every class — the resolver must agree or it
@@ -461,6 +480,27 @@ describe('resolveAutoSizes — cascade fidelity', () => {
     })
     expect(resolveAutoSizes('img', page, site)).toBe('min(100vw, 1200px)')
   })
+
+  it('an important class declaration outranks a normal inline declaration', () => {
+    const page = makePage({
+      root: { moduleId: 'base.body', children: ['img'] },
+      img: {
+        moduleId: 'base.image',
+        classIds: ['thumb'],
+        inlineStyles: { width: '100%' },
+      },
+    })
+    const site = makeSite({
+      breakpoints: DESKTOP,
+      styleRules: {
+        thumb: makeClass('thumb', {
+          styles: { width: '240px' },
+          stylePriorities: { width: 'important' },
+        }),
+      },
+    })
+    expect(resolveAutoSizes('img', page, site)).toBe('240px')
+  })
 })
 
 describe('resolveAutoSizes — grid placement fidelity', () => {
diff --git a/src/__tests__/siteImport/colorTokens.test.ts b/src/__tests__/siteImport/colorTokens.test.ts
index 6905f9e97..17f80fd3b 100644
--- a/src/__tests__/siteImport/colorTokens.test.ts
+++ b/src/__tests__/siteImport/colorTokens.test.ts
@@ -71,4 +71,14 @@ describe('extractRootColorTokens', () => {
     expect(colorTokens).toEqual([{ slug: 'brand', value: '#f00' }])
     expect(out[0].styles).toEqual({ color: 'red' })
   })
+
+  it('leaves an important custom property authored instead of losing its priority', () => {
+    const rule = ambient(':root', { '--brand': '#f00', '--plain': '#0f0' })
+    rule.stylePriorities = { '--brand': 'important' }
+    const { rules: out, colorTokens } = extractRootColorTokens([rule])
+
+    expect(colorTokens).toEqual([{ slug: 'plain', value: '#0f0' }])
+    expect(out[0].styles).toEqual({ '--brand': '#f00' })
+    expect(out[0].stylePriorities).toEqual({ '--brand': 'important' })
+  })
 })
diff --git a/src/__tests__/siteImport/cssToStyleRules-substitution.test.ts b/src/__tests__/siteImport/cssToStyleRules-substitution.test.ts
index 33e1630d0..82a1ec7b3 100644
--- a/src/__tests__/siteImport/cssToStyleRules-substitution.test.ts
+++ b/src/__tests__/siteImport/cssToStyleRules-substitution.test.ts
@@ -58,6 +58,12 @@ describe('cssToStyleRules — substitution declarations survive verbatim', () =>
     expect(rules[0].styles['--own']).toBe('12px')
   })
 
+  it('preserves priority on an encoded substitution declaration', () => {
+    const { rules } = cssToStyleRules(`.x { color: var(--ink) !important; }`)
+    expect(rules[0].styles.color).toBe('var(--ink)')
+    expect(rules[0].stylePriorities).toEqual({ color: 'important' })
+  })
+
   it('preserves var() declarations inside @media overrides', () => {
     const { rules } = cssToStyleRules(`
       .plan { color: red; }
diff --git a/src/__tests__/siteImport/cssToStyleRules.test.ts b/src/__tests__/siteImport/cssToStyleRules.test.ts
index a261b1959..c692b1526 100644
--- a/src/__tests__/siteImport/cssToStyleRules.test.ts
+++ b/src/__tests__/siteImport/cssToStyleRules.test.ts
@@ -139,6 +139,17 @@ describe('cssToStyleRules — @media → contextStyles (matched)', () => {
     expect(rules[0].styles).toEqual({})
     expect(rules[0].contextStyles.mobile).toMatchObject({ color: 'blue' })
   })
+
+  it('preserves declaration priority in a matched context', () => {
+    const { rules } = cssToStyleRules(
+      '@media (max-width: 768px) { .foo { color: blue !important } }',
+      { breakpoints: [{ id: 'mobile', width: 768 }] },
+    )
+    expect(rules[0].contextStyles.mobile.color).toBe('blue')
+    expect(rules[0].contextStylePriorities).toEqual({
+      mobile: { color: 'important' },
+    })
+  })
 })
 
 // ---------------------------------------------------------------------------
@@ -451,6 +462,22 @@ describe('cssToStyleRules — duplicate class names', () => {
     expect(warnings[0].selector).toBe('.foo')
   })
 
+  it('an earlier important declaration resists a later normal declaration', () => {
+    const { rules } = cssToStyleRules(
+      '.foo { color: red !important } .foo { color: blue }',
+    )
+    expect(rules[0].styles.color).toBe('red')
+    expect(rules[0].stylePriorities).toEqual({ color: 'important' })
+  })
+
+  it('a later important declaration replaces an earlier normal declaration', () => {
+    const { rules } = cssToStyleRules(
+      '.foo { color: red } .foo { color: blue !important }',
+    )
+    expect(rules[0].styles.color).toBe('blue')
+    expect(rules[0].stylePriorities).toEqual({ color: 'important' })
+  })
+
   it('ambient h1 duplicates are allowed (no dedup for ambient)', () => {
     // Two h1 rules are valid CSS (cascade resolves by source order)
     const { rules, warnings } = cssToStyleRules('h1 { color: red } h1 { color: blue }')
diff --git a/src/__tests__/siteImport/stylesheetModes.test.ts b/src/__tests__/siteImport/stylesheetModes.test.ts
index c85057787..10ad29c3a 100644
--- a/src/__tests__/siteImport/stylesheetModes.test.ts
+++ b/src/__tests__/siteImport/stylesheetModes.test.ts
@@ -110,6 +110,34 @@ describe('cross-sheet class conflicts', () => {
     expect(btnClassRules).toHaveLength(1)
   })
 
+  it('uses important-aware cascade semantics when comparing definitions', () => {
+    const plan = buildImportPlan({
+      fileMap: twoPageFileMap(
+        '.btn { color: red !important; } .btn { color: blue; }',
+        '.btn { color: red !important; }',
+      ),
+      currentSite: makeEmptySiteDocument(),
+    })
+
+    expect(plan.conflicts.crossSheetClasses).toHaveLength(0)
+  })
+
+  it('preserves priority when materialising a renamed divergent definition', () => {
+    const plan = buildImportPlan({
+      fileMap: twoPageFileMap(
+        '.btn { color: red; }',
+        '.btn { color: blue !important; }',
+      ),
+      currentSite: makeEmptySiteDocument(),
+    })
+    const resolved = resolveWithDefaults(plan)
+    const renamed = resolved.styleRules.find(
+      (rule) => rule.kind === 'class' && rule.name === 'btn-2',
+    )
+    expect(renamed?.styles.color).toBe('blue')
+    expect(renamed?.stylePriorities).toEqual({ color: 'important' })
+  })
+
   it('keep-first (skip) drops the divergent definition and binds its pages to the first', () => {
     const plan = buildImportPlan({
       fileMap: twoPageFileMap(
diff --git a/src/admin/pages/site/agent/cssTools.ts b/src/admin/pages/site/agent/cssTools.ts
new file mode 100644
index 000000000..3c99c84c2
--- /dev/null
+++ b/src/admin/pages/site/agent/cssTools.ts
@@ -0,0 +1,88 @@
+import {
+  aiToolError,
+  aiToolOk,
+  type AiToolOutput,
+  type ApplyCssInput,
+} from '@core/ai'
+import type { ConditionDef } from '@core/page-tree'
+import { cssToStyleRules, type NewStyleRule } from '@core/siteImport'
+import type { EditorStore } from '@site/store/types'
+import { getAgentStoreApi } from './storeRef'
+
+// Live access to the editor store. Routed through `./storeRef` so this module
+// has no static import edge back into `editor-store/store.ts`.
+const getStoreState = (): EditorStore => getAgentStoreApi<EditorStore>().getState()
+
+/**
+ * Parse CSS harvested from agent-supplied HTML into registry rules. The live
+ * site's viewport contexts let matching `@media` rules fold into the
+ * corresponding context; unmatched conditions remain reusable site rules.
+ */
+export function parseImportedStyleCss(styleCss: string): {
+  rules: NewStyleRule[]
+  conditions: ConditionDef[]
+} {
+  if (!styleCss.trim()) return { rules: [], conditions: [] }
+  const site = getStoreState().site
+  const breakpoints = site
+    ? site.breakpoints.map((breakpoint) => ({
+        id: breakpoint.id,
+        width: breakpoint.width,
+        mediaQuery: breakpoint.mediaQuery,
+      }))
+    : []
+  const { rules, conditions } = cssToStyleRules(styleCss, { breakpoints })
+  return { rules, conditions }
+}
+
+/** Apply an exact-selector CSS mutation to the live site's style registry. */
+export function runApplyCss(input: ApplyCssInput): AiToolOutput {
+  if (input.operation === 'delete') {
+    const result = getStoreState().deleteCssRules(input.selectors)
+    if (result.missingSelectors.length > 0) {
+      return aiToolError(`CSS selectors not found: ${result.missingSelectors.join(', ')}`)
+    }
+    if (result.blockedSelectors.length > 0) {
+      return aiToolError(
+        `Framework-generated CSS selectors are locked: ${result.blockedSelectors.join(', ')}`,
+      )
+    }
+    return aiToolOk({ cssRulesDeleted: result.deleted })
+  }
+
+  if (input.operation === 'remove-properties') {
+    const result = getStoreState().removeCssRuleProperties(input.selectors, input.properties)
+    if (result.missingSelectors.length > 0) {
+      return aiToolError(`CSS selectors not found: ${result.missingSelectors.join(', ')}`)
+    }
+    if (result.blockedSelectors.length > 0) {
+      return aiToolError(
+        `Framework-generated CSS selectors are locked: ${result.blockedSelectors.join(', ')}`,
+      )
+    }
+    if (result.missingProperties.length > 0) {
+      return aiToolError(
+        `CSS properties are not set on the requested selectors: ${result.missingProperties.join(', ')}`,
+      )
+    }
+    return aiToolOk({
+      cssRulesUpdated: result.updated,
+      cssPropertiesRemoved: result.removed,
+    })
+  }
+
+  const { rules, conditions } = parseImportedStyleCss(input.css)
+  if (rules.length === 0) {
+    return aiToolError(
+      'No CSS rules parsed. Provide CSS like ".hero { color: var(--primary) }" or ' +
+        '"nav a:hover { text-decoration: underline }".',
+    )
+  }
+  const result = getStoreState().applyCssRules(rules, conditions, input.operation)
+  if (result.blockedSelectors.length > 0) {
+    return aiToolError(
+      `Framework-generated CSS selectors are locked: ${result.blockedSelectors.join(', ')}`,
+    )
+  }
+  return aiToolOk({ cssRulesCreated: result.created, cssRulesUpdated: result.updated })
+}
diff --git a/src/admin/pages/site/agent/executor.ts b/src/admin/pages/site/agent/executor.ts
index 1294bea1e..145dfe032 100644
--- a/src/admin/pages/site/agent/executor.ts
+++ b/src/admin/pages/site/agent/executor.ts
@@ -56,7 +56,6 @@ import {
   type MoveNodeInput,
   type RenameNodeInput,
   type DuplicateNodeInput,
-  type ApplyCssInput,
   type AssignClassInput,
   type RemoveClassInput,
   type AddPageInput,
@@ -70,9 +69,7 @@ import type { EditorStore } from '@site/store/types'
 import { registry } from '@core/module-engine'
 import { sanitizeRichtext, isRichtextPropKey } from '@core/sanitize'
 import { importHtml } from '@core/htmlImport'
-import { cssToStyleRules } from '@core/siteImport'
-import type { NewStyleRule } from '@core/siteImport'
-import type { BaseNode, ConditionDef, PageTemplateConfig } from '@core/page-tree'
+import type { BaseNode, PageTemplateConfig } from '@core/page-tree'
 import { renderNode, type RenderConfig, type RenderAccumulators } from '@core/publisher'
 import { getAgentStoreApi } from './storeRef'
 import {
@@ -89,6 +86,7 @@ import {
   runWriteCodeAsset,
 } from './codeAssetTools'
 import { runRenderSnapshotAtBreakpoint } from './renderSnapshotAtBreakpoint'
+import { parseImportedStyleCss, runApplyCss } from './cssTools'
 import {
   activeDocumentNodes,
   activeRenderPage,
@@ -104,26 +102,6 @@ import { getErrorMessage } from '@core/utils/errorMessage'
 // has no static import edge back into `editor-store/store.ts`.
 const getStoreState = (): EditorStore => getAgentStoreApi<EditorStore>().getState()
 
-/**
- * Parse the CSS harvested from `<style>` blocks in an agent-supplied HTML
- * snippet into registry rules. Uses the live site's viewport contexts so any
- * matching `@media` folds into that viewport's contextStyles;
- * unmatched conditions round-trip as reusable site conditions. Returns empty
- * arrays for an empty/whitespace-only snippet.
- */
-function parseImportedStyleCss(styleCss: string): {
-  rules: NewStyleRule[]
-  conditions: ConditionDef[]
-} {
-  if (!styleCss.trim()) return { rules: [], conditions: [] }
-  const site = getStoreState().site
-  const breakpoints = site
-    ? site.breakpoints.map((b) => ({ id: b.id, width: b.width, mediaQuery: b.mediaQuery }))
-    : []
-  const { rules, conditions } = cssToStyleRules(styleCss, { breakpoints })
-  return { rules, conditions }
-}
-
 // ---------------------------------------------------------------------------
 // Tool input validation
 //
@@ -264,8 +242,13 @@ function runInsertHtml(input: InsertHtmlInput): AiToolOutput {
     // `site_apply_css` tool is the canonical path for this; insertHtml stays forgiving
     // when a CSS-only payload arrives here.)
     if (rules.length > 0 || conditions.length > 0) {
-      const { created, updated } = getStoreState().upsertCssRules(rules, conditions)
-      return aiToolOk({ cssRulesCreated: created, cssRulesUpdated: updated })
+      const result = getStoreState().applyCssRules(rules, conditions, 'merge')
+      if (result.blockedSelectors.length > 0) {
+        return aiToolError(
+          `Framework-generated CSS selectors are locked: ${result.blockedSelectors.join(', ')}`,
+        )
+      }
+      return aiToolOk({ cssRulesCreated: result.created, cssRulesUpdated: result.updated })
     }
     const scriptHint = stripped.scripts > 0 || stripped.inlineHandlers > 0
       ? ' Scripts and inline event handlers are stripped from HTML imports; create runtime behavior with site_write_code_asset({ type:"script", ... }) instead.'
@@ -380,8 +363,13 @@ function runReplaceNodeHtml(input: ReplaceNodeHtmlInput): AiToolOutput {
     // the subtree intact and just upsert its rules — same forgiving behaviour
     // as insertHtml. Wiping children to insert nothing would be surprising.
     if (rules.length > 0 || conditions.length > 0) {
-      const { created, updated } = getStoreState().upsertCssRules(rules, conditions)
-      return aiToolOk({ cssRulesCreated: created, cssRulesUpdated: updated })
+      const result = getStoreState().applyCssRules(rules, conditions, 'merge')
+      if (result.blockedSelectors.length > 0) {
+        return aiToolError(
+          `Framework-generated CSS selectors are locked: ${result.blockedSelectors.join(', ')}`,
+        )
+      }
+      return aiToolOk({ cssRulesCreated: result.created, cssRulesUpdated: result.updated })
     }
     const scriptHint = stripped.scripts > 0 || stripped.inlineHandlers > 0
       ? ' Scripts and inline event handlers are stripped from HTML imports; create runtime behavior with site_write_code_asset({ type:"script", ... }) instead.'
@@ -466,29 +454,6 @@ function runRenameNode(input: RenameNodeInput): AiToolOutput {
   return aiToolOk()
 }
 
-/**
- * Apply authored CSS text to the site's style registry.
- *
- * The single styling-by-CSS tool: parse the CSS with the SAME engine the HTML
- * importer uses (`cssToStyleRules` via `parseImportedStyleCss`), then UPSERT
- * every rule — a bare `.foo {}` selector creates/edits a reusable class, any
- * other selector (`.hero a`, `a:hover`, `nav > li`, `::before`) creates/edits
- * an ambient rule, and `@media` folds into per-breakpoint/condition overrides.
- * Re-applying an existing selector EDITS it; this is what `updateClassStyles`
- * could not do for descendant/pseudo selectors.
- */
-function runApplyCss(input: ApplyCssInput): AiToolOutput {
-  const { rules, conditions } = parseImportedStyleCss(input.css)
-  if (rules.length === 0 && conditions.length === 0) {
-    return aiToolError(
-      'No CSS rules parsed. Provide CSS like ".hero { color: var(--primary) }" or ' +
-        '"nav a:hover { text-decoration: underline }".',
-    )
-  }
-  const { created, updated } = getStoreState().upsertCssRules(rules, conditions)
-  return aiToolOk({ cssRulesCreated: created, cssRulesUpdated: updated })
-}
-
 function runAssignClass(input: AssignClassInput): AiToolOutput {
   const store = getStoreState()
   const classId = resolveClassId(store, input.classId)
diff --git a/src/admin/pages/site/agent/renderEvidence.ts b/src/admin/pages/site/agent/renderEvidence.ts
index 9c2d7a32d..5a973ac9c 100644
--- a/src/admin/pages/site/agent/renderEvidence.ts
+++ b/src/admin/pages/site/agent/renderEvidence.ts
@@ -10,6 +10,8 @@ import type {
 import { getErrorMessage } from '@core/utils/errorMessage'
 
 const MAX_TEXT_LENGTH = 300
+const MAX_COMPUTED_BACKGROUND_IMAGE_LENGTH = 500
+const COMPUTED_STYLE_TRUNCATION_SUFFIX = '...[truncated]'
 const OVERFLOW_TOLERANCE_PX = 2
 const FRAME_WAIT_TIMEOUT_MS = 5_000
 const FRAME_WAIT_POLL_MS = 16
@@ -315,6 +317,10 @@ function collectNodeLayout(
       overflow: computed.overflow,
       color: computed.color,
       backgroundColor: computed.backgroundColor,
+      backgroundImage: boundComputedBackgroundImage(computed.backgroundImage),
+      backgroundClip: computed.backgroundClip,
+      webkitBackgroundClip: computed.getPropertyValue('-webkit-background-clip'),
+      webkitTextFillColor: computed.getPropertyValue('-webkit-text-fill-color'),
       fontSize: computed.fontSize,
       lineHeight: computed.lineHeight,
     },
@@ -544,6 +550,14 @@ function trimText(text: string): string {
     : normalized
 }
 
+function boundComputedBackgroundImage(value: string): string {
+  if (value.length <= MAX_COMPUTED_BACKGROUND_IMAGE_LENGTH) return value
+  return `${value.slice(
+    0,
+    MAX_COMPUTED_BACKGROUND_IMAGE_LENGTH - COMPUTED_STYLE_TRUNCATION_SUFFIX.length,
+  )}${COMPUTED_STYLE_TRUNCATION_SUFFIX}`
+}
+
 function round(value: number): number {
   return Math.round(value * 100) / 100
 }
diff --git a/src/admin/pages/site/agent/types.ts b/src/admin/pages/site/agent/types.ts
index 80daf6bef..6628761db 100644
--- a/src/admin/pages/site/agent/types.ts
+++ b/src/admin/pages/site/agent/types.ts
@@ -209,6 +209,10 @@ export interface AgentLayoutNodeContext {
     overflow: string
     color: string
     backgroundColor: string
+    backgroundImage: string
+    backgroundClip: string
+    webkitBackgroundClip: string
+    webkitTextFillColor: string
     fontSize: string
     lineHeight: string
   }
diff --git a/src/admin/pages/site/canvas/canvasClassCss.ts b/src/admin/pages/site/canvas/canvasClassCss.ts
index 546bae592..84547f0b1 100644
--- a/src/admin/pages/site/canvas/canvasClassCss.ts
+++ b/src/admin/pages/site/canvas/canvasClassCss.ts
@@ -148,7 +148,10 @@ export function generatePreviewClassCSS(
   preview: { breakpointId?: string | null; styles: Record<string, unknown> },
   responsiveOptions: ResponsiveCssOptions = {},
 ): string {
-  const decls = bagToCSS(preview.styles, responsiveOptions)
+  const priorities = preview.breakpointId
+    ? cls.contextStylePriorities?.[preview.breakpointId]
+    : cls.stylePriorities
+  const decls = bagToCSS(preview.styles, responsiveOptions, priorities)
   if (!decls) return ''
   const selector = styleRuleSelector(cls)
   const doubled = `${selector}${selector}`
@@ -209,7 +212,12 @@ export function generateForcedStateCSS(
   }
 
   const emitRule = createStyleRuleCssEmitter(breakpoints, conditions, responsiveOptions)
-  return emitRule(selector, baseStyles, contextStyles).join('\n\n')
+  return emitRule(selector, {
+    styles: baseStyles,
+    stylePriorities: rule.stylePriorities,
+    contextStyles,
+    contextStylePriorities: rule.contextStylePriorities,
+  }).join('\n\n')
 }
 
 function escapeCssAttribute(value: string): string {
diff --git a/src/admin/pages/site/panels/AgentPanel/index.ts b/src/admin/pages/site/panels/AgentPanel/index.ts
index 4959a7153..02058f9e8 100644
--- a/src/admin/pages/site/panels/AgentPanel/index.ts
+++ b/src/admin/pages/site/panels/AgentPanel/index.ts
@@ -4,3 +4,4 @@ export {
   getContextMeterMetrics,
 } from './contextMeterMetrics'
 export type { ContextMeterMetrics, ContextMeterTone } from './contextMeterMetrics'
+export { getToolCallDisplay } from './toolCallDisplay'
diff --git a/src/admin/pages/site/panels/AgentPanel/toolCallDisplay.ts b/src/admin/pages/site/panels/AgentPanel/toolCallDisplay.ts
index 7e140cfb5..e0fbdc73b 100644
--- a/src/admin/pages/site/panels/AgentPanel/toolCallDisplay.ts
+++ b/src/admin/pages/site/panels/AgentPanel/toolCallDisplay.ts
@@ -79,7 +79,7 @@ export function getToolCallDisplay(actionType: string, params: unknown): ToolCal
       return display('Duplicating node', duplicateNodeDetail(p.nodeId, p.count), 'copy', 'write')
 
     case 'apply_css':
-      return display('Updating CSS', summarizeCss(optionalString(p.css)), 'style', 'style')
+      return cssOperationDisplay(p)
     case 'assign_class':
       return display('Assigning class', classDetail(p.classId, p.nodeId), 'class', 'style')
     case 'remove_class':
@@ -341,6 +341,31 @@ function summarizeCss(css: string): string {
   return selectors.length > 2 ? `${head} +${selectors.length - 2}` : head
 }
 
+function cssOperationDisplay(params: Record<string, unknown>): ToolCallDisplay {
+  const operation = optionalString(params.operation)
+  if (operation === 'replace') {
+    return display('Replacing CSS', summarizeCss(optionalString(params.css)), 'style', 'style')
+  }
+  if (operation === 'delete') {
+    return display('Deleting CSS rules', summarizeStringList(params.selectors), 'delete', 'danger')
+  }
+  if (operation === 'remove-properties') {
+    const selectors = summarizeStringList(params.selectors)
+    const properties = summarizeStringList(params.properties)
+    const detail = [selectors, properties].filter(Boolean).join(' · ')
+    return display('Removing CSS properties', detail, 'style', 'danger')
+  }
+  return display('Updating CSS', summarizeCss(optionalString(params.css)), 'style', 'style')
+}
+
+function summarizeStringList(value: unknown): string {
+  if (!Array.isArray(value)) return ''
+  const items = value.filter((item): item is string => typeof item === 'string' && item.length > 0)
+  if (items.length === 0) return ''
+  const head = items.slice(0, 2).join(', ')
+  return items.length > 2 ? `${head} +${items.length - 2}` : head
+}
+
 function humanizeToolName(toolName: string): string {
   return toolName
     .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
diff --git a/src/admin/pages/site/store/slices/styleRule/conditionActions.ts b/src/admin/pages/site/store/slices/styleRule/conditionActions.ts
index a49d612f1..0e198c7e3 100644
--- a/src/admin/pages/site/store/slices/styleRule/conditionActions.ts
+++ b/src/admin/pages/site/store/slices/styleRule/conditionActions.ts
@@ -56,6 +56,10 @@ export function createConditionActions({ get, mutateSite }: SiteSliceHelpers): C
         for (const cls of Object.values(site.styleRules)) {
           if (condId in cls.contextStyles) {
             delete cls.contextStyles[condId]
+            delete cls.contextStylePriorities?.[condId]
+            if (cls.contextStylePriorities && Object.keys(cls.contextStylePriorities).length === 0) {
+              delete cls.contextStylePriorities
+            }
             cls.updatedAt = Date.now()
           }
         }
@@ -129,6 +133,13 @@ export function createConditionActions({ get, mutateSite }: SiteSliceHelpers): C
         const draftClass = site.styleRules[classId]
         if (!draftClass || !(contextId in draftClass.contextStyles)) return false
         delete draftClass.contextStyles[contextId]
+        delete draftClass.contextStylePriorities?.[contextId]
+        if (
+          draftClass.contextStylePriorities
+          && Object.keys(draftClass.contextStylePriorities).length === 0
+        ) {
+          delete draftClass.contextStylePriorities
+        }
         draftClass.updatedAt = Date.now()
         return true
       })
diff --git a/src/admin/pages/site/store/slices/styleRule/crudActions.ts b/src/admin/pages/site/store/slices/styleRule/crudActions.ts
index 4056c6266..09e51b751 100644
--- a/src/admin/pages/site/store/slices/styleRule/crudActions.ts
+++ b/src/admin/pages/site/store/slices/styleRule/crudActions.ts
@@ -9,6 +9,9 @@ import type { StyleRule } from '@core/page-tree'
 import { classKindSelector } from '@core/page-tree'
 import { isGeneratedClassLocked } from '@core/page-tree'
 import { assertValidCssClassName } from '@core/page-tree'
+import { styleRuleSelector } from '@core/page-tree'
+import { cssPropertyNameToStorageKey } from '@core/css-substitution'
+import type { NewStyleRule } from '@core/siteImport'
 import { isValidCssSelector } from '../../styleRuleRename'
 import type { SiteSliceHelpers } from '../site/types'
 import type { StyleRuleSlice } from './types'
@@ -20,9 +23,266 @@ type CrudActions = Pick<
   | 'createAmbientRule'
   | 'updateClassStyles'
   | 'setClassContextStyles'
-  | 'upsertCssRules'
+  | 'applyCssRules'
+  | 'deleteCssRules'
+  | 'removeCssRuleProperties'
 >
 
+type PriorityBag = Record<string, 'important'>
+
+interface RulePayload {
+  styles: Record<string, unknown>
+  contextStyles: Record<string, Record<string, unknown>>
+  stylePriorities?: PriorityBag
+  contextStylePriorities?: Record<string, PriorityBag>
+  rawCss?: string
+}
+
+function clonePriorityBag(priorities: PriorityBag | undefined): PriorityBag | undefined {
+  if (!priorities || Object.keys(priorities).length === 0) return undefined
+  return { ...priorities }
+}
+
+function cloneContextStyles(
+  contexts: Record<string, Record<string, unknown>> | undefined,
+): Record<string, Record<string, unknown>> {
+  return Object.fromEntries(
+    Object.entries(contexts ?? {}).map(([contextId, styles]) => [contextId, { ...styles }]),
+  )
+}
+
+function cloneContextPriorities(
+  contexts: Record<string, PriorityBag> | undefined,
+): Record<string, PriorityBag> | undefined {
+  if (!contexts) return undefined
+  const cloned = Object.fromEntries(
+    Object.entries(contexts)
+      .filter(([, priorities]) => Object.keys(priorities).length > 0)
+      .map(([contextId, priorities]) => [contextId, { ...priorities }]),
+  )
+  return Object.keys(cloned).length > 0 ? cloned : undefined
+}
+
+function payloadFromRule(rule: StyleRule | NewStyleRule): RulePayload {
+  return {
+    styles: { ...rule.styles },
+    contextStyles: cloneContextStyles(rule.contextStyles),
+    stylePriorities: clonePriorityBag(rule.stylePriorities),
+    contextStylePriorities: cloneContextPriorities(rule.contextStylePriorities),
+    ...(rule.rawCss !== undefined ? { rawCss: rule.rawCss } : {}),
+  }
+}
+
+function orderedBagEqual(
+  left: Record<string, unknown>,
+  right: Record<string, unknown>,
+): boolean {
+  const leftEntries = Object.entries(left)
+  const rightEntries = Object.entries(right)
+  if (leftEntries.length !== rightEntries.length) return false
+  return leftEntries.every(([key, value], index) => {
+    const rightEntry = rightEntries[index]
+    return rightEntry?.[0] === key && Object.is(rightEntry[1], value)
+  })
+}
+
+function priorityBagEqual(left: PriorityBag | undefined, right: PriorityBag | undefined): boolean {
+  const leftEntries = Object.entries(left ?? {})
+  const rightEntries = Object.entries(right ?? {})
+  if (leftEntries.length !== rightEntries.length) return false
+  return leftEntries.every(([key, value]) => right?.[key] === value)
+}
+
+function contextStylesEqual(
+  left: Record<string, Record<string, unknown>>,
+  right: Record<string, Record<string, unknown>>,
+): boolean {
+  const leftKeys = Object.keys(left)
+  const rightKeys = Object.keys(right)
+  if (leftKeys.length !== rightKeys.length) return false
+  return leftKeys.every((contextId) => {
+    const rightBag = right[contextId]
+    return rightBag !== undefined && orderedBagEqual(left[contextId], rightBag)
+  })
+}
+
+function contextPrioritiesEqual(
+  left: Record<string, PriorityBag> | undefined,
+  right: Record<string, PriorityBag> | undefined,
+): boolean {
+  const leftContexts = left ?? {}
+  const rightContexts = right ?? {}
+  const leftKeys = Object.keys(leftContexts)
+  const rightKeys = Object.keys(rightContexts)
+  if (leftKeys.length !== rightKeys.length) return false
+  return leftKeys.every((contextId) => priorityBagEqual(leftContexts[contextId], rightContexts[contextId]))
+}
+
+function payloadEqual(left: RulePayload, right: RulePayload): boolean {
+  return orderedBagEqual(left.styles, right.styles)
+    && contextStylesEqual(left.contextStyles, right.contextStyles)
+    && priorityBagEqual(left.stylePriorities, right.stylePriorities)
+    && contextPrioritiesEqual(left.contextStylePriorities, right.contextStylePriorities)
+    && Object.is(left.rawCss, right.rawCss)
+}
+
+/**
+ * Merge one declaration layer while moving every touched declaration to the
+ * end in the incoming authored order. Object.assign keeps an existing key in
+ * its old position, which can leave a longhand before a later shorthand and
+ * make an apparently successful CSS repair lose in the emitted rule.
+ */
+function mergeLayer(
+  current: Record<string, unknown>,
+  currentPriorities: PriorityBag | undefined,
+  patch: Record<string, unknown>,
+  patchPriorities: PriorityBag | undefined,
+  respectExistingImportant: boolean,
+): { styles: Record<string, unknown>; priorities?: PriorityBag } {
+  const acceptedPatchKeys = new Set<string>()
+  for (const key of Object.keys(patch)) {
+    if (
+      respectExistingImportant
+      && currentPriorities?.[key] === 'important'
+      && patchPriorities?.[key] !== 'important'
+    ) {
+      continue
+    }
+    acceptedPatchKeys.add(key)
+  }
+
+  const styles: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(current)) {
+    if (!acceptedPatchKeys.has(key)) styles[key] = value
+  }
+  for (const [key, value] of Object.entries(patch)) {
+    if (acceptedPatchKeys.has(key)) styles[key] = value
+  }
+
+  const priorities: PriorityBag = {}
+  for (const [key, priority] of Object.entries(currentPriorities ?? {})) {
+    if (!acceptedPatchKeys.has(key)) priorities[key] = priority
+  }
+  for (const key of acceptedPatchKeys) {
+    if (patchPriorities?.[key] === 'important') priorities[key] = 'important'
+  }
+
+  return {
+    styles,
+    ...(Object.keys(priorities).length > 0 ? { priorities } : {}),
+  }
+}
+
+function mergePayload(
+  current: RulePayload,
+  patch: RulePayload,
+  respectExistingImportant: boolean,
+): RulePayload {
+  const base = mergeLayer(
+    current.styles,
+    current.stylePriorities,
+    patch.styles,
+    patch.stylePriorities,
+    respectExistingImportant,
+  )
+  const contextStyles = cloneContextStyles(current.contextStyles)
+  const contextStylePriorities = cloneContextPriorities(current.contextStylePriorities) ?? {}
+
+  for (const [contextId, patchStyles] of Object.entries(patch.contextStyles)) {
+    const merged = mergeLayer(
+      contextStyles[contextId] ?? {},
+      contextStylePriorities[contextId],
+      patchStyles,
+      patch.contextStylePriorities?.[contextId],
+      respectExistingImportant,
+    )
+    contextStyles[contextId] = merged.styles
+    if (merged.priorities) contextStylePriorities[contextId] = merged.priorities
+    else delete contextStylePriorities[contextId]
+  }
+
+  return {
+    styles: base.styles,
+    contextStyles,
+    ...(base.priorities ? { stylePriorities: base.priorities } : {}),
+    ...(Object.keys(contextStylePriorities).length > 0 ? { contextStylePriorities } : {}),
+    ...(patch.rawCss !== undefined
+      ? { rawCss: patch.rawCss }
+      : current.rawCss !== undefined
+        ? { rawCss: current.rawCss }
+        : {}),
+  }
+}
+
+function writePayload(target: StyleRule, payload: RulePayload): void {
+  target.styles = payload.styles
+  target.contextStyles = payload.contextStyles
+  if (payload.stylePriorities) target.stylePriorities = payload.stylePriorities
+  else delete target.stylePriorities
+  if (payload.contextStylePriorities) {
+    target.contextStylePriorities = payload.contextStylePriorities
+  } else {
+    delete target.contextStylePriorities
+  }
+  if (payload.rawCss !== undefined) target.rawCss = payload.rawCss
+  else delete target.rawCss
+}
+
+interface ConsolidatedRule {
+  selector: string
+  source: NewStyleRule
+  payload: RulePayload
+}
+
+function consolidateIncomingRules(rules: NewStyleRule[]): ConsolidatedRule[] {
+  const bySelector = new Map<string, ConsolidatedRule>()
+  for (const rule of rules) {
+    const selector = styleRuleSelector(rule)
+    const existing = bySelector.get(selector)
+    if (!existing) {
+      const item = { selector, source: rule, payload: payloadFromRule(rule) }
+      bySelector.set(selector, item)
+      continue
+    }
+    // Multiple authored blocks with the same selector collapse exactly as the
+    // CSS cascade would: a prior important value beats a later normal one;
+    // otherwise the later declaration wins and moves to the end.
+    existing.payload = mergePayload(existing.payload, payloadFromRule(rule), true)
+  }
+  return [...bySelector.values()]
+}
+
+function rulesBySelector(rules: Record<string, StyleRule>): Map<string, StyleRule[]> {
+  const index = new Map<string, StyleRule[]>()
+  for (const rule of Object.values(rules)) {
+    const selector = styleRuleSelector(rule)
+    const matches = index.get(selector)
+    if (matches) matches.push(rule)
+    else index.set(selector, [rule])
+  }
+  return index
+}
+
+const SIDE_STORAGE_KEYS: Record<string, string[]> = {
+  padding: ['padding', 'paddingTop', 'paddingRight', 'paddingBottom', 'paddingLeft'],
+  margin: ['margin', 'marginTop', 'marginRight', 'marginBottom', 'marginLeft'],
+}
+
+function storageKeysForProperty(property: string): string[] {
+  const storageKey = cssPropertyNameToStorageKey(property)
+  return SIDE_STORAGE_KEYS[storageKey] ?? [storageKey]
+}
+
+function ruleHasAnyProperty(rule: StyleRule, keys: readonly string[]): boolean {
+  if (keys.some((key) => key in rule.styles)) return true
+  return Object.values(rule.contextStyles).some((styles) => keys.some((key) => key in styles))
+}
+
+function deletePriorityKeys(priorities: PriorityBag | undefined, keys: readonly string[]): void {
+  if (!priorities) return
+  for (const key of keys) delete priorities[key]
+}
+
 export function createCrudActions({ get, mutateSite }: SiteSliceHelpers): CrudActions {
   return {
     createClass(name, styles = {}) {
@@ -108,8 +368,12 @@ export function createCrudActions({ get, mutateSite }: SiteSliceHelpers): CrudAc
         for (const [k, v] of Object.entries(patch)) {
           if (v === undefined || v === null) {
             delete draftClass.styles[k]
+            delete draftClass.stylePriorities?.[k]
           }
         }
+        if (draftClass.stylePriorities && Object.keys(draftClass.stylePriorities).length === 0) {
+          delete draftClass.stylePriorities
+        }
         draftClass.updatedAt = Date.now()
         return true
       })
@@ -134,23 +398,45 @@ export function createCrudActions({ get, mutateSite }: SiteSliceHelpers): CrudAc
         for (const [k, v] of Object.entries(patch)) {
           if (v === undefined || v === null) {
             delete draftClass.contextStyles[contextId][k]
+            delete draftClass.contextStylePriorities?.[contextId]?.[k]
           }
         }
+        const contextPriorities = draftClass.contextStylePriorities?.[contextId]
+        if (contextPriorities && Object.keys(contextPriorities).length === 0) {
+          delete draftClass.contextStylePriorities?.[contextId]
+        }
+        if (
+          draftClass.contextStylePriorities
+          && Object.keys(draftClass.contextStylePriorities).length === 0
+        ) {
+          delete draftClass.contextStylePriorities
+        }
         draftClass.updatedAt = Date.now()
         return true
       })
     },
 
-    upsertCssRules(rules, conditions) {
+    applyCssRules(rules, conditions, mode) {
       const { site } = get()
-      if (!site) return { created: 0, updated: 0 }
+      if (!site) return { created: 0, updated: 0, blockedSelectors: [] }
+      const incoming = consolidateIncomingRules(rules)
+      const existingBySelector = rulesBySelector(site.styleRules)
+      const blockedSelectors = incoming
+        .filter(({ selector }) =>
+          (existingBySelector.get(selector) ?? []).some(isGeneratedClassLocked),
+        )
+        .map(({ selector }) => selector)
+      if (blockedSelectors.length > 0) {
+        return { created: 0, updated: 0, blockedSelectors }
+      }
+
       let created = 0
       let updated = 0
 
       mutateSite((site) => {
-        // 1. Register any referenced reusable conditions (custom @media /
-        //    @container / @supports) so per-context overrides resolve, deduped
-        //    by deterministic id.
+        let mutated = false
+
+        // Register referenced reusable conditions before their context bags.
         if (conditions.length > 0) {
           if (!site.conditions) site.conditions = []
           const known = new Set(site.conditions.map((c) => c.id))
@@ -158,65 +444,175 @@ export function createCrudActions({ get, mutateSite }: SiteSliceHelpers): CrudAc
             if (known.has(def.id)) continue
             known.add(def.id)
             site.conditions.push(def)
+            mutated = true
           }
         }
 
-        // 2. Index the live registry so an incoming rule UPDATES the rule it
-        //    names instead of piling up a duplicate: class rules key on `name`,
-        //    ambient rules key on `selector` (first id wins on the rare clash).
-        const classByName = new Map<string, string>()
-        const ambientBySelector = new Map<string, string>()
+        const targetBySelector = rulesBySelector(site.styleRules)
         let maxOrder = -1
         for (const rule of Object.values(site.styleRules)) {
           if (typeof rule.order === 'number' && rule.order > maxOrder) maxOrder = rule.order
-          if (rule.kind === 'ambient') {
-            if (!ambientBySelector.has(rule.selector)) ambientBySelector.set(rule.selector, rule.id)
-          } else if (!classByName.has(rule.name)) {
-            classByName.set(rule.name, rule.id)
+        }
+
+        const now = Date.now()
+        for (const item of incoming) {
+          const targets = targetBySelector.get(item.selector) ?? []
+          if (targets.length > 0) {
+            for (const target of targets) {
+              const current = payloadFromRule(target)
+              const next = mode === 'replace'
+                ? item.payload
+                : mergePayload(current, item.payload, false)
+              if (payloadEqual(current, next)) continue
+              writePayload(target, next)
+              target.updatedAt = now
+              updated++
+              mutated = true
+            }
+            continue
           }
+
+          const id = nanoid()
+          const newRule: StyleRule = {
+            ...item.source,
+            ...item.payload,
+            id,
+            order: (maxOrder += 1),
+            createdAt: now,
+            updatedAt: now,
+          }
+          site.styleRules[id] = newRule
+          targetBySelector.set(item.selector, [newRule])
+          created++
+          mutated = true
+        }
+
+        return mutated
+      })
+
+      return { created, updated, blockedSelectors: [] }
+    },
+
+    deleteCssRules(selectors) {
+      const { site } = get()
+      if (!site) {
+        return { deleted: 0, missingSelectors: selectors, blockedSelectors: [] }
+      }
+      const requested = [...new Set(selectors.map((selector) => selector.trim()))]
+      const existingBySelector = rulesBySelector(site.styleRules)
+      const missingSelectors = requested.filter((selector) =>
+        (existingBySelector.get(selector) ?? []).length === 0,
+      )
+      const blockedSelectors = requested.filter((selector) =>
+        (existingBySelector.get(selector) ?? []).some(isGeneratedClassLocked),
+      )
+      if (missingSelectors.length > 0 || blockedSelectors.length > 0) {
+        return { deleted: 0, missingSelectors, blockedSelectors }
+      }
+
+      const ids = requested.flatMap((selector) =>
+        (existingBySelector.get(selector) ?? []).map((rule) => rule.id),
+      )
+      get().deleteClasses(ids)
+      return { deleted: ids.length, missingSelectors: [], blockedSelectors: [] }
+    },
+
+    removeCssRuleProperties(selectors, properties) {
+      const { site } = get()
+      if (!site) {
+        return {
+          updated: 0,
+          removed: 0,
+          missingSelectors: selectors,
+          missingProperties: properties,
+          blockedSelectors: [],
         }
+      }
+      const requestedSelectors = [...new Set(selectors.map((selector) => selector.trim()))]
+      const requestedProperties = [...new Set(properties.map((property) => property.trim()))]
+      const existingBySelector = rulesBySelector(site.styleRules)
+      const missingSelectors = requestedSelectors.filter((selector) =>
+        (existingBySelector.get(selector) ?? []).length === 0,
+      )
+      const blockedSelectors = requestedSelectors.filter((selector) =>
+        (existingBySelector.get(selector) ?? []).some(isGeneratedClassLocked),
+      )
+      const targets = requestedSelectors.flatMap((selector) => existingBySelector.get(selector) ?? [])
+      const propertyKeys = new Map(
+        requestedProperties.map((property) => [property, storageKeysForProperty(property)]),
+      )
+      const missingProperties = requestedProperties.filter((property) =>
+        !targets.some((rule) => ruleHasAnyProperty(rule, propertyKeys.get(property) ?? [])),
+      )
 
-        // 3. Upsert: merge onto the matching rule, or mint a new one at the end
-        //    of the cascade. This is the whole point of the tool — re-applying
-        //    `.hero a { color: blue }` over an existing `.hero a` EDITS it,
-        //    where the additive import path would have skipped it as a dupe.
+      if (
+        missingSelectors.length > 0
+        || blockedSelectors.length > 0
+        || missingProperties.length > 0
+      ) {
+        return {
+          updated: 0,
+          removed: 0,
+          missingSelectors,
+          missingProperties,
+          blockedSelectors,
+        }
+      }
+
+      const keys = [...new Set([...propertyKeys.values()].flat())]
+      let updated = 0
+      let removed = 0
+      mutateSite((site) => {
         const now = Date.now()
-        for (const rule of rules) {
-          const existingId = rule.kind === 'ambient'
-            ? ambientBySelector.get(rule.selector)
-            : classByName.get(rule.name)
-
-          if (existingId) {
-            const target = site.styleRules[existingId]
-            // Never overwrite a framework-generated token/utility class — those
-            // are owned by the design system, not authored CSS.
-            if (isGeneratedClassLocked(target)) continue
-            Object.assign(target.styles, rule.styles)
-            for (const [contextId, patch] of Object.entries(rule.contextStyles ?? {})) {
-              if (!target.contextStyles[contextId]) target.contextStyles[contextId] = {}
-              Object.assign(target.contextStyles[contextId], patch)
+        for (const target of targets) {
+          const draftRule = site.styleRules[target.id]
+          if (!draftRule) continue
+          let ruleChanged = false
+          for (const key of keys) {
+            if (key in draftRule.styles) {
+              delete draftRule.styles[key]
+              removed++
+              ruleChanged = true
+            }
+            for (const contextStyles of Object.values(draftRule.contextStyles)) {
+              if (key in contextStyles) {
+                delete contextStyles[key]
+                removed++
+                ruleChanged = true
+              }
             }
-            target.updatedAt = now
-            updated++
-          } else {
-            const id = nanoid()
-            site.styleRules[id] = {
-              ...rule,
-              id,
-              order: (maxOrder += 1),
-              createdAt: now,
-              updatedAt: now,
+          }
+          deletePriorityKeys(draftRule.stylePriorities, keys)
+          if (draftRule.stylePriorities && Object.keys(draftRule.stylePriorities).length === 0) {
+            delete draftRule.stylePriorities
+          }
+          for (const priorities of Object.values(draftRule.contextStylePriorities ?? {})) {
+            deletePriorityKeys(priorities, keys)
+          }
+          if (draftRule.contextStylePriorities) {
+            for (const [contextId, priorities] of Object.entries(draftRule.contextStylePriorities)) {
+              if (Object.keys(priorities).length === 0) {
+                delete draftRule.contextStylePriorities[contextId]
+              }
+            }
+            if (Object.keys(draftRule.contextStylePriorities).length === 0) {
+              delete draftRule.contextStylePriorities
             }
-            if (rule.kind === 'ambient') ambientBySelector.set(rule.selector, id)
-            else classByName.set(rule.name, id)
-            created++
           }
+          if (!ruleChanged) continue
+          draftRule.updatedAt = now
+          updated++
         }
-
-        return created > 0 || updated > 0
+        return updated > 0
       })
 
-      return { created, updated }
+      return {
+        updated,
+        removed,
+        missingSelectors: [],
+        missingProperties: [],
+        blockedSelectors: [],
+      }
     },
   }
 }
diff --git a/src/admin/pages/site/store/slices/styleRule/propertyActions.ts b/src/admin/pages/site/store/slices/styleRule/propertyActions.ts
index 6ad225e7c..d6d973442 100644
--- a/src/admin/pages/site/store/slices/styleRule/propertyActions.ts
+++ b/src/admin/pages/site/store/slices/styleRule/propertyActions.ts
@@ -6,6 +6,7 @@
  */
 
 import type { CSSPropertyBag } from '@core/page-tree'
+import type { StyleRule } from '@core/page-tree'
 import { isGeneratedClassLocked } from '@core/page-tree'
 import type { SiteSliceHelpers } from '../site/types'
 import type { StyleRuleSlice } from './types'
@@ -15,6 +16,22 @@ type PropertyActions = Pick<
   'removeClassStyleProperty' | 'clearClassStyleProperties'
 >
 
+function removePriorityKeys(rule: StyleRule, keys: readonly string[]): void {
+  for (const key of keys) delete rule.stylePriorities?.[key]
+  if (rule.stylePriorities && Object.keys(rule.stylePriorities).length === 0) {
+    delete rule.stylePriorities
+  }
+  for (const [contextId, priorities] of Object.entries(rule.contextStylePriorities ?? {})) {
+    for (const key of keys) delete priorities[key]
+    if (Object.keys(priorities).length === 0) {
+      delete rule.contextStylePriorities?.[contextId]
+    }
+  }
+  if (rule.contextStylePriorities && Object.keys(rule.contextStylePriorities).length === 0) {
+    delete rule.contextStylePriorities
+  }
+}
+
 export function createPropertyActions({ get, mutateSite }: SiteSliceHelpers): PropertyActions {
   return {
     removeClassStyleProperty(classId, property: keyof CSSPropertyBag) {
@@ -42,6 +59,7 @@ export function createPropertyActions({ get, mutateSite }: SiteSliceHelpers): Pr
           const bag = draftClass.contextStyles[contextId]
           if (bag) delete (bag as Record<string, unknown>)[propKey]
         }
+        removePriorityKeys(draftClass, [propKey])
         draftClass.updatedAt = Date.now()
         return true
       })
@@ -70,6 +88,7 @@ export function createPropertyActions({ get, mutateSite }: SiteSliceHelpers): Pr
             if (bag) delete (bag as Record<string, unknown>)[key]
           }
         }
+        removePriorityKeys(draftClass, keys)
         draftClass.updatedAt = Date.now()
         return true
       })
diff --git a/src/admin/pages/site/store/slices/styleRule/registryActions.ts b/src/admin/pages/site/store/slices/styleRule/registryActions.ts
index f88dd05e2..e3c64c58e 100644
--- a/src/admin/pages/site/store/slices/styleRule/registryActions.ts
+++ b/src/admin/pages/site/store/slices/styleRule/registryActions.ts
@@ -120,10 +120,23 @@ export function createRegistryActions({
         order: nextRuleOrder(site.styleRules),
         description: cls.description,
         styles: { ...cls.styles },
+        ...(cls.stylePriorities
+          ? { stylePriorities: { ...cls.stylePriorities } }
+          : {}),
         // Per-context overrides reference the shared site-level conditions
         // registry by id, so cloning the bags (independent copies) is enough —
         // no per-rule condition definitions to clone.
         contextStyles: cloneContextStyles(cls.contextStyles),
+        ...(cls.contextStylePriorities
+          ? {
+              contextStylePriorities: Object.fromEntries(
+                Object.entries(cls.contextStylePriorities).map(([contextId, priorities]) => [
+                  contextId,
+                  { ...priorities },
+                ]),
+              ),
+            }
+          : {}),
         tags: cls.tags ? [...cls.tags] : undefined,
         createdAt: now,
         updatedAt: now,
diff --git a/src/admin/pages/site/store/slices/styleRule/types.ts b/src/admin/pages/site/store/slices/styleRule/types.ts
index b08b102a1..27535d060 100644
--- a/src/admin/pages/site/store/slices/styleRule/types.ts
+++ b/src/admin/pages/site/store/slices/styleRule/types.ts
@@ -46,6 +46,28 @@ interface ClassStylesPreview {
   styles: Partial<CSSPropertyBag>
 }
 
+export type CssRuleApplyMode = 'merge' | 'replace'
+
+export interface CssRuleApplyResult {
+  created: number
+  updated: number
+  blockedSelectors: string[]
+}
+
+export interface CssRuleDeleteResult {
+  deleted: number
+  missingSelectors: string[]
+  blockedSelectors: string[]
+}
+
+export interface CssRulePropertyRemovalResult {
+  updated: number
+  removed: number
+  missingSelectors: string[]
+  missingProperties: string[]
+  blockedSelectors: string[]
+}
+
 // ---------------------------------------------------------------------------
 // Slice interface
 // ---------------------------------------------------------------------------
@@ -97,25 +119,29 @@ export interface StyleRuleSlice {
   updateClassStyles(classId: string, patch: Partial<CSSPropertyBag>): void
 
   /**
-   * Apply a batch of CSS rules parsed from authored CSS text (see
-   * `cssToStyleRules`) to the registry with UPSERT semantics: a rule whose
-   * `name` (class) or `selector` (ambient) already exists is MERGED onto the
-   * existing rule — base `styles` and every per-context override — so the same
-   * call both creates new selectors and EDITS existing ones. New selectors are
-   * minted at the end of the cascade. Framework-generated/locked token classes
-   * are never overwritten. Any referenced reusable conditions are registered
-   * first. The whole batch is one undo step. Returns how many rules were
-   * created vs. updated.
-   *
-   * This is the engine behind the agent's `applyCss` tool and the element-less
-   * `<style>` payload path — the editing counterpart to the additive
-   * `mergeImportedStyleRules` used when importing structure (which deliberately
-   * does NOT clobber shared classes as a side effect of inserting nodes).
+   * Apply parsed authored CSS by exact emitted selector. Merge patches only
+   * the addressed declarations/contexts; replace makes the incoming rule's
+   * complete CSS payload authoritative while preserving registry identity,
+   * cascade order, assignments, and metadata. Duplicate exact selectors are
+   * all updated atomically. New selectors append in authored order.
    */
-  upsertCssRules(
+  applyCssRules(
     rules: NewStyleRule[],
     conditions: ConditionDef[],
-  ): { created: number; updated: number }
+    mode: CssRuleApplyMode,
+  ): CssRuleApplyResult
+
+  /** Delete every editable rule whose emitted selector exactly matches. */
+  deleteCssRules(selectors: string[]): CssRuleDeleteResult
+
+  /**
+   * Remove storage-key CSS properties from base and every context of every
+   * exact selector match, as one atomic history entry.
+   */
+  removeCssRuleProperties(
+    selectors: string[],
+    properties: string[],
+  ): CssRulePropertyRemovalResult
 
   // ── Per-context overrides (unified viewport-context + custom-condition axis) ─
   /**
diff --git a/src/admin/pages/site/store/subtreeSnapshot.ts b/src/admin/pages/site/store/subtreeSnapshot.ts
index ab878f1df..7be539d5b 100644
--- a/src/admin/pages/site/store/subtreeSnapshot.ts
+++ b/src/admin/pages/site/store/subtreeSnapshot.ts
@@ -156,12 +156,25 @@ export function insertSnapshotSubtrees(
           id: newId,
           scope: { ...cls.scope, nodeId: newScopeNodeId },
           styles: { ...cls.styles },
+          ...(cls.stylePriorities
+            ? { stylePriorities: { ...cls.stylePriorities } }
+            : {}),
           contextStyles: Object.fromEntries(
             Object.entries(cls.contextStyles).map(([ctx, s]) => [
               ctx,
               { ...s },
             ]),
           ),
+          ...(cls.contextStylePriorities
+            ? {
+                contextStylePriorities: Object.fromEntries(
+                  Object.entries(cls.contextStylePriorities).map(([ctx, priorities]) => [
+                    ctx,
+                    { ...priorities },
+                  ]),
+                ),
+              }
+            : {}),
           createdAt: now,
           updatedAt: now,
         },
@@ -190,12 +203,25 @@ export function insertSnapshotSubtrees(
           cls: {
             ...cls,
             styles: { ...cls.styles },
+            ...(cls.stylePriorities
+              ? { stylePriorities: { ...cls.stylePriorities } }
+              : {}),
             contextStyles: Object.fromEntries(
               Object.entries(cls.contextStyles).map(([ctx, s]) => [
                 ctx,
                 { ...s },
               ]),
             ),
+            ...(cls.contextStylePriorities
+              ? {
+                  contextStylePriorities: Object.fromEntries(
+                    Object.entries(cls.contextStylePriorities).map(([ctx, priorities]) => [
+                      ctx,
+                      { ...priorities },
+                    ]),
+                  ),
+                }
+              : {}),
           },
         })
       }
diff --git a/src/core/ai/toolSchemas.ts b/src/core/ai/toolSchemas.ts
index ae2bc2202..38255bf1d 100644
--- a/src/core/ai/toolSchemas.ts
+++ b/src/core/ai/toolSchemas.ts
@@ -119,9 +119,43 @@ export type DuplicateNodeInput = Static<typeof DuplicateNodeInputSchema>
 // CSS + class-assignment write tools
 // ---------------------------------------------------------------------------
 
-export const ApplyCssInputSchema = Type.Object({
-  css: Type.String({ minLength: 1 }),
+const CssTextInputSchema = Type.String({ minLength: 1 })
+const CssSelectorListInputSchema = Type.Array(
+  Type.String({ minLength: 1 }),
+  { minItems: 1, maxItems: 100, uniqueItems: true },
+)
+const CssPropertyNameInputSchema = Type.String({
+  minLength: 1,
+  pattern: '^-{0,2}[a-zA-Z][a-zA-Z0-9-]*$',
 })
+
+/**
+ * One explicit CSS-registry mutation. The discriminator keeps destructive
+ * replacement/deletion impossible to trigger accidentally by omitting an
+ * optional flag from a normal merge.
+ */
+export const ApplyCssInputSchema = Type.Union([
+  Type.Object({
+    operation: Type.Literal('merge'),
+    css: CssTextInputSchema,
+  }),
+  Type.Object({
+    operation: Type.Literal('replace'),
+    css: CssTextInputSchema,
+  }),
+  Type.Object({
+    operation: Type.Literal('delete'),
+    selectors: CssSelectorListInputSchema,
+  }),
+  Type.Object({
+    operation: Type.Literal('remove-properties'),
+    selectors: CssSelectorListInputSchema,
+    properties: Type.Array(
+      CssPropertyNameInputSchema,
+      { minItems: 1, maxItems: 100, uniqueItems: true },
+    ),
+  }),
+])
 export type ApplyCssInput = Static<typeof ApplyCssInputSchema>
 
 export const AssignClassInputSchema = Type.Object({
diff --git a/src/core/css-substitution/index.ts b/src/core/css-substitution/index.ts
index 62a1e3f7f..5f6e10410 100644
--- a/src/core/css-substitution/index.ts
+++ b/src/core/css-substitution/index.ts
@@ -40,6 +40,7 @@
  */
 
 import { isEmittableProperty } from '@core/publisher'
+import type { CSSDeclarationPriorityBag } from '@core/page-tree'
 /** Prefix for encoded substitution declarations. */
 export const SUBSTITUTION_PROP_MARKER = '--instatic-sub-'
 
@@ -219,11 +220,16 @@ function scanUntil(css: string, start: number, stops: string): number {
  * names like `-webkit-foo` DO camelCase to `WebkitFoo`, matching the DOM
  * style API.)
  */
-function kebabToCamel(prop: string): string {
+export function cssPropertyNameToStorageKey(prop: string): string {
   if (prop.startsWith('--')) return prop
   return prop.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase())
 }
 
+export interface CssDeclarationBlock {
+  styles: Record<string, string>
+  priorities: CSSDeclarationPriorityBag
+}
+
 /**
  * Walk a parsed `CSSStyleDeclaration` into a camelCase property bag:
  * decodes substitution markers back to their real property
@@ -240,22 +246,34 @@ function kebabToCamel(prop: string): string {
  * Uses `.length` + index access (not `for...of`) since CSSStyleDeclaration
  * does not enumerate properties via Symbol.iterator.
  */
-export function readCssDeclarationBag(
+export function readCssDeclarationBlock(
   style: CSSStyleDeclaration,
   onBlockedProperty?: (camel: string, kebab: string) => void,
-): Record<string, string> {
-  const out: Record<string, string> = {}
+): CssDeclarationBlock {
+  const styles: Record<string, string> = {}
+  const priorities: CSSDeclarationPriorityBag = {}
   for (let i = 0; i < style.length; i++) {
     const rawKebab = style[i]
     const value = style.getPropertyValue(rawKebab).trim()
     if (!value) continue
     const kebab = decodeSubstitutionProperty(rawKebab) ?? rawKebab
-    const camel = kebabToCamel(kebab)
+    const camel = cssPropertyNameToStorageKey(kebab)
     if (!isEmittableProperty(camel)) {
       onBlockedProperty?.(camel, kebab)
       continue
     }
-    out[camel] = value
+    styles[camel] = value
+    if (style.getPropertyPriority(rawKebab).toLowerCase() === 'important') {
+      priorities[camel] = 'important'
+    }
   }
-  return out
+  return { styles, priorities }
+}
+
+/** Value-only view used by node inline styles, whose shape stays unchanged. */
+export function readCssDeclarationBag(
+  style: CSSStyleDeclaration,
+  onBlockedProperty?: (camel: string, kebab: string) => void,
+): Record<string, string> {
+  return readCssDeclarationBlock(style, onBlockedProperty).styles
 }
diff --git a/src/core/page-tree/index.ts b/src/core/page-tree/index.ts
index e3776f0d9..416288906 100644
--- a/src/core/page-tree/index.ts
+++ b/src/core/page-tree/index.ts
@@ -22,6 +22,7 @@ export {
 } from './operationSchema'
 export { PageSchema } from './page'
 export {
+  CSSDeclarationPriorityBagSchema,
   StyleRuleSchema,
   classKindSelector,
   classifySelectorCreateInput,
@@ -38,7 +39,12 @@ export type { PageNode } from './pageNode'
 export type { TreeOperation, TreeMutateResult } from './operationSchema'
 export type { Page } from './page'
 export type { CSSPropertyBag } from './cssPropertyBag'
-export type { SelectorCreateInput, StyleRule, StyleRuleKind } from './styleRule'
+export type {
+  CSSDeclarationPriorityBag,
+  SelectorCreateInput,
+  StyleRule,
+  StyleRuleKind,
+} from './styleRule'
 export type { Condition, ConditionDef } from './condition'
 export type { SiteSettings } from './siteSettings'
 export type { SiteShell, SiteDocument } from './siteDocument'
diff --git a/src/core/page-tree/scopedClassClone.ts b/src/core/page-tree/scopedClassClone.ts
index 05904b4cf..977e49757 100644
--- a/src/core/page-tree/scopedClassClone.ts
+++ b/src/core/page-tree/scopedClassClone.ts
@@ -57,6 +57,9 @@ export function cloneScopedClassesForNodeMap(
       id: newId,
       scope: { ...cls.scope, nodeId: newScopeNodeId },
       styles: { ...cls.styles },
+      ...(cls.stylePriorities
+        ? { stylePriorities: { ...cls.stylePriorities } }
+        : {}),
       // Deep-clone every per-context override bag so the clone owns independent
       // maps — the bare `...cls` spread would share the same bag objects with
       // the source rule (the shared-reference hazard F-0005 addresses for
@@ -65,6 +68,16 @@ export function cloneScopedClassesForNodeMap(
       contextStyles: Object.fromEntries(
         Object.entries(cls.contextStyles).map(([ctx, s]) => [ctx, { ...s }]),
       ),
+      ...(cls.contextStylePriorities
+        ? {
+            contextStylePriorities: Object.fromEntries(
+              Object.entries(cls.contextStylePriorities).map(([ctx, priorities]) => [
+                ctx,
+                { ...priorities },
+              ]),
+            ),
+          }
+        : {}),
       ...(cls.tags !== undefined ? { tags: [...cls.tags] } : {}),
       createdAt: now,
       updatedAt: now,
diff --git a/src/core/page-tree/styleRule.ts b/src/core/page-tree/styleRule.ts
index c5d0287e7..5b6f05f8a 100644
--- a/src/core/page-tree/styleRule.ts
+++ b/src/core/page-tree/styleRule.ts
@@ -51,6 +51,17 @@ import { escapeCssIdentifier as escapeCssIdent } from './cssIdentifier'
 const StyleRuleKindSchema = Type.Union([Type.Literal('class'), Type.Literal('ambient')])
 export type StyleRuleKind = Static<typeof StyleRuleKindSchema>
 
+/**
+ * CSS declaration priority is deliberately stored beside — never inside — a
+ * property value. Keeping the metadata sparse preserves the scalar
+ * CSSPropertyBag values consumed by editor controls and node inline styles.
+ */
+export const CSSDeclarationPriorityBagSchema = Type.Record(
+  Type.String(),
+  Type.Literal('important'),
+)
+export type CSSDeclarationPriorityBag = Static<typeof CSSDeclarationPriorityBagSchema>
+
 export const StyleRuleSchema = Type.Object({
   id: Type.String(),
   name: Type.String(),
@@ -88,6 +99,8 @@ export const StyleRuleSchema = Type.Object({
    * Falls back to {} when missing or invalid — handled in parseStyleRule.
    */
   styles: withFallback(Type.Record(Type.String(), Type.Unknown()), {} as Record<string, unknown>),
+  /** Sparse property -> `important` metadata for base declarations. */
+  stylePriorities: Type.Optional(CSSDeclarationPriorityBagSchema),
   /**
    * Per-context overrides — same persistence semantics as `styles`. The unified
    * "editing context" model (docs/plans/2026-05-30-unified-condition-axis.md):
@@ -103,6 +116,8 @@ export const StyleRuleSchema = Type.Object({
     Type.Record(Type.String(), Type.Record(Type.String(), Type.Unknown())),
     {} as Record<string, Record<string, unknown>>,
   ),
+  /** Sparse context id -> declaration-priority metadata. */
+  contextStylePriorities: Type.Optional(Type.Record(Type.String(), CSSDeclarationPriorityBagSchema)),
   /** Sanitised raw CSS for supported stylesheet-level rules such as @keyframes. */
   rawCss: Type.Optional(Type.String()),
   /** Optional search/filter tags. Invalid items silently dropped — handled in parseStyleRule. */
@@ -161,6 +176,34 @@ function parseContextStyles(raw: Record<string, unknown>): Record<string, Record
   return parseBreakpointStylesBag(raw.contextStyles)
 }
 
+/** Keep only valid priority entries that still have a declaration value. */
+function parsePriorityBag(
+  raw: unknown,
+  styles: Record<string, unknown>,
+): CSSDeclarationPriorityBag | undefined {
+  const record = asPlainObject(raw)
+  if (!record) return undefined
+  const priorities: CSSDeclarationPriorityBag = {}
+  for (const [property, priority] of Object.entries(record)) {
+    if (priority === 'important' && property in styles) priorities[property] = 'important'
+  }
+  return Object.keys(priorities).length > 0 ? priorities : undefined
+}
+
+function parseContextStylePriorities(
+  raw: unknown,
+  contextStyles: Record<string, Record<string, unknown>>,
+): Record<string, CSSDeclarationPriorityBag> | undefined {
+  const record = asPlainObject(raw)
+  if (!record) return undefined
+  const priorities: Record<string, CSSDeclarationPriorityBag> = {}
+  for (const [contextId, contextPriorities] of Object.entries(record)) {
+    const parsed = parsePriorityBag(contextPriorities, contextStyles[contextId] ?? {})
+    if (parsed) priorities[contextId] = parsed
+  }
+  return Object.keys(priorities).length > 0 ? priorities : undefined
+}
+
 /** Parse a StyleRule scope (currently only `{ type: 'node', nodeId, role: 'module-style' }`). */
 function parseStyleRuleScope(raw: unknown): StyleRule['scope'] {
   const s = asPlainObject(raw)
@@ -184,7 +227,10 @@ export function parseStyleRule(raw: unknown): StyleRule | null {
 
   const scope = parseStyleRuleScope(r.scope)
   const tags = parseStringArrayField(r.tags)
+  const styles = parseStylesBag(r.styles)
   const contextStyles = parseContextStyles(r)
+  const stylePriorities = parsePriorityBag(r.stylePriorities, styles)
+  const contextStylePriorities = parseContextStylePriorities(r.contextStylePriorities, contextStyles)
   const generated = compiledCheck(GeneratedClassMetadataSchema, r.generated)
     ? (r.generated as StyleRule['generated'])
     : undefined
@@ -197,8 +243,10 @@ export function parseStyleRule(raw: unknown): StyleRule | null {
     order: r.order,
     ...(typeof r.description === 'string' ? { description: r.description } : {}),
     ...(scope !== undefined ? { scope } : {}),
-    styles: parseStylesBag(r.styles),
+    styles,
+    ...(stylePriorities !== undefined ? { stylePriorities } : {}),
     contextStyles,
+    ...(contextStylePriorities !== undefined ? { contextStylePriorities } : {}),
     ...(typeof r.rawCss === 'string' && r.rawCss.trim() ? { rawCss: r.rawCss } : {}),
     ...(tags !== undefined ? { tags } : {}),
     ...(generated !== undefined ? { generated } : {}),
diff --git a/src/core/publisher/classCss.ts b/src/core/publisher/classCss.ts
index ffc466c94..fe197bbf7 100644
--- a/src/core/publisher/classCss.ts
+++ b/src/core/publisher/classCss.ts
@@ -1,4 +1,9 @@
-import type { StyleRule, Condition, ConditionDef } from '@core/page-tree'
+import type {
+  CSSDeclarationPriorityBag,
+  StyleRule,
+  Condition,
+  ConditionDef,
+} from '@core/page-tree'
 import { breakpointMediaQuery, styleRuleSelector } from '@core/page-tree'
 import { sanitiseCssValue } from './utils'
 import { responsiveBackgroundImage, type ResponsiveCssOptions } from './responsiveBackground'
@@ -107,17 +112,26 @@ function buildSidesShorthand(top: string, right: string, bottom: string, left: s
 function tryCollapseSides(
   bag: Record<string, unknown>,
   prefix: SideShorthandPrefix,
-): string | null {
+  priorities: CSSDeclarationPriorityBag,
+): { value: string; important: boolean } | null {
   const values: string[] = []
+  let important: boolean | undefined
   for (const side of SIDES) {
-    const raw = bag[`${prefix}${side}`]
+    const property = `${prefix}${side}`
+    const raw = bag[property]
     if (raw === undefined || raw === null || raw === '') return null
     const sanitised = sanitiseCssValue(raw as string | number)
     if (sanitised === null) return null
+    const propertyImportant = priorities[property] === 'important'
+    if (important !== undefined && propertyImportant !== important) return null
+    important = propertyImportant
     values.push(sanitised)
   }
   const [top, right, bottom, left] = values
-  return buildSidesShorthand(top, right, bottom, left)
+  return {
+    value: buildSidesShorthand(top, right, bottom, left),
+    important: important ?? false,
+  }
 }
 
 /**
@@ -141,8 +155,9 @@ function tryCollapseSides(
 function bagToDeclarations(
   bag: Record<string, unknown>,
   options: ResponsiveCssOptions = {},
-): Array<[string, string]> {
-  const decls: Array<[string, string]> = []
+  priorities: CSSDeclarationPriorityBag = {},
+): Array<[string, string, boolean]> {
+  const decls: Array<[string, string, boolean]> = []
   // Track which prefixes have already been emitted as a collapsed shorthand
   // so we skip the remaining three side properties for that prefix.
   const collapsedPrefixes = new Set<SideShorthandPrefix>()
@@ -154,9 +169,9 @@ function bagToDeclarations(
     const sidePrefix = SIDE_PROP_TO_PREFIX.get(prop)
     if (sidePrefix) {
       if (collapsedPrefixes.has(sidePrefix)) continue
-      const shorthand = tryCollapseSides(bag, sidePrefix)
+      const shorthand = tryCollapseSides(bag, sidePrefix, priorities)
       if (shorthand !== null) {
-        decls.push([sidePrefix, shorthand])
+        decls.push([sidePrefix, shorthand.value, shorthand.important])
         collapsedPrefixes.add(sidePrefix)
         continue
       }
@@ -166,17 +181,18 @@ function bagToDeclarations(
     const sanitised = sanitiseCssValue(value as string | number)
     if (sanitised === null) continue
     const kebab = toKebab(prop)
+    const important = priorities[prop] === 'important'
     if (prop === 'backgroundImage') {
       const responsive = responsiveBackgroundImage(sanitised, options.mediaAssets)
       const fallback = sanitiseCssValue(responsive.fallback)
-      if (fallback !== null) decls.push([kebab, fallback])
+      if (fallback !== null) decls.push([kebab, fallback, important])
       if (responsive.imageSet) {
         const imageSet = sanitiseCssValue(responsive.imageSet)
-        if (imageSet !== null) decls.push([kebab, imageSet])
+        if (imageSet !== null) decls.push([kebab, imageSet, important])
       }
       continue
     }
-    decls.push([kebab, sanitised])
+    decls.push([kebab, sanitised, important])
   }
   return decls
 }
@@ -186,9 +202,13 @@ function bagToDeclarations(
  * for use inside a `{ … }` rule body). See `bagToDeclarations` for the shared
  * extraction rules.
  */
-export function bagToCSS(bag: Record<string, unknown>, options: ResponsiveCssOptions = {}): string {
-  return bagToDeclarations(bag, options)
-    .map(([prop, value]) => `  ${prop}: ${value};`)
+export function bagToCSS(
+  bag: Record<string, unknown>,
+  options: ResponsiveCssOptions = {},
+  priorities: CSSDeclarationPriorityBag = {},
+): string {
+  return bagToDeclarations(bag, options, priorities)
+    .map(([prop, value, important]) => `  ${prop}: ${value}${important ? ' !important' : ''};`)
     .join('\n')
 }
 
@@ -296,10 +316,16 @@ export function compareViewportContextCascade(
  * viewport @media contexts (see `compareViewportContextCascade`). Context keys
  * matching neither registry are skipped (orphaned overrides).
  */
+export interface StyleRuleDeclarationLayers {
+  styles: Record<string, unknown>
+  stylePriorities?: CSSDeclarationPriorityBag
+  contextStyles?: Record<string, Record<string, unknown>>
+  contextStylePriorities?: Record<string, CSSDeclarationPriorityBag>
+}
+
 export type StyleRuleCssEmitter = (
   selector: string,
-  styles: Record<string, unknown>,
-  contextStyles?: Record<string, Record<string, unknown>>,
+  layers: StyleRuleDeclarationLayers,
 ) => string[]
 
 export function createStyleRuleCssEmitter(
@@ -316,33 +342,43 @@ export function createStyleRuleCssEmitter(
     conditions.map((c, index) => [c.id, { condition: c.condition, index }]),
   )
 
-  return (selector, styles, contextStyles) => {
+  return (selector, layers) => {
     const blocks: string[] = []
 
-    const baseDecls = bagToCSS(styles, options)
+    const baseDecls = bagToCSS(layers.styles, options, layers.stylePriorities)
     if (baseDecls) {
       blocks.push(`${selector} {\n${baseDecls}\n}`)
     }
 
     // Partition contextStyles into custom-condition entries and viewport-context
     // entries. Keys matching neither registry are skipped (orphaned overrides).
-    const conditionEntries: Array<{ bag: Record<string, unknown>; condition: Condition; index: number }> = []
-    const bpEntries: Array<{ bag: Record<string, unknown>; breakpoint: ViewportContext; index: number }> = []
-    for (const [contextId, bag] of Object.entries(contextStyles ?? {})) {
+    const conditionEntries: Array<{
+      contextId: string
+      bag: Record<string, unknown>
+      condition: Condition
+      index: number
+    }> = []
+    const bpEntries: Array<{
+      contextId: string
+      bag: Record<string, unknown>
+      breakpoint: ViewportContext
+      index: number
+    }> = []
+    for (const [contextId, bag] of Object.entries(layers.contextStyles ?? {})) {
       const cond = conditionById.get(contextId)
       if (cond) {
-        conditionEntries.push({ bag, condition: cond.condition, index: cond.index })
+        conditionEntries.push({ contextId, bag, condition: cond.condition, index: cond.index })
         continue
       }
       const breakpointEntry = breakpointById.get(contextId)
-      if (breakpointEntry) bpEntries.push({ bag, ...breakpointEntry })
+      if (breakpointEntry) bpEntries.push({ contextId, bag, ...breakpointEntry })
     }
 
     // Custom conditions emit AFTER base but BEFORE viewport contexts, so
     // viewport-specific overrides keep winning when both contexts match.
     conditionEntries.sort((a, b) => a.index - b.index)
-    for (const { bag, condition } of conditionEntries) {
-      const decls = bagToCSS(bag, options)
+    for (const { contextId, bag, condition } of conditionEntries) {
+      const decls = bagToCSS(bag, options, layers.contextStylePriorities?.[contextId])
       if (!decls) continue
       const prelude = conditionPrelude(condition)
       if (!prelude) continue
@@ -350,8 +386,8 @@ export function createStyleRuleCssEmitter(
     }
 
     bpEntries.sort(compareViewportContextCascade)
-    for (const { bag, breakpoint } of bpEntries) {
-      const decls = bagToCSS(bag, options)
+    for (const { contextId, bag, breakpoint } of bpEntries) {
+      const decls = bagToCSS(bag, options, layers.contextStylePriorities?.[contextId])
       if (!decls) continue
       const prelude = conditionPrelude({ kind: 'media', query: breakpointMediaQuery(breakpoint) })
       if (!prelude) continue
@@ -388,7 +424,7 @@ export function generateClassCSS(
       continue
     }
 
-    blocks.push(...emitRule(styleRuleSelector(cls), cls.styles, cls.contextStyles))
+    blocks.push(...emitRule(styleRuleSelector(cls), cls))
   }
 
   return blocks.join('\n\n')
diff --git a/src/core/publisher/index.ts b/src/core/publisher/index.ts
index b5d498f55..a3926559f 100644
--- a/src/core/publisher/index.ts
+++ b/src/core/publisher/index.ts
@@ -42,7 +42,11 @@ export {
   generateClassCSS,
   isEmittableProperty,
 } from './classCss'
-export type { StyleRuleCssEmitter, ViewportContext } from './classCss'
+export type {
+  StyleRuleCssEmitter,
+  StyleRuleDeclarationLayers,
+  ViewportContext,
+} from './classCss'
 
 export {
   collectBackgroundImagePaths,
diff --git a/src/core/publisher/sizesResolver.ts b/src/core/publisher/sizesResolver.ts
index 24c92f727..5856b2482 100644
--- a/src/core/publisher/sizesResolver.ts
+++ b/src/core/publisher/sizesResolver.ts
@@ -222,15 +222,36 @@ function effectiveBag(
   breakpointId: string | null,
 ): Record<string, unknown> {
   const out: Record<string, unknown> = {}
+  const importantProperties = new Set<string>()
+  const applyLayer = (
+    styles: Record<string, unknown> | undefined,
+    priorities: Record<string, 'important'> | undefined,
+  ) => {
+    if (!styles) return
+    for (const [property, value] of Object.entries(styles)) {
+      const important = priorities?.[property] === 'important'
+      if (importantProperties.has(property) && !important) continue
+      out[property] = value
+      if (important) importantProperties.add(property)
+      else importantProperties.delete(property)
+    }
+  }
   const classes = (node.classIds ?? [])
     .map((classId) => site.styleRules[classId])
     .filter((cls) => cls !== undefined)
     .sort((a, b) => (typeof a.order === 'number' ? a.order : 0) - (typeof b.order === 'number' ? b.order : 0))
   for (const cls of classes) {
-    Object.assign(out, cls.styles)
-    if (breakpointId) Object.assign(out, cls.contextStyles?.[breakpointId])
+    applyLayer(cls.styles, cls.stylePriorities)
+    if (breakpointId) {
+      applyLayer(
+        cls.contextStyles?.[breakpointId],
+        cls.contextStylePriorities?.[breakpointId],
+      )
+    }
   }
-  if (node.inlineStyles) Object.assign(out, node.inlineStyles)
+  // Normal inline declarations outrank normal class declarations, but an
+  // author-important class declaration outranks a normal inline declaration.
+  applyLayer(node.inlineStyles, undefined)
   return out
 }
 
diff --git a/src/core/siteImport/classCascades.ts b/src/core/siteImport/classCascades.ts
index bfadfeebb99f9973dc49f6409ec13215b3ffdd8f..ded44580398787db29c17d69ee74424003b158d2 100644
GIT binary patch
delta 722
zcmaDpn{nYR#tnPf>N9f-@{39os<{*tl8aIkOH!Q^i<1*mQd5FUDsxhUN^??u5-U@S
zigkbra#M@aQ{m!Jg&>LIg2bZYROkG>lGKWlfTGO&qRf)aRInb16slNBWkIR}M7tpt
zi)t0pit=+6)b;dJQj>EMixNvR^Yfs#sdG(UC?2qxm;D_VQ;fmpKY~t7;y7G9d8UXm
zPC0SWH*R?StDy<>7YJbWv_?v5nvOydFmyCGbBmkH*6Zo%X`p*m1FSVguNV}Ph!B7o
zte{}8P_2L_X$7$lLz6-+)Hw<YRtnX%nxIezfn-RSPxdr%mQzqbxB??CG$sd{2z%gi
z1=JXD+#=Li;fh$WVbTbNn&{5k+-CBZ8&}|OzUNTNC{G~tC+~7vtb{%6A;Ag>{>k$d
LMK?#e^l}0Kaiah;

delta 893
zcmZ2Di}Cqv#tnPfCQncd*u0nh9Ty|R=CwjjOwrW}#U+(Fsl`?bL8;04MJYDLB}JKe
z={gFfdD(gS<#~423d#9-C8-r9!PwQ|&}OGlJDE*XnWpADh`y;uxWBqq2i>XFwF<Rd
z3Si)$l$DxXqL)})oSB}dk&>FG2l2O#LQ!c>DwLyOZ?8~Ys|nSTmS3cx0rY%vi9$3q
z3_MeG6p|9tV-@n#6u>4<-sQ?w4>kcMl%NJ_DpW(wQcwU{iJ}H!W~_p(LbZaPo*vj;
zI2A!0rvp+5bOYRHwVR8?%w;Dlns{xNF#XO=%MjnJ=2*&@jvV9)iN&}Q4z}39RE;P3
z>~dNhfEsPNsYU6jDU`(A<PEMOD#XOsWPKA+5o}R3*}z0Z1z7@Dv`n5TCbD^ob1x?V
DsVFw0

diff --git a/src/core/siteImport/colorTokens.ts b/src/core/siteImport/colorTokens.ts
index 5d4796a38..929742776 100644
--- a/src/core/siteImport/colorTokens.ts
+++ b/src/core/siteImport/colorTokens.ts
@@ -100,18 +100,27 @@ export function extractRootColorTokens(
     }
 
     const remaining: Record<string, unknown> = {}
+    const remainingPriorities: Record<string, 'important'> = {}
     for (const [prop, value] of Object.entries(rule.styles)) {
-      if (prop.startsWith('--') && typeof value === 'string' && isCssColorValue(value)) {
+      const important = rule.stylePriorities?.[prop] === 'important'
+      if (!important && prop.startsWith('--') && typeof value === 'string' && isCssColorValue(value)) {
         colorTokens.push({ slug: prop.slice(2), value: value.trim() })
       } else {
         remaining[prop] = value
+        if (important) remainingPriorities[prop] = 'important'
       }
     }
 
     const hasContext = Object.keys(rule.contextStyles ?? {}).length > 0
     // Keep the rule only if it still carries declarations (base or contextual).
     if (Object.keys(remaining).length > 0 || hasContext) {
-      out.push({ ...rule, styles: remaining })
+      const rewritten = { ...rule, styles: remaining }
+      if (Object.keys(remainingPriorities).length > 0) {
+        rewritten.stylePriorities = remainingPriorities
+      } else {
+        delete rewritten.stylePriorities
+      }
+      out.push(rewritten)
     }
   }
 
diff --git a/src/core/siteImport/cssDeclarationReader.ts b/src/core/siteImport/cssDeclarationReader.ts
new file mode 100644
index 000000000..b22c4dd2f
--- /dev/null
+++ b/src/core/siteImport/cssDeclarationReader.ts
@@ -0,0 +1,19 @@
+import { readCssDeclarationBlock } from '@core/css-substitution'
+import type { ImportWarning } from './types'
+import type { DeclarationLayer } from './declarationCascade'
+
+export function parseStyleDeclarations(
+  style: CSSStyleDeclaration,
+  selectorForWarning: string,
+  warnings: ImportWarning[],
+): DeclarationLayer {
+  const parsed = readCssDeclarationBlock(style, (camel, kebab) => {
+    warnings.push({
+      kind: 'blocked-property',
+      message: `Property "${camel}" (${kebab}) is blocked for security and was dropped`,
+      selector: selectorForWarning,
+      property: camel,
+    })
+  })
+  return { styles: parsed.styles, priorities: parsed.priorities }
+}
diff --git a/src/core/siteImport/cssToStyleRules.ts b/src/core/siteImport/cssToStyleRules.ts
index 4e2854173..218201b69 100644
--- a/src/core/siteImport/cssToStyleRules.ts
+++ b/src/core/siteImport/cssToStyleRules.ts
@@ -41,8 +41,14 @@ import type { StyleRuleKind, Condition, ConditionDef } from '@core/page-tree'
 import { conditionId, makeConditionDef } from '@core/page-tree'
 import { formatVariant } from '@core/fonts'
 import { processKeyframesRule } from './keyframesToStyleRule'
-import { encodeSubstitutionDeclarations, readCssDeclarationBag } from '@core/css-substitution'
+import { encodeSubstitutionDeclarations } from '@core/css-substitution'
 import { matchMediaQueryToViewport } from './mediaQueryMatch'
+import {
+  mergeRuleBaseDeclarations,
+  mergeRuleContextDeclarations,
+  sparsePriorities,
+} from './declarationCascade'
+import { parseStyleDeclarations } from './cssDeclarationReader'
 import type {
   ImportWarning,
   BreakpointHint,
@@ -169,34 +175,6 @@ function extractUrlPayloads(value: string): string[] {
   return result
 }
 
-/**
- * Parse all declarations from a CSSStyleDeclaration into a camelCase Record.
- *
- * Phase 1a: the property gate is permissive — `isEmittableProperty` accepts
- * any valid CSS property name except a tiny denylist. So a real-site import
- * keeps every standard property (`flex-grow`, `grid-auto-flow`, …) instead of
- * dropping it. The only declarations dropped here are the genuinely
- * dead/dangerous denied names, surfaced as a (rare) `blocked-property`
- * warning rather than the old flood of `unknown-property`.
- *
- * The brief specifies using `.length` + index access (not `for...of`) since
- * CSSStyleDeclaration doesn't enumerate properties via Symbol.iterator.
- */
-function parseDeclarations(
-  style: CSSStyleDeclaration,
-  selectorForWarning: string,
-  warnings: ImportWarning[],
-): Record<string, unknown> {
-  return readCssDeclarationBag(style, (camel, kebab) => {
-    warnings.push({
-      kind: 'blocked-property',
-      message: `Property "${camel}" (${kebab}) is blocked for security and was dropped`,
-      selector: selectorForWarning,
-      property: camel,
-    })
-  })
-}
-
 /**
  * Scan a declarations map for `url(...)` values and append AssetRef entries.
  */
@@ -410,7 +388,8 @@ function processTopLevelRule(
       // by `animation-name`. They must publish globally or animation-start
       // states like `opacity: 0` never resolve to their final frame.
       processKeyframesRule(rule as CSSKeyframesRule, rules, warnings, assetRefs, {
-        parseDeclarations,
+        parseDeclarations: (style, selector, keyframeWarnings) =>
+          parseStyleDeclarations(style, selector, keyframeWarnings).styles,
         collectAssetRefsFromDecls,
       })
       return
@@ -553,7 +532,7 @@ function processBaseStyleRule(
 ): void {
   const selector = rule.selectorText.trim()
   const classified = classifySelector(selector)
-  const decls = parseDeclarations(rule.style, selector, warnings)
+  const declarations = parseStyleDeclarations(rule.style, selector, warnings)
 
   if (classified.kind === 'class') {
     if (seenClassSelectors.has(selector)) {
@@ -564,10 +543,9 @@ function processBaseStyleRule(
         selector,
       })
       const existingIdx = selectorToLastIndex.get(selector)!
-      // Overwrite base styles with the new declarations (last-write-wins)
-      Object.assign(rules[existingIdx].styles, decls)
+      mergeRuleBaseDeclarations(rules[existingIdx], declarations)
       // Collect any new asset refs from the updated declarations
-      collectAssetRefsFromDecls(decls, existingIdx, undefined, assetRefs)
+      collectAssetRefsFromDecls(declarations.styles, existingIdx, undefined, assetRefs)
       return
     }
     seenClassSelectors.add(selector)
@@ -579,11 +557,14 @@ function processBaseStyleRule(
     kind: classified.kind,
     selector,
     order: idx,
-    styles: decls,
+    styles: declarations.styles,
+    ...(sparsePriorities(declarations.priorities)
+      ? { stylePriorities: declarations.priorities }
+      : {}),
     contextStyles: {},
   })
   selectorToLastIndex.set(selector, idx)
-  collectAssetRefsFromDecls(decls, idx, undefined, assetRefs)
+  collectAssetRefsFromDecls(declarations.styles, idx, undefined, assetRefs)
 }
 
 // ---------------------------------------------------------------------------
@@ -680,7 +661,7 @@ function processConditionInner(
 
     const innerStyle = inner as CSSStyleRule
     const selector = innerStyle.selectorText.trim()
-    const decls = parseDeclarations(innerStyle.style, selector, warnings)
+    const declarations = parseStyleDeclarations(innerStyle.style, selector, warnings)
 
     // Find or create the rule for this selector
     let idx: number
@@ -701,8 +682,7 @@ function processConditionInner(
       if (classified.kind === 'class') seenClassSelectors.add(selector)
     }
 
-    const existing = (rules[idx].contextStyles[contextId] ?? {}) as Record<string, unknown>
-    rules[idx].contextStyles[contextId] = { ...existing, ...decls }
-    collectAssetRefsFromDecls(decls, idx, contextId, assetRefs)
+    mergeRuleContextDeclarations(rules[idx], contextId, declarations)
+    collectAssetRefsFromDecls(declarations.styles, idx, contextId, assetRefs)
   }
 }
diff --git a/src/core/siteImport/declarationCascade.ts b/src/core/siteImport/declarationCascade.ts
new file mode 100644
index 000000000..ccfbe5e9a
--- /dev/null
+++ b/src/core/siteImport/declarationCascade.ts
@@ -0,0 +1,117 @@
+import type { CSSDeclarationPriorityBag } from '@core/page-tree'
+import type { NewStyleRule } from './types'
+
+export interface DeclarationLayer {
+  styles: Record<string, unknown>
+  priorities: CSSDeclarationPriorityBag
+}
+
+export interface CascadedStyleRuleLayers {
+  styles: Record<string, unknown>
+  stylePriorities: CSSDeclarationPriorityBag
+  contextStyles: Record<string, Record<string, unknown>>
+  contextStylePriorities: Record<string, CSSDeclarationPriorityBag>
+}
+
+export function createCascadedStyleRuleLayers(): CascadedStyleRuleLayers {
+  return {
+    styles: {},
+    stylePriorities: {},
+    contextStyles: {},
+    contextStylePriorities: {},
+  }
+}
+
+/**
+ * Merge equal-specificity declaration fragments in source order. An existing
+ * important declaration resists a later normal declaration; otherwise the
+ * later value wins. Re-inserting winners also preserves their later authored
+ * position relative to shorthand declarations.
+ */
+export function mergeDeclarationCascade(
+  target: DeclarationLayer,
+  incoming: DeclarationLayer,
+): void {
+  for (const [property, value] of Object.entries(incoming.styles)) {
+    const currentImportant = target.priorities[property] === 'important'
+    const incomingImportant = incoming.priorities[property] === 'important'
+    if (currentImportant && !incomingImportant) continue
+
+    delete target.styles[property]
+    target.styles[property] = value
+    if (incomingImportant) target.priorities[property] = 'important'
+    else delete target.priorities[property]
+  }
+}
+
+export function mergeStyleRuleCascade(
+  target: CascadedStyleRuleLayers,
+  incoming: NewStyleRule,
+): void {
+  mergeDeclarationCascade(
+    { styles: target.styles, priorities: target.stylePriorities },
+    { styles: incoming.styles, priorities: incoming.stylePriorities ?? {} },
+  )
+  for (const [contextId, styles] of Object.entries(incoming.contextStyles ?? {})) {
+    if (!target.contextStyles[contextId]) target.contextStyles[contextId] = {}
+    if (!target.contextStylePriorities[contextId]) target.contextStylePriorities[contextId] = {}
+    mergeDeclarationCascade(
+      {
+        styles: target.contextStyles[contextId],
+        priorities: target.contextStylePriorities[contextId],
+      },
+      {
+        styles,
+        priorities: incoming.contextStylePriorities?.[contextId] ?? {},
+      },
+    )
+  }
+}
+
+export function sparsePriorities(
+  priorities: CSSDeclarationPriorityBag,
+): CSSDeclarationPriorityBag | undefined {
+  return Object.keys(priorities).length > 0 ? priorities : undefined
+}
+
+export function sparseContextPriorities(
+  priorities: Record<string, CSSDeclarationPriorityBag>,
+): Record<string, CSSDeclarationPriorityBag> | undefined {
+  const sparse = Object.fromEntries(
+    Object.entries(priorities).filter(([, bag]) => Object.keys(bag).length > 0),
+  )
+  return Object.keys(sparse).length > 0 ? sparse : undefined
+}
+
+export function mergeRuleBaseDeclarations(
+  rule: NewStyleRule,
+  incoming: DeclarationLayer,
+): void {
+  const priorities = { ...(rule.stylePriorities ?? {}) }
+  mergeDeclarationCascade({ styles: rule.styles, priorities }, incoming)
+  const sparse = sparsePriorities(priorities)
+  if (sparse) rule.stylePriorities = sparse
+  else delete rule.stylePriorities
+}
+
+export function mergeRuleContextDeclarations(
+  rule: NewStyleRule,
+  contextId: string,
+  incoming: DeclarationLayer,
+): void {
+  const styles = rule.contextStyles[contextId] ?? {}
+  const priorities = { ...(rule.contextStylePriorities?.[contextId] ?? {}) }
+  mergeDeclarationCascade({ styles, priorities }, incoming)
+  rule.contextStyles[contextId] = styles
+
+  const sparse = sparsePriorities(priorities)
+  if (sparse) {
+    if (!rule.contextStylePriorities) rule.contextStylePriorities = {}
+    rule.contextStylePriorities[contextId] = sparse
+  } else if (rule.contextStylePriorities) {
+    delete rule.contextStylePriorities[contextId]
+    if (Object.keys(rule.contextStylePriorities).length === 0) {
+      delete rule.contextStylePriorities
+    }
+  }
+}
diff --git a/src/core/siteImport/fontTokens.ts b/src/core/siteImport/fontTokens.ts
index ac150e796..dbc700b86 100644
--- a/src/core/siteImport/fontTokens.ts
+++ b/src/core/siteImport/fontTokens.ts
@@ -129,15 +129,28 @@ export function extractRootFontTokens(
     }
 
     const remaining: Record<string, unknown> = {}
+    const remainingPriorities: Record<string, 'important'> = {}
     for (const [prop, value] of Object.entries(rule.styles)) {
-      const token = typeof value === 'string' ? importTokenFromDeclaration(prop, value.trim()) : null
+      const important = rule.stylePriorities?.[prop] === 'important'
+      const token = !important && typeof value === 'string'
+        ? importTokenFromDeclaration(prop, value.trim())
+        : null
       if (token) fontTokens.push(token)
-      else remaining[prop] = value
+      else {
+        remaining[prop] = value
+        if (important) remainingPriorities[prop] = 'important'
+      }
     }
 
     const hasContext = Object.keys(rule.contextStyles ?? {}).length > 0
     if (Object.keys(remaining).length > 0 || hasContext) {
-      out.push({ ...rule, styles: remaining })
+      const rewritten = { ...rule, styles: remaining }
+      if (Object.keys(remainingPriorities).length > 0) {
+        rewritten.stylePriorities = remainingPriorities
+      } else {
+        delete rewritten.stylePriorities
+      }
+      out.push(rewritten)
     }
   }
 

From a6e7aab3b1ecf4632a6df47026f5881ea3c6b2b1 Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Sat, 11 Jul 2026 16:58:46 +0200
Subject: [PATCH 2/2] fix(agent): make CSS tool schema Anthropic-compatible

---
 docs/features/agent.md                        |  7 +-
 docs/reference/architecture-tests.md          |  1 +
 server/ai/tools/site/writeTools.ts            | 11 +--
 src/__tests__/agent/executor.test.ts          | 17 ++++
 .../architecture/ai-tool-input-object.test.ts | 26 ++++++
 .../architecture/ai-tool-schema-ssot.test.ts  | 10 ++-
 src/admin/pages/site/agent/cssTools.ts        |  4 +-
 src/admin/pages/site/agent/executor.ts        | 25 +++---
 src/core/ai/index.ts                          |  2 +
 src/core/ai/toolSchemas.ts                    | 81 ++++++++++++++-----
 10 files changed, 141 insertions(+), 43 deletions(-)
 create mode 100644 src/__tests__/architecture/ai-tool-input-object.test.ts

diff --git a/docs/features/agent.md b/docs/features/agent.md
index 4d8bfb2d2..d3ee642fb 100644
--- a/docs/features/agent.md
+++ b/docs/features/agent.md
@@ -18,7 +18,7 @@ The agent runs on a provider-agnostic AI runtime (`server/ai/`) that can drive a
 - **Content scope: 15 tools total.** 7 server-side content/catalog/media/user read tools + 8 browser-bridged document mutation/navigation tools.
 - **Two-endpoint bridge.** `POST /admin/api/ai/chat/:scope` opens an NDJSON stream. When the model calls a browser-bridged tool, the server emits `toolRequest`; the browser executor reads or mutates the live workspace and POSTs the `AiToolOutput` result to `POST /admin/api/ai/tool-result`.
 - **Provider-agnostic.** The runtime selects a driver (Anthropic, OpenAI, OpenRouter, Ollama, Custom Provider) from the conversation's configured credential.
-- **Site tool input schemas are a single source of truth** in `@core/ai` (`src/core/ai/toolSchemas.ts`). The server tool registry (`server/ai/tools/site/writeTools.ts`) and the browser executor (`executor.ts` + `tokenRunners.ts`) import the exact same schema objects — a constraint added once is enforced on both sides at build time. Gated by `ai-tool-schema-ssot.test.ts` and `ai-tools-typebox-only.test.ts`.
+- **Site tool input schemas are a single source of truth** in `@core/ai` (`src/core/ai/toolSchemas.ts`). The server registry and browser executor import from that shared leaf. Most tools reuse the exact same schema object; `site_apply_css` deliberately advertises a flat provider object because Anthropic rejects root-level schema composition, then the executor validates the payload against the leaf's exact operation union. Gated by `ai-tool-input-object.test.ts`, `ai-tool-schema-ssot.test.ts`, and `ai-tools-typebox-only.test.ts`.
 - **Capabilities.** `ai.chat` required to stream; `ai.tools.write` required for write tools. Gated by `ai-handlers-capability-gated.test.ts`.
 
 ---
@@ -28,7 +28,7 @@ The agent runs on a provider-agnostic AI runtime (`server/ai/`) that can drive a
 ```text
 src/core/ai/
 ├── toolOutput.ts           — AiToolOutput type + AiToolOutputSchema + aiToolOk / aiToolError
-├── toolSchemas.ts          — all site write-tool input schemas (single source of truth for both server and browser)
+├── toolSchemas.ts          — all site write-tool schemas; provider/execution layers for site_apply_css share field definitions here
 └── index.ts                — barrel re-export (canonical @core/ai import path)
 
 server/ai/
@@ -806,7 +806,7 @@ unblocks deletion of the credential that had been protected by the default FK.
   - `src/core/ai/chatRequest.ts` — canonical browser-to-server chat envelope and computed multi-image request ceiling
   - `src/core/ai/contentBlock.ts` — persisted/provider content blocks plus the lazy-URL conversation-detail view schema
   - `src/core/ai/userImage.ts` — accepted source formats, normalised JPEG schema, byte/dimension limits, and eight-image per-message bound
-  - `src/core/ai/toolSchemas.ts` — all site browser-tool input schemas (single source of truth; imported by both the server registry and the browser executor)
+  - `src/core/ai/toolSchemas.ts` — all site browser-tool input schemas (single source of truth); includes the flat provider schema and exact execution union required for `site_apply_css`
   - `src/core/ai/documentRefs.ts` — document refs/descriptors for pages, templates, and visual components
   - `src/core/ai/readSurface.ts` — runtime-agnostic `renderAgentDocument` annotated HTML + compact CSS renderer
   - `src/core/ai/index.ts` — barrel re-exporting the above
@@ -870,6 +870,7 @@ unblocks deletion of the credential that had been protected by the default FK.
   - `src/admin/pages/site/panels/AgentPanel/ContextMeter.tsx` — five-segment context status and rich usage tooltip
   - `src/admin/pages/site/panels/AgentPanel/contextMeterMetrics.ts` — exact five-band fill/tone calculation
 - Gate tests:
+  - `src/__tests__/architecture/ai-tool-input-object.test.ts`
   - `src/__tests__/architecture/ai-tool-schema-ssot.test.ts`
   - `src/__tests__/architecture/ai-driver-isolation.test.ts`
   - `src/__tests__/architecture/ai-tools-typebox-only.test.ts`
diff --git a/docs/reference/architecture-tests.md b/docs/reference/architecture-tests.md
index f6b09c7cb..2c8d56a8d 100644
--- a/docs/reference/architecture-tests.md
+++ b/docs/reference/architecture-tests.md
@@ -170,6 +170,7 @@ See [docs/features/plugin-system.md](../features/plugin-system.md).
 
 | Test                                          | What it enforces                                                                 |
 |-----------------------------------------------|----------------------------------------------------------------------------------|
+| `ai-tool-input-object.test.ts`                | Every provider-facing site/content tool schema has a plain `type: object` root with no root-level `anyOf`, `oneOf`, or `allOf`, matching Anthropic's tool-schema contract while keeping one cross-provider registry. |
 | `ai-tool-schema-ssot.test.ts`                 | Site write-tool input schemas live once in `src/core/ai/toolSchemas.ts` (re-exported from `@core/ai`). Every registered tool's `inputSchema` is the exact object from `@core/ai` (referential identity check); consumer modules (`writeTools.ts`, `executor.ts`, `tokenRunners.ts`) import from `@core/ai` and do not redeclare local copies. |
 | `ai-driver-isolation.test.ts`                 | Provider SDKs (`@anthropic-ai/claude-agent-sdk`, `@openai/agents`, `@openrouter/agent`), `zod`, and `@anthropic-ai/sdk` are banned repo-wide with no allowed callers. `@modelcontextprotocol/sdk` is **scoped**: allowed only under `server/ai/mcp/` (the MCP server), banned everywhere else (drivers + browser). Drivers talk directly to each provider's REST API over HTTP/SSE and pass TypeBox schemas through as JSON Schema. `src/` and `server/` are both scanned. |
 | `ai-mcp-connectors-never-leak.test.ts`        | The MCP connector wire projection (`toConnectorView`) and `McpConnectorViewSchema` never expose the token or its hash. Mirrors `ai-credentials-never-leak.test.ts`. |
diff --git a/server/ai/tools/site/writeTools.ts b/server/ai/tools/site/writeTools.ts
index 6ccd3a68f..384d1398c 100644
--- a/server/ai/tools/site/writeTools.ts
+++ b/server/ai/tools/site/writeTools.ts
@@ -12,11 +12,12 @@
  * site_render_snapshot, site_get_node_html).
  *
  * The input schemas are the single source of truth in `@core/ai`
- * (`src/core/ai/toolSchemas.ts`). This module imports each `*InputSchema`
- * for its tool `inputSchema`; the browser executor at
- * `src/admin/pages/site/agent/executor.ts` imports the SAME schemas to
- * validate each call. Neither side redeclares them, so a constraint added
- * here is enforced in the browser too — at build time.
+ * (`src/core/ai/toolSchemas.ts`). This module imports each provider-facing
+ * `*InputSchema`; the browser executor imports the same schemas for validation.
+ * `site_apply_css` has one deliberate second layer: providers receive a flat
+ * object because Anthropic rejects root schema composition, then the executor
+ * validates the call against the exact `ApplyCssExecutionInputSchema` union.
+ * Both CSS layers reuse the same field schemas in the shared leaf.
  */
 
 import {
diff --git a/src/__tests__/agent/executor.test.ts b/src/__tests__/agent/executor.test.ts
index 44715c9b8..32494c578 100644
--- a/src/__tests__/agent/executor.test.ts
+++ b/src/__tests__/agent/executor.test.ts
@@ -1000,6 +1000,23 @@ describe('executeAgentTool — applyCss', () => {
     expect(findRule((rule) => rule.selector === '.legacy-shape')).toBeUndefined()
   })
 
+  it('enforces required fields while tolerating optional siblings from the flat provider schema', async () => {
+    freshStore()
+    expectToolError(await executeAgentTool('site_apply_css', { operation: 'merge' }))
+    expectToolError(await executeAgentTool('site_apply_css', { operation: 'delete' }))
+    expectToolError(await executeAgentTool('site_apply_css', {
+      operation: 'remove-properties',
+      selectors: ['.card'],
+    }))
+    const result = await executeAgentTool('site_apply_css', {
+      operation: 'replace',
+      css: '.card { color: red; }',
+      selectors: ['.card'],
+    })
+    expectToolData(result)
+    expect(findRule((rule) => rule.selector === '.card')?.styles.color).toBe('red')
+  })
+
   it('creates a reusable class from a bare `.foo` selector', async () => {
     freshStore()
     const result = await executeAgentTool('site_apply_css', {
diff --git a/src/__tests__/architecture/ai-tool-input-object.test.ts b/src/__tests__/architecture/ai-tool-input-object.test.ts
new file mode 100644
index 000000000..0d7aa7cea
--- /dev/null
+++ b/src/__tests__/architecture/ai-tool-input-object.test.ts
@@ -0,0 +1,26 @@
+/**
+ * Architecture Gate — provider-facing tool inputs are object-rooted schemas.
+ *
+ * Anthropic requires `input_schema.type === "object"` and rejects top-level
+ * `anyOf`/`oneOf`/`allOf`; OpenAI-compatible providers and Instatic's MCP
+ * adapter use the same canonical TypeBox schema. Keep that provider contract
+ * in the shared registry instead of repairing schemas in individual drivers.
+ */
+
+import { describe, expect, it } from 'bun:test'
+import { contentTools } from '../../../server/ai/tools/content'
+import { siteTools } from '../../../server/ai/tools/site'
+
+describe('AI tool input object gate', () => {
+  it('every registered tool advertises an object-rooted input schema', () => {
+    for (const tool of [...siteTools, ...contentTools]) {
+      expect(
+        tool.inputSchema.type,
+        `${tool.name} must expose a top-level JSON Schema object`,
+      ).toBe('object')
+      expect(tool.inputSchema.anyOf, `${tool.name} cannot compose its schema root`).toBeUndefined()
+      expect(tool.inputSchema.oneOf, `${tool.name} cannot compose its schema root`).toBeUndefined()
+      expect(tool.inputSchema.allOf, `${tool.name} cannot compose its schema root`).toBeUndefined()
+    }
+  })
+})
diff --git a/src/__tests__/architecture/ai-tool-schema-ssot.test.ts b/src/__tests__/architecture/ai-tool-schema-ssot.test.ts
index c113f9051..9a1ffaf2c 100644
--- a/src/__tests__/architecture/ai-tool-schema-ssot.test.ts
+++ b/src/__tests__/architecture/ai-tool-schema-ssot.test.ts
@@ -4,12 +4,14 @@
  * The site write-tool input schemas (`site_insert_html`, `site_update_node_props`,
  * `site_set_color_tokens`, …) live ONCE in the dependency-free leaf
  * `src/core/ai/toolSchemas.ts` (re-exported from `@core/ai`). They are
- * consumed by BOTH sides of the browser bridge:
+ * consumed across BOTH sides of the browser bridge:
  *
  *   - the server tool registry (`server/ai/tools/site/writeTools.ts`) advertises
  *     each schema as the tool's `inputSchema`;
  *   - the browser executor (`src/admin/pages/site/agent/executor.ts`) and token
- *     runners (`tokenRunners.ts`) validate each `toolRequest` payload against it.
+ *     runners (`tokenRunners.ts`) validate each `toolRequest` payload from the
+ *     same leaf. `site_apply_css` uses the leaf's exact execution union because
+ *     Anthropic requires its advertised schema to stay a flat object.
  *
  * Before this leaf existed the schemas were declared three times and silently
  * drifted, so a server-side constraint never reached the browser validator.
@@ -21,8 +23,8 @@
  *   2. NO RE-DECLARATION — the consumer modules import the schemas and do not
  *      define their own `const xxxSchema = Type.Object(...)` tool-input copies.
  *
- * Type-level drift is additionally caught by the compiler: both consumers use
- * the leaf's `Static` types, so adding a required field breaks both at build.
+ * Type-level drift is additionally caught by the compiler: consumers use the
+ * leaf's schema-derived types, including the exact CSS execution-input type.
  */
 
 import { describe, it, expect } from 'bun:test'
diff --git a/src/admin/pages/site/agent/cssTools.ts b/src/admin/pages/site/agent/cssTools.ts
index 3c99c84c2..31ad45929 100644
--- a/src/admin/pages/site/agent/cssTools.ts
+++ b/src/admin/pages/site/agent/cssTools.ts
@@ -2,7 +2,7 @@ import {
   aiToolError,
   aiToolOk,
   type AiToolOutput,
-  type ApplyCssInput,
+  type ApplyCssExecutionInput,
 } from '@core/ai'
 import type { ConditionDef } from '@core/page-tree'
 import { cssToStyleRules, type NewStyleRule } from '@core/siteImport'
@@ -36,7 +36,7 @@ export function parseImportedStyleCss(styleCss: string): {
 }
 
 /** Apply an exact-selector CSS mutation to the live site's style registry. */
-export function runApplyCss(input: ApplyCssInput): AiToolOutput {
+export function runApplyCss(input: ApplyCssExecutionInput): AiToolOutput {
   if (input.operation === 'delete') {
     const result = getStoreState().deleteCssRules(input.selectors)
     if (result.missingSelectors.length > 0) {
diff --git a/src/admin/pages/site/agent/executor.ts b/src/admin/pages/site/agent/executor.ts
index 145dfe032..30a14d0df 100644
--- a/src/admin/pages/site/agent/executor.ts
+++ b/src/admin/pages/site/agent/executor.ts
@@ -32,6 +32,7 @@ import {
   RenameNodeInputSchema,
   DuplicateNodeInputSchema,
   ApplyCssInputSchema,
+  ApplyCssExecutionInputSchema,
   AssignClassInputSchema,
   RemoveClassInputSchema,
   ListCodeAssetsInputSchema,
@@ -105,16 +106,16 @@ const getStoreState = (): EditorStore => getAgentStoreApi<EditorStore>().getStat
 // ---------------------------------------------------------------------------
 // Tool input validation
 //
-// The per-tool input schemas are the single source of truth in `@core/ai`
-// (`src/core/ai/toolSchemas.ts`) — the SAME schemas the server advertises as
-// each tool's `inputSchema` in `server/ai/tools/site/writeTools.ts`. The
-// executor imports them and re-validates each `toolRequest` payload here with
-// `parseValue` — defence-in-depth at the store boundary (Constraint #272).
+// The provider-facing and execution input schemas have one source in `@core/ai`
+// (`src/core/ai/toolSchemas.ts`). The executor imports them and validates each
+// `toolRequest` payload here with `parseValue` — defence-in-depth at the store
+// boundary (Constraint #272). Most tools use one schema for both layers.
 //
-// `site_render_snapshot` is the one divergence: the model-facing schema carries only
-// `breakpointId`/`nodeId`, so we compose the server-set `captureScreenshot`
-// flag (chosen from the model's vision capability — non-vision models skip the
-// expensive html-to-image capture) on top of the shared shape here.
+// Two deliberate provider-boundary layers live here:
+// - `site_render_snapshot` composes the server-set `captureScreenshot` flag
+//   onto its model-facing schema.
+// - `site_apply_css` advertises a flat provider-compatible object, then uses
+//   `ApplyCssExecutionInputSchema` here for exact operation-specific fields.
 // ---------------------------------------------------------------------------
 
 const renderSnapshotSchema = Type.Composite([
@@ -607,8 +608,10 @@ export async function executeAgentTool(
         return runMoveNode(parseValue(MoveNodeInputSchema, rawInput))
       case 'site_rename_node':
         return runRenameNode(parseValue(RenameNodeInputSchema, rawInput))
-      case 'site_apply_css':
-        return runApplyCss(parseValue(ApplyCssInputSchema, rawInput))
+      case 'site_apply_css': {
+        const providerInput = parseValue(ApplyCssInputSchema, rawInput)
+        return runApplyCss(parseValue(ApplyCssExecutionInputSchema, providerInput))
+      }
       case 'site_list_code_assets':
         return await runListCodeAssets(parseValue(ListCodeAssetsInputSchema, rawInput))
       case 'site_read_code_asset':
diff --git a/src/core/ai/index.ts b/src/core/ai/index.ts
index a4bcdb4fb..790392fed 100644
--- a/src/core/ai/index.ts
+++ b/src/core/ai/index.ts
@@ -53,6 +53,7 @@ export {
   RenameNodeInputSchema,
   DuplicateNodeInputSchema,
   ApplyCssInputSchema,
+  ApplyCssExecutionInputSchema,
   AssignClassInputSchema,
   RemoveClassInputSchema,
   ListCodeAssetsInputSchema,
@@ -85,6 +86,7 @@ export type {
   RenameNodeInput,
   DuplicateNodeInput,
   ApplyCssInput,
+  ApplyCssExecutionInput,
   AssignClassInput,
   RemoveClassInput,
   ListCodeAssetsInput,
diff --git a/src/core/ai/toolSchemas.ts b/src/core/ai/toolSchemas.ts
index 38255bf1d..217377e7b 100644
--- a/src/core/ai/toolSchemas.ts
+++ b/src/core/ai/toolSchemas.ts
@@ -19,10 +19,15 @@
  * browser-runtime imports — so both `server/` and `src/admin/` may import it
  * (mirrors `@core/css-sanitize` / `@core/framework-schema`). Keep it that way.
  *
- * `render_snapshot` is the one legitimate divergence: the model-facing schema
- * (`RenderSnapshotInputSchema`) exposes only `breakpointId`/`nodeId`, while the
- * executor adds a server-set `captureScreenshot` flag on top — see that schema
- * and the executor's composed `renderSnapshotInputSchema`.
+ * Two provider-boundary constraints intentionally add a second validation
+ * layer in the browser executor:
+ *
+ *   - `render_snapshot` adds the server-set `captureScreenshot` flag on top of
+ *     the model-facing `RenderSnapshotInputSchema`.
+ *   - `site_apply_css` advertises one flat object because Anthropic rejects
+ *     `anyOf`/`oneOf`/`allOf` at a tool schema's root. The executor validates
+ *     that object against `ApplyCssExecutionInputSchema`, the exact
+ *     discriminated union. Both schemas reuse the field definitions below.
  */
 
 import { Type, type Static } from '@core/utils/typeboxHelpers'
@@ -119,44 +124,84 @@ export type DuplicateNodeInput = Static<typeof DuplicateNodeInputSchema>
 // CSS + class-assignment write tools
 // ---------------------------------------------------------------------------
 
-const CssTextInputSchema = Type.String({ minLength: 1 })
+const CssTextInputSchema = Type.String({
+  minLength: 1,
+  description: 'Required for merge and replace. Contains complete CSS rules, including their selectors.',
+})
 const CssSelectorListInputSchema = Type.Array(
   Type.String({ minLength: 1 }),
-  { minItems: 1, maxItems: 100, uniqueItems: true },
+  {
+    minItems: 1,
+    maxItems: 100,
+    uniqueItems: true,
+    description: 'Required for delete and remove-properties. Each entry is one exact emitted selector.',
+  },
 )
 const CssPropertyNameInputSchema = Type.String({
   minLength: 1,
   pattern: '^-{0,2}[a-zA-Z][a-zA-Z0-9-]*$',
 })
+const CssPropertyListInputSchema = Type.Array(
+  CssPropertyNameInputSchema,
+  {
+    minItems: 1,
+    maxItems: 100,
+    uniqueItems: true,
+    description: 'Required only for remove-properties. Names use CSS kebab-case, including vendor/custom properties.',
+  },
+)
+const CssMergeOperationSchema = Type.Literal('merge')
+const CssReplaceOperationSchema = Type.Literal('replace')
+const CssDeleteOperationSchema = Type.Literal('delete')
+const CssRemovePropertiesOperationSchema = Type.Literal('remove-properties')
+const CssOperationSchema = Type.Union([
+  CssMergeOperationSchema,
+  CssReplaceOperationSchema,
+  CssDeleteOperationSchema,
+  CssRemovePropertiesOperationSchema,
+], {
+  description: 'The CSS mutation to perform. Its required companion fields are documented on css, selectors, and properties.',
+})
 
 /**
- * One explicit CSS-registry mutation. The discriminator keeps destructive
- * replacement/deletion impossible to trigger accidentally by omitting an
- * optional flag from a normal merge.
+ * Provider-facing tool schema. Tool providers require an ordinary object at
+ * the root, and Anthropic explicitly rejects root-level schema composition.
+ * The descriptions state each operation's required fields; the browser then
+ * enforces the exact discriminated shape with ApplyCssExecutionInputSchema.
  */
-export const ApplyCssInputSchema = Type.Union([
+export const ApplyCssInputSchema = Type.Object({
+  operation: CssOperationSchema,
+  css: Type.Optional(CssTextInputSchema),
+  selectors: Type.Optional(CssSelectorListInputSchema),
+  properties: Type.Optional(CssPropertyListInputSchema),
+}, { additionalProperties: false })
+
+/**
+ * Exact CSS-registry mutation accepted at the editor-store boundary. The
+ * discriminator keeps destructive replacement/deletion impossible to trigger
+ * accidentally by omitting an optional field from a normal merge.
+ */
+export const ApplyCssExecutionInputSchema = Type.Union([
   Type.Object({
-    operation: Type.Literal('merge'),
+    operation: CssMergeOperationSchema,
     css: CssTextInputSchema,
   }),
   Type.Object({
-    operation: Type.Literal('replace'),
+    operation: CssReplaceOperationSchema,
     css: CssTextInputSchema,
   }),
   Type.Object({
-    operation: Type.Literal('delete'),
+    operation: CssDeleteOperationSchema,
     selectors: CssSelectorListInputSchema,
   }),
   Type.Object({
-    operation: Type.Literal('remove-properties'),
+    operation: CssRemovePropertiesOperationSchema,
     selectors: CssSelectorListInputSchema,
-    properties: Type.Array(
-      CssPropertyNameInputSchema,
-      { minItems: 1, maxItems: 100, uniqueItems: true },
-    ),
+    properties: CssPropertyListInputSchema,
   }),
 ])
 export type ApplyCssInput = Static<typeof ApplyCssInputSchema>
+export type ApplyCssExecutionInput = Static<typeof ApplyCssExecutionInputSchema>
 
 export const AssignClassInputSchema = Type.Object({
   nodeId: Type.String({ minLength: 1 }),