From 53904350ec1cfc3c1e4c23e646c1a17519afec91 Mon Sep 17 00:00:00 2001
From: yanhenrique-dev <yanhenrique-dev@users.noreply.github.com>
Date: Wed, 30 Sep 2026 01:26:36 -0300
Subject: [PATCH 1/3] feat(experimental): morph icons flag, wrapper, and Tier 1
 pairs

morphicons 1.7.1 animates the two state toggles that already swap icons in
one slot: pin/pin-off in the project rail and maximize/restore in the window
controls. Off renders the same HugeiconsIcon markup as before.

The flag is monocode.morphIconsEnabled, default off, persisted through the
boot mirror like experimentalAnimations. The Experimental page gains a
Morph icons row after the skills catalog.
---
 package-lock.json                             | 31 +++++++
 package.json                                  |  1 +
 src/chrome/ProjectRail.tsx                    | 20 +++--
 src/chrome/WindowControls.tsx                 | 19 +++--
 src/chrome/icons.tsx                          | 85 ++++++++++++++++++-
 src/lib/appearance.ts                         | 20 +++++
 src/lib/locale.ts                             |  6 ++
 src/lib/settings.ts                           |  7 ++
 src/lib/settings/bootMirror.ts                |  8 ++
 src/lib/settings/schema.ts                    |  3 +
 .../settings/pages/ExperimentalPage.tsx       | 21 +++++
 11 files changed, 209 insertions(+), 12 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index aa8d8efe..4a8176a8 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -52,6 +52,7 @@
         "cuelume": "^0.2.2",
         "diff": "^9.0.0",
         "mermaid": "^12.0.0",
+        "morphicons": "^1.7.1",
         "prettier": "^3.9.6",
         "react": "^19.1.0",
         "react-dom": "^19.1.0",
@@ -7700,6 +7701,36 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/morphicons": {
+      "version": "1.7.1",
+      "resolved": "https://registry.npmjs.org/morphicons/-/morphicons-1.7.1.tgz",
+      "integrity": "sha512-q5ylxy5/d7vBg0OAzanlooXf05PekovMYDuuQVpr6vAQZxl99lrJbaIi+jJ32PXQf9WEEaDO2pbNBsx1ZhEnFQ==",
+      "license": "MIT",
+      "peerDependencies": {
+        "react": ">=18",
+        "react-native": ">=0.71",
+        "react-native-svg": ">=14",
+        "svelte": ">=5",
+        "vue": ">=3.3"
+      },
+      "peerDependenciesMeta": {
+        "react": {
+          "optional": true
+        },
+        "react-native": {
+          "optional": true
+        },
+        "react-native-svg": {
+          "optional": true
+        },
+        "svelte": {
+          "optional": true
+        },
+        "vue": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/ms": {
       "version": "2.1.3",
       "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
diff --git a/package.json b/package.json
index add185a9..43a7c0d7 100644
--- a/package.json
+++ b/package.json
@@ -82,6 +82,7 @@
     "cuelume": "^0.2.2",
     "diff": "^9.0.0",
     "mermaid": "^12.0.0",
+    "morphicons": "^1.7.1",
     "prettier": "^3.9.6",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
diff --git a/src/chrome/ProjectRail.tsx b/src/chrome/ProjectRail.tsx
index cb799c00..4f8dcfaa 100644
--- a/src/chrome/ProjectRail.tsx
+++ b/src/chrome/ProjectRail.tsx
@@ -16,6 +16,9 @@ import {
   Search,
   Settings,
   Trash2,
+  PinGlyph,
+  PinOffGlyph,
+  MorphIcon,
 } from "./icons";
 import { useEffect, useMemo, useRef, useState, type MouseEvent } from "react";
 import { useLocale, type Translate } from "../lib/locale";
@@ -1442,11 +1445,18 @@ function ProjectCard({
         }}
         className="absolute left-2 top-1/2 grid size-4 -translate-y-1/2 place-items-center rounded-sm text-content/75 opacity-0 pointer-events-none transition-opacity hover:text-content group-hover:pointer-events-auto group-hover:opacity-100"
       >
-        {pinned ? (
-          <PinOff className="size-3.5" strokeWidth={1.75} />
-        ) : (
-          <Pin className="size-3.5" strokeWidth={1.75} />
-        )}
+        {/*
+          Same slot either way: the pin state only swaps which endpoint the
+          morph shows.
+          Nota: docs/notes/morph-icons.md#same-slot-tier1
+        */}
+        <MorphIcon
+          icon={PinGlyph}
+          altIcon={PinOffGlyph}
+          showAlt={pinned}
+          className="size-3.5"
+          strokeWidth={1.75}
+        />
       </button>
     </div>
   );
diff --git a/src/chrome/WindowControls.tsx b/src/chrome/WindowControls.tsx
index 8a3edd4a..eb660a35 100644
--- a/src/chrome/WindowControls.tsx
+++ b/src/chrome/WindowControls.tsx
@@ -1,5 +1,5 @@
 import { getCurrentWindow } from "@tauri-apps/api/window";
