@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/streaming.js

@@ -0,0 +1,537 @@
+import path from "node:path";
+import { defaultConfig } from "./config.js";
+import { escapeHtml } from "./expressions.js";
+import { processDirectives } from "./process.js";
+import { createDetailedErrorMessage, extractVariables } from "./utils.js";
+const defaultStreamingConfig = {
+  enabled: !0,
+  bufferSize: 16384,
+  strategy: "auto",
+  timeout: 30000
+}, SECTION_PATTERN = /<!-- @section:([\w-]+) -->([\s\S]*?)<!-- @endsection:\1 -->/g, _DATA_SECTION_PATTERN = /<template\s+data-section="([\w-]+)">([\s\S]*?)<\/template>/g, SUSPENSE_PATTERN = /<!-- @suspense:([\w-]+) -->([\s\S]*?)<!-- @endsuspense:\1 -->/g;
+function parseStreamableChunks(content) {
+  const chunks = [];
+  let lastIndex = 0, match;
+  SUSPENSE_PATTERN.lastIndex = 0;
+  while ((match = SUSPENSE_PATTERN.exec(content)) !== null) {
+    if (match.index > lastIndex) {
+      const beforeContent = content.slice(lastIndex, match.index);
+      if (beforeContent.trim())
+        chunks.push({
+          type: chunks.length === 0 ? "shell" : "content",
+          content: beforeContent
+        });
+    }
+    const suspenseName = match[1], suspenseContent = match[2];
+    chunks.push({
+      type: "suspense",
+      name: suspenseName,
+      content: suspenseContent
+    });
+    lastIndex = match.index + match[0].length;
+  }
+  if (lastIndex < content.length) {
+    const remainingContent = content.slice(lastIndex);
+    if (remainingContent.trim())
+      chunks.push({
+        type: chunks.length === 0 ? "shell" : "content",
+        content: remainingContent
+      });
+  }
+  if (chunks.length === 0)
+    chunks.push({
+      type: "shell",
+      content
+    });
+  return chunks;
+}
+export async function streamTemplate(templatePath, data = {}, options = {}) {
+  const fullOptions = {
+    ...defaultConfig,
+    ...options,
+    streaming: {
+      ...defaultStreamingConfig,
+      ...options.streaming
+    }
+  }, bufferSize = fullOptions.streaming?.bufferSize || 16384;
+  return new ReadableStream({
+    async start(controller) {
+      try {
+        const content = await Bun.file(templatePath).text(), serverScriptMatch = content.match(/<script\b[^>]*\bserver\b[^>]*>([\s\S]*?)<\/script>/i), scriptContent = serverScriptMatch ? serverScriptMatch[1] : "", templateContent = content.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, ""), context = {
+          ...data,
+          __filename: templatePath,
+          __dirname: path.dirname(templatePath)
+        };
+        if (scriptContent.trim())
+          await extractVariables(scriptContent, context, templatePath);
+        const chunks = parseStreamableChunks(templateContent), dependencies = new Set;
+        if (!chunks.some((c) => c.type === "suspense")) {
+          const strategy = fullOptions.streaming?.strategy || "auto", sectionTestRegex = new RegExp(SECTION_PATTERN.source, "g");
+          if (!(strategy !== "manual" && sectionTestRegex.test(templateContent))) {
+            const output = await processDirectives(templateContent, context, templatePath, fullOptions, dependencies);
+            for (let i = 0;i < output.length; i += bufferSize) {
+              controller.enqueue(output.slice(i, i + bufferSize));
+              await new Promise((resolve) => setTimeout(resolve, 0));
+            }
+          } else {
+            const sections = [], sectionRegex = new RegExp(SECTION_PATTERN.source, "g");
+            let match;
+            while ((match = sectionRegex.exec(templateContent)) !== null)
+              sections.push({ name: match[1], content: match[2], start: match.index, end: match.index + match[0].length });
+            let lastEnd = 0;
+            for (const section of sections) {
+              if (section.start > lastEnd) {
+                const shellPart = templateContent.slice(lastEnd, section.start);
+                if (shellPart.trim()) {
+                  const processed = await processDirectives(shellPart, context, templatePath, fullOptions, dependencies);
+                  controller.enqueue(processed);
+                  await new Promise((resolve) => setTimeout(resolve, 0));
+                }
+              }
+              const processed = await processDirectives(section.content, context, templatePath, fullOptions, dependencies);
+              controller.enqueue(processed);
+              await new Promise((resolve) => setTimeout(resolve, 0));
+              lastEnd = section.end;
+            }
+            if (lastEnd < templateContent.length) {
+              const remaining = templateContent.slice(lastEnd);
+              if (remaining.trim()) {
+                const processed = await processDirectives(remaining, context, templatePath, fullOptions, dependencies);
+                controller.enqueue(processed);
+              }
+            }
+          }
+        } else {
+          const suspensePromises = new Map;
+          for (const chunk of chunks)
+            if (chunk.type === "shell" || chunk.type === "content") {
+              const processed = await processDirectives(chunk.content, context, templatePath, fullOptions, dependencies);
+              controller.enqueue(processed);
+            } else if (chunk.type === "suspense" && chunk.name) {
+              const placeholderId = `stx-suspense-${chunk.name}`;
+              controller.enqueue(`<div id="${placeholderId}" data-suspense="${chunk.name}" style="display:contents;">
+  <template data-suspense-fallback>Loading...</template>
+</div>`);
+              suspensePromises.set(chunk.name, processDirectives(chunk.content, context, templatePath, fullOptions, dependencies));
+            }
+          controller.enqueue(`
+<script>
+(function() {
+  window.__stxSuspense = window.__stxSuspense || {
+    resolve: function(name, content) {
+      var el = document.querySelector('[data-suspense="' + name + '"]');
+      if (el) {
+        // Create a template to parse the HTML
+        var template = document.createElement('template');
+        template.innerHTML = content;
+        // Replace placeholder with actual content
+        el.replaceWith(template.content);
+      }
+    }
+  };
+})();
+</script>`);
+          const resolvePromises = Array.from(suspensePromises.entries()).map(async ([name, promise]) => {
+            controller.enqueue(await buildSuspenseResolveScript(name, promise));
+          });
+          await Promise.all(resolvePromises);
+        }
+        controller.close();
+      } catch (error) {
+        controller.error(error);
+      }
+    }
+  });
+}
+export async function buildSuspenseResolveScript(name, promise) {
+  try {
+    const escapedContent = (await promise).replace(/`/g, "\\`").replace(/<\/script>/gi, "<\\/script>");
+    return `
+<script>
+window.__stxSuspense.resolve('${name}', \`${escapedContent}\`);
+</script>`;
+  } catch (error) {
+    const errorMsg = error instanceof Error ? error.message : String(error);
+    return `
+<script>
+window.__stxSuspense.resolve('${name}', '<div class="stx-error">Error loading content: ${escapeHtml(errorMsg)}</div>');
+</script>`;
+  }
+}
+export const SUSPENSE_RESOLVER_RUNTIME = `
+<script>
+(function(){
+  window.__stxSuspense = window.__stxSuspense || {
+    resolve: function(name, content){
+      var el = document.querySelector('[data-suspense="' + name + '"]');
+      if (!el) return;
+      var t = document.createElement('template');
+      t.innerHTML = content;
+      // Keep handles to the inserted nodes \u2014 the fragment is emptied on insert.
+      var nodes = Array.prototype.slice.call(t.content.childNodes);
+      el.replaceWith(t.content);
+      // Hydrate the streamed content so interactive islands/directives inside
+      // it come alive (no-op when the signals runtime isn't on the page).
+      if (window.stx && typeof window.stx.hydrate === 'function') {
+        nodes.forEach(function(n){ if (n.nodeType === 1) window.stx.hydrate(n); });
+      }
+    }
+  };
+})();
+</script>`;
+function withTimeout(promise, ms, id) {
+  if (!ms || ms <= 0)
+    return promise;
+  let timer;
+  const timeout = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => reject(Error(`streaming boundary "${id}" timed out after ${ms}ms`)), ms);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+export function renderStreamingPage(shellHtml, boundaries = [], options = {}) {
+  const timeoutMs = options.timeoutMs ?? 0;
+  return new ReadableStream({
+    async start(controller) {
+      try {
+        controller.enqueue(shellHtml);
+        if (boundaries.length > 0) {
+          controller.enqueue(SUSPENSE_RESOLVER_RUNTIME);
+          await Promise.all(boundaries.map(async (boundary) => {
+            const render = withTimeout(boundary.render(), timeoutMs, boundary.id);
+            controller.enqueue(await buildSuspenseResolveScript(boundary.id, render));
+          }));
+        }
+        controller.close();
+      } catch (error) {
+        controller.error(error);
+      }
+    }
+  });
+}
+const STREAM_DIRECTIVE_RE = /@stream\s*\(\s*['"]([^'"]+)['"]\s*\)([\s\S]*?)@endstream/gi;
+export function processStreamDirectives(template, context) {
+  return template.replace(STREAM_DIRECTIVE_RE, (_match, rawId, inner) => {
+    const id = rawId.trim(), parts = inner.split(/@fallback/i), content = parts[0].trim(), fallback = parts.length > 1 ? parts.slice(1).join("@fallback").trim() : "";
+    if (!context.__streamTemplates)
+      context.__streamTemplates = {};
+    context.__streamTemplates[id] = content;
+    return `<div data-suspense="${id}">${fallback}</div>`;
+  });
+}
+export function extractStreamBoundaries(context) {
+  const map = context?.streamBoundaries;
+  if (!map || typeof map !== "object")
+    return;
+  const entries = Object.entries(map).filter(([, fn]) => typeof fn === "function");
+  return entries.length > 0 ? entries.map(([id, render]) => ({ id, render })) : void 0;
+}
+export async function streamTemplateSimple(templatePath, data = {}, options = {}) {
+  const fullOptions = {
+    ...defaultConfig,
+    ...options,
+    streaming: {
+      ...defaultStreamingConfig,
+      ...options.streaming
+    }
+  }, bufferSize = fullOptions.streaming?.bufferSize || 16384;
+  return new ReadableStream({
+    async start(controller) {
+      try {
+        const content = await Bun.file(templatePath).text(), serverScriptMatch = content.match(/<script\b[^>]*\bserver\b[^>]*>([\s\S]*?)<\/script>/i), scriptContent = serverScriptMatch ? serverScriptMatch[1] : "", templateContent = content.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, ""), context = {
+          ...data,
+          __filename: templatePath,
+          __dirname: path.dirname(templatePath)
+        };
+        if (scriptContent.trim())
+          await extractVariables(scriptContent, context, templatePath);
+        const dependencies = new Set, strategy = fullOptions.streaming?.strategy || "auto", sectionTestRegex = new RegExp(SECTION_PATTERN.source, "g");
+        if (!(strategy !== "manual" && sectionTestRegex.test(templateContent))) {
+          const output = await processDirectives(templateContent, context, templatePath, fullOptions, dependencies);
+          for (let i = 0;i < output.length; i += bufferSize)
+            controller.enqueue(output.slice(i, i + bufferSize));
+        } else {
+          const sections = [], sectionRegex = new RegExp(SECTION_PATTERN.source, "g");
+          let match;
+          while ((match = sectionRegex.exec(templateContent)) !== null)
+            sections.push({ name: match[1], content: match[2], start: match.index, end: match.index + match[0].length });
+          let lastEnd = 0;
+          for (const section of sections) {
+            if (section.start > lastEnd) {
+              const shellPart = templateContent.slice(lastEnd, section.start);
+              if (shellPart.trim()) {
+                const processed = await processDirectives(shellPart, context, templatePath, fullOptions, dependencies);
+                controller.enqueue(processed);
+              }
+            }
+            const processed = await processDirectives(section.content, context, templatePath, fullOptions, dependencies);
+            controller.enqueue(processed);
+            lastEnd = section.end;
+          }
+          if (lastEnd < templateContent.length) {
+            const remaining = templateContent.slice(lastEnd);
+            if (remaining.trim()) {
+              const processed = await processDirectives(remaining, context, templatePath, fullOptions, dependencies);
+              controller.enqueue(processed);
+            }
+          }
+        }
+        controller.close();
+      } catch (error) {
+        controller.error(error);
+      }
+    }
+  });
+}
+export async function createStreamRenderer(templatePath, options = {}) {
+  const fullOptions = {
+    ...defaultConfig,
+    ...options,
+    streaming: {
+      ...defaultStreamingConfig,
+      ...options.streaming
+    }
+  }, content = await Bun.file(templatePath).text(), serverScriptMatch = content.match(/<script\b[^>]*\bserver\b[^>]*>([\s\S]*?)<\/script>/i), scriptContent = serverScriptMatch ? serverScriptMatch[1] : "", templateContent = content.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, ""), originalTemplate = templateContent, sections = {};
+  let match;
+  SECTION_PATTERN.lastIndex = 0;
+  while ((match = SECTION_PATTERN.exec(templateContent)) !== null) {
+    const sectionName = match[1], sectionContent = match[2];
+    sections[sectionName] = sectionContent;
+  }
+  const shellTemplate = templateContent.replace(SECTION_PATTERN, "");
+  return {
+    renderShell: async (data = {}) => {
+      const context = {
+        ...data,
+        __filename: templatePath,
+        __dirname: path.dirname(templatePath)
+      };
+      await extractVariables(scriptContent, context, templatePath);
+      return processDirectives(shellTemplate, context, templatePath, fullOptions, new Set);
+    },
+    renderSection: async (sectionName, data = {}) => {
+      try {
+        if (!sections[sectionName])
+          return `<div class="error-message">Section "${escapeHtml(sectionName)}" not found in template "${escapeHtml(templatePath)}"</div>`;
+        const context = {
+          ...data,
+          __filename: templatePath,
+          __dirname: path.dirname(templatePath)
+        };
+        await extractVariables(scriptContent, context, templatePath);
+        const dependencies = new Set;
+        return await processDirectives(sections[sectionName], context, templatePath, fullOptions, dependencies);
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return createDetailedErrorMessage("Expression", errorMessage, templatePath, sections[sectionName] || "", 0, sections[sectionName] || "");
+      }
+    },
+    getSections: () => {
+      return Object.keys(sections);
+    },
+    getTemplate: () => {
+      return originalTemplate;
+    }
+  };
+}
+export const streamingSuspenseDirective = {
+  name: "suspense",
+  hasEndTag: !0,
+  handler: (content, params, _context, _filePath) => {
+    if (!params || params.length === 0)
+      throw Error("Suspense directive requires a name parameter");
+    const suspenseName = params[0].replace(/['"`]/g, "");
+    return `<!-- @suspense:${suspenseName} -->${content}<!-- @endsuspense:${suspenseName} -->`;
+  }
+}, islandDirective = {
+  name: "island",
+  hasEndTag: !0,
+  handler: (content, params, _context, _filePath) => {
+    if (!params || params.length === 0)
+      throw Error("Island directive requires a name parameter");
+    const islandName = params[0].replace(/['"`]/g, ""), priority = params[1] ? params[1].replace(/['"`]/g, "") : "lazy", id = `island-${islandName}-${Math.random().toString(36).substring(2, 9)}`, propsMatch = content.match(/<script\s+props\s*>([\s\S]*?)<\/script>/i), propsScript = propsMatch ? propsMatch[1].trim() : "", contentWithoutProps = propsMatch ? content.replace(propsMatch[0], "") : content;
+    return `<div data-island="${islandName}" data-island-id="${id}" data-priority="${priority}">
+      ${contentWithoutProps}
+      <script type="application/json" data-island-props="${id}">
+        ${propsScript ? `{${propsScript}}` : "{}"}
+      </script>
+    </div>`;
+  }
+};
+export function registerStreamingDirectives(options = {}) {
+  const directives = [];
+  if (options.streaming?.enabled)
+    directives.push(streamingSuspenseDirective);
+  if (options.hydration?.enabled)
+    directives.push(islandDirective);
+  return directives;
+}
+export async function processSectionDirectives(content, context, filePath, _options = {}) {
+  return content;
+}
+export function streamToResponse(stream, init = {}) {
+  const encoder = new TextEncoder, byteStream = stream.pipeThrough(new TransformStream({
+    transform(chunk, controller) {
+      controller.enqueue(encoder.encode(chunk));
+    }
+  })), headers = new Headers(init.headers);
+  if (!headers.has("Content-Type"))
+    headers.set("Content-Type", "text/html; charset=utf-8");
+  if (!headers.has("Transfer-Encoding"))
+    headers.set("Transfer-Encoding", "chunked");
+  if (!headers.has("X-Content-Type-Options"))
+    headers.set("X-Content-Type-Options", "nosniff");
+  if (!headers.has("X-Accel-Buffering"))
+    headers.set("X-Accel-Buffering", "no");
+  return new Response(byteStream, {
+    ...init,
+    headers
+  });
+}
+export function generateHydrationRuntime(config = { mode: "full" }) {
+  const { mode, components = {}, dynamicImports = !0 } = config, componentRegistry = Object.entries(components).map(([name, path]) => `'${name}': ${dynamicImports ? `() => import('${path}')` : `require('${path}')`}`).join(`,
+      `);
+  if (mode === "loader")
+    return `
+(function() {
+  window.__stx = window.__stx || {};
+  window.__stx.islands = new Map();
+  window.__stx.registerComponent = function(name, component) {
+    window.__stx.islands.set(name, component);
+  };
+})();`;
+  return `
+(function() {
+  'use strict';
+
+  // Hydration runtime for stx islands
+  const stx = {
+    // Component registry
+    components: {
+      ${componentRegistry}
+    },
+
+    // Loaded island instances
+    islands: new Map(),
+
+    // Register a component for hydration
+    registerComponent: function(name, loader) {
+      this.components[name] = loader;
+    },
+
+    // Get props for an island by ID
+    getIslandProps: function(id) {
+      const propsScript = document.querySelector('[data-island-props="' + id + '"]');
+      if (!propsScript) return {};
+      try {
+        return JSON.parse(propsScript.textContent || '{}');
+      }
+catch (e) {
+        console.warn('[stx] Failed to parse island props:', id, e);
+        return {};
+      }
+    },
+
+    // Hydrate a single island
+    hydrateIsland: async function(element) {
+      const name = element.dataset.island;
+      const id = element.dataset.islandId;
+
+      if (!name || this.islands.has(id)) return;
+
+      const loader = this.components[name];
+      if (!loader) {
+        console.warn('[stx] Unknown island component:', name);
+        return;
+      }
+
+      try {
+        const component = typeof loader === 'function' ? await loader() : loader;
+        const props = this.getIslandProps(id);
+
+        // Mark as hydrating
+        element.dataset.hydrating = 'true';
+
+        // Call component's hydrate method if available
+        if (component.hydrate) {
+          await component.hydrate(element, props);
+        }
+else if (component.default && component.default.hydrate) {
+          await component.default.hydrate(element, props);
+        }
+
+        // Mark as hydrated
+        delete element.dataset.hydrating;
+        element.dataset.hydrated = 'true';
+        this.islands.set(id, { element, component, props });
+
+      }
+catch (error) {
+        console.error('[stx] Failed to hydrate island:', name, error);
+        element.dataset.hydrateError = 'true';
+      }
+    },
+
+    // Hydrate all islands based on priority
+    hydrate: function() {
+      const islands = document.querySelectorAll('[data-island]');
+
+      // Group by priority
+      const eager = [];
+      const lazy = [];
+      const idle = [];
+
+      islands.forEach(function(el) {
+        const priority = el.dataset.priority || 'lazy';
+        if (priority === 'eager') eager.push(el);
+        else if (priority === 'idle') idle.push(el);
+        else lazy.push(el);
+      });
+
+      // Hydrate eager immediately
+      eager.forEach(function(el) { stx.hydrateIsland(el); });
+
+      // Hydrate lazy on intersection
+      if (lazy.length > 0 && 'IntersectionObserver' in window) {
+        const observer = new IntersectionObserver(function(entries) {
+          entries.forEach(function(entry) {
+            if (entry.isIntersecting) {
+              observer.unobserve(entry.target);
+              stx.hydrateIsland(entry.target);
+            }
+          });
+        }, { rootMargin: '50px' });
+
+        lazy.forEach(function(el) { observer.observe(el); });
+      }
+else {
+        // Fallback: hydrate all lazy immediately
+        lazy.forEach(function(el) { stx.hydrateIsland(el); });
+      }
+
+      // Hydrate idle during browser idle time
+      if (idle.length > 0 && 'requestIdleCallback' in window) {
+        requestIdleCallback(function() {
+          idle.forEach(function(el) { stx.hydrateIsland(el); });
+        });
+      }
+else {
+        // Fallback: hydrate after a delay
+        setTimeout(function() {
+          idle.forEach(function(el) { stx.hydrateIsland(el); });
+        }, 200);
+      }
+    }
+  };
+
+  // Expose to window
+  window.__stx = stx;
+
+  // Auto-hydrate on DOMContentLoaded if not SSR
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', function() { stx.hydrate(); });
+  }
+else {
+    stx.hydrate();
+  }
+})();`;
+}

package/dist/strict-lint.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Lint a single source string for the Phase-1 stx footguns.
+ *
+ * @example
+ * ```ts
+ * const diagnostics = lintStxStrict(source, { filePath: 'resources/views/login.stx' })
+ * for (const d of diagnostics)
+ *   console.error(`${d.line}:${d.column} ${d.ruleId} — ${d.message}`)
+ * ```
+ */
+export declare function lintStxStrict(source: string, options?: StxStrictOptions): StxStrictDiagnostic[];
+export declare interface StxStrictDiagnostic {
+  ruleId: StxStrictRuleId
+  message: string
+  line: number
+  column: number
+  severity: 'error' | 'warning'
+}
+export declare interface StxStrictOptions {
+  filePath?: string
+  fileKind?: 'view' | 'component' | 'layout'
+  rules?: Partial<Record<StxStrictRuleId, boolean>>
+}
+/**
+ * stx-strict — the documented-footgun linter (stacksjs/stx#1744, Phase 1).
+ *
+ * A self-contained detection engine: feed it `.stx` (or store `.ts`) source
+ * and it returns diagnostics for the patterns that "look correct but do
+ * nothing / do the wrong thing" at runtime. It deliberately has NO imports
+ * from the rest of the package (no template pipeline, no i18n) so it's cheap
+ * to run and trivially unit-testable; wiring it into pickier / the CLI / the
+ * editor is a thin follow-up (Phase 1 ships the hard part — correct detection
+ * with low false-positive rate).
+ *
+ * Phase 1 covers the five highest-hit footguns from the issue:
+ *   1. stx/no-bare-function-ref-in-event       `@click="store.method"` (member path)
+ *   2. stx/store-value-imports-must-be-local   value import escaping resources/stores/
+ *   3. stx/no-signal-call-in-for-iteration-var calling the `:for` loop var like a signal
+ *   4. stx/no-backticks-in-html-comments       a backtick inside an HTML comment
+ *
+ * `stx/no-view-level-script-client` was removed in #1815: it asserted at error
+ * severity that a view-level `<script client>` is silently dropped, which is
+ * false — it is the primary documented authoring pattern, and its symbols reach
+ * the built page. The rule told people to break working code.
+ *
+ * Remaining footguns (web-components, template tags, @include loop-var
+ * forwarding, etc.) are Phase 2.
+ */
+export type StxStrictRuleId = | 'stx/no-bare-function-ref-in-event'
+  | 'stx/store-value-imports-must-be-local'
+  | 'stx/no-signal-call-in-for-iteration-var'
+  | 'stx/no-backticks-in-html-comments';