@1agh/maude 0.43.0 → 0.45.0

package/apps/studio/bin/import-asset.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# import-asset.sh — hardened local-file SVG/PDF ingestion. Thin shim over
+# _import-asset.mjs; reached via `maude design import-asset` (DDR-062), never
+# a raw bin path. See _import-asset.mjs + DDR-167 for the full security
+# rationale. Requires bun (not the node/bun fallback fetch-asset.sh uses) —
+# _import-asset.mjs imports the `.ts` SVGO engine module directly, same
+# constraint as svg-optimize.sh.
+#
+# Usage:
+#   import-asset.sh <local-path> --root <repo> [--design-root .design]
+#                   [--kind svg|pdf|raster] [--json]
+#
+# stdout on success = one reference path per line (e.g. /assets/a44d3d60.svg).
+# PDF import is not yet available (DDR-167 addendum) — the verb accepts a
+# .pdf input and fails loud naming why, rather than silently rejecting it as
+# an unknown flag. `raster` (PNG/JPEG, magic-byte sniffed) content-addresses
+# a local image as-is — added for DDR-174/T15's vision-reconstruction source.
+#
+# Exit: 0 ok · 1 not-yet-available/other · 2 usage · 3 sanitize/validation
+#       reject · 4 read/parse error · 5 unsupported media type ·
+#       6 write/containment error.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+case "$1" in
+  --help|-h) sed -n '2,17p' "$0" | sed 's/^# \?//'; exit 0 ;;
+esac
+
+if ! command -v bun >/dev/null 2>&1; then
+  echo "import-asset.sh: bun is required (hard dependency — see plugins/design/dependencies.json)." >&2
+  echo "  Install: curl -fsSL https://bun.sh/install | bash" >&2
+  exit 1
+fi
+
+exec bun run "$SCRIPT_DIR/_import-asset.mjs" "$@"

package/apps/studio/bin/import-brand.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# import-brand.sh — brand-file typed-cue extraction (DDR-173). Thin shim over
+# _import-brand.mjs; reached via `maude design import-brand` (DDR-062), never
+# a raw bin path. Operates ONLY on an already-DDR-167-sanitized SVG asset
+# (as produced by `maude design import-asset`) — never re-reads or
+# re-sanitizes the original brand file (DDR-173 Decision 2: no parallel,
+# ungated read path). Requires bun — _import-brand.mjs imports
+# _import-tokens.mjs's `.mjs` grammar reuse and happy-dom directly.
+#
+# Usage:
+#   import-brand.sh <sanitized-svg-path> --root <repo> [--design-root .design] [--json]
+#
+# stdout on success = the typed payload `{ palette, fonts, logoRef, logoRasterRef }`.
+#
+# Exit: 0 ok · 1 other · 2 usage · 3 validation/hardening reject ·
+#       4 read/parse error · 6 write/containment error.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+case "$1" in
+  --help|-h) sed -n '2,15p' "$0" | sed 's/^# \?//'; exit 0 ;;
+esac
+
+if ! command -v bun >/dev/null 2>&1; then
+  echo "import-brand.sh: bun is required (hard dependency — see plugins/design/dependencies.json)." >&2
+  echo "  Install: curl -fsSL https://bun.sh/install | bash" >&2
+  exit 1
+fi
+
+exec bun run "$SCRIPT_DIR/_import-brand.mjs" "$@"

