@elyndra/astro-effects 1.2.0

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@elyndra/astro-effects",
+  "version": "1.2.0",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Elyndra effects components for Astro (SSR shells with vanilla client hydration)",
+  "keywords": [
+    "elyndra",
+    "ui",
+    "front-end",
+    "framework",
+    "scifi",
+    "sci-fi",
+    "science-fiction",
+    "astro"
+  ],
+  "homepage": "https://elyndra.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Gabox301/elyndra.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Gabox301/elyndra/issues"
+  },
+  "funding": "https://github.com/sponsors/romelperez",
+  "license": "MIT",
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./Illuminator": "./src/Illuminator/Illuminator.astro",
+    "./IlluminatorSVG": "./src/IlluminatorSVG/IlluminatorSVG.astro",
+    "./client": "./src/client/effectsClient.ts"
+  },
+  "types": "./src/index.ts",
+  "module": "./src/index.ts",
+  "main": "./src/index.ts",
+  "peerDependencies": {
+    "astro": "7.3.2"
+  },
+  "dependencies": {
+    "@elyndra/effects": "^1.2.0",
+    "@elyndra/tools": "^1.2.0",
+    "tslib": "2.8.1"
+  },
+  "scripts": {
+    "build": "tsc --noEmit -p tsconfig.json"
+  }
+}

package/src/Illuminator/Illuminator.astro

@@ -0,0 +1,31 @@
+---
+import type { IlluminatorElementProps } from '../types.js';
+
+interface Props extends IlluminatorElementProps {}
+
+const { className, ...settings } = Astro.props as Props;
+
+// Ids only need page-level uniqueness: the component script consumes them in
+// the same render.
+const nodeId = `elyndra-illuminator-${Math.random().toString(36).slice(2)}`;
+const serializable = { ...settings };
+---
+
+<div
+  id={nodeId}
+  data-elyndra-illuminator
+  role="presentation"
+  class={className}
+  style="position: absolute; inset: 0; overflow: hidden; width: 100%; height: 100%;"
+>
+  <slot />
+</div>
+
+<script define:vars={{ nodeId, serializable }}>
+  import { initIlluminatorElement } from '../client/effectsClient.js';
+
+  const element = document.getElementById(nodeId);
+  if (element instanceof HTMLElement) {
+    initIlluminatorElement(element, serializable);
+  }
+</script>

package/src/Illuminator/Illuminator.test.ts

@@ -0,0 +1,25 @@
+// @vitest-environment node
+// Render tests assert on SSR strings, so they run in node: under jsdom the
+// Astro plugin compiles `.astro` imports for the browser (client stub).
+import { expect, test } from 'vitest';
+import { renderComponent } from '../testUtils/index.js';
+import Illuminator from './Illuminator.astro';
+
+test('Should render children inside the illuminator shell', async () => {
+  const html = await renderComponent(Illuminator, {
+    slots: { default: '<span>hello</span>' },
+  });
+
+  expect(html).toContain('data-elyndra-illuminator');
+  expect(html).toContain('hello');
+});
+
+test('Should pass serializable settings to the client script', async () => {
+  const html = await renderComponent(Illuminator, {
+    props: { color: 'red', size: 120 },
+    slots: { default: 'x' },
+  });
+
+  expect(html).toContain('data-elyndra-illuminator');
+  expect(html).toContain('initIlluminatorElement');
+});

package/src/IlluminatorSVG/IlluminatorSVG.astro

@@ -0,0 +1,26 @@
+---
+import type { IlluminatorSVGElementProps } from '../types.js';
+
+interface Props extends IlluminatorSVGElementProps {}
+
+const { className, ...settings } = Astro.props as Props;
+
+// Ids only need page-level uniqueness: the component script consumes them in
+// the same render. The `<g>` must be placed inside a consumer `<svg>`; the
+// client resolves it via `closest('svg')`.
+const nodeId = `elyndra-illuminator-svg-${Math.random().toString(36).slice(2)}`;
+const serializable = { ...settings };
+---
+
+<g id={nodeId} data-elyndra-illuminator-svg class={className} style="pointer-events: none;">
+  <slot />
+</g>
+
+<script define:vars={{ nodeId, serializable }}>
+  import { initIlluminatorSVGElement } from '../client/effectsClient.js';
+
+  const element = document.getElementById(nodeId);
+  if (element instanceof SVGGElement) {
+    initIlluminatorSVGElement(element, serializable);
+  }
+</script>

