@makershq/react 0.0.0-stage → 0.3.1

package/dist/tauri/index.d.ts

@@ -0,0 +1,10 @@
+/** Presents release notes and consumer-owned updates in native Tauri windows.
+ *
+ * Mounts SDK child views before app children and keeps all updater callbacks in the host.
+ *
+ * Import this optional entry point only in Tauri apps with the documented capabilities.
+ */
+export { ReleaseNotesHost, type ReleaseNotesHostProps, } from './components/release-notes-host/index.js';
+export { ReleaseNotesSettings } from './components/release-notes-settings/index.js';
+export { useReleaseNotes, type ReleaseNotesActions, type ReleaseNotesResult, type ReaderPresentation, type UpdatePresentation, } from './hooks/use-release-notes.js';
+export type { AppUpdater, AvailableUpdate, InstallProgress, ReleaseNotesState, ReleaseNotesPreferences, } from './contracts.js';

package/dist/tauri/index.js

@@ -0,0 +1,9 @@
+/** Presents release notes and consumer-owned updates in native Tauri windows.
+ *
+ * Mounts SDK child views before app children and keeps all updater callbacks in the host.
+ *
+ * Import this optional entry point only in Tauri apps with the documented capabilities.
+ */
+export { ReleaseNotesHost, } from './components/release-notes-host/index.js';
+export { ReleaseNotesSettings } from './components/release-notes-settings/index.js';
+export { useReleaseNotes, } from './hooks/use-release-notes.js';

package/dist/tauri/peer-protocol.d.ts

@@ -0,0 +1,36 @@
+/** Validates the bounded connection between existing local settings windows and main.
+ *
+ * Keeps secondary windows limited to bounded settings and headless presentation commands.
+ *
+ * Allow only authenticated presentation commands in headless mode; never remote updater notifications.
+ */
+import { type ChildKind, type PresentationAction } from './protocol.js';
+/** Existing-window connection request event. */
+export declare const PEER_CONNECT_EVENT = "makers-hq-release-notes-connect";
+/** Existing-window command event, authenticated after the connection handshake. */
+export declare const PEER_ACTION_EVENT = "makers-hq-release-notes-peer-action";
+/** Targeted completion event for bounded settings and presentation commands. */
+export declare const PEER_RESULT_EVENT = "makers-hq-release-notes-peer-result";
+/** Supported settings and presentation actions; updater resources remain main-owned. */
+export type PeerAction = {
+    type: 'open' | 'check' | 'disconnect';
+} | {
+    type: 'preference';
+    value: boolean;
+} | {
+    type: 'presentation';
+    kind: ChildKind;
+    generation: number;
+    action: PresentationAction;
+};
+/** Tests the labels allowed to request a settings connection.
+ * @param label - Claimed existing native window label.
+ * @param host - Sole callback-owning main label.
+ * @returns Whether the label can belong to a non-SDK settings peer.
+ */
+export declare function isPeerLabel(label: unknown, host: string): label is string;
+/** Validates a bounded settings or presentation action and its exact payload.
+ * @param value - Untrusted action payload.
+ * @returns Whether the payload is a supported bounded command.
+ */
+export declare function isPeerAction(value: unknown): value is PeerAction;

package/dist/tauri/peer-protocol.js

@@ -0,0 +1,43 @@
+/** Validates the bounded connection between existing local settings windows and main.
+ *
+ * Keeps secondary windows limited to bounded settings and headless presentation commands.
+ *
+ * Allow only authenticated presentation commands in headless mode; never remote updater notifications.
+ */
+import { CHILD_PREFIX, isPresentationAction, } from './protocol.js';
+/** Existing-window connection request event. */
+export const PEER_CONNECT_EVENT = 'makers-hq-release-notes-connect';
+/** Existing-window command event, authenticated after the connection handshake. */
+export const PEER_ACTION_EVENT = 'makers-hq-release-notes-peer-action';
+/** Targeted completion event for bounded settings and presentation commands. */
+export const PEER_RESULT_EVENT = 'makers-hq-release-notes-peer-result';
+/** Tests the labels allowed to request a settings connection.
+ * @param label - Claimed existing native window label.
+ * @param host - Sole callback-owning main label.
+ * @returns Whether the label can belong to a non-SDK settings peer.
+ */
+export function isPeerLabel(label, host) {
+    return (typeof label === 'string' &&
+        /^[a-zA-Z0-9_:/-]{1,128}$/.test(label) &&
+        label !== host &&
+        !label.startsWith(CHILD_PREFIX));
+}
+/** Validates a bounded settings or presentation action and its exact payload.
+ * @param value - Untrusted action payload.
+ * @returns Whether the payload is a supported bounded command.
+ */
+export function isPeerAction(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const action = value;
+    if (action.type === 'presentation')
+        return ((action.kind === 'reader' || action.kind === 'update') &&
+            Number.isSafeInteger(action.generation) &&
+            Number(action.generation) > 0 &&
+            isPresentationAction(action.action) &&
+            Object.keys(action).length === 4);
+    if (action.type === 'preference')
+        return typeof action.value === 'boolean' && Object.keys(action).length === 2;
+    return (['open', 'check', 'disconnect'].includes(String(action.type)) &&
+        Object.keys(action).length === 1);
+}