package/apps/studio/bin/import-tokens.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# import-tokens.sh — token-file import (W3C design-tokens / Style-Dictionary
+# JSON / raw CSS custom properties -> the DS CSS-variable contract). Thin
+# shim over _import-tokens.mjs; reached via `maude design import-tokens`
+# (DDR-062), never a raw bin path. See _import-tokens.mjs + DDR-172 for the
+# full mapping contract + security rationale. Requires bun — _import-tokens.mjs
+# imports the `.ts` palette/paths modules directly, same constraint as
+# import-asset.sh.
+#
+# All args are forwarded quoted ("$@") — never unquoted or eval-expanded
+# (DDR-172 Decision 8 wrapper-hygiene requirement; the charset/shape
+# validation itself happens in _import-tokens.mjs, not here).
+#
+# Usage:
+#   import-tokens.sh <token-file> --root <repo> [--design-root .design]
+#                    [--ds <name> | --new-ds <name>] [--theme <name>]
+#                    [--force-insert] [--json]
+#
+# Exit: 0 ok · 1 other · 2 usage · 3 validation/mapping reject ·
+#       4 read/parse error · 5 unsupported format · 6 write/containment error.
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+case "$1" in
+  --help|-h) sed -n '2,16p' "$0" | sed 's/^# \?//'; exit 0 ;;
+esac
+
+if ! command -v bun >/dev/null 2>&1; then
+  echo "import-tokens.sh: bun is required (hard dependency — see plugins/design/dependencies.json)." >&2
+  echo "  Install: curl -fsSL https://bun.sh/install | bash" >&2
+  exit 1
+fi
+
+exec bun run "$SCRIPT_DIR/_import-tokens.mjs" "$@"

package/apps/studio/bin/photo-bg-remove.sh

@@ -16,6 +16,19 @@
 #
 # Reached via `maude design photo-bg-remove` (never a raw bin path — DDR-062).
 #
+# Security hardening (fix-photo-editor-followup-debt, Stage A): `--asset` is
+# validated against the strict `assets/<sha8>.<ext>` shape (mirrors
+# photo-store.ts's SHA_RE) rather than a loose glob — a permissive check
+# previously let a crafted `--asset` value splice unescaped content into the
+# generated harness `.tsx`. The harness-file write is symlink-safe (write to a
+# freshly O_EXCL-created tmp path, then atomic `mv` into place — `mv`/rename(2)
+# replaces a destination symlink's OWN dirent rather than following it, so even
+# a pre-planted symlink at the harness path can't redirect the write into a
+# real reviewed canvas file). The stdout deliverable is shape-validated before
+# print. `--slug` failure hard-fails instead of downgrading to an unsanitized
+# fallback. Concurrent invocations against the SAME asset serialize via a
+# `mkdir`-based lock (portable — `flock` isn't available on macOS by default).
+#
 # Usage:
 #   photo-bg-remove.sh --asset <assets/<sha8>.<ext>> [--root <repo>]
 #                       [--slug <name>] [--timeout <secs>]
@@ -29,11 +42,16 @@
 # Stderr: progress / diagnostics.
 # Exit:   0 success / 1 missing input, server, or agent-browser / 2 bad args
 #         / 3 drive/navigation failed / 4 the harness itself reported an error
-#         / 5 timed out waiting for the ML pass to finish.
+#         (or produced a malformed result) / 5 timed out waiting for the ML
+#         pass to finish / 6 another run is already in progress for this asset
 
 set -uo pipefail
 
 ASSET="" SLUG="" REPO="" TIMEOUT=150
+# Mirrors photo-store.ts's SHA_RE shape: lowercase hex sha8 (8-64 chars),
+# case-insensitive extension. Shared between --asset validation (Task 1) and
+# the stdout-deliverable validation (Task 3) so the two checks can't drift.
+ASSET_SHAPE_RE='^assets/[0-9a-f]{8,64}\.[a-zA-Z0-9]+$'
 
 while [ $# -gt 0 ]; do
   case "$1" in
@@ -42,7 +60,7 @@ while [ $# -gt 0 ]; do
     --root)    REPO="$2"; shift 2 ;;
     --timeout) TIMEOUT="$2"; shift 2 ;;
     --help|-h)
-      sed -n '2,29p' "$0" | sed 's/^# \?//'
+      sed -n '2,39p' "$0" | sed 's/^# \?//'
       exit 0
       ;;
     *)
@@ -55,14 +73,42 @@ done
 [ -n "$ASSET" ] || { echo "photo-bg-remove.sh: --asset <assets/<sha8>.<ext>> required" >&2; exit 2; }
 # Strip a leading designRoot-relative slash/prefix if the caller passed one.
 ASSET="${ASSET#/}"