package/src/IlluminatorSVG/IlluminatorSVG.test.ts

@@ -0,0 +1,16 @@
+// @vitest-environment node
+// Render tests assert on SSR strings, so they run in node: under jsdom the
+// Astro plugin compiles `.astro` imports for the browser (client stub).
+import { expect, test } from 'vitest';
+import { renderComponent } from '../testUtils/index.js';
+import IlluminatorSVG from './IlluminatorSVG.astro';
+
+test('Should render children inside the svg illuminator shell', async () => {
+  const html = await renderComponent(IlluminatorSVG, {
+    props: { color: 'red' },
+    slots: { default: '<circle />' },
+  });
+
+  expect(html).toContain('data-elyndra-illuminator-svg');
+  expect(html).toContain('initIlluminatorSVGElement');
+});

package/src/astro.d.ts

@@ -0,0 +1,7 @@
+// In-repo ambient types for `.astro` imports (tests only). The published
+// package ships the `.astro` sources and consumers get full prop inference
+// from the frontmatter `Props` interfaces via their own Astro setup.
+declare module '*.astro' {
+  const Component: unknown;
+  export default Component;
+}

package/src/client/effectsClient.test.ts

@@ -0,0 +1,52 @@
+import { beforeEach, expect, test } from 'vitest';
+import { initIlluminatorElement, initIlluminatorSVGElement } from './effectsClient.js';
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+test('Should append the illuminator layer and mark the node', () => {
+  const element = document.createElement('div');
+  document.body.appendChild(element);
+
+  initIlluminatorElement(element, { color: 'red', size: 120 });
+
+  expect(element.hasAttribute('data-elyndra-illuminator-node')).toBe(true);
+  expect(element.querySelector('[data-name="illuminator"]')).not.toBeNull();
+});
+
+test('Should remove the layer and unmark on dispose, idempotently', () => {
+  const element = document.createElement('div');
+  document.body.appendChild(element);
+  const handle = initIlluminatorElement(element, {});
+
+  handle.dispose();
+  handle.dispose();
+
+  expect(element.hasAttribute('data-elyndra-illuminator-node')).toBe(false);
+  expect(element.querySelector('[data-name="illuminator"]')).toBeNull();
+});
+
+test('Should resolve the svg ancestor and mark the svg node', () => {
+  const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+  const element = document.createElementNS('http://www.w3.org/2000/svg', 'g');
+  svg.appendChild(element);
+  document.body.appendChild(svg);
+
+  const handle = initIlluminatorSVGElement(element, { color: 'blue', size: 80 });
+
+  expect(handle).toBeDefined();
+  expect(element.hasAttribute('data-elyndra-illuminator-svg-node')).toBe(true);
+
+  handle?.dispose();
+
+  expect(element.hasAttribute('data-elyndra-illuminator-svg-node')).toBe(false);
+});
+
+test('Should return undefined outside any svg', () => {
+  const element = document.createElementNS('http://www.w3.org/2000/svg', 'g');
+  document.body.appendChild(element);
+
+  expect(initIlluminatorSVGElement(element, {})).toBeUndefined();
+  expect(element.hasAttribute('data-elyndra-illuminator-svg-node')).toBe(false);
+});

package/src/client/effectsClient.ts

