@luv1211/dsh-pet 0.1.1-rc.2

package/lib/invariant.js

@@ -0,0 +1,19 @@
+//#region lib/types/invariant.js
+/** Package-owned invariant companion. @module @luv1211/dsh-pet/invariant */
+const PACKAGE_NAME = "@luv1211/dsh-pet";
+/** Cordis companion plugin name. */
+const name = "pet-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the preference document persists through the
+* settings seam (schema-validated there), and activity records are
+* presentation state the service derives and owns alone, so a companion
+* would restate the service rather than check a relation another package
+* can violate.
+*/
+const install = () => {};
+/** Register this package's invariant companion. */
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/activity.d.ts

@@ -0,0 +1,29 @@
+/** Host activity projection adapter consumed by the pet domain. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { PetActivitySource, PetHostActivityRecord } from './types.ts';
+/**
+ * Owns detached host activity records and publishes whole replacements. When
+ * constructed with a Context, it supplies the existing session lifecycle as
+ * the default host producer; a richer host projection can instead be
+ * provided to PetService through the `petActivity` service key.
+ */
+export declare class PetActivityProjection implements PetActivitySource {
+    private readonly records;
+    private readonly listeners;
+    /**
+     * @param ctx - optional host context for the default session producer.
+     */
+    constructor(ctx?: Context);
+    /** Read a detached activity projection. */
+    getSnapshot(): readonly PetHostActivityRecord[];
+    /** Subscribe to whole detached projection replacements. */
+    subscribe(listener: (records: readonly PetHostActivityRecord[]) => void): () => void;
+    /** Publish one host-owned replacement after its producer commits.
+     * @param records - detached records replacing the current projection.
+     */
+    publish(records: readonly PetHostActivityRecord[]): void;
+    private observe;
+    private forget;
+    private notify;
+}
+//# sourceMappingURL=activity.d.ts.map

package/lib/types/activity.js

@@ -0,0 +1,63 @@
+/** Host activity projection adapter consumed by the pet domain. */
+/**
+ * Owns detached host activity records and publishes whole replacements. When
+ * constructed with a Context, it supplies the existing session lifecycle as
+ * the default host producer; a richer host projection can instead be
+ * provided to PetService through the `petActivity` service key.
+ */
+export class PetActivityProjection {
+    records = new Map();
+    listeners = new Set();
+    /**
+     * @param ctx - optional host context for the default session producer.
+     */
+    constructor(ctx) {
+        if (ctx === undefined)
+            return;
+        ctx.on('session/event', (session, event) => { this.observe(session, event); }, { global: true });
+        ctx.on('session/disposed', (session) => { this.forget(session); }, { global: true });
+    }
+    /** Read a detached activity projection. */
+    getSnapshot() {
+        return [...this.records.values()].map(record => ({ ...record }));
+    }
+    /** Subscribe to whole detached projection replacements. */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    /** Publish one host-owned replacement after its producer commits.
+     * @param records - detached records replacing the current projection.
+     */
+    publish(records) {
+        this.records.clear();
+        for (const record of records)
+            this.records.set(String(record.sessionId), { ...record });
+        this.notify();
+    }
+    observe(session, event) {
+        if (event.type !== 'turn/start' && event.type !== 'turn/end')
+            return;
+        const record = event.type === 'turn/start'
+            ? { sessionId: session.id, title: String(session.id), status: 'running', since: event.time, completed: false }
+            : {
+                sessionId: session.id,
+                title: String(session.id),
+                status: event.data.reason.kind === 'blocked' || event.data.reason.kind === 'error' ? 'blocked' : 'idle',
+                since: event.time,
+                completed: event.data.reason.kind !== 'blocked' && event.data.reason.kind !== 'error',
+            };
+        this.records.set(String(session.id), record);
+        this.notify();
+    }
+    forget(session) {
+        if (this.records.delete(String(session.id)))
+            this.notify();
+    }
+    notify() {
+        const snapshot = this.getSnapshot();
+        for (const listener of this.listeners)
+            listener(snapshot);
+    }
+}
+//# sourceMappingURL=activity.js.map