-case "$ASSET" in
-  assets/*) : ;;
-  *) echo "photo-bg-remove.sh: --asset must look like assets/<sha8>.<ext>, got '$ASSET'" >&2; exit 2 ;;
-esac
+# Strict shape check (Task 1) — replaces the old `case "$ASSET" in assets/*)`
+# glob, which only checked the PREFIX and let anything after it (quotes,
+# backticks, `../`, JSX-breaking sequences) ride unescaped into the generated
+# harness .tsx below. `[[ =~ ]]` against a character-class regex is the bash
+# equivalent of photo-store.ts's `SHA_RE` hex check — `..`, `/`, quotes, and
+# any non-hex/non-alnum content can never match, so nothing but a clean
+# `assets/<sha8>.<ext>` reference survives validation. Captures the bare sha8
+# for reuse as a filesystem-safe lock key (Task 6).
+if [[ "$ASSET" =~ ^assets/([0-9a-f]{8,64})\.[a-zA-Z0-9]+$ ]]; then
+  ASSET_KEY="${BASH_REMATCH[1]}"
+else
+  echo "photo-bg-remove.sh: --asset must look like assets/<sha8>.<ext> (lowercase hex, 8-64 chars), got '$ASSET'" >&2
+  exit 2
+fi
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 [ -n "$SLUG" ] || SLUG=$(basename "$ASSET" | sed -E 's/\.[^.]+$//')
-SLUG=$(bash "$SCRIPT_DIR/slug.sh" "$SLUG" 2>/dev/null || printf '%s' "$SLUG" | tr '[:upper:]' '[:lower:]')
+# Hard-fail (Task 4) instead of downgrading to a lowercased-but-unstripped
+# fallback on slug.sh failure — a safety subprocess's failure must never
+# silently continue with a less-safe code path. This repo has documented
+# history (DDR-045) of sibling-script resolution breaking specifically in
+# packaged/compiled distributions, so this failure mode is realistic.
+# (SLUG_INPUT is captured separately so a failed substitution — which still
+# assigns its, here empty, stdout to $SLUG — doesn't blank the diagnostic.)
+SLUG_INPUT="$SLUG"
+if ! SLUG="$(bash "$SCRIPT_DIR/slug.sh" "$SLUG_INPUT" 2>/dev/null)"; then
+  echo "photo-bg-remove.sh: slug.sh failed to normalize slug '$SLUG_INPUT' — refusing to fall back to an unsanitized value" >&2
+  exit 1
+fi
+# Assigned this early (not just before the agent-browser open call below) so
+# it's always bound by the time `trap cleanup EXIT` is installed — a security
+# review of this plan found that `cleanup()` unconditionally reads $SESSION,
+# and under `set -u` an exit on one of the harness-write failure paths (before
+# SESSION used to be assigned) would abort mid-cleanup on the unbound
+# variable, skipping the `rmdir "$LOCK_DIR"` below it and leaking the lock.
+SESSION="photo-bgremove-$SLUG-$$"
 
 # ---------- resolve repo + design root + port ----------
 if [ -z "$REPO" ]; then
@@ -97,29 +143,69 @@ if [ -z "${AGENT_BROWSER_EXECUTABLE_PATH:-}" ]; then
   [ -n "$BROWSER_PATH" ] && export AGENT_BROWSER_EXECUTABLE_PATH="$BROWSER_PATH"
 fi
 
-# ---------- generate the harness canvas ----------
+# ---------- per-asset concurrency guard (Task 6) ----------
+# `mkdir` is atomic on every POSIX filesystem and needs no extra binary —
+# `flock` isn't available on macOS by default, so this is the portable choice.
+# Keyed on the asset's sha8 (already validated hex — safe as a path segment),
+# NOT global, so two different assets still run concurrently. Fail-fast rather
+# than queue/wait: a full job queue is out of scope for this backstop, whose
+# only job is refusing to let a runaway loop spawn unbounded concurrent
+# browser+WASM processes against the same asset.
 PHOTO_DIR="$DESIGN_ROOT/_photo"
 mkdir -p "$PHOTO_DIR"
+LOCK_DIR="$PHOTO_DIR/.lock.$ASSET_KEY"
+TMP_HARNESS=""
+if ! mkdir "$LOCK_DIR" 2>/dev/null; then
+  echo "photo-bg-remove.sh: another photo-bg-remove run is already in progress for asset '$ASSET' — refusing to run concurrently against the same asset (lock: ${LOCK_DIR#$REPO/})" >&2
+  exit 6
+fi
+
+cleanup() {
+  "$AB" --session "$SESSION" close >/dev/null 2>&1 || true
+  [ -n "$TMP_HARNESS" ] && rm -f "$TMP_HARNESS" 2>/dev/null
+  rmdir "$LOCK_DIR" 2>/dev/null || true
+}
+trap cleanup EXIT
+
+# ---------- generate the harness canvas (symlink-safe — Task 2) ----------
+# Write to a freshly O_CREAT|O_EXCL-created tmp path in the SAME directory
+# (same filesystem, so the rename below is atomic), then `mv` into place.
+# `mv`/rename(2) replaces the destination NAME, never dereferences it — so
+# even a pre-planted symlink at $HARNESS_TSX gets its dirent swapped out
+# rather than followed, unlike the bare `{ ... } > "$HARNESS_TSX"` truncating
+# redirect this replaces (which WOULD follow a symlink and could splice
+# attacker-controlled JSX into whatever real file it pointed at). `set -C`
+# (noclobber) makes bash open the tmp path with O_EXCL, so a pre-existing tmp
+# path (including a dangling symlink) fails the write instead of following it
+# — the bash equivalent of sync/atomic-write.ts's Node `wx` flag (DDR-054 §2c).
 HARNESS_TSX="$PHOTO_DIR/$SLUG.bgremove.tsx"
-{
-  echo "import { PhotoBgRemoveHarness } from '@maude/canvas-lib';"
-  echo
-  echo "// AUTO-GENERATED by \`maude design photo-bg-remove\` — headless bg-removal proof"
-  echo "// harness. Lives under _photo/ (gitignored); safe to delete + regenerate."
-  echo "export default function PhotoBgRemoveCanvas() {"
-  printf '  return <PhotoBgRemoveHarness source=%s />;\n' "\"$ASSET\""
-  echo "}"
-} > "$HARNESS_TSX"
+TMP_HARNESS="$PHOTO_DIR/.$SLUG.bgremove.tsx.tmp.$$.$RANDOM$RANDOM"
+if ! (
+  set -C
+  {
+    echo "import { PhotoBgRemoveHarness } from '@maude/canvas-lib';"
+    echo
+    echo "// AUTO-GENERATED by \`maude design photo-bg-remove\` — headless bg-removal proof"
+    echo "// harness. Lives under _photo/ (gitignored); safe to delete + regenerate."
+    echo "export default function PhotoBgRemoveCanvas() {"
+    printf '  return <PhotoBgRemoveHarness source=%s />;\n' "\"$ASSET\""
+    echo "}"
+  } > "$TMP_HARNESS"
+); then
+  echo "photo-bg-remove.sh: failed to create harness scratch file (possible pre-existing path at $TMP_HARNESS)" >&2
+  exit 1
+fi
+if ! mv "$TMP_HARNESS" "$HARNESS_TSX"; then
+  echo "photo-bg-remove.sh: atomic rename of harness file failed" >&2
+  exit 1
+fi
+TMP_HARNESS="" # renamed away — nothing left for cleanup() to remove
 echo "→ harness canvas: ${HARNESS_TSX#$REPO/}" >&2
 
 REL="_photo/$SLUG.bgremove.tsx"
 URL="http://localhost:$PORT/_canvas-shell.html?canvas=$REL"
-SESSION="photo-bgremove-$SLUG-$$"
 SEL="[data-photo-bgremove-status]"
 
-cleanup() { "$AB" --session "$SESSION" close >/dev/null 2>&1 || true; }
-trap cleanup EXIT
-
 echo "→ driving $URL (session $SESSION)" >&2
 if ! "$AB" --session "$SESSION" open "$URL" >&2; then
   echo "photo-bg-remove.sh: agent-browser failed to open the harness canvas" >&2
@@ -154,7 +240,19 @@ fi
 
 RESULT="$("$AB" --session "$SESSION" get attr "$SEL" data-photo-bgremove-result 2>/dev/null | tr -d '"')"
 [ -n "$RESULT" ] || { echo "photo-bg-remove.sh: harness reported done but no result asset" >&2; exit 4; }
+# Shape-validate the deliverable (Task 3) before it's ever trusted as far as
+# stdout — the harness runs inside the (untrusted, DDR-054) canvas origin, so
+# a malformed/crafted `data-photo-bgremove-result` value is treated exactly
+# like the empty-result case above rather than printed verbatim.
+if [[ ! "$RESULT" =~ $ASSET_SHAPE_RE ]]; then
+  echo "photo-bg-remove.sh: harness reported a malformed result asset '$RESULT'" >&2
+  exit 4
+fi
 
 echo "→ background removed → $RESULT" >&2
 # Last stdout line = the new matte asset path, for $(maude design photo-bg-remove ...) capture.
 printf '%s\n' "$RESULT"
+
+# Clean up the harness scratch file on the SUCCESS path only (Task 5) — left
+# in place on any error exit above, where it's useful for debugging.
+rm -f "$HARNESS_TSX"

package/apps/studio/bin/transcribe.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# transcribe.sh — feature-ai-media-generation (Phase 2, DDR-164). Local, no-key
+# speech-to-text for automatic subtitles: run whisper.cpp on an audio/video file
+# and emit SRT/VTT through the shared captions.ts reflow. The DEFAULT subtitle
+# path — free, offline, private, word-timestamped — with cloud STT (ElevenLabs
+# Scribe / Groq Whisper) as the fallback when whisper.cpp isn't installed.
+#
+# Reached via `maude design transcribe` (never a raw bin path — DDR-062). No dev
+# server needed; the work is a local whisper.cpp spawn (mirrors probe-footage).
+#
+# Usage:
+#   transcribe.sh --source <assets/x.mp4|file> [--root <repo>]
+#     [--provider whisper|elevenlabs|groq]
+#     [--format srt|vtt|both] [--model <id>] [--whisper <bin>]
+#     [--lang <code>] [--segments]
+#
+# The engine is an EXPLICIT user choice (Task 2.6, DDR-164), never an automatic
+# fallback: --provider wins, else the project's generation.transcription.provider
+# config, else local whisper — and it SAYS which it chose. A chosen cloud engine
+# (elevenlabs / groq) needs the dev server running (the key is resolved
+# server-side) and an assets/<sha8> source; whisper is local, free, no key.
+#
+# whisper.cpp is a SOFT dependency (plugins/design/dependencies.json). A ggml
+# model is required (--model / $MAUDE_WHISPER_MODEL); whisper.cpp ships no default
+# and does not auto-download. See _transcribe.mjs for the download pointer.
+#
+# Stdout (last line): the produced .srt path (for $(...) capture).
+# Exit: 0 ok / 1 dependency-or-input problem / 3 transcription failed.
+
+set -euo pipefail
+
+if ! command -v bun >/dev/null 2>&1; then
+  echo "transcribe.sh: bun is required (hard dependency — see plugins/design/dependencies.json)." >&2
+  echo "  Install: curl -fsSL https://bun.sh/install | bash" >&2
+  exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec bun run "$SCRIPT_DIR/_transcribe.mjs" "$@"

package/apps/studio/canvas-edit.ts

@@ -3406,8 +3406,14 @@ function collectJsxByTag(program: AnyNode, tagName: string): AnyNode[] {
  * `width="430"` and break the numeric prop. Overwrites an existing `{expr}` or
  * `"literal"`, or inserts the attribute after the tag name if missing.
  */
