Build for the platform

Prefer fully native UI when practical. The gain is in everyday behaviour: the app responds to the menus, keyboard, selection, accessibility and navigation habits a person brings from the rest of their device. A familiar appearance alone does not deliver that improvement.

Use platform controls and conventions for navigation, menus, contextual actions, links, windows, drag/drop, sharing and keyboard interaction. Desktop right-click should expose the relevant context menu. Link actions should support the platform's expectations for opening, copying and sharing destinations; do not reduce every link to a JavaScript click handler. Accessibility semantics and focus behaviour belong in the first implementation.

When a hybrid app is appropriate

A complex editor, feed or established interactive screen can justify reuse through a webview. Keep the app shell and navigation native and choose individual embedded surfaces deliberately. Give the embedded content a narrow, typed bridge for app commands and navigation intents. The native host resolves those intents to native screens, contextual actions and system services. It should not need to inspect DOM text to discover meaning.

Internal app destinations open through native navigation. External web destinations follow the platform's browser conventions, including the person's choice where applicable. Preserve useful editing, selection and accessibility behaviour inside the web surface. Avoid replacing a capable web editor merely to increase the percentage of native code.

For encrypted content, bridge capabilities stay narrow. Pass only what the embedded surface needs; a webview that displays one conversation need not receive the account's private key or another conversation's keys.

A shared app manifest

When navigation and commands are repeated across clients, consider a manifest of app meaning with separate web and native compilers/renderers. It can describe stable destination IDs, route parameters, commands, capabilities, labels/localisation keys and link intent. The app's server still enforces permissions; hiding a command is not authorisation.

For example, the common definition can say a document supports open, rename, share and delete, and identify their handlers. The web renderer can use routes, anchors, forms and a toolbar; the Mac renderer can use windows, menu commands and right-click actions; the iPhone renderer can use navigation stacks, toolbars and action menus. Destructive confirmation and disabled/unavailable actions need explicit meaning in that contract.

Keep DOM structure, coordinates and platform-specific navigation stacks out of the common schema. Provide platform overrides for presentation and capabilities rather than forcing the least capable shared layout everywhere. Share business rules, API contracts and test vectors below the renderers.

The first proof should be a real feature rendered for web and native, with tests for destinations and action semantics plus platform UI tests. Extract the manifest schema after that proof, rather than designing a universal compiler before either client works.

No such compiler ships in the initial kit. Rastrillo's existing resource manifests generate server-rendered web CRUD; they are a separate mechanism.