Crosswake Install Guide

View Source

Crosswake keeps one primary package surface: crosswake. Companion-ready and docs-only surfaces stay explicit, but there is still one primary install path for the Phoenix host and one scaffold-once path for host-owned native shells.

See guides/adoption.md for offline-sync architecture context and the rationale for the generated shell pattern.

  1. mix crosswake.install
  2. mix crosswake.gen.shell ios|android
  3. mix crosswake.doctor --router Elixir.YourAppWeb.Router
  4. bash script/verify_phase5_example_hosts.sh
  5. mix crosswake.doctor --router Elixir.YourAppWeb.Router --native-checks

The generated Phoenix and native files are host-owned, reviewable, and editable after generation. Crosswake owns the DSL, manifest contract, doctor surface, support matrix, and release-boundary policy. It does not re-own your app files after scaffolding.

Package Surface

There is one primary crosswake package plus explicitly bounded companion-ready and docs-only surfaces. Package class does not override route ownership.

If you are deciding whether your app pressure is mostly LiveView, one explicit native route, or one honest offline island, read guides/adopter_profiles.md for the Phoenix SaaS Portal, Selective Native Flow, and Local-First Study Flow profiles before drilling into the deeper shell, offline, or pack contracts.

Add Crosswake To Your Dependencies

Add crosswake to the deps in your Phoenix host's mix.exs:

def deps do
  [
    {:crosswake, "~> 0.1"}
  ]
end

Then fetch it:

mix deps.get

Step 1: Install Crosswake Into A Phoenix Host

Run:

mix crosswake.install

What it does:

  • patches lib/<app>_web/router.ex with explicit Crosswake marker lines
  • keeps LiveView router imports compatible with the Crosswake live macro
  • generates a host-owned policy module at lib/<app>_web/crosswake/policy.ex
  • writes priv/crosswake/install_manifest.json so later tooling can inspect what Crosswake created or reused
  • points follow-up diagnostics at mix crosswake.doctor, guides/compatibility.md, guides/support_matrix.md, guides/native_shell.md, guides/bridge.md, and guides/packs.md

Repeated installer runs are idempotent. Existing marker blocks are reused instead of duplicating router edits, and existing host-owned policy files are left alone.

Step 2: Generate Host-Owned Native Shells

Run one of:

mix crosswake.gen.shell ios
mix crosswake.gen.shell android

What it does:

  • creates a host-owned shell project under native/<platform>/crosswake_shell
  • bundles the canonical manifest, activation, route-unavailable, and declared-pack fixtures
  • scaffolds manifest-first activation, explicit route unavailable UI, and the bounded bridge channel

What it does not do:

  • it does not safely regenerate over host edits
  • it does not turn unsupported routes into generic container fallback
  • it does not widen support beyond explicit, proof-backed surfaces

Read guides/native_shell.md for the shell contract and guides/bridge.md for the bounded bridge contract.

Step 3: Verify Host And Manifest Truth

Run:

mix crosswake.doctor --router Elixir.YourAppWeb.Router

This checks install state, manifest truth, shell generation posture, bounded bridge truth, release policy posture, and fail-closed denial vocabulary.

Step 4: Run The Public Proof Lane

Run:

bash script/verify_phase5_example_hosts.sh

This is the primary proof artifact class Crosswake publishes for adopters.

Step 5: Re-Run Local Generated-Host Verification

Run:

mix crosswake.doctor --router Elixir.YourAppWeb.Router --native-checks

With --native-checks, doctor executes the generated-host verification hooks:

  • script/verify_generated_ios_shell.sh
  • script/verify_generated_android_shell.sh

Do I need to rebuild?

Use the four public change classes first, before raw version numbers:

  • docs-only -> read the updated guidance and run docs integrity only
  • core-only/no native rebuild -> update core and rerun core contract + doctor/support proof
  • compatibility-bump only -> confirm your compatibility window and run fail-closed compatibility fixtures
  • native or companion rebuild required -> rebuild the affected shell or companion and rerun generated-shell or companion verification lanes

The matching proof lanes are:

  • docs integrity only
  • core contract + doctor/support proof
  • fail-closed compatibility fixtures
  • generated-shell or companion verification lanes

The generated support matrix remains authoritative: guides/support_matrix.md

See the canonical action-class table at guides/support_matrix.md#action-classes and Promotion rules at guides/support_matrix.md#promotion-rules.

Promotion rules keep advisory support explicit: StoreKit/Play Billing seams in v3.7 emit reconciliation evidence only, backend projection grants authority, provider/device proof remains advisory unless promotion criteria pass, Sigra session-authority route evaluation, Phase 55 handoff ticket/server-record contracts, Phase 56 step-up intent plus Plug/LiveView ceremony, Phase 57 OAuth/passkey/native auth-return boundary contracts, and Phase 58 telemetry/security closeout are shipped, refresh-token helpers, provider/device auth proof, provider templates, passkey SDK wrappers, direct shell/WebView token authority, and native auth UI are deferred, notification-token readiness is provider-snapshot only, and standalone public shell packages are deferred.

compatibility-window narrowing is distinct from a native rebuild; it can be compatibility-bump only when the shipped native runtime line remains compatible.

Docs-Only Install Boundary

The install walkthrough is useful product guidance, but it is not first-class supported as a separate package surface. It teaches the primary crosswake install path and the boundary between host-owned artifacts and Crosswake-owned contract surfaces.

Route owner

Install guidance does not change route ownership. Phoenix routes remain Phoenix-owned unless a route policy explicitly declares otherwise.

Why not core/companion

This walkthrough explains package and artifact boundaries. It is not itself a runtime package, and it does not promote host scaffolding into a companion surface.

Host-owned responsibilities

The host reviews generated files, owns shell project edits after generation, reruns proof hooks, and decides when local rebuilds are needed.

Prerequisites

A Phoenix host, explicit router wiring, generated policy module, and the proof scripts referenced by the support matrix.

Denial behavior

If install or compatibility truth is incomplete, mix crosswake.doctor reports blocking issues instead of inferring that the host is correctly wired.

Fallback behavior

Crosswake falls back to explicit diagnostics and route-unavailable posture, not silent package promotion or generic shell behavior.

Native rebuild required

Only when your change lands in the native or companion rebuild required class. Docs-only install guidance and core-only policy changes do not automatically imply a native rebuild.