@cxxi-lab/hubbyware-sdk 0.0.0-stage → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Louis-Antoine Lumet
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,59 @@
1
+ import { createElement, StrictMode, type ComponentType } from 'react'
2
+ import { createRoot } from 'react-dom/client'
3
+ import type { HubbyPage } from '../protocol'
4
+ import { connect, register, usePath } from './sdk'
5
+
6
+ /**
7
+ * A hubby's front (docs/spec-hubby.md § 6): its pages, each a component; those with a `nav`
8
+ * section make its navigation (built by the host: the column on desktop, the bottom bar on phones).
9
+ */
10
+ export interface HubbyPageDefinition {
11
+ /** relative to the hubby: '/', '/settings', '/:id' */
12
+ path: string
13
+ component: ComponentType<{ params: Record<string, string> }>
14
+ title?: string
15
+ icon?: unknown
16
+ nav?: { section?: string }
17
+ }
18
+
19
+ export interface HubbyDefinition {
20
+ pages: HubbyPageDefinition[]
21
+ /** the sections' icons in the navigation, by title */
22
+ navSections?: Record<string, unknown>
23
+ }
24
+
25
+ export function defineHubby(definition: HubbyDefinition): HubbyDefinition {
26
+ return definition
27
+ }
28
+
29
+ /** @deprecated defineHubby: its SDK 2 name, kept for the hubbies built before the rename */
30
+ export const defineModule = defineHubby
31
+
32
+ /** The page matching a path, with its parameters (`:name` segments). */
33
+ export function match(pages: HubbyPageDefinition[], path: string): { page: HubbyPageDefinition, params: Record<string, string> } | null {
34
+ const parts = path.split('/').filter(Boolean)
35
+ for (const page of pages) {
36
+ const pattern = page.path.split('/').filter(Boolean)
37
+ if (pattern.length !== parts.length) continue
38
+ const params: Record<string, string> = {}
39
+ if (pattern.every((p, i) => p.startsWith(':') ? (params[p.slice(1)] = decodeURIComponent(parts[i]), true) : p === parts[i])) {
40
+ return { page, params }
41
+ }
42
+ }
43
+ return null
44
+ }
45
+
46
+ function Router({ definition }: { definition: HubbyDefinition }) {
47
+ const path = usePath()
48
+ const found = match(definition.pages, path)
49
+ if (!found) return createElement('p', { className: 'p-6 text-sm text-steel-400' }, `Nothing at ${path}`)
50
+ return createElement(found.page.component, { params: found.params })
51
+ }
52
+
53
+ /** Runs a hubby in its frame: announces its pages to the host, renders the one it is on. */
54
+ export function start(definition: HubbyDefinition): void {
55
+ const pages: HubbyPage[] = definition.pages.map(p => ({ path: p.path, title: p.title, icon: p.icon, section: p.nav ? (p.nav.section ?? '') : undefined }))
56
+ createRoot(document.getElementById('root')!).render(createElement(StrictMode, null, createElement(Router, { definition })))
57
+ connect()
58
+ register(pages, definition.navSections ?? {})
59
+ }
package/frame/index.ts ADDED
@@ -0,0 +1,8 @@
1
+ // @cxxi-lab/hubbyware-sdk/frame inside a hubby's frame (docs/spec-hubby.md § 6.3): what a hubby imports. Everything
2
+ // goes to the host by message; the frame has no token, no cookie, no access to the app.
3
+ // the base stylesheet, extracted into runtime.css at build (the frame page links it)
4
+ import './runtime.css'
5
+
6
+ export { call, collection, nav, notifications, settings, useInit, usePath, type Doc } from './sdk'
7
+ export { defineHubby, defineModule, start, type HubbyDefinition, type HubbyPageDefinition } from './hubby'
8
+ export { useBackHandler, useMediaQuery } from '@cxxi-lab/hubbyware-ui'
@@ -0,0 +1,16 @@
1
+ /* A hubby frame's base styles: the design tokens, the base, the design system's utilities (the
2
+ hubby's own utilities come with it, in its style.css). */
3
+ @layer theme, base, components, utilities;
4
+ @import "@cxxi-lab/hubbyware-ui/theme.css";
5
+ @import "tailwindcss/preflight.css" layer(base);
6
+ @import "tailwindcss/utilities.css" layer(utilities) source(none);
7
+ @source "../../../node_modules/@cxxi-lab/hubbyware-ui/src";
8
+ @source "./";
9
+ @import "@cxxi-lab/hubbyware-ui/fonts.css";
10
+
11
+ html, body {
12
+ background: var(--color-steel-900);
13
+ color: var(--color-white);
14
+ font-family: var(--font-display), sans-serif;
15
+ font-size: 14px;
16
+ }
package/frame/sdk.ts ADDED
@@ -0,0 +1,125 @@
1
+ import { useEffect, useState } from 'react'
2
+ import { onBackDepth, handleBack } from '@cxxi-lab/hubbyware-ui'
3
+ import { PROTOCOL, type Envelope, type GuestMessage, type HostMessage, type HubbyPage } from '../protocol'
4
+
5
+ /**
6
+ * The hubby SDK inside its frame (prototype): every call goes to the host by message and comes
7
+ * back as a promise. The frame has no token, no cookie, no access to the app.
8
+ */
9
+
10
+ let nextId = 1
11
+ const pending = new Map<number, { resolve: (v: unknown) => void, reject: (e: Error) => void }>()
12
+ const initListeners = new Set<(init: Extract<HostMessage, { type: 'init' }>) => void>()
13
+ const pathListeners = new Set<(path: string) => void>()
14
+ let init: Extract<HostMessage, { type: 'init' }> | null = null
15
+
16
+ function post(message: GuestMessage) {
17
+ const envelope: Envelope<GuestMessage> = { protocol: PROTOCOL, message }
18
+ // the host's origin can't be checked from an opaque origin: '*', the host checks the source
19
+ window.parent.postMessage(envelope, '*')
20
+ }
21
+
22
+ /** The app's theme and accent on this frame's root (the shared tokens are redefined under them). */
23
+ function applyTheme(theme: 'light' | 'dark' | undefined, accent: string | undefined) {
24
+ const root = document.documentElement
25
+ const value = theme ?? 'dark'
26
+ root.dataset.theme = value
27
+ root.style.colorScheme = value
28
+ if (accent && accent !== 'blue') root.dataset.accent = accent
29
+ else delete root.dataset.accent
30
+ }
31
+
32
+ window.addEventListener('message', event => {
33
+ if (event.source !== window.parent) return
34
+ const data = event.data as Envelope<HostMessage> | undefined
35
+ if (data?.protocol !== PROTOCOL) return
36
+ const m = data.message
37
+ if (m.type === 'result') {
38
+ const p = pending.get(m.id)
39
+ pending.delete(m.id)
40
+ if (!p) return
41
+ if (m.ok) p.resolve(m.value)
42
+ else p.reject(new Error(m.error))
43
+ }
44
+ else if (m.type === 'init') {
45
+ applyTheme(m.theme, m.accent)
46
+ init = m
47
+ initListeners.forEach(l => l(m))
48
+ }
49
+ else if (m.type === 'back') handleBack()
50
+ else if (m.type === 'path') pathListeners.forEach(l => l(m.path))
51
+ else if (m.type === 'theme') applyTheme(m.theme, m.accent)
52
+ })
53
+
54
+ /** A call to the host (the platform API, through it). */
55
+ export function call<T>(method: string, ...args: unknown[]): Promise<T> {
56
+ const id = nextId++
57
+ return new Promise<T>((resolve, reject) => {
58
+ pending.set(id, { resolve: resolve as (v: unknown) => void, reject })
59
+ post({ type: 'call', id, method, args })
60
+ })
61
+ }
62
+
63
+ export function useInit() {
64
+ const [value, setValue] = useState(init)
65
+ useEffect(() => {
66
+ initListeners.add(setValue)
67
+ setValue(init) // it may have come before this component listened
68
+ return () => { initListeners.delete(setValue) }
69
+ }, [])
70
+ return value
71
+ }
72
+
73
+ export function usePath(): string {
74
+ const [path, setPath] = useState(init?.path ?? '/')
75
+ useEffect(() => {
76
+ pathListeners.add(setPath)
77
+ const onInit = (m: { path: string }) => setPath(m.path)
78
+ initListeners.add(onInit)
79
+ if (init) setPath(init.path)
80
+ return () => { pathListeners.delete(setPath); initListeners.delete(onInit) }
81
+ }, [])
82
+ return path
83
+ }
84
+
85
+ export const nav = {
86
+ navigate(path: string) {
87
+ post({ type: 'navigate', path })
88
+ }
89
+ }
90
+
91
+ export interface Doc { id: string, [field: string]: unknown }
92
+
93
+ /** A collection of the hubby (the generic API, through the host). */
94
+ export function collection(name: string) {
95
+ return {
96
+ find: () => call<Doc[]>('collection.find', name),
97
+ create: (doc: Record<string, unknown>) => call<Doc>('collection.create', name, doc),
98
+ remove: (id: string) => call<void>('collection.remove', name, id)
99
+ }
100
+ }
101
+
102
+ export const settings = {
103
+ /** a real API call made by the host (measures a network round trip) */
104
+ account: () => call<Record<string, unknown>>('settings.account')
105
+ }
106
+
107
+ export const notifications = {
108
+ upsert: (n: { key: string, title: string, body?: string }) => call<void>('notifications.upsert', n)
109
+ }
110
+
111
+ /** Announces the hubby's pages to its host (it builds the navigation). */
112
+ export function register(pages: HubbyPage[], sections: Record<string, unknown>) {
113
+ post({ type: 'register', pages, sections })
114
+ }
115
+
116
+ /** Wires the frame to its host: ready, back depth, keys the app listens to (Ctrl+Alt…). */
117
+ export function connect() {
118
+ onBackDepth(depth => post({ type: 'back-depth', depth }))
119
+ window.addEventListener('keydown', e => {
120
+ if (e.ctrlKey || e.altKey || e.metaKey) {
121
+ post({ type: 'key', key: e.key, ctrl: e.ctrlKey, alt: e.altKey, shift: e.shiftKey, meta: e.metaKey })
122
+ }
123
+ })
124
+ post({ type: 'ready', at: performance.now() })
125
+ }
package/package.json CHANGED
@@ -1,6 +1,38 @@
1
1
  {
2
- "name": "@cxxi-lab/hubbyware-sdk",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
2
+ "name": "@cxxi-lab/hubbyware-sdk",
3
+ "version": "3.0.1",
4
+ "description": "The contract of Hubbyware's hubbies: the SDK a hubby builds on (provided by the host app at run time), and the SDK of the hubbies running isolated in their frame. Formerly @cxxi-lab/hub-sdk.",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "exports": {
8
+ ".": {
9
+ "types": "./types/index.d.ts"
10
+ },
11
+ "./frame": "./frame/index.ts",
12
+ "./protocol": "./protocol.ts",
13
+ "./version.json": "./version.json",
14
+ "./shared.json": "./shared.json",
15
+ "./package.json": "./package.json"
16
+ },
17
+ "files": [
18
+ "types",
19
+ "frame",
20
+ "protocol.ts",
21
+ "version.json",
22
+ "LICENSE",
23
+ "shared.json"
24
+ ],
25
+ "repository": {
26
+ "type": "git",
27
+ "url": "git+https://github.com/cxxi-lab/hubbyware-client.git",
28
+ "directory": "packages/hubbyware-sdk"
29
+ },
30
+ "publishConfig": {
31
+ "access": "public"
32
+ },
33
+ "peerDependencies": {
34
+ "@cxxi-lab/hubbyware-ui": "^0.5.0",
35
+ "react": "^19.2.4",
36
+ "react-dom": "^19.2.4"
37
+ }
38
+ }
package/protocol.ts ADDED
@@ -0,0 +1,47 @@
1
+ /**
2
+ * The messages between the app (host) and a hubby's frame (guest), both ways over postMessage.
3
+ * (docs/plan-hubby-architecture.md § 4, 4 ter): the guest runs in a sandboxed iframe with an
4
+ * opaque origin; it never gets a token, the host makes the API calls for it, within its scopes.
5
+ */
6
+
7
+ /** A page of the hubby, as it announces it (its navigation is built by the host). */
8
+ export interface HubbyPage {
9
+ /** relative to the hubby ('/', '/:id'…) */
10
+ path: string
11
+ title?: string
12
+ /** a FontAwesome icon definition (plain data) */
13
+ icon?: unknown
14
+ /** in the navigation, under this section (no title: not in the navigation) */
15
+ section?: string
16
+ }
17
+
18
+ /** Guest → host. */
19
+ export type GuestMessage =
20
+ | { type: 'ready', at: number }
21
+ | { type: 'register', pages: HubbyPage[], sections: Record<string, unknown> }
22
+ | { type: 'call', id: number, method: string, args: unknown[] }
23
+ | { type: 'back-depth', depth: number }
24
+ | { type: 'key', key: string, ctrl: boolean, alt: boolean, shift: boolean, meta: boolean }
25
+ | { type: 'navigate', path: string }
26
+
27
+ /** Host → guest. */
28
+ export type HostMessage =
29
+ /**
30
+ * `theme`, `accent`: the app's (a host from before themes sends none: dark, blue). `module`: the
31
+ * hubby's id under its SDK 2 name, still sent for the hubbies built before the rename (a host from
32
+ * before it sends `module` only).
33
+ */
34
+ | { type: 'init', hubby: string, module: string, path: string, phone: boolean, scopes: string[], theme?: 'light' | 'dark', accent?: string }
35
+ | { type: 'result', id: number, ok: true, value: unknown }
36
+ | { type: 'result', id: number, ok: false, error: string }
37
+ | { type: 'back' }
38
+ | { type: 'path', path: string }
39
+ /** the app's theme or accent changed */
40
+ | { type: 'theme', theme: 'light' | 'dark', accent?: string }
41
+
42
+ export const PROTOCOL = 'hubby/1'
43
+
44
+ export interface Envelope<M> {
45
+ protocol: typeof PROTOCOL
46
+ message: M
47
+ }
package/shared.json ADDED
@@ -0,0 +1,10 @@
1
+ {
2
+ "react": "react",
3
+ "react/jsx-runtime": "react-jsx-runtime",
4
+ "react-dom": "react-dom",
5
+ "react-router": "react-router",
6
+ "@fortawesome/react-fontawesome": "fontawesome-react",
7
+ "@fortawesome/fontawesome-svg-core": "fontawesome-core",
8
+ "@cxxi-lab/hubbyware-sdk": "sdk",
9
+ "@cxxi-lab/hubbyware-ui": "ui"
10
+ }