arcy.js 0.0.2 → 0.1.0

package/dist/design-mode.d.ts

@@ -0,0 +1,197 @@
+/**
+ * The thin identity core: the fields an interaction event carries in
+ * `payload.fingerprint`, and the fields the backend hashes into
+ * `fingerprint_key` (sorted keys, canonical JSON, SHA-256; slice 19.0).
+ *
+ * This shape is a cross-repo contract, not a convenience type. The same
+ * object is captured in two places, by 7.3's collector on every interactive
+ * click and by the design-mode picker (15.4) when an operator selects an
+ * element, and the two must produce byte-identical JSON for the same element
+ * or match counts (15.9), the observed-element list (D180), and the
+ * fingerprint-confidence stats silently read zero. Three rules keep the hash
+ * stable, enforced by the golden-vector parity tests:
+ *
+ * 1. **Flat.** `computeFingerprintKey` sorts only top-level keys, so a nested
+ *    object would hash in whatever insertion order the client used. The
+ *    semantic ancestor is three flat fields for exactly this reason.
+ * 2. **Absent keys are omitted, never `null` or `undefined`.**
+ *    `JSON.stringify` drops `undefined` properties but keeps `null` ones, so
+ *    the two spellings of "no value" would hash differently. There is one
+ *    spelling: the key does not appear.
+ * 3. **No raw class string, anywhere.** G5 (PRODUCT_SCOPE §6.2.5.1.1): on a
+ *    Tailwind app a class string is a presentational sentence that changes
+ *    when a designer touches padding. Classes enter the system only through
+ *    the ranked selector generator (15.2), after utility suppression.
+ *
+ * Changing this field set orphans every stored `fingerprint_key`. It is a
+ * migration, not an edit (see ADR 0059).
+ */
+interface EventFingerprint {
+    /** Lowercase tag name. The one field that is always present. */
+    tag: string;
+    /** Subtree text, whitespace-collapsed, PII-masked, capped. Primary matcher. */
+    text?: string;
+    /** The icon-only control's signal; masked and capped like text. */
+    ariaLabel?: string;
+    /** Form controls have no textContent; their placeholder stands in. */
+    placeholder?: string;
+    /**
+     * The element's own id, only when it looks author-written. Generated ids
+     * (React useId's `:r3:`, Radix) change per render and would fragment the
+     * key, turning one button into a new "element" every session.
+     */
+    id?: string;
+    /** The explicit `role` attribute. No implicit-role table: not worth its bytes. */
+    role?: string;
+    /**
+     * The element's own `data-testid`, `data-test`, or `data-cy`, first one
+     * present (ADR 0134). The strongest evidence a page can offer that two
+     * elements are the same element: it is written by a developer to be stable
+     * and survives a redesign, a copy edit, and a locale switch at once.
+     *
+     * Read from the element itself, unlike `ancestorAttr`/`ancestorValue`,
+     * which report the same attributes found on an ancestor. Absent on most
+     * elements, and absence is spelled the way every optional field here is
+     * spelled: the key does not appear.
+     */
+    testId?: string;
+    /** 0-based index among same-tag element siblings. The structural tiebreak. */
+    siblingIndex: number;
+    /** Nearest ancestor carrying a semantic identifier, as three flat fields. */
+    ancestorTag?: string;
+    /** Which attribute won the ancestor walk (e.g. "data-testid", "id"). */
+    ancestorAttr?: string;
+    /** That attribute's value, masked and capped like text. */
+    ancestorValue?: string;
+}
+/**
+ * How strictly the runtime matcher (15.3) scores candidates. A discrete step,
+ * not a float: the mapping from step to score threshold lives in the matcher,
+ * so tuning the scoring function never migrates stored targets. 1 is loosest,
+ * 5 is strictest. The slider help text is the workflow: loosen when the
+ * element is not found, tighten when the wrong element is found.
+ */
+type Precision = 1 | 2 | 3 | 4 | 5;
+/**
+ * The full element target: the identity core plus the authoring layer an
+ * operator sets in the picker (15.4) and edits in manual adjustment (15.9).
+ * Stored on a flow step, so this object outlives any single arcy.js version.
+ */
+interface TargetFingerprint {
+    /**
+     * Schema version. Durable data stored in customers' flows needs a
+     * discriminant before a v2 exists, or the v2 migration has nothing to
+     * dispatch on. Bump only with a migration plan for stored targets.
+     */
+    v: 1;
+    /**
+     * The identity core, embedded as-is and never spread flat. Everything that
+     * hashes or matches reads `target.core`, structurally the same object shape
+     * an event carries, so a field can never be forgotten in translation.
+     */
+    core: EventFingerprint;
+    /**
+     * The active selector refinement. Default null (§6.2.5.1: the reference
+     * leads with text, not a selector, and that default is preserved). Never
+     * hand-authored; 15.2's generator is the only writer, and it writes only
+     * when the top-ranked candidate is top-two-tier and matches exactly one
+     * element at pick time (D318).
+     */
+    selector: string | null;
+    /**
+     * Ranked stable-selector candidates captured at pick time by 15.2, shown
+     * read-only in manual adjustment as a diagnostic. Capped so a pathological
+     * page cannot bloat a stored target.
+     */
+    selectorCandidates: string[];
+    /**
+     * 1-based position among document-ordered candidates that survive the
+     * precision threshold: "if multiple matches, select 1st element". Always
+     * present. This is the G5 policy reversal (D013): a human pointed at the
+     * element and set this, so ties take the ordinal, never refuse-to-guess.
+     */
+    ordinal: number;
+    precision: Precision;
+    /**
+     * Marks text as changing at runtime ("3 items in cart"), so the matcher
+     * down-weights text rather than treating its mismatch as disqualifying.
+     */
+    dynamicText: boolean;
+}
+
+/** The one masking token. Exported because the matcher (15.3) must treat it
+ * as an absent signal rather than a value: every masked email collapses to
+ * this same string, so scoring it as text would make any PII match any
+ * other PII exactly. */
+declare const MASK = "[masked]";
+
+/**
+ * Bumped whenever a message shape changes incompatibly. A receiver that reads
+ * a number it does not speak refuses and says so, rather than guessing at a
+ * payload it half understands (the same posture ADR 0069 took for loading).
+ */
+declare const DESIGN_MODE_PROTOCOL = 2;
+/** Posted once, when the overlay has mounted and the operator can click. */
+declare const DESIGN_MODE_READY = "arcy:design-mode:ready";
+/** Posted for every pick. The last one wins; there is no confirm (D502). */
+declare const DESIGN_MODE_PICK = "arcy:design-mode:pick";
+/** Posted when the operator leaves design mode. */
+declare const DESIGN_MODE_EXIT = "arcy:design-mode:exit";
+/**
+ * Posted once per pick, asynchronously, after rasterization finishes
+ * (15.7). Never gates `DESIGN_MODE_PICK`'s own delivery (D502): a receiver
+ * that has not built `DESIGN_MODE_SCREENSHOT` into its `switch` simply drops
+ * it via the same unknown-`type` path every other unrecognized message takes,
+ * so this needed no `DESIGN_MODE_PROTOCOL` bump to add.
+ */
+declare const DESIGN_MODE_SCREENSHOT = "arcy:design-mode:screenshot";
+interface DesignModeReady {
+    type: typeof DESIGN_MODE_READY;
+    protocol: number;
+}
+interface DesignModePick {
+    type: typeof DESIGN_MODE_PICK;
+    protocol: number;
+    target: TargetFingerprint;
+    /**
+     * The path the element was picked on, read at pick time (D504). A target
+     * and the page it lives on are stored as two separate fields on a step, and
+     * browse mode means the operator can be somewhere else by the time they
+     * pick. Without this the step would keep whichever page was chosen in the
+     * dropdown, and a target filed under the wrong page reports zero forever.
+     */
+    route: string;
+    /**
+     * How many elements on this page matched the target at the moment it was
+     * picked (ADR 0132). Scored here, where the live document and the matcher
+     * both already are, rather than asked for afterwards over a channel to a tab
+     * the pick is about to close.
+     *
+     * Information for the operator, never a gate: zero and forty are both real
+     * answers worth showing, and neither is a reason to refuse a save.
+     */
+    matchCount: number;
+}
+interface DesignModeExit {
+    type: typeof DESIGN_MODE_EXIT;
+    protocol: number;
+}
+interface DesignModeScreenshot {
+    type: typeof DESIGN_MODE_SCREENSHOT;
+    protocol: number;
+    /** A `data:image/png;base64,...` artifact of the most recently picked
+     * element. Last one wins, same as the pick it decorates: a receiver simply
+     * overwrites whatever it is holding. */
+    screenshot: string;
+}
+type DesignModeMessage = DesignModeReady | DesignModePick | DesignModeExit | DesignModeScreenshot;
+/**
+ * The receiver's only entry point: turns `event.data` into a message it can
+ * act on, or null. Says nothing about *who* sent it. The other two checks
+ * D501 requires, the source window and the origin, belong to the receiver,
+ * because only it knows which window it opened and which environment it is
+ * authoring in.
+ */
+declare function readDesignModeMessage(data: unknown): DesignModeMessage | null;
+
+export { DESIGN_MODE_EXIT, DESIGN_MODE_PICK, DESIGN_MODE_PROTOCOL, DESIGN_MODE_READY, DESIGN_MODE_SCREENSHOT, type DesignModeExit, type DesignModeMessage, type DesignModePick, type DesignModeReady, type DesignModeScreenshot, MASK, readDesignModeMessage };