package/lib/types/catalog.d.ts

@@ -0,0 +1,67 @@
+/** Host-side compatible pet catalog and transactional user-package storage. */
+import { type PetPackageValidationOptions } from './runtime.ts';
+import type { PetCatalog, PetDescriptor } from './types.ts';
+/** Configured filesystem limits and the one DSH-owned user package root. */
+export interface PetCatalogOptions extends PetPackageValidationOptions {
+    /** Explicit DSH home used when petRoot is absent. */
+    readonly dshHome?: string;
+    /** One user-managed package root; defaults to `<dshHome>/pets`. */
+    readonly petRoot?: string;
+    /** Maximum wall time for one complete user-image decode. */
+    readonly decodeTimeoutMs?: number;
+}
+/** One validated built-in or user package with detached client metadata. */
+export declare class PetCatalogStore {
+    /** Absolute DSH-owned directory for user-installed pet packages. */
+    readonly petRoot: string;
+    private readonly options;
+    private readonly records;
+    private readonly listeners;
+    /**
+     * Load the embedded package and the configured DSH user root.
+     * @param options - package root and validation limits.
+     */
+    constructor(options?: PetCatalogOptions);
+    /** Read a detached deterministic catalog.
+     * @returns a stable descriptor list without filesystem references.
+     */
+    getCatalog(): PetCatalog;
+    /** Return a detached validated sprite for one catalog-owned id.
+     * @param id - catalog id to resolve.
+     * @returns a copied sprite byte array, or `undefined` for an unknown id.
+     */
+    getAsset(id: string): Uint8Array | undefined;
+    /** Subscribe to catalog publication and return its disposer.
+     * @param listener - callback receiving each detached catalog.
+     * @returns a disposer that removes the listener.
+     */
+    subscribe(listener: (catalog: PetCatalog) => void): () => void;
+    /** Check that an id names a loaded package.
+     * @param id - catalog id to test.
+     * @returns whether the id is currently loaded.
+     */
+    has(id: string): boolean;
+    /** Create the configured user root before a host action opens it. */
+    ensureRoot(): void;
+    /**
+     * Atomically publish one validated package under the user root.
+     * @param manifestBytes - UTF-8 compatible pet.json bytes.
+     * @param spritesheetBytes - validated WebP bytes.
+     * @returns the newly published descriptor.
+     */
+    importPackage(manifestBytes: Uint8Array, spritesheetBytes: Uint8Array): PetDescriptor;
+    /**
+     * Atomically replace one existing user package's content in place.
+     * @param manifestBytes - UTF-8 compatible pet.json bytes whose id names a loaded user package.
+     * @param spritesheetBytes - validated WebP bytes.
+     * @returns the freshly published descriptor.
+     */
+    replacePackage(manifestBytes: Uint8Array, spritesheetBytes: Uint8Array): PetDescriptor;
+    /** Dispose all update listeners owned by the catalog service. */
+    dispose(): void;
+    /** Delete the `.tmp` residue of earlier interrupted imports or replacements of one id. */
+    private sweepTemporaryDirectories;
+    /** Reload validated package records from the embedded assets and the user root, then publish one detached catalog. */
+    reload(): void;
+}
+//# sourceMappingURL=catalog.d.ts.map

package/lib/types/catalog.js

