@makershq/react 0.0.0-stage → 0.3.1

package/dist/website/use-website-updates-connector.js

@@ -0,0 +1,318 @@
+/**
+ * Coordinates deployment checks and exact notes for the JavaScript already loaded.
+ *
+ * Owns browser triggers, fresh publication requests, latched presentation and save-before-reload.
+ *
+ * Share this lifecycle with default and app-owned presentation; apps own their refresh save barrier.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { gt } from 'semver';
+import { fetchReleasePage } from '../api.js';
+import { acknowledgeWebsiteVersion, dismissWebsiteBuild, readDismissedWebsiteBuild, readWebsitePreferences, websitePreferenceKey, } from './preferences.js';
+import { fetchWebsiteBuild, reloadWebsite, websiteManifestUrl, websiteReleaseVersion, } from './version.js';
+/** Coordinates deployment detection, fresh exact notes and safe refresh.
+ * @param options - Loaded build, release project and refresh configuration.
+ * @param options.projectId - Public project identifier.
+ * @param options.currentBuild - Build compiled into the running JavaScript.
+ * @param options.currentBuild.buildId - Opaque loaded deployment identity.
+ * @param options.currentBuild.releaseVersion - Optional loaded semantic release version.
+ * @param options.manifestUrl - Deployment manifest location.
+ * @param options.beforeRefresh - Consumer save barrier before reloading.
+ * @returns Visible release/candidate and actions bound to that presentation.
+ */
+export function useWebsiteUpdatesConnector({ projectId, currentBuild, manifestUrl = '/version.json', beforeRefresh, }) {
+    const version = websiteReleaseVersion(currentBuild.releaseVersion);
+    const identity = JSON.stringify([
+        projectId,
+        currentBuild.buildId,
+        version,
+        manifestUrl,
+    ]);
+    const [state, setState] = useState({
+        identity,
+        candidate: null,
+        displayedRelease: null,
+        refreshing: false,
+        error: null,
+    });
+    const runtime = useRef(null);
+    const activeIdentity = useRef(identity);
+    activeIdentity.current = identity;
+    const save = useRef(beforeRefresh);
+    save.current = beforeRefresh;
+    useEffect(() => {
+        let disposed = false;
+        let fetching = false;
+        let refreshing = false;
+        let displayedRelease = null;
+        let candidate = null;
+        let dismissedBuild = null;
+        let acknowledgedVersion = null;
+        let key = null;
+        let url = null;
+        let lastVisibilityCheck = Date.now();
+        let pendingCheck = null;
+        let pendingDeadline;
+        const update = (patch) => {
+            if (!disposed)
+                setState((previous) => ({
+                    ...(previous.identity === identity
+                        ? previous
+                        : {
+                            identity,
+                            candidate: null,
+                            displayedRelease: null,
+                            refreshing: false,
+                            error: null,
+                        }),
+                    ...patch,
+                }));
+        };
+        try {
+            url = websiteManifestUrl(manifestUrl, window.location.href);
+            key = websitePreferenceKey(projectId, url);
+            dismissedBuild = readDismissedWebsiteBuild(key);
+            acknowledgedVersion =
+                readWebsitePreferences(key, version)?.acknowledgedVersion ?? null;
+        }
+        catch {
+            /* Invalid manifest URLs are silent; no requests or automatic panels. */
+        }
+        update({
+            candidate: null,
+            displayedRelease: null,
+            refreshing: false,
+            error: null,
+        });
+        const owner = {
+            identity,
+            async refresh(build) {
+                if (disposed ||
+                    activeIdentity.current !== identity ||
+                    refreshing ||
+                    !candidate ||
+                    candidate !== build ||
+                    candidate.buildId === dismissedBuild ||
+                    displayedRelease)
+                    return;
+                refreshing = true;
+                update({ refreshing: true, error: null });
+                try {
+                    await save.current?.();
+                    if (!disposed &&
+                        activeIdentity.current === identity &&
+                        runtime.current === owner &&
+                        candidate === build &&
+                        candidate.buildId !== dismissedBuild &&
+                        !displayedRelease)
+                        reloadWebsite();
+                    else {
+                        refreshing = false;
+                        update({ refreshing: false });
+                    }
+                }
+                catch {
+                    refreshing = false;
+                    update({
+                        ...(candidate === build && candidate.buildId !== dismissedBuild
+                            ? { error: 'Couldn’t refresh. Please try again.' }
+                            : {}),
+                        refreshing: false,
+                    });
+                }
+            },
+            dismissCandidate(build) {
+                if (disposed || candidate !== build)
+                    return;
+                dismissedBuild = build.buildId;
+                if (key)
+                    dismissWebsiteBuild(key, build.buildId);
+                update({
+                    candidate: null,
+                    error: null,
+                });
+            },
+            dismissRelease(release) {
+                if (disposed || displayedRelease !== release)
+                    return;
+                displayedRelease = null;
+                update({
+                    displayedRelease: null,
+                    candidate: candidate?.buildId === dismissedBuild ? null : candidate,
+                });
+            },
+            renderedRelease(release) {
+                if (!disposed &&
+                    key &&
+                    release === displayedRelease &&
+                    release.version === version)
+                    acknowledgeWebsiteVersion(key, version);
+            },
+        };
+        runtime.current = owner;
+        const readPreferences = () => {
+            if (!key)
+                return null;
+            const preferences = readWebsitePreferences(key, version);
+            if (!preferences)
+                return null;
+            if (preferences.acknowledgedVersion &&
+                (!acknowledgedVersion ||
+                    gt(preferences.acknowledgedVersion, acknowledgedVersion)))
+                acknowledgedVersion = preferences.acknowledgedVersion;
+            return { acknowledgedVersion };
+        };
+        const onStorage = (event) => {
+            if (event.key === key || event.key === null)
+                readPreferences();
+        };
+        const check = async () => {
+            if (disposed || fetching || !url || !key)
+                return;
+            fetching = true;
+            const request = new AbortController();
+            pendingCheck = request;
+            const cancelled = new Promise((resolve) => {
+                request.signal.addEventListener('abort', () => resolve(), {
+                    once: true,
+                });
+            });
+            const deadline = window.setTimeout(() => request.abort(), 30000);
+            pendingDeadline = deadline;
+            const preferences = readPreferences();
+            const showNotes = !displayedRelease &&
+                version &&
+                preferences &&
+                (!preferences.acknowledgedVersion ||
+                    gt(version, preferences.acknowledgedVersion));
+            try {
+                await Promise.race([
+                    Promise.allSettled([
+                        (async () => {
+                            const deployed = await fetchWebsiteBuild(url, request.signal);
+                            if (disposed ||
+                                request.signal.aborted ||
+                                pendingCheck !== request)
+                                return;
+                            candidate =
+                                deployed.buildId === currentBuild.buildId
+                                    ? null
+                                    : candidate?.buildId === deployed.buildId
+                                        ? candidate
+                                        : deployed;
+                            update({
+                                candidate: candidate?.buildId === dismissedBuild ? null : candidate,
+                            });
+                        })(),
+                        ...(showNotes
+                            ? [
+                                (async () => {
+                                    const page = await fetchReleasePage(projectId, {
+                                        version,
+                                        signal: request.signal,
+                                    });
+                                    if (disposed ||
+                                        request.signal.aborted ||
+                                        pendingCheck !== request ||
+                                        displayedRelease ||
+                                        page.items.length !== 1)
+                                        return;
+                                    const latest = readPreferences();
+                                    if (!latest ||
+                                        (latest.acknowledgedVersion &&
+                                            !gt(version, latest.acknowledgedVersion)))
+                                        return;
+                                    displayedRelease = page.items[0];
+                                    update({ displayedRelease });
+                                })(),
+                            ]
+                            : []),
+                    ]),
+                    cancelled,
+                ]);
+            }
+            finally {
+                window.clearTimeout(deadline);
+                request.abort();
+                if (pendingCheck === request) {
+                    pendingCheck = null;
+                    pendingDeadline = undefined;
+                    fetching = false;
+                }
+            }
+        };
+        const onVisible = () => {
+            if (document.visibilityState !== 'visible' ||
+                Date.now() - lastVisibilityCheck < 60000)
+                return;
+            lastVisibilityCheck = Date.now();
+            void check();
+        };
+        const onOnline = () => {
+            void check();
+        };
+        const interval = window.setInterval(() => {
+            if (document.visibilityState === 'visible')
+                void check();
+        }, 300000);
+        window.addEventListener('focus', onVisible);
+        document.addEventListener('visibilitychange', onVisible);
+        window.addEventListener('online', onOnline);
+        window.addEventListener('storage', onStorage);
+        void check();
+        return () => {
+            disposed = true;
+            pendingCheck?.abort();
+            window.clearTimeout(pendingDeadline);
+            window.clearInterval(interval);
+            window.removeEventListener('focus', onVisible);
+            document.removeEventListener('visibilitychange', onVisible);
+            window.removeEventListener('online', onOnline);
+            window.removeEventListener('storage', onStorage);
+            if (runtime.current === owner)
+                runtime.current = null;
+        };
+    }, [identity, projectId, currentBuild.buildId, version, manifestUrl]);
+    const active = state.identity === identity
+        ? state
+        : {
+            candidate: null,
+            displayedRelease: null,
+            refreshing: false,
+            error: null,
+        };
+    const build = active.candidate;
+    const release = active.displayedRelease;
+    const owner = runtime.current;
+    const current = useCallback(() => activeIdentity.current === identity &&
+        owner?.identity === identity &&
+        runtime.current === owner
+        ? runtime.current
+        : null, [identity, owner]);
+    const refresh = useCallback(async () => {
+        if (build)
+            await current()?.refresh(build);
+    }, [current, build]);
+    const dismissCandidate = useCallback(() => {
+        if (build)
+            current()?.dismissCandidate(build);
+    }, [current, build]);
+    const dismissRelease = useCallback(() => {
+        if (release)
+            current()?.dismissRelease(release);
+    }, [current, release]);
+    const onReleaseRendered = useCallback(() => {
+        if (release)
+            current()?.renderedRelease(release);
+    }, [current, release]);
+    return {
+        candidate: active.candidate,
+        displayedRelease: release,
+        refreshing: active.refreshing,
+        error: active.error,
+        refresh,
+        dismissCandidate,
+        dismissRelease,
+        onReleaseRendered,
+    };
+}

