feat: integrate interaction policy with Studio selection

.changeset/2026-07-28-issue-167-interaction-policy-selection.md

@@ -0,0 +1,9 @@
+---
+'@ankhorage/studio': minor
+---
+
+Add public interaction-policy and stationary-selection runtime helpers, require ZORA 2.9 in
+generated apps, support explicit extension policy declarations, and provide stale-safe
+pointer/touch selection with layout-neutral, momentum-safe root-owned unsupported-component
+overlays. Generate first-party Expo SDK 54 apps with the compatible Reanimated 4.3.0 and Worklets
+0.8.3 pair.

README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/studio
 
-![license: MIT](././paradox/badges/license.svg) ![npm: v0.10.5](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
+![license: MIT](././paradox/badges/license.svg) ![npm: v0.10.9](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
 
 Standalone Studio authoring package for Ankhorage apps.
 

apps/studio/app.config.ts

@@ -4,6 +4,10 @@ export default ({ config }: ConfigContext): ExpoConfig => ({
   ...config,
   name: config.name ?? 'Ankhorage Studio',
   slug: config.slug ?? 'ankhorage-studio',
+  android: {
+    ...config.android,
+    package: config.android?.package ?? 'com.ankhorage.studio',
+  },
   plugins: [...(config.plugins ?? [])],
   experiments: {
     ...config.experiments,

apps/studio/babel.config.js

@@ -13,11 +13,12 @@ module.exports = function (api) {
             '@': './src',
             '@root': './',
             '@ankhorage/studio': '../../dist/root.js',
+            'expo-router': '../../node_modules/expo-router',
           },
         },
       ],
-      // Required for Reanimated. Must be the last plugin.
-      'react-native-reanimated/plugin',
+      // Required for Worklets/Reanimated. Must be the last plugin.
+      'react-native-worklets/plugin',
     ],
   };
 };

apps/studio/package.json

@@ -29,11 +29,11 @@
     "react-dom": "19.1.0",
     "react-native": "0.81.5",
     "react-native-gesture-handler": "~2.28.0",
-    "react-native-reanimated": "~4.1.1",
+    "react-native-reanimated": "4.3.0",
     "react-native-safe-area-context": "~5.6.0",
     "react-native-screens": "~4.16.0",
     "react-native-web": "^0.21.2",
-    "react-native-worklets": "0.5.1",
+    "react-native-worklets": "0.8.3",
     "@react-native-picker/picker": "2.11.1",
     "expo-linear-gradient": "~15.0.8"
   },

docs/studio-runtime-selection.md

@@ -0,0 +1,30 @@
+# Studio Runtime selection
+
+Generated apps compose Studio selection through the normal Runtime renderer configuration:
+`wrapNode` records the bubbling node path, while one root gesture recognizer commits a stationary
+selection. Edit mode supplies `interactionPolicy="passive"` only to components that explicitly
+support the canonical policy; Preview restores `enabled`.
+
+Unsupported extension components can expose indicator geometry on native by attaching
+`useStudioUnsupportedNodeMeasurement()` from `@ankhorage/studio/runtime` to their existing native
+root view:
+
+```tsx
+const measurement = useStudioUnsupportedNodeMeasurement();
+
+return (
+  <View ref={measurement.ref} onLayout={measurement.onLayout}>
+    {children}
+  </View>
+);
+```
+
+The Studio recorder remains `display: "contents"` and therefore does not add a Yoga layout box.
+The hook measures the component's authored root through React Native's public ref API. It does not
+opt the component into interaction-policy support, clone the rendered element, or alter the
+component's props or identity.
+
+The visual indicator is rendered by the root selection surface with `pointerEvents="none"`.
+Native scroll input starts a bounded settle sequence that stops after stable measurements or a
+strict sample limit; Preview, unmount, navigation, and removal of the last unsupported measurement
+cancel pending work.

package.json

@@ -240,11 +240,12 @@
     "@ankhorage/supabase-auth": "^1.1.1",
     "@ankhorage/supabase-vault": "^0.2.0",
     "@ankhorage/templates": "^3.0.0",
