@tuongaz/seeflow 0.1.31 → 0.1.40

package/src/registry.ts

@@ -7,7 +7,7 @@ export interface FlowEntry {
   slug: string;
   name: string;
   repoPath: string;
-  architecturePath: string;
+  flowPath: string;
   lastModified: number;
   valid: boolean;
 }
@@ -15,7 +15,7 @@ export interface FlowEntry {
 export interface RegisterInput {
   name: string;
   repoPath: string;
-  architecturePath: string;
+  flowPath: string;
   valid?: boolean;
   lastModified?: number;
 }
@@ -25,10 +25,7 @@ export interface Registry {
   getById(id: string): FlowEntry | undefined;
   getBySlug(slug: string): FlowEntry | undefined;
   getByRepoPath(repoPath: string): FlowEntry | undefined;
-  getByRepoPathAndArchitecturePath(
-    repoPath: string,
-    architecturePath: string,
-  ): FlowEntry | undefined;
+  getByRepoPathAndFlowPath(repoPath: string, flowPath: string): FlowEntry | undefined;
   upsert(input: RegisterInput): FlowEntry;
   remove(id: string): boolean;
 }
@@ -60,7 +57,7 @@ export function createRegistry(options: { path?: string } = {}): Registry {
             typeof e.slug === 'string' &&
             typeof e.repoPath === 'string'
           ) {
-            if (typeof e.architecturePath !== 'string') {
+            if (typeof e.flowPath !== 'string') {
               console.warn(
                 `[registry] ignoring legacy entry ${e.id} (${e.slug}) — pre-split format, please re-register`,
               );
@@ -87,12 +84,9 @@ export function createRegistry(options: { path?: string } = {}): Registry {
     return undefined;
   };
 
-  const findByRepoPathAndArchitecturePath = (
-    repoPath: string,
-    architecturePath: string,
-  ): FlowEntry | undefined => {
+  const findByRepoPathAndFlowPath = (repoPath: string, flowPath: string): FlowEntry | undefined => {
     for (const e of entries.values()) {
-      if (e.repoPath === repoPath && e.architecturePath === architecturePath) return e;
+      if (e.repoPath === repoPath && e.flowPath === flowPath) return e;
     }
     return undefined;
   };
@@ -110,16 +104,16 @@ export function createRegistry(options: { path?: string } = {}): Registry {
     getById: (id) => entries.get(id),
     getBySlug: (slug) => [...entries.values()].find((e) => e.slug === slug),
     getByRepoPath: findByRepoPath,
-    getByRepoPathAndArchitecturePath: findByRepoPathAndArchitecturePath,
+    getByRepoPathAndFlowPath: findByRepoPathAndFlowPath,
     upsert(input) {
       const lastModified = input.lastModified ?? Date.now();
       const valid = input.valid ?? true;
-      const existing = findByRepoPathAndArchitecturePath(input.repoPath, input.architecturePath);
+      const existing = findByRepoPathAndFlowPath(input.repoPath, input.flowPath);
       if (existing) {
         const updated: FlowEntry = {
           ...existing,
           name: input.name,
-          architecturePath: input.architecturePath,
+          flowPath: input.flowPath,
           lastModified,
           valid,
         };
@@ -134,7 +128,7 @@ export function createRegistry(options: { path?: string } = {}): Registry {
         slug,
         name: input.name,
         repoPath: input.repoPath,
-        architecturePath: input.architecturePath,
+        flowPath: input.flowPath,
         lastModified,
         valid,
       };

package/src/schema.ts

@@ -27,10 +27,6 @@ export const ColorTokenSchema = z.enum([
 
 // Visual fields shared by every node type (functional + decorative). All
 // optional — existing demo files predate them and must continue to parse.
-// US-019: `locked` freezes a node in place (no drag / resize / delete) and
-// renders a lock badge on its top-right corner. Absent → unlocked default.
-// Mirrored explicitly into IconNodeDataSchema below
-// since that variant doesn't spread this base shape.
 const NodeVisualBaseShape = {
   width: z.number().positive().optional(),
   height: z.number().positive().optional(),
@@ -41,7 +37,6 @@ const NodeVisualBaseShape = {
   fontSize: z.number().positive().optional(),
   textColor: ColorTokenSchema.optional(),
   cornerRadius: z.number().min(0).optional(),
-  locked: z.boolean().optional(),
 };
 
 // Consolidated three-field metadata shared by every node variant. `description`
@@ -267,9 +262,6 @@ const IconNodeDataSchema = z.object({
   // `alt` (screen-reader text). Absent / empty → no caption rendered and the
   // node's bounding box is byte-identical to the unlabeled layout.
   name: z.string().optional(),
-  // US-019: lock state mirror of NodeVisualBaseShape.locked. IconNode does
-  // not spread the visual base so we declare it here explicitly.
-  locked: z.boolean().optional(),
   ...NodeDescriptionBaseShape,
 });
 
@@ -396,7 +388,7 @@ const ConnectorSchema = z.discriminatedUnion('kind', [
   DefaultConnectorSchema,
 ]);
 
-export const FlowSchema = z
+export const ResolvedFlowSchema = z
   .object({
     version: z.literal(2),
     name: z.string().min(1),
@@ -408,9 +400,9 @@ export const FlowSchema = z
     // script (US-008), so the script sees no stragglers.
     resetAction: ResetActionSchema.optional(),
   })
-  .superRefine((flow, ctx) => {
-    const nodeIds = new Set(flow.nodes.map((n) => n.id));
-    flow.connectors.forEach((c, idx) => {
+  .superRefine((resolved, ctx) => {
+    const nodeIds = new Set(resolved.nodes.map((n) => n.id));
+    resolved.connectors.forEach((c, idx) => {
       if (!nodeIds.has(c.source)) {
         ctx.addIssue({
           code: z.ZodIssueCode.custom,
@@ -428,8 +420,8 @@ export const FlowSchema = z
     });
   });
 
-export type Flow = z.infer<typeof FlowSchema>;
-export type FlowNode = z.infer<typeof NodeSchema>;
+export type ResolvedFlow = z.infer<typeof ResolvedFlowSchema>;
+export type ResolvedFlowNode = z.infer<typeof NodeSchema>;
 export type ShapeNode = z.infer<typeof ShapeNodeSchema>;
 export type ImageNode = z.infer<typeof ImageNodeSchema>;
 export type IconNode = z.infer<typeof IconNodeSchema>;
@@ -454,11 +446,11 @@ export type ResetAction = z.infer<typeof ResetActionSchema>;
 export type StateSource = z.infer<typeof StateSourceSchema>;
 
 // =============================================================================
-// Architecture schema — pure semantic data, every visual/layout field stripped.
-// What lives on disk in <project>/.seeflow/architecture.json after the split.
+// Flow schema — pure semantic data, every visual/layout field stripped.
+// What lives on disk in <project>/.seeflow/flow.json after the split.
 // =============================================================================
 
-const ArchitectureNodeDataBaseShape = {
+const FlowNodeDataBaseShape = {
   name: z.string().min(1),
   kind: z.string().min(1),
   stateSource: StateSourceSchema,
@@ -467,23 +459,23 @@ const ArchitectureNodeDataBaseShape = {
   ...NodeDescriptionBaseShape,
 };
 
-const ArchitecturePlayNodeDataSchema = z
+const FlowPlayNodeDataSchema = z
   .object({
-    ...ArchitectureNodeDataBaseShape,
+    ...FlowNodeDataBaseShape,
     playAction: PlayActionSchema,
     statusAction: StatusActionSchema.optional(),
   })
   .strict();
 
-const ArchitectureStateNodeDataSchema = z
+const FlowStateNodeDataSchema = z
   .object({
-    ...ArchitectureNodeDataBaseShape,
+    ...FlowNodeDataBaseShape,
     playAction: PlayActionSchema.optional(),
     statusAction: StatusActionSchema.optional(),
   })
   .strict();
 
-const ArchitectureShapeNodeDataSchema = z
+const FlowShapeNodeDataSchema = z
   .object({
     shape: ShapeKindSchema,
     name: z.string().optional(),
@@ -491,7 +483,7 @@ const ArchitectureShapeNodeDataSchema = z
   })
   .strict();
 
-const ArchitectureImageNodeDataSchema = z
+const FlowImageNodeDataSchema = z
   .object({
     path: z.string().min(1).refine(isCleanRelativePath, {
       message: 'path must be a relative path under .seeflow/ (no absolute / traversal)',
@@ -501,7 +493,7 @@ const ArchitectureImageNodeDataSchema = z
   })
   .strict();
 
-const ArchitectureIconNodeDataSchema = z
+const FlowIconNodeDataSchema = z
   .object({
     icon: z.string().min(1),
     alt: z.string().optional(),
@@ -510,7 +502,7 @@ const ArchitectureIconNodeDataSchema = z
   })
   .strict();
 
-const ArchitectureHtmlNodeDataSchema = z
+const FlowHtmlNodeDataSchema = z
   .object({
     htmlPath: z.string().min(1).refine(isCleanRelativePath, {
       message: 'htmlPath must be a relative path under .seeflow/ (no absolute / traversal)',
@@ -521,66 +513,66 @@ const ArchitectureHtmlNodeDataSchema = z
   })
   .strict();
 
-const ArchitectureNodeBaseShape = {
+const FlowNodeBaseShape = {
   id: z.string().min(1),
 };
 
-const ArchitectureNodeSchema = z.discriminatedUnion('type', [
+const FlowNodeSchema = z.discriminatedUnion('type', [
   z
     .object({
-      ...ArchitectureNodeBaseShape,
+      ...FlowNodeBaseShape,
       type: z.literal('playNode'),
-      data: ArchitecturePlayNodeDataSchema,
+      data: FlowPlayNodeDataSchema,
     })
     .strict(),
   z
     .object({
-      ...ArchitectureNodeBaseShape,
+      ...FlowNodeBaseShape,
       type: z.literal('stateNode'),
-      data: ArchitectureStateNodeDataSchema,
+      data: FlowStateNodeDataSchema,
     })
     .strict(),
   z
     .object({
-      ...ArchitectureNodeBaseShape,
+      ...FlowNodeBaseShape,
       type: z.literal('shapeNode'),
-      data: ArchitectureShapeNodeDataSchema,
+      data: FlowShapeNodeDataSchema,
     })
     .strict(),
   z
     .object({
-      ...ArchitectureNodeBaseShape,
+      ...FlowNodeBaseShape,
       type: z.literal('imageNode'),
-      data: ArchitectureImageNodeDataSchema,
+      data: FlowImageNodeDataSchema,
     })
     .strict(),
   z
     .object({
-      ...ArchitectureNodeBaseShape,
+      ...FlowNodeBaseShape,
       type: z.literal('iconNode'),
-      data: ArchitectureIconNodeDataSchema,
+      data: FlowIconNodeDataSchema,
     })
     .strict(),
   z
     .object({
-      ...ArchitectureNodeBaseShape,
+      ...FlowNodeBaseShape,
       type: z.literal('htmlNode'),
-      data: ArchitectureHtmlNodeDataSchema,
+      data: FlowHtmlNodeDataSchema,
     })
     .strict(),
 ]);
 
-const ArchitectureConnectorBaseShape = {
+const FlowConnectorBaseShape = {
   id: z.string().min(1),
   source: z.string().min(1),
   target: z.string().min(1),
   label: z.string().optional(),
 };
 
-const ArchitectureConnectorSchema = z.discriminatedUnion('kind', [
+const FlowConnectorSchema = z.discriminatedUnion('kind', [
   z
     .object({
-      ...ArchitectureConnectorBaseShape,
+      ...FlowConnectorBaseShape,
       kind: z.literal('http'),
       method: HttpMethodSchema.optional(),
       url: z.string().min(1).optional(),
@@ -588,38 +580,38 @@ const ArchitectureConnectorSchema = z.discriminatedUnion('kind', [
     .strict(),
   z
     .object({
-      ...ArchitectureConnectorBaseShape,
+      ...FlowConnectorBaseShape,
       kind: z.literal('event'),
       eventName: z.string().min(1),
     })
     .strict(),
   z
     .object({
-      ...ArchitectureConnectorBaseShape,
+      ...FlowConnectorBaseShape,
       kind: z.literal('queue'),
       queueName: z.string().min(1),
     })
     .strict(),
   z
     .object({
-      ...ArchitectureConnectorBaseShape,
+      ...FlowConnectorBaseShape,
       kind: z.literal('default'),
     })
     .strict(),
 ]);
 
-export const ArchitectureSchema = z
+export const FlowSchema = z
   .object({
     version: z.literal(2),
     name: z.string().min(1),
     resetAction: ResetActionSchema.optional(),
-    nodes: z.array(ArchitectureNodeSchema),
-    connectors: z.array(ArchitectureConnectorSchema),
+    nodes: z.array(FlowNodeSchema),
+    connectors: z.array(FlowConnectorSchema),
   })
   .strict()
-  .superRefine((arch, ctx) => {
-    const ids = new Set(arch.nodes.map((n) => n.id));
-    arch.connectors.forEach((c, idx) => {
+  .superRefine((flow, ctx) => {
+    const ids = new Set(flow.nodes.map((n) => n.id));
+    flow.connectors.forEach((c, idx) => {
       if (!ids.has(c.source)) {
         ctx.addIssue({
           code: z.ZodIssueCode.custom,
@@ -637,9 +629,9 @@ export const ArchitectureSchema = z
     });
   });
 
-export type Architecture = z.infer<typeof ArchitectureSchema>;
-export type ArchitectureNode = z.infer<typeof ArchitectureNodeSchema>;
-export type ArchitectureConnector = z.infer<typeof ArchitectureConnectorSchema>;
+export type Flow = z.infer<typeof FlowSchema>;
+export type FlowNode = z.infer<typeof FlowNodeSchema>;
+export type FlowConnector = z.infer<typeof FlowConnectorSchema>;
 
 // =============================================================================
 // Style schema — keyed map of presentation overrides, side-table by id.
@@ -658,7 +650,6 @@ const NodeStyleSchema = z
     fontSize: z.number().positive().optional(),
     textColor: ColorTokenSchema.optional(),
     cornerRadius: z.number().min(0).optional(),
-    locked: z.boolean().optional(),
     // imageNode-specific
     borderWidth: z.number().min(1).max(8).optional(),
     // iconNode-specific

package/src/status-runner.ts

@@ -25,7 +25,7 @@ import { isAbsolute, join, resolve, sep } from 'node:path';
 import type { EventBus } from './events.ts';
 import { type ProcessSpawner, type SpawnHandle, defaultProcessSpawner } from './process-spawner.ts';
 import type { FlowEntry, Registry } from './registry.ts';
-import { type Flow, type StatusAction, StatusReportSchema } from './schema.ts';
+import { type ResolvedFlow, type StatusAction, StatusReportSchema } from './schema.ts';
 import { readMergedFlow } from './watcher.ts';
 
 export interface StatusRunner {
@@ -141,10 +141,10 @@ function truncate(s: string, n: number): string {
   return s.length > n ? `${s.slice(0, n)}…` : s;
 }
 
-async function loadDemo(entry: FlowEntry): Promise<Flow | undefined> {
-  const fullPath = isAbsolute(entry.architecturePath)
-    ? entry.architecturePath
-    : join(entry.repoPath, entry.architecturePath);
+async function loadDemo(entry: FlowEntry): Promise<ResolvedFlow | undefined> {
+  const fullPath = isAbsolute(entry.flowPath)
+    ? entry.flowPath
+    : join(entry.repoPath, entry.flowPath);
   if (!existsSync(fullPath)) return undefined;
   const result = readMergedFlow(fullPath);
   return result.flow ?? undefined;
@@ -155,7 +155,7 @@ interface StatusNode {
   action: StatusAction;
 }
 
-function collectStatusNodes(demo: Flow): StatusNode[] {
+function collectStatusNodes(demo: ResolvedFlow): StatusNode[] {
   const out: StatusNode[] = [];
   for (const node of demo.nodes) {
     if (node.type !== 'playNode' && node.type !== 'stateNode') continue;

package/src/watcher.ts

@@ -1,16 +1,31 @@
+import { createHash } from 'node:crypto';
 import { type FSWatcher, existsSync, readFileSync, watch } from 'node:fs';
 import { basename, dirname, isAbsolute, join } from 'node:path';
 import type { EventBus } from './events.ts';
 import { resolveFileRefs } from './file-ref.ts';
-import { mergeArchitectureAndStyle } from './merge.ts';
+import { mergeFlowAndStyle } from './merge.ts';
 import type { Registry } from './registry.ts';
-import { type Architecture, ArchitectureSchema, type Flow, StyleSchema } from './schema.ts';
+import { type Flow, FlowSchema, type ResolvedFlow, StyleSchema } from './schema.ts';
 
 const DEFAULT_DEBOUNCE_MS = 100;
 
+/** Max recent self-write hashes retained per flow for own-echo suppression. */
+const WRITTEN_HASH_RING_SIZE = 4;
+
+const sha256Hex = (s: string): string => createHash('sha256').update(s).digest('hex');
+
+/**
+ * Canonical "what's on disk for this flow" string used for own-write
+ * dedupe. Combines flow.json and style.json bytes so a self-write that
+ * touches either file is recognized; a NUL separator keeps the boundary
+ * unambiguous. `styleContent` is `''` when style.json doesn't exist.
+ */
+const combinedContent = (flowContent: string, styleContent: string): string =>
+  `${flowContent}\0${styleContent}`;
+
 export interface FlowSnapshot {
   /** Last successfully parsed flow, if we ever saw one. */
-  flow: Flow | null;
+  flow: ResolvedFlow | null;
   /** Result of the most recent parse attempt. */
   valid: boolean;
   /** Human-readable error from the most recent parse, when `valid: false`. */
@@ -41,6 +56,19 @@ export interface FlowWatcher {
   closeAll(): void;
   /** Force a reparse synchronously. Useful for tests + initial load. */
   reparse(flowId: string): FlowSnapshot | null;
+  /**
+   * Record a snapshot that the server just wrote and broadcast flow:reload
+   * directly from it. Stores the file-content hash so the upcoming fs-watcher
+   * echo for this same write is suppressed (see startWatch's debounce
+   * callback). `flowContent` / `styleContent` are the exact bytes written —
+   * pass `''` for style when style.json was deleted or doesn't exist.
+   */
+  notifyWritten(
+    flowId: string,
+    snap: FlowSnapshot,
+    flowContent: string,
+    styleContent: string,
+  ): void;
   /**
    * Relative paths (under `<project>/.seeflow/`) currently being watched
    * because they're referenced by a node's `data.htmlPath` or `data.path`.
@@ -69,8 +97,24 @@ interface WatchHandle {
   fileWatchers: Map<string, FileWatchEntry>;
 }
 
-const resolveFilePath = (repoPath: string, architecturePath: string): string =>
-  isAbsolute(architecturePath) ? architecturePath : join(repoPath, architecturePath);
+const resolveFilePath = (repoPath: string, flowPath: string): string =>
+  isAbsolute(flowPath) ? flowPath : join(repoPath, flowPath);
+
+// `file://` refs in flow.json resolve against `<project>/.seeflow/` per the
+// skill spec — not against the flow file's own directory. Walk up from the
+// flow's parent looking for an ancestor named `.seeflow`. Fallback to the
+// flow's parent for flows registered outside the `.seeflow/` convention.
+const computeSeeflowRoot = (flowPath: string): string => {
+  const flowDir = dirname(flowPath);
+  let current = flowDir;
+  while (true) {
+    if (basename(current) === '.seeflow') return current;
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return flowDir;
+};
 
 const isCleanRelativePath = (p: string): boolean => {
   if (!p) return false;
@@ -85,7 +129,7 @@ const isCleanRelativePath = (p: string): boolean => {
 };
 
 /**
- * Walk raw architecture JSON (pre-schema-parse) collecting referenced file
+ * Walk raw flow JSON (pre-schema-parse) collecting referenced file
  * paths: `nodes[].data.htmlPath` (htmlNode) and `nodes[].data.path`
  * (imageNode). Operates on the raw JSON so the watcher works before those
  * fields are formally validated.
@@ -110,21 +154,21 @@ const collectReferencedPaths = (raw: unknown): string[] => {
 };
 
 /**
- * Read architecture.json + optional style.json, resolve file:// refs in the
- * architecture, validate both, and merge into a Flow. Shared by the watcher
- * and by sync read fallbacks (getFlowImpl) so they produce identical results.
+ * Read flow.json + optional style.json, resolve file:// refs in the flow,
+ * validate both, and merge into a ResolvedFlow. Shared by the watcher and
+ * by sync read fallbacks (getFlowImpl) so they produce identical results.
  */
 export interface ReadMergedFlowResult {
-  flow: Flow | null;
+  flow: ResolvedFlow | null;
   valid: boolean;
   error: string | null;
   /** Sorted relative paths under `<seeflowRoot>` resolved via file://. */
   fileRefs: string[];
-  /** Architecture file paths referenced via htmlPath / imageNode.path. */
+  /** Flow file paths referenced via htmlPath / imageNode.path. */
   staticRefs: string[];
 }
 
-export function readMergedFlow(archPath: string): ReadMergedFlowResult {
+export function readMergedFlow(flowPath: string): ReadMergedFlowResult {
   const empty: ReadMergedFlowResult = {
     flow: null,
     valid: false,
@@ -132,34 +176,35 @@ export function readMergedFlow(archPath: string): ReadMergedFlowResult {
     fileRefs: [],
     staticRefs: [],
   };
-  if (!existsSync(archPath)) {
-    return { ...empty, error: `Architecture file not found: ${archPath}` };
+  if (!existsSync(flowPath)) {
+    return { ...empty, error: `Flow file not found: ${flowPath}` };
   }
 
-  const seeflowRoot = dirname(archPath);
-  const stylePath = join(seeflowRoot, 'style.json');
+  const flowDir = dirname(flowPath);
+  const seeflowRoot = computeSeeflowRoot(flowPath);
+  const stylePath = join(flowDir, 'style.json');
 
-  let rawArch: unknown;
+  let rawFlow: unknown;
   try {
-    rawArch = JSON.parse(readFileSync(archPath, 'utf8'));
+    rawFlow = JSON.parse(readFileSync(flowPath, 'utf8'));
   } catch (err) {
     return {
       ...empty,
-      error: `Invalid JSON in architecture.json: ${err instanceof Error ? err.message : String(err)}`,
+      error: `Invalid JSON in flow.json: ${err instanceof Error ? err.message : String(err)}`,
     };
   }
 
-  const { resolved, refs } = resolveFileRefs(rawArch, seeflowRoot);
-  const staticRefs = collectReferencedPaths(rawArch);
+  const { resolved, refs } = resolveFileRefs(rawFlow, seeflowRoot);
+  const staticRefs = collectReferencedPaths(rawFlow);
 
-  const archParse = ArchitectureSchema.safeParse(resolved);
-  if (!archParse.success) {
-    const message = archParse.error.issues
+  const flowParse = FlowSchema.safeParse(resolved);
+  if (!flowParse.success) {
+    const message = flowParse.error.issues
       .map((i) => `${i.path.join('.') || '<root>'}: ${i.message}`)
       .join('; ');
     return {
       ...empty,
-      error: `Architecture schema validation failed: ${message}`,
+      error: `Flow schema validation failed: ${message}`,
       fileRefs: refs,
       staticRefs,
     };
@@ -192,7 +237,7 @@ export function readMergedFlow(archPath: string): ReadMergedFlowResult {
     };
   }
 
-  const flow = mergeArchitectureAndStyle(archParse.data as Architecture, styleParse.data);
+  const flow = mergeFlowAndStyle(flowParse.data as Flow, styleParse.data);
   return { flow, valid: true, error: null, fileRefs: refs, staticRefs };
 }
 
@@ -210,6 +255,43 @@ export function createWatcher(deps: WatcherDeps): FlowWatcher {
 
   const handles = new Map<string, WatchHandle>();
   const snapshots = new Map<string, FlowSnapshot>();
+  /**
+   * Ring buffer of recent self-write content hashes per flow. The fs watcher
+   * computes the same hash on its debounced callback and short-circuits when
+   * it matches — that's how a server-initiated PATCH avoids re-broadcasting
+   * itself on top of the direct notifyWritten broadcast.
+   */
+  const writtenHashes = new Map<string, string[]>();
+
+  const rememberWrittenHash = (flowId: string, hash: string): void => {
+    const ring = writtenHashes.get(flowId);
+    if (!ring) {
+      writtenHashes.set(flowId, [hash]);
+      return;
+    }
+    ring.push(hash);
+    if (ring.length > WRITTEN_HASH_RING_SIZE) ring.shift();
+  };
+
+  const isOwnWriteEcho = (flowId: string, hash: string): boolean =>
+    writtenHashes.get(flowId)?.includes(hash) ?? false;
+
+  /**
+   * Read flow.json + style.json bytes at this moment so the fs callback can
+   * compute the same combined hash that notifyWritten recorded. Missing
+   * style.json maps to empty string — matches notifyWritten's contract.
+   */
+  const readCombinedFromDisk = (flowPath: string): string | null => {
+    let flowContent: string;
+    try {
+      flowContent = readFileSync(flowPath, 'utf8');
+    } catch {
+      return null;
+    }
+    const stylePath = join(dirname(flowPath), 'style.json');
+    const styleContent = existsSync(stylePath) ? readFileSync(stylePath, 'utf8') : '';
+    return combinedContent(flowContent, styleContent);
+  };
 
   // Reconcile the file-watch set for `flowId` against the desired referenced
   // paths. Closes watchers for dirs that disappeared, updates the basename
@@ -300,7 +382,7 @@ export function createWatcher(deps: WatcherDeps): FlowWatcher {
   const reparse = (flowId: string): FlowSnapshot | null => {
     const entry = registry.getById(flowId);
     if (!entry) return null;
-    const filePath = resolveFilePath(entry.repoPath, entry.architecturePath);
+    const filePath = resolveFilePath(entry.repoPath, entry.flowPath);
 
     const previous = snapshots.get(flowId) ?? null;
     const parsedAt = Date.now();
@@ -313,14 +395,14 @@ export function createWatcher(deps: WatcherDeps): FlowWatcher {
     snapshots.set(flowId, next);
 
     // Reconcile the referenced-file watch set: htmlPath/imageNode.path from
-    // architecture + any file:// targets that resolved cleanly. Schema errors
+    // flow + any file:// targets that resolved cleanly. Schema errors
     // shouldn't drop the watch set — the user is mid-edit and the referenced
     // files are still valid targets, so this reconciles whenever the JSON
     // parsed (even if schema validation failed).
     const handle = handles.get(flowId);
     if (handle) {
       const allRefs = [...result.fileRefs, ...result.staticRefs];
-      reconcileFileWatchers(flowId, handle, dirname(filePath), allRefs);
+      reconcileFileWatchers(flowId, handle, computeSeeflowRoot(filePath), allRefs);
     }
 
     return next;
@@ -346,7 +428,7 @@ export function createWatcher(deps: WatcherDeps): FlowWatcher {
     const entry = registry.getById(flowId);
     if (!entry) return;
 
-    const filePath = resolveFilePath(entry.repoPath, entry.architecturePath);
+    const filePath = resolveFilePath(entry.repoPath, entry.flowPath);
     const dir = dirname(filePath);
     const base = basename(filePath);
 
@@ -360,7 +442,7 @@ export function createWatcher(deps: WatcherDeps): FlowWatcher {
     let fsWatcher: FSWatcher;
     try {
       fsWatcher = watch(dir, { persistent: true }, (_event, changed) => {
-        // React to architecture.json, style.json, or rename-on-save events
+        // React to flow.json, style.json, or rename-on-save events
         // (some platforms emit those with no filename).
         if (changed && changed !== base && changed !== 'style.json') return;
         const handle = handles.get(flowId);
@@ -368,6 +450,11 @@ export function createWatcher(deps: WatcherDeps): FlowWatcher {
         if (handle.debounceTimer) clearTimeout(handle.debounceTimer);
         handle.debounceTimer = setTimeout(() => {
           handle.debounceTimer = null;
+          // Own-write dedupe: if the on-disk bytes match what the server just
+          // wrote (recent hash in the ring), this is our own echo — drop it.
+          // notifyWritten already broadcast and seeded the snapshot.
+          const combined = readCombinedFromDisk(filePath);
+          if (combined !== null && isOwnWriteEcho(flowId, sha256Hex(combined))) return;
           const snap = reparse(flowId);
           if (snap) broadcastReload(flowId, snap);
         }, debounceMs);
@@ -419,8 +506,14 @@ export function createWatcher(deps: WatcherDeps): FlowWatcher {
       }
       handles.clear();
       snapshots.clear();
+      writtenHashes.clear();
     },
     reparse,
+    notifyWritten(flowId, snap, flowContent, styleContent) {
+      snapshots.set(flowId, snap);
+      rememberWrittenHash(flowId, sha256Hex(combinedContent(flowContent, styleContent)));
+      broadcastReload(flowId, snap);
+    },
     referencedPaths(flowId) {
       const h = handles.get(flowId);
       if (!h) return [];