@agent-native/core 0.114.1 → 0.114.3

package/corpus/templates/design/.agents/skills/agent-native-toolkit/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: agent-native-toolkit
+description: >-
+  Inventory and ownership rules for shared Agent Native workspace UI. Use
+  before building app chrome, settings, navigation, sharing, collaboration,
+  setup, history, comments, chat rails, agent UX, or repeated workspace behavior.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Agent-Native Toolkit
+
+Use this skill when deciding whether app chrome, settings, collaboration,
+sharing, navigation, organization, setup, history, comments, or agent UX should
+be built app-locally or moved into reusable framework/toolkit pieces.
+
+## Core Rule
+
+Apps own domain models, domain actions, and product-specific workflows. The
+framework and `@agent-native/toolkit` own repeated workspace behavior users
+expect to work the same everywhere.
+
+Move behavior into shared toolkit primitives when it is:
+
+- workspace-wide, such as settings, nav, search, org membership, or setup
+- agent-visible, such as context, actions, run progress, or proof-of-done
+- governed, such as secrets, permissions, sharing, audit, or billing
+- repeated by two or more apps
+- not tied to one domain model
+
+Keep behavior app-local when the abstraction would hide important domain
+language or make a simple app-specific workflow harder to understand.
+
+## Discover Before Building
+
+Before creating an app-local version of repeated workspace or agent UI:
+
+1. Check the reusable kits below and the installed package documentation.
+2. Search installed public components and source with `docs-search` and
+   `source-search`.
+3. Run `agent-native eject --list` to see the version-matched units published
+   by the packages installed in this app.
+4. Read `customizing-agent-native` and configure, compose, or eject the
+   smallest unit instead of recreating shared behavior from memory.
+
+Use public package exports at runtime. Published source and ejection manifests
+are discovery and ownership-transfer mechanisms, not private runtime APIs.
+
+## Settings Direction
+
+Durable settings belong in the Settings app or a registered settings route. The
+agent sidebar should not become a second settings app. It can show contextual
+quick controls and deep links such as:
+
+- `/settings/ai`
+- `/settings/connections`
+- `/settings/secrets`
+- `/settings/usage`
+- `/settings/apps/:appId`
+
+When adding a new API key, OAuth grant, provider connection, model selector, app
+preference, notification preference, or usage/billing surface, register it as a
+settings tab or app settings panel first. Only add sidebar UI when it is needed
+in the moment of agent use.
+
+## Reusable Kits
+
+- **Settings kit**: a searchable settings page with account, workspace, AI
+  models, LLM keys, connections, secrets, usage, notifications, changelog, and
+  app-specific panels. Search is on by default; register a `SettingsSearchEntry`
+  per control so users find settings by name across tabs.
+- **Collaboration kit**: Yjs docs, presence, agent presence, live cursors,
+  remote selections, recent edit highlights, real-time sync indicators, and
+  undo/redo grouping.
+- **Sharing kit**: private/workspace/org/public-link access, invites, roles,
+  expirations, agent-readable links, and resource registration.
+- **Navigation and command kit**: app shell, side nav, breadcrumbs, app switcher,
+  command palette entries, recent resources, pinned resources, and global search.
+- **Organization kit**: folders, tags, favorites, archive, trash, ownership,
+  membership, and common resource metadata.
+- **Setup and connections kit**: declarative setup requirements, model readiness,
+  missing-secret states, OAuth grants, and provider connection health.
+- **Agent UX kit**: sidebar, composer, staged context, mentions, voice, human
+  approval, generative UI, progress, and screen-state exposure.
+- **Chat history kit**: presentational chat lists and recent-chat rails belong
+  in Toolkit; Core keeps thread persistence, agent execution, transport, and
+  page-to-sidebar handoff. Apps inject routing, labels, and domain actions.
+- **Agent page kit**: the full-page `/agent` surface (`AgentTabsPage` from
+  `@agent-native/core/client`) with Context, Files, Connections, Jobs, and
+  Access tabs plus a Personal/Organization scope toggle. The canonical home
+  for context transparency, MCP servers, A2A remote agents, recurring
+  jobs/automations, and external-client connect flows. See the `agent-page`
+  skill.
+- **History and recovery kit**: audit log, activity feed, version history,
+  checkpoints, undo, redo, restore, and proof-of-done.
+- **Comments and review kit**: anchored comments, pins, mentions, review
+  requests, resolved threads, agent follow-up tasks, and notifications.
+- **Workflow and observability kit**: notifications, approvals, scheduled work,
+  background runs, recurring jobs, traces, evals, feedback, and run timelines.
+
+## Implementation Checklist
+
+When adding or refactoring one of these areas:
+
+1. Search existing framework and template code for duplicated UI or actions.
+2. Decide the shared contract: data shape, action API, React component/hook, and
+   app adapter points.
+3. Keep shared data provider-agnostic and scoped by auth/sharing rules.
+4. Expose the same capability to the UI and agent through actions or documented
+   client helpers.
+5. Register app-specific labels, routes, resource adapters, and settings panels
+   instead of hardcoding app names in core UI.
+6. Update docs and relevant skills so future apps discover the shared path.
+7. Keep the component easy to adopt piecemeal: expose props/slots first and
+   ship readable source plus a complete ejection unit so apps can take ownership
+   of the smallest feature when needed. See `customizing-agent-native` for the
+   configure → compose → eject → propose seam ladder.
+
+## Related Skills
+
+Read these alongside this skill when the work touches the specific area:
+
+- `sharing`
+- `real-time-collab`
+- `real-time-sync`
+- `client-side-routing`
+- `context-awareness`
+- `onboarding`
+- `secrets`
+- `audit-log`
+- `observability`
+- `frontend-design`

