ignotum 0.0.13 → 0.0.15

package/src/client/bootstrap.ts

@@ -0,0 +1,110 @@
+import type { ExecutionSelection } from "@ignotum/contracts/platform";
+import { createElement, Fragment, render, type ComponentChildren } from "preact";
+import { useLayoutEffect, useState } from "preact/hooks";
+import { mountManagedSync } from "./sync.js";
+import type { ManagedBrowserClient } from "./managed-client.js";
+import { RouterContext, useRouterSnapshot } from "./router.js";
+// oxlint-disable-next-line anti-slop-effect/no-service-constructor-imports -- Each browser mount owns its router and releases it on disposal.
+import { RouterStore, type ClientRegistration } from "./router-store.js";
+
+import { Branch, LoadFailure } from "./route-boundaries.js";
+
+const RouterView = ({ router }: { readonly router: RouterStore }): ComponentChildren => {
+  const snapshot = useRouterSnapshot(router);
+  useLayoutEffect(() => {
+    router.rendered(snapshot.commit);
+  }, [router, snapshot]);
+  return createElement(
+    RouterContext.Provider,
+    { value: router },
+    snapshot.branch === undefined || snapshot.location === undefined
+      ? createElement("div", { role: "status" }, snapshot.failure === undefined ? "Loading…" : null)
+      : createElement(Branch, {
+          branch: snapshot.branch,
+          location: snapshot.location,
+          router,
+          failure: snapshot.failure,
+        }),
+    snapshot.failure !== undefined && snapshot.branch === undefined
+      ? createElement(LoadFailure, { failure: snapshot.failure, router })
+      : null,
+  );
+};
+
+const mounts = new WeakSet<Element>();
+
+const ManagedStatus = ({ client }: { readonly client: ManagedBrowserClient }) => {
+  const [snapshot, setSnapshot] = useState(client.upgrade.getSnapshot);
+  useLayoutEffect(
+    () => client.upgrade.subscribe(() => setSnapshot(client.upgrade.getSnapshot())),
+    [client],
+  );
+  if (snapshot.phase === "ready" && snapshot.recovery.length === 0) return null;
+  return createElement(
+    "aside",
+    {
+      "data-ignotum-update": snapshot.phase,
+      role: snapshot.phase === "error" ? "alert" : "status",
+    },
+    snapshot.message ?? (snapshot.phase === "connecting" ? "Connecting to the app…" : null),
+    snapshot.recovery.length === 0
+      ? null
+      : createElement(
+          "ul",
+          null,
+          snapshot.recovery.map((message) => createElement("li", { key: message }, message)),
+        ),
+    snapshot.phase === "error"
+      ? createElement("button", { type: "button", onClick: () => client.retry() }, "Reload app")
+      : null,
+    snapshot.recovery.length === 0
+      ? null
+      : createElement(
+          "button",
+          { type: "button", onClick: client.upgrade.dismissRecovery },
+          "Dismiss",
+        ),
+  );
+};
+
+/** The platform owns mounting. Generated registrations contain no Preact render/bootstrap code. */
+export const mountClient = (registration: ClientRegistration, selection: ExecutionSelection) => {
+  const root = window.document.getElementById("app");
+  if (root === null) throw new Error("Ignotum mount element is missing.");
+  if (mounts.has(root)) throw new Error("The Ignotum client is already mounted.");
+  const router = new RouterStore(registration, selection, window);
+  const managed = mountManagedSync(selection, window, {
+    stopAdmission: router.stopForUpgrade,
+    reload: router.upgrade,
+  });
+  router.setAdmission({
+    validate: managed.client.validate,
+    recoverLoad: managed.client.recoverLoad,
+  });
+  render(
+    createElement(
+      Fragment,
+      null,
+      createElement(ManagedStatus, { client: managed.client }),
+      createElement(RouterView, { router }),
+    ),
+    root,
+  );
+  const ready = managed.client
+    .whenReady()
+    .then((accepted) => (accepted ? router.start() : { status: "cancelled" as const }));
+  mounts.add(root);
+  let disposed = false;
+  return {
+    ready,
+    upgrade: () => managed.client.upgrade.require(),
+    dispose: () => {
+      if (disposed) return;
+      disposed = true;
+      mounts.delete(root);
+      router.dispose();
+      managed.dispose();
+      render(null, root);
+    },
+  };
+};

