@kennofizet/apphub-frontend 0.1.0

package/README.md

@@ -0,0 +1,84 @@
+# App Hub Frontend
+
+Vue 3 **Windows-style desktop** for App Hub. Modular apps run in draggable windows.
+
+## Modules (independent)
+
+| Module | Path | Role |
+|--------|------|------|
+| **desktop** | `src/modules/desktop` | Wallpaper, icons, taskbar, Start menu |
+| **window-manager** | `src/modules/window-manager` | Open / close / focus / minimize windows |
+| **app-store** | `src/modules/app-store` | Built-in **App Store** (default Hub app) |
+
+Each module has its own `index.js` and can be imported alone:
+
+```js
+import { AppHubDesktop } from '@kennofizet/apphub-frontend/modules/desktop'
+import { useWindowManager } from '@kennofizet/apphub-frontend/modules/window-manager'
+```
+
+## Install (host app)
+
+```bash
+npm install @kennofizet/apphub-frontend
+```
+
+```js
+import { createApp } from 'vue'
+import { installAppHubModule, AppHubDesktop } from '@kennofizet/apphub-frontend'
+
+const app = createApp(App)
+const hostApi = installAppHubModule(app, {
+  coreUrl: 'https://your-api/api/knf',
+  backendUrl: 'https://your-api/api/knf/apphub',
+  token: sessionTokenFromHost,
+  hostAccessSecret: import.meta.env.VITE_APPHUB_HOST_ACCESS_SECRET,
+  language: 'vi',
+  theme: 'dark',
+  themeToggle: false,
+  allowedRuntimeOrigins: ['https://publisher-app.example.com'],
+})
+```
+
+**Local dev:** `backendUrl` + `token` is enough on `localhost` — the package auto-relaxes origin checks.
+
+**Production:** Bootstrap auto-derives URLs from existing Laravel env (no extra App Hub vars):
+
+- Hub host → browser `Origin` on `GET /bootstrap` (where the Vue app runs)
+- Runtime API → `{APP_URL}/{KNF_CORE_API_PREFIX}/{APPHUB_API_PREFIX}` (Laravel backend)
+
+Set `APP_URL` to your Laravel API host. Hub SPA can be on a different origin (e.g. Vite `:3000` in dev, `apphub.` subdomain in prod) — bootstrap learns it from the request. Optional overrides: `hubOrigin`, `runtimePublicUrl`. Embed the Hub URL in your product iframe — do not mount Hub inside the product Vue app.
+
+`hostApi.grantBridgeScope`, `integrationDocsInternal` — host app only, not `inject()`.
+
+Hub shell components use `useAppHubHostApi()` from the package. The host token and `hostAccessSecret` stay in private module credentials — not in `inject('apphubOptions')` and not via `provide('apphubApi')`.
+
+### Who can read internal docs?
+
+| Role | Internal docs (`integration-docs/internal`)? |
+|------|---------------------------------------------|
+| End user on Hub desktop | No — use Guide or public `integration-docs` |
+| Publisher | No |
+| packages-core **zone/server manager** (settings in other packages) | **No** — that is not host integrator |
+| **Host team** embedding App Hub | Yes — `APPHUB_HOST_ACCESS_SECRET` + `hostAccessSecret` in `installAppHubModule` |
+
+Do not pass `hostAccessSecret` to every logged-in user. Only your host app build/config (dev/ops), never user login API.
+
+```vue
+<template>
+  <AppHubDesktop language="vi" theme="light" :theme-toggle="false" />
+</template>
+```
+
+Full-screen route example: `/apphub` → only `<AppHubDesktop />`.
+
+## UX
+
+- Desktop icons (double-click to open).
+- **App Store** icon is always on the desktop (install user apps).
+- On first load, App Store window opens automatically (`openAppStoreOnMount`, default `true`).
+- Installed apps from the store appear as new desktop icons (demo placeholder window until backend launch).
+
+## Verify
+
+Use `____TEST/test` frontend (manual `npm install` there). Do not run `npm install` inside `apphub-packages` per project rules.

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@kennofizet/apphub-frontend",
+  "version": "0.1.0",
+  "description": "App Hub Vue 3 UI — Windows-style desktop shell and modular apps (App Store default).",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "require": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./modules/desktop": "./src/modules/desktop/index.js",
+    "./modules/app-store": "./src/modules/app-store/index.js",
+    "./modules/window-manager": "./src/modules/window-manager/index.js"
+  },
+  "keywords": ["vue", "vue3", "apphub", "desktop", "frontend"],
+  "author": "KennoFizet",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.1.2",
+    "vue": "^3.2.0"
+  },
+  "peerDependencies": {
+    "vue": "^3.2.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}

package/src/api/coreApi.js

@@ -0,0 +1,25 @@
+import axios from 'axios'
+
+const REQUEST_TIMEOUT_MS = 30_000
+
+/**
+ * packages-core client (zones, auth) — same pattern as workpoint/rewardplay.
+ */
+export function createCoreApi(coreUrl, token) {
+  const baseURL = (coreUrl || '').replace(/\/$/, '')
+
+  const client = axios.create({
+    baseURL,
+    timeout: REQUEST_TIMEOUT_MS,
+    headers: {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      ...(token ? { 'X-Knf-Token': token } : {}),
+    },
+  })
+
+  return {
+    authCheck: () => client.get('/auth/check'),
+    getPlayerZones: () => client.get('/player/zones'),
+  }
+}

package/src/api/index.js

@@ -0,0 +1,80 @@
+import axios from 'axios'
+
+const REQUEST_TIMEOUT_MS = 30_000
+
+/**
+ * HTTP client for apphub-backend.
+ */
+export function createAppHubApi(backendUrl, token, options = {}) {
+  const baseURL = (backendUrl || '').replace(/\/$/, '')
+  const hostAccessSecret = options.hostAccessSecret || ''
+  const getZoneHeaderId = options.getZoneHeaderId
+
+  const client = axios.create({
+    baseURL,
+    timeout: REQUEST_TIMEOUT_MS,
+    headers: {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      ...(token ? { 'X-Knf-Token': token } : {}),
+    },
+  })
+
+  client.interceptors.request.use((config) => {
+    const zoneId = typeof getZoneHeaderId === 'function' ? getZoneHeaderId() : null
+    if (zoneId) {
+      config.headers = config.headers || {}
+      config.headers['X-Knf-Zone-Id'] = zoneId
+    }
+    return config
+  })
+
+  function bridgeHeaders(launchToken, appSlug) {
+    return {
+      'X-AppHub-Launch-Token': launchToken,
+      'X-AppHub-App-Slug': appSlug,
+    }
+  }
+
+  function hostHeaders() {
+    return hostAccessSecret ? { 'X-AppHub-Host-Access': hostAccessSecret } : {}
+  }
+
+  return {
+    bootstrap: () => client.get('/bootstrap'),
+    integrationDocs: () => client.get('/integration-docs'),
+    integrationDocsInternal: () =>
+      client.get('/integration-docs/internal', { headers: hostHeaders() }),
+    apps: (params) => client.get('/apps', { params }),
+    launch: (slug, payload) => client.post(`/apps/${encodeURIComponent(slug)}/launch`, payload ?? {}),
+    ping: (slug) => client.post(`/apps/${encodeURIComponent(slug)}/ping`),
+    verifyLaunchToken: (launchToken, appSlug) =>
+      client.post('/verify-launch-token', {
+        launch_token: launchToken,
+        ...(appSlug ? { app_slug: appSlug } : {}),
+      }),
+    usage: (slug, payload) =>
+      client.post(`/apps/${encodeURIComponent(slug)}/usage`, payload),
+    devApps: (params) => client.get('/dev/apps', { params }),
+    devInspectBundle: (slug) =>
+      client.get(`/dev/apps/${encodeURIComponent(slug)}/bundle-inspect`),
+    devDisableApp: (slug) =>
+      client.post(`/dev/apps/${encodeURIComponent(slug)}/disable`),
+    devSetAppStatus: (slug, status) =>
+      client.post(`/dev/apps/${encodeURIComponent(slug)}/status`, { status }),
+    registerApp: (formData) =>
+      client.post('/apps/register', formData, {
+        headers: { 'Content-Type': 'multipart/form-data' },
+        timeout: 120_000,
+      }),
+    appVersions: (slug) => client.get(`/apps/${encodeURIComponent(slug)}/versions`),
+    grantBridgeScope: (launchToken, scope) =>
+      client.post('/bridge/scopes', { launch_token: launchToken, scope }),
+    bridgeUser: (launchToken, appSlug) =>
+      client.get('/bridge/user', { headers: bridgeHeaders(launchToken, appSlug) }),
+    bridgeDesktopMessage: (launchToken, appSlug, payload) =>
+      client.post('/bridge/desktop/message', payload, {
+        headers: bridgeHeaders(launchToken, appSlug),
+      }),
+  }
+}

package/src/composables/createZoneContext.js

@@ -0,0 +1,156 @@
+import { computed, reactive } from 'vue'
+import {
+  loadStoredZone,
+  parseZonesFromResponse,
+  parseZonesMeta,
+  saveStoredZone,
+} from '../utils/zoneContext.js'
+
+function parseUserFromBootstrap(resp) {
+  const data = resp?.data?.data ?? resp?.data?.datas ?? resp?.data ?? {}
+  const user = data.user
+  if (!user || user.id == null) return null
+  return {
+    id: user.id,
+    name: user.name ?? String(user.id),
+  }
+}
+
+/**
+ * Hub session — user (apphub bootstrap) + zones (packages-core).
+ */
+export function createZoneContextState(getCoreApi, getHostApi, hooks = {}) {
+  const state = reactive({
+    user: { id: null, name: null },
+    zones: [],
+    selectedZoneId: null,
+    viewAllZones: false,
+    loading: false,
+    error: '',
+    timezone: null,
+    isManager: false,
+    authOk: false,
+  })
+
+  const selectedZone = computed(() =>
+    state.zones.find((z) => z.id === state.selectedZoneId) ?? null,
+  )
+
+  const activeZoneIds = computed(() => {
+    if (state.viewAllZones) {
+      return state.zones.map((z) => z.id).filter((id) => id != null)
+    }
+    return state.selectedZoneId != null ? [state.selectedZoneId] : []
+  })
+
+  function selectZone(zoneOrId) {
+    const id = typeof zoneOrId === 'object' ? zoneOrId?.id : zoneOrId
+    const zone = state.zones.find((z) => z.id === id)
+    if (!zone) return
+    state.selectedZoneId = zone.id
+    state.viewAllZones = false
+    saveStoredZone(zone)
+  }
+
+  function setViewAllZones(enabled) {
+    state.viewAllZones = !!enabled
+    if (!state.viewAllZones && state.selectedZoneId == null && state.zones.length) {
+      selectZone(state.zones[0])
+    }
+  }
+
+  function resolveInitialZone(list) {
+    const stored = loadStoredZone()
+    if (stored?.id && list.some((z) => z.id === stored.id)) {
+      state.selectedZoneId = stored.id
+      return
+    }
+    if (list.length === 1) {
+      selectZone(list[0])
+    } else if (list.length > 1 && state.selectedZoneId == null) {
+      selectZone(list[0])
+    }
+  }
+
+  async function refreshUser() {
+    if (hooks.ensureBootstrapSession) {
+      await hooks.ensureBootstrapSession()
+      return
+    }
+
+    const hostApi = getHostApi?.()
+    if (!hostApi?.bootstrap) return
+
+    try {
+      const res = await hostApi.bootstrap()
+      hooks.onBootstrap?.(res)
+      const user = parseUserFromBootstrap(res)
+      if (user) {
+        state.user.id = user.id
+        state.user.name = user.name
+      }
+    } catch {
+      /* keep previous user */
+    }
+  }
+
+  async function refreshZones() {
+    const api = getCoreApi?.()
+    if (!api?.getPlayerZones) {
+      state.error = 'no_core_api'
+      state.zones = []
+      return
+    }
+
+    state.error = ''
+    try {
+      if (api.authCheck) {
+        try {
+          const authRes = await api.authCheck()
+          state.authOk = authRes?.data?.success !== false
+        } catch {
+          state.authOk = false
+        }
+      }
+
+      const resp = await api.getPlayerZones()
+      const list = parseZonesFromResponse(resp)
+      const meta = parseZonesMeta(resp)
+      state.zones = list
+      state.timezone = meta.timezone
+      state.isManager = meta.isManager
+      resolveInitialZone(list)
+    } catch {
+      state.error = 'load_failed'
+      state.zones = []
+    }
+  }
+
+  async function refresh(options = {}) {
+    state.loading = true
+    try {
+      if (options.skipBootstrap) {
+        await refreshZones()
+      } else {
+        await Promise.all([refreshUser(), refreshZones()])
+      }
+    } finally {
+      state.loading = false
+    }
+  }
+
+  function getZoneHeaderId() {
+    if (state.viewAllZones || state.selectedZoneId == null) return null
+    return String(state.selectedZoneId)
+  }
+
+  return {
+    state,
+    selectedZone,
+    activeZoneIds,
+    selectZone,
+    setViewAllZones,
+    refresh,
+    getZoneHeaderId,
+  }
+}

package/src/composables/useAppHubHostApi.js

@@ -0,0 +1,24 @@
+import { getCurrentInstance } from 'vue'
+import { getAppHubStore } from '../moduleStore.js'
+
+export function resolveRootApp(instance = getCurrentInstance()) {
+  if (!instance) return null
+  return instance.appContext?.app ?? instance.app ?? null
+}
+
+export function getHostApiForApp(app) {
+  return getAppHubStore(app)?.facade ?? null
+}
+
+export function isBackendReadyForApp(app) {
+  const store = getAppHubStore(app)
+  return !!(store?.credentials?.backendUrl && store?.credentials?.token)
+}
+
+/**
+ * Host-only API — use in Hub shell components. Not provided via inject
+ * so publisher app code cannot access grantBridgeScope or internal docs.
+ */
+export function useAppHubHostApi() {
+  return getHostApiForApp(resolveRootApp())
+}

package/src/composables/useAppHubZoneContext.js

@@ -0,0 +1,11 @@
+import { inject } from 'vue'
+
+export const APPHUB_ZONE_CONTEXT_KEY = 'apphubZoneContext'
+
+export function useAppHubZoneContext() {
+  const ctx = inject(APPHUB_ZONE_CONTEXT_KEY, null)
+  if (!ctx) {
+    throw new Error('useAppHubZoneContext() requires installAppHubModule()')
+  }
+  return ctx
+}

package/src/composables/useDevOriginToggle.js

@@ -0,0 +1,40 @@
+import { computed, getCurrentInstance, inject } from 'vue'
+import { getAppHubStore } from '../moduleStore.js'
+import { saveDevFriendlyOriginsPreference } from '../utils/devOriginSettings.js'
+import { isLocalDevHostPage } from '../utils/originSafety.js'
+
+function reconcileAfterToggle(vueApp, enabled) {
+  import('../index.js').then(({ installAppHubModule }) => {
+    installAppHubModule(vueApp, { enforceDevFriendlyOrigins: enabled, isDevUser: true })
+  })
+}
+
+/** Dev-only localhost toggle — requires bootstrap is_dev_user (APPHUB_DEV_USER_IDS). */
+export function useDevOriginToggle() {
+  const moduleOptions = inject('apphubOptions', {})
+  const vueApp = getCurrentInstance()?.appContext?.app
+
+  const visible = computed(
+    () => moduleOptions?.isDevUser === true && isLocalDevHostPage(),
+  )
+
+  const devFriendlyOn = computed(
+    () => moduleOptions?.enforceDevFriendlyOrigins !== false,
+  )
+
+  function toggle() {
+    if (!vueApp || moduleOptions?.isDevUser !== true) return
+    const next = !devFriendlyOn.value
+    saveDevFriendlyOriginsPreference(next)
+    const store = getAppHubStore(vueApp)
+    if (store) {
+      store.options.enforceDevFriendlyOrigins = next
+      if (!next) {
+        store.options.hubOrigin = ''
+      }
+    }
+    reconcileAfterToggle(vueApp, next)
+  }
+
+  return { visible, devFriendlyOn, toggle }
+}

package/src/i18n/index.js

@@ -0,0 +1,16 @@
+import en from './translations/en.js'
+import vi from './translations/vi.js'
+import { resolveLang } from './resolveLang.js'
+
+const catalogs = { en, vi }
+
+export function t(key, lang = 'vi', params = {}) {
+  const code = resolveLang(lang)
+  let text = catalogs[code]?.[key] ?? catalogs.en?.[key] ?? String(key)
+  if (params && typeof params === 'object') {
+    Object.entries(params).forEach(([k, v]) => {
+      text = text.replace(new RegExp(`\\{${k}\\}`, 'g'), String(v ?? ''))
+    })
+  }
+  return text
+}

package/src/i18n/resolveLang.js

@@ -0,0 +1,6 @@
+/** Normalize language from prop, inject, or ref. */
+export function resolveLang(source, fallback = 'vi') {
+  if (typeof source === 'string' && source) return source
+  if (source && typeof source.value === 'string' && source.value) return source.value
+  return fallback
+}

package/src/i18n/resolveTheme.js

@@ -0,0 +1,30 @@
+const VALID = new Set(['dark', 'light'])
+
+/** Normalize theme from prop, inject, ref, or saved setting. Returns null when unset/auto. */
+export function resolveTheme(source, fallback = null) {
+  const read = (value) => {
+    if (typeof value !== 'string') return null
+    const code = value.trim().toLowerCase()
+    if (code === 'auto' || code === '') return null
+    return VALID.has(code) ? code : null
+  }
+
+  const direct = read(typeof source === 'string' ? source : null)
+  if (direct) return direct
+
+  if (source && typeof source === 'object' && 'value' in source) {
+    const fromRef = read(source.value)
+    if (fromRef) return fromRef
+  }
+
+  return read(fallback)
+}
+
+/** True when host passes theme via prop or installAppHubModule (not auto). */
+export function isThemeLocked(propTheme, injectTheme) {
+  return resolveTheme(propTheme) != null || resolveTheme(injectTheme) != null
+}
+
+export function normalizeTheme(value, fallback = 'dark') {
+  return resolveTheme(value, fallback) ?? fallback
+}