# 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.