@ankhorage/studio 0.15.0 → 0.17.0

package/dist/manifestState.js

@@ -1,3 +1,4 @@
+import { NAVIGATOR_TYPES } from '@ankhorage/contracts';
 import { insertNodeAtPlacement, moveNodeToPlacement } from './index';
 export const DEFAULT_STUDIO_SCREEN_TEMPLATE = {
     id: 'tpl-screen-empty',
@@ -104,6 +105,215 @@ export function groupScreenRouteEntries(entries) {
     }
     return Array.from(groups.values());
 }
+/**
+ * Verifies the Studio manifest invariant that route registry keys and stable
+ * ScreenSpec identities are the same unique value.
+ */
+export function hasCanonicalStudioScreenRegistryIdentity(screens) {
+    const screenIds = new Set();
+    for (const [registryKey, screen] of Object.entries(screens)) {
+        if (registryKey !== screen.id || screenIds.has(screen.id))
+            return false;
+        screenIds.add(screen.id);
+    }
+    return true;
+}
+function resolveCanonicalStudioScreen(manifest, screenId) {
+    if (!hasCanonicalStudioScreenRegistryIdentity(manifest.screens))
+        return undefined;
+    return manifest.screens[screenId];
+}
+/**
+ * Derives the complete package-neutral screen/navigation authoring model from
+ * the manifest without flattening its navigator tree.
+ */
+export function deriveStudioScreenNavigationModel(manifest) {
+    const primaryNavigatorPath = getPrimaryNavigatorPath(manifest.navigator.routes);
+    const primaryNavigator = findNavigatorAtPath(manifest.navigator, primaryNavigatorPath) ?? manifest.navigator;
+    const diagnostics = [];
+    const referencesByRegistryKey = new Map();
+    collectNavigationModelReferences({
+        navigator: manifest.navigator,
+        screens: manifest.screens,
+        primaryNavigatorPath,
+        parentPath: [],
+        routePathPrefix: [],
+        runtimePathPrefix: [],
+        diagnostics,
+        referencesByRegistryKey,
+    });
+    const screenIdCounts = new Map();
+    for (const screen of Object.values(manifest.screens)) {
+        screenIdCounts.set(screen.id, (screenIdCounts.get(screen.id) ?? 0) + 1);
+    }
+    const reportedDuplicateScreenIds = new Set();
+    const screens = Object.entries(manifest.screens).map(([registryKey, screen]) => {
+        const screenId = screen.id;
+        const routeReferences = referencesByRegistryKey.get(registryKey) ?? [];
+        if (registryKey !== screenId) {
+            diagnostics.push({
+                code: 'screen-registry-key-mismatch',
+                message: `Screen registry key "${registryKey}" does not match stable ScreenSpec.id "${screenId}".`,
+                parentPath: [],
+                screenId,
+            });
+        }
+        if ((screenIdCounts.get(screenId) ?? 0) > 1 && !reportedDuplicateScreenIds.has(screenId)) {
+            reportedDuplicateScreenIds.add(screenId);
+            diagnostics.push({
+                code: 'duplicate-screen-id',
+                message: `Stable ScreenSpec.id "${screenId}" is used by multiple screen registry entries.`,
+                parentPath: [],
+                screenId,
+            });
+        }
+        if (routeReferences.length > 1) {
+            diagnostics.push({
+                code: 'ambiguous-screen-route-reference',
+                message: `Screen "${screenId}" is referenced by ${routeReferences.length} routes.`,
+                parentPath: [],
+                screenId,
+            });
+        }
+        return { screenId, screen, routeReferences };
+    });
+    return {
+        primaryNavigatorPath,
+        primaryNavigator,
+        screens,
+        diagnostics,
+    };
+}
+/**
+ * Returns a concrete canonical app pathname only when a screen has one route
+ * reference and that route does not require runtime parameters.
+ */
+export function resolveStudioScreenAppPath(model, screenId) {
+    const matchingEntries = model.screens.filter((candidate) => candidate.screenId === screenId);
+    if (matchingEntries.length !== 1)
+        return null;
+    const [entry] = matchingEntries;
+    if (!entry)
+        return null;
+    if (entry.routeReferences.length !== 1)
+        return null;
+    const [reference] = entry.routeReferences;
+    if (!reference)
+        return null;
+    const hasDynamicSegment = reference.pathnamePattern
+        .split('/')
+        .some((segment) => segment.startsWith(':') || /^\[.*\]$/u.test(segment));
+    if (hasDynamicSegment)
+        return null;
+    const matchingReferences = model.screens.flatMap((candidate) => candidate.routeReferences.filter((candidateReference) => candidateReference.pathnamePattern === reference.pathnamePattern));
+    return matchingReferences.length === 1 ? reference.pathnamePattern : null;
+}
+function collectNavigationModelReferences(args) {
+    const { navigator, screens, primaryNavigatorPath, parentPath, routePathPrefix, runtimePathPrefix, diagnostics, referencesByRegistryKey, } = args;
+    const siblingNameCounts = new Map();
+    for (const route of navigator.routes) {
+        siblingNameCounts.set(route.name, (siblingNameCounts.get(route.name) ?? 0) + 1);
+    }
+    if (navigator.routes.length === 0) {
+        diagnostics.push({
+            code: 'empty-navigator',
+            message: `Navigator at "${formatParentPath(parentPath)}" has no routes.`,
+            parentPath,
+        });
+    }
+    if (navigator.initialRouteName !== undefined &&
+        siblingNameCounts.get(navigator.initialRouteName) !== 1) {
+        diagnostics.push({
+            code: 'invalid-initial-route',
+            message: `Initial route "${navigator.initialRouteName}" is not one unambiguous direct route of "${formatParentPath(parentPath)}".`,
+            parentPath,
+            routeName: navigator.initialRouteName,
+        });
+    }
+    for (const [siblingIndex, route] of navigator.routes.entries()) {
+        const routePath = [...routePathPrefix, route.name];
+        const runtimePath = appendRuntimeRoutePath(runtimePathPrefix, route);
+        const isPrimaryNavigatorMember = pathsEqual(parentPath, primaryNavigatorPath);
+        if ((siblingNameCounts.get(route.name) ?? 0) > 1 &&
+            navigator.routes.findIndex((candidate) => candidate.name === route.name) === siblingIndex) {
+            diagnostics.push({
+                code: 'duplicate-sibling-route-name',
+                message: `Route name "${route.name}" is duplicated under "${formatParentPath(parentPath)}".`,
+                parentPath,
+                routeName: route.name,
+                screenId: route.screenId,
+            });
+        }
+        if (!route.screenId && !route.navigator) {
+            diagnostics.push({
+                code: 'missing-route-target',
+                message: `Route "${route.name}" has neither a screen nor a nested navigator.`,
+                parentPath,
+                routeName: route.name,
+            });
+        }
+        else if (route.screenId && route.navigator) {
+            diagnostics.push({
+                code: 'ambiguous-route-target',
+                message: `Route "${route.name}" targets both a screen and a nested navigator.`,
+                parentPath,
+                routeName: route.name,
+                screenId: route.screenId,
+            });
+        }
+        if (route.screenId) {
+            if (!screens[route.screenId]) {
+                diagnostics.push({
+                    code: 'missing-screen-reference',
+                    message: `Route "${route.name}" references missing screen "${route.screenId}".`,
+                    parentPath,
+                    routeName: route.name,
+                    screenId: route.screenId,
+                });
+            }
+            else {
+                const reference = {
+                    route,
+                    parentPath,
+                    routePath,
+                    pathnamePattern: toCanonicalRoutePattern(runtimePath),
+                    siblingIndex,
+                    navigatorType: navigator.type,
+                    isPrimaryNavigatorMember,
+                    showInPrimaryNavigation: route.showInPrimaryNavigation !== false,
+                    isPrimaryInitialRoute: isPrimaryNavigatorMember && navigator.initialRouteName === route.name,
+                };
+                const currentReferences = referencesByRegistryKey.get(route.screenId) ?? [];
+                currentReferences.push(reference);
+                referencesByRegistryKey.set(route.screenId, currentReferences);
+            }
+        }
+        if (route.navigator) {
+            collectNavigationModelReferences({
+                navigator: route.navigator,
+                screens,
+                primaryNavigatorPath,
+                parentPath: routePath,
+                routePathPrefix: routePath,
+                runtimePathPrefix: runtimePath,
+                diagnostics,
+                referencesByRegistryKey,
+            });
+        }
+    }
+}
+function appendRuntimeRoutePath(runtimePathPrefix, route) {
+    const explicitPath = route.path?.trim();
+    const segmentPath = explicitPath ?? route.name;
+    const segments = segmentPath.split('/').filter(Boolean);
+    return explicitPath?.startsWith('/') ? segments : [...runtimePathPrefix, ...segments];
+}
+function pathsEqual(first, second) {
+    return first.length === second.length && first.every((value, index) => value === second[index]);
+}
+function formatParentPath(parentPath) {
+    return parentPath.length === 0 ? '<root>' : parentPath.join('/');
+}
 export function listScreenIdsInRouteOrder(routes) {
     return collectScreenRouteEntries(routes).map((entry) => entry.screenId);
 }