package/corpus/templates/design/.agents/skills/feature-flags/SKILL.md

@@ -37,7 +37,7 @@ Keep definitions in a shared TypeScript module so server and client code use the
 same stable key. Flags are boolean and default-off.
 
 ```ts
-import { defineFeatureFlag } from "@agent-native/core/feature-flags";
+import { defineFeatureFlag } from "@agent-native/core/feature-flags/registry";
 
 export const FULL_APP_BUILDING = defineFeatureFlag({
   key: "full-app-building",

package/corpus/templates/design/AGENTS.md

@@ -7,6 +7,11 @@ through actions against the shared SQL state.
 Keep this file essential. Detailed generation, design-system, export, and UI
 patterns live in `.agents/skills/`.
 
+Before building common workspace or agent UI, read `agent-native-toolkit` to
+inventory existing public kits and installed package seams. Use
+`customizing-agent-native` for the configure → compose → eject → propose seam
+ladder.
+
 ## Core Rules
 
 - Store large file/blob payloads in configured file/blob storage, not SQL: no

package/corpus/templates/design/actions/update-file.ts

@@ -169,7 +169,16 @@ export default defineAction({
       .limit(1);
 
     if (!file) {
-      throw new Error(`File not found: ${id}`);
+      // Terminal (not transient): the row is gone or out of access scope, so a
+      // retry can never succeed. Mark it 404 so the client save-outbox drops the
+      // entry instead of retrying forever (which turns one orphaned/deleted
+      // screen into an update-file 500 storm — see design-save-outbox
+      // isTerminalSaveError).
+      const notFound = new Error(`File not found: ${id}`) as Error & {
+        status?: number;
+      };
+      notFound.status = 404;
+      throw notFound;
     }
 
     await assertAccess("design", file.designId, "editor");

package/corpus/templates/design/app/components/design/DesignCanvas.tsx

@@ -109,6 +109,7 @@ import {
   schedulePendingTextEditActivation,
 } from "./design-canvas/pending-text-edit";
 import { DeviceFrame } from "./DeviceFrame";
+import { dndHostLog } from "./dnd-debug";
 import { shapeClosingHandles } from "./multi-screen/draft-primitives";
 import type {
   ElementInfo,
@@ -304,6 +305,15 @@ ${editorChromeBridgeScript}
 </script>
 `;
 
+/**
+ * Master switch for the Figma-parity live-reflow drag (hysteresis-stabilized
+ * targeting + size guard in Phase 0; transform lift/follow, live sibling
+ * reflow, and exact absolute commit in Phase 1). Flip to `true` to try the new
+ * drag feel; flip back to `false` for the previous behavior without a revert.
+ * Baked into the injected bridge as `__LIVE_REFLOW_ENABLED__`.
+ */
+const LIVE_REFLOW_ENABLED = true;
+
 interface DesignCanvasProps {
   content: string;
   contentKey?: string;
@@ -931,6 +941,10 @@ function buildEditorChromeBridgeScript(args: {
         "__RUNTIME_LAYER_SNAPSHOT_ENABLED__",
         args.runtimeLayerSnapshotEnabled ? "true" : "false",
       )
+      .replace(
+        "__LIVE_REFLOW_ENABLED__",
+        LIVE_REFLOW_ENABLED ? "true" : "false",
+      )
   );
 }
 
