@linxin666/dsh-pet 0.1.1 → 0.1.3

package/lib/types/client/settings-form.js

@@ -0,0 +1,211 @@
+/**
+ * Staged form model behind the plugin settings card. A card stages what the
+ * user types and writes it only when they save — the settings write is a
+ * durable, revision-fenced document mutation, so staging keeps what is on
+ * screen exactly what a save would store. Mirrors the official
+ * ui-plugin-config card-store pattern in a self-contained slice: this
+ * package must not depend on a sibling UI package.
+ */
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client';
+/** A whole-number field. An empty draft clears the field; any other draft that is not a finite number blocks the save. */
+export function numberField(field) {
+    return {
+        field,
+        format: value => typeof value === 'number' ? String(value) : '',
+        parse: (text) => {
+            const trimmed = text.trim();
+            if (trimmed === '')
+                return { kind: 'clear' };
+            const parsed = Number(trimmed);
+            return Number.isFinite(parsed) ? { kind: 'set', value: parsed } : undefined;
+        },
+    };
+}
+/** A free-text field. An empty draft clears the field. */
+export function textField(field) {
+    return {
+        field,
+        format: value => typeof value === 'string' ? value : '',
+        parse: (text) => {
+            const trimmed = text.trim();
+            return trimmed === '' ? { kind: 'clear' } : { kind: 'set', value: trimmed };
+        },
+    };
+}
+/** A boolean field, edited through true/false draft text. */
+export function booleanField(field) {
+    return {
+        field,
+        format: value => typeof value === 'boolean' ? String(value) : '',
+        parse: (text) => {
+            if (text === 'true')
+                return { kind: 'set', value: true };
+            if (text === 'false')
+                return { kind: 'set', value: false };
+            return undefined;
+        },
+    };
+}
+/**
+ * Stages one card's edits over one settings namespace and writes them on save.
+ *
+ * The Host is the only authority on whether a value was accepted — its
+ * validators own the constraints no schema can express — so the outcome is
+ * read back from the section rather than predicted here. A save that did not
+ * land keeps its drafts, so the user can correct them instead of retyping.
+ */
+export class CardForm {
+    scope;
+    specs;
+    staged = new Map();
+    listeners = new Set();
+    saving = false;
+    failed = false;
+    /** @param scope - the bound settings scope for this card's namespace. */
+    constructor(scope, specs) {
+        this.scope = scope;
+        this.specs = new Map(specs.map(spec => [spec.field, spec]));
+        scope.subscribe(() => { this.publish(); });
+    }
+    /** Publish a projection of this form, rebuilt whenever the scope or a draft changes. */
+    bind(project) {
+        const store = createSnapshotStore(project());
+        this.listeners.add(() => { store.set(project()); });
+        return store;
+    }
+    /** Read the card-level state: what the Host serves, and what a save would do. */
+    shell() {
+        const snapshot = this.scope.getSnapshot();
+        const plan = this.plan();
+        return {
+            available: snapshot.status === 'ready',
+            writable: snapshot.writable,
+            dirty: plan.length > 0,
+            invalid: plan.some(item => item.run === undefined),
+            saving: this.saving,
+            failed: this.failed,
+        };
+    }
+    /** Read one field's state from the effective section and its staged draft. */
+    field(field) {
+        const spec = this.specOf(field);
+        const staged = this.staged.get(field);
+        if (staged === undefined) {
+            return { text: spec.format(this.sectionValue(field)), overridden: this.stored(field), invalid: false };
+        }
+        const write = staged.clear ? { kind: 'clear' } : spec.parse(staged.text);
+        return {
+            text: staged.text,
+            overridden: write?.kind === 'set',
+            invalid: write === undefined,
+        };
+    }
+    /** The actions the card's slot registration injects. */
+    actions() {
+        return {
+            edit: (field, text) => { this.stage(field, { text, clear: false }); },
+            resetField: (field) => {
+                this.stage(field, { text: this.specOf(field).format(this.baseValue(field)), clear: true });
+            },
+            save: () => { void this.save(); },
+            discard: () => {
+                if (this.staged.size === 0 && !this.failed)
+                    return;
+                this.staged.clear();
+                this.failed = false;
+                this.publish();
+            },
+        };
+    }
+    /**
+     * Write every staged edit, then re-seed from what the Host accepted.
+     * @returns settlement after every write and the read-back.
+     */
+    async save() {
+        const plan = this.plan();
+        const writes = plan.flatMap(item => item.run === undefined ? [] : [item.run]);
+        if (plan.length === 0 || this.saving || writes.length !== plan.length)
+            return;
+        this.saving = true;
+        this.failed = false;
+        this.publish();
+        let landed = true;
+        for (const write of writes) {
+            landed = await write() && landed;
+        }
+        if (landed)
+            this.staged.clear();
+        this.saving = false;
+        this.failed = !landed;
+        this.publish();
+    }
+    /**
+     * Every staged edit a save would write. An entry whose draft is not a value
+     * its field accepts carries no write: the form is still dirty, and the save
+     * refuses rather than dropping the edit. A staged edit that matches the
+     * effective section is not a write at all.
+     * @returns the planned writes, in the order the fields were staged.
+     */
+    plan() {
+        const plan = [];
+        for (const [field, staged] of this.staged) {
+            const spec = this.specOf(field);
+            if (staged.clear) {
+                if (this.stored(field))
+                    plan.push({ field, run: () => this.clear(field) });
+                continue;
+            }
+            if (staged.text === spec.format(this.sectionValue(field)))
+                continue;
+            const write = spec.parse(staged.text);
+            if (write === undefined)
+                plan.push({ field, run: undefined });
+            else if (write.kind === 'clear')
+                plan.push({ field, run: () => this.clear(field) });
+            else
+                plan.push({ field, run: () => this.store(field, write.value) });
+        }
+        return plan;
+    }
+    async clear(field) {
+        await this.scope.unset(field);
+        return !this.stored(field);
+    }
+    async store(field, value) {
+        await this.scope.set(field, value);
+        return this.userLayer()?.[field] === value;
+    }
+    stage(field, edit) {
+        this.staged.set(field, edit);
+        this.failed = false;
+        this.publish();
+    }
+    specOf(field) {
+        const spec = this.specs.get(field);
+        // Every call site names a field this card declared; a missing one is a
+        // wiring mistake that must not degrade into a silently inert control.
+        if (spec === undefined)
+            throw new Error(`settings card has no field ${field}`);
+        return spec;
+    }
+    snapshotOf() {
+        return this.scope.getSnapshot();
+    }
+    sectionValue(field) {
+        return this.snapshotOf().value?.[field];
+    }
+    baseValue(field) {
+        return this.snapshotOf().base?.[field];
+    }
+    userLayer() {
+        return this.snapshotOf().user;
+    }
+    stored(field) {
+        const user = this.userLayer();
+        return user !== undefined && Object.hasOwn(user, field);
+    }
+    publish() {
+        for (const listener of this.listeners)
+            listener();
+    }
+}

