@1agh/maude 0.45.2 → 0.47.0

package/apps/studio/exporters/png.ts

@@ -12,6 +12,7 @@ import { tmpdir } from 'node:os';
 import path from 'node:path';
 
 import JSZip from 'jszip';
+import { CSS_DPI } from '../print/units.ts';
 import { exportShimPath, runShim } from './_runtime.ts';
 import {
   canvasShellUrl,
@@ -27,7 +28,8 @@ import type { Target } from './scope.ts';
 const PNG_PLAYWRIGHT = exportShimPath('_png-playwright.mjs');
 
 interface CaptureOptions {
-  scale?: 1 | 2 | 3;
+  /** Fully-resolved Playwright deviceScaleFactor — see resolveDeviceScale. */
+  scale?: number;
   timeoutSec?: number;
 }
 
@@ -42,6 +44,44 @@ export function clampScale(raw: unknown): 1 | 2 | 3 {
   return 2;
 }
 
+/** feature-2-print-artboards T4 — supported DPI presets (Adobe-conventional
+ *  print ladder). Exported for unit coverage. */
+export const DPI_PRESETS = [96, 150, 300, 600] as const;
+export type DpiPreset = (typeof DPI_PRESETS)[number];
+
+/** Coerce an arbitrary `options.dpi` to the nearest supported preset, or
+ *  `undefined` when absent/invalid (caller then falls back to `scale`). */
+export function clampDpi(raw: unknown): DpiPreset | undefined {
+  if (raw === undefined || raw === null) return undefined;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return undefined;
+  let best: DpiPreset = DPI_PRESETS[0];
+  let bestDelta = Math.abs(n - best);
+  for (const preset of DPI_PRESETS) {
+    const delta = Math.abs(n - preset);
+    if (delta < bestDelta) {
+      best = preset;
+      bestDelta = delta;
+    }
+  }
+  return best;
+}
+
+/**
+ * The Playwright `deviceScaleFactor` for a capture — `dpi` (physical print
+ * resolution) wins when present, else the legacy 1×/2×/3× UI preset.
+ * `dpi/96` because authoring is at CSS px @96dpi (print/units.ts CSS_DPI) —
+ * this is the ONE place outside that module allowed to divide by 96 (a
+ * device-scale-factor derivation, not an mm→px conversion, so it's exempt
+ * from the T1 single-source `25.4` lint guard, but stays in lockstep with
+ * CSS_DPI by importing it rather than hardcoding 96 again).
+ */
+export function resolveDeviceScale(options: ExportOptions): number {
+  const dpi = clampDpi(options.dpi);
+  if (dpi !== undefined) return dpi / CSS_DPI;
+  return clampScale(options.scale);
+}
+
 async function captureElement(
   target: Extract<Target, { kind: 'element' }>,
   ctx: ExportContext,
@@ -112,8 +152,10 @@ export async function run(
   const captureOpts: CaptureOptions = {
     // Default 2× — a single-scale PNG was uselessly small (item 1). The dialog
     // sends an explicit scale; this default covers direct API / curl callers.
-    // Clamped to the 1–3 preset range; the shim re-clamps deviceScaleFactor ≤ 4.
-    scale: clampScale(options.scale),
+    // feature-2-print-artboards T4 — `options.dpi` (96/150/300/600) wins over
+    // the legacy 1–3 preset when present; the shim re-clamps deviceScaleFactor
+    // ≤ 8 and guards oversized output (see _png-playwright.mjs).
+    scale: resolveDeviceScale(options),
     timeoutSec: (options.timeoutSec as number | undefined) ?? 8,
   };
 

package/apps/studio/footage/schema.ts

@@ -150,6 +150,10 @@ export interface FootageAnalysis {
   summary?: string;
   /** Cross-cutting tags ("rebrand", "exterior", "people"). */
   tags?: string[];
+  /** Optional audio/speech note — gist + language of what is said, filled ONLY when
+   *  an orchestrator (e.g. /design:video-analyze) hands the analyst a transcript.
+   *  Absent for the default vision-only path (e.g. /design:reel). */
+  speech?: string;
 }
 
 /** An optional graphic overlay laid over a beat (title card / lower-third / logo). */
@@ -437,7 +441,18 @@ export function validateFootageAnalysis(input: unknown): ValidationResult {
   assertKeys(
     errors,
     input,
-    ['version', 'asset', 'durationSec', 'width', 'height', 'keyframes', 'shots', 'summary', 'tags'],
+    [
+      'version',
+      'asset',
+      'durationSec',
+      'width',
+      'height',
+      'keyframes',
+      'shots',
+      'summary',
+      'tags',
+      'speech',
+    ],
     'root'
   );
   if ('version' in input && input.version != null && typeof input.version !== 'number')
@@ -449,6 +464,7 @@ export function validateFootageAnalysis(input: unknown): ValidationResult {
   intGe(errors, input, 'keyframes', 0, 'root');
   str(errors, input, 'summary', 4000, 'root');
   strArray(errors, input, 'tags', 64, 'root');
+  str(errors, input, 'speech', 4000, 'root');
 
   const dur = typeof input.durationSec === 'number' ? input.durationSec : Infinity;
   if ('shots' in input && input.shots != null) {

package/apps/studio/generation/gemma-models.ts

@@ -0,0 +1,224 @@
+// generation/gemma-models.ts — managed local Gemma-4 MLX models for the `gemma`
+// tier of `maude design smart-frames` (feature-scene-aware-keyframes). The
+// "one-click Gemma scout" story, mirroring whisper-models.ts — but with three
+// real differences from whisper:
+//
+//   1. Apple-Silicon only. The scout runs through mlx-vlm (a Python package); the
+//      model is useless without it. So the download is GATED on `mlxVlmAvailable`.
+//   2. Multi-file HF snapshot, not a single .bin. mlx-vlm resolves a model from the
+//      standard HuggingFace hub cache, so we download THERE (via huggingface_hub,
+//      a transitive dep of mlx-vlm) rather than a Maude-private cache — otherwise
+//      mlx-vlm wouldn't find it. "downloaded" = the snapshot is in the HF cache.
+//   3. The RUNTIME (mlx-vlm itself) is a manual `pip install` the app can't do for
+//      you — the Settings card says so and only the MODEL half is one click.
+//
+// This module owns the registry + availability probes + the HF-cache-aware
+// downloaded check + resolve. The download SPAWN lives here (it shells the mlx
+// Python's huggingface_hub); the http route wraps it with progress state, next to
+// the other provider egress.
+
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export interface GemmaModelDescriptor {
+  /** Stable id used by the pref + route. */
+  id: string;
+  /** The mlx-community HF repo (also the `--model` mlx-vlm resolves). */
+  repo: string;
+  /** Pinned commit SHA — the download fetches THIS revision, never floating `main`,
+   *  so a poisoned-main / namespace-reuse push can't land arbitrary model files
+   *  (DDR-183 supply-chain finding; the whisper baseline pins exact file URLs). */
+  revision: string;
+  label: string;
+  /** Approximate on-disk size (consent copy). */
+  sizeMB: number;
+  note: string;
+}
+
+// Curated allowlist of Gemma-4 MLX scout models. `repo` + `revision` are the frozen
+// download target (never user input). e4b is the default (better beats); e2b is the
+// small, fast option for lower-RAM Macs. Revisions pinned 2026-07-16.
+export const GEMMA_MODELS: readonly GemmaModelDescriptor[] = [
+  {
+    id: 'gemma-4-e4b-it-4bit',
+    repo: 'mlx-community/gemma-4-e4b-it-4bit',
+    revision: '475b9088d29754a3379866cf5aeb6b41acd313c2',
+    label: 'Gemma 4 E4B (4-bit)',
+    sizeMB: 3300,
+    note: 'The recommended scout — best semantic beats. ~3.3 GB. Needs an Apple-Silicon Mac + mlx-vlm.',
+  },
+  {
+    id: 'gemma-4-e2b-it-4bit',
+    repo: 'mlx-community/gemma-4-e2b-it-4bit',
+    revision: '238767527555cb75a05732a84dff5d6ba0dd6809',
+    label: 'Gemma 4 E2B (4-bit)',
+    sizeMB: 1900,
+    note: 'Smaller/faster, coarser beats. ~1.9 GB. Good for 16 GB Macs.',
+  },
+];
+
+export function getGemmaModel(id: unknown): GemmaModelDescriptor | null {
+  return GEMMA_MODELS.find((m) => m.id === id) ?? null;
+}
+
+/** The HuggingFace hub cache dir mlx-vlm resolves models from (HF_HOME-aware). */
+export function hfHubDir(): string {
+  const hfHome = process.env.HF_HOME;
+  if (hfHome && hfHome.length > 0) return join(hfHome, 'hub');
+  const base = process.env.XDG_CACHE_HOME || join(homedir(), '.cache');
+  return join(base, 'huggingface', 'hub');
+}
+
+/** HF snapshot dir name for a repo: `models--<org>--<name>`. */
+function repoCacheDir(repo: string): string {
+  return join(hfHubDir(), `models--${repo.replace('/', '--')}`);
+}
+
+/** A model counts as downloaded when its HF snapshot dir has a non-empty snapshot. */
+export function gemmaModelDownloaded(m: GemmaModelDescriptor): boolean {
+  const snaps = join(repoCacheDir(m.repo), 'snapshots');
+  try {
+    if (!existsSync(snaps)) return false;
+    for (const rev of readdirSync(snaps)) {
+      const revDir = join(snaps, rev);
+      try {
+        if (statSync(revDir).isDirectory() && readdirSync(revDir).length > 0) return true;
+      } catch {
+        /* skip */
+      }
+    }
+  } catch {
+    /* not downloaded */
+  }
+  return false;
+}
+
+export interface GemmaModelStatus extends GemmaModelDescriptor {
+  downloaded: boolean;
+}
+
+export function listGemmaModels(): GemmaModelStatus[] {
+  return GEMMA_MODELS.map((m) => ({ ...m, downloaded: gemmaModelDownloaded(m) }));
+}
+
+/** Resolve a Python that can `import mlx_vlm` (honors $MAUDE_MLX_PYTHON), or null. */
+export function resolveMlxPython(): string | null {
+  const candidates = [process.env.MAUDE_MLX_PYTHON, 'python3', 'python'].filter(
+    Boolean
+  ) as string[];
+  for (const py of candidates) {
+    const r = spawnSync(py, ['-c', 'import mlx_vlm'], { stdio: 'ignore' });
+    if (r.status === 0) return py;
+  }
+  return null;
+}
+
+// Availability probes spawn subprocesses (importing mlx_vlm can take hundreds of ms
+// to seconds). The GET /_api/generate/keyframe-model route is un-CSRF-gated (correct
+// for a read), so a cross-origin drive-by could hammer it and stall the single-
+// threaded Bun event loop on synchronous spawns (security-auditor DDR-183 finding).
+// Memoize with a short TTL: DoS-bounded to at most one probe per PROBE_TTL_MS
+// regardless of request rate, while still picking up a mid-session `pip install` /
+// PATH change within the TTL.
+const PROBE_TTL_MS = 30_000;
+const probeCache = new Map<string, { at: number; value: boolean }>();
+
+function cachedProbe(key: string, compute: () => boolean): boolean {
+  const now = Date.now();
+  const hit = probeCache.get(key);
+  if (hit && now - hit.at < PROBE_TTL_MS) return hit.value;
+  const value = compute();
+  probeCache.set(key, { at: now, value });
+  return value;
+}
+
+export function mlxVlmAvailable(): boolean {
+  return cachedProbe('mlx', () => resolveMlxPython() !== null);
+}
+
+export function ffmpegAvailable(): boolean {
+  return cachedProbe('ffmpeg', () => {
+    const finder = process.platform === 'win32' ? 'where' : 'which';
+    return (
+      spawnSync(finder, ['ffmpeg'], { stdio: 'ignore' }).status === 0 &&
+      spawnSync(finder, ['ffprobe'], { stdio: 'ignore' }).status === 0
+    );
+  });
+}
+
+/**
+ * Download a Gemma model into the HF hub cache via huggingface_hub (a transitive
+ * dep of mlx-vlm, so it's present whenever the scout can actually run). We delegate
+ * to Python rather than reimplement multi-file HF snapshot download + LFS/Xet
+ * redirect handling in TS — the repo id is frozen (never user input), the runtime
+ * is pinned to the mlx Python, and the route is loopback + same-origin only.
+ * Progress is coarse (tqdm on stderr → a heartbeat), which the route surfaces as an
+ * in-flight state. Rejects if mlx-vlm/Python is absent (you couldn't run the model
+ * anyway) or the process exits non-zero.
+ */
+export function downloadGemmaModel(
+  id: string,
+  onProgress: (received: number, total: number) => void,
+  signal?: AbortSignal
+): Promise<void> {
+  const m = getGemmaModel(id);
+  if (!m) return Promise.reject(new Error(`unknown gemma model: ${id}`));
+  const py = resolveMlxPython();
+  if (!py)
+    return Promise.reject(
+      new Error(
+        'mlx-vlm not installed — the Gemma scout needs an Apple-Silicon Mac + `pip install mlx-vlm`.'
+      )
+    );
+
+  // Refuse a steered HF endpoint (mirror/redirect) — the whisper path pins the host;
+  // huggingface_hub otherwise honors HF_ENDPOINT/HF_HUB_ENDPOINT. Keep the pull on
+  // the canonical hub (DDR-183 supply-chain finding).
+  const endpoint = process.env.HF_ENDPOINT || process.env.HF_HUB_ENDPOINT;
+  if (endpoint && !/^https:\/\/huggingface\.co\/?$/.test(endpoint))
+    return Promise.reject(new Error(`refusing model download: HF endpoint steered to ${endpoint}`));
+
+  const total = m.sizeMB * 1024 * 1024;
+  return new Promise((resolve, reject) => {
+    // snapshot_download(repo, revision=<pinned sha>) — repo AND revision are from the
+    // frozen registry (never user input), passed as argv (not interpolated into -c).
+    const child = spawn(
+      py,
+      [
+        '-c',
+        'import sys; from huggingface_hub import snapshot_download; snapshot_download(sys.argv[1], revision=sys.argv[2])',
+        m.repo,
+        m.revision,
+      ],
+      {
+        stdio: ['ignore', 'ignore', 'pipe'],
+        env: { ...process.env, HF_HUB_DISABLE_TELEMETRY: '1' },
+      }
+    );
+    let received = 0;
+    const onAbort = () => child.kill('SIGTERM');
+    signal?.addEventListener('abort', onAbort, { once: true });
+    // tqdm writes percentage lines to stderr; use them as a coarse heartbeat.
+    child.stderr?.on('data', (buf: Buffer) => {
+      const s = buf.toString();
+      const pct = /(\d{1,3})%/.exec(s);
+      if (pct) received = Math.min(total, Math.round((Number(pct[1]) / 100) * total));
+      onProgress(received, total);
+    });
+    child.on('error', (err) => {
+      signal?.removeEventListener('abort', onAbort);
+      reject(err);
+    });
+    child.on('close', (code) => {
+      signal?.removeEventListener('abort', onAbort);
+      if (code === 0 && gemmaModelDownloaded(m)) {
+        onProgress(total, total);
+        resolve();
+      } else {
+        reject(new Error(`gemma model download failed (exit ${code})`));
+      }
+    });
+  });
+}

package/apps/studio/generation/prefs.ts

@@ -20,6 +20,16 @@ export function isTranscriptionProvider(v: unknown): v is TranscriptionProvider
   return typeof v === 'string' && (TRANSCRIPTION_PROVIDERS as readonly string[]).includes(v);
 }
 
+/** Scene-aware keyframe engines (feature-scene-aware-keyframes) — the tier the
+ *  `gemma` scout → `ffmpeg` scene-detect → `blind` Chromium fallback ladder runs
+ *  in. `auto` self-detects installed deps. */
+export const KEYFRAME_ENGINES = ['auto', 'gemma', 'ffmpeg', 'blind'] as const;
+export type KeyframeEngine = (typeof KEYFRAME_ENGINES)[number];
+
+export function isKeyframeEngine(v: unknown): v is KeyframeEngine {
+  return typeof v === 'string' && (KEYFRAME_ENGINES as readonly string[]).includes(v);
+}
+
 function configPath(repoRoot: string): string {
   return join(repoRoot, '.design', 'config.json');
 }
@@ -80,3 +90,36 @@ export async function writeTranscriptionProvider(
   await Bun.write(configPath(repoRoot), `${JSON.stringify(next, null, 2)}\n`);
   return true;
 }
+
+/** The current scene-aware keyframe engine preference, or 'auto' (the default). */
+export function readKeyframeEngine(repoRoot: string): KeyframeEngine {
+  const cfg = readConfig(repoRoot);
+  const gen = cfg.generation as Record<string, unknown> | undefined;
+  const kf = gen?.keyframes as Record<string, unknown> | undefined;
+  return isKeyframeEngine(kf?.engine) ? (kf?.engine as KeyframeEngine) : 'auto';
+}
+
+/**
+ * Persist the keyframe-engine choice into `.design/config.json`, preserving every
+ * other field (same additive-merge + fail-closed-on-corrupt discipline as the
+ * transcription writer).
+ */
+export async function writeKeyframeEngine(repoRoot: string, engine: string): Promise<boolean> {
+  if (!isKeyframeEngine(engine)) throw new Error(`invalid keyframe engine: ${engine}`);
+  const p = configPath(repoRoot);
+  if (existsSync(p)) {
+    try {
+      JSON.parse(readFileSync(p, 'utf8'));
+    } catch {
+      throw new Error(
+        '.design/config.json is present but not valid JSON — fix it before changing generation prefs (refusing to overwrite it)'
+      );
+    }
+  }
+  const cfg = readConfig(repoRoot);
+  const gen = (cfg.generation as Record<string, unknown>) ?? {};
+  const keyframes = (gen.keyframes as Record<string, unknown>) ?? {};
+  const next = { ...cfg, generation: { ...gen, keyframes: { ...keyframes, engine } } };
+  await Bun.write(configPath(repoRoot), `${JSON.stringify(next, null, 2)}\n`);
+  return true;
+}

package/apps/studio/grid-track-handles.ts

@@ -0,0 +1,179 @@
+/**
+ * @file       grid-track-handles.ts — feature-3-web-artboards T5 (absorbed
+ *             feature-grid-track-editor stub).
+ * @purpose    Pure geometry + value math for the on-canvas grid gutter
+ *             drag-resize overlay. Framework-free (unit-testable without a
+ *             DOM), mirroring `spacing-handles.ts`'s shape exactly — this is
+ *             the CSS-Grid sibling of that flex/box-model module, deferred
+ *             there in a doc comment ("CSS-Grid gap editing is out of v1
+ *             scope — grid tracks are a separate follow-up plan").
+ *
+ *             Track SIZING math is a two-layer split, same idiom as the
+ *             padding/gap overlay: geometry (gutter positions) reads the
+ *             browser's RESOLVED px sizes (the caller reads
+ *             `getComputedStyle(el).gridTemplateColumns` — the browser
+ *             already ran the grid-sizing algorithm, resolving `fr`/`auto`/
+ *             `%` tracks to concrete px, so this module never re-implements
+ *             that algorithm); DRAG math re-derives a new AUTHORED value
+ *             (the JSX-authored unit — px/%/fr/em — read from the element's
+ *             inline style, since these on-canvas tools only edit inline-
+ *             style-authored values, same constraint as every other curated
+ *             knob) from the ratio between the target resolved size and the
+ *             track's CURRENT resolved size.
+ */
+
+export type GridTrackUnit = 'px' | '%' | 'fr' | 'em' | 'auto' | 'min-content' | 'max-content';
+
+export const GRID_KEYWORD_UNITS: ReadonlySet<GridTrackUnit> = new Set([
+  'auto',
+  'min-content',
+  'max-content',
+]);
+
+export interface GridTrack {
+  /** Numeric value; 0 (ignored) for keyword-only units. */
+  value: number;
+  unit: GridTrackUnit;
+}
+
+const NUMERIC_TRACK_RE = /^(-?\d+(?:\.\d+)?)(px|%|fr|em)$/;
+
+/**
+ * Parse a `grid-template-columns`/`grid-template-rows` value into a track
+ * list. Handles a plain space-separated list of numeric (px/%/fr/em) and
+ * keyword (auto/min-content/max-content) tracks. Returns `[]` for an empty
+ * string OR anything it can't parse token-for-token (e.g. `repeat(...)`,
+ * `minmax(...)`, `subgrid`) — the caller treats an empty parse as "no
+ * drag-editable tracks", falling back to the Inspector's raw-value field
+ * rather than guessing at a lossy round-trip.
+ */
+export function parseTrackList(raw: string | null | undefined): GridTrack[] {
+  const s = (raw ?? '').trim();
+  if (!s) return [];
+  const parts = s.split(/\s+/);
+  const out: GridTrack[] = [];
+  for (const part of parts) {
+    if (GRID_KEYWORD_UNITS.has(part as GridTrackUnit)) {
+      out.push({ value: 0, unit: part as GridTrackUnit });
+      continue;
+    }
+    const m = NUMERIC_TRACK_RE.exec(part);
+    if (!m) return [];
+    out.push({ value: Number(m[1]), unit: m[2] as GridTrackUnit });
+  }
+  return out;
+}
+
+/** Serialize a track list back to a `grid-template-columns`/`-rows` value —
+ *  the inverse of `parseTrackList`. `fr` (and every other unit) round-trips
+ *  byte-for-byte modulo the `round2` value rounding applied during drag. */
+export function serializeTrackList(tracks: GridTrack[]): string {
+  return tracks
+    .map((t) => (GRID_KEYWORD_UNITS.has(t.unit) ? t.unit : `${round2(t.value)}${t.unit}`))
+    .join(' ');
+}
+
+export interface ScreenRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+export interface GutterLine {
+  /** Index of the track BEFORE this gutter; track `index + 1` is after it. */
+  index: number;
+  axis: 'x' | 'y';
+  x: number;
+  y: number;
+}
+
+/**
+ * Compute gutter handle positions from a grid container's screen rect, each
+ * track's RESOLVED size in screen px (already zoom-scaled — same convention
+ * as `computePaddingLines`'s `padding` argument), and the resolved gap
+ * between tracks. One gutter per adjacent pair, positioned at the gap's
+ * midpoint. Fewer than 2 tracks → no gutters.
+ */
+export function computeGutterLines(
+  rect: ScreenRect,
+  resolvedSizesPx: number[],
+  gapPx: number,
+  axis: 'col' | 'row'
+): GutterLine[] {
+  if (resolvedSizesPx.length < 2) return [];
+  const out: GutterLine[] = [];
+  let cum = axis === 'col' ? rect.x : rect.y;
+  for (let i = 0; i < resolvedSizesPx.length - 1; i++) {
+    cum += resolvedSizesPx[i] as number;
+    const mid = cum + gapPx / 2;
+    if (axis === 'col') {
+      out.push({ index: i, axis: 'x', x: mid, y: rect.y + rect.h / 2 });
+    } else {
+      out.push({ index: i, axis: 'y', x: rect.x + rect.w / 2, y: mid });
+    }
+    cum += gapPx;
+  }
+  return out;
+}
+
+/**
+ * New AUTHORED value for one track being dragged, given the screen-px delta
+ * (world units — the caller already divides by zoom, same convention as
+ * `computePaddingDrag`/`computeGapDrag`... actually this one takes the RAW
+ * screen delta + zoom together, dividing internally, to match those two
+ * functions' own signature exactly) and the track's CURRENT resolved px size.
+ *
+ * - `px` / `em` — additive: 1 world px of drag = 1 unit (em is treated as a
+ *   px-equivalent for drag purposes — a precise em→px conversion would need
+ *   the element's own font-size; this is a disclosed simplification, same
+ *   spirit as the rest of this drag lane favoring predictable math over
+ *   pixel-perfect unit fidelity mid-drag).
+ * - `fr` / `%` — proportional SHARE units, not absolute sizes: the new value
+ *   is the OLD value scaled by (targetResolvedPx / currentResolvedPx) — the
+ *   same "re-derive the ratio" approach a flex-grow-style drag uses. Clamped
+ *   to a small positive floor so a track never collapses to (or past) zero
+ *   share.
+ * - keyword tracks (auto/min-content/max-content) have no numeric value —
+ *   returns the track unchanged; the caller must not offer this as a
+ *   drag target (see `gutterTrackIndices` — the hook filters keyword-only
+ *   tracks out of the touched set before calling this).
+ */
+export function computeTrackDrag(
+  track: GridTrack,
+  resolvedPx: number,
+  dxScreen: number,
+  dyScreen: number,
+  zoom: number,
+  axis: 'x' | 'y'
+): number {
+  if (GRID_KEYWORD_UNITS.has(track.unit)) return track.value;
+  const z = zoom > 0 ? zoom : 1;
+  const d = (axis === 'x' ? dxScreen : dyScreen) / z;
+  if (track.unit === 'px' || track.unit === 'em') {
+    return Math.max(0, round2(track.value + d));
+  }
+  const targetPx = Math.max(1, resolvedPx + d);
+  if (resolvedPx <= 0) return track.value; // no ratio to derive from — no-op
+  const ratio = targetPx / resolvedPx;
+  const floor = track.unit === '%' ? 1 : 0.1;
+  return Math.max(floor, round2(track.value * ratio));
+}
+
+/**
+ * Which track indices a gutter drag touches, given the Shift modifier —
+ * mirrors `paddingSideSet`'s Alt/Shift convention: plain drag touches only
+ * the track BEFORE the gutter; Shift touches BOTH neighbors (each driven to
+ * its own new value from the SAME cursor delta — "symmetric" in this
+ * codebase's established vocabulary means both move together, not an
+ * inversely-linked splitter, matching how `paddingSideSet`'s Alt sets both
+ * opposite padding sides to the identical dragged value rather than trading
+ * space between them).
+ */
+export function gutterTrackIndices(gutterIndex: number, shiftKey: boolean): number[] {
+  return shiftKey ? [gutterIndex, gutterIndex + 1] : [gutterIndex];
+}
+
+function round2(n: number): number {
+  return Math.round(n * 100) / 100;
+}

package/apps/studio/handoff.ts

@@ -80,6 +80,15 @@ export interface RegistryItem {
     light?: Record<string, string>;
     dark?: Record<string, string>;
   };
+  /**
+   * shadcn's generic item-specific-metadata extension point. feature-3-web-
+   * artboards T6 — carries the resolved artboard `kind` (`digital` | `print`
+   * | `web` | `video` | `mixed`) so a consumer (or a future re-import) knows
+   * what authoring contract produced this drop without re-parsing the TSX.
+   */
+  meta?: {
+    kind: string;
+  };
 }
 
 export interface EmitOptions {
@@ -103,6 +112,31 @@ export interface EmitOptions {
   designRoot?: string;
 }
 
+// ---------------------------------------------------------------------------
+// feature-3-web-artboards T6 — thread the artboard kind into the emitted
+// registry-item's `meta` (a first-class shadcn registry-item.json extension
+// point for item-specific metadata, not a maude-invented field). A regex scan
+// is deliberate here (not an AST walk like stripDataCdId) — this only needs
+// the `kind="…"` string values, never a node reference to edit.
+
+/**
+ * Resolve a single `kind` value for the whole canvas file, from its
+ * `<DCArtboard kind="…">` occurrences. A canvas with zero explicit `kind`
+ * attributes resolves to `'digital'` (DCArtboard's own implicit default). A
+ * canvas whose artboards carry more than one distinct explicit kind (e.g. a
+ * multi-breakpoint web canvas assembled via "Duplicate at width…" next to an
+ * unrelated screen) resolves to `'mixed'` rather than picking one arbitrarily.
+ */
+export function resolveCanvasKind(rawSource: string): string {
+  const kinds = new Set<string>();
+  for (const m of rawSource.matchAll(/<DCArtboard\b[^>]*\bkind="([a-z]+)"/g)) {
+    if (m[1]) kinds.add(m[1]);
+  }
+  if (kinds.size === 0) return 'digital';
+  if (kinds.size === 1) return [...kinds][0] as string;
+  return 'mixed';
+}
+
 // ---------------------------------------------------------------------------
 // Strip data-cd-id from source — the inverse of canvas-pipeline.ts pass 1.
 
@@ -668,6 +702,7 @@ export async function emitRegistryItem(opts: EmitOptions): Promise<RegistryItem>
     registryDependencies,
     files,
     ...(cssVars ? { cssVars } : {}),
+    meta: { kind: resolveCanvasKind(rawTsx) },
   };
 
   // Drop undefined keys for a clean JSON.