package/dist/tauri/preferences.d.ts

@@ -0,0 +1,18 @@
+/** Owns the native after-update preference and version-transition rules.
+ *
+ * Keeps first launch, downgrades and unavailable-note retries deterministic.
+ *
+ * Preserve exact version strings when adding presentation rules.
+ */
+import type { ReleaseNotesPreferences } from './contracts.js';
+/** Validates stored preferences without retaining extra persisted fields.
+ * @param value - Value read from the app-local store.
+ * @returns The supported preferences, applying safe defaults to invalid data.
+ */
+export declare function readPreferences(value: unknown): ReleaseNotesPreferences;
+/** Determines whether an installed version is an unacknowledged upgrade.
+ * @param current - Installed native app version.
+ * @param acknowledged - Last acknowledged version, or null for first launch.
+ * @returns True only for a valid newer installed release, including changed build metadata.
+ */
+export declare function isInstalledUpgrade(current: string, acknowledged: string | null): boolean;

package/dist/tauri/preferences.js

@@ -0,0 +1,39 @@
+/** Owns the native after-update preference and version-transition rules.
+ *
+ * Keeps first launch, downgrades and unavailable-note retries deterministic.
+ *
+ * Preserve exact version strings when adding presentation rules.
+ */
+import { gt, eq, valid } from 'semver';
+import { normalizeReleaseVersion } from '../api.js';
+/** Validates stored preferences without retaining extra persisted fields.
+ * @param value - Value read from the app-local store.
+ * @returns The supported preferences, applying safe defaults to invalid data.
+ */
+export function readPreferences(value) {
+    const data = value && typeof value === 'object' ? value : {};
+    return {
+        showAfterUpdate: typeof data.showAfterUpdate === 'boolean' ? data.showAfterUpdate : true,
+        acknowledgedVersion: typeof data.acknowledgedVersion === 'string' &&
+            valid(data.acknowledgedVersion)
+            ? data.acknowledgedVersion
+            : null,
+        skippedVersion: typeof data.skippedVersion === 'string' && valid(data.skippedVersion)
+            ? data.skippedVersion
+            : null,
+    };
+}
+/** Determines whether an installed version is an unacknowledged upgrade.
+ * @param current - Installed native app version.
+ * @param acknowledged - Last acknowledged version, or null for first launch.
+ * @returns True only for a valid newer installed release, including changed build metadata.
+ */
+export function isInstalledUpgrade(current, acknowledged) {
+    return Boolean(acknowledged &&
+        valid(current) &&
+        valid(acknowledged) &&
+        (gt(current, acknowledged) ||
+            (eq(current, acknowledged) &&
+                normalizeReleaseVersion(current) !==
+                    normalizeReleaseVersion(acknowledged))));
+}

package/dist/tauri/protocol.d.ts

