@timmo001/groundwork-mobile 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# @timmo001/groundwork-mobile
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The page side of Groundwork's Android shell, a small Kotlin app around the
+system WebView. It works out whether the page runs in the shell, talks to the
+shell over a typed bridge when it does, and falls back to
+`@timmo001/groundwork-pwa` when it doesn't, so one app runs in both.
+
+```ts
+import { connectMobile } from "@timmo001/groundwork-mobile/view";
+
+import mobileConfig from "../mobile.config.ts";
+import pwaConfig from "../pwa.config.ts";
+
+const mobile = await connectMobile(mobileConfig, {
+  pwa: pwaConfig,
+  onShare: (share) => openDraft(share),
+  onDeepLink: (url) => route(url),
+});
+```
+
+- `.` defines the app's mobile config, which the shell also reads as JSON
+  when it's built: a hosted `url`, extra `origins`, and which of shares,
+  notifications, push, deep links, downloads and the rest it keeps.
+- `./view` connects the page: notifications, push, shares, deep links, the
+  phone's dynamic color, and the app's own requests to its Kotlin handlers.
+- `./bridge` is the bridge's message shapes and the Schema for each of the
+  shell's requests and messages.
+
+The Kotlin shell itself is the Gradle library in `packages/mobile/android`,
+taken into an app by Groundwork's sync rather than from npm. The docs are at
+[groundwork.timmo.dev/phones/shell](https://groundwork.timmo.dev/phones/shell),
+and `templates/android-app` is a starting point.

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@timmo001/groundwork-mobile",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.0",
+  "description": "The page side of Groundwork's Android shell: the app config, the typed bridge to the shell, and a fallback to the PWA outside it",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/config.ts",
+    "./bridge": "./src/bridge.ts",
+    "./view": "./src/view.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/timmo001/groundwork.git",
+    "directory": "packages/mobile"
+  },
+  "scripts": {
+    "check": "bun run --parallel --no-exit-on-error lint typecheck format:check",
+    "test": "bun test",
+    "lint": "oxlint .",
+    "typecheck": "tsc",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "dependencies": {
+    "@timmo001/groundwork-pwa": "0.0.0",
+    "@timmo001/groundwork-tokens": "0.12.1",
+    "effect": "4.1.2"
+  },
+  "devDependencies": {
+    "@oxlint/plugins": "1.92.0",
+    "@timmo001/oxlint-rules": "0.6.4",
+    "@types/bun": "1.4.4",
+    "oxlint": "1.92.0",
+    "oxlint-tsgolint": "7.0.2006",
+    "prettier": "3.9.10",
+    "typescript": "7.0.2"
+  }
+}

package/src/bridge.ts