package/lib/types/client/slots-augment.js

@@ -0,0 +1 @@
+export {};

package/lib/types/client/spritesheet.js

@@ -0,0 +1,120 @@
+/**
+ * Whale-girl spritesheet geometry and animation tracks.
+ *
+ * The atlas follows the Codex/hatch-pet contract: 8 columns × 9 rows of
+ * 192×208 cells (1536×1872 total), rows in this order:
+ *   0 idle, 1 running-right, 2 running-left, 3 waving, 4 jumping,
+ *   5 failed, 6 waiting, 7 running, 8 review
+ *
+ * Frame counts and per-frame durations are per-track definitions below; the
+ * whale-girl atlas is produced by the hatch-pet pipeline, so calibrate
+ * `TRACKS` against the actual run (`pet_request.json` frame counts) when the
+ * asset lands. Tracks that do not loop hand off to `fallback`.
+ * @module @linxin666/dsh-pet/client/spritesheet
+ */
+/** Atlas cell size in px (Codex contract). */
+export const FRAME_WIDTH = 192;
+export const FRAME_HEIGHT = 208;
+/** Columns per row (max frames per track). */
+export const FRAME_COLUMNS = 8;
+/**
+ * Track definitions for the whale-girl. Durations are tuned for a soft,
+ * slow-healing feel (roughly 2.5× the earlier fast draft — the pet should
+ * breathe, not race); calibrate frame counts against the hatch-pet run when
+ * the asset lands (rows may carry 4–8 frames).
+ */
+export const TRACKS = {
+    idle: { frames: [0, 1, 2, 3, 4, 5], durations: [400, 400, 500, 400, 400, 500], loop: true },
+    'running-right': { frames: [0, 1, 2, 3, 4, 5, 6, 7], durations: [225, 225, 225, 225, 225, 225, 225, 225], loop: true },
+    'running-left': { frames: [0, 1, 2, 3, 4, 5, 6, 7], durations: [225, 225, 225, 225, 225, 225, 225, 225], loop: true },
+    waving: { frames: [0, 1, 2, 3], durations: [350, 350, 350, 350], loop: true },
+    jumping: { frames: [0, 1, 2, 3, 4], durations: [300, 300, 300, 350, 350], loop: false, fallback: 'idle' },
+    failed: { frames: [0, 1, 2, 3, 4, 5, 6, 7], durations: [450, 450, 450, 500, 550, 600, 450, 450], loop: false, fallback: 'idle' },
+    waiting: { frames: [0, 1, 2, 3, 4, 5], durations: [450, 450, 500, 450, 450, 500], loop: true },
+    running: { frames: [0, 1, 2, 3, 4, 5], durations: [250, 250, 250, 250, 250, 250], loop: true },
+    review: { frames: [0, 1, 2, 3, 4, 5], durations: [550, 550, 550, 550, 550, 550], loop: true },
+};
+/** Row index of one animation track (mirrors state.ts rowOf). */
+export function rowOfTrack(animation) {
+    const rows = {
+        idle: 0,
+        'running-right': 1,
+        'running-left': 2,
+        waving: 3,
+        jumping: 4,
+        failed: 5,
+        waiting: 6,
+        running: 7,
+        review: 8,
+    };
+    return rows[animation];
+}
+/**
+ * Background-position (px) of one frame cell within the scaled atlas.
+ * The background image is scaled by `scale` (element size ÷ cell size), and
+ * background-position offsets are applied in SCALED coordinates — using raw
+ * atlas coordinates here would drift each frame by the scale factor and
+ * render torn/overlapping frames.
+ */
+export function framePosition(row, col, scale = 1) {
+    return { x: -col * FRAME_WIDTH * scale, y: -row * FRAME_HEIGHT * scale };
+}
+/** Total duration of one track, ms. */
+export function trackDuration(track) {
+    return track.durations.reduce((sum, d) => sum + d, 0);
+}
+/**
+ * Detect how many frames each row actually carries by scanning the decoded
+ * atlas for non-transparent cells (hatch-pet rows may hold 4–8 frames; the
+ * unused trailing cells are fully transparent). Rows whose every sample is
+ * transparent report 0.
+ * @param image - the fully decoded spritesheet (natural size 1536×1872).
+ * @returns per-row frame counts, length 9.
+ */
+export function detectFrameCounts(image) {
+    const canvas = document.createElement('canvas');
+    canvas.width = image.naturalWidth;
+    canvas.height = image.naturalHeight;
+    const ctx = canvas.getContext('2d');
+    if (ctx === null)
+        return Array.from({ length: 9 }, () => FRAME_COLUMNS);
+    ctx.drawImage(image, 0, 0);
+    const data = ctx.getImageData(0, 0, canvas.width, canvas.height).data;
+    const counts = [];
+    const stride = FRAME_COLUMNS * FRAME_WIDTH;
+    const probeStep = 8;
+    const margin = 12;
+    for (let row = 0; row < 9; row++) {
+        let count = 0;
+        for (let col = 0; col < FRAME_COLUMNS; col++) {
+            let hasContent = false;
+            const x0 = col * FRAME_WIDTH;
+            const y0 = row * FRAME_HEIGHT;
+            for (let y = y0 + margin; y < y0 + FRAME_HEIGHT - margin && !hasContent; y += probeStep) {
+                for (let x = x0 + margin; x < x0 + FRAME_WIDTH - margin && !hasContent; x += probeStep) {
+                    const idx = (y * stride + x) * 4;
+                    if ((data[idx + 3] ?? 0) > 8)
+                        hasContent = true;
+                }
+            }
+            if (hasContent)
+                count += 1;
+        }
+        counts.push(count);
+    }
+    return counts;
+}
+/**
+ * Trim a track to the actual frame count of its row. A row with 0 detected
+ * frames degrades to the first frame (the atlas is still loading or corrupt)
+ * so the pet never renders blank.
+ */
+export function trimTrack(track, frameCount) {
+    const n = Math.max(1, Math.min(frameCount, track.frames.length));
+    return {
+        frames: track.frames.slice(0, n),
+        durations: track.durations.slice(0, n),
+        loop: track.loop,
+        ...(track.fallback === undefined ? {} : { fallback: track.fallback }),
+    };
+}

