@daydreamui/has-lab 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,48 @@
-# Temporary Holding Version
+# :has lab
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Needs plugin API 3.0.
+
+A Daydream plugin for exploring real CSS relationships on the canvas. It uses the existing plugin API; no new kernel API, state simulation, or network services.
+
+## Try it
+
+1. Open **:has lab** and select an element in a page, or choose **Add playground page** in either mode.
+2. Under **Explore rules**, choose a rule. The panel separates the element carrying `:has()`, the condition it checks, and the element the rule targets. Only the selected relationship is drawn on the canvas.
+3. Move the pointer over the page, hold Option, and interact with the actual controls. The panel follows their state. Release Option to see the canvas labels again.
+4. Try the playground's ticket checkboxes, next-sibling hover, and email validation. For validation, enter an invalid email, then correct it. No form is submitted.
+5. Use **Select styled element** to select the recipient for further editing. **Declarations** shows the rule's source and declarations.
+
+The match count describes the `:has()` condition on its candidate elements. It does not claim that declarations win the cascade or that enclosing stylesheet media conditions are active.
+
+## Create a rule
+
+The secondary **Create a rule** tab retains the selection-driven recipe builder. Choose a condition, edit declarations, and use **Try on canvas**. This writes the real stylesheet immediately. **Revert trial** restores it; **Keep rule** commits one undoable edit. Other edits may interrupt and commit a trial; Daydream Undo remains available.
+
+Minimizing the panel reverts a live trial and stops the lens. Playground creation and trials cannot run together.
+
+The panel names the unconditional writable sheet being edited and warns when other pages link it. Page rewrites can reset browser input state, so interact again after starting a trial.
+
+## Supported relationships
+
+- The explainer supports one `:has()` on a simple tag/class/id selector, a simple descendant/child/following-sibling condition, and an optional descendant/child recipient. It recognizes checked, hover, focus, validity, placeholder, and integer child-count conditions.
+- Complex selectors and rules inside nesting or conditional groups remain visible with an explicit explanation of the limitation. This is a bounded explainer, not a general CSS parser.
+- Both modes outline one carrier, up to three condition elements, and four recipients. At most 200 carriers are checked and offered in the picker; larger sets show a sampling notice and counts for that sample. Narrow the rule to inspect other elements.
+- Daydream hides plugin overlays while browsing. Hover/focus may end on returning to the panel; the plugin does not pin them.
+- Viewports without rendered node access show a limitation instead of an empty analysis.
+- Carrier picks are stored as source selectors and expire on markup edits, so an old list position cannot silently select another element.
+- Independent variant pages use the same controls as other pages. The creator adds rules rather than editing or deduplicating existing rules.
+
+## Build and install
+
+From the repository root, with Node 24:
+
+```sh
+pnpm install
+pnpm typecheck
+pnpm test:kernel /path/to/daydream plugins/daydream.has-lab
+pnpm ship plugins/daydream.has-lab --enable
+```
+
+Rebuild and reinstall after changes so Daydream trusts the new bundle. Permissions remain canvas reading and project-page editing.
+
+Node unit tests cover the bounded selector grammar, candidate derivation, source preservation and rule collection. Browser tests mount the real Daydream shell and cover selector shapes, native control state, sibling hover, disclosure changes, form reset, selection and remounts, project changes, stylesheet conditions, and trial cancellation/commit/undo. The plugin uses API 3.0 and the same browser implementation on desktop and in the browser app. No native bridge or additional kernel API is required.