@lotics/app-sdk 0.91.0 → 0.91.1

package/dist/src/router.d.ts

@@ -1,4 +1,17 @@
 import { type RouteObject } from "react-router";
-export declare function AppRouter({ routes }: {
+/**
+ * The not-found screen's words. The SDK ships no locale, so an app whose reader
+ * does not read English passes its own — from `@lotics/ui`'s locale where the app
+ * uses the kit, from its own strings otherwise.
+ */
+export interface NotFoundWords {
+    /** Names the address that has no screen. Takes the path so the words may put
+     *  it anywhere the language needs it. */
+    message: (path: string) => string;
+    /** The label of the link back to the first screen. */
+    firstScreen: string;
+}
+export declare function AppRouter({ routes, notFound }: {
     routes: RouteObject[];
+    notFound?: NotFoundWords;
 }): import("react").JSX.Element;

package/dist/src/router.js

@@ -35,9 +35,14 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  *       { path: "/item/:id", element: <Detail /> },
  *     ]} />;
  *   }
+ *
+ * An address none of the routes claim renders the SDK's not-found screen rather
+ * than nothing — see {@link NotFoundScreen} and {@link withNotFound}. Its words
+ * are the `notFound` prop ({@link NotFoundWords}), because an app's reader reads
+ * the app's language and the SDK ships no locale.
  */
 import { useEffect } from "react";
-import { BrowserRouter, useLocation, useRoutes, } from "react-router";
+import { BrowserRouter, Link, useLocation, useRoutes, } from "react-router";
 import { isEmbedded, setUrlParams } from "./rpc.js";
 /** Host query key carrying the app's current screen, so it's shareable and the
  *  host can restore it on refresh. */
@@ -70,10 +75,70 @@ function HostScreenMirror() {
 function RoutedRoutes({ routes }) {
     return useRoutes(routes);
 }
-export function AppRouter({ routes }) {
+/*
+ * Shaped like the kit's `RegionState` — a centred message and one destination —
+ * and written in its tokens with literal fallbacks, so it takes the app's theme
+ * where `@lotics/ui/styles.css` is loaded and stays legible where it is not. It
+ * cannot BE `RegionState`: the SDK ships no kit component.
+ */
+const NOT_FOUND_ROOT = {
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: "var(--lotics-space-8, 8px)",
+    paddingBlock: "var(--lotics-space-48, 48px)",
+    paddingInline: "var(--lotics-space-16, 16px)",
+    textAlign: "center",
+    fontFamily: "var(--font-sans, system-ui, sans-serif)",
+};
+const NOT_FOUND_MESSAGE = {
+    margin: 0,
+    fontSize: "var(--lotics-text-sm, 14px)",
+    color: "var(--lotics-ink-muted, #71717a)",
+};
+const NOT_FOUND_LINK = {
+    fontSize: "var(--lotics-text-sm, 14px)",
+    color: "var(--lotics-accent, #2563eb)",
+};
+const NOT_FOUND_ENGLISH = {
+    message: (path) => `No screen at ${path}`,
+    firstScreen: "Go to the first screen",
+};
+/**
+ * What an app shows at an address none of its routes claim. Without it
+ * `useRoutes` matches nothing and the page renders EMPTY — no message and no
+ * console error — so a stale link or a typo reads as a crash.
+ */
+function NotFoundScreen({ home, words }) {
+    const { pathname } = useLocation();
+    return (_jsxs("div", { style: NOT_FOUND_ROOT, children: [
+            _jsx("p", { style: NOT_FOUND_MESSAGE, children: words.message(pathname) }), _jsx(Link, { to: home, style: NOT_FOUND_LINK, children: words.firstScreen })
+        ] }));
+}
+/**
+ * The catch-all, appended at EVERY level of the tree: a route with `children`
+ * is a layout, and a catch-all among those children is what keeps that layout's
+ * shell on screen instead of swapping the whole page for the message. An app
+ * that declares its own `*` still wins — react-router ranks equal matches by
+ * declaration order and ours is appended last.
+ */
+function withNotFound(routes, element) {
+    return [
+        ...routes.map((route) => route.children === undefined
+            ? route
+            : { ...route, children: withNotFound(route.children, element) }),
+        { path: "*", element },
+    ];
+}
+/** The screen the not-found sends the reader back to — the first one declared. */
+function firstScreenPath(routes) {
+    const first = routes.find((route) => route.path !== undefined && route.path !== "*");
+    return first?.path ?? "/";
+}
+export function AppRouter({ routes, notFound = NOT_FOUND_ENGLISH, }) {
     // `isEmbedded()` reads the `?lotics_host=` the host puts on the iframe src, so
     // it's known synchronously at first render.
     const embedded = isEmbedded();
-    return (_jsxs(BrowserRouter, { children: [embedded ? _jsx(HostScreenMirror, {}) : null, _jsx(RoutedRoutes, { routes: routes })
-        ] }));
+    return (_jsxs(BrowserRouter, { children: [embedded ? _jsx(HostScreenMirror, {}) : null, _jsx(RoutedRoutes, { routes: withNotFound(routes, _jsx(NotFoundScreen, { home: firstScreenPath(routes), words: notFound })) })] }));
 }

package/docs/ai.md

@@ -13,7 +13,7 @@ Don't run a structured extraction through `askAi` (the result is stranded in a c
 
 ## Declared agents — what `useAgentRun` runs
 
-An agent is **declared on the app server-side, by alias**, with the `set_app_agent` tool (removed with `remove_app_agent`). `lotics app deploy` ships code and queries only — it never binds agents. The `lotics.agents` map in `package.json` is a **read-only reflection** written by `lotics app pull`; hand-editing it does nothing. Invoking an alias that isn't bound fails with a "no agent alias" error naming `set_app_agent`. (After a deploy, the CLI warns about any manifest alias not bound on the server.)
+An agent is **declared on the app server-side, by alias**, with the `set_app_agent` tool (removed with `remove_app_agent`) — the only verb that creates a binding, so no deploy binds an alias the app does not already have. A deploy does push an alias it has: the prose in `src/agents/<alias>.md` and the authored `inputs`/`outputs` in `package.json#lotics.agents.<alias>` go through `set_app_agent` whenever either differs from the live row, before the bundle ships. Every other key of that map is a reflection `lotics app pull` refreshes and no verb sends, so replaying a stale snapshot cannot revert a grant bound elsewhere. Invoking an alias that isn't bound fails with a "no agent alias" error naming `set_app_agent`. (After a deploy, the CLI warns about any manifest alias not bound on the server.)
 
 A declaration carries:
 

package/docs/mutations.md

@@ -29,10 +29,9 @@ const result = await createOrder({ customer_id, quantity: 3 });
   owner's** authority (never the viewer's — see [security](./security.md) for attribution,
   privilege gates, and public-app semantics).
 - Binding is server-side (`set_app_workflow`, or `lotics app workflow set <alias>` from the
-  app project). `lotics app deploy` ships code, queries, and capabilities — it never binds
-  workflows.
-  The `package.json#lotics.workflows` map is a *pulled reflection* of the live bindings, used
-  purely to type `useWorkflow` (below); hand-editing it changes nothing on the server.
+  app project), and `lotics app deploy` calls it: `package.json#lotics.workflows.<alias>` plus
+  `src/workflows/<alias>.ts` ARE the source of a binding, so an alias committed to the repo is
+  one the next clone ships. The declaration also types `useWorkflow` (below).
 - Invoking an alias that is not bound resolves with `status: "error"` and a message naming
   the missing binding.
 - Anonymous visitors to a publicly shared app can invoke workflows too; the triggering