-function writeNumericAttr(s: MagicString, opening: AnyNode, name: string, value: number): void {
-  const num = Math.max(1, Math.round(value));
+function writeNumericAttr(
+  s: MagicString,
+  opening: AnyNode,
+  name: string,
+  value: number,
+  min = 1
+): void {
+  const num = Math.max(min, Math.round(value));
   const attr = findAttribute(opening, name);
   if (attr) {
     const v = attr.value;
@@ -3494,6 +3500,195 @@ export async function resizeArtboard(
   });
 }
 
+/**
+ * Write/clear a BARE JSX boolean attribute (`<DCArtboard fixed>`, not
+ * `fixed={true}` or a string). `value=false` reuses `removeStringAttr`'s
+ * generic span-plus-leading-whitespace removal (it doesn't care whether the
+ * attribute it's removing has a value) — only the `true` insert path is new.
+ */
+function writeBooleanAttr(
+  s: MagicString,
+  opening: AnyNode,
+  name: string,
+  value: boolean,
+  source: string
+): void {
+  if (!value) {
+    removeStringAttr(s, opening, name, source);
+    return;
+  }
+  if (findAttribute(opening, name)) return; // already present in some form
+  const insertAt: number | undefined = opening?.name?.end;
+  if (typeof insertAt !== 'number') throw new Error('Opening element has no resolvable name range');
+  s.appendLeft(insertAt, ` ${name}`);
+}
+
+/**
+ * Toggle an artboard's height sizing mode (Hug ⇄ Fixed CSS-panel control).
+ * `fixed=true` adds the bare `fixed` prop and, when `freezeHeight` is given
+ * (the board's current measured height), also writes it as the exact
+ * `height` — so pinning to Fixed doesn't snap the box back to whatever the
+ * JSX `height` floor happened to be. `fixed=false` removes the `fixed` prop;
+ * `height` is left as-is (it resumes being the hug floor). Same id-prop
+ * addressing as applyResizeArtboard (DDR-027 — an artboard frame carries no
+ * data-cd-id). Pure; reparse-gated.
+ */
+export function applySetArtboardHug(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string,
+  fixed: boolean,
+  freezeHeight?: number
+): { source: string } {
+  const parsed = parseSync(canvasAbsPath, source, { sourceType: 'module' });
+  if (parsed.errors && parsed.errors.length > 0) {
+    throw new CanvasEditError(
+      `oxc-parser failed on ${canvasAbsPath}: ${parsed.errors[0]?.message ?? 'unknown'}`,
+      { canvas: canvasAbsPath, id: artboardId }
+    );
+  }
+  const artboards = collectJsxByTag(parsed.program, 'DCArtboard');
+  const target = artboards.find((a) => getStringAttr(a.openingElement, 'id') === artboardId);
+  if (!target) {
+    throw new CanvasEditError(`<DCArtboard id="${artboardId}"> not found in ${canvasAbsPath}`, {
+      canvas: canvasAbsPath,
+      id: artboardId,
+    });
+  }
+  const s = new MagicString(source);
+  writeBooleanAttr(s, target.openingElement, 'fixed', fixed, source);
+  if (fixed && typeof freezeHeight === 'number') {
+    writeNumericAttr(s, target.openingElement, 'height', freezeHeight);
+  }
+  const out = s.toString();
+  const check = parseSync(canvasAbsPath, out, { sourceType: 'module' });
+  if (check.errors && check.errors.length > 0) {
+    throw new CanvasEditError(
+      `artboard hug-toggle produced invalid source (${check.errors[0]?.message ?? 'parse error'})`,
+      { canvas: canvasAbsPath, id: artboardId }
+    );
+  }
+  return { source: out };
+}
+
+/** Set an artboard's Hug/Fixed mode on disk (atomic write + cross-process lock). */
+export async function setArtboardHug(
+  canvasAbsPath: string,
+  artboardId: string,
+  fixed: boolean,
+  freezeHeight?: number
+): Promise<{ source: string }> {
+  return withLock(canvasAbsPath, async () => {
+    const file = Bun.file(canvasAbsPath);
+    if (!(await file.exists())) {
+      throw new CanvasEditError(`Canvas not found: ${canvasAbsPath}`, {
+        canvas: canvasAbsPath,
+        id: artboardId,
+      });
+    }
+    const source = await file.text();
+    const next = applySetArtboardHug(canvasAbsPath, source, artboardId, fixed, freezeHeight);
+    if (next.source === source) return next;
+    const tmp = `${canvasAbsPath}.tmp.${Math.random().toString(36).slice(2, 10)}`;
+    await Bun.write(tmp, next.source);
+    const { rename } = await import('node:fs/promises');
+    await rename(tmp, canvasAbsPath);
+    return next;
+  });
+}
+
+/** Patch shape for {@link applySetArtboardStyle} — `null` resets/removes that
+ *  prop back to the engine default; `undefined`/absent leaves it untouched. */
+export interface ArtboardStylePatch {
+  background?: string | null;
+  padding?: number | null;
+  layout?: string | null;
+  gap?: number | null;
+}
+
+/**
+ * Write the artboard "more settings" props (background / padding / layout /
+ * gap) — applied to `.dc-artboard-body` by DCArtboard, not the frame chrome.
+ * String props (background/layout) reuse `editStringAttr`/`removeStringAttr`;
+ * numeric props (padding/gap) reuse `writeNumericAttr` with a 0 floor (unlike
+ * width/height, 0 padding/gap is a normal value, not a degenerate one). Same
+ * id-prop addressing + reparse-gate as applyResizeArtboard/applySetArtboardHug.
+ */
+export function applySetArtboardStyle(
+  canvasAbsPath: string,
+  source: string,
+  artboardId: string,
+  patch: ArtboardStylePatch
+): { source: string } {
+  const parsed = parseSync(canvasAbsPath, source, { sourceType: 'module' });
+  if (parsed.errors && parsed.errors.length > 0) {
+    throw new CanvasEditError(
+      `oxc-parser failed on ${canvasAbsPath}: ${parsed.errors[0]?.message ?? 'unknown'}`,
+      { canvas: canvasAbsPath, id: artboardId }
+    );
+  }
+  const artboards = collectJsxByTag(parsed.program, 'DCArtboard');
+  const target = artboards.find((a) => getStringAttr(a.openingElement, 'id') === artboardId);
+  if (!target) {
+    throw new CanvasEditError(`<DCArtboard id="${artboardId}"> not found in ${canvasAbsPath}`, {
+      canvas: canvasAbsPath,
+      id: artboardId,
+    });
+  }
+  const s = new MagicString(source);
+  const opening = target.openingElement;
+  if ('background' in patch) {
+    if (patch.background == null) removeStringAttr(s, opening, 'background', source);
+    else editStringAttr(s, opening, 'background', patch.background, canvasAbsPath, artboardId);
+  }
+  if ('layout' in patch) {
+    if (patch.layout == null) removeStringAttr(s, opening, 'layout', source);
+    else editStringAttr(s, opening, 'layout', patch.layout, canvasAbsPath, artboardId);
+  }
+  if ('padding' in patch) {
+    if (patch.padding == null) removeStringAttr(s, opening, 'padding', source);
+    else writeNumericAttr(s, opening, 'padding', patch.padding, 0);
+  }
+  if ('gap' in patch) {
+    if (patch.gap == null) removeStringAttr(s, opening, 'gap', source);
+    else writeNumericAttr(s, opening, 'gap', patch.gap, 0);
+  }
+  const out = s.toString();
+  const check = parseSync(canvasAbsPath, out, { sourceType: 'module' });
+  if (check.errors && check.errors.length > 0) {
+    throw new CanvasEditError(
+      `artboard style edit produced invalid source (${check.errors[0]?.message ?? 'parse error'})`,
+      { canvas: canvasAbsPath, id: artboardId }
+    );
+  }
+  return { source: out };
+}
+
+/** Set an artboard's style props on disk (atomic write + cross-process lock). */
+export async function setArtboardStyle(
+  canvasAbsPath: string,
+  artboardId: string,
+  patch: ArtboardStylePatch
+): Promise<{ source: string }> {
+  return withLock(canvasAbsPath, async () => {
+    const file = Bun.file(canvasAbsPath);
+    if (!(await file.exists())) {
+      throw new CanvasEditError(`Canvas not found: ${canvasAbsPath}`, {
+        canvas: canvasAbsPath,
+        id: artboardId,
+      });
+    }
+    const source = await file.text();
+    const next = applySetArtboardStyle(canvasAbsPath, source, artboardId, patch);
+    if (next.source === source) return next;
+    const tmp = `${canvasAbsPath}.tmp.${Math.random().toString(36).slice(2, 10)}`;
+    await Bun.write(tmp, next.source);
+    const { rename } = await import('node:fs/promises');
+    await rename(tmp, canvasAbsPath);
+    return next;
+  });
+}
+
 /**
  * Delete the `<DCArtboard id="…">` whose `id` prop equals `artboardId` — the
  * artboard counterpart of applyDeleteElement (an artboard is addressed by its id