@@ -113,6 +323,8 @@ export function listScreenIdsInRouteOrder(routes) {
  * back to the first route that reaches an available screen.
  */
 export function resolveInitialScreenId(navigator, screens) {
+    if (screens && !hasCanonicalStudioScreenRegistryIdentity(screens))
+        return null;
     const initialRoute = navigator.initialRouteName
         ? navigator.routes.find((route) => route.name === navigator.initialRouteName)
         : undefined;
@@ -126,22 +338,22 @@ export function resolveInitialScreenId(navigator, screens) {
                 return nestedScreenId;
         }
         if (route.screenId && (!screens || screens[route.screenId])) {
-            return route.screenId;
+            return screens ? (screens[route.screenId]?.id ?? null) : route.screenId;
         }
     }
     return null;
 }
 export function resolveInitialActiveScreenId(manifest) {
-    if (!manifest)
+    if (!manifest || !hasCanonicalStudioScreenRegistryIdentity(manifest.screens))
         return null;
     const firstRoutedScreenId = resolveInitialScreenId(manifest.navigator, manifest.screens);
-    const [firstScreenId] = Object.keys(manifest.screens);
+    const [firstScreenId] = Object.values(manifest.screens).map((screen) => screen.id);
     return firstRoutedScreenId ?? firstScreenId ?? null;
 }
 export function resolveActiveRootNode(manifest, activeScreenId) {
     if (!manifest || !activeScreenId)
         return null;
-    return manifest.screens[activeScreenId]?.root ?? null;
+    return resolveCanonicalStudioScreen(manifest, activeScreenId)?.root ?? null;
 }
 export function findNodeInManifest(root, id) {
     if (root.id === id)
@@ -159,9 +371,11 @@ export function resolveSafeSelectedNodeId(rootNode, selectedNodeId) {
     return findNodeInManifest(rootNode, selectedNodeId) ? selectedNodeId : null;
 }
 export function findScreenIdForNode(manifest, nodeId) {
-    for (const [screenId, screen] of Object.entries(manifest.screens)) {
+    if (!hasCanonicalStudioScreenRegistryIdentity(manifest.screens))
+        return null;
+    for (const screen of Object.values(manifest.screens)) {
         if (findNodeInManifest(screen.root, nodeId)) {
-            return screenId;
+            return screen.id;
         }
     }
     return null;
@@ -169,7 +383,7 @@ export function findScreenIdForNode(manifest, nodeId) {
 export function updateStudioManifestNode(manifest, activeScreenId, nodeId, newProps) {
     if (!activeScreenId)
         return manifest;
-    const screen = manifest.screens[activeScreenId];
+    const screen = resolveCanonicalStudioScreen(manifest, activeScreenId);
     if (!screen)
         return manifest;
     const newRoot = updateNodeInManifestTree(screen.root, nodeId, newProps);
@@ -189,7 +403,7 @@ export function updateStudioManifestNode(manifest, activeScreenId, nodeId, newPr
 export function deleteStudioManifestNode(manifest, activeScreenId, nodeId) {
     if (!activeScreenId)
         return manifest;
-    const screen = manifest.screens[activeScreenId];
+    const screen = resolveCanonicalStudioScreen(manifest, activeScreenId);
     if (!screen || screen.root.id === nodeId)
         return manifest;
     const deletedNode = findNodeInManifest(screen.root, nodeId);
@@ -216,7 +430,7 @@ export function insertStudioManifestNodeAtPlacement(args) {
     const { manifest, activeScreenId, placement, newNode, componentMeta } = args;
     if (!activeScreenId)
         return null;
-    const screen = manifest.screens[activeScreenId];
+    const screen = resolveCanonicalStudioScreen(manifest, activeScreenId);
     if (!screen)
         return null;
     const insertion = insertNodeAtPlacement({
@@ -245,7 +459,7 @@ export function moveStudioManifestNodeToPlacement(args) {
     const { manifest, activeScreenId, nodeId, placement, componentMeta } = args;
     if (!activeScreenId)
         return null;
-    const screen = manifest.screens[activeScreenId];
+    const screen = resolveCanonicalStudioScreen(manifest, activeScreenId);
     if (!screen)
         return null;
     const movement = moveNodeToPlacement({
@@ -420,7 +634,10 @@ export function findRoutesAtParentPath(routes, parentPath) {
     const [segment, ...rest] = parentPath;
     if (!segment)
         return null;
-    const route = routes.find((item) => item.name === segment);
+    const matches = routes.filter((item) => item.name === segment);
+    if (matches.length !== 1)
+        return null;
+    const [route] = matches;
     if (!route?.navigator?.routes)
         return null;
     return findRoutesAtParentPath(route.navigator.routes, rest);
@@ -429,8 +646,12 @@ export function insertRouteAtParentPath(routes, parentPath, newRoute) {
     if (parentPath.length === 0)
         return [...routes, newRoute];
     const [segment, ...rest] = parentPath;
+    const matches = routes.filter((route) => route.name === segment && route.navigator);
+    if (matches.length !== 1)
+        return routes;
+    const [targetRoute] = matches;
     return routes.map((route) => {
-        if (route.name !== segment || !route.navigator?.routes)
+        if (route !== targetRoute || !route.navigator?.routes)
             return route;
         return {
             ...route,
@@ -447,7 +668,10 @@ export function findNavigatorAtPath(navigator, parentPath) {
     const [segment, ...rest] = parentPath;
     if (!segment)
         return null;
-    const route = navigator.routes.find((item) => item.name === segment);
+    const matches = navigator.routes.filter((item) => item.name === segment);
+    if (matches.length !== 1)
+        return null;
+    const [route] = matches;
     if (!route?.navigator)
         return null;
     return findNavigatorAtPath(route.navigator, rest);
@@ -456,10 +680,14 @@ export function updateNavigatorAtPath(navigator, parentPath, updater) {
     if (parentPath.length === 0)
         return updater(navigator);
     const [segment, ...rest] = parentPath;
+    const matches = navigator.routes.filter((route) => route.name === segment && route.navigator);
+    if (matches.length !== 1)
+        return navigator;
+    const [targetRoute] = matches;
     return {
         ...navigator,
         routes: navigator.routes.map((route) => {
-            if (route.name !== segment || !route.navigator)
+            if (route !== targetRoute || !route.navigator)
                 return route;
             return {
                 ...route,
@@ -469,6 +697,8 @@ export function updateNavigatorAtPath(navigator, parentPath, updater) {
     };
 }
 export function setStudioManifestNavigatorType(manifest, type) {
+    if (!NAVIGATOR_TYPES.includes(type))
+        return manifest;
     const primaryNavigatorPath = getPrimaryNavigatorPath(manifest.navigator.routes);
     const currentNavigator = findNavigatorAtPath(manifest.navigator, primaryNavigatorPath);
     if (!currentNavigator || currentNavigator.type === type)
@@ -489,8 +719,9 @@ export function setStudioManifestNavigatorInitialRoute(manifest, routeName) {
     const currentNavigator = findNavigatorAtPath(manifest.navigator, primaryNavigatorPath);
     if (!currentNavigator)
         return manifest;
-    if (!currentNavigator.routes.some((route) => route.name === normalizedRoute))
+    if (currentNavigator.routes.filter((route) => route.name === normalizedRoute).length !== 1) {
         return manifest;
+    }
     if (currentNavigator.initialRouteName === normalizedRoute)
         return manifest;
     return {
@@ -501,26 +732,82 @@ export function setStudioManifestNavigatorInitialRoute(manifest, routeName) {
         })),
     };
 }
+export function setStudioManifestRoutePrimaryNavigationVisibility(args) {
+    const { manifest, parentPath, routeName, showInPrimaryNavigation } = args;
+    const navigator = findNavigatorAtPath(manifest.navigator, parentPath);
+    if (!navigator)
+        return manifest;
+    const matches = navigator.routes.filter((route) => route.name === routeName);
+    if (matches.length !== 1)
+        return manifest;
+    const [matchedRoute] = matches;
+    if (!matchedRoute)
+        return manifest;
+    const alreadyCanonical = showInPrimaryNavigation
+        ? matchedRoute.showInPrimaryNavigation === undefined
+        : matchedRoute.showInPrimaryNavigation === false;
+    if (alreadyCanonical)
+        return manifest;
+    return {
+        ...manifest,
+        navigator: updateNavigatorAtPath(manifest.navigator, parentPath, (current) => ({
+            ...current,
+            routes: current.routes.map((route) => {
+                if (route !== matchedRoute)
+                    return route;
+                if (!showInPrimaryNavigation) {
+                    return { ...route, showInPrimaryNavigation: false };
+                }
+                const { showInPrimaryNavigation: _visibility, ...visibleRoute } = route;
+                return visibleRoute;
+            }),
+        })),
+    };
+}
+export function moveStudioManifestRoute(args) {
+    const { manifest, parentPath, routeName, toIndex } = args;
+    if (!Number.isInteger(toIndex))
+        return manifest;
+    const navigator = findNavigatorAtPath(manifest.navigator, parentPath);
+    if (!navigator || toIndex < 0 || toIndex >= navigator.routes.length)
+        return manifest;
+    const matchingIndexes = navigator.routes.flatMap((route, index) => route.name === routeName ? [index] : []);
+    if (matchingIndexes.length !== 1)
+        return manifest;
+    const [fromIndex] = matchingIndexes;
+    if (fromIndex === undefined || fromIndex === toIndex)
+        return manifest;
+    return {
+        ...manifest,
+        navigator: updateNavigatorAtPath(manifest.navigator, parentPath, (current) => {
+            const routes = [...current.routes];
+            const [route] = routes.splice(fromIndex, 1);
+            if (!route)
+                return current;
+            routes.splice(toIndex, 0, route);
+            return { ...current, routes };
+        }),
+    };
+}
 export function addStudioManifestScreen(args) {
     const { manifest, activeScreenId, createId = generateManifestStateId } = args;
+    if (!hasCanonicalStudioScreenRegistryIdentity(manifest.screens)) {
+        return { manifest, activeScreenId };
+    }
     const trimmedName = args.name.trim();
     if (!trimmedName)
         return { manifest, activeScreenId };
     const baseRouteName = normalizeRouteName(trimmedName);
-    const activeParentPath = activeScreenId
-        ? findParentPathForScreenId(manifest.navigator.routes, activeScreenId)
-        : null;
-    const fallbackParentPath = getPrimaryNavigatorPath(manifest.navigator.routes);
-    const activeParentRoutes = activeParentPath !== null
-        ? findRoutesAtParentPath(manifest.navigator.routes, activeParentPath)
-        : null;
-    const parentPath = activeParentPath && activeParentRoutes ? activeParentPath : fallbackParentPath;
-    const siblingRoutes = findRoutesAtParentPath(manifest.navigator.routes, parentPath) ?? [];
+    const parentPath = args.parentPath ?? getPrimaryNavigatorPath(manifest.navigator.routes);
+    const siblingRoutes = findRoutesAtParentPath(manifest.navigator.routes, parentPath);
+    if (!siblingRoutes)
+        return { manifest, activeScreenId };
+    const existingScreenIds = new Set(Object.values(manifest.screens).map((screen) => screen.id));
     let screenId = createId('Screen');
-    while (manifest.screens[screenId]) {
+    while (manifest.screens[screenId] || existingScreenIds.has(screenId)) {
         screenId = createId('Screen');
     }
-    const existingPatterns = new Set(collectScreenRouteEntries(manifest.navigator.routes).map((entry) => toCanonicalRoutePattern(entry.routePath)));
+    const existingPatterns = new Set(collectCanonicalRoutePatterns(manifest.navigator.routes));
     const routeName = makeUniqueRouteNameForParent(baseRouteName, siblingRoutes, parentPath, existingPatterns);
     const newScreen = {
         id: screenId,
@@ -548,46 +835,33 @@ export function addStudioManifestScreen(args) {
     };
 }
 export function deleteStudioManifestScreen(manifest, screenId, activeScreenId) {
+    if (!hasCanonicalStudioScreenRegistryIdentity(manifest.screens)) {
+        return { manifest, activeScreenId };
+    }
     if (Object.keys(manifest.screens).length <= 1)
         return { manifest, activeScreenId };
+    const deletedScreen = manifest.screens[screenId];
+    if (!deletedScreen)
+        return { manifest, activeScreenId };
     const { [screenId]: _deletedScreen, ...remainingScreens } = manifest.screens;
     const remainingScreenIds = Object.keys(remainingScreens);
-    let safeRoutes = removeScreenIdFromRoutes(manifest.navigator.routes, screenId);
-    if (safeRoutes.length === 0 && remainingScreenIds.length > 0) {
-        const [fallbackScreenId] = remainingScreenIds;
-        if (!fallbackScreenId)
-            return { manifest, activeScreenId };
-        const fallbackScreen = remainingScreens[fallbackScreenId];
-        safeRoutes = [
-            {
-                name: makeUniqueSiblingRouteName('screen', []),
-                label: fallbackScreen?.name ?? 'Screen',
-                screenId: fallbackScreenId,
-            },
-        ];
-    }
+    const safeRoutes = removeScreenIdFromRoutes(manifest.navigator.routes, screenId);
     const orderedScreenIds = listScreenIdsInRouteOrder(safeRoutes).filter((id) => !!remainingScreens[id]);
     const nextActiveScreenId = !activeScreenId || activeScreenId === screenId || !remainingScreens[activeScreenId]
         ? (orderedScreenIds[0] ?? remainingScreenIds[0] ?? null)
         : activeScreenId;
+    const deletedNodeIds = collectNodeIds(deletedScreen.root);
+    const dataBindings = Object.fromEntries(Object.entries(manifest.dataBindings ?? {}).filter(([componentId, binding]) => !deletedNodeIds.has(componentId) && !deletedNodeIds.has(binding.componentId)));
     return {
         activeScreenId: nextActiveScreenId,
         manifest: {
             ...manifest,
+            dataBindings,
             screens: remainingScreens,
-            navigator: {
+            navigator: normalizeNavigatorAfterRouteUpdate({
                 ...manifest.navigator,
                 routes: safeRoutes,
-            },
-        },
-    };
-}
-export function reorderStudioManifestScreens(manifest, newRoutes) {
-    return {
-        ...manifest,
-        navigator: {
-            ...manifest.navigator,
-            routes: newRoutes,
+            }),
         },
     };
 }
@@ -653,6 +927,17 @@ function normalizeRouteName(value) {
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-+|-+$/g, '') || 'screen');
 }
+function collectCanonicalRoutePatterns(routes, runtimePathPrefix = []) {
+    const patterns = [];
+    for (const route of routes) {
+        const runtimePath = appendRuntimeRoutePath(runtimePathPrefix, route);
+        patterns.push(toCanonicalRoutePattern(runtimePath));
+        if (route.navigator) {
+            patterns.push(...collectCanonicalRoutePatterns(route.navigator.routes, runtimePath));
+        }
+    }
+    return patterns;
+}
 function cloneNodeWithNewIds(node, createId) {
     const clonedNode = {
         ...node,