dsh-better-display 0.3.8 → 0.3.10

package/docs/openapi.yaml

@@ -0,0 +1,147 @@
+openapi: 3.0.3
+info:
+  title: dsh-better-display
+  version: 0.3.9
+  description: >
+    Exact routes registered by apply() in src/dsh-better-display.ts.
+    POST /better-display/reveal is createRevealHandler in src/reveal.ts.
+    GET /better-display/skill-status returns toPublicSkillStatus.
+    The host webServer mounts these paths. The handlers do not read an
+    Authorization header or any other credential.
+servers:
+  - url: /
+    description: DeepSeek Harness host after this plugin has loaded.
+paths:
+  /better-display/reveal:
+    post:
+      operationId: revealInFileManager
+      summary: Reveal a workspace file in the OS file manager
+      description: >
+        Any method other than POST returns 405 with an empty body and no
+        Content-Type. The JSON body is read to completion, then parsed.
+        An absolute path is used as-is and does not call the workspace root
+        lookup. A relative path must resolve to exactly one existing file
+        under the session cwd or the matching workspace registry roots.
+        Drive-relative and root-relative Windows paths are rejected.
+        On success the host spawns open -R, explorer.exe /select, or xdg-open.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [path]
+              properties:
+                path:
+                  type: string
+                  description: Trimmed. Empty or whitespace-only is 400.
+                sessionId:
+                  type: string
+                  description: Optional. Used only when path is not absolute.
+            examples:
+              relative:
+                value:
+                  path: docs/report.md
+                  sessionId: target
+      responses:
+        '200':
+          description: The file manager was spawned. Body is JSON.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [ok]
+                additionalProperties: false
+                properties:
+                  ok:
+                    type: boolean
+                    enum: [true]
+        '400':
+          description: >
+            JSON.parse failed, path was empty, the path was not
+            workspace-relative, no root contained the file, or more than one
+            root contained it. error is String(err), so it includes the
+            Error prefix.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorBody'
+        '405':
+          description: req.method was not POST. Empty body. Content-Type is not set.
+  /better-display/skill-status:
+    get:
+      operationId: getGenerativeMcpappsSkillStatus
+      summary: Public generative-mcpapps install status
+      description: >
+        Any method other than GET returns 405 with an empty body and no
+        Content-Type. The optional cwd query selects which project roots are
+        scanned. The JSON body is toPublicSkillStatus, which always replaces
+        roots with the two conventional relative paths and drops packPath
+        and any host home absolute path.
+      parameters:
+        - in: query
+          name: cwd
+          required: false
+          schema:
+            type: string
+          description: Project directory passed to scanGenerativeMcpappsStatus. Omitted when the settings probe has no session cwd.
+      responses:
+        '200':
+          description: Public skill status. This body has no ok field.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PublicSkillStatus'
+        '405':
+          description: req.method was not GET. Empty body. Content-Type is not set.
+        '500':
+          description: scanGenerativeMcpappsStatus threw. error is String(err).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorBody'
+components:
+  schemas:
+    ErrorBody:
+      type: object
+      required: [ok, error]
+      additionalProperties: false
+      properties:
+        ok:
+          type: boolean
+          enum: [false]
+        error:
+          type: string
+    PublicSkillRoot:
+      type: object
+      required: [source, path]
+      additionalProperties: false
+      properties:
+        source:
+          type: string
+          enum: [conventional]
+        path:
+          type: string
+          enum: ['.dsh/skills', '.agents/skills']
+    PublicSkillStatus:
+      type: object
+      required: [name, installed, via, roots]
+      additionalProperties: false
+      properties:
+        name:
+          type: string
+          enum: [generative-mcpapps]
+        installed:
+          type: boolean
+        via:
+          type: string
+          nullable: true
+          enum: ['skills.list', 'skill-root', null]
+          description: skills.list when the host skills registry lists the skill, skill-root when a scanned root has it, otherwise null.
+        roots:
+          type: array
+          minItems: 2
+          maxItems: 2
+          items:
+            $ref: '#/components/schemas/PublicSkillRoot'
+          description: Always .dsh/skills then .agents/skills, source conventional. Not the scanned absolute roots.

package/docs/runbooks/blank-reader.md

