@cxxi-lab/hub-sdk 0.0.0-stage → 1.12.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Louis-Antoine Lumet
+
+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/frame/index.ts

@@ -0,0 +1,8 @@
+// @cxxi-lab/hub-sdk/frame inside a hubby's frame (docs/spec-module.md § 6.3): what a hubby imports. Everything
+// goes to the host by message; the frame has no token, no cookie, no access to the app.
+// the base stylesheet, extracted into runtime.css at build (the frame page links it)
+import './runtime.css'
+
+export { call, collection, nav, notifications, settings, useInit, usePath, type Doc } from './sdk'
+export { defineModule, start, type HubbyDefinition, type HubbyPageDefinition } from './module'
+export { useBackHandler, useMediaQuery } from '@cxxi-lab/hub-ui'

package/frame/module.tsx

@@ -0,0 +1,56 @@
+import { createElement, StrictMode, type ComponentType } from 'react'
+import { createRoot } from 'react-dom/client'
+import type { HubbyPage } from '../protocol'
+import { connect, register, usePath } from './sdk'
+
+/**
+ * A hubby's front (docs/spec-module.md § 6): its pages, each a component; those with a `nav`
+ * section make its navigation (built by the host: the column on desktop, the bottom bar on phones).
+ */
+export interface HubbyPageDefinition {
+	/** relative to the hubby: '/', '/settings', '/:id' */
+	path: string
+	component: ComponentType<{ params: Record<string, string> }>
+	title?: string
+	icon?: unknown
+	nav?: { section?: string }
+}
+
+export interface HubbyDefinition {
+	pages: HubbyPageDefinition[]
+	/** the sections' icons in the navigation, by title */
+	navSections?: Record<string, unknown>
+}
+
+export function defineModule(definition: HubbyDefinition): HubbyDefinition {
+	return definition
+}
+
+/** The page matching a path, with its parameters (`:name` segments). */
+export function match(pages: HubbyPageDefinition[], path: string): { page: HubbyPageDefinition, params: Record<string, string> } | null {
+	const parts = path.split('/').filter(Boolean)
+	for (const page of pages) {
+		const pattern = page.path.split('/').filter(Boolean)
+		if (pattern.length !== parts.length) continue
+		const params: Record<string, string> = {}
+		if (pattern.every((p, i) => p.startsWith(':') ? (params[p.slice(1)] = decodeURIComponent(parts[i]), true) : p === parts[i])) {
+			return { page, params }
+		}
+	}
+	return null
+}
+
+function Router({ definition }: { definition: HubbyDefinition }) {
+	const path = usePath()
+	const found = match(definition.pages, path)
+	if (!found) return createElement('p', { className: 'p-6 text-sm text-steel-400' }, `Nothing at ${path}`)
+	return createElement(found.page.component, { params: found.params })
+}
+
+/** Runs a hubby in its frame: announces its pages to the host, renders the one it is on. */
+export function start(definition: HubbyDefinition): void {
+	const pages: HubbyPage[] = definition.pages.map(p => ({ path: p.path, title: p.title, icon: p.icon, section: p.nav ? (p.nav.section ?? '') : undefined }))
+	createRoot(document.getElementById('root')!).render(createElement(StrictMode, null, createElement(Router, { definition })))
+	connect()
+	register(pages, definition.navSections ?? {})
+}

package/frame/runtime.css

@@ -0,0 +1,16 @@
+/* A hubby frame's base styles: the design tokens, the base, the design system's utilities (the
+   hubby's own utilities come with it, in its style.css). */
+@layer theme, base, components, utilities;
+@import "@cxxi-lab/hub-ui/theme.css";
+@import "tailwindcss/preflight.css" layer(base);
+@import "tailwindcss/utilities.css" layer(utilities) source(none);
+@source "../../../node_modules/@cxxi-lab/hub-ui/src";
+@source "./";
+@import "@cxxi-lab/hub-ui/fonts.css";
+
+html, body {
+	background: var(--color-steel-900);
+	color: var(--color-white);
+	font-family: var(--font-display), sans-serif;
+	font-size: 14px;
+}