@@ -0,0 +1,204 @@
+/**
+ * The messages between the Android shell and its view, mirroring the
+ * desktop's requests and messages. They travel as JSON text over the object
+ * the shell injects with `WebViewCompat.addWebMessageListener`, each with a
+ * `type`, so the Kotlin side reads them without a schema library. Every
+ * reply and message is parsed here as it comes in. An app adds its own
+ * requests and messages beside these, with its own schemas.
+ */
+import { Option, Schema } from "effect";
+
+/** The name of the object the shell injects into allowed pages. */
+export const bridgeObjectName = "groundworkShell";
+
+/** A notification for the shell to show, or a notice in the app without one. */
+export const Notice = Schema.Struct({
+  heading: Schema.String,
+  body: Schema.optionalKey(Schema.String),
+  tone: Schema.optionalKey(
+    Schema.Literals(["neutral", "info", "success", "warning", "danger"]),
+  ),
+  /** Like notices share a tag, so a new one replaces the last. */
+  tag: Schema.optionalKey(Schema.String),
+  /** Opens this page, relative to the app, on a tap. */
+  link: Schema.optionalKey(Schema.String),
+});
+
+export interface Notice extends Schema.Schema.Type<typeof Notice> {}
+
+/** A share from another app, the same shape the PWA's share target gives. */
+export const ShellShare = Schema.Struct({
+  title: Schema.optionalKey(Schema.String),
+  text: Schema.optionalKey(Schema.String),
+  url: Schema.optionalKey(Schema.String),
+});
+
+export const DeepLink = Schema.Struct({ url: Schema.String });
+
+export interface DeepLink extends Schema.Schema.Type<typeof DeepLink> {}
+
+/** One mode's Material roles, as `androidTheme` in the tokens reads them. */
+export const AndroidSchemeColors = Schema.Struct({
+  surface: Schema.optionalKey(Schema.String),
+  surfaceContainerLowest: Schema.optionalKey(Schema.String),
+  surfaceContainer: Schema.optionalKey(Schema.String),
+  surfaceContainerHigh: Schema.optionalKey(Schema.String),
+  onSurface: Schema.optionalKey(Schema.String),
+  onSurfaceVariant: Schema.optionalKey(Schema.String),
+  outlineVariant: Schema.optionalKey(Schema.String),
+  primary: Schema.optionalKey(Schema.String),
+  error: Schema.optionalKey(Schema.String),
+});
+
+/** The phone's dynamic color, or `null` where there's none or it's off. */
+export const AndroidThemeMessage = Schema.Struct({
+  colors: Schema.NullOr(
+    Schema.Struct({ light: AndroidSchemeColors, dark: AndroidSchemeColors }),
+  ),
+});
+
+export interface AndroidThemeMessage extends Schema.Schema.Type<
+  typeof AndroidThemeMessage
+> {}
+
+/** Where push stands, as the PWA's `pushState` reports it. */
+export const ShellPushState = Schema.Literals([
+  "unsupported",
+  "default",
+  "denied",
+  "subscribed",
+]);
+
+export type ShellPushState = Schema.Schema.Type<typeof ShellPushState>;
+
+/** What the shell reports about itself. */
+export const ShellInfo = Schema.Struct({
+  /** True in debug builds. */
+  dev: Schema.Boolean,
+  /** The shell's version, from the synced copy. */
+  version: Schema.String,
+});
+
+export interface ShellInfo extends Schema.Schema.Type<typeof ShellInfo> {}
+
+/**
+ * Whether the app may reach the local network: `granted` (or not gated,
+ * before Android 17), `denied`, or `undeclared` when the app's manifest
+ * lacks ACCESS_LOCAL_NETWORK.
+ */
+export const LocalNetworkState = Schema.Literals([
+  "granted",
+  "denied",
+  "undeclared",
+]);
+
+export type LocalNetworkState = Schema.Schema.Type<typeof LocalNetworkState>;
+
+/** One mDNS service, resolved. */
+export const DiscoveredService = Schema.Struct({
+  /** The instance name, such as `Office PC`. */
+  name: Schema.String,
+  type: Schema.String,
+  /** The `.local` hostname, on Android 17 and up. */
+  hostname: Schema.NullOr(Schema.String),
+  /** An address ready for a URL, IPv4 first, IPv6 in brackets. */
+  host: Schema.NullOr(Schema.String),
+  addresses: Schema.Array(Schema.String),
+  port: Schema.Number,
+  /** The TXT record's attributes, `null` for one with no value. */
+  txt: Schema.Record(Schema.String, Schema.NullOr(Schema.String)),
+});
+
+export interface DiscoveredService extends Schema.Schema.Type<
+  typeof DiscoveredService
+> {}
+
+/**
+ * How `discoverServices` finds them: `picker` asks the person to choose one
+ * in the system's picker, which grants the app that device alone; `browse`
+ * lists every service, asking for the local network permission first. Left
+ * out, it browses when it may and shows the picker otherwise.
+ */
+export const DiscoveryMode = Schema.Literals(["picker", "browse"]);
+
+export type DiscoveryMode = Schema.Schema.Type<typeof DiscoveryMode>;
+
+/**
+ * The shell's requests, each with the schema its reply is read with. The
+ * Kotlin side answers the same names.
+ */
+export const mobileRequests = {
+  info: ShellInfo,
+  /** Opens a URL in the browser or the app that handles it. */
+  openExternal: Schema.Boolean,
+  /** A system notification when the config turns them on, otherwise false. */
+  notify: Schema.Boolean,
+  /** The phone's dynamic color, when the config passes it on. */
+  androidTheme: AndroidThemeMessage,
+  /** Registers for UnifiedPush and posts the endpoint through the push contract. */
+  subscribePush: ShellPushState,
+  unsubscribePush: Schema.Boolean,
+  pushState: ShellPushState,
+  /** Asks for local network access where Android gates it. */
+  localNetwork: LocalNetworkState,
+  /** Finds mDNS services of a type, such as `_http._tcp`. */
+  discoverServices: Schema.Array(DiscoveredService),
+  /** Scans a QR code with the camera: its text, or `null` when cancelled. */
+  scanQr: Schema.NullOr(Schema.String),
+} as const;
+
+/** The shell's messages, each with the schema its data is read with. */
+export const mobileMessages = {
+  notice: Notice,
+  /** A deep link or App Link the app was opened with. */
+  deepLink: DeepLink,
+  /** A share from another app. */
+  share: ShellShare,
+  /** The phone's dynamic color changed, such as with a new wallpaper. */
+  androidTheme: AndroidThemeMessage,
+} as const;
+
+/**
+ * The wire format. The view sends `request`; the shell answers each with a
+ * `reply` carrying its `id`, and sends `message` whenever it has news.
+ */
+export const BridgeRequest = Schema.Struct({
+  type: Schema.Literal("request"),
+  id: Schema.Number,
+  name: Schema.String,
+  params: Schema.optionalKey(Schema.Json),
+});
+
+export interface BridgeRequest extends Schema.Schema.Type<
+  typeof BridgeRequest
+> {}
+
+export const BridgeReply = Schema.Struct({
+  type: Schema.Literal("reply"),
+  id: Schema.Number,
+  ok: Schema.Boolean,
+  value: Schema.optionalKey(Schema.Json),
+  error: Schema.optionalKey(Schema.String),
+});
+
+export interface BridgeReply extends Schema.Schema.Type<typeof BridgeReply> {}
+
+export const BridgeMessage = Schema.Struct({
+  type: Schema.Literal("message"),
+  name: Schema.String,
+  data: Schema.optionalKey(Schema.Json),
+});
+
+export interface BridgeMessage extends Schema.Schema.Type<
+  typeof BridgeMessage
+> {}
+
+const decodeIncoming = Schema.decodeUnknownOption(
+  Schema.fromJsonString(Schema.Union([BridgeReply, BridgeMessage])),
+);
+
+/** Reads what the shell sent, or `undefined` when it isn't bridge JSON. */
+export const decodeIncomingText = (
+  text: string,
+): BridgeReply | BridgeMessage | undefined =>
+  Option.getOrUndefined(decodeIncoming(text));

