@crossworks/share-ui 0.230.43

package/LICENSE.md

@@ -0,0 +1,135 @@
+# License
+
+Mantle is **dual-licensed** by Cross Works Engineering (Pty) Ltd:
+
+1. **Public license — Functional Source License 1.1 (MIT Future), reproduced in
+   full below.** Free to use, self-host, modify, and run for any purpose that is
+   not a Competing Use (see the _Permitted Purpose_ clause). Two years after each
+   version is first published, that version automatically converts to the MIT
+   license.
+2. **Commercial license — see [`LICENSE-COMMERCIAL.md`](./LICENSE-COMMERCIAL.md).**
+   A paid agreement that lifts the FSL's _Competing Use_ restriction for partners
+   who want to embed Mantle in a commercial product or offer it as a service
+   during the two-year window. Contact **licensing@crossworks.engineering**.
+
+For a plain-language explanation of how the two licenses fit together and what the
+key terms mean, see [`LICENSING.md`](./LICENSING.md). Third-party open-source
+components bundled with Mantle are attributed in
+[`THIRD-PARTY-NOTICES.md`](./THIRD-PARTY-NOTICES.md).
+
+The "Change Date" for each release is **two years after that release is first made
+available** under this license; on the Change Date that release becomes available
+under the MIT license (the _Grant of Future License_ below).
+
+---
+
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Cross Works Engineering (Pty) Ltd
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@crossworks/share-ui",
+  "version": "0.230.43",
+  "description": "The server-rendered share surface — the /s/<token> presenters, view-payload contract, mini-app sandbox, and the few primitives they need. Lives in MANTLE (the server renders these), published for jackdaw to consume; may depend only on @mantle/{client-types,content-core} (the jackdaw-repo-split boundary).",
+  "exports": {
+    "./app-presenter": "./src/app-presenter.tsx",
+    "./draw-presenter": "./src/draw-presenter.tsx",
+    "./event-presenter": "./src/event-presenter.tsx",
+    "./file-presenter": "./src/file-presenter.tsx",
+    "./formula-calculator": "./src/formula-calculator.tsx",
+    "./formula-presenter": "./src/formula-presenter.tsx",
+    "./note-presenter": "./src/note-presenter.tsx",
+    "./table-presenter": "./src/table-presenter.tsx",
+    "./task-presenter": "./src/task-presenter.tsx",
+    "./view-payload": "./src/view-payload.ts",
+    "./app-sandbox": "./src/app-sandbox.tsx",
+    "./app-bridge-protocol": "./src/app-bridge-protocol.ts",
+    "./ui/button": "./src/ui/button.tsx",
+    "./ui/input": "./src/ui/input.tsx",
+    "./ui/label": "./src/ui/label.tsx",
+    "./lib/utils": "./src/lib/utils.ts",
+    "./page-outline": "./src/page-outline.tsx",
+    "./nav-items": "./src/nav-items.ts",
+    "./help-topics": "./src/help-topics.ts",
+    "./appearance": "./src/appearance.ts",
+    "./backgrounds": "./src/backgrounds.ts",
+    "./avatar": "./src/avatar.ts",
+    "./lib/themes": "./src/lib/themes.ts",
+    "./styles/themes.css": "./styles/themes.css",
+    "./styles/app.css": "./styles/app.css"
+  },
+  "dependencies": {
+    "@radix-ui/react-label": "^2.1.12",
+    "@radix-ui/react-slot": "^1.3.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "katex": "^0.18.1",
+    "lucide-react": "^1.25.0",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1",
+    "tailwind-merge": "^3.5.0",
+    "@dicebear/core": "^10.4.0",
+    "@dicebear/styles": "^10.3.0",
+    "@mantle/content-core": "npm:@crossworks/content-core@0.230.43",
+    "@mantle/client-types": "npm:@crossworks/client-types@0.230.43"
+  },
+  "peerDependencies": {
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "devDependencies": {
+    "@types/katex": "^0.16.8",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@types/node": "^22.20.1"
+  },
+  "license": "SEE LICENSE IN LICENSE.md",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/crossworks-engineering/mantle"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "themes:build": "node themes/generate.mjs",
+    "themes:check": "node themes/generate.mjs --check",
+    "themes:report": "node themes/generate.mjs --report"
+  }
+}

package/src/app-bridge-protocol.ts