package/frame/sdk.ts

@@ -0,0 +1,113 @@
+import { useEffect, useState } from 'react'
+import { onBackDepth, handleBack } from '@cxxi-lab/hub-ui'
+import { PROTOCOL, type Envelope, type GuestMessage, type HostMessage, type HubbyPage } from '../protocol'
+
+/**
+ * The hubby SDK inside its frame (prototype): every call goes to the host by message and comes
+ * back as a promise. The frame has no token, no cookie, no access to the app.
+ */
+
+let nextId = 1
+const pending = new Map<number, { resolve: (v: unknown) => void, reject: (e: Error) => void }>()
+const initListeners = new Set<(init: Extract<HostMessage, { type: 'init' }>) => void>()
+const pathListeners = new Set<(path: string) => void>()
+let init: Extract<HostMessage, { type: 'init' }> | null = null
+
+function post(message: GuestMessage) {
+	const envelope: Envelope<GuestMessage> = { protocol: PROTOCOL, message }
+	// the host's origin can't be checked from an opaque origin: '*', the host checks the source
+	window.parent.postMessage(envelope, '*')
+}
+
+window.addEventListener('message', event => {
+	if (event.source !== window.parent) return
+	const data = event.data as Envelope<HostMessage> | undefined
+	if (data?.protocol !== PROTOCOL) return
+	const m = data.message
+	if (m.type === 'result') {
+		const p = pending.get(m.id)
+		pending.delete(m.id)
+		if (!p) return
+		if (m.ok) p.resolve(m.value)
+		else p.reject(new Error(m.error))
+	}
+	else if (m.type === 'init') {
+		init = m
+		initListeners.forEach(l => l(m))
+	}
+	else if (m.type === 'back') handleBack()
+	else if (m.type === 'path') pathListeners.forEach(l => l(m.path))
+})
+
+/** A call to the host (the platform API, through it). */
+export function call<T>(method: string, ...args: unknown[]): Promise<T> {
+	const id = nextId++
+	return new Promise<T>((resolve, reject) => {
+		pending.set(id, { resolve: resolve as (v: unknown) => void, reject })
+		post({ type: 'call', id, method, args })
+	})
+}
+
+export function useInit() {
+	const [value, setValue] = useState(init)
+	useEffect(() => {
+		initListeners.add(setValue)
+		setValue(init) // it may have come before this component listened
+		return () => { initListeners.delete(setValue) }
+	}, [])
+	return value
+}
+
+export function usePath(): string {
+	const [path, setPath] = useState(init?.path ?? '/')
+	useEffect(() => {
+		pathListeners.add(setPath)
+		const onInit = (m: { path: string }) => setPath(m.path)
+		initListeners.add(onInit)
+		if (init) setPath(init.path)
+		return () => { pathListeners.delete(setPath); initListeners.delete(onInit) }
+	}, [])
+	return path
+}
+
+export const nav = {
+	navigate(path: string) {
+		post({ type: 'navigate', path })
+	}
+}
+
+export interface Doc { id: string, [field: string]: unknown }
+
+/** A collection of the module (the generic API, through the host). */
+export function collection(name: string) {
+	return {
+		find: () => call<Doc[]>('collection.find', name),
+		create: (doc: Record<string, unknown>) => call<Doc>('collection.create', name, doc),
+		remove: (id: string) => call<void>('collection.remove', name, id)
+	}
+}
+
+export const settings = {
+	/** a real API call made by the host (measures a network round trip) */
+	account: () => call<Record<string, unknown>>('settings.account')
+}
+
+export const notifications = {
+	upsert: (n: { key: string, title: string, body?: string }) => call<void>('notifications.upsert', n)
+}
+
+/** Announces the hubby's pages to its host (it builds the navigation). */
+export function register(pages: HubbyPage[], sections: Record<string, unknown>) {
+	post({ type: 'register', pages, sections })
+}
+
+/** Wires the frame to its host: ready, back depth, keys the app listens to (Ctrl+Alt…). */
+export function connect() {
+	onBackDepth(depth => post({ type: 'back-depth', depth }))
+	window.addEventListener('keydown', e => {
+		if (e.ctrlKey || e.altKey || e.metaKey) {
+			post({ type: 'key', key: e.key, ctrl: e.ctrlKey, alt: e.altKey, shift: e.shiftKey, meta: e.metaKey })
+		}
+	})
+	post({ type: 'ready', at: performance.now() })
+}