package/src/config.ts

@@ -0,0 +1,109 @@
+/**
+ * An app's `mobile.config`: every default the Android shell gives a
+ * Groundwork app, each on unless the config turns it off, so an empty config
+ * gives all of them. Shared by the view and, as JSON, the Kotlin shell.
+ */
+
+/** The text the shell's defaults show, for an app in another language. */
+export interface MobileLabels {
+  /** The notification channel for the app's notices. Defaults to `Notifications`. */
+  readonly notifications?: string;
+  /** The channel for ongoing work. Defaults to `Ongoing`. */
+  readonly ongoing?: string;
+  /** Defaults to `Download finished`. */
+  readonly downloadFinished?: string;
+}
+
+export type ResolvedMobileLabels = Required<MobileLabels>;
+
+export interface MobileConfig {
+  /**
+   * A hosted page to open instead of the bundled build, such as a service's
+   * own web UI, for an app that's a remote for a service elsewhere. Its
+   * origin may use the bridge. Without it the shell opens the bundled build.
+   */
+  readonly url?: string;
+  /**
+   * Origins besides the app's own whose pages may use the bridge, such as a
+   * paired service. The bundled app's origin is always allowed.
+   */
+  readonly origins?: readonly string[];
+  /** Shares from other apps, delivered as a `gw-share` event. */
+  readonly shares?: boolean;
+  /** System notifications from the view and from pushes. */
+  readonly notifications?: boolean;
+  /** Pushes through UnifiedPush, with the embedded FCM distributor as the fallback. */
+  readonly push?: boolean;
+  /** Passes the app's deep links and App Links to the view. */
+  readonly deepLinks?: boolean;
+  /** Links outside the allowed origins open in the browser. */
+  readonly externalLinks?: boolean;
+  /** Schemes besides http(s) that open outside the app. Defaults to `mailto` and `tel`. */
+  readonly externalSchemes?: readonly string[];
+  /** Back steps through the page's history before leaving the app. */
+  readonly back?: boolean;
+  /** Downloads go to the system's Downloads, with a notice when they finish. */
+  readonly downloads?: boolean;
+  /** The camera and microphone, when the page asks and the person allows it. */
+  readonly media?: boolean;
+  /** The file chooser for `<input type="file">`. */
+  readonly files?: boolean;
+  /**
+   * Passes the phone's dynamic color to the view, and every change.
+   * `pageTheme` offers it and uses it once it's picked.
+   */
+  readonly androidTheme?: boolean;
+  /** The WebView's dev tools through Chrome, in debug builds only. */
+  readonly devTools?: boolean;
+  /** The text the defaults show. English by default. */
+  readonly labels?: MobileLabels;
+}
+
+/** Every option filled in. */
+export interface ResolvedMobileConfig {
+  readonly url: string | null;
+  readonly origins: readonly string[];
+  readonly shares: boolean;
+  readonly notifications: boolean;
+  readonly push: boolean;
+  readonly deepLinks: boolean;
+  readonly externalLinks: boolean;
+  readonly externalSchemes: readonly string[];
+  readonly back: boolean;
+  readonly downloads: boolean;
+  readonly media: boolean;
+  readonly files: boolean;
+  readonly androidTheme: boolean;
+  readonly devTools: boolean;
+  readonly labels: ResolvedMobileLabels;
+}
+
+/** Types a config in the app's `mobile.config.ts`. */
+export const defineMobileConfig = (config: MobileConfig = {}): MobileConfig =>
+  config;
+
+/** Fills in the defaults. */
+export const resolveConfig = (
+  config: MobileConfig = {},
+): ResolvedMobileConfig => ({
+  url: config.url ?? null,
+  origins: config.origins ?? [],
+  shares: config.shares ?? true,
+  notifications: config.notifications ?? true,
+  push: config.push ?? true,
+  deepLinks: config.deepLinks ?? true,
+  externalLinks: config.externalLinks ?? true,
+  externalSchemes: config.externalSchemes ?? ["mailto", "tel"],
+  back: config.back ?? true,
+  downloads: config.downloads ?? true,
+  media: config.media ?? true,
+  files: config.files ?? true,
+  androidTheme: config.androidTheme ?? true,
+  devTools: config.devTools ?? true,
+  labels: {
+    notifications: "Notifications",
+    ongoing: "Ongoing",
+    downloadFinished: "Download finished",
+    ...config.labels,
+  },
+});