@@ -0,0 +1,71 @@
+/** Validates the narrow messages exchanged by the native host and its child windows.
+ *
+ * Authenticates each child with a random per-window token and fixed same-origin route.
+ *
+ * Add explicit actions here instead of creating a general-purpose remote call protocol.
+ */
+/** Targeted child-to-host presentation event. */
+export declare const ACTION_EVENT = "makers-hq-release-notes-action";
+/** Targeted host-to-child snapshot event. */
+export declare const STATE_EVENT = "makers-hq-release-notes-state";
+/** SDK-owned route discriminator on the existing app entry point. */
+export declare const CHILD_QUERY = "__makers_hq_window";
+/** Fixed namespace for the two SDK child labels. */
+export declare const CHILD_PREFIX = "makers-hq-release-notes-";
+/** Fixed SDK child-window roles. */
+export type ChildKind = 'reader' | 'update';
+/** Serializable child actions; installation always carries the displayed version. */
+export type ChildAction = {
+    type: 'ready' | 'check' | 'open-reader' | 'cancel';
+} | {
+    type: 'preference';
+    value: boolean;
+} | {
+    type: 'install' | 'skip' | 'rendered';
+    version: string;
+};
+/** Authenticated envelope scoped to one child lifecycle. */
+export interface ActionEnvelope {
+    sender: string;
+    token: string;
+    action: ChildAction;
+    generation?: number;
+}
+/** Checks a child action and rejects arbitrary payloads before dispatch.
+ * @param value - Untrusted event payload.
+ * @param sender - Expected fixed child label.
+ * @param token - Random capability token assigned when creating the child.
+ * @returns Whether the complete envelope is valid.
+ */
+export declare function isActionEnvelope(value: unknown, sender: string, token: string): value is ActionEnvelope;
+/** Reads a child route only when its role, label and host are valid.
+ * @param url - Current same-origin application URL.
+ * @param label - Native current webview label.
+ * @returns Validated child route or null for the ordinary host app.
+ */
+export declare function childRoute(url: string, label: string): {
+    kind: ChildKind;
+    host: string;
+    token: string;
+} | null;
+/** Bounded presentation commands shared by the host and authenticated headless peers. */
+export type PresentationAction = {
+    type: 'dismiss' | 'cancel';
+} | {
+    type: 'install' | 'skip';
+    version: string;
+} | {
+    type: 'rendered';
+    version: string;
+    cached: boolean;
+};
+/** Validates the complete scalar presentation command.
+ * @param value - Untrusted peer command.
+ * @returns Whether the command is supported with an exact payload.
+ */
+export declare function isPresentationAction(value: unknown): value is PresentationAction;
+/** Checks the serializable presentation fields before authenticated snapshots reach hooks.
+ * @param state - Authenticated state object from the host.
+ * @returns Whether readiness, mode and private presentation identities are valid.
+ */
+export declare function hasPresentationState(state: Record<string, unknown>): boolean;

package/dist/tauri/protocol.js

@@ -0,0 +1,106 @@
+/** Validates the narrow messages exchanged by the native host and its child windows.
+ *
+ * Authenticates each child with a random per-window token and fixed same-origin route.
+ *
+ * Add explicit actions here instead of creating a general-purpose remote call protocol.
+ */
+/** Targeted child-to-host presentation event. */
+export const ACTION_EVENT = 'makers-hq-release-notes-action';
+/** Targeted host-to-child snapshot event. */
+export const STATE_EVENT = 'makers-hq-release-notes-state';
+/** SDK-owned route discriminator on the existing app entry point. */
+export const CHILD_QUERY = '__makers_hq_window';
+/** Fixed namespace for the two SDK child labels. */
+export const CHILD_PREFIX = 'makers-hq-release-notes-';
+/** Checks a child action and rejects arbitrary payloads before dispatch.
+ * @param value - Untrusted event payload.
+ * @param sender - Expected fixed child label.
+ * @param token - Random capability token assigned when creating the child.
+ * @returns Whether the complete envelope is valid.
+ */
+export function isActionEnvelope(value, sender, token) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const envelope = value;
+    if (envelope.sender !== sender ||
+        envelope.token !== token ||
+        !envelope.action ||
+        typeof envelope.action !== 'object')
+        return false;
+    if (envelope.generation !== undefined &&
+        (!Number.isSafeInteger(envelope.generation) ||
+            Number(envelope.generation) < 1))
+        return false;
+    const action = envelope.action;
+    if (['ready', 'check', 'open-reader', 'cancel'].includes(String(action.type)))
+        return Object.keys(action).length === 1;
+    if (action.type === 'preference')
+        return typeof action.value === 'boolean' && Object.keys(action).length === 2;
+    return (['install', 'skip', 'rendered'].includes(String(action.type)) &&
+        typeof action.version === 'string' &&
+        action.version.length > 0 &&
+        action.version.length <= 128 &&
+        Object.keys(action).length === 2);
+}
+/** Reads a child route only when its role, label and host are valid.
+ * @param url - Current same-origin application URL.
+ * @param label - Native current webview label.
+ * @returns Validated child route or null for the ordinary host app.
+ */
+export function childRoute(url, label) {
+    const params = new URL(url).searchParams;
+    const kind = params.get(CHILD_QUERY);
+    if (kind !== 'reader' && kind !== 'update')
+        return null;
+    const host = params.get('__makers_hq_host') ?? '';
+    const token = params.get('__makers_hq_token') ?? '';
+    if (label !== CHILD_PREFIX + kind ||
+        !/^[a-zA-Z0-9_:/-]{1,128}$/.test(host) ||
+        !/^[a-f0-9-]{36}$/.test(token))
+        throw new Error('Invalid release notes window route.');
+    return { kind, host, token };
+}
+/** Validates the complete scalar presentation command.
+ * @param value - Untrusted peer command.
+ * @returns Whether the command is supported with an exact payload.
+ */
+export function isPresentationAction(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const action = value;
+    if (['dismiss', 'cancel'].includes(String(action.type)))
+        return Object.keys(action).length === 1;
+    if (['install', 'skip'].includes(String(action.type)))
+        return (typeof action.version === 'string' &&
+            action.version.length > 0 &&
+            action.version.length <= 128 &&
+            Object.keys(action).length === 2);
+    return (action.type === 'rendered' &&
+        typeof action.version === 'string' &&
+        action.version.length > 0 &&
+        action.version.length <= 128 &&
+        typeof action.cached === 'boolean' &&
+        Object.keys(action).length === 3);
+}
+/** Checks the serializable presentation fields before authenticated snapshots reach hooks.
+ * @param state - Authenticated state object from the host.
+ * @returns Whether readiness, mode and private presentation identities are valid.
+ */
+export function hasPresentationState(state) {
+    function request(value) {
+        if (value === null)
+            return true;
+        if (!value || typeof value !== 'object')
+            return false;
+        const record = value;
+        return (Number.isSafeInteger(record.generation) &&
+            Number(record.generation) > 0 &&
+            typeof record.originWindowLabel === 'string' &&
+            /^[a-zA-Z0-9_:/-]{1,128}$/.test(record.originWindowLabel));
+    }
+    return (typeof state.ready === 'boolean' &&
+        (state.presentation === 'native' || state.presentation === 'headless') &&
+        (state.readerVersion === null || typeof state.readerVersion === 'string') &&
+        request(state.readerRequest) &&
+        request(state.updateRequest));
+}