package/dist/design-mode.js

@@ -0,0 +1,127 @@
+/* arcy.js — https://arcyai.com */
+
+// src/fingerprint/model.ts
+var FINGERPRINT_TEXT_MAX = 80;
+var SELECTOR_CANDIDATES_MAX = 5;
+
+// src/fingerprint/capture.ts
+var MASK = "[masked]";
+
+// src/picker/message.ts
+var DESIGN_MODE_PROTOCOL = 2;
+var DESIGN_MODE_READY = "arcy:design-mode:ready";
+var DESIGN_MODE_PICK = "arcy:design-mode:pick";
+var DESIGN_MODE_EXIT = "arcy:design-mode:exit";
+var DESIGN_MODE_SCREENSHOT = "arcy:design-mode:screenshot";
+var TAG_MAX = 64;
+var ROUTE_MAX = 2048;
+var SELECTOR_MAX = 512;
+var ORDINAL_MAX = 1e4;
+var SIBLING_INDEX_MAX = 1e5;
+var SCREENSHOT_DATA_URL_MAX = 4e6;
+var SCREENSHOT_PREFIX = "data:image/png;base64,";
+var MATCH_COUNT_MAX = 1e6;
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isBoundedString(value, max) {
+  return typeof value === "string" && value.length > 0 && value.length <= max;
+}
+function isOptionalBoundedString(value, max) {
+  return value === void 0 || isBoundedString(value, max);
+}
+function isBoundedInteger(value, min, max) {
+  return typeof value === "number" && Number.isInteger(value) && value >= min && value <= max;
+}
+function readCore(value) {
+  if (!isRecord(value)) return null;
+  if (!isBoundedString(value.tag, TAG_MAX)) return null;
+  if (!isBoundedInteger(value.siblingIndex, 0, SIBLING_INDEX_MAX)) return null;
+  const optional = [
+    "text",
+    "ariaLabel",
+    "placeholder",
+    "id",
+    "role",
+    "testId",
+    "ancestorTag",
+    "ancestorAttr",
+    "ancestorValue"
+  ];
+  for (const key of optional) {
+    if (!isOptionalBoundedString(value[key], FINGERPRINT_TEXT_MAX)) return null;
+  }
+  const core = {
+    tag: value.tag,
+    siblingIndex: value.siblingIndex
+  };
+  for (const key of optional) {
+    const field = value[key];
+    if (typeof field === "string") core[key] = field;
+  }
+  return core;
+}
+function readTarget(value) {
+  if (!isRecord(value)) return null;
+  if (value.v !== 1) return null;
+  const core = readCore(value.core);
+  if (!core) return null;
+  const { selector, selectorCandidates, ordinal, precision, dynamicText } = value;
+  if (selector !== null && !isBoundedString(selector, SELECTOR_MAX)) return null;
+  if (!Array.isArray(selectorCandidates)) return null;
+  if (selectorCandidates.length > SELECTOR_CANDIDATES_MAX) return null;
+  if (!selectorCandidates.every((c) => isBoundedString(c, SELECTOR_MAX)))
+    return null;
+  if (!isBoundedInteger(ordinal, 1, ORDINAL_MAX)) return null;
+  if (!isBoundedInteger(precision, 1, 5)) return null;
+  if (typeof dynamicText !== "boolean") return null;
+  return {
+    v: 1,
+    core,
+    selector,
+    selectorCandidates,
+    ordinal,
+    precision,
+    dynamicText
+  };
+}
+function readDesignModeMessage(data) {
+  if (!isRecord(data)) return null;
+  if (data.protocol !== DESIGN_MODE_PROTOCOL) return null;
+  switch (data.type) {
+    case DESIGN_MODE_READY:
+      return { type: DESIGN_MODE_READY, protocol: DESIGN_MODE_PROTOCOL };
+    case DESIGN_MODE_EXIT:
+      return { type: DESIGN_MODE_EXIT, protocol: DESIGN_MODE_PROTOCOL };
+    case DESIGN_MODE_PICK: {
+      const target = readTarget(data.target);
+      if (!target) return null;
+      const { route, matchCount } = data;
+      if (!isBoundedString(route, ROUTE_MAX)) return null;
+      if (!route.startsWith("/")) return null;
+      if (route.startsWith("//")) return null;
+      if (!isBoundedInteger(matchCount, 0, MATCH_COUNT_MAX)) return null;
+      return {
+        type: DESIGN_MODE_PICK,
+        protocol: DESIGN_MODE_PROTOCOL,
+        target,
+        route,
+        matchCount
+      };
+    }
+    case DESIGN_MODE_SCREENSHOT: {
+      const { screenshot } = data;
+      if (!isBoundedString(screenshot, SCREENSHOT_DATA_URL_MAX)) return null;
+      if (!screenshot.startsWith(SCREENSHOT_PREFIX)) return null;
+      return {
+        type: DESIGN_MODE_SCREENSHOT,
+        protocol: DESIGN_MODE_PROTOCOL,
+        screenshot
+      };
+    }
+    default:
+      return null;
+  }
+}
+
+export { DESIGN_MODE_EXIT, DESIGN_MODE_PICK, DESIGN_MODE_PROTOCOL, DESIGN_MODE_READY, DESIGN_MODE_SCREENSHOT, MASK, readDesignModeMessage };