@@ -0,0 +1,108 @@
+import {
+  type EffectIlluminator,
+  type EffectIlluminatorSVG,
+  createEffectIlluminator,
+  createEffectIlluminatorSVG,
+} from '@elyndra/effects';
+import { filterProps } from '@elyndra/tools';
+import type { IlluminatorElementProps, IlluminatorSVGElementProps } from '../types.js';
+
+const ILLUMINATOR_NODE_MARKER = 'data-elyndra-illuminator-node';
+const ILLUMINATOR_SVG_NODE_MARKER = 'data-elyndra-illuminator-svg-node';
+
+interface IlluminatorHandle {
+  readonly effect: EffectIlluminator;
+  readonly dispose: () => void;
+}
+
+interface IlluminatorSVGHandle {
+  readonly effect: EffectIlluminatorSVG;
+  readonly dispose: () => void;
+}
+
+const illuminatorByElement = new WeakMap<Element, IlluminatorHandle>();
+const illuminatorSVGByElement = new WeakMap<Element, IlluminatorSVGHandle>();
+
+/**
+ * Hydrates one illuminator element: the shell itself is the vanilla
+ * container. Idempotent: re-running cancels the previous effect first.
+ */
+const initIlluminatorElement = (
+  element: HTMLElement,
+  props: IlluminatorElementProps,
+): IlluminatorHandle => {
+  illuminatorByElement.get(element)?.dispose();
+
+  const effect = createEffectIlluminator({
+    container: element,
+    ...filterProps({ color: props.color, size: props.size }),
+  });
+
+  element.setAttribute(ILLUMINATOR_NODE_MARKER, '');
+
+  const handle: IlluminatorHandle = {
+    effect,
+    dispose: () => {
+      if (illuminatorByElement.get(element) !== handle) {
+        return;
+      }
+      illuminatorByElement.delete(element);
+      element.removeAttribute(ILLUMINATOR_NODE_MARKER);
+      effect.cancel();
+    },
+  };
+
+  illuminatorByElement.set(element, handle);
+
+  return handle;
+};
+
+/**
+ * Hydrates one SVG illuminator element: the `<svg>` ancestor resolves via
+ * `closest('svg')` (the island replacement for the React `svgRef`). Returns
+ * `undefined` outside any `<svg>`. Idempotent: re-running cancels the
+ * previous effect first.
+ */
+const initIlluminatorSVGElement = (
+  element: SVGGElement,
+  props: IlluminatorSVGElementProps,
+): IlluminatorSVGHandle | undefined => {
+  illuminatorSVGByElement.get(element)?.dispose();
+
+  const svg = element.closest('svg');
+  if (!(svg instanceof SVGSVGElement)) {
+    return undefined;
+  }
+
+  const effect = createEffectIlluminatorSVG({
+    svg,
+    container: element,
+    ...filterProps({ color: props.color, size: props.size }),
+  });
+
+  element.setAttribute(ILLUMINATOR_SVG_NODE_MARKER, '');
+
+  const handle: IlluminatorSVGHandle = {
+    effect,
+    dispose: () => {
+      if (illuminatorSVGByElement.get(element) !== handle) {
+        return;
+      }
+      illuminatorSVGByElement.delete(element);
+      element.removeAttribute(ILLUMINATOR_SVG_NODE_MARKER);
+      effect.cancel();
+    },
+  };
+
+  illuminatorSVGByElement.set(element, handle);
+
+  return handle;
+};
+
+export {
+  ILLUMINATOR_NODE_MARKER,
+  ILLUMINATOR_SVG_NODE_MARKER,
+  initIlluminatorElement,
+  initIlluminatorSVGElement,
+};
+export type { IlluminatorHandle, IlluminatorSVGHandle };

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './client/effectsClient.js';
+export type * from './types.js';

package/src/testUtils/index.ts

@@ -0,0 +1 @@
+export * from './renderComponent.js';

package/src/testUtils/renderComponent.ts

@@ -0,0 +1,16 @@
+import {
+  type ContainerRenderOptions,
+  experimental_AstroContainer as AstroContainer,
+} from 'astro/container';
+
+/**
+ * Renders an `.astro` component to a string. In-repo `.astro` imports are
+ * `unknown` (ambient declaration, tests only), so the factory type is
+ * inferred from the container itself — no drift if Astro changes it.
+ */
+const renderComponent = async (component: unknown, options?: ContainerRenderOptions): Promise<string> => {
+  const container = await AstroContainer.create();
+  return container.renderToString(component as Parameters<typeof container.renderToString>[0], options);
+};
+
+export { renderComponent };

package/src/types.ts

@@ -0,0 +1,32 @@
+/**
+ * Serializable subset of the illuminator settings. Only JSON crosses the
+ * Astro server/client boundary (`define:vars`):
+ * - `container` is excluded: the shell element itself is the container.
+ * - `className`/`style` stay server-side as presentational shell attrs.
+ * - `elementRef`/`svgRef` are excluded: the shell element is hydrated
+ *   directly and the `<svg>` ancestor resolves via `closest('svg')`.
+ */
+interface IlluminatorSerializableSettings {
+  color?: string;
+  size?: number;
+}
+
+interface IlluminatorElementProps extends IlluminatorSerializableSettings {
+  className?: string;
+}
+
+interface IlluminatorSVGSerializableSettings {
+  color?: string;
+  size?: number;
+}
+
+interface IlluminatorSVGElementProps extends IlluminatorSVGSerializableSettings {
+  className?: string;
+}
+
+export type {
+  IlluminatorElementProps,
+  IlluminatorSerializableSettings,
+  IlluminatorSVGElementProps,
+  IlluminatorSVGSerializableSettings,
+};