@@ -0,0 +1,39 @@
+# Blank reader, missing stylesheet, stuck fold
+
+These three show up in CHANGELOG as real failures. There is no dashboard to open. Look at the host page and the versions below.
+
+## Blank reader
+
+0.3.8 (#60) re-injects the plugin stylesheet when a session switch clears it, because that clear left a blank page. `ensureStyles` in `src/client/styles.ts` remembers `style[data-plugin="dsh-better-display"][data-plugin-css]` and puts a missing tag back on `document.head`. The client entry calls it while the module loads (`src/client/index.tsx`), and `Reader` calls it again from `useInsertionEffect` before paint.
+
+A page that never becomes the reading view is a different failure. 0.3.1 threw while booting because `conversation.chat.turnTail` had become a list slot, and the host stayed on “Failed to load plugins”. 0.3.7 shipped a host entry that imported `./skill-roots.ts`; the host died with `ERR_MODULE_NOT_FOUND` while the market still showed the plugin installed. 0.3.8 stops externalising those relative host imports. Reinstalling the broken 0.3.7 build does not fix that.
+
+Check, in order:
+
+1. Reopen the Web Host and reload. The bundle is read at boot.
+2. If the host says “Failed to load plugins”, read that error. Do not toggle auto-fold. A slot mismatch or `ERR_MODULE_NOT_FOUND ./skill-roots.ts` means the installed build never reached `Reader`.
+3. In the document, look for `style[data-plugin="dsh-better-display"]`. If the reading column is mounted and those tags are missing, the stylesheet was cleared before `ensureStyles` had stored it. Reload so the client entry runs again.
+
+## Missing stylesheet
+
+The same 0.3.8 note (#60) is the stylesheet case: the session switch removes the plugin style tags, the reading column is still there, and it paints without the reader sheet. `ensureStyles` can only restore tags it has already seen. If `document.head` has no `data-plugin-css` node for this plugin and the in-memory map is empty, there is nothing to put back until the entry runs again.
+
+Confirm the host did not mount the plugin twice. A hand-written `cordis.patch.yml` insert plus `dsh plugin add` loads two copies. Reload after a single install. Do not add a second stylesheet link.
+
+## Stuck fold
+
+0.2.0: the fold choreography advanced only on animation promises and rendered frames. A cancelled animation rejects, and a hidden tab delivers no frames. The machine stayed in a non-idle phase, the frame source stayed on the shown snapshot, and the text reveal paused, so the turn looked stuck until the view remounted. Each phase now has a wall-clock deadline. In `src/client/fold-choreography.ts`, `watchdogSlack` is 240ms added to the phase duration (`collapse` 320, `count` 160, `settle` 80, `reveal` 180). `ChoreographedFlow` fires that deadline with `setTimeout` and moves the phase even when `onfinish` never runs.
+
+The same release gave disclosures a deadline. `fill: 'both'` pins the opening keyframe, so a Web Animation that never reaches `onfinish` left the row at zero height and zero opacity. A click looked like nothing happened. Later deadlines in `motion.tsx` and `ReasoningCard.tsx` use the same 240ms slack on top of the animation length.
+
+0.3.5: a finished expand animation has to release back to the row’s natural height. Content that changed after expanding left blank space or clipped steps until refresh. The collapse animation stays until React removes the content, so it does not flash for one frame.
+
+0.3.8 (#60) adds a timeout fallback for retiring content animations so they complete instead of holding the row.
+
+0.3.0: turning auto-fold off, opening process detail, then turning it on again used to leave the process expanded. Turning it on restores the auto-fold rules. Text selection protection and a later manual expand still win. The switch is on the reading toolbar and in Settings. The root store key is `dsh.reader.v1`; `foldIntensity` 0 is off, 1 is the default fold, 2 folds process runs into a digest and does not fold prose.
+
+Check, in order:
+
+1. Settings shows auto-fold on. Off means thinking and tools stay expanded. That is not a stuck animation.
+2. Wait out the phase plus 240ms. A row still at zero height after that should have been settled by the deadline. Reload the reading view once. The pre-0.2.0 recovery was a remount, and a deadline that did not run is the bug to report.
+3. Say whether the tab was in the background and whether `prefers-reduced-motion` is set. Do not restyle `Reader` to force the row open.