@duro-app/cli 4.3.0 → 4.5.0

package/README.md

@@ -130,12 +130,14 @@ hand-roll widgets the DS ships.
 ```
 
 Wire `--check` into the repo's lint or CI job to catch a stale hook after a
-CLI upgrade. The generated script pins `@duro-app/cli@^3.4.0` — a floating
+CLI upgrade. The generated script pins `@duro-app/cli@^4.4.0` — a floating
 pin, so patch releases never read as drift, but a **floor**: a repo whose
-script still pins `^1.2.0` never resolves a 2.x or 3.x payload and never sees
-what the session-start injection gained since. After a major, re-run
-`hook install` in every consumer and delete `.claude/.duro-session.cache*`
-(the payload is cached seven days).
+script still pins `^3.4.0` never resolves a 4.x payload and never sees what
+the session-start injection gained since. The release refuses a tag whose
+major differs from that floor (`scripts/check-pin-major.mjs`). After a major,
+re-run `hook install` (and `skill install`) in every consumer: the cache
+records the floor it was fetched with, so the next session refetches it on its
+own, and a failed refetch says so on stderr.
 
 ### Plan-mode nudge
 
@@ -187,7 +189,7 @@ wires both:
 
 ```
 # stage     name         scope                                                                                                          severity  command
-pre-commit  duro-doctor  *.css,package.json,root.tsx,main.tsx,vite.config.ts,vitest.config.ts,postcss.config.js,postcss.config.mjs,babel.config.js  block     npx -y @duro-app/cli@^3.4.0 doctor
+pre-commit  duro-doctor  *.css,package.json,root.tsx,main.tsx,vite.config.ts,vitest.config.ts,postcss.config.js,postcss.config.mjs,babel.config.js  block     npx -y @duro-app/cli@^4.4.0 doctor
 ```
 
 ## Mockups that speak the design system

package/dist/hook-script.d.ts

@@ -32,9 +32,18 @@ export declare const HOOK_COMMAND = "sh .claude/hooks/duro-catalog.sh";
  * sees what the payload gained (1.2.0 pinned every repo out of 2.x).
  * 3.0.0: the SCREENS section and the /duro-mockup pointer.
  * 3.4.0: duro doctor --session.
+ * 4.4.0: the first CLI whose payload matches @duro-app/ui 4 — a ^3 floor
+ *        never reaches 4.x, so 4.x consumers were served 3.x docs. The
+ *        release refuses a tag whose major differs from this floor's
+ *        (scripts/check-pin-major.mjs).
  */
-export declare const HOOK_MIN_CLI = "3.4.0";
-export declare const HOOK_SCRIPT = "#!/bin/sh\n# Duro design-system session bootstrap \u2014 GENERATED by `duro hook install`.\n# Regenerate: npx -y @duro-app/cli hook install   (--check verifies it in CI)\n#\n# Injects the consult-first preamble plus the component catalog into agent\n# context at SessionStart, so \"check the design system before building UI\" is\n# ambient context instead of a step an agent has to remember. Then runs\n# `duro doctor`, which says nothing unless this repo's build wiring flattens\n# the components' styles.\n#\n# Do not hand-edit. Repo-specific caveats go in\n# .claude/duro-hook.local.md \u2014 appended below, and left alone by regeneration.\ncache=\".claude/.duro-session.cache\"\nnotes=\".claude/duro-hook.local.md\"\ndoctor=\".claude/.duro-session.cache.doctor\"\n\n# npx resolution dominates session start; the catalog only changes on upgrade.\nif [ ! -s \"$cache\" ] || [ -n \"$(find \"$cache\" -mtime +7 2>/dev/null)\" ]; then\n  if npx -y @duro-app/cli@^3.4.0 hook session-start >\"$cache.tmp\" 2>/dev/null; then\n    mv \"$cache.tmp\" \"$cache\"\n  else\n    rm -f \"$cache.tmp\"\n  fi\nfi\n\n# Offline with no cache yet: stay silent rather than fail the session.\nif [ -s \"$cache\" ]; then\n  cat \"$cache\"\n  if [ -s \"$notes\" ]; then\n    echo\n    cat \"$notes\"\n  fi\nfi\n\n# duro doctor reads build config, entries and stylesheets. Re-run it when one\n# of those changes rather than on a timer, so an edit shows up next session\n# and a healthy repo only pays for npx after touching its config.\nkey=$(find . -maxdepth 4 \\( -name node_modules -o -name .git -o -name dist -o -name build \\) -prune -o \\\n  -type f \\( -name package.json -o -name pnpm-workspace.yaml -o -name '*.css' -o -name 'vite*' \\\n  -o -name 'babel*' -o -name '.babelrc*' -o -name '*.babel.*' -o -name 'postcss*' \\\n  -o -name 'root.tsx' -o -name 'main.tsx' -o -name 'index.tsx' \\) -exec cksum {} + 2>/dev/null |\n  sort | cksum)\nif [ \"$key\" != \"$(cat \"$doctor.key\" 2>/dev/null)\" ]; then\n  if npx -y @duro-app/cli@^3.4.0 doctor --session >\"$doctor.tmp\" 2>/dev/null; then\n    mv \"$doctor.tmp\" \"$doctor\"\n    echo \"$key\" >\"$doctor.key\"\n  else\n    rm -f \"$doctor.tmp\"\n  fi\nfi\nif [ -s \"$doctor\" ]; then\n  echo\n  cat \"$doctor\"\nfi\n";
+export declare const HOOK_MIN_CLI = "4.4.0";
+/**
+ * First line of the catalog cache: the floor it was fetched with. A cache
+ * from another floor is refetched, and this line is never printed.
+ */
+export declare const HOOK_PIN_LINE = "#duro-hook-pin 4.4.0";
+export declare const HOOK_SCRIPT = "#!/bin/sh\n# Duro design-system session bootstrap \u2014 GENERATED by `duro hook install`.\n# Regenerate: npx -y @duro-app/cli hook install   (--check verifies it in CI)\n#\n# Injects the consult-first preamble plus the component catalog into agent\n# context at SessionStart, so \"check the design system before building UI\" is\n# ambient context instead of a step an agent has to remember. Then runs\n# `duro doctor`, which says nothing unless this repo's build wiring flattens\n# the components' styles.\n#\n# Do not hand-edit. Repo-specific caveats go in\n# .claude/duro-hook.local.md \u2014 appended below, and left alone by regeneration.\ncache=\".claude/.duro-session.cache\"\nnotes=\".claude/duro-hook.local.md\"\ndoctor=\".claude/.duro-session.cache.doctor\"\npin=\"#duro-hook-pin 4.4.0\"\n\n# npx resolution dominates session start; the catalog only changes on upgrade.\n# Refetch when it is missing, a week old, fetched with another floor (its\n# first line), or older than this script (a regenerate).\nif [ ! -s \"$cache\" ] || [ \"$(head -n 1 \"$cache\" 2>/dev/null)\" != \"$pin\" ] ||\n  [ -n \"$(find \"$cache\" -mtime +7 2>/dev/null)\" ] || [ \".claude/hooks/duro-catalog.sh\" -nt \"$cache\" ]; then\n  # The pin is written with the payload, so a failed fetch (or one that\n  # printed nothing) leaves the old cache as it was and never a pin-only file.\n  if { echo \"$pin\"; npx -y @duro-app/cli@^4.4.0 hook session-start; } >\"$cache.tmp\" 2>/dev/null &&\n    [ -n \"$(tail -n +2 \"$cache.tmp\")\" ]; then\n    mv \"$cache.tmp\" \"$cache\"\n  else\n    rm -f \"$cache.tmp\"\n    if [ -s \"$cache\" ] && [ \"$(head -n 1 \"$cache\")\" != \"$pin\" ]; then\n      echo \"duro: the catalog below is from an older CLI and could not be refreshed; run: npx -y @duro-app/cli@^4.4.0 hook install\" >&2\n    fi\n  fi\nfi\n\n# Offline with no cache yet: stay silent rather than fail the session.\nif [ -s \"$cache\" ]; then\n  # The pin line is bookkeeping, not catalog: skip it, and only it.\n  case \"$(head -n 1 \"$cache\")\" in\n    '#duro-hook-pin '*) tail -n +2 \"$cache\" ;;\n    *) cat \"$cache\" ;;\n  esac\n  if [ -s \"$notes\" ]; then\n    echo\n    cat \"$notes\"\n  fi\nfi\n\n# duro doctor reads build config, entries and stylesheets. Re-run it when one\n# of those changes rather than on a timer, so an edit shows up next session\n# and a healthy repo only pays for npx after touching its config.\nkey=$(find . -maxdepth 4 \\( -name node_modules -o -name .git -o -name dist -o -name build \\) -prune -o \\\n  -type f \\( -name package.json -o -name pnpm-workspace.yaml -o -name '*.css' -o -name 'vite*' \\\n  -o -name 'babel*' -o -name '.babelrc*' -o -name '*.babel.*' -o -name 'postcss*' \\\n  -o -name 'root.tsx' -o -name 'main.tsx' -o -name 'index.tsx' \\) -exec cksum {} + 2>/dev/null |\n  sort | cksum)\n# The floor is part of the key: a new floor reruns the doctor.\nkey=\"4.4.0 $key\"\nif [ \"$key\" != \"$(cat \"$doctor.key\" 2>/dev/null)\" ]; then\n  if npx -y @duro-app/cli@^4.4.0 doctor --session >\"$doctor.tmp\" 2>/dev/null; then\n    mv \"$doctor.tmp\" \"$doctor\"\n    echo \"$key\" >\"$doctor.key\"\n  else\n    rm -f \"$doctor.tmp\"\n  fi\nfi\nif [ -s \"$doctor\" ]; then\n  echo\n  cat \"$doctor\"\nfi\n";
 /**
  * The UserPromptSubmit hook: a plan-mode nudge toward fresh mockup
  * directions (fleet decision `handoff.fresh-directions-trigger`), so a plan

package/dist/hook-script.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hook-script.d.ts","sourceRoot":"","sources":["../src/hook-script.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,yCAAyC;AACzC,eAAO,MAAM,gBAAgB,kCAAkC,CAAA;AAC/D,eAAO,MAAM,kBAAkB,0BAA0B,CAAA;AACzD,eAAO,MAAM,eAAe,gCAAgC,CAAA;AAC5D;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,uCAA8B,CAAA;AACjE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,iCAAwB,CAAA;AACtD,gFAAgF;AAChF,eAAO,MAAM,eAAe,+BAA+B,CAAA;AAE3D,mEAAmE;AACnE,eAAO,MAAM,YAAY,qCAA2B,CAAA;AAEpD;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,UAAU,CAAA;AAEnC,eAAO,MAAM,WAAW,qtEAsDvB,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,+BAA+B,CAAA;AAEjE,uFAAuF;AACvF,eAAO,MAAM,iBAAiB,kCAAgC,CAAA;AAE9D,uEAAuE;AACvE,eAAO,MAAM,UAAU,ieAKtB,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,2oCAiB5B,CAAA;AAED,eAAO,MAAM,eAAe,kFAA0E,CAAA"}
+{"version":3,"file":"hook-script.d.ts","sourceRoot":"","sources":["../src/hook-script.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,yCAAyC;AACzC,eAAO,MAAM,gBAAgB,kCAAkC,CAAA;AAC/D,eAAO,MAAM,kBAAkB,0BAA0B,CAAA;AACzD,eAAO,MAAM,eAAe,gCAAgC,CAAA;AAC5D;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,uCAA8B,CAAA;AACjE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,iCAAwB,CAAA;AACtD,gFAAgF;AAChF,eAAO,MAAM,eAAe,+BAA+B,CAAA;AAE3D,mEAAmE;AACnE,eAAO,MAAM,YAAY,qCAA2B,CAAA;AAEpD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,UAAU,CAAA;AAEnC;;;GAGG;AACH,eAAO,MAAM,aAAa,yBAAmC,CAAA;AAE7D,eAAO,MAAM,WAAW,+qGAsEvB,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,+BAA+B,CAAA;AAEjE,uFAAuF;AACvF,eAAO,MAAM,iBAAiB,kCAAgC,CAAA;AAE9D,uEAAuE;AACvE,eAAO,MAAM,UAAU,ieAKtB,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,2oCAiB5B,CAAA;AAED,eAAO,MAAM,eAAe,kFAA0E,CAAA"}

package/dist/hook-script.js

@@ -32,8 +32,17 @@ export const HOOK_COMMAND = `sh ${HOOK_SCRIPT_PATH}`;
  * sees what the payload gained (1.2.0 pinned every repo out of 2.x).
  * 3.0.0: the SCREENS section and the /duro-mockup pointer.
  * 3.4.0: duro doctor --session.
+ * 4.4.0: the first CLI whose payload matches @duro-app/ui 4 — a ^3 floor
+ *        never reaches 4.x, so 4.x consumers were served 3.x docs. The
+ *        release refuses a tag whose major differs from this floor's
+ *        (scripts/check-pin-major.mjs).
  */
-export const HOOK_MIN_CLI = '3.4.0';
+export const HOOK_MIN_CLI = '4.4.0';
+/**
+ * First line of the catalog cache: the floor it was fetched with. A cache
+ * from another floor is refetched, and this line is never printed.
+ */
+export const HOOK_PIN_LINE = `#duro-hook-pin ${HOOK_MIN_CLI}`;
 export const HOOK_SCRIPT = `#!/bin/sh
 # Duro design-system session bootstrap — GENERATED by \`duro hook install\`.
 # Regenerate: npx -y @duro-app/cli hook install   (--check verifies it in CI)
@@ -49,19 +58,33 @@ export const HOOK_SCRIPT = `#!/bin/sh
 cache="${HOOK_CACHE_PATH}"
 notes="${HOOK_NOTES_PATH}"
 doctor="${HOOK_DOCTOR_CACHE_PATH}"
