@linxin666/dsh-pet 0.2.9 → 0.3.0

package/lib/types/registry.js

@@ -302,9 +302,20 @@ function resolveLive2dEntry(manifest, dir, options) {
         record('error', 'pet ' + manifest.id + ': renderer live2d requires a live2d block');
         return undefined;
     }
+    const modelFile = join(dir, block.model);
     let model3;
     try {
-        model3 = JSON.parse(readFileSync(join(dir, block.model), 'utf8'));
+        // Stat guard before the read: a pathological model file — huge, or a
+        // FIFO/device — is skipped with a warning instead of stalling the host
+        // at scan time, mirroring the voice/decoration descriptor discipline.
+        // The guard stays silent on stat errors, so a missing or unreadable
+        // path is re-stat'ed here to fall through to the original fail-closed
+        // 'not readable' diagnostic below.
+        if (guardedScannedJsonStat(modelFile, options, 'live2d model ' + block.model, PET_SCAN_LIVE2D_MODEL_CAP) === undefined) {
+            statSync(modelFile);
+            return undefined;
+        }
+        model3 = JSON.parse(readFileSync(modelFile, 'utf8'));
     }
     catch (error) {
         record('error', 'pet ' + manifest.id + ': live2d model ' + block.model + ' is not readable: '
@@ -373,7 +384,7 @@ function scanPetDir(dir, options) {
         const manifestFile = join(dir, name, 'pet.json');
         if (!existsSync(manifestFile))
             continue;
-        const parsed = readPetJson(manifestFile, options.warnings);
+        const parsed = readPetJson(manifestFile, options);
         if (parsed === undefined)
             continue;
         const entryDir = join(dir, name);
@@ -406,13 +417,20 @@ function scanPetDir(dir, options) {
     }
     return entries;
 }
-/** Read and parse one manifest file; undefined (warning recorded) on failure. */
-function readPetJson(file, warnings) {
+/**
+ * Read and parse one pet.json manifest; undefined (warning recorded) on
+ * failure. The descriptor stat guard applies first: a pathological file —
+ * huge, or a FIFO/device — is skipped with a warning instead of stalling
+ * or OOM-ing the host at scan time (same discipline as voice/decoration).
+ */
+function readPetJson(file, options) {
+    if (guardedScannedJsonStat(file, options, 'pet manifest') === undefined)
+        return undefined;
     try {
         return JSON.parse(readFileSync(file, 'utf8'));
     }
     catch (error) {
-        warnings?.push('skipping ' + file + ': ' + (error instanceof Error ? error.message : String(error)));
+        options.warnings?.push('skipping ' + file + ': ' + (error instanceof Error ? error.message : String(error)));
         return undefined;
     }
 }
@@ -424,13 +442,23 @@ function readPetJson(file, warnings) {
  * discipline can apply (review-spd follow-up, pet-center M4/M5).
  */
 export const PET_SCAN_JSON_CAP = 64 * 1024;
+/**
+ * Scan-time read ceiling for a live2d model3.json, matching the asset
+ * route's model cap (PET_ASSET_CAPS.model). Model descriptors are far
+ * larger than the other scanned JSON, but a pathological file — huge, or a
+ * FIFO/device — must still be skipped with a warning instead of stalling
+ * or OOM-ing the host at plugin startup (same review-spd follow-up).
+ */
+export const PET_SCAN_LIVE2D_MODEL_CAP = 32 * 1024 * 1024;
 /**
  * Stat one scanned JSON descriptor with a regular-file + size guard, so a
  * pathological user file is skipped with a warning instead of stalling or
  * OOM-ing the host at startup. Returns the Stats, or undefined when the
- * caller must skip the file (a warning was recorded).
+ * caller must skip the file (a warning was recorded). 'cap' defaults to
+ * the descriptor ceiling (PET_SCAN_JSON_CAP); model descriptors pass the
+ * larger live2d ceiling.
  */
-function guardedScannedJsonStat(file, options, what) {
+function guardedScannedJsonStat(file, options, what, cap = PET_SCAN_JSON_CAP) {
     let st;
     try {
         st = statSync(file);
@@ -446,8 +474,8 @@ function guardedScannedJsonStat(file, options, what) {
         warn(what + ' is not a regular file; ignored');
         return undefined;
     }
-    if (st.size > PET_SCAN_JSON_CAP) {
-        warn(what + ' exceeds the ' + PET_SCAN_JSON_CAP + '-byte scan ceiling; ignored');
+    if (st.size > cap) {
+        warn(what + ' exceeds the ' + cap + '-byte scan ceiling; ignored');
         return undefined;
     }
     return st;

package/lib/types/routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAA;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAM9C,+CAA+C;AAC/C,eAAO,MAAM,cAAc,aAAa,CAAA;AAExC,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,SAAS,CAAA;AAMtC;;;;GAIG;AACH,eAAO,MAAM,cAAc;IACzB,yBAAyB;;IAEzB,iDAAiD;;IAEjD,8EAA8E;;CAEtE,CAAA;AAEV,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd;AAWD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUrF;AAsPD,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,QAA8B,CAAA;AAe7D,4EAA4E;AAC5E,eAAO,MAAM,eAAe,QAAmB,CAAA;AAE/C,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAwMD,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,YAAY,CAAA;CAAE,GAAG,eAAe,GAAG,QAAQ,EAAE,CAwDjI;AAGD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA"}
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAA;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAO9C,+CAA+C;AAC/C,eAAO,MAAM,cAAc,aAAa,CAAA;AAExC,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,SAAS,CAAA;AAMtC;;;;GAIG;AACH,eAAO,MAAM,cAAc;IACzB,yBAAyB;;IAEzB,iDAAiD;;IAEjD,8EAA8E;;CAEtE,CAAA;AAEV,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;CACd;AAWD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUrF;AAwND,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,QAA8B,CAAA;AAe7D,4EAA4E;AAC5E,eAAO,MAAM,eAAe,QAAmB,CAAA;AAE/C,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAwMD,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAAE,OAAO,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,YAAY,CAAA;CAAE,GAAG,eAAe,GAAG,QAAQ,EAAE,CAwDjI;AAGD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA"}

package/lib/types/routes.js

@@ -17,6 +17,7 @@ import { join, sep } from 'node:path';
 import { DECORATION_ASSET_PREFIX, petEntryView, petPackageRoot } from "./registry.js";
 import { isPetAllowed } from "./access.js";
 import { dshHome } from "./dsh-home.js";
+import { readJsonBody, writeJson } from "./http.js";
 /** Browser-facing base path of the pet API. */
 export const PET_API_PREFIX = '/api/pet';
 /** Browser-facing base path of the pet asset routes ('/pet/<id>/...'). */
@@ -76,52 +77,18 @@ function mimeFor(file) {
         return 'application/octet-stream';
     return MIME_BY_EXT[file.slice(dot).toLowerCase()] ?? 'application/octet-stream';
 }
-/** Write one JSON response. */
-function json(res, status, body) {
-    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
-    res.end(JSON.stringify(body));
-}
 /** Require the method or answer 405. */
 function requireMethod(req, res, method) {
     if (req.method === method)
         return true;
-    json(res, 405, { ok: false, error: 'method-not-allowed' });
+    writeJson(res, 405, { ok: false, error: 'method-not-allowed' });
     return false;
 }
-/** Read a JSON request body (bounded). */
-function readJsonBody(req) {
-    return new Promise((resolve, reject) => {
-        let size = 0;
-        const chunks = [];
-        req.on('data', (chunk) => {
-            size += chunk.length;
-            if (size > 64 * 1024) {
-                reject(new Error('body-too-large'));
-                queueMicrotask(() => req.destroy());
-                return;
-            }
-            chunks.push(chunk);
-        });
-        req.on('end', () => {
-            if (chunks.length === 0) {
-                resolve({});
-                return;
-            }
-            try {
-                resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')));
-            }
-            catch {
-                reject(new Error('invalid-json'));
-            }
-        });
-        req.on('error', reject);
-    });
-}
 /** Shared route fence: loopback always passes; a live paired-device cookie is an extra allow path. */
 function guard(ctx, req, res) {
     if (isPetAllowed(ctx, req))
         return true;
-    json(res, 403, { ok: false, error: 'forbidden: loopback-only' });
+    writeJson(res, 403, { ok: false, error: 'forbidden: loopback-only' });
     return false;
 }
 /** Wrap one async service call as a GET JSON route. */
@@ -134,8 +101,8 @@ function getRoute(ctx, path, run) {
                 return;
             if (!requireMethod(req, res, 'GET'))
                 return;
-            run().then((value) => json(res, 200, value), (error) => {
-                json(res, 500, { ok: false, error: error instanceof Error ? error.message : String(error) });
+            run().then((value) => writeJson(res, 200, value), (error) => {
+                writeJson(res, 500, { ok: false, error: error instanceof Error ? error.message : String(error) });
             });
         },
     };
@@ -150,13 +117,18 @@ function postRoute(ctx, path, run) {
                 return Promise.resolve();
             if (!requireMethod(req, res, 'POST'))
                 return Promise.resolve();
-            return readJsonBody(req).then((body) => {
-                const record = (typeof body === 'object' && body !== null) ? body : {};
-                return run(record).then((value) => json(res, 200, value), (error) => {
-                    json(res, 400, { ok: false, error: error instanceof Error ? error.message : String(error) });
+            // Shared lenient reader (64 KiB cap): an empty body yields null and is
+            // restored to {} at the call site (legacy empty-body semantics); invalid
+            // JSON and over-limit bodies also yield null, so the endpoint validators
+            // below keep answering 400 with the same { ok: false, error } envelope.
+            return readJsonBody(req, { maxBytes: 64 * 1024 }).then((parsed) => {
+                const payload = parsed ?? {};
+                const record = (typeof payload === 'object' && payload !== null) ? payload : {};
+                return run(record).then((value) => writeJson(res, 200, value), (error) => {
+                    writeJson(res, 400, { ok: false, error: error instanceof Error ? error.message : String(error) });
                 });
             }, (error) => {
-                json(res, 400, { ok: false, error: error instanceof Error ? error.message : String(error) });
+                writeJson(res, 400, { ok: false, error: error instanceof Error ? error.message : String(error) });
             });
         },
     };
@@ -369,7 +341,7 @@ function runtimeHandler(ctx, roots) {
         const base = spec.root === 'runtimeDir' ? roots.runtimeDir : roots.vendorDir;
         const file = join(base, name);
         if (!existsSync(file)) {
-            json(res, 404, { ok: false, error: 'runtime-file-missing', file: name });
+            writeJson(res, 404, { ok: false, error: 'runtime-file-missing', file: name });
             return;
         }
         const resolved = containedRealpath(base, file);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@linxin666/dsh-pet",
   "description": "Multi-pet companion plugin for the dsh web GUI: a registry-driven floating pet that reacts to model activity, with per-pet naming, petting/feeding interactions and an affinity score",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "type": "module",
   "engines": {
     "node": "^22.19.0 || >=24.0.0"

package/src/client/PetSettingsCard.tsx

@@ -103,6 +103,9 @@ export class PetSettingsCardController {
   private diagnostics: PetDiagnosticView[] = []
   private loaded = false
   private attempts = 0
+  private disposed = false
+  /** Pending deferred-load or retry timer; cancelled by dispose(). */
+  private pendingTimer: number | undefined
 
   /** @param scope - the bound settings scope for the 'pet' namespace. */
   constructor(scope: SettingsScope<PetSettings>) {
@@ -120,7 +123,9 @@ export class PetSettingsCardController {
     // the first registry request until that pass completes so transport
     // plugins (notably remote-web-ui on a paired non-loopback origin) can
     // install their fetch channel before /api/pet/pets is issued.
-    window.setTimeout(() => {
+    this.pendingTimer = window.setTimeout(() => {
+      this.pendingTimer = undefined
+      if (this.disposed) return
       void this.loadPets()
       void this.loadDiagnostics()
     }, 0)
@@ -130,6 +135,7 @@ export class PetSettingsCardController {
   private async loadDiagnostics(): Promise<void> {
     try {
       this.diagnostics = await fetchPetDiagnostics()
+      if (this.disposed) return
       this.store.set(this.projection())
     } catch {
       this.diagnostics = []
@@ -138,17 +144,23 @@ export class PetSettingsCardController {
 
   /** Resolve the registry choices once (retried a few times on failure). */
   private async loadPets(): Promise<void> {
-    if (this.loaded) return
+    if (this.loaded || this.disposed) return
     try {
       const list = await fetchPetChoices()
+      if (this.disposed) return
       this.petChoices.splice(0, this.petChoices.length, ...list.map(choice => choice.id))
       for (const choice of list) this.petLabels.set(choice.id, choice.displayName)
       this.loaded = true
       this.store.set(this.projection())
     } catch {
+      if (this.disposed) return
       this.attempts += 1
       if (this.attempts < 3) {
-        window.setTimeout(() => { void this.loadPets() }, 3000)
+        this.pendingTimer = window.setTimeout(() => {
+          this.pendingTimer = undefined
+          if (this.disposed) return
+          void this.loadPets()
+        }, 3000)
       }
     }
   }
@@ -177,10 +189,16 @@ export class PetSettingsCardController {
   }
 
   /**
-   * Release the card's scope subscription and bound stores; the slot
-   * disposer calls this on teardown.
+   * Release the card's scope subscription, bound stores and pending load
+   * timers; the slot disposer calls this on teardown.
    */
   dispose(): void {
+    if (this.disposed) return
+    this.disposed = true
+    if (this.pendingTimer !== undefined) {
+      window.clearTimeout(this.pendingTimer)
+      this.pendingTimer = undefined
+    }
     this.form.dispose()
   }
 }

package/src/client/PetSprite.test.tsx

@@ -159,6 +159,22 @@ describe('PetSprite custom visual (pet-center M3)', () => {
   })
 })
 
+describe('PetSprite always-visible close control', () => {
+  it('renders a corner close button and hides without petting', () => {
+    const onHide = vi.fn()
+    const onPet = vi.fn()
+    renderPet({ onHide, onPet })
+
+    const close = screen.getByTestId('pet-close')
+    expect(close.getAttribute('aria-label')).toBe('隐藏')
+    expect(close.getAttribute('title')).toBe('隐藏')
+    fireEvent.click(close)
+
+    expect(onHide).toHaveBeenCalledTimes(1)
+    expect(onPet).not.toHaveBeenCalled()
+  })
+})
+
 describe('PetSprite rename input', () => {
   it('submits the draft on Enter outside composition', () => {
     const { onRename } = renderPet()

package/src/client/PetSprite.tsx

@@ -466,34 +466,58 @@ export function PetSprite(props: PetSpriteProps): ReactPortal {
       }}
     >
       <div
-        ref={spriteRef}
-        className={styles.sprite}
-        style={{
-          width: spriteWidth,
-          height: spriteHeight,
-          ...(props.visual === undefined
-            ? {
-                backgroundImage: imageReady ? 'url(' + definition.atlasUrl + ')' : undefined,
-                backgroundSize: (cell.width * columns * spriteScale) + 'px ' + (cell.height * (definition.atlasRows ?? rows.length) * spriteScale) + 'px',
-                backgroundRepeat: 'no-repeat',
-                backgroundPosition: '0 0',
-              }
-            : {}),
-          cursor: dragRef.current === null ? 'grab' : 'grabbing',
-        }}
-        onPointerDown={onPointerDown}
-        onPointerMove={onPointerMove}
-        onPointerUp={onPointerUp}
-        onClick={() => {
-          // A pointer sequence that moved (dragged) still fires a trailing
-          // click; skip the pet when that happened.
-          if (draggedRef.current) return
-          props.onPet()
-        }}
-        role="button"
-        aria-label={definition.displayName}
+        className={styles.spriteWrap}
+        style={{ width: spriteWidth, height: spriteHeight }}
       >
-        {props.visual}
+        <div
+          ref={spriteRef}
+          className={styles.sprite}
+          style={{
+            width: spriteWidth,
+            height: spriteHeight,
+            ...(props.visual === undefined
+              ? {
+                  backgroundImage: imageReady ? 'url(' + definition.atlasUrl + ')' : undefined,
+                  backgroundSize: (cell.width * columns * spriteScale) + 'px ' + (cell.height * (definition.atlasRows ?? rows.length) * spriteScale) + 'px',
+                  backgroundRepeat: 'no-repeat',
+                  backgroundPosition: '0 0',
+                }
+              : {}),
+            cursor: dragRef.current === null ? 'grab' : 'grabbing',
+          }}
+          onPointerDown={onPointerDown}
+          onPointerMove={onPointerMove}
+          onPointerUp={onPointerUp}
+          onClick={() => {
+            // A pointer sequence that moved (dragged) still fires a trailing
+            // click; skip the pet when that happened.
+            if (draggedRef.current) return
+            props.onPet()
+          }}
+          role="button"
+          aria-label={definition.displayName}
+        >
+          {props.visual}
+        </div>
+        <button
+          type="button"
+          className={styles.closeButton}
+          aria-label={panelLabel('hide', props.t('pet.hide'))}
+          title={panelLabel('hide', props.t('pet.hide'))}
+          data-testid="pet-close"
+          onPointerDown={(e) => {
+            // Keep the close control from starting a drag on the sprite.
+            e.stopPropagation()
+          }}
+          onClick={(e) => {
+            // The close control sits beside the pet button; do not pet as a
+            // side effect of closing the overlay.
+            e.stopPropagation()
+            props.onHide()
+          }}
+        >
+          ×
+        </button>
       </div>
       {feedback !== null && (
         <div key={feedback.at} ref={bubbleRef} className={clsx(styles.bubble, feedback.kind === 'feed' ? styles.bubbleFeed : styles.bubblePet)}>

package/src/client/index.ts

@@ -121,8 +121,13 @@ export function apply(ctx: ClientContext): void {
 
   // First-level settings section: one staged form over the 'pet' settings
   // namespace, registered as a top-level settings page. The controller loads
-  // the petId choices from the registry endpoint itself.
+  // the petId choices from the registry endpoint itself — the registry lists
+  // the available pets (built-in assets plus user dirs), so the section only
+  // ever shows installed pets. Installing new pets happens in the Workshop
+  // store.
   const petSettings = new PetSettingsCardController(settingsScope)
+  // The section entry owns the controller: unregistering it (fiber disposal,
+  // hot reload) releases the scope subscription through petSettings.dispose.
   ctx.slots.inject('settings.section', () => {
     const unregister = ctx.slots.register({
       name: 'settings.section',
@@ -133,8 +138,8 @@ export function apply(ctx: ClientContext): void {
       inject: () => petSettings.inject(),
     }, PetSettingsSection)
     return () => {
-      petSettings.dispose()
       unregister()
+      petSettings.dispose()
     }
   })
 

package/src/client/pet.module.css

@@ -9,11 +9,42 @@
 }
 
 .sprite {
-  position: relative;
   image-rendering: auto;
   touch-action: none;
 }
 
+.spriteWrap {
+  position: relative;
+  flex: 0 0 auto;
+}
+
+.closeButton {
+  position: absolute;
+  top: 4px;
+  right: 4px;
+  z-index: 2;
+  width: 24px;
+  height: 24px;
+  padding: 0;
+  border: 1px solid rgba(226, 232, 255, 0.72);
+  border-radius: 999px;
+  color: #f8fafc;
+  background: rgba(7, 11, 26, 0.78);
+  font: 600 18px/20px sans-serif;
+  cursor: pointer;
+  touch-action: manipulation;
+  transition: background 120ms ease, box-shadow 120ms ease;
+}
+
+.closeButton:hover {
+  background: rgba(44, 62, 126, 0.95);
+}
+
+.closeButton:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px rgba(126, 152, 255, 0.95);
+}
+
 .bubble {
   position: absolute;
   bottom: 100%;
@@ -402,7 +433,8 @@
 
   .action,
   .summon,
-  .bubbleMore {
+  .bubbleMore,
+  .closeButton {
     transition: none;
   }
 }

package/src/client/settings-section.module.css

@@ -11,18 +11,18 @@
   border: 1px dashed var(--dsw-alias-border-l2);
   border-radius: 8px;
   font-size: 12px;
-  color: var(--dsw-alias-label-dimmed);
+  color: var(--dsw-alias-label-tertiary);
 }
 .diagnosticsTitle {
   display: block;
   font-weight: 600;
   margin-bottom: 4px;
-  color: var(--dsw-alias-label);
+  color: var(--dsw-alias-label-primary);
 }
 .diagnostics ul {
   margin: 0;
   padding-left: 16px;
 }
 .diagnostics li[data-level="error"] {
-  color: var(--dsw-alias-error, #c04848);
+  color: var(--dsw-alias-label-error, #c04848);
 }

package/src/http.ts

@@ -0,0 +1,105 @@
+// Generated by scripts/sync-shared.mjs from shared/host/http.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Shared JSON body/response helpers for the host route families: one strict
+ * bounded body reader, one lenient bounded body reader, one JSON object
+ * narrow, and one JSON writer. Previously these were copy-pasted across the
+ * package route files (routes.ts, update-routes.ts, mobile-api.ts, and each
+ * family's route module) with drifting contracts: body caps ranging 4 KiB to
+ * 1 MiB and four distinct overflow behaviors (reject, undefined, null, throw).
+ *
+ * Packages receive this file as a generated copy via scripts/sync-shared.mjs;
+ * edit this shared source and re-run the sync instead of editing a copy.
+ * Consumer code is migrated onto it in follow-up waves; no call site changes
+ * belong in the same change as its introduction.
+ * @module dsh-web-ui-shared/host/http
+ */
+
+import type { IncomingMessage, OutgoingHttpHeaders, ServerResponse } from 'node:http'
+
+/** Default body cap for readJsonBody: 64 KiB. */
+const DEFAULT_JSON_BODY_MAX_BYTES = 64 * 1024
+
+/** Family-default JSON response headers; callers may append or override. */
+const JSON_HEADERS = {
+  'content-type': 'application/json; charset=utf-8',
+  'referrer-policy': 'no-referrer',
+} satisfies OutgoingHttpHeaders
+
+/**
+ * Strict bounded body reader: parse a request body of at most maxBytes as
+ * JSON.
+ * @throws 'body too large' past the cap, or the JSON.parse error for an
+ *   invalid or empty payload.
+ */
+export async function readBoundedJson(req: IncomingMessage, maxBytes: number): Promise<unknown> {
+  const chunks: Buffer[] = []
+  let size = 0
+  for await (const chunk of req) {
+    const buffer = chunk as Buffer
+    size += buffer.length
+    if (size > maxBytes) throw new Error('body too large')
+    chunks.push(buffer)
+  }
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'))
+}
+
+/**
+ * Lenient bounded body reader: parse a request body as JSON, or null on an
+ * empty body, invalid JSON, or a body past maxBytes (default 64 KiB).
+ * Overflow destroys the request instead of draining the remainder (no drain
+ * call, matching the current repo-wide behavior); callers must not keep
+ * reading the request afterwards. With objectOnly, non-JSON-object payloads
+ * also yield null.
+ */
+export async function readJsonBody(
+  req: IncomingMessage,
+  opts: { maxBytes?: number; objectOnly?: boolean } = {},
+): Promise<unknown | null> {
+  const maxBytes = opts.maxBytes ?? DEFAULT_JSON_BODY_MAX_BYTES
+  const chunks: Buffer[] = []
+  let size = 0
+  for await (const chunk of req) {
+    const buffer = chunk as Buffer
+    size += buffer.length
+    if (size > maxBytes) {
+      req.destroy()
+      return null
+    }
+    chunks.push(buffer)
+  }
+  const text = Buffer.concat(chunks).toString('utf8')
+  if (text === '') return null
+  try {
+    const parsed: unknown = JSON.parse(text)
+    if (opts.objectOnly && !isJsonObject(parsed)) return null
+    return parsed
+  } catch {
+    return null
+  }
+}
+
+/** Whether a value is a JSON object: typeof object, not null, not an array. */
+function isJsonObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** Narrow a value to a JSON object, or undefined when it is not one. */
+export function asJsonObject(value: unknown): Record<string, unknown> | undefined {
+  return isJsonObject(value) ? value : undefined
+}
+
+/**
+ * Write one JSON response. Default headers are the family defaults
+ * (content-type and referrer-policy); caller headers are appended or
+ * override them.
+ */
+export function writeJson(
+  res: ServerResponse,
+  status: number,
+  body: unknown,
+  headers: OutgoingHttpHeaders = {},
+): void {
+  const payload = JSON.stringify(body)
+  res.writeHead(status, { ...JSON_HEADERS, ...headers })
+  res.end(payload)
+}