package/lib/types/index.js

@@ -0,0 +1,84 @@
+/**
+ * dsh-pet host half — mounts the pet service and its HTTP routes. The
+ * browser half (the `./client` entry) renders the whale-girl companion and
+ * drives it through the same-origin `/api/pet/*` JSON endpoints plus the
+ * `/pet/whale/*` media route. Install via `dsh plugin --profile web add
+ * link:<dsh-web-ui>/packages/dsh-pet`; the cordis.patch.yml inserts this plugin row.
+ * @module @linxin666/dsh-pet
+ */
+import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings';
+import z from 'schemastery';
+import { PetService, PET_SETTINGS_NAMESPACE } from "./service.js";
+import { makePetRoutes, petPackageRoot } from "./routes.js";
+import { DEFAULT_PET_NAME, DISPLAY_INSET_MAX, DISPLAY_SIZE_MAX, DISPLAY_SIZE_MIN, PET_NAME_MAX_LENGTH, } from "./persist.js";
+export { PetService } from "./service.js";
+export { AFFINITY_MAX, AFFINITY_RANKS, applyInteraction, applyTurnReward, emptyAffinity, rankOf, } from "./affinity.js";
+export { animationForPhase, PetStateMachine, rowOf, } from "./state.js";
+export { consumeTreat, defaultTreatConfig, emptyTreatLedger, settleTreatGrants, } from "./treats.js";
+export { defaultDisplayConfig, emptyPersist, loadPetPersist, petHomeDir, savePetPersist, } from "./persist.js";
+export { makePetRoutes, petPackageRoot, PET_API_PREFIX, PET_ASSET_PREFIX, } from "./routes.js";
+/** Stable cordis plugin name (matches cordis.patch.yml insert id). */
+export const name = 'pet';
+/** Services required before the pet can mount its surfaces. */
+export const inject = ['webServer'];
+/** Settings section schema: the display fields and name the web settings surface edits. */
+export const PET_SETTINGS_SCHEMA = z.object({
+    visible: z.boolean().default(true),
+    size: z.number().step(1).min(DISPLAY_SIZE_MIN).max(DISPLAY_SIZE_MAX).default(160),
+    right: z.number().step(1).min(0).max(DISPLAY_INSET_MAX).default(24),
+    bottom: z.number().step(1).min(0).max(DISPLAY_INSET_MAX).default(20),
+    name: z.string().min(1).max(PET_NAME_MAX_LENGTH).pattern(/\S/).default(DEFAULT_PET_NAME),
+    enabled: z.boolean().default(true),
+});
+/** Register the pet service and its API + asset routes on the context. */
+export function apply(ctx, config = {}) {
+    const service = new PetService(ctx, config);
+    // The settings surface edits the display config through the `pet`
+    // namespace. The composition `base` starts as the persisted pet.json
+    // values (clamped to schema bounds), so an empty user layer resolves to
+    // exactly what the pet already shows — a fresh deployment never
+    // overwrites a customized layout, and reset re-inherits it. Runtime drag
+    // interactions mirror back into the settings document through the service
+    // (see syncSettingsFromPet), keeping both views consistent.
+    let current = () => base;
+    const base = {
+        visible: service.display().visible,
+        size: service.display().size,
+        right: service.display().right,
+        bottom: service.display().bottom,
+        name: service.petName(),
+        enabled: config.enabled ?? true,
+    };
+    // The browser half talks to the pet through same-origin JSON endpoints and
+    // loads the atlas from the pet's own media route (RPC domains are
+    // platform-registered, so the pet serves its own API — the same pattern as
+    // dsh-remote-web-ui's /api/pair family). The routes are registered while
+    // the plugin is enabled; toggling the setting off makes the pet API
+    // disappear until it is re-enabled.
+    const routes = makePetRoutes({ service, packageRoot: petPackageRoot(import.meta.url) });
+    let disposeRoutes;
+    const syncRoutes = () => {
+        const enabled = current().enabled ?? true;
+        if (disposeRoutes === undefined && enabled) {
+            disposeRoutes = ctx.effect(() => {
+                const disposers = routes.map((route) => ctx.webServer.register(route));
+                return () => { for (const dispose of disposers)
+                    dispose(); };
+            }, 'pet: routes');
+        }
+        else if (disposeRoutes !== undefined && !enabled) {
+            disposeRoutes();
+            disposeRoutes = undefined;
+        }
+    };
+    installSettingsSection(ctx, settingsNamespace(PET_SETTINGS_NAMESPACE), PET_SETTINGS_SCHEMA, base, {
+        setSource: (source) => { current = source; },
+        onChange: () => {
+            const section = current();
+            service.applySettingsSection(section);
+            service.setEnabled(section.enabled ?? true);
+            syncRoutes();
+        },
+    });
+    syncRoutes();
+}

