How Bridge is designed and why.
Bridge exists to make native capabilities feel like part of the web application. It should expose small, stable, and well-documented interfaces, while hiding platform-specific complexity.
Every plugin should solve a real problem shared by multiple projects before it is added.
Every abstraction should earn its keep. A plugin exists because there is a real native capability that multiple web applications need. A generic "PluginFactory" meta-framework does not exist because it would add indirection without solving a concrete problem.
Build for what you have, not for what you imagine you might one day need.
Bridge exists because future Palmshed products would each need native capabilities like secure storage, biometrics, and file access. Extracting those capabilities once for Bridge avoids rebuilding them three more times.
A capability that only one product will ever use does not belong in Bridge. It belongs in the product.
Every exported symbol is a commitment. Changing it requires a major version bump, deprecation warnings, and a migration window.
It is better to leave a symbol internal for an extra release than to expose it and immediately regret the shape.
Lint, typecheck, and tests must pass before any release is cut. If CI cannot verify the code, the release does not ship.
A plugin is not complete until it has tests that cover the public API, platform-specific tests for Android and iOS, a README that documents configuration and usage, and a short example showing basic usage.
Documentation is not a separate task. It is the same task.
Use the Web APIs that are available across browsers and platforms. Reach for native bridges only when the web platform cannot solve the problem.
This is not a universal rule. When a native capability dramatically improves the user experience, use it. But default to web first and justify every native bridge.
The most important architectural skill is knowing when a capability is not yet needed. Bridge will grow. It should grow because multiple products need it, not because there is another abstract service waiting to be extracted.