@ashraf_mizo/htmlcanvas 1.0.0

package/editor/cssVars.js

@@ -0,0 +1,134 @@
+/**
+ * cssVars.js — CSS variable safety layer
+ *
+ * A pure utility module with zero dependencies. Provides functions to safely
+ * detect and preserve CSS custom property (var()) references in raw style
+ * strings, without going through the CSSOM (which would resolve them away).
+ *
+ * Rule: no phase beyond Phase 1 may write a CSS value without calling
+ * hasVarReference first.
+ */
+
+/**
+ * Returns true if the given string contains any var() reference.
+ *
+ * Uses a permissive pattern — if a value looks like it might contain var(),
+ * it is treated as protected. This correctly handles:
+ *   - Simple: var(--accent)
+ *   - With fallback: var(--pad, 16px)
+ *   - Nested: var(--a, var(--b))
+ *   - Colon in fallback: var(--a, rgb(0,0,0))
+ *   - URL fallback: var(--a, url('http://example.com'))
+ *
+ * @param {*} value - The value to test. Non-strings and empty strings return false.
+ * @returns {boolean}
+ *
+ * @example
+ * hasVarReference('var(--accent)')        // true
+ * hasVarReference('var(--a, rgb(0,0,0))') // true
+ * hasVarReference('#E87420')              // false
+ * hasVarReference(null)                   // false
+ */
+export function hasVarReference(value) {
+  if (typeof value !== 'string' || value === '') return false;
+  return /var\s*\(/.test(value);
+}
+
+/**
+ * Parses a raw inline style attribute string into a plain object.
+ *
+ * Splits on `;` to get declarations, then splits each declaration on the
+ * FIRST `:` only — everything after the first colon is treated as the value.
+ * This correctly preserves colon-containing values such as:
+ *   - var(--a, rgb(0,0,0))
+ *   - var(--a, url('http://example.com'))
+ *   - calc(100% - var(--pad))
+ *
+ * Trims both property and value. Skips declarations with no property name.
+ *
+ * @param {string|null|undefined} styleAttr - Raw value of a style="" attribute.
+ * @returns {Object.<string, string>} Plain object mapping property names to raw values.
+ *
+ * @example
+ * parseInlineStyle('color: var(--accent); margin: 0')
+ * // => { color: 'var(--accent)', margin: '0' }
+ *
+ * parseInlineStyle('background-color: var(--a, rgb(0,0,0))')
+ * // => { 'background-color': 'var(--a, rgb(0,0,0))' }
+ */
+export function parseInlineStyle(styleAttr) {
+  if (!styleAttr) return {};
+
+  const result = {};
+  const declarations = styleAttr.split(';');
+
+  for (const declaration of declarations) {
+    const colonIndex = declaration.indexOf(':');
+    if (colonIndex === -1) continue;
+
+    const prop = declaration.slice(0, colonIndex).trim();
+    const value = declaration.slice(colonIndex + 1).trim();
+
+    if (prop === '') continue;
+
+    result[prop] = value;
+  }
+
+  return result;
+}
+
+/**
+ * Collects all CSS custom properties (--name) declared in a document's
+ * stylesheets, along with their resolved computed values.
+ *
+ * NOTE: This function must be called from within an iframe context in phases 2+
+ * where the target document is available. In Phase 1, it is exported but not
+ * called against live documents.
+ *
+ * Cross-origin stylesheets are silently skipped (they throw SecurityError on
+ * .cssRules access).
+ *
+ * @param {Document} doc - The document to inspect (e.g., iframe.contentDocument).
+ * @returns {Object.<string, {declared: string, resolved: string}>}
+ *   Object keyed by --variable-name, each value has:
+ *   - declared: the raw value from the stylesheet rule
+ *   - resolved: the computed value from getComputedStyle on :root
+ *
+ * @example
+ * // In an iframe context:
+ * const vars = collectCSSVariables(iframe.contentDocument);
+ * // => { '--accent': { declared: '#E87420', resolved: '#E87420' }, ... }
+ */
+export function collectCSSVariables(doc) {
+  const vars = {};
+
+  for (const sheet of doc.styleSheets) {
+    try {
+      const rules = sheet.cssRules;
+      for (const rule of rules) {
+        if (!rule.style) continue;
+        for (let i = 0; i < rule.style.length; i++) {
+          const prop = rule.style[i];
+          if (prop.startsWith('--')) {
+            vars[prop] = {
+              declared: rule.style.getPropertyValue(prop).trim(),
+              resolved: '',
+            };
+          }
+        }
+      }
+    } catch {
+      // Cross-origin sheet — skip silently
+    }
+  }
+
+  // Resolve current computed values via :root
+  if (Object.keys(vars).length > 0) {
+    const computed = getComputedStyle(doc.documentElement);
+    for (const prop of Object.keys(vars)) {
+      vars[prop].resolved = computed.getPropertyValue(prop).trim();
+    }
+  }
+
+  return vars;
+}

package/editor/domModel.js

@@ -0,0 +1,161 @@
+// editor/domModel.js — DOM model with stable data-hc-id attributes
+//
+// Parses raw HTML and injects data-hc-id="hc-N" on every element tag using
+// regex-based tag walking. Does NOT use DOMParser (which normalises HTML).
+// Exclusion zones (script content, style content, comments, doctypes) are
+// skipped so IDs are never injected into non-element contexts.
+
+// ── Module-level state ──────────────────────────────────────────────────────
+let _currentElementMap = null;
+let _currentRawHTML = null;
+
+/**
+ * Returns the current DOM model state set by the last injectIds call.
+ * @returns {{ elementMap: Map<string, ElementRecord> | null, rawHTML: string | null }}
+ */
+export function getModel() {
+  return { elementMap: _currentElementMap, rawHTML: _currentRawHTML };
+}
+
+// ── Exclusion zones ─────────────────────────────────────────────────────────
+
+/**
+ * Finds ranges in the HTML string where tags should NOT be annotated:
+ * - <!-- comments -->
+ * - <script>...</script> content (between the tags, not the tags themselves)
+ * - <style>...</style> content (between the tags, not the tags themselves)
+ * - <!DOCTYPE ...>
+ *
+ * @param {string} html
+ * @returns {Array<[number, number]>} Array of [startIndex, endIndex) pairs
+ */
+function findExclusionZones(html) {
+  const zones = [];
+  let m;
+
+  // DOCTYPE declarations
+  const doctypeRegex = /<!DOCTYPE[^>]*>/gi;
+  while ((m = doctypeRegex.exec(html)) !== null) {
+    zones.push([m.index, m.index + m[0].length]);
+  }
+
+  // HTML comments (<!-- ... -->)
+  const commentRegex = /<!--[\s\S]*?-->/g;
+  while ((m = commentRegex.exec(html)) !== null) {
+    zones.push([m.index, m.index + m[0].length]);
+  }
+
+  // Script content (between <script...> and </script>)
+  const scriptRegex = /<script([^>]*)>([\s\S]*?)<\/script>/gi;
+  while ((m = scriptRegex.exec(html)) !== null) {
+    // Exclude only the content between the opening and closing tags
+    const openTagEnd = m.index + m[0].indexOf('>') + 1;
+    const closeTagStart = m.index + m[0].lastIndexOf('</');
+    if (openTagEnd < closeTagStart) {
+      zones.push([openTagEnd, closeTagStart]);
+    }
+  }
+
+  // Style content (between <style...> and </style>)
+  const styleRegex = /<style([^>]*)>([\s\S]*?)<\/style>/gi;
+  while ((m = styleRegex.exec(html)) !== null) {
+    const openTagEnd = m.index + m[0].indexOf('>') + 1;
+    const closeTagStart = m.index + m[0].lastIndexOf('</');
+    if (openTagEnd < closeTagStart) {
+      zones.push([openTagEnd, closeTagStart]);
+    }
+  }
+
+  return zones;
+}
+
+/**
+ * Checks whether a given index falls inside any exclusion zone.
+ * @param {number} index
+ * @param {Array<[number, number]>} zones
+ * @returns {boolean}
+ */
+function isInExclusionZone(index, zones) {
+  return zones.some(([start, end]) => index >= start && index < end);
+}
+
+// ── Main export ─────────────────────────────────────────────────────────────
+
+/**
+ * Parses an HTML string and injects data-hc-id attributes on every element.
+ * Uses regex-based tag walking on the raw HTML to preserve the original
+ * formatting exactly (no attribute reordering, no whitespace changes).
+ *
+ * ID format: "hc-{sequential-number}" starting from 0.
+ * IDs are assigned in document order.
+ *
+ * Exclusion zones: tags inside <script>, <style>, <!-- comments -->, and
+ * <!DOCTYPE> are skipped.
+ *
+ * @param {string} rawHTML - The original HTML file content as a string
+ * @returns {{ annotatedHTML: string, elementMap: Map<string, ElementRecord> }}
+ *   - annotatedHTML: HTML string with data-hc-id on every element tag
+ *   - elementMap: Map from hc-id string to ElementRecord
+ *
+ * ElementRecord shape:
+ *   {
+ *     id: string,          // e.g. "hc-42"
+ *     tagName: string,     // e.g. "div", "span", "img"
+ *     sourceIndex: number, // character index in rawHTML where the opening tag starts
+ *     sourceLength: number // length of the original opening tag in rawHTML
+ *   }
+ */
+export function injectIds(rawHTML) {
+  _currentRawHTML = rawHTML;
+
+  const elementMap = new Map();
+  const zones = findExclusionZones(rawHTML);
+  let counter = 0;
+  let annotatedHTML = '';
+  let lastIndex = 0;
+
+  // Match opening tags: <tagName ...attributes... /> or <tagName ...attributes...>
+  // Does NOT match closing tags (</...>), comments (<!--), or doctypes (<!)
+  const openingTagRegex = /<([a-zA-Z][a-zA-Z0-9]*)((?:\s+(?:[^>"'=]+=(?:"[^"]*"|'[^']*'|[^\s>]+)|[^>"'=\s]+))*\s*)(\/?)>/g;
+  let match;
+
+  while ((match = openingTagRegex.exec(rawHTML)) !== null) {
+    const fullMatch = match[0];
+    const tagName = match[1];
+    const attributes = match[2];
+    const selfClosing = match[3];
+    const sourceIndex = match.index;
+
+    // Skip tags inside exclusion zones
+    if (isInExclusionZone(sourceIndex, zones)) {
+      continue;
+    }
+
+    const id = `hc-${counter++}`;
+
+    // Copy everything from lastIndex up to this tag
+    annotatedHTML += rawHTML.slice(lastIndex, sourceIndex);
+
+    // Reconstruct the tag with data-hc-id injected before the closing >
+    if (selfClosing) {
+      annotatedHTML += `<${tagName}${attributes} data-hc-id="${id}" />`;
+    } else {
+      annotatedHTML += `<${tagName}${attributes} data-hc-id="${id}">`;
+    }
+
+    lastIndex = sourceIndex + fullMatch.length;
+
+    elementMap.set(id, {
+      id,
+      tagName: tagName.toLowerCase(),
+      sourceIndex,
+      sourceLength: fullMatch.length,
+    });
+  }
+
+  // Append any remaining content after the last tag
+  annotatedHTML += rawHTML.slice(lastIndex);
+
+  _currentElementMap = elementMap;
+  return { annotatedHTML, elementMap };
+}