package/lib/types/invariant.js

@@ -0,0 +1,27 @@
+/**
+ * Package invariants — cheap structural checks run at import time on the
+ * host side. Mirrors the pattern used by other dsh plugin packages.
+ * @module @linxin666/dsh-pet/invariant
+ */
+import { AFFINITY_MAX, AFFINITY_RANKS, defaultAffinityConfig } from "./affinity.js";
+import { animationForPhase } from "./state.js";
+/** Assert a condition; throws a descriptive Error when violated. */
+export function invariant(condition, message) {
+    if (!condition) {
+        throw new Error(`[dsh-pet] ${message}`);
+    }
+}
+/** Run every package invariant once; throws on the first violation. */
+export function runPetInvariants() {
+    invariant(AFFINITY_MAX > 0, 'AFFINITY_MAX must be positive');
+    invariant(AFFINITY_RANKS.length > 0 && AFFINITY_RANKS[0].min === 0, 'AFFINITY_RANKS must start at 0');
+    invariant(defaultAffinityConfig.turnReward > 0, 'turnReward must be positive');
+    invariant(defaultAffinityConfig.feedCooldownMs > defaultAffinityConfig.petCooldownMs, 'feed cooldown must exceed pet cooldown');
+    // Every activity phase must map onto a known animation track.
+    const phases = ['idle', 'waiting', 'thinking', 'tool', 'done'];
+    for (const phase of phases) {
+        invariant(['idle', 'running', 'running-right', 'waiting', 'jumping'].includes(animationForPhase(phase)), `phase ${phase} maps outside the animation contract`);
+    }
+}
+// Run once on import (host half only; cheap and side-effect free).
+runPetInvariants();