@@ -0,0 +1,258 @@
+/** Host-side compatible pet catalog and transactional user-package storage. */
+import { closeSync, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readSync, realpathSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { resolveDshHome } from '@deepseek-ai/dsh-home-paths';
+import { DEFAULT_PET_ID, petSpritesheetPath, validatePetPackageFiles, } from "./runtime.js";
+import { decodeWebpDimensions } from "./host-image.js";
+/** One validated built-in or user package with detached client metadata. */
+export class PetCatalogStore {
+    /** Absolute DSH-owned directory for user-installed pet packages. */
+    petRoot;
+    options;
+    records = new Map();
+    listeners = new Set();
+    /**
+     * Load the embedded package and the configured DSH user root.
+     * @param options - package root and validation limits.
+     */
+    constructor(options = {}) {
+        this.options = { ...options };
+        this.petRoot = resolve(options.petRoot ?? join(resolveDshHome(options.dshHome), 'pets'));
+        this.reload();
+    }
+    /** Read a detached deterministic catalog.
+     * @returns a stable descriptor list without filesystem references.
+     */
+    getCatalog() {
+        return Object.freeze({ pets: Object.freeze([...this.records.values()].map(record => ({ ...record.descriptor }))) });
+    }
+    /** Return a detached validated sprite for one catalog-owned id.
+     * @param id - catalog id to resolve.
+     * @returns a copied sprite byte array, or `undefined` for an unknown id.
+     */
+    getAsset(id) {
+        const record = this.records.get(id);
+        return record === undefined ? undefined : new Uint8Array(record.spriteBytes);
+    }
+    /** Subscribe to catalog publication and return its disposer.
+     * @param listener - callback receiving each detached catalog.
+     * @returns a disposer that removes the listener.
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    /** Check that an id names a loaded package.
+     * @param id - catalog id to test.
+     * @returns whether the id is currently loaded.
+     */
+    has(id) {
+        return this.records.has(id);
+    }
+    /** Create the configured user root before a host action opens it. */
+    ensureRoot() {
+        mkdirSync(this.petRoot, { recursive: true });
+    }
+    /**
+     * Atomically publish one validated package under the user root.
+     * @param manifestBytes - UTF-8 compatible pet.json bytes.
+     * @param spritesheetBytes - validated WebP bytes.
+     * @returns the newly published descriptor.
+     */
+    importPackage(manifestBytes, spritesheetBytes) {
+        const firstPass = validatePetPackageFiles(manifestBytes, spritesheetBytes, { ...this.options, assetUrl: '', source: 'user' });
+        decodeWebpDimensions(spritesheetBytes, this.options.decodeTimeoutMs ?? 10_000);
+        if (firstPass.descriptor.id === DEFAULT_PET_ID)
+            throw new Error(`pet id ${DEFAULT_PET_ID} is reserved for the built-in package`);
+        if (this.records.has(firstPass.descriptor.id))
+            throw new Error(`pet id ${firstPass.descriptor.id} is already registered`);
+        mkdirSync(this.petRoot, { recursive: true });
+        const target = join(this.petRoot, firstPass.descriptor.id);
+        if (existsSync(target))
+            throw new Error(`pet package directory ${firstPass.descriptor.id} already exists`);
+        const temporary = join(this.petRoot, `.${firstPass.descriptor.id}.${randomUUID()}.tmp`);
+        try {
+            mkdirSync(temporary);
+            writeFileSync(join(temporary, 'pet.json'), manifestBytes, { flag: 'wx' });
+            const spriteTarget = join(temporary, firstPass.spritesheetPath.replaceAll('\\', '/'));
+            mkdirSync(dirname(spriteTarget), { recursive: true });
+            writeFileSync(spriteTarget, spritesheetBytes, { flag: 'wx' });
+            renameSync(temporary, target);
+        }
+        catch (error) {
+            rmSync(temporary, { recursive: true, force: true });
+            throw error;
+        }
+        this.reload();
+        const published = this.records.get(firstPass.descriptor.id)?.descriptor;
+        if (published === undefined)
+            throw new Error(`pet package ${firstPass.descriptor.id} was not published after atomic rename`);
+        return { ...published };
+    }
+    /**
+     * Atomically replace one existing user package's content in place.
+     * @param manifestBytes - UTF-8 compatible pet.json bytes whose id names a loaded user package.
+     * @param spritesheetBytes - validated WebP bytes.
+     * @returns the freshly published descriptor.
+     */
+    replacePackage(manifestBytes, spritesheetBytes) {
+        const firstPass = validatePetPackageFiles(manifestBytes, spritesheetBytes, { ...this.options, assetUrl: '', source: 'user' });
+        decodeWebpDimensions(spritesheetBytes, this.options.decodeTimeoutMs ?? 10_000);
+        const id = firstPass.descriptor.id;
+        if (this.records.get(id)?.source !== 'user')
+            throw new TypeError(`pet package ${id} is not an updatable user package`);
+        mkdirSync(this.petRoot, { recursive: true });
+        this.sweepTemporaryDirectories(id);
+        const target = join(this.petRoot, id);
+        // renameSync cannot overwrite a non-empty directory (EPERM on Windows,
+        // ENOTEMPTY on POSIX), so the swap is fixed at three renames. The target
+        // is briefly absent between the first two; every interruption outside
+        // that adjacent pair leaves either the complete old or complete new
+        // content, and a crash inside it leaves only same-id `.tmp` residue.
+        const staged = join(this.petRoot, `.${id}.${randomUUID()}.tmp`);
+        const aside = join(this.petRoot, `.${id}.${randomUUID()}.tmp`);
+        try {
+            mkdirSync(staged);
+            writeFileSync(join(staged, 'pet.json'), manifestBytes, { flag: 'wx' });
+            const spriteTarget = join(staged, firstPass.spritesheetPath.replaceAll('\\', '/'));
+            mkdirSync(dirname(spriteTarget), { recursive: true });
+            writeFileSync(spriteTarget, spritesheetBytes, { flag: 'wx' });
+            renameSync(target, aside);
+            try {
+                renameSync(staged, target);
+            }
+            catch (error) {
+                renameSync(aside, target);
+                throw error;
+            }
+        }
+        catch (error) {
+            rmSync(staged, { recursive: true, force: true });
+            throw error;
+        }
+        rmSync(aside, { recursive: true, force: true });
+        this.reload();
+        const published = this.records.get(id)?.descriptor;
+        if (published === undefined)
+            throw new Error(`pet package ${id} was not published after replacement`);
+        return { ...published };
+    }
+    /** Dispose all update listeners owned by the catalog service. */
+    dispose() {
+        this.listeners.clear();
+        this.records.clear();
+    }
+    /** Delete the `.tmp` residue of earlier interrupted imports or replacements of one id. */
+    sweepTemporaryDirectories(id) {
+        for (const entry of readdirSync(this.petRoot, { withFileTypes: true })) {
+            if (entry.name.startsWith(`.${id}.`) && entry.name.endsWith('.tmp')) {
+                rmSync(join(this.petRoot, entry.name), { recursive: true, force: true });
+            }
+        }
+    }
+    /** Reload validated package records from the embedded assets and the user root, then publish one detached catalog. */
+    reload() {
+        const next = new Map();
+        const builtin = readValidatedPackage(new URL('../assets/deepseek-whale/pet.json', import.meta.url), this.options, 'builtin');
+        next.set(DEFAULT_PET_ID, builtin);
+        if (existsSync(this.petRoot) && isDirectory(this.petRoot)) {
+            for (const entry of readdirSync(this.petRoot, { withFileTypes: true })) {
+                if (!entry.isDirectory() || entry.isSymbolicLink() || entry.name.startsWith('.'))
+                    continue;
+                const directory = join(this.petRoot, entry.name);
+                if (entry.name === DEFAULT_PET_ID)
+                    continue;
+                try {
+                    const record = readValidatedPackage(join(directory, 'pet.json'), this.options, 'user');
+                    if (next.has(record.descriptor.id))
+                        throw new Error(`pet id ${record.descriptor.id} is duplicated`);
+                    next.set(record.descriptor.id, record);
+                }
+                catch {
+                    // A malformed user package is excluded from the catalog. The next
+                    // explicit catalog read remains deterministic and never exposes its path.
+                }
+            }
+        }
+        this.records.clear();
+        for (const id of [DEFAULT_PET_ID, ...[...next.keys()].filter(key => key !== DEFAULT_PET_ID).sort()]) {
+            const record = next.get(id);
+            if (record !== undefined)
+                this.records.set(id, record);
+        }
+        const catalog = this.getCatalog();
+        for (const listener of this.listeners)
+            listener(catalog);
+    }
+}
+function readValidatedPackage(manifest, options, source) {
+    const maxManifestBytes = options.maxManifestBytes ?? 16 * 1024;
+    const maxSpriteBytes = options.maxSpriteBytes ?? 16 * 1024 * 1024;
+    const manifestBytes = readRegularFile(manifest, 'pet manifest', maxManifestBytes);
+    const relativeSprite = petSpritesheetPath(manifestBytes);
+    const spriteLocation = manifest instanceof URL
+        ? new URL(relativeSprite.replaceAll('\\', '/'), manifest)
+        : join(dirname(manifest), relativeSprite.replaceAll('\\', '/'));
+    if (typeof manifest === 'string' && typeof spriteLocation === 'string')
+        assertContainedFile(dirname(manifest), spriteLocation);
+    const spriteBytes = readRegularFile(spriteLocation, 'pet spritesheet', maxSpriteBytes);
+    const validated = validatePetPackageFiles(manifestBytes, spriteBytes, {
+        ...options,
+        assetUrl: '',
+        source,
+    });
+    if (source === 'user')
+        decodeWebpDimensions(spriteBytes, options.decodeTimeoutMs ?? 10_000);
+    const id = validated.descriptor.id;
+    const descriptor = Object.freeze({ ...validated.descriptor, assetUrl: `/__dsh/pet/assets/${id}/spritesheet.webp` });
+    if (descriptor.id !== id)
+        throw new Error(`pet package id ${descriptor.id} does not match its catalog key ${id}`);
+    return { descriptor, spriteBytes, source };
+}
+function readRegularFile(path, label, maxBytes) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0)
+        throw new Error(`${label} byte limit is invalid`);
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink())
+        throw new Error(`${label} must be a regular file`);
+    if (stat.size > maxBytes)
+        throw new Error(`${label} exceeds the configured byte limit`);
+    const handle = openSync(path, 'r');
+    try {
+        const openedStat = fstatSync(handle);
+        if (!openedStat.isFile() || openedStat.size > maxBytes)
+            throw new Error(`${label} exceeds the configured byte limit`);
+        const bytes = new Uint8Array(openedStat.size + 1);
+        let offset = 0;
+        while (offset < bytes.byteLength) {
+            const count = readSync(handle, bytes, offset, bytes.byteLength - offset, null);
+            if (count === 0)
+                break;
+            offset += count;
+        }
+        if (offset !== openedStat.size)
+            throw new Error(`${label} changed while it was being read`);
+        return bytes.subarray(0, offset);
+    }
+    finally {
+        closeSync(handle);
+    }
+}
+function assertContainedFile(packageRoot, candidate) {
+    const canonicalRoot = realpathSync(packageRoot);
+    const canonicalCandidate = realpathSync(candidate);
+    const fromRoot = relative(canonicalRoot, canonicalCandidate);
+    if (fromRoot.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) || fromRoot === '..' || isAbsolute(fromRoot)) {
+        throw new Error('pet spritesheet must stay inside its package directory');
+    }
+}
+function isDirectory(path) {
+    try {
+        return lstatSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=catalog.js.map

package/lib/types/client.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Client-namespace projection of the pet domain: a pure re-export of the
+ * package's types outlet. Client code imports ONLY the client namespace
+ * (repo discipline), so `./client` projects the same single-source content
+ * `./types` serves to host consumers — zero duplication.
+ * @module @luv1211/dsh-pet/client
+ */
+export type * from './types.ts';
+export type * from './renderer.ts';
+export type { PetAnimationState, PetDragDirection, PetLookTarget, PetPresentation, PetPresentationInput } from './runtime.ts';
+export { DEFAULT_PET_ID, DEFAULT_PET_SIZE_PX, MAX_PET_SIZE_PX, MIN_PET_SIZE_PX, PET_PREFERENCE_VERSION, PET_COMPAT_ATLAS, PetValidationError, comparePetActivities, defaultPetPreference, isDragMovement, petStatusForHostActivity, petWidthForSize, resolvePetPreference, selectLookDirection, selectPetPresentation, validatePetSize, validatePetPackage, } from './runtime.ts';
+export { petSpriteAvatar, petSpriteFrame } from './renderer.ts';
+//# sourceMappingURL=client.d.ts.map

package/lib/types/client.js

@@ -0,0 +1,10 @@
+/**
+ * Client-namespace projection of the pet domain: a pure re-export of the
+ * package's types outlet. Client code imports ONLY the client namespace
+ * (repo discipline), so `./client` projects the same single-source content
+ * `./types` serves to host consumers — zero duplication.
+ * @module @luv1211/dsh-pet/client
+ */
+export { DEFAULT_PET_ID, DEFAULT_PET_SIZE_PX, MAX_PET_SIZE_PX, MIN_PET_SIZE_PX, PET_PREFERENCE_VERSION, PET_COMPAT_ATLAS, PetValidationError, comparePetActivities, defaultPetPreference, isDragMovement, petStatusForHostActivity, petWidthForSize, resolvePetPreference, selectLookDirection, selectPetPresentation, validatePetSize, validatePetPackage, } from "./runtime.js";
+export { petSpriteAvatar, petSpriteFrame } from "./renderer.js";
+//# sourceMappingURL=client.js.map

package/lib/types/host-image.d.ts

@@ -0,0 +1,11 @@
+/** Host-only complete WebP decoding for package publication. */
+/** Decode every pixel in a bounded WebP inside an isolated process.
+ * @param bytes - already byte-limited candidate WebP data.
+ * @param timeoutMs - positive host-configured decode deadline.
+ * @returns dimensions reported by the successful decoder.
+ */
+export declare function decodeWebpDimensions(bytes: Uint8Array, timeoutMs: number): {
+    readonly width: number;
+    readonly height: number;
+};
+//# sourceMappingURL=host-image.d.ts.map

package/lib/types/host-image.js

@@ -0,0 +1,48 @@
+/** Host-only complete WebP decoding for package publication. */
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { scrubbedParentEnv } from '@deepseek-ai/dsh-subprocess';
+import { PetValidationError } from "./runtime.js";
+const SHARP_ENTRY_URL = pathToFileURL(createRequire(import.meta.url).resolve('sharp')).href;
+const DECODE_SCRIPT = `
+import fs from 'node:fs';
+import sharp from ${JSON.stringify(SHARP_ENTRY_URL)};
+const input = fs.readFileSync(0);
+try {
+  const result = await sharp(input).raw().toBuffer({ resolveWithObject: true });
+  process.stdout.write(JSON.stringify({ width: result.info.width, height: result.info.height }));
+} catch (error) {
+  process.stderr.write(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}
+`;
+/** Decode every pixel in a bounded WebP inside an isolated process.
+ * @param bytes - already byte-limited candidate WebP data.
+ * @param timeoutMs - positive host-configured decode deadline.
+ * @returns dimensions reported by the successful decoder.
+ */
+export function decodeWebpDimensions(bytes, timeoutMs) {
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0)
+        throw new PetValidationError('pet spritesheet decode timeout must be positive');
+    const result = spawnSync(process.execPath, ['--input-type=module', '--eval', DECODE_SCRIPT], {
+        input: bytes,
+        encoding: 'utf8',
+        env: scrubbedParentEnv(),
+        maxBuffer: 64 * 1024,
+        timeout: timeoutMs,
+        windowsHide: true,
+    });
+    if (result.status !== 0)
+        throw new PetValidationError('pet spritesheet must be a decodable WebP image');
+    try {
+        const dimensions = JSON.parse(result.stdout);
+        if (!Number.isSafeInteger(dimensions.width) || !Number.isSafeInteger(dimensions.height))
+            throw new Error('invalid decoder result');
+        return { width: dimensions.width, height: dimensions.height };
+    }
+    catch {
+        throw new PetValidationError('pet spritesheet decoder returned invalid dimensions');
+    }
+}
+//# sourceMappingURL=host-image.js.map

package/lib/types/host-native.d.ts

@@ -0,0 +1,17 @@
+/** Host-native pet package and folder operations assembled from existing host seams. */
+import type { DirectoryPickerCapability } from '@deepseek-ai/dsh-host-directory-picker';
+import type { PetNativeActions } from './types.ts';
+/** Injectable filesystem/open hooks used by the host adapter tests. */
+export interface PetNativeActionInternals {
+    /** Read one selected package file. */
+    readFile?: (path: string) => Promise<Uint8Array>;
+    /** Open one host path with its default application. */
+    openPath?: (path: string) => Promise<void>;
+}
+/** Assemble pet actions only when the composed directory picker is native.
+ * @param capability - composed directory picker capability.
+ * @param internals - optional filesystem and host-open test seams.
+ * @returns native pet actions, or `undefined` for browser-only pickers.
+ */
+export declare function createPetNativeActions(capability: DirectoryPickerCapability | undefined, internals?: PetNativeActionInternals): PetNativeActions | undefined;
+//# sourceMappingURL=host-native.d.ts.map

package/lib/types/host-native.js

@@ -0,0 +1,50 @@
+/** Host-native pet package and folder operations assembled from existing host seams. */
+import { lstat, readFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { openNativePath } from "./path-opener.js";
+import { petSpritesheetPath } from "./runtime.js";
+/** Assemble pet actions only when the composed directory picker is native.
+ * @param capability - composed directory picker capability.
+ * @param internals - optional filesystem and host-open test seams.
+ * @returns native pet actions, or `undefined` for browser-only pickers.
+ */
+export function createPetNativeActions(capability, internals = {}) {
+    if (capability?.kind !== 'native')
+        return undefined;
+    const read = internals.readFile ?? (async (path) => new Uint8Array(await readFile(path)));
+    const open = internals.openPath ?? (path => openNativePath(path, new AbortController().signal));
+    return {
+        async pickPetPackage() {
+            const selected = await capability.pick(new AbortController().signal);
+            if (selected === null)
+                return null;
+            const directory = await packageDirectory(selected);
+            const manifestBytes = await read(join(directory, 'pet.json'));
+            const spritesheetPath = petSpritesheetPath(manifestBytes);
+            return {
+                manifestBytes,
+                spritesheetBytes: await read(join(directory, spritesheetPath.replaceAll('\\', '/'))),
+            };
+        },
+        openPetFolder: open,
+    };
+}
+/** Resolve a picker result to one package directory and reject links or unrelated files. */
+async function packageDirectory(selected) {
+    const target = resolve(selected);
+    const targetStat = await lstat(target);
+    if (targetStat.isDirectory() && !targetStat.isSymbolicLink())
+        return target;
+    if (!targetStat.isFile() || targetStat.isSymbolicLink())
+        throw new Error('pet package selection must be a directory or package file');
+    const name = basename(target);
+    if (name !== 'pet.json' && name !== 'spritesheet.webp') {
+        throw new Error('pet package selection must name pet.json or spritesheet.webp');
+    }
+    const directory = dirname(target);
+    const directoryStat = await lstat(directory);
+    if (!directoryStat.isDirectory() || directoryStat.isSymbolicLink())
+        throw new Error('pet package directory is invalid');
+    return directory;
+}
+//# sourceMappingURL=host-native.js.map