package/package.json

@@ -1,6 +1,37 @@
 {
-  "name": "@cxxi-lab/hub-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@cxxi-lab/hub-sdk",
+	"version": "1.12.0",
+	"description": "The contract of hub's modules: the SDK a module builds on (provided by the host app at run time), and the SDK of the modules running isolated in their frame.",
+	"license": "MIT",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./types/index.d.ts"
+		},
+		"./frame": "./frame/index.ts",
+		"./protocol": "./protocol.ts",
+		"./version.json": "./version.json",
+		"./shared.json": "./shared.json"
+	},
+	"files": [
+		"types",
+		"frame",
+		"protocol.ts",
+		"version.json",
+		"LICENSE",
+		"shared.json"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/cxxi-lab/hub-apps.git",
+		"directory": "packages/hub-sdk"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"peerDependencies": {
+		"@cxxi-lab/hub-ui": "^0.1.0",
+		"react": "^19.2.4",
+		"react-dom": "^19.2.4"
+	}
+}

package/protocol.ts

@@ -0,0 +1,40 @@
+/**
+ * The messages between the app (host) and a hubby's frame (guest), both ways over postMessage.
+ * (docs/plan-module-architecture.md § 4, 4 ter): the guest runs in a sandboxed iframe with an
+ * opaque origin; it never gets a token, the host makes the API calls for it, within its scopes.
+ */
+
+/** A page of the hubby, as it announces it (its navigation is built by the host). */
+export interface HubbyPage {
+	/** relative to the hubby ('/', '/:id'…) */
+	path: string
+	title?: string
+	/** a FontAwesome icon definition (plain data) */
+	icon?: unknown
+	/** in the navigation, under this section (no title: not in the navigation) */
+	section?: string
+}
+
+/** Guest → host. */
+export type GuestMessage =
+	| { type: 'ready', at: number }
+	| { type: 'register', pages: HubbyPage[], sections: Record<string, unknown> }
+	| { type: 'call', id: number, method: string, args: unknown[] }
+	| { type: 'back-depth', depth: number }
+	| { type: 'key', key: string, ctrl: boolean, alt: boolean, shift: boolean, meta: boolean }
+	| { type: 'navigate', path: string }
+
+/** Host → guest. */
+export type HostMessage =
+	| { type: 'init', module: string, path: string, phone: boolean, scopes: string[] }
+	| { type: 'result', id: number, ok: true, value: unknown }
+	| { type: 'result', id: number, ok: false, error: string }
+	| { type: 'back' }
+	| { type: 'path', path: string }
+
+export const PROTOCOL = 'hubby/1'
+
+export interface Envelope<M> {
+	protocol: typeof PROTOCOL
+	message: M
+}

package/shared.json

@@ -0,0 +1,10 @@
+{
+	"react": "react",
+	"react/jsx-runtime": "react-jsx-runtime",
+	"react-dom": "react-dom",
+	"react-router": "react-router",
+	"@fortawesome/react-fontawesome": "fontawesome-react",
+	"@fortawesome/fontawesome-svg-core": "fontawesome-core",
+	"@cxxi-lab/hub-sdk": "sdk",
+	"@cxxi-lab/hub-ui": "ui"
+}