@@ -0,0 +1,115 @@
+/**
+ * The postMessage contract between a running mini app (inside its sandboxed
+ * iframe) and the host page. Zero-dependency + client-safe so both the host
+ * `AppSandbox` component and the API routes can import it.
+ *
+ * The iframe-side counterpart is bundled into every app by `@mantle/app-build`
+ * (see its `@host` kit module); the two MUST agree on these shapes. Keep this
+ * the single source of truth and mirror any change there.
+ *
+ * Trust model: the iframe has an opaque origin (sandbox without
+ * allow-same-origin), so it holds no credentials and cannot call host APIs
+ * directly. Its ONLY channel is postMessage to the parent, which re-derives the
+ * owner from the session and enforces the per-app allowlist server-side.
+ */
+
+export const BRIDGE_VERSION = 1 as const;
+
+/** Requests the app sends UP to the host (await a matching BridgeRes by `id`). */
+export type BridgeReq =
+  | { v: 1; id: string; kind: 'tool.call'; slug: string; input: unknown }
+  | { v: 1; id: string; kind: 'db.query'; sql: string; params?: unknown[] }
+  | { v: 1; id: string; kind: 'db.exec'; sql: string; params?: unknown[] }
+  // Team-hub surface only: the shell answers from the /api/team/hub payload it
+  // already holds (data-down). Rejected with ok:false anywhere else (owner
+  // editor, ordinary shares) so hub apps degrade to a local preview.
+  | { v: 1; id: string; kind: 'hub.get' };
+
+/** Where a hub app can ask the /team shell to navigate (intent-up: the SHELL
+ *  owns chat and the briefing reader; the app can open them, never embed them). */
+export type HubNavTarget = 'chat' | { briefing: string } | { app: string };
+
+/** Fire-and-forget lifecycle events the app emits (no response expected). */
+export type BridgeEvt =
+  | { v: 1; kind: 'ready' }
+  | { v: 1; kind: 'resize'; height: number }
+  | { v: 1; kind: 'error'; message: string; stack?: string }
+  // Inspect mode (host-injected overlay → host): the user locked/cleared a
+  // selection (regionId = a data-app-region value, or null when cleared), or
+  // exited inspect via Esc (`inspect` with on:false).
+  | { v: 1; kind: 'select'; regionId: string | null; label?: string }
+  | { v: 1; kind: 'inspect'; on: boolean }
+  // Team-hub surface only; ignored anywhere else.
+  | { v: 1; kind: 'hub.nav'; target: HubNavTarget };
+
+/** Responses the host sends DOWN, correlated to a BridgeReq by `id`. */
+export type BridgeRes =
+  { v: 1; id: string; ok: true; output: unknown } | { v: 1; id: string; ok: false; error: string };
+
+/** Control messages the host pushes DOWN unprompted: agent region annotations,
+ *  and inspect-mode control (toggle select mode; set/clear the locked selection
+ *  from the host side, e.g. when the user clears the focus chip). */
+export type BridgeCtl =
+  | { v: 1; kind: 'annotate'; regions: { id: string; note?: string; severity?: 'info' | 'warn' }[] }
+  | { v: 1; kind: 'inspect'; on: boolean }
+  | { v: 1; kind: 'select'; regionId: string | null }
+  // Live theme: the host's <html> class + data-color-theme, mirrored onto the
+  // iframe's <html> so a dark/light or colour-theme switch restyles a RUNNING
+  // app (every theme's tokens are already in the linked stylesheet).
+  | { v: 1; kind: 'theme'; cls: string; colorTheme: string | null };
+
+export type FromApp = BridgeReq | BridgeEvt;
+export type FromHost = BridgeRes | BridgeCtl;
+
+export function isFromApp(m: unknown): m is FromApp {
+  return !!m && typeof m === 'object' && (m as { v?: unknown }).v === BRIDGE_VERSION;
+}
+
+/** The `hub.get` answer on the /team surface — everything the built-in hub
+ *  renders, handed to a designated hub app so it can render the same things its
+ *  own way. Mirrors the /api/team/hub response; every field is member-safe by
+ *  construction (sections are the owner's team-mode page shares, stats are
+ *  whitelisted coarse counts). `memberName` is display-grade — a hub app must
+ *  never build permission logic on it. */
+export type HubData = {
+  /** Brain's site-name pref; null ⇒ the app should fall back to its own label. */
+  siteName: string | null;
+  /** Signed-in member's display name (null when the contact has none). */
+  memberName: string | null;
+  version: string;
+  sections: {
+    token: string;
+    title: string;
+    icon: string | null;
+    summary: string | null;
+    updatedAt: string;
+    /** Token of the nearest team-shared ANCESTOR page, or null when top-level.
+     *  A hub app nests children under their parent; the built-in hub renders
+     *  only top-level (null) as cards. Every section is an openable share. */
+    parentToken: string | null;
+  }[];
+  /** Whitelisted coarse per-type node counts (zeros included — the app decides
+   *  what to hide). Same shape as the /api/team/hub `counts` field. */
+  counts: Record<string, number>;
+  /** The owner's OTHER team-shared apps (green published build), as launcher
+   *  cards — the designated hub app is excluded. Open one with
+   *  `host.hub.openApp(token)`; the shell renders it in the in-hub reader
+   *  (same /s/<token> iframe + "back to hub" as a briefing). */
+  apps: {
+    token: string;
+    title: string;
+    description: string | null;
+    updatedAt: string;
+  }[];
+};
+
+/** Narrow an unknown `hub.nav` target to a valid one — the shell must not
+ *  navigate on a malformed message from a (possibly buggy) app bundle. */
+export function isHubNavTarget(t: unknown): t is HubNavTarget {
+  if (t === 'chat') return true;
+  if (!t || typeof t !== 'object') return false;
+  const briefing = (t as { briefing?: unknown }).briefing;
+  if (typeof briefing === 'string' && briefing.length > 0) return true;
+  const app = (t as { app?: unknown }).app;
+  return typeof app === 'string' && app.length > 0;
+}

package/src/app-presenter.tsx

@@ -0,0 +1,25 @@
+'use client';
+
+/**
+ * Public presenter for a SHARED mini-app. The app gets the WHOLE viewport
+ * (h-dvh, no chrome) in share mode (shareToken) so the bundle + tool/db
+ * brokers resolve under /s/<token>/* — no owner session. How the app fills
+ * (or doesn't fill) that space is the app's own business; it owns its
+ * internal layout and scrolling.
+ */
+import { AppSandbox } from './app-sandbox';
+import type { ShareViewPayload } from './view-payload';
+
+export function AppPresenter({
+  view,
+  token,
+}: {
+  view: Extract<ShareViewPayload, { kind: 'app' }>;
+  token: string;
+}) {
+  return (
+    <div className="h-dvh w-full">
+      <AppSandbox appId={view.appId} shareToken={token} frame="viewport" />
+    </div>
+  );
+}