@agent-native/core 0.80.9 → 0.80.10

package/corpus/templates/design/shared/shader-fill.ts

@@ -0,0 +1,323 @@
+/**
+ * shader-fill.ts — pure CSS mesh-gradient "shader fill" helpers.
+ *
+ * No DB, no side effects.  Deterministic output: same descriptor → same CSS.
+ *
+ * Two exports:
+ * - `generateShaderFillPreviewCss`  — a CSS mesh-gradient that approximates the
+ *   shader fill visually; safe to inject into the iframe via a bridge
+ *   `tweak-values`-style message without any write commit.
+ * - `generateShaderFillFallbackCss` — a static CSS fallback that can be placed
+ *   in `<style>` blocks when the WebGL runtime is absent (export, SSR, PDF).
+ *
+ * The fallback is intentionally simpler than the preview (no animation, no
+ * WebGL) so it stays safe at the container level.  Both return the string value
+ * of a CSS `background` property — the caller wraps it in a rule.
+ */
+
+import type { ShaderDescriptor, ShaderPresetName } from "./shader-presets.js";
+import { SHADER_PRESET_MAP } from "./shader-presets.js";
+
+// ─── CSS-injection safety ────────────────────────────────────────────────────
+
+/**
+ * Neutral fallback used when a caller-supplied colour fails validation. Keeps
+ * the rendered gradient deterministic and visually sane without ever echoing
+ * untrusted text into a CSS `background` / gradient string.
+ */
+const SAFE_FALLBACK_COLOR = "#808080";
+
+/**
+ * Characters that must never appear inside a colour token or selector: they
+ * can terminate the current declaration/rule (`;` `}`), open a new rule (`{`),
+ * break out of `<style>` (`<` `>`), or pull in a remote resource (`url(`).
+ */
+const CSS_BREAKOUT_RE = /[;{}<>]|url\(/i;
+
+/**
+ * Strict allowlist for a single CSS colour token. Accepts only:
+ * - hex: `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`
+ * - `rgb()` / `rgba()`
+ * - `hsl()` / `hsla()`
+ * - `oklch()`
+ * - bare named colours (e.g. `rebeccapurple`, `transparent`)
+ *
+ * Anything containing CSS-breakout characters, whitespace that could break out
+ * of the property value, or `url(` is rejected.
+ */
+function isSafeCssColor(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  const trimmed = value.trim();
+  if (!trimmed) return false;
+  // Reject declaration/rule/style/`url(` breakout characters outright.
+  if (CSS_BREAKOUT_RE.test(trimmed)) return false;
+  return (
+    // Hex: 3, 4, 6, or 8 digits.
+    /^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/.test(trimmed) ||
+    // rgb() / rgba(): digits, %, commas, dots, slash, whitespace, sign only.
+    /^rgba?\(\s*[0-9%,.\s/+-]+\)$/.test(trimmed) ||
+    // hsl() / hsla(): same numeric charset plus an optional `deg` unit.
+    /^hsla?\(\s*[0-9%,.\s/+-]+(?:deg)?[0-9%,.\s/+-]*\)$/.test(trimmed) ||
+    // oklch(): digits, %, dots, slash, whitespace, sign only.
+    /^oklch\(\s*[0-9%.\s/+-]+\)$/.test(trimmed) ||
+    // Bare named colour (alphabetic only — `transparent`, `rebeccapurple`, …).
+    /^[a-zA-Z]+$/.test(trimmed)
+  );
+}
+
+/**
+ * Coerce a caller-supplied colour to a safe value: returns the trimmed colour
+ * if it passes the strict allowlist, otherwise a neutral fallback. This is the
+ * single choke point every colour passes through before being interpolated
+ * into a CSS string.
+ */
+function safeColor(value: string): string {
+  return isSafeCssColor(value) ? value.trim() : SAFE_FALLBACK_COLOR;
+}
+
+/** Sanitise a whole palette, dropping nothing but neutralising unsafe entries. */
+function safePalette(colors: string[]): string[] {
+  return colors.map(safeColor);
+}
+
+/**
+ * Validate a CSS selector before it is interpolated into a `selector { … }`
+ * rule. Rejects anything containing declaration/rule/style/`url(` breakout
+ * characters; falls back to a harmless `:root` when invalid so callers never
+ * inject an attacker-controlled rule head.
+ */
+function safeSelector(selector: string): string {
+  const trimmed = typeof selector === "string" ? selector.trim() : "";
+  if (!trimmed || CSS_BREAKOUT_RE.test(trimmed)) return ":root";
+  return trimmed;
+}
+
+// ─── Internal colour helpers ────────────────────────────────────────────────
+
+/**
+ * Resolve the primary colour palette for a descriptor.
+ * Falls back to the preset defaults when the descriptor carries no colours.
+ *
+ * Every returned colour is run through the strict CSS-colour allowlist so the
+ * downstream gradient/`background` strings can never carry a CSS-injection
+ * payload from `descriptor.colors`.
+ */
+function resolveColors(descriptor: ShaderDescriptor): string[] {
+  if (descriptor.colors && descriptor.colors.length > 0) {
+    return safePalette(descriptor.colors);
+  }
+  const presetDef = SHADER_PRESET_MAP[descriptor.preset];
+  if (presetDef?.defaultColors && presetDef.defaultColors.length > 0) {
+    return safePalette(presetDef.defaultColors);
+  }
+  // Last-resort neutral palette.
+  return ["#e0e0e0", "#a0a0c0"];
+}
+
+/**
+ * Resolve the first "single back" color if the preset defines one, otherwise
+ * fall back to the last entry in the palette.
+ */
+function resolveBackColor(
+  descriptor: ShaderDescriptor,
+  palette: string[],
+): string {
+  const presetDef = SHADER_PRESET_MAP[descriptor.preset];
+  if (presetDef?.defaultColorBack) return safeColor(presetDef.defaultColorBack);
+  return palette[palette.length - 1] ?? "#000000";
+}
+
+// ─── Gradient stop generators (per-preset family) ────────────────────────────
+
+/**
+ * Build a conic-gradient string that loosely mimics MeshGradient / GrainGradient
+ * colour placement.  The stops are evenly distributed.
+ */
+function buildConicGradient(colors: string[], rotation = 0): string {
+  const deg = Math.round((rotation * 180) / Math.PI);
+  const n = colors.length;
+  const stops = colors
+    .map((c, i) => `${c} ${Math.round((i / n) * 360)}deg`)
+    .join(", ");
+  return `conic-gradient(from ${deg}deg at 50% 50%, ${stops}, ${colors[0]} 360deg)`;
+}
+
+/**
+ * Build a radial-gradient with the supplied colours — good approximation of
+ * Voronoi / Metaballs / GodRays where colour pools radiate from the centre.
+ */
+function buildRadialGradient(colors: string[], back: string): string {
+  const n = colors.length;
+  const stops = colors
+    .map((c, i) => {
+      const pct = Math.round(((i + 0.5) / n) * 100);
+      return `${c} ${pct}%`;
+    })
+    .join(", ");
+  return `radial-gradient(ellipse at 50% 50%, ${stops}, ${back} 100%)`;
+}
+
+/**
+ * Build a linear-gradient — used for Warp / Dithering / PaperTexture
+ * where a flat gradient is the closest safe approximation.
+ */
+function buildLinearGradient(colors: string[], angleDeg = 135): string {
+  const n = colors.length;
+  const stops = colors
+    .map((c, i) => `${c} ${Math.round((i / Math.max(n - 1, 1)) * 100)}%`)
+    .join(", ");
+  return `linear-gradient(${angleDeg}deg, ${stops})`;
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Generate a deterministic CSS `background` value that previews the shader
+ * fill without any WebGL runtime.
+ *
+ * The value is a multi-stop CSS gradient that approximates the shader's colour
+ * scheme and general shape.  It is safe to inject into the iframe canvas via a
+ * bridge message without persisting anything.
+ *
+ * Callers set this as the `background` property on the target element.
+ *
+ * @param descriptor - The ShaderDescriptor defining preset + params + colours.
+ * @returns A CSS `background` property value string.
+ */
+export function generateShaderFillPreviewCss(
+  descriptor: ShaderDescriptor,
+): string {
+  const palette = resolveColors(descriptor);
+  const back = resolveBackColor(descriptor, palette);
+  const preset: ShaderPresetName = descriptor.preset;
+  const rotation = descriptor.rotation ?? 0;
+
+  switch (preset) {
+    case "MeshGradient":
+    case "GrainGradient":
+      // Conic gradient best captures the swirling multi-colour look.
+      return buildConicGradient(palette, rotation);
+
+    case "Voronoi":
+    case "Metaballs":
+      // Radial gradient captures the pooling/bubbling character.
+      return buildRadialGradient(palette, back);
+
+    case "GodRays": {
+      // Radial for the central bloom, bias toward darker back colour.
+      const godColors =
+        palette.length > 0 ? palette : ["#6200ff", "#ffffff", "#a600ff"];
+      return buildRadialGradient(godColors, back);
+    }
+
+    case "Warp":
+    case "Dithering":
+    case "PaperTexture":
+    default:
+      // Linear gradient is the safest approximation for these.
+      return buildLinearGradient(
+        palette,
+        Math.round((rotation * 180) / Math.PI) + 135,
+      );
+  }
+}
+
+/**
+ * Generate a static CSS `background` value intended as a permanent fallback
+ * when the WebGL runtime is absent (export, PDF, SSR, e-mail).
+ *
+ * Deliberately simpler than the preview:
+ * - No animation keyframes (would be stripped anyway).
+ * - Single gradient stop per colour.
+ * - Safe at any container size.
+ *
+ * Callers set this as the `background` property in a `<style>` fallback rule
+ * that is overridden at runtime when the shader canvas mounts.
+ *
+ * @param descriptor - The ShaderDescriptor defining preset + params + colours.
+ * @returns A CSS `background` property value string, suitable for a `<style>` block.
+ */
+export function generateShaderFillFallbackCss(
+  descriptor: ShaderDescriptor,
+): string {
+  const palette = resolveColors(descriptor);
+  const back = resolveBackColor(descriptor, palette);
+
+  if (palette.length === 1) {
+    return palette[0];
+  }
+
+  // For all presets: a simple linear-gradient is the most universally
+  // compatible fallback.  135 deg gives a diagonal that reads as "designed".
+  const stops = palette
+    .map(
+      (c, i) =>
+        `${c} ${Math.round((i / Math.max(palette.length - 1, 1)) * 100)}%`,
+    )
+    .join(", ");
+
+  // If the preset has a distinct back colour, bookend with it.
+  const hasDistinctBack =
+    SHADER_PRESET_MAP[descriptor.preset]?.defaultColorBack != null &&
+    !palette.includes(back);
+
+  if (hasDistinctBack) {
+    return `linear-gradient(135deg, ${back} 0%, ${stops}, ${back} 100%)`;
+  }
+
+  return `linear-gradient(135deg, ${stops})`;
+}
+
+/**
+ * Build the complete CSS block for injecting a shader-fill fallback on a
+ * selector.  The block includes:
+ * 1. A `background` fallback rule (static gradient).
+ * 2. A CSS comment marking it as a shader-fill fallback so tooling can detect
+ *    and replace it.
+ *
+ * @param selector - The CSS selector to target (e.g. `#hero`, `.card`).
+ * @param descriptor - The ShaderDescriptor.
+ * @returns A complete CSS block string, ready to embed in a `<style>` element.
+ */
+export function buildShaderFillFallbackBlock(
+  selector: string,
+  descriptor: ShaderDescriptor,
+): string {
+  const bg = generateShaderFillFallbackCss(descriptor);
+  const safeSel = safeSelector(selector);
+  return [
+    `/* shader-fill-fallback: ${descriptor.preset} */`,
+    `${safeSel} {`,
+    `  background: ${bg};`,
+    `}`,
+  ].join("\n");
+}
+
+/**
+ * Resolve the CSS `background` value to persist into the design source for a
+ * shader fill.
+ *
+ * This is the single value `apply-shader-fill` writes onto the target element's
+ * inline `style.background`.  It is identical to the value the live preview
+ * renders (`generateShaderFillPreviewCss`) so "what you previewed is what you
+ * get", and — like every other output of this module — every colour passes
+ * through the strict CSS-colour allowlist before being interpolated, so a
+ * `descriptor.colors` payload can never carry a CSS-injection string into the
+ * persisted source.
+ *
+ * Returns the gradient string plus the sanitised palette that produced it so
+ * callers can surface proof-of-persist (which colours were written, which were
+ * neutralised) without re-deriving them.
+ *
+ * @param descriptor - The ShaderDescriptor defining preset + params + colours.
+ * @returns `{ background, colors }` — the value to write and the safe palette.
+ */
+export function buildShaderFillBackground(descriptor: ShaderDescriptor): {
+  background: string;
+  colors: string[];
+} {
+  return {
+    background: generateShaderFillPreviewCss(descriptor),
+    colors: resolveColors(descriptor),
+  };
+}

package/corpus/templates/design/shared/source-mode.ts

@@ -1,5 +1,92 @@
+/**
+ * Source modes, bridge operations, and capability-aware source descriptors for
+ * the Design Studio.
+ *
+ * This module is the single canonical home for:
+ * - `DesignSourceType` — the three runtime tiers (inline | localhost | fusion).
+ * - `DesignBridgeOperation` — the low-level bridge RPC surface.
+ * - `DesignSourceDescriptor` variants — now optionally carry a proven
+ *   `DesignSourceCapabilities` map so callers never infer write ability from
+ *   `sourceType` alone (see §1.1 of DESIGN-STUDIO-PLAN.md).
+ * - `resolveDescriptorCapabilities()` — preferred helper: returns the proven
+ *   capability set when present on the descriptor, otherwise falls back to the
+ *   `resolveSourceCapabilities()` tier defaults from `capability-resolver.ts`.
+ *
+ * Relation to `design-source-capabilities.ts`:
+ * - `DesignBridgeOperation` / `DesignBridgeOperationStatus` describe the
+ *   low-level bridge RPC surface (used in `DesignBridgeCapability` and
+ *   `LocalhostDesignConnectionConfig.capabilities`).
+ * - `DesignCapabilityName` / `DesignSourceCapabilities` (defined in
+ *   `design-source-capabilities.ts`) are the higher-level vocabulary that UI
+ *   panels and server actions gate on.  They extend
+ *   `DesignBridgeOperationStatus` with `"unavailable"` to support the
+ *   migration-CTA pattern.
+ */
+
+// Circular-safe imports from `design-source-capabilities.ts`.
+//
+// `design-source-capabilities.ts` imports only via `import type` from this
+// module, so the runtime module graph has NO cycle.  TypeScript's type checker
+// handles the bidirectional type reference correctly; `tsc --noEmit` passes.
+//
+// - Type-only import: used for the `capabilities?` fields on source descriptors
+//   and `LocalhostDesignConnectionConfig.sourceCapabilities`.
+// - Value import: the canonical default maps consumed by
+//   `resolveDescriptorCapabilities()`.
+import type { DesignSourceCapabilities } from "./design-source-capabilities";
+import {
+  FUSION_DISCONNECTED_CAPABILITIES,
+  FUSION_CONNECTED_CAPABILITIES,
+  INLINE_DEFAULT_CAPABILITIES,
+  LOCALHOST_DEFAULT_CAPABILITIES,
+} from "./design-source-capabilities";
+
 export const DESIGN_SOURCE_TYPES = ["inline", "localhost", "fusion"] as const;
 
+/**
+ * Source-level provenance for a selected DOM element, populated from
+ * data attributes emitted by the connected app's build-time transform
+ * (e.g. @vitejs/plugin-react jsxDEV source maps or a Babel source plugin).
+ *
+ * - data-source-file / data-loc "file:line:col" → sourceFile
+ * - data-source-line / data-loc                 → line
+ * - data-source-column / data-loc               → column
+ * - data-component-name                         → component
+ *
+ * All fields are optional because cross-origin localhost iframes cannot be
+ * read (same-origin policy), and inline screens may not carry these attrs.
+ */
+export interface ElementProvenance {
+  sourceFile?: string;
+  line?: number;
+  column?: number;
+  component?: string;
+}
+
+export function parseDataLocProvenance(
+  dataLoc: string,
+): Pick<ElementProvenance, "sourceFile" | "line" | "column"> | null {
+  const lastColonIndex = dataLoc.lastIndexOf(":");
+  if (lastColonIndex < 0) return null;
+  const lastPart = dataLoc.slice(lastColonIndex + 1);
+  if (!/^\d+$/.test(lastPart)) return null;
+
+  const beforeLastPart = dataLoc.slice(0, lastColonIndex);
+  const previousColonIndex = beforeLastPart.lastIndexOf(":");
+  const previousPart =
+    previousColonIndex >= 0 ? beforeLastPart.slice(previousColonIndex + 1) : "";
+  const hasColumn = /^\d+$/.test(previousPart);
+  const sourceFile = (
+    hasColumn ? beforeLastPart.slice(0, previousColonIndex) : beforeLastPart
+  ).trim();
+  const line = Number(hasColumn ? previousPart : lastPart);
+  const column = hasColumn ? Number(lastPart) : undefined;
+
+  if (!sourceFile || !Number.isFinite(line)) return null;
+  if (column !== undefined && !Number.isFinite(column)) return null;
+  return { sourceFile, line, column };
+}
+
 export type DesignSourceType = (typeof DESIGN_SOURCE_TYPES)[number];
 
 export const DESIGN_BRIDGE_OPERATIONS = [
@@ -22,6 +109,10 @@ export interface DesignBridgeCapability {
   reason?: string;
 }
 
+// Re-export `DesignSourceCapabilities` so callers that import from
+// `source-mode` continue to resolve the type without an extra import.
+export type { DesignSourceCapabilities };
+
 export interface LocalhostDesignRoute {
   id: string;
   path: string;
@@ -49,7 +140,25 @@ export interface LocalhostDesignConnectionConfig {
   bridgeUrl?: string;
   rootPath?: string;
   routeManifest: LocalhostDesignRouteManifest;
+  /**
+   * Low-level bridge operation capabilities (legacy shape).
+   *
+   * Kept for backward compatibility with existing persistence and consumers
+   * (`connect-localhost`, `list-localhost-connections`).  New code should read
+   * `sourceCapabilities` for the higher-level capability vocabulary that UI
+   * panels and agent actions gate on.
+   */
   capabilities: DesignBridgeCapability[];
+  /**
+   * High-level capability map for this connection (the preferred gate).
+   *
+   * Derived from and/or overrides `LOCALHOST_DEFAULT_CAPABILITIES`.  Absent
+   * means the caller should fall back to the tier defaults via
+   * `resolveDescriptorCapabilities()`.  Populated by the bridge handshake and
+   * persisted alongside the connection so capability checks remain correct
+   * across reconnects.
+   */
+  sourceCapabilities?: DesignSourceCapabilities;
   status: "connected" | "detected" | "manual" | "error";
   lastSeenAt?: string;
   createdAt?: string;
@@ -62,6 +171,14 @@ export interface InlineDesignSource {
   fileId?: string;
   filename?: string;
   revision?: string;
+  /**
+   * Optional proven capability set for this source.
+   *
+   * When present, UI panels and actions MUST read capabilities from here
+   * rather than inferring them from `sourceType`.  Absent means "use the
+   * tier defaults from `resolveDescriptorCapabilities()`".
+   */
+  capabilities?: DesignSourceCapabilities;
 }
 
 export interface LocalhostDesignSource {
@@ -72,6 +189,15 @@ export interface LocalhostDesignSource {
   url?: string;
   bridgeUrl?: string;
   revision?: string;
+  /**
+   * Optional proven capability set for this source.
+   *
+   * Populated after a successful bridge handshake; overrides the conservative
+   * `LOCALHOST_DEFAULT_CAPABILITIES` for capabilities the bridge has verified.
+   * Use `resolveDescriptorCapabilities(source)` to merge defaults with proven
+   * overrides.
+   */
+  capabilities?: DesignSourceCapabilities;
 }
 
 export interface FusionDesignSource {
@@ -80,6 +206,35 @@ export interface FusionDesignSource {
   url?: string;
   revision?: string;
   metadata?: Record<string, unknown>;
+  /**
+   * Whether Builder credentials are configured and a branch project is set for
+   * this fusion source.
+   *
+   * When `true`, `resolveDescriptorCapabilities()` returns
+   * `FUSION_CONNECTED_CAPABILITIES` (indexComponents + branch + deployPreview +
+   * deploy available; source writes still planned until bridge hardening).
+   *
+   * When `false` or absent, returns `FUSION_DISCONNECTED_CAPABILITIES`
+   * (preview-only — no real-app write or branch operations).
+   *
+   * Set this field after verifying Builder connection status via
+   * `resolveIsBuilderBranchingEnabled()` from `@agent-native/core/server`.
+   * Callers that need the capability map without a descriptor can use
+   * `resolveFusionCapabilities(connected)` from `capability-resolver.ts`.
+   */
+  connected?: boolean;
+  /**
+   * Optional proven capability set for this source.
+   *
+   * When present, UI panels and actions MUST read capabilities from here
+   * rather than inferring them from `sourceType` or `connected`.  Absent means
+   * "use the connection-aware tier defaults from
+   * `resolveDescriptorCapabilities()`".
+   *
+   * Populated once the Builder-hosted bridge has proven additional capabilities
+   * beyond the defaults (e.g. specific `writeFile` or `applyEdit` readiness).
+   */
+  capabilities?: DesignSourceCapabilities;
 }
 
 export type DesignSourceDescriptor =
@@ -244,3 +399,93 @@ export function titleFromRoutePath(path: string): string {
       .replace(/\b\w/g, (char) => char.toUpperCase()) || "Screen"
   );
 }
+
+/**
+ * Return the effective `DesignSourceCapabilities` for a source descriptor.
+ *
+ * **Preferred over reading `sourceType` directly.**  The function honours the
+ * three-level capability contract from DESIGN-STUDIO-PLAN.md §1.1:
+ *
+ * 1. If the descriptor already carries a proven `capabilities` map (populated
+ *    after a bridge handshake or capability verification), return that map.
+ * 2. For **fusion** sources, honour the `connected` flag on the descriptor:
+ *    - `connected === true` → `FUSION_CONNECTED_CAPABILITIES`: `indexComponents`,
+ *      `branch`, `deployPreview`, `deploy` are **available**; source writes
+ *      (`writeFile`, `writeTokens`, `writeMotion`) remain **planned** until
+ *      bridge hardening.
+ *    - `connected === false` / absent → `FUSION_DISCONNECTED_CAPABILITIES`:
+ *      preview-only; no real-app write or branch operations.
+ * 3. Otherwise fall back to the conservative tier defaults
+ *    (`INLINE_DEFAULT_CAPABILITIES` / `LOCALHOST_DEFAULT_CAPABILITIES`).
+ *
+ * Usage:
+ * ```ts
+ * import { resolveDescriptorCapabilities } from "./source-mode";
+ * import { hasCapability } from "./design-source-capabilities";
+ *
+ * const caps = resolveDescriptorCapabilities(source);
+ * if (hasCapability(caps, "branch")) { ... }
+ * ```
+ *
+ * To set the fusion connection state on a descriptor before resolving:
+ * ```ts
+ * import { resolveIsBuilderBranchingEnabled } from "@agent-native/core/server";
+ *
+ * const connected = await resolveIsBuilderBranchingEnabled();
+ * const source: FusionDesignSource = { ...existing, connected };
+ * const caps = resolveDescriptorCapabilities(source);
+ * ```
+ *
+ * To record proven capabilities discovered after a bridge handshake, spread
+ * the defaults and override the specific entries before storing on the
+ * descriptor:
+ * ```ts
+ * import { resolveFusionCapabilities, available } from "./capability-resolver";
+ *
+ * const caps = {
+ *   ...resolveFusionCapabilities(true),
+ *   writeFile: available("Bridge write hardening complete"),
+ * };
+ * const source: FusionDesignSource = { ...existing, capabilities: caps };
+ * ```
+ *
+ * Note: this module cannot import from `capability-resolver.ts` at runtime
+ * because `capability-resolver.ts` already imports `DesignSourceType` from
+ * here (circular).  The helper is therefore implemented inline using the same
+ * canonical default maps re-imported from `design-source-capabilities.ts`.
+ */
+export function resolveDescriptorCapabilities(
+  source: DesignSourceDescriptor,
+): DesignSourceCapabilities {
+  // If the descriptor carries a proven capability map, use it as-is.
+  // (A proven map overrides both sourceType and connected state.)
+  if (source.capabilities) return source.capabilities;
+
+  switch (source.sourceType) {
+    case "inline":
+      return INLINE_DEFAULT_CAPABILITIES;
+    case "localhost":
+      return LOCALHOST_DEFAULT_CAPABILITIES;
+    case "fusion":
+      // Honour the connection status flag on the descriptor.
+      //
+      // - `connected === true` → `FUSION_CONNECTED_CAPABILITIES`:
+      //     indexComponents, branch, deployPreview, deploy are available;
+      //     source writes (writeFile/writeTokens/writeMotion) remain planned.
+      // - `connected === false` or absent → `FUSION_DISCONNECTED_CAPABILITIES`:
+      //     preview-only; no real-app write or branch operations.
+      //
+      // Callers should set `source.connected` after verifying Builder status
+      // via `resolveIsBuilderBranchingEnabled()`.  When the status is unknown
+      // (e.g. a stale descriptor without the field), the conservative
+      // disconnected default is returned.
+      return source.connected
+        ? FUSION_CONNECTED_CAPABILITIES
+        : FUSION_DISCONNECTED_CAPABILITIES;
+    default: {
+      const _exhaustive: never = source;
+      void _exhaustive;
+      return INLINE_DEFAULT_CAPABILITIES;
+    }
+  }
+}

package/corpus/templates/plan/app/components/plan/CanvasArea.tsx

@@ -14,6 +14,7 @@ import { IconMinus, IconPlus } from "@tabler/icons-react";
 import {
   useCallback,
   useEffect,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState,
@@ -29,6 +30,9 @@ import { Textarea } from "@/components/ui/textarea";
 
 import { Wireframe, type DesignElementSelection } from "./wireframe/Wireframe";
 
+const useIsomorphicLayoutEffect =
+  typeof window === "undefined" ? useEffect : useLayoutEffect;
+
 /* -------------------------------------------------------------------------- */
 /* Pan / zoom feel — recovered from the on-main hardcoded renderer            */
 /* (server/ui-plan-html.ts UI_PLAN_JS) + claude.ai/designs design-canvas.jsx. */
@@ -313,7 +317,7 @@ export function CanvasArea({
     canvas.viewport?.pan?.x ?? ""
   }:${canvas.viewport?.pan?.y ?? ""}`;
   const lastAppliedSavedViewportKeyRef = useRef<string | null>(null);
-  useEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     if (!hasSavedViewport) return;
     if (lastAppliedSavedViewportKeyRef.current === savedViewportKey) return;
     lastAppliedSavedViewportKeyRef.current = savedViewportKey;
@@ -344,7 +348,7 @@ export function CanvasArea({
   boardRef.current = board;
 
   const lastAutoFitKeyRef = useRef<string | null>(null);
-  useEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     if (hasSavedViewport) return;
     if (lastAutoFitKeyRef.current === frameLayoutKey) return;
     const element = viewportRef.current;

package/corpus/templates/plan/changelog/2026-06-29-plan-canvases-open-without-an-initial-pan-and-zoom-flicker.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-06-29
+---
+
+Plan canvases open without an initial pan-and-zoom flicker while the first view settles.

package/dist/cli/design-connect.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"design-connect.d.ts","sourceRoot":"","sources":["../../src/cli/design-connect.ts"],"names":[],"mappings":"AAEA,OAAa,EAEX,KAAK,MAAM,EAEZ,MAAM,WAAW,CAAC;AAcnB,QAAA,MAAM,iBAAiB,YACrB,QAAQ,EACR,mBAAmB,EACnB,UAAU,EACV,WAAW,EACX,WAAW,EACX,iBAAiB,EACjB,cAAc,CACN,CAAC;AAEX,KAAK,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,cAAc,GAAG,MAAM,GAAG,QAAQ,CAAC;CAChD;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,CAAC,CAAC;IACX,MAAM,EAAE,6BAA6B,CAAC;IACtC,UAAU,EAAE,WAAW,CAAC;IACxB,SAAS,EAAE,IAAI,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oBAAoB,EAAE,OAAO,CAAC;IAC9B,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,KAAK,CAAC;QAClB,SAAS,EAAE,eAAe,CAAC;QAC3B,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,UAAU,CAAC;QAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,qBAAqB,CAAC;CACjC;AAyBD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,iBAAiB,CAwDxE;AAiED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,EAAE,CA+CvE;AA6DD,wBAAsB,4BAA4B,CAChD,OAAO,GAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAC3D,OAAO,CAAC,qBAAqB,CAAC,CA0ChC;AAiBD,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,qBAAqB,GAC9B,OAAO,CAAC,mBAAmB,CAAC,CAwC9B;AAgBD,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,mBA0C7C"}
+{"version":3,"file":"design-connect.d.ts","sourceRoot":"","sources":["../../src/cli/design-connect.ts"],"names":[],"mappings":"AAEA,OAAa,EAEX,KAAK,MAAM,EAEZ,MAAM,WAAW,CAAC;AAcnB,QAAA,MAAM,iBAAiB,YACrB,QAAQ,EACR,mBAAmB,EACnB,UAAU,EACV,WAAW,EACX,WAAW,EACX,iBAAiB,EACjB,cAAc,CACN,CAAC;AAEX,KAAK,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,cAAc,GAAG,MAAM,GAAG,QAAQ,CAAC;CAChD;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,CAAC,CAAC;IACX,MAAM,EAAE,6BAA6B,CAAC;IACtC,UAAU,EAAE,WAAW,CAAC;IACxB,SAAS,EAAE,IAAI,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oBAAoB,EAAE,OAAO,CAAC;IAC9B,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,KAAK,CAAC;QAClB,SAAS,EAAE,eAAe,CAAC;QAC3B,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,UAAU,CAAC;QAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,qBAAqB,CAAC;CACjC;AAyBD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,iBAAiB,CAwDxE;AAiED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,EAAE,CA+CvE;AA6DD,wBAAsB,4BAA4B,CAChD,OAAO,GAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAC3D,OAAO,CAAC,qBAAqB,CAAC,CAiDhC;AAiBD,wBAAsB,wBAAwB,CAC5C,QAAQ,EAAE,qBAAqB,GAC9B,OAAO,CAAC,mBAAmB,CAAC,CAwC9B;AAmCD,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,mBA0C7C"}