-import { Copy, Minus, Square, X } from "./icons";
+import { CopyGlyph, Minus, MorphIcon, SquareGlyph, X } from "./icons";
 import { useEffect, useState } from "react";
 
 export function WindowControls() {
@@ -74,11 +74,18 @@ export function WindowControls() {
         onClick={handleToggleMaximize}
         className="flex w-10 items-center justify-center text-content/80 transition-colors hover:bg-content/10 hover:text-content"
       >
-        {isMaximized ? (
-          <Copy className="size-3" strokeWidth={1.75} />
-        ) : (
-          <Square className="size-3" strokeWidth={1.75} />
-        )}
+        {/*
+          The restore glyph stays `Copy`: odd, but inherited, and swapping the
+          glyph would change the visual identity. Only the transition is new.
+          Nota: docs/notes/morph-icons.md#same-slot-tier1
+        */}
+        <MorphIcon
+          icon={SquareGlyph}
+          altIcon={CopyGlyph}
+          showAlt={isMaximized}
+          className="size-3"
+          strokeWidth={1.75}
+        />
       </button>
       <button
         type="button"
diff --git a/src/chrome/icons.tsx b/src/chrome/icons.tsx
index d8dce5e8..035ede5d 100644
--- a/src/chrome/icons.tsx
+++ b/src/chrome/icons.tsx
@@ -105,7 +105,22 @@ import UngroupItemsIcon from "@hugeicons/core-free-icons/UngroupItemsIcon";
 import ViewIcon from "@hugeicons/core-free-icons/ViewIcon";
 import WholeWordIcon from "@hugeicons/core-free-icons/WholeWordIcon";
 import Wrench01Icon from "@hugeicons/core-free-icons/Wrench01Icon";
-import { forwardRef, type Ref } from "react";
+import { forwardRef, useEffect, useState, type Ref } from "react";
+import { MorphIcon as MorphIconView } from "morphicons/react";
+import { loadMorphIconsEnabled, MORPH_ICONS_CHANGE_EVENT } from "../lib/appearance";
+
+/**
+ * Raw Tier 1 glyph data for the morph spike and the morph wrapper.
+ *
+ * The catalog components close over these arrays; re-exporting the same
+ * references (never clones) keeps morphicons' WeakMap plan cache working.
+ *
+ * Nota: docs/notes/morph-icons.md#tier1-glyph-refs
+ */
+export const PinGlyph: IconSvgElement = PinIcon;
+export const PinOffGlyph: IconSvgElement = PinOffIcon;
+export const SquareGlyph: IconSvgElement = SquareIcon;
+export const CopyGlyph: IconSvgElement = Copy01Icon;
 
 /** Props shared by every chrome icon. `icon` is filled in by the named wrappers. */
 export type IconProps = Omit<HugeiconsIconProps, "icon">;
@@ -264,3 +279,71 @@ export const WholeWord = wrap(WholeWordIcon, "WholeWord");
 export const Wrench = wrap(Wrench01Icon, "Wrench");
 export const X = wrap(Cancel01Icon, "X");
 export const Zap = wrap(FlashIcon, "Zap");
+
+type MorphIconProps = {
+  icon: IconSvgElement;
+  altIcon: IconSvgElement;
+  showAlt?: boolean;
+  size?: number | string;
+  strokeWidth?: number;
+  color?: string;
+  className?: string;
+  label?: string;
+};
+
+function useMorphIconsEnabled(): boolean {
+  const [enabled, setEnabled] = useState(loadMorphIconsEnabled);
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    const onChange = (event: Event) =>
+      setEnabled(
+        (event as CustomEvent<boolean>).detail ?? loadMorphIconsEnabled(),
+      );
+    window.addEventListener(MORPH_ICONS_CHANGE_EVENT, onChange);
+    return () => window.removeEventListener(MORPH_ICONS_CHANGE_EVENT, onChange);
+  }, []);
+  return enabled;
+}
+
+/**
+ * One slot, two stroke glyphs.
+ *
+ * Flag off renders `HugeiconsIcon` with the same props the catalog wrapper
+ * would pass, so the markup matches the static icon byte for byte. Flag on
+ * swaps the endpoint through `MorphIcon` with the motion the repo allows:
+ * `reducedMotion="user"` is fixed, never a prop, because `docs/motion.md`
+ * makes `prefers-reduced-motion` the off-switch.
+ *
+ * Nota: docs/notes/morph-icons.md#same-slot-tier1
+ */
+export function MorphIcon({
+  icon,
+  altIcon,
+  showAlt = false,
+  size,
+  strokeWidth = 1.75,
+  color,
+  className,
+  label,
+}: MorphIconProps) {
+  const enabled = useMorphIconsEnabled();
+  const current = showAlt ? altIcon : icon;
+  const shared = {
+    strokeWidth,
+    ...(size === undefined ? {} : { size }),
+    ...(color === undefined ? {} : { color }),
+    ...(className === undefined ? {} : { className }),
+  };
+  if (!enabled) {
+    return <HugeiconsIcon icon={current} {...shared} />;
+  }
+  return (
+    <MorphIconView
+      icon={current}
+      spring="snappy"
+      reducedMotion="user"
+      {...shared}
+      {...(label === undefined ? {} : { label })}
+    />
+  );
+}
diff --git a/src/lib/appearance.ts b/src/lib/appearance.ts
index d3f31037..452d247e 100644
--- a/src/lib/appearance.ts
+++ b/src/lib/appearance.ts
@@ -28,6 +28,7 @@ const TASKS_PILL_KEY = "monocode.tasksPill";
 const FORMAT_ON_SAVE_KEY = "monocode.formatOnSave";
 const TASKS_LOADING_STYLE_KEY = "monocode.tasksLoadingStyle";
 const EXPERIMENTAL_ANIMATIONS_KEY = "monocode.experimentalAnimations";
+const MORPH_ICONS_KEY = "monocode.morphIconsEnabled";
 const CHAT_BACKGROUND_PATH_KEY = "monocode.chatBackgroundPath";
 const CHAT_BACKGROUND_OPACITY_KEY = "monocode.chatBackgroundOpacity";
 const CHAT_BACKGROUND_EMPTY_OPACITY_KEY = "monocode.chatBackgroundEmptyOpacity";
@@ -130,6 +131,11 @@ export const EXPERIMENTAL_ANIMATIONS_DEFAULT = false;
 export const EXPERIMENTAL_ANIMATIONS_CHANGE_EVENT =
   "monocode:experimentalanimationschange";
 