@@ -204,11 +203,13 @@ if (r.status === "success" && r.data) {
 
 ## Declaring workflow inputs
 
-An alias's declaration is `{ workflow_id, inputs?, outputs? }`. `inputs` maps each input name
-to a typed declaration; it is authored when the workflow is bound (`set_app_workflow` /
-`lotics app workflow set` reads it from `package.json#lotics.workflows.<alias>`), and the
-schema the body was verified against is canonical — the manifest reflection cannot silently
-weaken it. It drives three things at once: compile-time typing of the `useWorkflow` payload,
+An alias's declaration is `{ inputs?, outputs?, workflow_id? }` — `workflow_id` is the server's
+half, stamped by the first bind, so an alias an author has only just written carries none.
+`inputs` maps each input name to a typed declaration; it is authored beside the body and
+travels with it (`set_app_workflow` / `lotics app workflow set` reads it from
+`package.json#lotics.workflows.<alias>`, and a deploy pushes a declaration that has moved), and
+the schema the body was verified against is canonical — a manifest edit that reaches no push
+weakens nothing. It drives three things at once: compile-time typing of the `useWorkflow` payload,
 compile-time typing of `trigger.app_workflow.inputs.*` inside the body, and runtime payload
 validation at the execute boundary.
 
@@ -278,7 +279,7 @@ When the alias declares `inputs`, the server validates the payload before the wo
   added after authoring is accepted, a removed one rejected
   (`select input "<path>" value "<v>" is not one of field "<key>"'s current options`) with no
   redeploy. A `field` that doesn't exist or names a non-select field is rejected at bind time
-  (`lotics app workflow set` / `set_app_workflow`; `lotics app deploy` never binds workflows) with
+  (`lotics app workflow set` / `set_app_workflow`, which a deploy calls for a declaration it holds) with
   `select input references field "<key>", which does not exist in this workspace` /
   `… which is a <type> field, not a select`. Prefer `field` for any select backed by a real
   field; keep `options` for a fixed enum the app owns. Populate pickers from `useFieldOptions`

package/docs/navigation_and_state.md

@@ -63,6 +63,28 @@ routes, and splats all work. Inside the tree, use react-router normally:
   (`^7 || ^8` — the canonical package; the `react-router-dom` shim's tree also
   satisfies it) is an **optional peer dependency** — an app that imports the
   router entry must install it itself; nothing else in the SDK needs it.
+- **An address no route claims says so.** `AppRouter` appends a catch-all at
+  every level of the tree, so such a path renders a not-found screen — a
+  message naming the path and a link to the first route — instead of an empty
+  page, and a layout route keeps its shell around that message. Declaring your
+  own `{ path: "*" }` replaces it.
+- **The not-found screen speaks the app's language.** Its two strings default
+  to English; an app whose reader reads another language passes them as
+  `notFound`, next to `routes`:
+
+  ```tsx
+  <AppRouter
+    routes={routes}
+    notFound={{
+      message: (path) => `Không có màn hình ở ${path}`,
+      firstScreen: "Về màn hình đầu tiên",
+    }}
+  />
+  ```
+
+  `message` takes the path so the words may place it where the language needs
+  it. Where the app uses `@lotics/ui`, read both from the kit's locale — the
+  SDK ships none of its own.
 - **Limitation: element routing only.** `AppRouter` mounts a plain browser
   router, not a react-router *data* router — route `loader`/`action` fields
   are ignored, and `useLoaderData` **throws** ("must be used within a data

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.91.0",
+  "version": "0.91.1",
   "description": "Runtime SDK for Lotics custom-code apps \u2014 typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {