@luv1211/dsh-pet 0.1.1-rc.2

package/lib/types/path-opener.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Cross-platform native path and text-document openers used by the local GUI
+ * carrier.
+ *
+ * The default intent prefers the default browser for documents it renders when
+ * the platform can name one, then falls back to the default application. WSL
+ * translates every path for the Windows desktop instead of assuming a Linux
+ * GUI. The text-editor intent never consults the browser.
+ */
+import { type NativeCommandRunner } from '@deepseek-ai/dsh-native-command';
+/** Testable command boundary; native implementations never invoke a shell. */
+export type PathOpenerRunner = NativeCommandRunner;
+/** Injectable platform facts for deterministic adapter tests. */
+export interface PathOpenerInternals {
+    platform?: NodeJS.Platform;
+    /** Kernel release override used to distinguish WSL from desktop Linux. */
+    osRelease?: string;
+    /** Environment used for WSL markers and the desktop Linux browser convention. */
+    env?: NodeJS.ProcessEnv;
+    run?: PathOpenerRunner;
+}
+/**
+ * Whether {@link openNativePath} plausibly reaches a desktop on this host.
+ *
+ * macOS and Windows always carry a desktop opener; Linux does when it is WSL
+ * (the Windows desktop takes the path) or a display server is announced.
+ * A headless or containerised Linux host answers false, which is what lets a
+ * surface show a path as text instead of offering a button that would spawn
+ * `xdg-open` into nothing.
+ * @param internals - platform and environment seam for deterministic tests.
+ * @returns true when handing a path to the native opener can work at all.
+ */
+export declare function canOpenNativePath(internals?: PathOpenerInternals): boolean;
+/**
+ * Open a filesystem path with the operating system's default application, or
+ * with the default browser when the path names a document a browser renders.
+ * @param path - absolute or host-resolvable path (caller owns resolution).
+ * @param signal - caller/connection lifetime; abort terminates the native command.
+ * @param internals - Platform, environment, and runner hooks for deterministic tests.
+ */
+export declare function openNativePath(path: string, signal: AbortSignal, internals?: PathOpenerInternals): Promise<void>;
+/**
+ * Open a text document for editing; macOS bypasses the file-type association
+ * so a YAML association with a browser cannot consume the gesture.
+ * @param path - absolute or host-resolvable text-document path.
+ * @param signal - caller/connection lifetime; abort terminates the native command.
+ * @param internals - Platform and runner hooks for deterministic tests.
+ */
+export declare function openNativeTextFile(path: string, signal: AbortSignal, internals?: PathOpenerInternals): Promise<void>;
+//# sourceMappingURL=path-opener.d.ts.map

package/lib/types/path-opener.js

@@ -0,0 +1,161 @@
+/**
+ * Cross-platform native path and text-document openers used by the local GUI
+ * carrier.
+ *
+ * The default intent prefers the default browser for documents it renders when
+ * the platform can name one, then falls back to the default application. WSL
+ * translates every path for the Windows desktop instead of assuming a Linux
+ * GUI. The text-editor intent never consults the browser.
+ */
+import { release as osRelease } from 'node:os';
+import { extname } from 'node:path';
+import { runNativeCommand } from '@deepseek-ai/dsh-native-command';
+/** Documents a browser renders, as opposed to ones an editor merely edits. */
+const BROWSER_DOCUMENTS = new Set(['.html', '.htm', '.xhtml', '.svg']);
+/**
+ * The macOS bundle registered for `https` — the default browser, as
+ * LaunchServices records it. The nested version dict is stripped first
+ * because it carries its own `LSHandlerRoleAll`.
+ */
+function macBundleForHttps(plist) {
+    const stripped = plist.replace(/LSHandlerPreferredVersions\s*=\s*\{[^}]*\};/g, '');
+    const block = /\{[^{}]*LSHandlerURLScheme\s*=\s*"?https"?;[^{}]*\}/.exec(stripped)?.[0];
+    if (block === undefined)
+        return undefined;
+    return /LSHandlerRoleAll\s*=\s*"?([\w.-]+)"?;/.exec(block)?.[1];
+}
+/**
+ * Open one browser-renderable document with the default browser.
+ * @returns true when a browser took it; false when this platform cannot name
+ * one, or naming it failed — the caller then uses the default application.
+ */
+async function openInBrowser(path, signal, platform, run, env) {
+    if (platform === 'darwin') {
+        let bundle;
+        try {
+            const { stdout } = await run('defaults', ['read', 'com.apple.LaunchServices/com.apple.launchservices.secure'], signal);
+            bundle = macBundleForHttps(stdout);
+        }
+        catch {
+            // No LaunchServices record (a fresh account never changed a default):
+            // the content-type handler is then the system's own choice anyway.
+            return false;
+        }
+        if (bundle === undefined)
+            return false;
+        await run('open', ['-b', bundle, path], signal);
+        return true;
+    }
+    if (platform === 'linux') {
+        // $BROWSER is the portable convention; desktop-entry resolution through
+        // xdg-settings needs a launcher this package has no business shipping.
+        const browser = env.BROWSER;
+        if (browser === undefined || browser === '')
+            return false;
+        await run(browser, [path], signal);
+        return true;
+    }
+    // Windows names no browser without reading the UserChoice registry, and its
+    // .html association is the browser in the ordinary case.
+    return false;
+}
+/** PowerShell single-quoted literal (doubles embedded quotes). */
+function powershellLiteral(path) {
+    return `'${path.replace(/'/g, "''")}'`;
+}
+/** Whether one environment marker is set to a non-empty value. */
+function present(value) {
+    return value !== undefined && value !== '';
+}
+/** Distinguish WSL from desktop Linux using its process and kernel markers. */
+function isWsl(internals) {
+    const env = internals.env ?? process.env;
+    if (present(env.WSL_DISTRO_NAME) || present(env.WSL_INTEROP))
+        return true;
+    return (internals.osRelease ?? osRelease()).toLowerCase().includes('microsoft');
+}
+/** Open one Windows-resolvable path through its registered desktop application. */
+async function openWindowsPath(path, signal, run) {
+    await run('powershell.exe', [
+        '-NoProfile',
+        '-Command',
+        `Invoke-Item -LiteralPath ${powershellLiteral(path)}`,
+    ], signal);
+}
+/** Translate a WSL path before handing it to the Windows desktop. */
+async function openWslPath(path, signal, run) {
+    const translated = await run('wslpath', ['-w', path], signal);
+    signal.throwIfAborted();
+    const windowsPath = translated.stdout.replace(/[\r\n]+$/, '');
+    if (windowsPath === '')
+        throw new Error('wslpath returned no Windows path');
+    await openWindowsPath(windowsPath, signal, run);
+}
+/** Dispatch one shell-free platform command for the requested open intent. */
+async function openNativePathWithIntent(path, signal, intent, internals = {}) {
+    const platform = internals.platform ?? process.platform;
+    const run = internals.run ?? runNativeCommand;
+    const env = internals.env ?? process.env;
+    const wsl = platform === 'linux' && isWsl(internals);
+    if (!wsl && intent === 'default' && BROWSER_DOCUMENTS.has(extname(path).toLowerCase())
+        && await openInBrowser(path, signal, platform, run, env))
+        return;
+    if (platform === 'darwin') {
+        await run('open', intent === 'text-editor' ? ['-t', path] : [path], signal);
+        return;
+    }
+    if (platform === 'win32') {
+        await openWindowsPath(path, signal, run);
+        return;
+    }
+    if (platform === 'linux') {
+        if (wsl) {
+            await openWslPath(path, signal, run);
+            return;
+        }
+        await run('xdg-open', [path], signal);
+        return;
+    }
+    throw new Error(`native path opener is unsupported on ${platform}`);
+}
+/**
+ * Whether {@link openNativePath} plausibly reaches a desktop on this host.
+ *
+ * macOS and Windows always carry a desktop opener; Linux does when it is WSL
+ * (the Windows desktop takes the path) or a display server is announced.
+ * A headless or containerised Linux host answers false, which is what lets a
+ * surface show a path as text instead of offering a button that would spawn
+ * `xdg-open` into nothing.
+ * @param internals - platform and environment seam for deterministic tests.
+ * @returns true when handing a path to the native opener can work at all.
+ */
+export function canOpenNativePath(internals = {}) {
+    const platform = internals.platform ?? process.platform;
+    if (platform === 'darwin' || platform === 'win32')
+        return true;
+    if (platform !== 'linux')
+        return false;
+    const env = internals.env ?? process.env;
+    return isWsl(internals) || present(env.DISPLAY) || present(env.WAYLAND_DISPLAY);
+}
+/**
+ * Open a filesystem path with the operating system's default application, or
+ * with the default browser when the path names a document a browser renders.
+ * @param path - absolute or host-resolvable path (caller owns resolution).
+ * @param signal - caller/connection lifetime; abort terminates the native command.
+ * @param internals - Platform, environment, and runner hooks for deterministic tests.
+ */
+export function openNativePath(path, signal, internals = {}) {
+    return openNativePathWithIntent(path, signal, 'default', internals);
+}
+/**
+ * Open a text document for editing; macOS bypasses the file-type association
+ * so a YAML association with a browser cannot consume the gesture.
+ * @param path - absolute or host-resolvable text-document path.
+ * @param signal - caller/connection lifetime; abort terminates the native command.
+ * @param internals - Platform and runner hooks for deterministic tests.
+ */
+export function openNativeTextFile(path, signal, internals = {}) {
+    return openNativePathWithIntent(path, signal, 'text-editor', internals);
+}
+//# sourceMappingURL=path-opener.js.map

package/lib/types/renderer.d.ts

@@ -0,0 +1,42 @@
+/** Browser-safe sprite frame projection shared by Web and desktop documents. */
+import { type PetAnimationState, type PetPresentation } from './runtime.ts';
+import type { PetAnimation } from '@luv1211/dsh-pet-compat';
+/** One CSS frame projection for the validated compatible atlas. */
+export interface PetSpriteFrameStyle {
+    /** Logical CSS width of one atlas cell. */
+    readonly width: number;
+    /** Logical CSS height of one atlas cell. */
+    readonly height: number;
+    /** Origin-relative or otherwise validated sprite URL supplied by the caller. */
+    readonly backgroundImage: string;
+    /** CSS pixel offset of the selected atlas cell. */
+    readonly backgroundPosition: string;
+    /** Full atlas size in logical CSS pixels. */
+    readonly backgroundSize: string;
+}
+/** Resolve one elapsed presentation into a frame and CSS background projection.
+ * @param assetUrl - validated origin-relative sprite URL.
+ * @param sizePx - validated logical CSS cell height.
+ * @param presentation - renderer state selected for this update.
+ * @param elapsedMs - elapsed time since the selected state began.
+ * @param animations - validated package animation tracks, when available.
+ * @returns the selected atlas cell and its CSS background projection.
+ */
+export declare function petSpriteFrame(assetUrl: string, sizePx: number, presentation: PetPresentation, elapsedMs: number, animations?: Readonly<Record<string, PetAnimation>>): {
+    frame: {
+        state: PetAnimationState;
+        row: number;
+        column: number;
+        done: boolean;
+    };
+    style: PetSpriteFrameStyle;
+};
+/** Resolve the static first atlas cell into a CSS background projection at any display height.
+ * Unlike {@link petSpriteFrame} this projection is decoupled from the validated overlay size range,
+ * so fixed-size list avatars can render smaller than the wake-state minimum.
+ * @param assetUrl - validated origin-relative sprite URL.
+ * @param heightPx - display cell height in CSS pixels, chosen by the caller.
+ * @returns the frame-zero cell and its CSS background projection.
+ */
+export declare function petSpriteAvatar(assetUrl: string, heightPx: number): PetSpriteFrameStyle;
+//# sourceMappingURL=renderer.d.ts.map

package/lib/types/renderer.js

@@ -0,0 +1,54 @@
+/** Browser-safe sprite frame projection shared by Web and desktop documents. */
+import { DEFAULT_PET_ANIMATIONS, frameAt } from '@luv1211/dsh-pet-compat';
+import { PET_COMPAT_ATLAS, petWidthForSize, } from "./runtime.js";
+/** Resolve one elapsed presentation into a frame and CSS background projection.
+ * @param assetUrl - validated origin-relative sprite URL.
+ * @param sizePx - validated logical CSS cell height.
+ * @param presentation - renderer state selected for this update.
+ * @param elapsedMs - elapsed time since the selected state began.
+ * @param animations - validated package animation tracks, when available.
+ * @returns the selected atlas cell and its CSS background projection.
+ */
+export function petSpriteFrame(assetUrl, sizePx, presentation, elapsedMs, animations) {
+    const frame = presentation.state === 'tucked'
+        ? { state: 'idle', row: 0, column: 0, done: true }
+        : (() => {
+            const selection = frameAt(animations ?? DEFAULT_PET_ANIMATIONS, presentation.state, elapsedMs, !presentation.animate);
+            const spriteIndex = selection?.spriteIndex ?? 0;
+            return {
+                state: presentation.state,
+                row: Math.floor(spriteIndex / PET_COMPAT_ATLAS.columns),
+                column: spriteIndex % PET_COMPAT_ATLAS.columns,
+                done: selection?.animation === 'idle' && presentation.state !== 'idle',
+            };
+        })();
+    const width = petWidthForSize(sizePx);
+    return {
+        frame,
+        style: {
+            width,
+            height: sizePx,
+            backgroundImage: `url(${assetUrl})`,
+            backgroundPosition: `${-frame.column * width}px ${-frame.row * sizePx}px`,
+            backgroundSize: `${petWidthForSize(sizePx) * PET_COMPAT_ATLAS.columns}px ${sizePx * PET_COMPAT_ATLAS.rows}px`,
+        },
+    };
+}
+/** Resolve the static first atlas cell into a CSS background projection at any display height.
+ * Unlike {@link petSpriteFrame} this projection is decoupled from the validated overlay size range,
+ * so fixed-size list avatars can render smaller than the wake-state minimum.
+ * @param assetUrl - validated origin-relative sprite URL.
+ * @param heightPx - display cell height in CSS pixels, chosen by the caller.
+ * @returns the frame-zero cell and its CSS background projection.
+ */
+export function petSpriteAvatar(assetUrl, heightPx) {
+    const width = Math.round(heightPx * PET_COMPAT_ATLAS.cellWidth / PET_COMPAT_ATLAS.cellHeight);
+    return {
+        width,
+        height: heightPx,
+        backgroundImage: `url(${assetUrl})`,
+        backgroundPosition: '0px 0px',
+        backgroundSize: `${width * PET_COMPAT_ATLAS.columns}px ${heightPx * PET_COMPAT_ATLAS.rows}px`,
+    };
+}
+//# sourceMappingURL=renderer.js.map

package/lib/types/runtime.d.ts

@@ -0,0 +1,155 @@
+/** Browser-safe pet constants, validation, presentation selection, and timing. */
+import type { PetActivityStatus, PetDescriptor, PetHostActivityRecord, PetPreference } from './types.ts';
+import type { PetSessionActivity } from './types.ts';
+/** Version of the durable pet preference document. */
+export declare const PET_PREFERENCE_VERSION: 3;
+/** Built-in identifier selected by a fresh preference document. */
+export declare const DEFAULT_PET_ID = "deepseek-whale";
+/** Default logical CSS height of one compatible atlas cell. */
+export declare const DEFAULT_PET_SIZE_PX = 112;
+/** Minimum logical CSS height accepted by the pet preference validator. */
+export declare const MIN_PET_SIZE_PX = 80;
+/** Maximum logical CSS height accepted by the pet preference validator. */
+export declare const MAX_PET_SIZE_PX = 224;
+/** Compatible atlas geometry owned by the DSH renderer. */
+export declare const PET_COMPAT_ATLAS: Readonly<{
+    width: 1536;
+    height: 1872;
+    cellWidth: 192;
+    cellHeight: 208;
+    columns: 8;
+    rows: 9;
+}>;
+/** Base animation states with cells in rows 0 through 8. */
+export type PetAnimationState = 'idle' | 'running-right' | 'running-left' | 'waving' | 'jumping' | 'failed' | 'waiting' | 'running' | 'review';
+/** Horizontal movement direction accepted by the presentation selector. */
+export type PetDragDirection = 'left' | 'right';
+/** Relative pointer target used for the 16 look-direction bins. */
+export interface PetLookTarget {
+    /** Horizontal target distance in CSS pixels. */
+    readonly x: number;
+    /** Vertical target distance in CSS pixels. */
+    readonly y: number;
+}
+/** Presentation input shared by the browser and Electron renderers. */
+export interface PetPresentationInput {
+    /** Whether the companion is currently rendered. */
+    readonly awake: boolean;
+    /** Highest-priority host activity, or undefined for idle. */
+    readonly status?: PetActivityStatus;
+    /** Whether the pointer is hovering the companion. */
+    readonly hover: boolean;
+    /** Accepted horizontal drag direction, when the pointer is being dragged. */
+    readonly dragDirection?: PetDragDirection;
+    /** Whether animation timers must be suppressed. */
+    readonly reducedMotion: boolean;
+    /** Relative pointer target for look-direction selection. */
+    readonly lookTarget?: PetLookTarget;
+}
+/** Presentation state selected for one renderer update. */
+export interface PetPresentation {
+    /** Domain-independent state used by CSS and animation lookup. */
+    readonly state: PetAnimationState | 'tucked';
+    /** Atlas row for the selected state. */
+    readonly row: number;
+    /** First frame column for the selected state. */
+    readonly frame: number;
+    /** One of the sixteen direction-row cells. */
+    readonly lookDirection: number;
+    /** Whether the frame renderer should use the direction rows for this state. */
+    readonly lookDirectionActive: boolean;
+    /** Whether the renderer should schedule future frames. */
+    readonly animate: boolean;
+}
+/** Validation limits supplied by the owning host configuration. */
+export interface PetPackageValidationOptions {
+    /** Optional origin-relative asset URL assigned by the catalog owner. */
+    readonly assetUrl?: string;
+    /** Maximum UTF-8 manifest size. */
+    readonly maxManifestBytes?: number;
+    /** Maximum spritesheet size. */
+    readonly maxSpriteBytes?: number;
+}
+/** Validation options that also name the catalog origin recorded on the descriptor. */
+export interface PetPackageSourceOptions extends PetPackageValidationOptions {
+    /** Origin written verbatim onto the returned descriptor's `source`. */
+    readonly source: PetDescriptor['source'];
+}
+/** Stable validation error that callers can diagnose without parsing messages. */
+export declare class PetValidationError extends TypeError {
+    /** Machine-readable validation category. */
+    readonly code = "invalid-pet-package";
+    constructor(message: string);
+}
+/**
+ * Sort activity records by user-action urgency, then newest state transition,
+ * then their stable opaque session ids.
+ * @param left - the first activity record.
+ * @param right - the second activity record.
+ * @returns a standard ascending sort comparison result.
+ */
+export declare function comparePetActivities(left: PetSessionActivity, right: PetSessionActivity): number;
+/** Resolve a missing preference or validate a current preference document.
+ * @param value - decoded preference value from the settings provider.
+ * @returns the validated v3 preference.
+ */
+export declare function resolvePetPreference(value: unknown): PetPreference;
+/** Return the fresh v3 preference defaults.
+ * @returns a new v3 preference document.
+ */
+export declare function defaultPetPreference(): PetPreference;
+/** Validate one logical CSS height.
+ * @param sizePx - candidate logical CSS height.
+ * @returns the validated height.
+ */
+export declare function validatePetSize(sizePx: unknown): number;
+/** Return true only after pointer movement exceeds the shared four-pixel drag threshold.
+ * @param deltaX - horizontal pointer displacement.
+ * @param deltaY - vertical pointer displacement.
+ * @param threshold - minimum Euclidean displacement.
+ * @returns whether the displacement is a drag.
+ */
+export declare function isDragMovement(deltaX: number, deltaY: number, threshold?: number): boolean;
+/** Derive the logical CSS width from one validated atlas-cell height.
+ * @param sizePx - validated logical CSS height.
+ * @returns the corresponding logical CSS width.
+ */
+export declare function petWidthForSize(sizePx: number): number;
+/** Pick one of sixteen clockwise look-direction cells from a relative target.
+ * @param target - relative pointer target, or `undefined` for neutral direction.
+ * @returns a direction index from zero through fifteen.
+ */
+export declare function selectLookDirection(target: PetLookTarget | undefined): number;
+/** Select the state and first frame used to render one presentation update.
+ * @param input - current host, pointer, motion, and wake state.
+ * @returns the renderer-independent presentation selection.
+ */
+export declare function selectPetPresentation(input: PetPresentationInput): PetPresentation;
+/** Validate a compatible manifest and its WebP dimensions without Node or filesystem APIs.
+ * @param manifestBytes - UTF-8 pet.json bytes.
+ * @param spritesheetBytes - WebP atlas bytes.
+ * @param options - catalog origin, optional asset URL, and byte limits.
+ * @returns a sanitized descriptor suitable for client transport.
+ */
+export declare function validatePetPackage(manifestBytes: Uint8Array, spritesheetBytes: Uint8Array, options: PetPackageSourceOptions): PetDescriptor;
+/** Validate package bytes and retain the manifest-relative asset location for host storage.
+ * @param manifestBytes - UTF-8 pet.json bytes.
+ * @param spritesheetBytes - WebP atlas bytes.
+ * @param options - catalog origin, optional asset URL, and byte limits.
+ * @returns sanitized client metadata and the validated relative spritesheet path.
+ */
+export declare function validatePetPackageFiles(manifestBytes: Uint8Array, spritesheetBytes: Uint8Array, options: PetPackageSourceOptions): {
+    readonly descriptor: PetDescriptor;
+    readonly spritesheetPath: string;
+};
+/** Resolve the safe relative spritesheet location before reading the image file.
+ * @param manifestBytes - bounded UTF-8 pet.json bytes.
+ * @returns the manifest-relative spritesheet path.
+ */
+export declare function petSpritesheetPath(manifestBytes: Uint8Array): string;
+/** Convert a host activity record into the pet's display status.
+ * @param record - detached host activity record.
+ * @returns the display status, or `undefined` when the record is idle.
+ */
+export declare function petStatusForHostActivity(record: PetHostActivityRecord): PetActivityStatus | undefined;
+//# sourceMappingURL=runtime.d.ts.map