@@ -2106,7 +2120,11 @@ export function DesignCanvas({
             "__DESIGN_CANVAS_CONTENT_OFFSET_Y__",
             String(Math.round(embeddedFrame?.contentOffsetY ?? 0)),
           )
-          .replace("__RUNTIME_LAYER_SNAPSHOT_ENABLED__", "false");
+          .replace("__RUNTIME_LAYER_SNAPSHOT_ENABLED__", "false")
+          .replace(
+            "__LIVE_REFLOW_ENABLED__",
+            LIVE_REFLOW_ENABLED ? "true" : "false",
+          );
     // ALWAYS injected (like the other always-on bridges above) so
     // MultiScreenCanvas's cross-screen drag hit-testing
     // (agent-native:hit-test / agent-native:hit-test-result) resolves an
@@ -2479,6 +2497,12 @@ export function DesignCanvas({
         const selector = String(e.data.selector || "");
         const anchorSelector = String(e.data.anchorSelector || "");
         const placement = String(e.data.placement || "after");
+        dndHostLog("recv:structure-change", {
+          selector,
+          anchorSelector,
+          placement,
+          dropMode: e.data.dropMode,
+        });
         const requestId =
           typeof e.data.requestId === "string" ? e.data.requestId : undefined;
         const sourceId =
@@ -2546,6 +2570,11 @@ export function DesignCanvas({
                 : undefined,
             },
           );
+          dndHostLog("persist:result", {
+            applied,
+            requestId,
+            willAck: Boolean(requestId) && applied !== "pending",
+          });
           if (requestId && applied !== "pending") {
             iframeRef.current?.contentWindow?.postMessage(
               {

package/corpus/templates/design/app/components/design/MultiScreenCanvas.tsx

@@ -84,6 +84,7 @@ import {
 } from "./canvas-primitive-style";
 import { appendHitTestResponder } from "./design-canvas/hit-test";
 import { DesignCanvas } from "./DesignCanvas";
+import { dndHostLog } from "./dnd-debug";
 import {
   gradientToCss,
   parseGradientCss,
@@ -154,6 +155,10 @@ const TRANSFORM_BADGE_MAX_WIDTH = 180;
 // (frame z-order is a small per-design integer) while staying well under the
 // reserved resize-handle stacking range (999_999+).
 const TOP_SCREEN_Z_BOOST = 100_000;
+// A live draw preview must paint above every screen — including the
+// TOP_SCREEN_Z_BOOSTed active one — or its outline hides behind the opaque
+// screen iframe until commit. Stays below the resize-handle range (999_999+).
+const DRAFT_PREVIEW_Z = TOP_SCREEN_Z_BOOST + 50_000;
 const EMPTY_SELECTED_LAYER_SELECTOR_GROUPS_BY_SCREEN: Record<
   string,
   string[][]
@@ -2269,6 +2274,13 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
         return;
       }
 
+      if (msg.phase !== "move") {
+        dndHostLog("overview:cross-screen", {
+          phase: msg.phase,
+          source: sourceScreenId,
+          selector: msg.selector,
+        });
+      }
       if (msg.phase === "start") {
         setCrossScreenSourceIsBoard(sourceScreenId === boardFileId);
         crossScreenDragMsgRef.current = {
@@ -5167,6 +5179,7 @@ export const MultiScreenCanvas = memo(function MultiScreenCanvas({
             frameGeometryWithOverrides(after, state.originFrames),
             after,
           );
+          dndHostLog("overview:frame-commit", { ids: state.targetIds });
           suppressNextPick.current = true;
         }
         finishDrag();
@@ -8156,7 +8169,7 @@ function DraftPrimitiveLayer({
         ...frameStyleLeftTop(geometry),
         width: geometry.width,
         height: geometry.height,
-        zIndex: geometry.z ?? 40,
+        zIndex: preview ? DRAFT_PREVIEW_Z : (geometry.z ?? 40),
         transform: geometry.rotation
           ? `rotate(${geometry.rotation}deg)`
           : undefined,