package/src/view.ts

@@ -0,0 +1,399 @@
+/**
+ * The view half of `@timmo001/groundwork-mobile`: connects the page to the
+ * Android shell over the bridge the shell injects, and falls back to the
+ * PWA floor's web APIs without one, so one app runs in both. Shares arrive
+ * as `gw-share` and deep links as `gw-deep-link` either way.
+ *
+ *   import mobileConfig from "../mobile.config.ts";
+ *   import pwaConfig from "../pwa.config.ts";
+ *
+ *   const mobile = await connectMobile(mobileConfig, {
+ *     pwa: pwaConfig,
+ *     onShare: (share) => openDraft(share),
+ *     onAndroidTheme: (colors) => void page.setAndroidTheme(colors),
+ *   });
+ *
+ *   // The app's own request, answered by its own Kotlin handler
+ *   const battery = await mobile.call("battery", Schema.Number);
+ */
+import {
+  connectPwa,
+  pushState,
+  subscribePush,
+  unsubscribePush,
+  type Pwa,
+  type PwaConfig,
+  type Share,
+} from "@timmo001/groundwork-pwa/view";
+import { Option, Schema } from "effect";
+
+import {
+  AndroidThemeMessage,
+  bridgeObjectName,
+  decodeIncomingText,
+  DeepLink,
+  mobileRequests,
+  Notice,
+  ShellShare,
+  type BridgeMessage,
+  type DiscoveredService,
+  type DiscoveryMode,
+  type LocalNetworkState,
+  type ShellInfo,
+  type ShellPushState,
+} from "./bridge.ts";
+import {
+  resolveConfig,
+  type MobileConfig,
+  type ResolvedMobileConfig,
+} from "./config.ts";
+
+export * from "./bridge.ts";
+
+export * from "./config.ts";
+
+/** The object `WebViewCompat.addWebMessageListener` injects. */
+export interface ShellObject {
+  readonly postMessage: (text: string) => void;
+  onmessage: ((event: { readonly data: string }) => void) | null;
+}
+
+declare global {
+  var groundworkShell: ShellObject | undefined;
+}
+
+/** Where the app subscribes to a service's pushes, in the shell or as a PWA. */
+export interface MobilePushOptions {
+  readonly service: string;
+  readonly client: {
+    readonly id: string;
+    readonly name: string;
+    readonly platform: "web" | "android";
+  };
+  readonly headers?: Readonly<Record<string, string>>;
+}
+
+/** What `connectMobile` sets up. */
+export interface ConnectMobileOptions {
+  /** The PWA config, for the floor's service worker, install and share target. */
+  readonly pwa?: PwaConfig;
+  /** Called with each share, from the shell or the share target. */
+  readonly onShare?: (share: Share) => void;
+  /** Called with each deep link the shell opens the app with. */
+  readonly onDeepLink?: (url: string) => void;
+  /**
+   * Called with the phone's dynamic color once connected and on every
+   * change, or `null` where there's none. Pass it to `pageTheme`'s
+   * `setAndroidTheme`.
+   */
+  readonly onAndroidTheme?: (colors: AndroidThemeMessage["colors"]) => void;
+  /** Called with a notice the shell sends, or one that can't be a notification. */
+  readonly onNotice?: (notice: Notice) => void;
+  /**
+   * Called with each message the app's own Kotlin sends, by name, with its
+   * JSON data for the app to parse with its own schema.
+   */
+  readonly onMessage?: (name: string, data: Schema.Json) => void;
+}
+
+/** The page's connection, to the shell or the PWA floor. */
+export interface Mobile {
+  /** True inside the Android shell, false as a PWA or in a browser. */
+  readonly shell: boolean;
+  readonly config: ResolvedMobileConfig;
+  /** What the shell reports, or `undefined` outside it. */
+  readonly info: ShellInfo | undefined;
+  /** The PWA connection, when the app runs without the shell. */
+  readonly pwa: Pwa | undefined;
+  /**
+   * Calls one of the app's own Kotlin handlers and reads the reply with
+   * `reply`. Rejects outside the shell, or when the handler fails.
+   */
+  readonly call: <S extends Schema.ConstraintDecoder<unknown>>(
+    name: string,
+    reply: S,
+    params?: Schema.Json,
+  ) => Promise<S["Type"]>;
+  /** Opens a URL in the browser or the app that handles it. */
+  readonly openExternal: (url: string) => Promise<void>;
+  /** A system notification, or `onNotice` where there can't be one. */
+  readonly notify: (notice: Notice) => Promise<void>;
+  /** Subscribes to a service's pushes: UnifiedPush in the shell, Web Push outside. */
+  readonly subscribePush: (
+    options: MobilePushOptions,
+  ) => Promise<ShellPushState>;
+  readonly unsubscribePush: (options: MobilePushOptions) => Promise<void>;
+  readonly pushState: () => Promise<ShellPushState>;
+  /**
+   * Asks for local network access where Android gates it. Always `granted`
+   * outside the shell, where the browser decides.
+   */
+  readonly localNetwork: () => Promise<LocalNetworkState>;
+  /**
+   * Finds mDNS services of `type`, such as `_http._tcp`, for
+   * `timeoutMs` (3 seconds by default) when it browses. Rejects outside the shell.
+   */
+  readonly discoverServices: (options: {
+    readonly type: string;
+    readonly mode?: DiscoveryMode;
+    readonly timeoutMs?: number;
+  }) => Promise<readonly DiscoveredService[]>;
+  /**
+   * Scans a QR code with the shell's scanner, which needs no Google Play
+   * services: its text, or `undefined` when the person cancels. Rejects
+   * outside the shell, where `scanPairingLink` scans in the page.
+   */
+  readonly scanQr: (options?: {
+    readonly hint?: string;
+  }) => Promise<string | undefined>;
+}
+
+interface Waiting {
+  readonly resolve: (value: Schema.Json) => void;
+  readonly reject: (error: Error) => void;
+}
+
+/** The `discoverServices` request's params; a type so it stays JSON. */
+type DiscoveryParams = {
+  type: string;
+  mode?: DiscoveryMode;
+  timeoutMs?: number;
+};
+
+/** The `scanQr` request's params. */
+type ScanParams = { hint?: string };
+
+const read = <S extends Schema.ConstraintDecoder<unknown>>(
+  schema: S,
+  value: Schema.Json,
+): S["Type"] | undefined =>
+  Option.getOrUndefined(Schema.decodeUnknownOption(schema)(value));
+
+const noticeJson = Schema.encodeSync(Schema.toCodecJson(Notice));
+
+const pushParams = ({ service, client, headers = {} }: MobilePushOptions) => ({
+  service,
+  client: { id: client.id, name: client.name, platform: client.platform },
+  headers: { ...headers },
+});
+
+const dispatchShare = (share: Share) =>
+  window.dispatchEvent(new CustomEvent("gw-share", { detail: share }));
+
+const dispatchDeepLink = (link: DeepLink) =>
+  window.dispatchEvent(new CustomEvent("gw-deep-link", { detail: link }));
+
+/** The PWA floor, for a page outside the shell. */
+const connectFloor = (
+  config: ResolvedMobileConfig,
+  options: ConnectMobileOptions,
+): Mobile => {
+  const pwa =
+    options.pwa === undefined
+      ? undefined
+      : connectPwa(options.pwa, {
+          onShare: (share) => options.onShare?.(share),
+        });
+
+  const registration = async () => pwa?.worker;
+
+  return {
+    shell: false,
+    config,
+    info: undefined,
+    pwa,
+    call: async () => {
+      throw new Error(`There's no ${bridgeObjectName} outside the shell`);
+    },
+    openExternal: async (url) => {
+      window.open(url, "_blank", "noopener");
+    },
+    notify: async (notice) => {
+      const worker = await registration();
+
+      if (
+        !config.notifications ||
+        worker === undefined ||
+        Notification.permission !== "granted"
+      ) {
+        options.onNotice?.(notice);
+
+        return;
+      }
+
+      const shown: NotificationOptions = { data: { link: notice.link } };
+
+      if (notice.body !== undefined) shown.body = notice.body;
+
+      if (notice.tag !== undefined) shown.tag = notice.tag;
+
+      await worker.showNotification(notice.heading, shown);
+    },
+    subscribePush: async (push) => subscribePush(await registration(), push),
+    unsubscribePush: async (push) =>
+      unsubscribePush(await registration(), push),
+    pushState: async () => pushState(await registration()),
+    localNetwork: async () => "granted",
+    discoverServices: async () => {
+      throw new Error("Service discovery needs the Android shell");
+    },
+    scanQr: async () => {
+      throw new Error("The QR scanner needs the Android shell");
+    },
+  };
+};
+
+/**
+ * Connects to the shell when the page runs in it, or sets up the PWA floor
+ * with `options.pwa` when it doesn't.
+ */
+export const connectMobile = async (
+  mobileConfig: MobileConfig = {},
+  options: ConnectMobileOptions = {},
+): Promise<Mobile> => {
+  const config = resolveConfig(mobileConfig);
+  const shell = globalThis.groundworkShell;
+
+  if (shell === undefined) return connectFloor(config, options);
+
+  const pending = new Map<number, Waiting>();
+  let next = 0;
+
+  const send = (name: string, params?: Schema.Json) =>
+    new Promise<Schema.Json>((resolve, reject) => {
+      next += 1;
+      pending.set(next, { resolve, reject });
+      shell.postMessage(
+        JSON.stringify({ type: "request", id: next, name, params }),
+      );
+    });
+
+  const call = async <S extends Schema.ConstraintDecoder<unknown>>(
+    name: string,
+    reply: S,
+    params?: Schema.Json,
+  ): Promise<S["Type"]> =>
+    Schema.decodeUnknownPromise(reply)(await send(name, params));
+
+  const onMessage = ({ name, data = null }: BridgeMessage) => {
+    switch (name) {
+      case "notice": {
+        const notice = read(Notice, data);
+
+        if (notice !== undefined) options.onNotice?.(notice);
+
+        return;
+      }
+
+      case "deepLink": {
+        const link = read(DeepLink, data);
+
+        if (link === undefined) return;
+
+        options.onDeepLink?.(link.url);
+        dispatchDeepLink(link);
+
+        return;
+      }
+
+      case "share": {
+        const share = read(ShellShare, data);
+
+        if (share === undefined) return;
+
+        options.onShare?.(share);
+        dispatchShare(share);
+
+        return;
+      }
+
+      case "androidTheme": {
+        const theme = read(AndroidThemeMessage, data);
+
+        if (theme !== undefined) options.onAndroidTheme?.(theme.colors);
+
+        return;
+      }
+
+      default:
+        options.onMessage?.(name, data);
+    }
+  };
+
+  shell.onmessage = ({ data }) => {
+    const incoming = decodeIncomingText(data);
+
+    if (incoming === undefined) return;
+
+    if (incoming.type === "message") {
+      onMessage(incoming);
+
+      return;
+    }
+
+    const waiting = pending.get(incoming.id);
+
+    pending.delete(incoming.id);
+
+    if (incoming.ok) waiting?.resolve(incoming.value ?? null);
+    else
+      waiting?.reject(
+        new Error(incoming.error ?? "The shell refused the request"),
+      );
+  };
+
+  const info = await call("info", mobileRequests.info);
+
+  if (config.androidTheme && options.onAndroidTheme !== undefined) {
+    const { onAndroidTheme } = options;
+
+    void call("androidTheme", mobileRequests.androidTheme).then(({ colors }) =>
+      onAndroidTheme(colors),
+    );
+  }
+
+  return {
+    shell: true,
+    config,
+    info,
+    pwa: undefined,
+    call,
+    openExternal: async (url) => {
+      await call("openExternal", mobileRequests.openExternal, { url });
+    },
+    notify: async (notice) => {
+      const shown =
+        config.notifications &&
+        (await call("notify", mobileRequests.notify, noticeJson(notice)));
+
+      if (!shown) options.onNotice?.(notice);
+    },
+    subscribePush: (push) =>
+      call("subscribePush", mobileRequests.subscribePush, pushParams(push)),
+    unsubscribePush: async (push) => {
+      await call(
+        "unsubscribePush",
+        mobileRequests.unsubscribePush,
+        pushParams(push),
+      );
+    },
+    pushState: () => call("pushState", mobileRequests.pushState),
+    localNetwork: () => call("localNetwork", mobileRequests.localNetwork),
+    discoverServices: ({ type, mode, timeoutMs }) => {
+      const params: DiscoveryParams = { type };
+
+      if (mode !== undefined) params["mode"] = mode;
+
+      if (timeoutMs !== undefined) params["timeoutMs"] = timeoutMs;
+
+      return call("discoverServices", mobileRequests.discoverServices, params);
+    },
+    scanQr: async ({ hint } = {}) => {
+      const params: ScanParams = {};
+
+      if (hint !== undefined) params["hint"] = hint;
+
+      return (await call("scanQr", mobileRequests.scanQr, params)) ?? undefined;
+    },
+  };
+};