+pin="${HOOK_PIN_LINE}"
 
 # npx resolution dominates session start; the catalog only changes on upgrade.
-if [ ! -s "$cache" ] || [ -n "$(find "$cache" -mtime +7 2>/dev/null)" ]; then
-  if npx -y @duro-app/cli@^${HOOK_MIN_CLI} hook session-start >"$cache.tmp" 2>/dev/null; then
+# Refetch when it is missing, a week old, fetched with another floor (its
+# first line), or older than this script (a regenerate).
+if [ ! -s "$cache" ] || [ "$(head -n 1 "$cache" 2>/dev/null)" != "$pin" ] ||
+  [ -n "$(find "$cache" -mtime +7 2>/dev/null)" ] || [ "${HOOK_SCRIPT_PATH}" -nt "$cache" ]; then
+  # The pin is written with the payload, so a failed fetch (or one that
+  # printed nothing) leaves the old cache as it was and never a pin-only file.
+  if { echo "$pin"; npx -y @duro-app/cli@^${HOOK_MIN_CLI} hook session-start; } >"$cache.tmp" 2>/dev/null &&
+    [ -n "$(tail -n +2 "$cache.tmp")" ]; then
     mv "$cache.tmp" "$cache"
   else
     rm -f "$cache.tmp"
+    if [ -s "$cache" ] && [ "$(head -n 1 "$cache")" != "$pin" ]; then
+      echo "duro: the catalog below is from an older CLI and could not be refreshed; run: npx -y @duro-app/cli@^${HOOK_MIN_CLI} hook install" >&2
+    fi
   fi
 fi
 
 # Offline with no cache yet: stay silent rather than fail the session.
 if [ -s "$cache" ]; then