package/dist/website/version.d.ts

@@ -0,0 +1,27 @@
+/** One compiled or deployed website build. */
+export interface WebsiteBuild {
+    buildId: string;
+    /** Opaque deployment identifier, including rollbacks. */
+    releaseVersion?: string;
+}
+/** Normalizes a loaded application version without making an invalid version fatal.
+ * @param value - Optional compiled release version.
+ * @returns A canonical semantic version, or null when absent or invalid.
+ */
+export declare function websiteReleaseVersion(value?: string): string | null;
+/** Resolves a manifest against the document URL without sending credentials.
+ * @param value - Consumer manifest URL.
+ * @param base - Browser document URL.
+ * @returns An HTTP(S) manifest URL with no fragment or embedded credentials.
+ * @throws Error when the URL is not an HTTP(S) destination.
+ */
+export declare function websiteManifestUrl(value: string, base: string): string;
+/** Requests a fresh deployment identity.
+ * @param url - Resolved manifest URL.
+ * @param signal - Lifecycle cancellation signal.
+ * @returns A validated deployed build, without interpreting its release version.
+ * @throws Error for unavailable or malformed manifests.
+ */
+export declare function fetchWebsiteBuild(url: string, signal: AbortSignal): Promise<WebsiteBuild>;
+/** Reloads the consumer document after its own save barrier completes. */
+export declare function reloadWebsite(): void;