package/lib/types/persist.js

@@ -0,0 +1,96 @@
+/**
+ * Pet persistence — tiny JSON store for affinity + display config, written
+ * under $DSH_HOME (defaults to ~/.dsh) as `pet.json`. Deliberately minimal:
+ * one file, atomic rename write, tolerant read (corrupt file → defaults).
+ * @module @linxin666/dsh-pet/persist
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { AFFINITY_MAX, emptyAffinity } from "./affinity.js";
+import { defaultTreatConfig, emptyTreatLedger } from "./treats.js";
+export const defaultDisplayConfig = {
+    visible: true,
+    size: 160,
+    right: 24,
+    bottom: 20,
+};
+/** Display value bounds (shared by load-time validation and setConfig). */
+export const DISPLAY_SIZE_MIN = 32;
+export const DISPLAY_SIZE_MAX = 512;
+export const DISPLAY_INSET_MAX = 10_000;
+/** Default pet name (used until the user renames the pet). */
+export const DEFAULT_PET_NAME = '鲸鱼娘';
+/** Name constraints. */
+export const PET_NAME_MAX_LENGTH = 20;
+export function emptyPersist() {
+    return {
+        name: DEFAULT_PET_NAME,
+        affinity: emptyAffinity(),
+        treats: emptyTreatLedger(),
+        display: { ...defaultDisplayConfig },
+    };
+}
+/** Resolve the persistence directory ($DSH_HOME or ~/.dsh). */
+export function petHomeDir() {
+    return process.env.DSH_HOME ?? join(homedir(), '.dsh');
+}
+/** Numeric field guard: finite numbers only, else the fallback. */
+function finiteNum(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+/** Clamp one count/score into [0, max]. */
+function clamp(value, max) {
+    return Math.min(max, Math.max(0, value));
+}
+/** Load persisted state; missing or corrupt files fall back to defaults. */
+export function loadPetPersist(dir = petHomeDir()) {
+    try {
+        const raw = readFileSync(join(dir, 'pet.json'), 'utf8');
+        const parsed = JSON.parse(raw);
+        const base = emptyPersist();
+        const rawAffinity = (parsed.affinity ?? {});
+        const affinity = {
+            points: clamp(finiteNum(rawAffinity.points, 0), AFFINITY_MAX),
+            lastPetAt: clamp(finiteNum(rawAffinity.lastPetAt, 0), Number.MAX_SAFE_INTEGER),
+            lastFeedAt: clamp(finiteNum(rawAffinity.lastFeedAt, 0), Number.MAX_SAFE_INTEGER),
+            pets: clamp(finiteNum(rawAffinity.pets, 0), Number.MAX_SAFE_INTEGER),
+            feeds: clamp(finiteNum(rawAffinity.feeds, 0), Number.MAX_SAFE_INTEGER),
+            turns: clamp(finiteNum(rawAffinity.turns, 0), Number.MAX_SAFE_INTEGER),
+        };
+        const rawTreats = (parsed.treats ?? {});
+        const treats = {
+            treats: clamp(finiteNum(rawTreats.treats, 0), defaultTreatConfig.maxTreats),
+            lastTreatGrantAt: clamp(finiteNum(rawTreats.lastTreatGrantAt, 0), Number.MAX_SAFE_INTEGER),
+            turnsAtLastTreatGrant: clamp(finiteNum(rawTreats.turnsAtLastTreatGrant, 0), Number.MAX_SAFE_INTEGER),
+        };
+        const rawDisplay = (parsed.display ?? {});
+        const display = {
+            visible: typeof rawDisplay.visible === 'boolean' ? rawDisplay.visible : base.display.visible,
+            // The settings schema requires whole pixels; drag positions are
+            // clamped but not integral, so round at the persistence boundary.
+            size: Math.round(Math.min(DISPLAY_SIZE_MAX, Math.max(DISPLAY_SIZE_MIN, finiteNum(rawDisplay.size, base.display.size)))),
+            right: Math.round(clamp(finiteNum(rawDisplay.right, base.display.right), DISPLAY_INSET_MAX)),
+            bottom: Math.round(clamp(finiteNum(rawDisplay.bottom, base.display.bottom), DISPLAY_INSET_MAX)),
+        };
+        return {
+            name: typeof parsed.name === 'string' && parsed.name.trim() !== ''
+                ? parsed.name
+                : base.name,
+            affinity,
+            treats,
+            display,
+        };
+    }
+    catch {
+        return emptyPersist();
+    }
+}
+/** Atomically persist state (write temp + rename). */
+export function savePetPersist(data, dir = petHomeDir()) {
+    mkdirSync(dir, { recursive: true });
+    const target = join(dir, 'pet.json');
+    const tmp = `${target}.tmp`;
+    writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf8');
+    renameSync(tmp, target);
+}