-  cat "$cache"
+  # The pin line is bookkeeping, not catalog: skip it, and only it.
+  case "$(head -n 1 "$cache")" in
+    '#duro-hook-pin '*) tail -n +2 "$cache" ;;
+    *) cat "$cache" ;;
+  esac
   if [ -s "$notes" ]; then
     echo
     cat "$notes"
@@ -76,6 +99,8 @@ key=$(find . -maxdepth 4 \\( -name node_modules -o -name .git -o -name dist -o -
   -o -name 'babel*' -o -name '.babelrc*' -o -name '*.babel.*' -o -name 'postcss*' \\
   -o -name 'root.tsx' -o -name 'main.tsx' -o -name 'index.tsx' \\) -exec cksum {} + 2>/dev/null |
   sort | cksum)
+# The floor is part of the key: a new floor reruns the doctor.
+key="${HOOK_MIN_CLI} $key"
 if [ "$key" != "$(cat "$doctor.key" 2>/dev/null)" ]; then
   if npx -y @duro-app/cli@^${HOOK_MIN_CLI} doctor --session >"$doctor.tmp" 2>/dev/null; then
     mv "$doctor.tmp" "$doctor"

package/dist/hook-script.js.map

@@ -1 +1 @@
-{"version":3,"file":"hook-script.js","sourceRoot":"","sources":["../src/hook-script.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,yCAAyC;AACzC,MAAM,CAAC,MAAM,gBAAgB,GAAG,+BAA+B,CAAA;AAC/D,MAAM,CAAC,MAAM,kBAAkB,GAAG,uBAAuB,CAAA;AACzD,MAAM,CAAC,MAAM,eAAe,GAAG,6BAA6B,CAAA;AAC5D;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,eAAe,SAAS,CAAA;AACjE;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,eAAe,GAAG,CAAA;AACtD,gFAAgF;AAChF,MAAM,CAAC,MAAM,eAAe,GAAG,4BAA4B,CAAA;AAE3D,mEAAmE;AACnE,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,gBAAgB,EAAE,CAAA;AAEpD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,OAAO,CAAA;AAEnC,MAAM,CAAC,MAAM,WAAW,GAAG;;;;;;;;;;;IAWvB,eAAe;SACV,eAAe;SACf,eAAe;UACd,sBAAsB;;;;6BAIH,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;6BAyBZ,YAAY;;;;;;;;;;;CAWxC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,4BAA4B,CAAA;AAEjE,uFAAuF;AACvF,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,qBAAqB,EAAE,CAAA;AAE9D,uEAAuE;AACvE,MAAM,CAAC,MAAM,UAAU,GAAG;;;;;CAKzB,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;EAc9B,UAAU;;;CAGX,CAAA;AAED,MAAM,CAAC,MAAM,eAAe,GAAG,kDAAkD,iBAAiB,IAAI,CAAA"}
+{"version":3,"file":"hook-script.js","sourceRoot":"","sources":["../src/hook-script.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,yCAAyC;AACzC,MAAM,CAAC,MAAM,gBAAgB,GAAG,+BAA+B,CAAA;AAC/D,MAAM,CAAC,MAAM,kBAAkB,GAAG,uBAAuB,CAAA;AACzD,MAAM,CAAC,MAAM,eAAe,GAAG,6BAA6B,CAAA;AAC5D;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,eAAe,SAAS,CAAA;AACjE;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,eAAe,GAAG,CAAA;AACtD,gFAAgF;AAChF,MAAM,CAAC,MAAM,eAAe,GAAG,4BAA4B,CAAA;AAE3D,mEAAmE;AACnE,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,gBAAgB,EAAE,CAAA;AAEpD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,OAAO,CAAA;AAEnC;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,kBAAkB,YAAY,EAAE,CAAA;AAE7D,MAAM,CAAC,MAAM,WAAW,GAAG;;;;;;;;;;;IAWvB,eAAe;SACV,eAAe;SACf,eAAe;UACd,sBAAsB;OACzB,aAAa;;;;;;0DAMsC,gBAAgB;;;4CAG9B,YAAY;;;;;;kHAM0D,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BvH,YAAY;;6BAEU,YAAY;;;;;;;;;;;CAWxC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,4BAA4B,CAAA;AAEjE,uFAAuF;AACvF,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,qBAAqB,EAAE,CAAA;AAE9D,uEAAuE;AACvE,MAAM,CAAC,MAAM,UAAU,GAAG;;;;;CAKzB,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;EAc9B,UAAU;;;CAGX,CAAA;AAED,MAAM,CAAC,MAAM,eAAe,GAAG,kDAAkD,iBAAiB,IAAI,CAAA"}

package/dist/skill-template.d.ts

@@ -14,9 +14,11 @@ export declare const SKILL_PATH = ".claude/skills/duro-mockup/SKILL.md";
 /** Repo-specific caveats, read by the skill and never touched by install. */
 export declare const SKILL_NOTES_PATH = ".claude/duro-mockup.local.md";
 /**
- * Floor for the npx pin inside the skill. `duro mockup` landed in 3.0.0. A
- * floating pin keeps patch releases from showing up as --check drift.
+ * Floor for the npx pin inside the skill. `duro mockup` landed in 3.0.0; it
+ * moves with the hook's floor to the release's own major (4.4.0), so a 4.x
+ * consumer runs a 4.x CLI. A floating pin keeps patch releases from showing
+ * up as --check drift.
  */
-export declare const SKILL_MIN_CLI = "3.0.0";
-export declare const SKILL = "---\nname: duro-mockup\ndescription: Take a new screen from mockup directions to an implemented, verified PR without leaving the Duro design system. Use whenever the user asks for a screen, a page, a UI proposal, mockups, or \"show me options\" in a repo that consumes @duro-app/ui \u2014 and when planning (plan mode) a new screen or a material layout, hierarchy or interaction change there.\n---\n\n# duro-mockup\n\nGENERATED by `duro skill install` \u2014 do not hand-edit. Regenerate:\n`npx -y @duro-app/cli@^3.0.0 skill install` (`--check` verifies it in CI). Repo-specific notes\nlive in `.claude/duro-mockup.local.md`; read it if it exists.\n\nStanding rule (fleet decision `ui.mockup-handoff`): a mockup is written in\nthe design system's own vocabulary, and the direction the user picks is a\ncontract. What binds: layout, hierarchy, states, the `data-duro` component\nmap and the token names. What does not bind: the artboard's pixel geometry.\n\n**This overrides the `design` skill's step 0.** That skill says to lift\nresolved values from the real stylesheets. Here you never write a resolved\nvalue: every colour, spacing, radius, font, shadow and duration is a\n`var(--duro-*)` from the seeded token block, and every element a person can\nact on carries `data-duro=\"<Component>\"`. The rest of the `design` skill\n(artboard shape, `seed-canvas.mjs`, the canvas Artifact) still applies.\n\n## Args\n\n- `propose <screen>` \u2014 seed 2\u20134 direction artboards, check them, publish the canvas.\n- `implement <screen> <direction>` \u2014 build the picked direction from its component map.\n- `prove <route>` \u2014 screenshot the built route and assemble the PR section.\n- no args \u2014 infer the stage from what exists under `docs/mockups/<screen>/`.\n\n## propose\n\n```bash\nnpx -y @duro-app/cli@^3.0.0 mockup seed --out docs/mockups/<screen> --name Main          # direction A\nnpx -y @duro-app/cli@^3.0.0 mockup seed --out docs/mockups/<screen> --name <Direction>   # B, C, \u2026\n```\n\n- `<screen>` is kebab-case (`approval-gates`). Artboards are committed with\n  the PR \u2014 never leave them in a scratch directory; a session scratchpad is\n  garbage-collected and the canvas URL would be the only surviving artefact.\n- Author each artboard inside the seeded `<style>` and root div. Colours,\n  spacing, radii, type, shadows and motion come only from the token block;\n  widths, heights and positions are yours. Every button, row, chip, tab,\n  input, link, table and dialog \u2014 whatever element it is drawn as \u2014 carries\n  `data-duro=\"<Component>\"` or `data-duro=\"<Component>.<Part>\"`, using names\n  from `npx -y @duro-app/cli@^3.0.0 list components`. Notes for the implementer go after the\n  name: `data-duro=\"Button variant=primary\"`.\n- Start from a recipe when one fits the screen shape (`npx -y @duro-app/cli@^3.0.0 list recipes`\n  \u2014 admin-detail-page, split-pane, page-with-sidenav, settings-page, \u2026) and\n  say so in the artboard's header comment; a hand-rolled layout needs a reason.\n- Gate before publishing:\n\n```bash\nnpx -y @duro-app/cli@^3.0.0 mockup check docs/mockups/<screen>/*.dc.html\n```\n\n  Exit 1 lists `file:line rule: message`. Fix every finding; do not publish\n  an artboard that fails. Then seed the canvas with the `design` skill's\n  helper (it lives under the current Claude Code version's bundled-skills\n  directory \u2014 locate it, never hardcode the path) and publish the Artifact.\n- Ask the user to pick a direction. Record the answer as\n  `<canvas URL> \u00B7 direction <X>` \u2014 it goes in the PR.\n- If the user edits an artboard in the canvas editor, its property panel\n  writes literals back over `var()` by design. Re-extract and run\n  `mockup check` again, but treat those findings as advisory: the authored\n  file in `docs/mockups/` is the contract, the canvas is the review surface.\n\n## implement\n\n- Read the picked artboard. Its `data-duro` attributes ARE the component\n  list: for each one, `npx -y @duro-app/cli@^3.0.0 <Component>` (or the `duro_ds_lookup` MCP\n  tool) gives props and usage. Do not substitute a hand-rolled element for a\n  named component; if a named component does not fit, say so and propose the\n  design-system change rather than working around it.\n- Tokens map one to one: `var(--duro-spacing-md)` is `spacing.md` from\n  `@duro-app/tokens/tokens/spacing.css`, `--duro-color-bg-card` is\n  `colors.bgCard`, `--duro-radius-sm` is `radii.sm`, `--duro-typography-*`\n  and `--duro-type-scale-*` are `typography`/`typeScale`, `--duro-shadow-*`\n  is `shadows`, `--duro-duration-*`/`--duro-easing-*` are `duration`/`easing`.\n  A media query on `768px` is `breakpoints.md` from\n  `@duro-app/tokens/tokens/breakpoints.css`. The lint config refuses the raw\n  value, so write the token the first time.\n- Layout comes from a recipe before a grid: `npx -y @duro-app/cli@^3.0.0 <recipe> --source-only`.\n- Geometry in the artboard is a sketch. Match its hierarchy and states, not\n  its pixel widths.\n\n## prove\n\n- Run the app, load the route in a real browser (Chrome MCP), and take a\n  screenshot at the artboard's width (1120px) in the artboard's theme.\n- The PR body carries, under `## Mockup`: the canvas URL and direction, the\n  path `docs/mockups/<screen>/`, and the artboard next to the live screenshot.\n  A PR that touches no screen writes `Mockup: none` instead. CI checks for\n  one or the other.\n- If the screenshot and the artboard disagree on hierarchy or states, that is\n  a finding to fix, not a caption to write.\n";
+export declare const SKILL_MIN_CLI = "4.4.0";
+export declare const SKILL = "---\nname: duro-mockup\ndescription: Take a new screen from mockup directions to an implemented, verified PR without leaving the Duro design system. Use whenever the user asks for a screen, a page, a UI proposal, mockups, or \"show me options\" in a repo that consumes @duro-app/ui \u2014 and when planning (plan mode) a new screen or a material layout, hierarchy or interaction change there.\n---\n\n# duro-mockup\n\nGENERATED by `duro skill install` \u2014 do not hand-edit. Regenerate:\n`npx -y @duro-app/cli@^4.4.0 skill install` (`--check` verifies it in CI). Repo-specific notes\nlive in `.claude/duro-mockup.local.md`; read it if it exists.\n\nStanding rule (fleet decision `ui.mockup-handoff`): a mockup is written in\nthe design system's own vocabulary, and the direction the user picks is a\ncontract. What binds: layout, hierarchy, states, the `data-duro` component\nmap and the token names. What does not bind: the artboard's pixel geometry.\n\n**This overrides the `design` skill's step 0.** That skill says to lift\nresolved values from the real stylesheets. Here you never write a resolved\nvalue: every colour, spacing, radius, font, shadow and duration is a\n`var(--duro-*)` from the seeded token block, and every element a person can\nact on carries `data-duro=\"<Component>\"`. The rest of the `design` skill\n(artboard shape, `seed-canvas.mjs`, the canvas Artifact) still applies.\n\n## Args\n\n- `propose <screen>` \u2014 seed 2\u20134 direction artboards, check them, publish the canvas.\n- `implement <screen> <direction>` \u2014 build the picked direction from its component map.\n- `prove <route>` \u2014 screenshot the built route and assemble the PR section.\n- no args \u2014 infer the stage from what exists under `docs/mockups/<screen>/`.\n\n## propose\n\n```bash\nnpx -y @duro-app/cli@^4.4.0 mockup seed --out docs/mockups/<screen> --name Main          # direction A\nnpx -y @duro-app/cli@^4.4.0 mockup seed --out docs/mockups/<screen> --name <Direction>   # B, C, \u2026\n```\n\n- `<screen>` is kebab-case (`approval-gates`). Artboards are committed with\n  the PR \u2014 never leave them in a scratch directory; a session scratchpad is\n  garbage-collected and the canvas URL would be the only surviving artefact.\n- Author each artboard inside the seeded `<style>` and root div. Colours,\n  spacing, radii, type, shadows and motion come only from the token block;\n  widths, heights and positions are yours. Every button, row, chip, tab,\n  input, link, table and dialog \u2014 whatever element it is drawn as \u2014 carries\n  `data-duro=\"<Component>\"` or `data-duro=\"<Component>.<Part>\"`, using names\n  from `npx -y @duro-app/cli@^4.4.0 list components`. Notes for the implementer go after the\n  name: `data-duro=\"Button variant=primary\"`.\n- Start from a recipe when one fits the screen shape (`npx -y @duro-app/cli@^4.4.0 list recipes`\n  \u2014 admin-detail-page, split-pane, page-with-sidenav, settings-page, \u2026) and\n  say so in the artboard's header comment; a hand-rolled layout needs a reason.\n- Gate before publishing:\n\n```bash\nnpx -y @duro-app/cli@^4.4.0 mockup check docs/mockups/<screen>/*.dc.html\n```\n\n  Exit 1 lists `file:line rule: message`. Fix every finding; do not publish\n  an artboard that fails. Then seed the canvas with the `design` skill's\n  helper (it lives under the current Claude Code version's bundled-skills\n  directory \u2014 locate it, never hardcode the path) and publish the Artifact.\n- Ask the user to pick a direction. Record the answer as\n  `<canvas URL> \u00B7 direction <X>` \u2014 it goes in the PR.\n- If the user edits an artboard in the canvas editor, its property panel\n  writes literals back over `var()` by design. Re-extract and run\n  `mockup check` again, but treat those findings as advisory: the authored\n  file in `docs/mockups/` is the contract, the canvas is the review surface.\n\n## implement\n\n- Read the picked artboard. Its `data-duro` attributes ARE the component\n  list: for each one, `npx -y @duro-app/cli@^4.4.0 <Component>` (or the `duro_ds_lookup` MCP\n  tool) gives props and usage. Do not substitute a hand-rolled element for a\n  named component; if a named component does not fit, say so and propose the\n  design-system change rather than working around it.\n- Tokens map one to one: `var(--duro-spacing-md)` is `spacing.md` from\n  `@duro-app/tokens/tokens/spacing.css`, `--duro-color-bg-card` is\n  `colors.bgCard`, `--duro-radius-sm` is `radii.sm`, `--duro-typography-*`\n  and `--duro-type-scale-*` are `typography`/`typeScale`, `--duro-shadow-*`\n  is `shadows`, `--duro-duration-*`/`--duro-easing-*` are `duration`/`easing`.\n  A media query on `768px` is `breakpoints.md` from\n  `@duro-app/tokens/tokens/breakpoints.css`. The lint config refuses the raw\n  value, so write the token the first time.\n- Layout comes from a recipe before a grid: `npx -y @duro-app/cli@^4.4.0 <recipe> --source-only`.\n- Geometry in the artboard is a sketch. Match its hierarchy and states, not\n  its pixel widths.\n\n## prove\n\n- Run the app, load the route in a real browser (Chrome MCP), and take a\n  screenshot at the artboard's width (1120px) in the artboard's theme.\n- The PR body carries, under `## Mockup`: the canvas URL and direction, the\n  path `docs/mockups/<screen>/`, and the artboard next to the live screenshot.\n  A PR that touches no screen writes `Mockup: none` instead. CI checks for\n  one or the other.\n- If the screenshot and the artboard disagree on hierarchy or states, that is\n  a finding to fix, not a caption to write.\n";
 //# sourceMappingURL=skill-template.d.ts.map

package/dist/skill-template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skill-template.d.ts","sourceRoot":"","sources":["../src/skill-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,4CAA4C;AAC5C,eAAO,MAAM,SAAS,+BAA+B,CAAA;AACrD,eAAO,MAAM,UAAU,wCAA0B,CAAA;AACjD,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB,iCAAiC,CAAA;AAE9D;;;GAGG;AACH,eAAO,MAAM,aAAa,UAAU,CAAA;AAIpC,eAAO,MAAM,KAAK,88KAgGjB,CAAA"}
+{"version":3,"file":"skill-template.d.ts","sourceRoot":"","sources":["../src/skill-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,4CAA4C;AAC5C,eAAO,MAAM,SAAS,+BAA+B,CAAA;AACrD,eAAO,MAAM,UAAU,wCAA0B,CAAA;AACjD,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB,iCAAiC,CAAA;AAE9D;;;;;GAKG;AACH,eAAO,MAAM,aAAa,UAAU,CAAA;AAIpC,eAAO,MAAM,KAAK,88KAgGjB,CAAA"}

package/dist/skill-template.js

@@ -14,10 +14,12 @@ export const SKILL_PATH = `${SKILL_DIR}/SKILL.md`;
 /** Repo-specific caveats, read by the skill and never touched by install. */
 export const SKILL_NOTES_PATH = '.claude/duro-mockup.local.md';
 /**
- * Floor for the npx pin inside the skill. `duro mockup` landed in 3.0.0. A
- * floating pin keeps patch releases from showing up as --check drift.
+ * Floor for the npx pin inside the skill. `duro mockup` landed in 3.0.0; it
+ * moves with the hook's floor to the release's own major (4.4.0), so a 4.x
+ * consumer runs a 4.x CLI. A floating pin keeps patch releases from showing
+ * up as --check drift.
  */
-export const SKILL_MIN_CLI = '3.0.0';
+export const SKILL_MIN_CLI = '4.4.0';
 const DURO = `npx -y @duro-app/cli@^${SKILL_MIN_CLI}`;
 export const SKILL = `---
 name: duro-mockup

package/dist/skill-template.js.map

@@ -1 +1 @@
-{"version":3,"file":"skill-template.js","sourceRoot":"","sources":["../src/skill-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,4CAA4C;AAC5C,MAAM,CAAC,MAAM,SAAS,GAAG,4BAA4B,CAAA;AACrD,MAAM,CAAC,MAAM,UAAU,GAAG,GAAG,SAAS,WAAW,CAAA;AACjD,6EAA6E;AAC7E,MAAM,CAAC,MAAM,gBAAgB,GAAG,8BAA8B,CAAA;AAE9D;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,OAAO,CAAA;AAEpC,MAAM,IAAI,GAAG,yBAAyB,aAAa,EAAE,CAAA;AAErD,MAAM,CAAC,MAAM,KAAK,GAAG;;;;;;;;IAQjB,IAAI;YACI,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;EAwB1B,IAAI;EACJ,IAAI;;;;;;;;;;;WAWK,IAAI;;0DAE2C,IAAI;;;;;;EAM5D,IAAI;;;;;;;;;;;;;;;;;0BAiBoB,IAAI;;;;;;;;;;;;gDAYkB,IAAI;;;;;;;;;;;;;;CAcnD,CAAA"}
+{"version":3,"file":"skill-template.js","sourceRoot":"","sources":["../src/skill-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,4CAA4C;AAC5C,MAAM,CAAC,MAAM,SAAS,GAAG,4BAA4B,CAAA;AACrD,MAAM,CAAC,MAAM,UAAU,GAAG,GAAG,SAAS,WAAW,CAAA;AACjD,6EAA6E;AAC7E,MAAM,CAAC,MAAM,gBAAgB,GAAG,8BAA8B,CAAA;AAE9D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,OAAO,CAAA;AAEpC,MAAM,IAAI,GAAG,yBAAyB,aAAa,EAAE,CAAA;AAErD,MAAM,CAAC,MAAM,KAAK,GAAG;;;;;;;;IAQjB,IAAI;YACI,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;EAwB1B,IAAI;EACJ,IAAI;;;;;;;;;;;WAWK,IAAI;;0DAE2C,IAAI;;;;;;EAM5D,IAAI;;;;;;;;;;;;;;;;;0BAiBoB,IAAI;;;;;;;;;;;;gDAYkB,IAAI;;;;;;;;;;;;;;CAcnD,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duro-app/cli",
-  "version": "4.3.0",
+  "version": "4.5.0",
   "type": "module",
   "license": "MIT",
   "description": "Machine-queryable docs for the Duro design system: components, props, recipes, tokens and rules as CLI output, JSON, or an MCP server.",
@@ -45,7 +45,7 @@
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": ">=1.0.0",
-    "@duro-app/ui": "^4.3.0"
+    "@duro-app/ui": "^4.5.0"
   },
   "peerDependenciesMeta": {
     "@duro-app/ui": {
@@ -60,9 +60,9 @@
     "@types/node": "^24.0.0",
     "ts-morph": "^26.0.0",
     "typescript": "^5.7.0",
-    "@duro-app/tokens": "^4.3.0",
-    "@duro-app/eslint-plugin": "^4.3.0",
-    "@duro-app/ui": "^4.3.0"
+    "@duro-app/eslint-plugin": "^4.5.0",
+    "@duro-app/tokens": "^4.5.0",
+    "@duro-app/ui": "^4.5.0"
   },
   "scripts": {
     "registry": "node scripts/build-registry.mjs",

package/registry.json

@@ -11,6 +11,11 @@
             "component": "Table",
             "kind": "composition",
             "relationship": "Common pattern: Table checkboxes + ActionBar for bulk ops"
+          },
+          {
+            "component": "DetailPanel",
+            "kind": "composition",
+            "relationship": "With a DetailPanel docked at the end edge, pass the panel's width as insetInlineEnd"
           }
         ],
         "whenNotToUse": [
@@ -20,7 +25,8 @@
         "whenToUse": [
           "Bulk actions on table selections (delete, revoke, export)",
           "Multi-select workflows where actions apply to all selected items",
-          "Selection-scoped verbs on a canvas/editor surface (set `bottomOffset` to clear any bottom chrome such as zoom controls)"
+          "Selection-scoped verbs on a canvas/editor surface (set `bottomOffset` to clear any bottom chrome such as zoom controls)",
+          "A docked side panel (DetailPanel) is open: pass its width as `insetInlineEnd` so the bar centres beside it, not under it (follows the writing direction: the left edge in right-to-left)"
         ]
       },
       "name": "ActionBar",
@@ -61,6 +67,12 @@
           "required": false,
           "type": "SpacingToken | number"
         },
+        {
+          "description": "Width in px of chrome docked at the window's inline-end edge (right in left-to-right, left in right-to-left), such as an open DetailPanel: the bar centres in what is left and keeps 24px clear of it. 0 or omitted centres on the window.",
+          "name": "insetInlineEnd",
+          "required": false,
+          "type": "number"
+        },
         {
           "description": "Action buttons to display.",
           "name": "children",
@@ -81,6 +93,11 @@
             "component": "Table",
             "kind": "composition",
             "relationship": "Common pattern: Table checkboxes + ActionBar for bulk ops"
+          },
+          {
+            "component": "DetailPanel",
+            "kind": "composition",
+            "relationship": "With a DetailPanel docked at the end edge, pass the panel's width as insetInlineEnd"
           }
         ],
         "whenNotToUse": [
@@ -90,7 +107,8 @@
         "whenToUse": [
           "Bulk actions on table selections (delete, revoke, export)",
           "Multi-select workflows where actions apply to all selected items",
-          "Selection-scoped verbs on a canvas/editor surface (set `bottomOffset` to clear any bottom chrome such as zoom controls)"
+          "Selection-scoped verbs on a canvas/editor surface (set `bottomOffset` to clear any bottom chrome such as zoom controls)",
+          "A docked side panel (DetailPanel) is open: pass its width as `insetInlineEnd` so the bar centres beside it, not under it (follows the writing direction: the left edge in right-to-left)"
         ]
       },
       "name": "ActionBarProvider",
@@ -1041,6 +1059,11 @@
         "description": "Searchable dropdown for selecting a value from a filterable list. Combines a text input with a popup listbox. Compound component — Root is required.",
         "example": "<Combobox.Root name=\"country\" defaultValue=\"us\" initialLabels={{us: 'United States'}}>\n  <Combobox.Input placeholder=\"Search countries…\" />\n  <Combobox.Popup>\n    <Combobox.Item value=\"us\">United States</Combobox.Item>\n    <Combobox.Item value=\"gb\">United Kingdom</Combobox.Item>\n    <Combobox.Item value=\"fr\">France</Combobox.Item>\n    <Combobox.Item value=\"de\">Germany</Combobox.Item>\n    <Combobox.Empty>No countries found</Combobox.Empty>\n  </Combobox.Popup>\n</Combobox.Root>",
         "relatedTo": [
+          {
+            "component": "Popover",
+            "kind": "composition",
+            "relationship": "Inside Popover.Popup a Combobox keeps the popover open while you choose; Escape closes only the list"
+          },
           {
             "component": "Select",
             "kind": "contrast",
@@ -1329,6 +1352,11 @@
         "description": "Non-modal side panel for right-side inspection. Click a table row to show details, click another to update in place. Built on Panel internally. In-flow (flex child), not fixed/modal — content behind remains interactive.",
         "example": "<html.div style={layoutStyles.container}>\n  <html.div style={layoutStyles.main}>\n    <Table.Root columns={3}>...</Table.Root>\n  </html.div>\n  <DetailPanel.Root open={selectedId != null} onOpenChange={handleOpenChange}>\n    <DetailPanel.Content size=\"sm\" label=\"User details\">\n      <DetailPanel.Header>\n        <DetailPanel.Title>{user.name}</DetailPanel.Title>\n        <DetailPanel.Close />\n      </DetailPanel.Header>\n      <DetailPanel.Body>\n        <Stack gap=\"md\">...</Stack>\n      </DetailPanel.Body>\n    </DetailPanel.Content>\n  </DetailPanel.Root>\n</html.div>",
         "relatedTo": [
+          {
+            "component": "ActionBar",
+            "kind": "composition",
+            "relationship": "An ActionBar shown while the panel is open takes the panel's width as insetInlineEnd"
+          },
           {
             "component": "Drawer",
             "kind": "contrast",
@@ -1930,7 +1958,7 @@
             "Portal"
           ]
         },
-        "description": "Modal sliding panel from a screen edge (right, left, or bottom). Slides in with backdrop overlay. Supports swipe-to-dismiss gestures on mobile, backdrop click dismiss, and Escape key. Use for secondary workflows, settings panels, or mobile-friendly detail views.",
+        "description": "Modal sliding panel from a screen edge (right, left, or bottom). Slides in with backdrop overlay. Supports swipe-to-dismiss gestures on mobile, backdrop click dismiss, and Escape key. Swipe yields to an inner Duro ScrollArea: a drag there scrolls it, and dismisses only toward the edge from the scroll start (a native overflow:auto child is not covered — use ScrollArea). Use for secondary workflows, settings panels, or mobile-friendly detail views.",
         "example": "<Drawer.Root anchor=\"right\" open={open} onOpenChange={setOpen}>\n  <Drawer.Trigger>\n    <Button>Open drawer</Button>\n  </Drawer.Trigger>\n  <Drawer.Portal size=\"md\">\n    <Drawer.Header>\n      <Drawer.Title>Settings</Drawer.Title>\n      <Drawer.Close />\n    </Drawer.Header>\n    <Drawer.Body>\n      <Stack gap=\"md\">\n        <Text>Drawer content goes here.</Text>\n      </Stack>\n    </Drawer.Body>\n    <Drawer.Footer>\n      <Button variant=\"secondary\" onClick={() => setOpen(false)}>Done</Button>\n    </Drawer.Footer>\n  </Drawer.Portal>\n</Drawer.Root>",
         "relatedTo": [
           {
@@ -3744,6 +3772,11 @@
             "kind": "contrast",
             "relationship": "Drawer is the modal edge panel for phone width; Popover is anchored and non-modal"
           },
+          {
+            "component": "Select",
+            "kind": "composition",
+            "relationship": "A Select or Combobox inside Popover.Popup keeps the popover open while you choose; a Select backdrop press closes only its list"
+          },
           {
             "component": "Field",
             "kind": "composition",
@@ -3759,7 +3792,8 @@
         ],
         "whenToUse": [
           "A small form or controls tied to one element that stay open while you work in them",
-          "Anchoring to a spot that is not a button (a canvas point, a text selection) with a virtual anchor"
+          "Anchoring to a spot that is not a button (a canvas point, a text selection) with a virtual anchor",
+          "Holding a Select or Combobox: their portalled list counts as inside the popover, so choosing an item keeps it open; Escape closes an open Select, Combobox or Menu before the popover"
         ]
       },
       "name": "Popover",
@@ -3988,7 +4022,7 @@
             "Thumb"
           ]
         },
-        "description": "Custom scrollbar region with draggable thumb. Supports vertical and horizontal scrolling. Compound component — Root is required.",
+        "description": "Custom scrollbar region with draggable thumb. Supports vertical and horizontal scrolling. Compound component — Root is required. Inside a Drawer, a drag in the viewport scrolls it; the drawer only takes a drag toward its edge from the scroll start.",
         "example": "<ScrollArea.Root>\n  <ScrollArea.Viewport maxHeight={300}>\n    <ScrollArea.Content>\n      {/* Long content here */}\n    </ScrollArea.Content>\n  </ScrollArea.Viewport>\n  <ScrollArea.Scrollbar orientation=\"vertical\">\n    <ScrollArea.Thumb orientation=\"vertical\" />\n  </ScrollArea.Scrollbar>\n</ScrollArea.Root>",
         "whenNotToUse": [
           "Simple page-level scrolling — browser scroll is fine",
@@ -4064,6 +4098,19 @@
               "name": "maxHeight",
               "required": false,
               "type": "number | string"
+            },
+            {
+              "description": "Extra styles for the viewport (e.g. a pointer-aware max height).",
+              "name": "style",
+              "required": false,
+              "type": "ComponentProps<typeof html.div>['style']"
+            },
+            {
+              "default": "false",
+              "description": "A roving-focus group owns the keyboard: drop the viewport's own tab stop and region role.",
+              "name": "rovingOwner",
+              "required": false,
+              "type": "boolean"
             }
           ],
           "sourcePath": "packages/ui/src/components/ScrollArea/ScrollArea.tsx"
@@ -4092,6 +4139,11 @@
         "description": "Dropdown select for choosing one value from a list. Compound component — Root is required (throws without it).",
         "example": "<Select.Root name=\"role\" defaultValue=\"viewer\">\n  <Select.Trigger>\n    <Select.Value placeholder=\"Select role\" />\n    <Select.Icon />\n  </Select.Trigger>\n  <Select.Popup>\n    <Select.Item value=\"admin\">Admin</Select.Item>\n    <Select.Item value=\"editor\">Editor</Select.Item>\n    <Select.Item value=\"viewer\">Viewer</Select.Item>\n  </Select.Popup>\n</Select.Root>",
         "relatedTo": [
+          {
+            "component": "Popover",
+            "kind": "composition",
+            "relationship": "Inside Popover.Popup a Select keeps the popover open while you choose; its backdrop press and Escape close only the list"
+          },
           {
             "component": "Menu",
             "kind": "contrast",
@@ -5806,7 +5858,7 @@
       "importPath": "@duro-app/ui",
       "kind": "component",
       "meta": {
-        "description": "Toggle button with pressed/unpressed state. Works standalone or within ToggleGroup for multi/single selection.",
+        "description": "Toggle button with pressed/unpressed state. Works standalone or within ToggleGroup for multi/single selection. Under a coarse pointer (touch) every Toggle is at least 44×44px; in a wrapping ToggleGroup each keeps its own border and a fixed row height.",
         "example": "// Standalone\n<Toggle pressed={isBold} onPressedChange={setIsBold} aria-label=\"Bold\">\n  <Icon name=\"key\" size=\"sm\" />\n</Toggle>\n\n// In a group\n<ToggleGroup value={['grid']} onValueChange={setView} multiple={false}>\n  <Toggle value=\"list\">List</Toggle>\n  <Toggle value=\"grid\">Grid</Toggle>\n</ToggleGroup>",
         "relatedTo": [
           {
@@ -5898,7 +5950,7 @@
       "kind": "component",
       "meta": {
         "description": "Container for Toggle buttons enabling single or multi selection. Provides context to child Toggles.",
-        "example": "<ToggleGroup\n  value={selected}\n  onValueChange={setSelected}\n  multiple={false}\n  orientation=\"horizontal\"\n  size=\"default\"\n>\n  <Toggle value=\"list\">List view</Toggle>\n  <Toggle value=\"grid\">Grid view</Toggle>\n  <Toggle value=\"board\">Board view</Toggle>\n</ToggleGroup>",
+        "example": "<ToggleGroup\n  value={selected}\n  onValueChange={setSelected}\n  multiple={false}\n  orientation=\"horizontal\"\n  size=\"default\"\n>\n  <Toggle value=\"list\">List view</Toggle>\n  <Toggle value=\"grid\">Grid view</Toggle>\n  <Toggle value=\"board\">Board view</Toggle>\n</ToggleGroup>\n\n// Icon choices: wraps onto rows, scrolls past three, one tab stop\n<ToggleGroup wrap maxRows={3} size=\"small\" value={[icon]} onValueChange={(v) => v[0] && setIcon(v[0])} aria-label=\"Icon\">\n  {names.map((name) => (\n    <Toggle key={name} value={name} aria-label={name}>\n      <Icon name={name} size=\"sm\" />\n    </Toggle>\n  ))}\n</ToggleGroup>",
         "relatedTo": [
           {
             "component": "Toggle",
@@ -5913,12 +5965,13 @@
         ],
         "whenNotToUse": [
           "Dropdown selection — use Select",
-          "Many options (5+) — use Select for space efficiency",
+          "Many text options (5+) — use Select for space efficiency; does not apply to icon-only choices, which keep options visible and open no layer",
           "Form checkboxes — use Checkbox group in Fieldset"
         ],
         "whenToUse": [
           "Visible option set where user picks one or more (view mode, filter categories)",
-          "Segmented control pattern"
+          "Segmented control pattern",
+          "A visible grid of icon choices: wrap + maxRows (rows scroll past maxRows, one tab stop with arrow keys, 44px touch targets)"
         ]
       },
       "name": "ToggleGroup",
@@ -5974,6 +6027,19 @@
             "small"
           ]
         },
+        {
+          "default": "false",
+          "description": "Items wrap onto rows, each with its own border (default false). Enables roving focus: one tab stop, arrow keys move between items.",
+          "name": "wrap",
+          "required": false,
+          "type": "boolean"
+        },
+        {
+          "description": "Caps a wrapping group at this many rows (plus half a row, hinting more) and scrolls the rest. Only with `wrap`; ignored without it.",
+          "name": "maxRows",
+          "required": false,
+          "type": "number"
+        },
         {
           "description": "Accessible name when the group is not inside a Field.Root (inside one, the Field.Label names it).",
           "name": "aria-label",