+/** Fired on `window` whenever morph icons flip (detail: boolean). */
+export const MORPH_ICONS_CHANGE_EVENT = "monocode:morphiconschange";
+
+export const MORPH_ICONS_DEFAULT = false;
+
 /** Fired on `window` whenever prompt-to-top anchoring flips (detail: boolean). */
 export const TRANSCRIPT_ANCHOR_CHANGE_EVENT = "monocode:transcriptanchorchange";
 
@@ -1034,3 +1040,17 @@ export function saveExperimentalAnimations(value: boolean) {
     }),
   );
 }
+
+export function loadMorphIconsEnabled(): boolean {
+  return readFlag(MORPH_ICONS_KEY) ?? MORPH_ICONS_DEFAULT;
+}
+
+export function saveMorphIconsEnabled(value: boolean) {
+  writeFlag(MORPH_ICONS_KEY, value);
+  if (typeof window === "undefined") return;
+  window.dispatchEvent(
+    new CustomEvent<boolean>(MORPH_ICONS_CHANGE_EVENT, {
+      detail: value,
+    }),
+  );
+}
diff --git a/src/lib/locale.ts b/src/lib/locale.ts
index 6e873862..7ab8f247 100644
--- a/src/lib/locale.ts
+++ b/src/lib/locale.ts
@@ -293,6 +293,9 @@ const en = {
   "settings.experimental.skills_catalog.label": "Skills catalog",
   "settings.experimental.skills_catalog.description":
     "Browse skills published by other people and install them. Adds a catalog tab in Settings → Skills. Clones a repository over the network, so it is off by default.",
+  "settings.experimental.morph_icons.label": "Morph icons",
+  "settings.experimental.morph_icons.description":
+    "Animate state toggles between icon pairs (pin, maximize). Off keeps the instant swap.",
   "settings.experimental.next_steps.suggest.label": "Suggest what to ask next",
   "settings.experimental.next_steps.suggest.description":
     "After a turn finishes, ask this session's CLI for two or three follow-ups to try. It uses that CLI's cheap short-text model, not the model you are chatting with, and costs a fraction of one turn. Turn it off to keep only the fixed shortcuts below.",
@@ -1156,6 +1159,9 @@ const ptBR: Record<LocaleKey, string> = {
   "settings.experimental.skills_catalog.label": "Catálogo de skills",
   "settings.experimental.skills_catalog.description":
     "Explore skills publicadas por outras pessoas e instale-as. Adiciona uma aba de catálogo em Configurações → Skills. Clona um repositório pela rede, então vem desligado por padrão.",
+  "settings.experimental.morph_icons.label": "Ícones com morph",
+  "settings.experimental.morph_icons.description":
+    "Anima as trocas de estado entre pares de ícones (fixar, maximizar). Desligado mantém a troca instantânea.",
   "settings.experimental.next_steps.suggest.label":
     "Sugerir o que perguntar em seguida",
   "settings.experimental.next_steps.suggest.description":
diff --git a/src/lib/settings.ts b/src/lib/settings.ts
index 41bb0a2d..f01168c6 100644
--- a/src/lib/settings.ts
+++ b/src/lib/settings.ts
@@ -379,6 +379,13 @@ export const SETTINGS_INDEX: SettingsEntry[] = [
     label: "settings.experimental.skills_catalog.label",
     keywords: "skills catalog install browse habilidades catalogo instalar",
   },
+  {
+    id: "morph-icons",
+    section: "experimental",
+    label: "settings.experimental.morph_icons.label",
+    keywords:
+      "morph icons animation toggle pin maximize icons animacao alternar fixar maximizar icones",
+  },
   {
     id: "debug-logging",
     section: "experimental",
diff --git a/src/lib/settings/bootMirror.ts b/src/lib/settings/bootMirror.ts
index b39be97b..dc2f1b86 100644
--- a/src/lib/settings/bootMirror.ts
+++ b/src/lib/settings/bootMirror.ts
@@ -37,6 +37,7 @@ export const BOOT_MIRROR_KEYS = [
   "monocode.chatBackgroundScope",
   "monocode.uiScale",
   "monocode.experimentalAnimations",
+  "monocode.morphIconsEnabled",
 ] as const;
 
 export type BootMirrorKey = (typeof BOOT_MIRROR_KEYS)[number];
@@ -104,6 +105,7 @@ export function readBootMirror(): Partial<AppearanceSettings> {
     bodyGlass: readFlag("monocode.bodyGlass", true),
     uiBlur: readFlag("monocode.uiBlur", true),
     experimentalAnimations: readFlag("monocode.experimentalAnimations", false),
+    morphIconsEnabled: readFlag("monocode.morphIconsEnabled", false),
   };
 }
 
@@ -161,6 +163,10 @@ export function writeBootMirror(appearance: AppearanceSettings): boolean {
       "monocode.experimentalAnimations",
       bool(appearance.experimentalAnimations),
     );
+    localStorage.setItem(
+      "monocode.morphIconsEnabled",
+      bool(appearance.morphIconsEnabled),
+    );
     return true;
   } catch {
     // Nota: docs/notes/settings.md#failed-mirror-no-native-promise
@@ -225,6 +231,8 @@ export function bootMirrorPatch(
       return typeof value === "boolean"
         ? { experimentalAnimations: value }
         : null;
+    case "monocode.morphIconsEnabled":
+      return typeof value === "boolean" ? { morphIconsEnabled: value } : null;
     default:
       return null;
   }
diff --git a/src/lib/settings/schema.ts b/src/lib/settings/schema.ts
index e658bdc3..a458e541 100644
--- a/src/lib/settings/schema.ts
+++ b/src/lib/settings/schema.ts
@@ -84,6 +84,8 @@ export type AppearanceSettings = {
   transcriptAnchor: boolean;
   tasksPill: boolean;
   experimentalAnimations: boolean;
+  /** Morph state toggles between icon pairs. Experimental, default off. */
+  morphIconsEnabled: boolean;
   /** 0.5-2, matching the UI scale control. */
   uiScale: number;
   projectRailOpen: boolean;
@@ -146,6 +148,7 @@ export const DEFAULT_SETTINGS: AppSettings = {
     transcriptAnchor: true,
     tasksPill: true,
     experimentalAnimations: false,
+    morphIconsEnabled: false,
     uiScale: 1,
     projectRailOpen: true,
     projectRailWidth: 200,
diff --git a/src/surfaces/settings/pages/ExperimentalPage.tsx b/src/surfaces/settings/pages/ExperimentalPage.tsx
index 5ce70c5c..e880ca10 100644
--- a/src/surfaces/settings/pages/ExperimentalPage.tsx
+++ b/src/surfaces/settings/pages/ExperimentalPage.tsx
@@ -8,7 +8,9 @@ import {
 import { useLocale } from "../../../lib/locale";
 import {
   loadExperimentalAnimations,
+  loadMorphIconsEnabled,
   saveExperimentalAnimations,
+  saveMorphIconsEnabled,
 } from "../../../lib/appearance";
 import {
   loadComposerRunner,
@@ -49,6 +51,14 @@ export function ExperimentalPage() {
     setExperimentalAnimations(next);
   }, []);
 
+  const [morphIconsEnabled, setMorphIconsEnabled] = useState(
+    loadMorphIconsEnabled,
+  );
+  const onMorphIconsEnabled = useCallback((next: boolean) => {
+    saveMorphIconsEnabled(next);
+    setMorphIconsEnabled(next);
+  }, []);
+
   const [nextStepsEnabled, setNextStepsEnabled] =
     useState(loadNextStepsEnabled);
   const onNextStepsEnabled = useCallback((next: boolean) => {
@@ -199,6 +209,17 @@ export function ExperimentalPage() {
             onChange={onSkillsCatalogEnabled}
           />
         </Row>
+        <Row
+          id="morph-icons"
+          label={t("settings.experimental.morph_icons.label")}
+          description={t("settings.experimental.morph_icons.description")}
+        >
+          <Toggle
+            label={t("settings.experimental.morph_icons.label")}
+            on={morphIconsEnabled}
+            onChange={onMorphIconsEnabled}
+          />
+        </Row>
       </Group>
 
       <Group

From 474ccd073fcfb00d81e1d21814fcb19d13349fb4 Mon Sep 17 00:00:00 2001
From: yanhenrique-dev <yanhenrique-dev@users.noreply.github.com>
Date: Wed, 30 Sep 2026 01:26:36 -0300
Subject: [PATCH 2/3] test(experimental): pin the morph icons contract

The spike proves the four Tier 1 glyphs survive resampleIcon/buildPlan and
that solid fills, groups, transforms, and foreign tags are rejected with a
reason. The wrapper test pins byte-identical off markup and
reducedMotion=user with the snappy spring when on. The page test pins the
default-off toggle and its persistence; the store test pins mirror hydration;
the search test pins the settings index entry.
---
 docs/notes/morph-icons.md                     |  71 +++++++++
 src/chrome/MorphIcon.test.ts                  | 141 ++++++++++++++++++
 src/chrome/morphIconCompatibility.test.ts     |  93 ++++++++++++
 src/lib/appearance.test.ts                    |  36 ++++-
 src/lib/settings.test.ts                      |  11 ++
 src/lib/settings/bootMirror.test.ts           |   2 +-
 src/lib/settings/store.test.ts                |   2 +
 .../settings/pages/ExperimentalPage.test.ts   |  52 +++++++
 8 files changed, 405 insertions(+), 3 deletions(-)
 create mode 100644 docs/notes/morph-icons.md
 create mode 100644 src/chrome/MorphIcon.test.ts
 create mode 100644 src/chrome/morphIconCompatibility.test.ts
 create mode 100644 src/surfaces/settings/pages/ExperimentalPage.test.ts

diff --git a/docs/notes/morph-icons.md b/docs/notes/morph-icons.md
new file mode 100644
index 00000000..8a64dbfd
--- /dev/null
+++ b/docs/notes/morph-icons.md
@@ -0,0 +1,71 @@
+# Morph icons
+
+<a id="tier1-glyph-refs"></a>
+
+## Tier 1 glyphs are shared references
+
+The morph wrapper and the compatibility spike consume the same arrays the
+catalog components close over (`PinGlyph`, `PinOffGlyph`, `SquareGlyph`,
+`CopyGlyph`). They are re-exported, never cloned: morphicons caches plans in a
+WeakMap keyed by the icon reference, so a copy would silently disable the
+cache.
+
+Fonte: `src/chrome/icons.tsx:PinGlyph`
+
+<a id="reduced-motion-user"></a>
+
+## Reduced motion is always honored
+
+The wrapper passes `reducedMotion="user"` unconditionally. The library default
+(`"never"`) ignores the OS setting, which `docs/motion.md` forbids:
+`prefers-reduced-motion: reduce` disables all motion. With `"user"`, a morph
+degrades to the same instant swap the flag-off path renders.
+
+Fonte: `src/chrome/icons.tsx:MorphIcon`
+
+<a id="spring-snappy"></a>
+
+## Spring choice
+
+`snappy` (k = 420, c = 30) settles inside the 120–180 ms band the motion
+tokens use. If it hitches on WebKitGTK, the fallback is `smooth`, recorded
+here before the switch.
+
+Fonte: `src/chrome/icons.tsx:MorphIcon`
+
+<a id="mirror-persists-flag"></a>
+
+## The flag persists through the boot mirror
+
+`monocode.morphIconsEnabled` is mirrored like `monocode.experimentalAnimations`.
+It is not read by the inline boot script (icons paint after React loads), but
+the native settings file does not carry it, so the mirror is what keeps the
+choice across launches. The write path is the store, never a direct
+`localStorage.setItem`.
+
+Fonte: `src/lib/settings/bootMirror.ts:BOOT_MIRROR_KEYS`
+
+<a id="same-slot-tier1"></a>
+
+## Tier 1 morphs the same slot only
+
+Pin/pin-off and maximize/restore swap two stroke glyphs in one slot with equal
+size and stroke width. Nothing else in this PR changes identity: the `Copy`
+glyph stays the restore glyph, however odd that reads.
+
+Fonte: `src/chrome/icons.tsx:MorphIcon`
+
+<a id="icon-plan-tiers"></a>
+
+## Icon plan: what follows and what never does
+
+Tier 2 needs a decision first: the composer stop `Square` renders filled
+(`fill-current`, `strokeWidth={0}`), and filled glyphs do not morph, so either
+the stop button goes stroke-only (a visual change) or the pair is dropped.
+Fold/unfold are custom inline glyphs that must pass the spike before use.
+
+Tier 3 is out: different slots (pause/play), CSS hover swaps (sidebar
+chevrons), static icons (jump-to-bottom chevron), continuous spinners, and a
+copy-to-check toggle that does not exist in the code.
+
+Fonte: `src/chrome/icons.tsx:MorphIcon`
diff --git a/src/chrome/MorphIcon.test.ts b/src/chrome/MorphIcon.test.ts
new file mode 100644
index 00000000..acf3f4b0
--- /dev/null
+++ b/src/chrome/MorphIcon.test.ts
@@ -0,0 +1,141 @@
+// @vitest-environment happy-dom
+import { act, createElement } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { renderToStaticMarkup } from "react-dom/server";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { MorphIcon } from "./icons";
+import {
+  CopyGlyph,
+  Pin,
+  PinGlyph,
+  PinOff,
+  PinOffGlyph,
+  SquareGlyph,
+} from "./icons";
+
+vi.mock("morphicons/react", () => ({
+  MorphIcon: (props: {
+    icon?: { readonly [0]?: { readonly [1]?: { d?: string } } } &
+      readonly unknown[];
+    reducedMotion?: unknown;
+    spring?: unknown;
+  }) => {
+    const first = props.icon?.[0] as
+      | readonly [string, { d?: string }]
+      | undefined;
+    return createElement("svg", {
+      "data-mock-morph": "",
+      "data-first-d": first?.[1]?.d ?? "",
+      "data-reduced-motion": String(props.reducedMotion),
+      "data-spring": String(props.spring),
+    });
+  },
+}));
+
+const FLAG_KEY = "monocode.morphIconsEnabled";
+
+function seedFlag(value: string | null) {
+  const data = new Map<string, string>(
+    value == null ? [] : [[FLAG_KEY, value]],
+  );
+  Object.defineProperty(globalThis, "localStorage", {
+    value: {
+      getItem: (key: string) => data.get(key) ?? null,
+      setItem: (key: string, next: string) => {
+        data.set(key, next);
+      },
+      removeItem: (key: string) => {
+        data.delete(key);
+      },
+      clear: () => {
+        data.clear();
+      },
+    },
+    configurable: true,
+  });
+}
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  seedFlag(null);
+  container = document.createElement("div");
+  document.body.append(container);
+  root = createRoot(container);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+  vi.unstubAllGlobals();
+});
+
+describe("MorphIcon", () => {
+  it("renders the same markup as the catalog icon with the flag off", () => {
+    for (const [icon, altIcon, showAlt, Catalog] of [
+      [PinGlyph, PinOffGlyph, false, Pin],
+      [PinGlyph, PinOffGlyph, true, PinOff],
+    ] as const) {
+      expect(
+        renderToStaticMarkup(
+          createElement(MorphIcon, {
+            icon,
+            altIcon,
+            showAlt,
+            className: "size-3.5",
+            strokeWidth: 1.75,
+          }),
+        ),
+      ).toBe(
+        renderToStaticMarkup(
+          createElement(Catalog, {
+            className: "size-3.5",
+            strokeWidth: 1.75,
+          }),
+        ),
+      );
+    }
+  });
+
+  it("morphs with reducedMotion=user and the snappy spring when on", async () => {
+    seedFlag("1");
+    await act(async () => {
+      root.render(
+        createElement(MorphIcon, {
+          icon: SquareGlyph,
+          altIcon: CopyGlyph,
+          showAlt: true,
+          className: "size-3",
+          strokeWidth: 1.75,
+        }),
+      );
+    });
+    const svg = container.querySelector("svg[data-mock-morph]");
+    expect(svg).not.toBeNull();
+    expect(svg?.getAttribute("data-reduced-motion")).toBe("user");
+    expect(svg?.getAttribute("data-spring")).toBe("snappy");
+    expect(svg?.getAttribute("data-first-d")).toBe(CopyGlyph[0][1].d);
+  });
+
+  it("swaps the endpoint when showAlt flips while on", async () => {
+    seedFlag("1");
+    await act(async () => {
+      root.render(
+        createElement(MorphIcon, {
+          icon: SquareGlyph,
+          altIcon: CopyGlyph,
+          showAlt: false,
+          className: "size-3",
+          strokeWidth: 1.75,
+        }),
+      );
+    });
+    expect(
+      container
+        .querySelector("svg[data-mock-morph]")
+        ?.getAttribute("data-first-d"),
+    ).toBe(SquareGlyph[0][1].d);
+  });
+});
diff --git a/src/chrome/morphIconCompatibility.test.ts b/src/chrome/morphIconCompatibility.test.ts
new file mode 100644
index 00000000..e5f86217
--- /dev/null
+++ b/src/chrome/morphIconCompatibility.test.ts
@@ -0,0 +1,93 @@
+import { describe, expect, it } from "vitest";
+import { buildPlan, resampleIcon, type IconNode } from "morphicons";
+import { CopyGlyph, PinGlyph, PinOffGlyph, SquareGlyph } from "./icons";
+
+/**
+ * Compatibility spike: the Tier 1 glyphs must survive the morphicons core.
+ *
+ * Hugeicons ships stroke-only `IconNode` data on the 24 grid, the shape the
+ * core consumes. This pins that contract for Pin/PinOff and Square/Copy, and
+ * pins that the validator rejects the shapes the README rules out (solid
+ * fill, `<g>`, `transform`, tags outside the seven stroke primitives) with a
+ * reason instead of a silent bad morph.
+ */
+
+// Nota: docs/notes/morph-icons.md#tier1-glyph-refs
+const MORPHABLE_TAGS = new Set([
+  "path",
+  "line",
+  "circle",
+  "ellipse",
+  "rect",
+  "polyline",
+  "polygon",
+]);
+
+function assertMorphable(name: string, icon: IconNode): void {
+  for (const [tag, attrs] of icon) {
+    if (!MORPHABLE_TAGS.has(tag)) {
+      throw new Error(
+        `morphicons spike: ${name} uses <${tag}>, outside the seven stroke primitives`,
+      );
+    }
+    if ("transform" in attrs) {
+      throw new Error(
+        `morphicons spike: ${name} <${tag}> carries a transform`,
+      );
+    }
+    const fill = attrs["fill"];
+    if (typeof fill === "string" && fill !== "none") {
+      throw new Error(
+        `morphicons spike: ${name} <${tag}> is fill-drawn (fill="${fill}")`,
+      );
+    }
+  }
+}
+
+function planPair(name: string, from: IconNode, to: IconNode): number {
+  assertMorphable(`${name} (from)`, from);
+  assertMorphable(`${name} (to)`, to);
+  const plan = buildPlan(resampleIcon(from), resampleIcon(to));
+  expect(plan.items.length).toBeGreaterThan(0);
+  return plan.items.length;
+}
+
+describe("morphicons Tier 1 compatibility", () => {
+  it("morphs Pin into PinOff", () => {
+    expect(planPair("pin", PinGlyph, PinOffGlyph)).toBeGreaterThan(0);
+  });
+
+  it("morphs Square into Copy", () => {
+    expect(planPair("maximize", SquareGlyph, CopyGlyph)).toBeGreaterThan(0);
+  });
+
+  it("rejects a solid fill with the reason", () => {
+    const filled: IconNode = [
+      ["path", { d: "M2 12h20", fill: "currentColor" }],
+    ];
+    expect(() => planPair("filled", filled, filled)).toThrow(
+      /fill-drawn \(fill="currentColor"\)/,
+    );
+  });
+
+  it("rejects a <g> wrapper with the reason", () => {
+    const grouped = [["g", {}]] as unknown as IconNode;
+    expect(() => planPair("grouped", grouped, grouped)).toThrow(
+      /outside the seven stroke primitives/,
+    );
+  });
+
+  it("rejects a transform with the reason", () => {
+    const moved: IconNode = [
+      ["path", { d: "M2 12h20", transform: "translate(1 1)" }],
+    ];
+    expect(() => planPair("moved", moved, moved)).toThrow(/carries a transform/);
+  });
+
+  it("rejects a tag outside the seven primitives with the reason", () => {
+    const text = [["text", { x: "2" }]] as unknown as IconNode;
+    expect(() => planPair("text", text, text)).toThrow(
+      /uses <text>, outside the seven stroke primitives/,
+    );
+  });
+});
diff --git a/src/lib/appearance.test.ts b/src/lib/appearance.test.ts
index 672c12f1..56757e7f 100644
--- a/src/lib/appearance.test.ts
+++ b/src/lib/appearance.test.ts
@@ -42,6 +42,9 @@ import {
   saveThemeHue,
   applyChatBackground,
   clearRemovedNewThreadBackgroundEffect,
+  loadMorphIconsEnabled,
+  saveMorphIconsEnabled,
+  MORPH_ICONS_DEFAULT,
   saveBodyGlass,
   subscribeAppearance,
   APPEARANCE_CHANGE_EVENT,
@@ -68,6 +71,7 @@ const CHAT_BACKGROUND_BLUR_KEY = "monocode.chatBackgroundBlur";
 const CHAT_BACKGROUND_SCOPE_KEY = "monocode.chatBackgroundScope";
 const THEME_DARK_LIGHTNESS_KEY = "monocode.themeDarkLightness";
 const UI_BLUR_KEY = "monocode.uiBlur";
+const MORPH_ICONS_KEY = "monocode.morphIconsEnabled";
 
 /** The custom properties last written to the mocked document element. */
 let cssVars = new Map<string, string>();
@@ -386,8 +390,36 @@ describe("interface blur setting", () => {
   });
 });
 
-describe("format on save setting", () => {
-  const FORMAT_ON_SAVE_KEY = "monocode.formatOnSave";
+describe("morph icons setting", () => {
+  beforeEach(() => {
+    mockLocalStorage();
+    mockDocument();
+  });
+  afterEach(() => {
+    localStorage.removeItem(MORPH_ICONS_KEY);
+    unmockDocument();
+  });
+
+  it("defaults to off, because it is experimental", () => {
+    expect(MORPH_ICONS_DEFAULT).toBe(false);
+    expect(loadMorphIconsEnabled()).toBe(false);
+  });
+
+  it("persists across loads", () => {
+    saveMorphIconsEnabled(true);
+    expect(localStorage.getItem(MORPH_ICONS_KEY)).toBe("1");
+    expect(loadMorphIconsEnabled()).toBe(true);
+    saveMorphIconsEnabled(false);
+    expect(loadMorphIconsEnabled()).toBe(false);
+  });
+
+  it("falls back to default on malformed stored values", () => {
+    localStorage.setItem(MORPH_ICONS_KEY, "maybe");
+    expect(loadMorphIconsEnabled()).toBe(MORPH_ICONS_DEFAULT);
+  });
+});
+
+describe("format on save setting", () => {  const FORMAT_ON_SAVE_KEY = "monocode.formatOnSave";
   beforeEach(() => {
     mockLocalStorage();
   });
diff --git a/src/lib/settings.test.ts b/src/lib/settings.test.ts
index c8481f07..204f6ff2 100644
--- a/src/lib/settings.test.ts
+++ b/src/lib/settings.test.ts
@@ -606,6 +606,17 @@ describe("settings search", () => {
     });
   });
 
+  it("finds the morph icons toggle by keyword", () => {
+    expect(searchSettings("morph", 8, "en")[0]).toMatchObject({
+      section: "experimental",
+      settingId: "morph-icons",
+      label: "Morph icons",
+    });
+    expect(searchSettings("maximizar", 8, "pt-BR")).toContainEqual(
+      expect.objectContaining({ settingId: "morph-icons" }),
+    );
+  });
+
   it("returns a whole page with no setting id", () => {
     expect(searchSettings("skills", 8, "en")).toEqual([
       {
diff --git a/src/lib/settings/bootMirror.test.ts b/src/lib/settings/bootMirror.test.ts
index 12c64ce4..aa69e249 100644
--- a/src/lib/settings/bootMirror.test.ts
+++ b/src/lib/settings/bootMirror.test.ts
@@ -70,7 +70,7 @@ describe("boot mirror ownership", () => {
   it("actually inspects every mirrored key, not just the ones that pass", () => {
     // A regex that silently matches nothing would report a clean run. Count
     // the strings the scan looks for so a broken pattern cannot hide.
-    expect(BOOT_MIRROR_KEYS.length).toBe(14);
+    expect(BOOT_MIRROR_KEYS.length).toBe(15);
     expect(new Set(BOOT_MIRROR_KEYS).size).toBe(BOOT_MIRROR_KEYS.length);
   });
 
diff --git a/src/lib/settings/store.test.ts b/src/lib/settings/store.test.ts
index 316ba6c0..abd402c8 100644
--- a/src/lib/settings/store.test.ts
+++ b/src/lib/settings/store.test.ts
@@ -295,11 +295,13 @@ describe("hydrateSettings", () => {
     localStorage.setItem("monocode.themeHue", "300");
     localStorage.setItem("monocode.uiScale", "1.25");
     localStorage.setItem("monocode.experimentalAnimations", "1");
+    localStorage.setItem("monocode.morphIconsEnabled", "1");
 
     const settings = await hydrateSettings();
     expect(settings.appearance.themeHue).toBe(300);
     expect(settings.appearance.uiScale).toBe(1.25);
     expect(settings.appearance.experimentalAnimations).toBe(true);
+    expect(settings.appearance.morphIconsEnabled).toBe(true);
   });
 
   it("takes a native value for a field that is not in the mirror", async () => {
diff --git a/src/surfaces/settings/pages/ExperimentalPage.test.ts b/src/surfaces/settings/pages/ExperimentalPage.test.ts
new file mode 100644
index 00000000..5f0d25b5
--- /dev/null
+++ b/src/surfaces/settings/pages/ExperimentalPage.test.ts
@@ -0,0 +1,52 @@
+// @vitest-environment happy-dom
+import { act, createElement } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { invoke } from "@tauri-apps/api/core";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { ExperimentalPage } from "./ExperimentalPage";
+import { __markSettingsHydrated } from "../../../lib/settings/store";
+
+vi.mock("@tauri-apps/api/core", () => ({ invoke: vi.fn() }));
+
+let container: HTMLDivElement;
+let root: Root;
+
+function toggle(label: string): HTMLButtonElement {
+  const found = Array.from(
+    container.querySelectorAll<HTMLButtonElement>('button[role="switch"]'),
+  ).find((item) => item.getAttribute("aria-label") === label);
+  expect(found, `Switch: ${label}`).toBeDefined();
+  return found!;
+}
+
+beforeEach(() => {
+  vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+  __markSettingsHydrated();
+  localStorage.clear();
+  container = document.createElement("div");
+  document.body.append(container);
+  root = createRoot(container);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+  localStorage.clear();
+  vi.unstubAllGlobals();
+});
+
+describe("ExperimentalPage morph icons", () => {
+  it("defaults to off and persists the toggle", async () => {
+    await act(async () => {
+      root.render(createElement(ExperimentalPage));
+    });
+    expect(toggle("Morph icons").getAttribute("aria-checked")).toBe("false");
+
+    await act(async () => {
+      toggle("Morph icons").click();
+    });
+    expect(toggle("Morph icons").getAttribute("aria-checked")).toBe("true");
+    expect(localStorage.getItem("monocode.morphIconsEnabled")).toBe("1");
+    expect(invoke).not.toHaveBeenCalled();
+  });
+});

From 7f86616d6b0b33c78037d9d9257a18a7f893d1d6 Mon Sep 17 00:00:00 2001
From: yanhenrique-dev <yanhenrique-dev@users.noreply.github.com>
Date: Wed, 30 Sep 2026 01:41:28 -0300
Subject: [PATCH 3/3] fix(experimental): a morph icons write that did not
 persist is not announced

CodeRabbit #289, both findings.

- writeFlag already returns whether the write landed and
  saveMorphIconsEnabled ignored it, so a refused write still published
  the change: listeners got a value loadMorphIconsEnabled does not
  confirm, and the preference reverted on the next boot. The setter now
  returns false and stays quiet on failure, following saveAccentColor,
  which already does exactly this. The Experimental page moves its
  toggle only when the write returned true, so the switch cannot show a
  state the next boot will not read. New test fails without the guard,
  and saveMorphIconsEnabled joined the existing 'stays silent when
  persistence fails' case.

- The 'swaps the endpoint when showAlt flips while on' test rendered once
  with showAlt=false and stopped, so it passed on a component that read
  showAlt at mount and ignored it afterwards -- the same shape as
  picking the right endpoint only once. It now re-renders on the same
  root with showAlt=true and expects the other glyph.
---
 src/chrome/MorphIcon.test.ts                  | 33 +++++++++++--------
 src/lib/appearance.test.ts                    | 24 ++++++++++++++
 src/lib/appearance.ts                         |  9 +++--
 .../settings/pages/ExperimentalPage.tsx       |  5 +--
 4 files changed, 53 insertions(+), 18 deletions(-)

diff --git a/src/chrome/MorphIcon.test.ts b/src/chrome/MorphIcon.test.ts
index acf3f4b0..d6e7846e 100644
--- a/src/chrome/MorphIcon.test.ts
+++ b/src/chrome/MorphIcon.test.ts
@@ -121,21 +121,26 @@ describe("MorphIcon", () => {
 
   it("swaps the endpoint when showAlt flips while on", async () => {
     seedFlag("1");
+    const props = {
+      icon: SquareGlyph,
+      altIcon: CopyGlyph,
+      className: "size-3",
+      strokeWidth: 1.75,
+    };
+    const firstD = () =>
+      container.querySelector("svg[data-mock-morph]")?.getAttribute("data-first-d");
+
     await act(async () => {
-      root.render(
-        createElement(MorphIcon, {
-          icon: SquareGlyph,
-          altIcon: CopyGlyph,
-          showAlt: false,
-          className: "size-3",
-          strokeWidth: 1.75,
-        }),
-      );
+      root.render(createElement(MorphIcon, { ...props, showAlt: false }));
+    });
+    expect(firstD()).toBe(SquareGlyph[0][1].d);
+
+    // Re-rendered on the same root, same instance. Without this the test passes
+    // on a component that read `showAlt` once and ignored it afterwards, which
+    // is the same shape as picking the right endpoint only at mount.
+    await act(async () => {
+      root.render(createElement(MorphIcon, { ...props, showAlt: true }));
     });
-    expect(
-      container
-        .querySelector("svg[data-mock-morph]")
-        ?.getAttribute("data-first-d"),
-    ).toBe(SquareGlyph[0][1].d);
+    expect(firstD()).toBe(CopyGlyph[0][1].d);
   });
 });
diff --git a/src/lib/appearance.test.ts b/src/lib/appearance.test.ts
index 56757e7f..c0a1130f 100644
--- a/src/lib/appearance.test.ts
+++ b/src/lib/appearance.test.ts
@@ -45,6 +45,7 @@ import {
   loadMorphIconsEnabled,
   saveMorphIconsEnabled,
   MORPH_ICONS_DEFAULT,
+  MORPH_ICONS_CHANGE_EVENT,
   saveBodyGlass,
   subscribeAppearance,
   APPEARANCE_CHANGE_EVENT,
@@ -516,10 +517,33 @@ describe("appearance change event", () => {
     saveThemePreference("dark");
     saveBodyGlass(false);
     saveChatBackgroundScope("empty");
+    saveMorphIconsEnabled(true);
     stop();
     expect(count).toBe(0);
   });
 
+  it("reports a morph icons write that did not persist", () => {
+    mockWindowEvents();
+    const storage = globalThis.localStorage;
+    const setItem = vi.spyOn(storage, "setItem").mockImplementation(() => {
+      throw new Error("denied");
+    });
+    let announced = 0;
+    window.addEventListener(MORPH_ICONS_CHANGE_EVENT, () => {
+      announced += 1;
+    });
+
+    // The caller uses this to leave the toggle where it was, and a `true` here
+    // would tell it the preference stuck when it did not.
+    expect(saveMorphIconsEnabled(true)).toBe(false);
+    expect(announced).toBe(0);
+    expect(loadMorphIconsEnabled()).toBe(MORPH_ICONS_DEFAULT);
+
+    setItem.mockRestore();
+    expect(saveMorphIconsEnabled(true)).toBe(true);
+    expect(announced).toBe(1);
+  });
+
   it("exposes the documented event name", () => {
     expect(APPEARANCE_CHANGE_EVENT).toBe("monocode:appearance-change");
   });
diff --git a/src/lib/appearance.ts b/src/lib/appearance.ts
index 452d247e..ecef362e 100644
--- a/src/lib/appearance.ts
+++ b/src/lib/appearance.ts
@@ -1046,11 +1046,16 @@ export function loadMorphIconsEnabled(): boolean {
 }
 
 export function saveMorphIconsEnabled(value: boolean) {
-  writeFlag(MORPH_ICONS_KEY, value);
-  if (typeof window === "undefined") return;
+  // Same rule as `saveAccentColor`: a write that did not persist must not be
+  // announced, or the listeners get a change `loadMorphIconsEnabled` does not
+  // confirm, and the preference reverts on the next boot. The caller keeps the
+  // previous value when this returns false.
+  if (!writeFlag(MORPH_ICONS_KEY, value)) return false;
+  if (typeof window === "undefined") return true;
   window.dispatchEvent(
     new CustomEvent<boolean>(MORPH_ICONS_CHANGE_EVENT, {
       detail: value,
     }),
   );
+  return true;
 }
diff --git a/src/surfaces/settings/pages/ExperimentalPage.tsx b/src/surfaces/settings/pages/ExperimentalPage.tsx
index e880ca10..a6687ca2 100644
--- a/src/surfaces/settings/pages/ExperimentalPage.tsx
+++ b/src/surfaces/settings/pages/ExperimentalPage.tsx
@@ -55,8 +55,9 @@ export function ExperimentalPage() {
     loadMorphIconsEnabled,
   );
   const onMorphIconsEnabled = useCallback((next: boolean) => {
-    saveMorphIconsEnabled(next);
-    setMorphIconsEnabled(next);
+    // The toggle only moves when the write landed, so the switch cannot show a
+    // state the next boot will not read back.
+    if (saveMorphIconsEnabled(next)) setMorphIconsEnabled(next);
   }, []);
 
   const [nextStepsEnabled, setNextStepsEnabled] =