package/dist/tauri/remote-settings-client.d.ts

@@ -0,0 +1,72 @@
+/** Connects an existing local settings window to the one native main host.
+ *
+ * Receives presentation snapshots and forwards only bounded settings actions.
+ *
+ * Keep updater resources, installation and background notifications in the main window.
+ */
+import type { NativeState } from './contracts.js';
+import { type ChildKind, type PresentationAction } from './protocol.js';
+/** Internal read/presentation client for one existing settings window. */
+export declare class RemoteSettingsClient {
+    private projectId;
+    private hostLabel;
+    private state;
+    private listeners;
+    private token;
+    private snapshotRevision;
+    private nonce;
+    private disposers;
+    private pending;
+    private connectionWaiters;
+    private connectionFailure;
+    private disposed;
+    private label;
+    /** Connects to the main host without invoking consumer updater callbacks.
+     * @param projectId - Expected release-note project.
+     * @param hostLabel - Existing callback-owning main window.
+     */
+    constructor(projectId: string, hostLabel: string);
+    /** Subscribes to main-host state.
+     * @param listener - React external-store listener.
+     * @returns Unsubscribe callback.
+     */
+    subscribe: (listener: () => void) => (() => void);
+    /** Reads the stable presentation snapshot.
+     * @returns Latest authenticated main-host state.
+     */
+    getSnapshot: () => NativeState;
+    private patch;
+    private initialize;
+    private settleConnection;
+    private waitForConnection;
+    private send;
+    /** Opens a reader owned by main and returning focus to this settings window.
+     * @returns Completion after the native reader is ready.
+     */
+    open: () => Promise<void>;
+    /** Runs the main host's manual check, bypassing its skipped candidate.
+     * @returns Completion after the host finishes presenting its result.
+     */
+    check: () => Promise<void>;
+    /** Saves the main host's shared preference.
+     * @param value - New after-update preference.
+     * @returns Completion after host persistence and synchronization.
+     */
+    setShowAfterUpdate: (value: boolean) => Promise<void>;
+    /** Sends one bounded command for a captured headless presentation.
+     * @param kind - Reader or update role.
+     * @param generation - Private identity from the authenticated snapshot.
+     * @param action - Bounded presentation command.
+     * @param action.type - Fixed command discriminator.
+     * @param action.version - Exact displayed candidate or rendered release version.
+     * @param action.cached - Whether rendered content came from offline storage.
+     * @returns Command acceptance; long operations report through synchronized state.
+     */
+    presentationAction: (kind: ChildKind, generation: number, action: PresentationAction) => Promise<void>;
+    /** Rejects secondary-window background notifications.
+     * @returns A rejected promise; consumer background checking belongs in the main host.
+     */
+    notifyUpdateAvailable: () => Promise<void>;
+    /** Releases secondary-window listeners without touching main's updater resources. */
+    dispose(): void;
+}