package/src/client/errors.ts

@@ -1,7 +1,7 @@
 /** @effect-diagnostics globalConsole:skip-file */
 import { Cause, Effect, ErrorReporter, Schema } from "effect";
 
-import { ErrorCode, FunctionAddress, Operation } from "@ignotum/contracts/runtime/sync";
+import { FunctionAddress } from "@ignotum/contracts/runtime/sync";
 
 export class ConnectionUnavailable extends Schema.TaggedError<ConnectionUnavailable>()(
   "ConnectionUnavailable",
@@ -11,10 +11,9 @@ export class ConnectionUnavailable extends Schema.TaggedError<ConnectionUnavaila
   },
 ) {}
 
-export class InvalidClientMessage extends Schema.TaggedError<InvalidClientMessage>()(
-  "InvalidClientMessage",
+export class PlatformUpgrading extends Schema.TaggedError<PlatformUpgrading>()(
+  "PlatformUpgrading",
   {
-    cause: Schema.Defect(),
     message: Schema.String,
   },
 ) {}
@@ -37,14 +36,21 @@ export class InvalidServerMessage extends Schema.TaggedError<InvalidServerMessag
 ) {}
 
 export class ServerError extends Schema.TaggedError<ServerError>()("ServerError", {
-  code: ErrorCode,
+  code: Schema.Literals([
+    "PlatformUpgrading",
+    "SessionExpired",
+    "InvalidMessage",
+    "Unavailable",
+    "InvalidArguments",
+    "InvocationIdConflict",
+    "ResourceLimitExceeded",
+  ]),
   message: Schema.String,
-  operation: Schema.optional(Operation),
 }) {}
 
 export const ClientInfrastructureError = Schema.Union([
+  PlatformUpgrading,
   ConnectionUnavailable,
-  InvalidClientMessage,
   InvalidMutationArguments,
   InvalidServerMessage,
   ServerError,

package/src/client/files.ts

@@ -11,6 +11,8 @@ import {
   type FileFormat,
   type FileValue,
 } from "@ignotum/contracts/schema/file";
+import type { FunctionAddress } from "@ignotum/contracts/runtime/sync";
+import { InvalidServerMessage, ConnectionUnavailable, InvalidMutationArguments } from "./errors.js";
 import { IdGenerator } from "@ignotum/shared/id";
 import { Effect, Predicate, Schema } from "effect";
 
@@ -167,3 +169,65 @@ export const applyFileGrants = (
   if (matched.size !== byId.size) throw new Error("A query file grant has no result value.");
   return granted;
 };
+
+export const uploadPreparedFiles = Effect.fn("uploadPreparedFiles")(function* (
+  nativeFiles: ReadonlyMap<FileId, File>,
+  uploads: ReadonlyArray<{ readonly id: FileId; readonly url?: string }>,
+  functionAddress: FunctionAddress,
+) {
+  const expected = new Set(nativeFiles.keys());
+  const received = new Set<string>();
+  const transfers: Array<{ readonly file: File; readonly url: string }> = [];
+  for (const upload of uploads) {
+    if (!expected.has(upload.id) || received.has(upload.id)) {
+      return yield* InvalidServerMessage.make({
+        cause: new Error(`Unexpected prepared file '${upload.id}'.`),
+        message: "The server returned invalid application file preparation data.",
+      });
+    }
+    received.add(upload.id);
+    const file = nativeFiles.get(upload.id);
+    if (file === undefined) {
+      return yield* InvalidServerMessage.make({
+        cause: new Error(`Missing native file '${upload.id}'.`),
+        message: "The server prepared an unknown application file.",
+      });
+    }
+    if (upload.url === undefined) continue;
+    transfers.push({ file, url: upload.url });
+  }
+  if (received.size !== expected.size) {
+    return yield* InvalidServerMessage.make({
+      cause: new Error("The server omitted a prepared file."),
+      message: "The server returned incomplete application file preparation data.",
+    });
+  }
+  yield* Effect.forEach(
+    transfers,
+    Effect.fn("SyncClient.uploadFile")(function* ({ file, url }) {
+      const response = yield* Effect.tryPromise({
+        try: (signal) =>
+          fetch(url, {
+            method: "PUT",
+            body: file,
+            headers: { "content-type": file.type },
+            signal,
+          }),
+        catch: (cause) =>
+          ConnectionUnavailable.make({
+            cause,
+            message: `File '${file.name}' could not be uploaded.`,
+          }),
+      });
+      if (!response.ok) {
+        const detail = yield* Effect.promise(() => response.text());
+        return yield* InvalidMutationArguments.make({
+          cause: new Error(detail),
+          function: functionAddress,
+          message: `File '${file.name}' was rejected by application storage.`,
+        });
+      }
+    }),
+    { concurrency: 3, discard: true },
+  );
+});

package/src/client/id.ts

@@ -108,11 +108,15 @@ export class BrowserSession extends Context.Service<
       );
 
       const readOutcome = () => {
-        const raw = globalThis.sessionStorage.getItem(outcomeKey);
-        if (raw !== null) {
-          const decoded = Schema.decodeUnknownOption(SessionOutcome)(raw);
-          if (Option.isSome(decoded)) state = { ...state, outcome: decoded.value };
-          globalThis.sessionStorage.removeItem(outcomeKey);
+        try {
+          const raw = globalThis.sessionStorage.getItem(outcomeKey);
+          if (raw !== null) {
+            const decoded = Schema.decodeUnknownOption(SessionOutcome)(raw);
+            if (Option.isSome(decoded)) state = { ...state, outcome: decoded.value };
+            globalThis.sessionStorage.removeItem(outcomeKey);
+          }
+        } catch {
+          // The authenticated session response remains valid when optional redirect storage is denied.
         }
       };
       const parameters = () => {

package/src/client/image.ts

@@ -0,0 +1,28 @@
+import { createElement, type JSX } from "preact";
+
+declare const ImageSourceTypeId: unique symbol;
+
+/** A compiler-provided reference to an imported image. */
+export interface ImageSource {
+  readonly type: "ImageSource";
+  readonly url: string;
+  readonly [ImageSourceTypeId]: true;
+}
+
+export type ImageProps = Omit<
+  JSX.ImgHTMLAttributes<HTMLImageElement>,
+  "alt" | "src" | "srcSet" | "srcset"
+> & {
+  readonly src: ImageSource;
+  readonly alt: string;
+};
+
+/** Renders an imported image. */
+export const Image = ({ src, alt, ...attributes }: ImageProps): JSX.Element =>
+  createElement("img", { ...attributes, src: src.url, alt });
+
+/** @internal Creates an image reference from a compiler-resolved URL. */
+export const createImageSource = (url: string): ImageSource => {
+  // SAFETY: This factory constructs the complete runtime representation; the brand exists only in types.
+  return { type: "ImageSource", url } as ImageSource;
+};

package/src/client/index.ts

@@ -20,8 +20,8 @@ export { useId, useMutation, usePaginatedQuery, useQuery } from "./hooks.js";
 export type { PaginatedQueryOptions, PaginatedQueryValue, PaginationStatus } from "./hooks.js";
 export { Query } from "./query.js";
 export type { QuerySkip } from "./query.js";
-export { app } from "./app.js";
-export type { AppDefinition } from "./app.js";
+export { Image } from "./image.js";
+export type { ImageProps, ImageSource } from "./image.js";
 
 export {
   Component,
@@ -101,3 +101,26 @@ export type { Dispatch, Reducer, StateUpdater } from "preact/hooks";
 
 export type { User, UserId, ProfileField } from "@ignotum/contracts/id";
 export type { IdResult, IdOptions } from "./hooks.js";
+
+export type {
+  RouteInputs,
+  RouteProps,
+  RouteMatch,
+  RouteLocation,
+  NavigationResult,
+} from "./routes.js";
+
+export {
+  Link,
+  NavLink,
+  Redirect,
+  url,
+  useNavigate,
+  useRoute,
+  useMatch,
+  useLocation,
+  useNavigation,
+  useBlocker,
+} from "./router.js";
+
+export type { BlockerState } from "./router-store.js";