@hyperframes/inspector 0.8.155 → 0.8.157

package/README.md

@@ -2,7 +2,7 @@
 
 Recover original HTML/CSS/GSAP context for **known elements before an edit**. This is not a video check, screenshot, diff, or affected-component verifier. It combines the I002 runtime/compiler provenance approach with the I003 HF-owned service boundary. The agent adapter holds no DOM or animation state.
 
-This source-only experimental package is private. It does not modify the shared installation or register itself in a harness. Base: HF 0.8.127, commit `b3d2b82fe`.
+Published as `@hyperframes/inspector`. It does not modify the shared installation or register itself in a harness.
 
 ## Start
 
@@ -17,13 +17,9 @@ export HF_INSPECT_CHROME=/absolute/path/to/chrome
 bun packages/inspector/src/server.ts /absolute/video/project
 ```
 
-The service prints its loopback URL. Starting it does **not** start a browser. First inspection loads the project once. Configure the harness's MCP server to execute:
+The service prints its loopback URL. Starting it does **not** start a browser. First inspection loads the project once.
 
-```sh
-HF_INSPECT_URL=http://127.0.0.1:PRINTED_PORT bun packages/inspector/src/mcp.ts
-```
-
-Tool: `inspect_components`. Direct HTTP equivalent: `POST /inspect` with the same JSON. The service is bound to one project at startup, so no per-call project path is needed. `GET /info` returns project identity and startup/query counters. Stop with SIGINT/SIGTERM; the service disposes its own pages/browser.
+The package ships the capability, not agent tools: a harness defines its own tool names, descriptions and schemas, and calls `POST /inspect` with the JSON below. The service is bound to one project at startup, so no per-call project path is needed. `GET /info` returns project identity and startup/query counters. Stop with SIGINT/SIGTERM; the service disposes its own pages/browser.
 
 ## Input
 
@@ -83,7 +79,25 @@ Code blocks are atomic. `omitted`, `omittedCount`, and `nextOffset` describe mis
 
 `maxBytes` can be raised explicitly (2,048–256,000). A block larger than the budget is not cut in half: request that ID with a larger budget or read its file/range. Pagination can therefore remain at the same offset until the budget increases. Old-generation continuations are rejected.
 
-Full runtime evidence is only available by an explicit HTTP request with `debug: true`; it is deliberately not part of the agent tool schema or its default output budget.
+Full runtime evidence is only available by an explicit HTTP request with `debug: true`; it is deliberately not part of the default request or its output budget.
+
+## Timeline
+
+`POST /timeline` answers which animations are scheduled when, from the same browser, page and generation as `/inspect`. It never seeks, renders or edits files.
+
+```json
+{ "component": { "selector": "#title" }, "boundary": 7.9 }
+```
+
+`component` is optional and resolves like an `/inspect` target; omit it for every registered HF timeline. Give at most one of `at`, `range: [start, end]` or `boundary`, in global seconds; omit all three for the schedule overview. Results are short text grouped by component, with event times, targets, properties and source locations; `generation` and `offset` page through them. Coverage is registered DOM-target GSAP animations and explicit HF items only; anything outside that, or past the expansion limits, is reported as incomplete coverage rather than guessed.
+
+## Element map
+
+`POST /element-map` returns the composition's element map from the same page. It reads no query fields. A project with no `index.html` answers `404` `{ "error": "no-composition", "code": "no-composition" }`.
+
+## Errors
+
+Every refusal is JSON `{ "error", "code" }`. `code` is the stable token (`no-composition`, `stale_generation`, `source_changed_during_query`, `request_too_large`); a sentence with no token is `invalid_request`. A missing browser is `503` `browser_unavailable`, and an unexpected failure is `500` `internal_error`. Importing the module does not listen; `createInspectorServer(project)` builds one. An unknown route is `404` `{ "error": "not_found", "code": "not_found" }`. `GET /info` adds `version`, this package's version. The process listens on `127.0.0.1` and refuses a `Host` that is not loopback, so a rebinding request cannot read the project path. Install the server with the package: `hyperframes-inspector <project> [port]`, or `node dist/server.js`.
 
 ## Lifecycle and overhead
 

package/dist/inspection.js

@@ -10,16 +10,32 @@
     }
     return unknown();
   }
-  function animationValues(vars, properties) {
-    const startAt = vars.startAt && typeof vars.startAt === "object" ? vars.startAt : {};
+  var record = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  function declaredEase(ease) {
+    return typeof ease === "function" ? { kind: "expression", value: "custom function" } : declared(ease);
+  }
+  function animationValues(vars, properties, keyframesEase) {
+    const startAt = record(vars.startAt);
+    const endpoints = (property, end, start) => ({
+      property,
+      from: declared(vars.runBackwards ? end : start),
+      to: vars.runBackwards ? unknown() : declared(end)
+    });
+    const segment = declaredEase(vars.ease);
+    const whole = keyframesEase === void 0 ? void 0 : declaredEase(keyframesEase);
     return {
       basis: "authored-tween",
-      properties: properties.map((property) => ({
-        property,
-        from: declared(vars.runBackwards ? vars[property] : startAt[property]),
-        to: vars.runBackwards ? unknown() : declared(vars[property])
-      })),
-      ease: declared(vars.ease)
+      properties: properties.flatMap((property) => {
+        const nested = record(vars[property]);
+        const keys = property === "attr" || property === "css" ? Object.keys(nested) : [];
+        if (!keys.length) return [endpoints(property, vars[property], startAt[property])];
+        const nestedStart = record(startAt[property]);
+        return keys.map((key) => endpoints(`${property}.${key}`, nested[key], nestedStart[key]));
+      }),
+      ease: whole ? {
+        kind: "expression",
+        value: `${whole.value ?? "?"} across keyframes, ${segment.value ?? "?"} per segment`
+      } : segment
     };
   }
 
@@ -1610,7 +1626,8 @@
     const seen = /* @__PURE__ */ new Set();
     const resolver = createRuntimeStartTimeResolver({
       timelineRegistry: registry,
-      documentRef: scope.ownerDocument
+      documentRef: scope.ownerDocument,
+      includeAuthoredTimingAttrs: true
     });
     const rootElement = findRootCompositionElement(scope.ownerDocument);
     const clocks = /* @__PURE__ */ new Map();
@@ -1665,7 +1682,11 @@
           const properties = Object.keys(piece.vars ?? {}).filter(
             (k) => !reserved2.has(k) && !k.startsWith("on")
           );
-          const values = animationValues(piece.vars ?? {}, properties);
+          const values = animationValues(
+            piece.vars ?? {},
+            properties,
+            internal && a.vars?.keyframes ? a.vars.ease : void 0
+          );
           const localIntervals = internal ? globalIntervals(
             a,
             clock,
@@ -1782,15 +1803,22 @@
       }
       return value2;
     };
+    const ancestorId = (el) => {
+      for (let parent = el.parentElement; parent; parent = parent.parentElement) {
+        if (parent.id) return parent.id;
+      }
+      return "";
+    };
     const describe = (el) => ({
       ref: ref(el),
       tag: el.tagName.toLowerCase(),
       id: el.id,
       hfId: el.getAttribute("data-hf-id"),
       classes: [...el.classList],
-      composition: el.closest("[data-composition-id]")?.getAttribute("data-composition-id") ?? null
+      composition: el.closest("[data-composition-id]")?.getAttribute("data-composition-id") ?? null,
+      withinId: ancestorId(el)
     });
-    function record(value2, stack) {
+    function record2(value2, stack) {
       if (animation(value2) && !records.has(value2) && count < limit) {
         records.set(value2, stack);
         count++;
@@ -1816,8 +1844,8 @@
           if (name === "add" && animation(args[0])) attachments.set(args[0], stack);
           else if (before) {
             for (const child of self?.getChildren?.(false, true, true) ?? [])
-              if (!before.has(child)) record(child, stack);
-          } else record(result, stack);
+              if (!before.has(child)) record2(child, stack);
+          } else record2(result, stack);
         }
         return result;
       };