-    "@ankhorage/zora": "^2.8.7",
+    "@ankhorage/zora": "^2.9.0",
     "@ankhorage/zora-chess": "^0.1.2",
     "@ankhorage/zora-tabletop": "^0.0.5",
     "@fastify/cors": "^11.2.0",
-    "fastify": "^5.7.4"
+    "fastify": "^5.7.4",
+    "react-native-gesture-handler": "~2.28.0"
   },
   "peerDependencies": {
     "@expo/vector-icons": "^15.0.3",

paradox/diagrams/architecture-overview.mmd

@@ -175,8 +175,10 @@ graph TD
   module_src_host_createStudioHost_ts --> module_src_host_orchestrator_projectManager_ts
   module_src_host_generatedAdminExpoWeb_smoke_test_ts["src/host/generatedAdminExpoWeb.smoke.test.ts"]
   package__ankhorage_studio -.-> module_src_host_generatedAdminExpoWeb_smoke_test_ts
+  module_src_host_generatedAdminExpoWeb_smoke_test_ts --> module_src_host_installedPackageProvenance_ts
   module_src_host_generatedAdminExpoWeb_smoke_test_ts --> module_src_host_orchestrator_moduleManager_ts
   module_src_host_generatedAdminExpoWeb_smoke_test_ts --> module_src_host_orchestrator_projectManager_ts
+  module_src_host_generatedAdminExpoWeb_smoke_test_ts --> module_src_host_orchestrator_semverRange_ts
   module_src_host_generatedAdminExpoWeb_smoke_test_ts --> module_src_host_templateRegistry_index_ts
   module_src_host_generatedAuthAdapterRuntime_smoke_test_ts["src/host/generatedAuthAdapterRuntime.smoke.test.ts"]
   package__ankhorage_studio -.-> module_src_host_generatedAuthAdapterRuntime_smoke_test_ts
@@ -234,6 +236,11 @@ graph TD
   module_src_host_http_standalone_ts --> module_src_host_http_serverWithSecrets_ts
   module_src_host_index_ts["src/host/index.ts"]
   package__ankhorage_studio -.-> module_src_host_index_ts
+  module_src_host_installedPackageProvenance_test_ts["src/host/installedPackageProvenance.test.ts"]
+  package__ankhorage_studio -.-> module_src_host_installedPackageProvenance_test_ts
+  module_src_host_installedPackageProvenance_test_ts --> module_src_host_installedPackageProvenance_ts
+  module_src_host_installedPackageProvenance_ts["src/host/installedPackageProvenance.ts"]
+  package__ankhorage_studio -.-> module_src_host_installedPackageProvenance_ts
   module_src_host_layout_auth_resolveAuthLayoutPlan_test_ts["src/host/layout/auth/resolveAuthLayoutPlan.test.ts"]
   package__ankhorage_studio -.-> module_src_host_layout_auth_resolveAuthLayoutPlan_test_ts
   module_src_host_layout_auth_resolveAuthLayoutPlan_test_ts --> module_src_host_layout_auth_resolveAuthLayoutPlan_ts
@@ -259,6 +266,9 @@ graph TD
   module_src_host_layout_layoutGenerator_ts --> module_src_host_modules_layout_ts
   module_src_host_layout_layoutGenerator_ts --> module_src_index_ts
   module_src_host_layout_layoutGenerator_ts --> module_src_studioAdminRouteModel_ts
+  module_src_host_layout_templates_auth_adapter_test_ts["src/host/layout/templates/auth/adapter.test.ts"]
+  package__ankhorage_studio -.-> module_src_host_layout_templates_auth_adapter_test_ts
+  module_src_host_layout_templates_auth_adapter_test_ts --> module_src_host_layout_templates_auth_adapter_ts
   module_src_host_layout_templates_auth_adapter_ts["src/host/layout/templates/auth/adapter.ts"]
   package__ankhorage_studio -.-> module_src_host_layout_templates_auth_adapter_ts
   module_src_host_layout_templates_auth_callback_ts["src/host/layout/templates/auth/callback.ts"]
@@ -295,9 +305,6 @@ graph TD
   module_src_host_layout_templates_redirect_ts["src/host/layout/templates/redirect.ts"]
   package__ankhorage_studio -.-> module_src_host_layout_templates_redirect_ts
   module_src_host_layout_templates_redirect_ts --> module_src_host_layout_utils_escapeStringLiteral_ts
-  module_src_host_layout_templates_rootLayout_selectionDom_test_ts["src/host/layout/templates/rootLayout.selectionDom.test.ts"]
-  package__ankhorage_studio -.-> module_src_host_layout_templates_rootLayout_selectionDom_test_ts
-  module_src_host_layout_templates_rootLayout_selectionDom_test_ts --> module_src_host_layout_templates_rootLayout_ts
   module_src_host_layout_templates_rootLayout_test_ts["src/host/layout/templates/rootLayout.test.ts"]
   package__ankhorage_studio -.-> module_src_host_layout_templates_rootLayout_test_ts
   module_src_host_layout_templates_rootLayout_test_ts --> module_src_host_layout_templates_rootLayout_ts
@@ -345,6 +352,15 @@ graph TD
   module_src_host_oauthFixtureConsumer_smoke_test_ts --> module_src_host_orchestrator_moduleManager_ts
   module_src_host_oauthFixtureConsumer_smoke_test_ts --> module_src_host_orchestrator_projectManager_ts
   module_src_host_oauthFixtureConsumer_smoke_test_ts --> module_src_host_templateRegistry_index_ts
+  module_src_host_orchestrator_expoSdk54AnimationCompatibility_test_ts["src/host/orchestrator/expoSdk54AnimationCompatibility.test.ts"]
+  package__ankhorage_studio -.-> module_src_host_orchestrator_expoSdk54AnimationCompatibility_test_ts
+  module_src_host_orchestrator_expoSdk54AnimationCompatibility_test_ts --> module_src_host_orchestrator_expoSdk54AnimationCompatibility_ts
+  module_src_host_orchestrator_expoSdk54AnimationCompatibility_test_ts --> module_src_host_orchestrator_templates_ts
+  module_src_host_orchestrator_expoSdk54AnimationCompatibility_ts["src/host/orchestrator/expoSdk54AnimationCompatibility.ts"]
+  package__ankhorage_studio -.-> module_src_host_orchestrator_expoSdk54AnimationCompatibility_ts
+  module_src_host_orchestrator_generatedAppFiles_test_ts["src/host/orchestrator/generatedAppFiles.test.ts"]
+  package__ankhorage_studio -.-> module_src_host_orchestrator_generatedAppFiles_test_ts
+  module_src_host_orchestrator_generatedAppFiles_test_ts --> module_src_host_orchestrator_generatedAppFiles_ts
   module_src_host_orchestrator_generatedAppFiles_ts["src/host/orchestrator/generatedAppFiles.ts"]
   package__ankhorage_studio -.-> module_src_host_orchestrator_generatedAppFiles_ts
   module_src_host_orchestrator_generatedAppFiles_ts --> module_src_host_zoraExtensions_index_ts
@@ -419,16 +435,23 @@ graph TD
   module_src_host_orchestrator_scaffolder_ts --> module_src_host_orchestrator_templates_ts
   module_src_host_orchestrator_scaffolder_ts --> module_src_host_templateRegistry_index_ts
   module_src_host_orchestrator_scaffolder_ts --> module_src_host_zoraExtensions_index_ts
+  module_src_host_orchestrator_semverRange_test_ts["src/host/orchestrator/semverRange.test.ts"]
+  package__ankhorage_studio -.-> module_src_host_orchestrator_semverRange_test_ts
+  module_src_host_orchestrator_semverRange_test_ts --> module_src_host_orchestrator_semverRange_ts
+  module_src_host_orchestrator_semverRange_ts["src/host/orchestrator/semverRange.ts"]
+  package__ankhorage_studio -.-> module_src_host_orchestrator_semverRange_ts
   module_src_host_orchestrator_studioInfraUp_ts["src/host/orchestrator/studioInfraUp.ts"]
   package__ankhorage_studio -.-> module_src_host_orchestrator_studioInfraUp_ts
   module_src_host_orchestrator_studioInfraUp_ts --> module_src_host_orchestrator_infraRuntime_ts
   module_src_host_orchestrator_studioInfraUp_ts --> module_src_host_orchestrator_projectManager_ts
   module_src_host_orchestrator_studioInfraUp_ts --> module_src_host_secrets_trustedOAuthInfraEnvironment_ts
   module_src_host_orchestrator_templates_test_ts["src/host/orchestrator/templates.test.ts"]
   package__ankhorage_studio -.-> module_src_host_orchestrator_templates_test_ts
+  module_src_host_orchestrator_templates_test_ts --> module_src_host_orchestrator_expoSdk54AnimationCompatibility_ts
   module_src_host_orchestrator_templates_test_ts --> module_src_host_orchestrator_templates_ts
   module_src_host_orchestrator_templates_ts["src/host/orchestrator/templates.ts"]
   package__ankhorage_studio -.-> module_src_host_orchestrator_templates_ts
+  module_src_host_orchestrator_templates_ts --> module_src_host_orchestrator_expoSdk54AnimationCompatibility_ts
   module_src_host_orchestrator_workspaceRuntime_ts["src/host/orchestrator/workspaceRuntime.ts"]
   package__ankhorage_studio -.-> module_src_host_orchestrator_workspaceRuntime_ts
   module_src_host_secrets_bunSupabaseVaultClient_ts["src/host/secrets/bunSupabaseVaultClient.ts"]
@@ -593,6 +616,24 @@ graph TD
   package__ankhorage_studio -.-> module_src_runtime_appExtensionRegistry_ts
   module_src_runtime_index_ts["src/runtime/index.ts"]
   package__ankhorage_studio -.-> module_src_runtime_index_ts
+  module_src_runtime_indicatorRefreshCoordinator_test_ts["src/runtime/indicatorRefreshCoordinator.test.ts"]
+  package__ankhorage_studio -.-> module_src_runtime_indicatorRefreshCoordinator_test_ts
+  module_src_runtime_indicatorRefreshCoordinator_test_ts --> module_src_runtime_indicatorRefreshCoordinator_ts
+  module_src_runtime_indicatorRefreshCoordinator_ts["src/runtime/indicatorRefreshCoordinator.ts"]
+  package__ankhorage_studio -.-> module_src_runtime_indicatorRefreshCoordinator_ts
+  module_src_runtime_indicatorSettleCoordinator_test_ts["src/runtime/indicatorSettleCoordinator.test.ts"]
+  package__ankhorage_studio -.-> module_src_runtime_indicatorSettleCoordinator_test_ts
+  module_src_runtime_indicatorSettleCoordinator_test_ts --> module_src_runtime_indicatorSettleCoordinator_ts
+  module_src_runtime_indicatorSettleCoordinator_ts["src/runtime/indicatorSettleCoordinator.ts"]
+  package__ankhorage_studio -.-> module_src_runtime_indicatorSettleCoordinator_ts
+  module_src_runtime_interactionPolicy_test_ts["src/runtime/interactionPolicy.test.ts"]
+  package__ankhorage_studio -.-> module_src_runtime_interactionPolicy_test_ts
+  module_src_runtime_interactionPolicy_test_ts --> module_src_runtime_interactionPolicyCore_ts
+  module_src_runtime_interactionPolicy_ts["src/runtime/interactionPolicy.ts"]
+  package__ankhorage_studio -.-> module_src_runtime_interactionPolicy_ts
+  module_src_runtime_interactionPolicy_ts --> module_src_runtime_interactionPolicyCore_ts
+  module_src_runtime_interactionPolicyCore_ts["src/runtime/interactionPolicyCore.ts"]
+  package__ankhorage_studio -.-> module_src_runtime_interactionPolicyCore_ts
   module_src_runtime_localizationPreview_ts["src/runtime/localizationPreview.ts"]
   package__ankhorage_studio -.-> module_src_runtime_localizationPreview_ts
   module_src_runtime_previewRegistry_ts["src/runtime/previewRegistry.ts"]
@@ -601,13 +642,33 @@ graph TD
   module_src_runtime_previewRuntimeConfig_ts["src/runtime/previewRuntimeConfig.ts"]
   package__ankhorage_studio -.-> module_src_runtime_previewRuntimeConfig_ts
   module_src_runtime_previewRuntimeConfig_ts --> module_src_runtime_actionSuppression_ts
+  module_src_runtime_previewRuntimeConfig_ts --> module_src_runtime_interactionPolicy_ts
+  module_src_runtime_previewRuntimeConfig_ts --> module_src_runtime_interactionPolicyCore_ts
   module_src_runtime_previewRuntimeConfig_ts --> module_src_runtime_previewRegistry_ts
   module_src_runtime_registry_tsx["src/runtime/registry.tsx"]
   package__ankhorage_studio -.-> module_src_runtime_registry_tsx
   module_src_runtime_runtimeActions_ts["src/runtime/runtimeActions.ts"]
   package__ankhorage_studio -.-> module_src_runtime_runtimeActions_ts
   module_src_runtime_runtimeSurface_test_ts["src/runtime/runtimeSurface.test.ts"]
   package__ankhorage_studio -.-> module_src_runtime_runtimeSurface_test_ts
+  module_src_runtime_stationarySelection_test_ts["src/runtime/stationarySelection.test.ts"]
+  package__ankhorage_studio -.-> module_src_runtime_stationarySelection_test_ts
+  module_src_runtime_stationarySelection_ts["src/runtime/stationarySelection.ts"]
+  package__ankhorage_studio -.-> module_src_runtime_stationarySelection_ts
+  module_src_runtime_stationarySelection_ts --> module_src_runtime_indicatorRefreshCoordinator_ts
+  module_src_runtime_stationarySelection_ts --> module_src_runtime_indicatorSettleCoordinator_ts
+  module_src_runtime_stationarySelection_ts --> module_src_runtime_stationarySelectionCoordinator_ts
+  module_src_runtime_stationarySelection_ts --> module_src_runtime_stationarySelectionInputState_ts
+  module_src_runtime_stationarySelectionCoordinator_test_ts["src/runtime/stationarySelectionCoordinator.test.ts"]
+  package__ankhorage_studio -.-> module_src_runtime_stationarySelectionCoordinator_test_ts
+  module_src_runtime_stationarySelectionCoordinator_test_ts --> module_src_runtime_stationarySelectionCoordinator_ts
+  module_src_runtime_stationarySelectionCoordinator_ts["src/runtime/stationarySelectionCoordinator.ts"]
+  package__ankhorage_studio -.-> module_src_runtime_stationarySelectionCoordinator_ts
+  module_src_runtime_stationarySelectionInputState_test_ts["src/runtime/stationarySelectionInputState.test.ts"]
+  package__ankhorage_studio -.-> module_src_runtime_stationarySelectionInputState_test_ts
+  module_src_runtime_stationarySelectionInputState_test_ts --> module_src_runtime_stationarySelectionInputState_ts
+  module_src_runtime_stationarySelectionInputState_ts["src/runtime/stationarySelectionInputState.ts"]
+  package__ankhorage_studio -.-> module_src_runtime_stationarySelectionInputState_ts
   module_src_runtime_useRuntimeAction_ts["src/runtime/useRuntimeAction.ts"]
   package__ankhorage_studio -.-> module_src_runtime_useRuntimeAction_ts
   module_src_runtime_useRuntimeAction_ts --> module_src_runtime_runtimeActions_ts