package/dist/website/version.js

@@ -0,0 +1,73 @@
+/**
+ * Reads a website deployment manifest without relying on browser globals at import time.
+ *
+ * Owns opaque build identity validation and strict optional release-version normalization.
+ *
+ * Keep deployment detection separate from the version of the JavaScript already loaded.
+ */
+import { normalizeReleaseVersion } from '../api.js';
+/** Normalizes a loaded application version without making an invalid version fatal.
+ * @param value - Optional compiled release version.
+ * @returns A canonical semantic version, or null when absent or invalid.
+ */
+export function websiteReleaseVersion(value) {
+    try {
+        return value ? normalizeReleaseVersion(value) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Resolves a manifest against the document URL without sending credentials.
+ * @param value - Consumer manifest URL.
+ * @param base - Browser document URL.
+ * @returns An HTTP(S) manifest URL with no fragment or embedded credentials.
+ * @throws Error when the URL is not an HTTP(S) destination.
+ */
+export function websiteManifestUrl(value, base) {
+    const url = new URL(value, base);
+    if (!['http:', 'https:'].includes(url.protocol) ||
+        url.username ||
+        url.password)
+        throw new Error('A valid website manifest URL is required.');
+    url.hash = '';
+    return url.href;
+}
+/** Requests a fresh deployment identity.
+ * @param url - Resolved manifest URL.
+ * @param signal - Lifecycle cancellation signal.
+ * @returns A validated deployed build, without interpreting its release version.
+ * @throws Error for unavailable or malformed manifests.
+ */
+export async function fetchWebsiteBuild(url, signal) {
+    const response = await fetch(url, {
+        cache: 'no-store',
+        credentials: 'omit',
+        signal,
+        headers: { Accept: 'application/json' },
+    });
+    if (!response.ok)
+        throw new Error('Website version is unavailable.');
+    const body = await response.text();
+    if (body.length > 16384)
+        throw new Error('Invalid website version.');
+    const value = JSON.parse(body);
+    if (!value ||
+        typeof value.buildId !== 'string' ||
+        !value.buildId.trim() ||
+        value.buildId.length > 512 ||
+        (value.releaseVersion !== undefined &&
+            (typeof value.releaseVersion !== 'string' ||
+                value.releaseVersion.length > 256)))
+        throw new Error('Invalid website version.');
+    return {
+        buildId: value.buildId,
+        ...(value.releaseVersion === undefined
+            ? {}
+            : { releaseVersion: value.releaseVersion }),
+    };
+}
+/** Reloads the consumer document after its own save barrier completes. */
+export function reloadWebsite() {
+    window.location.reload();
+}

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "@makershq/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.1",
+  "description": "Release notes for React and optional Tauri 2 apps",
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./tauri": {
+      "types": "./dist/tauri/index.d.ts",
+      "import": "./dist/tauri/index.js"
+    },
+    "./styles.css": {
+      "types": "./dist/styles.d.ts",
+      "default": "./dist/styles.css"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "dependencies": {
+    "@animate-ui/react": "2.2.1",
+    "motion": "14.6.0",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1",
+    "rehype-raw": "^7.0.0",
+    "rehype-sanitize": "^6.0.0",
+    "semver": "^7.7.3"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@tauri-apps/api": "^2.0.0",
+    "@tauri-apps/plugin-store": "^2.0.0",
+    "@tauri-apps/plugin-opener": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tauri-apps/api": {
+      "optional": true
+    },
+    "@tauri-apps/plugin-store": {
+      "optional": true
+    },
+    "@tauri-apps/plugin-opener": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@tailwindcss/cli": "^4.0.0",
+    "@tauri-apps/api": "^2.0.0",
+    "@tauri-apps/plugin-store": "^2.0.0",
+    "@tauri-apps/plugin-opener": "^2.0.0",
+    "@types/semver": "^7.7.1",
+    "typescript-5-8": "npm:typescript@~5.8.3"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --config vitest.config.ts",
+    "test:pack": "node scripts/pack-test.mjs"
+  }
 }