@elyndra/astro-bgs 1.2.0

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@elyndra/astro-bgs",
+  "version": "1.2.0",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Elyndra backgrounds 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",
+    "./Dots": "./src/Dots/Dots.astro",
+    "./GridLines": "./src/GridLines/GridLines.astro",
+    "./MovingLines": "./src/MovingLines/MovingLines.astro",
+    "./Puffs": "./src/Puffs/Puffs.astro",
+    "./client": "./src/client/bgsClient.ts"
+  },
+  "types": "./src/index.ts",
+  "module": "./src/index.ts",
+  "main": "./src/index.ts",
+  "peerDependencies": {
+    "astro": "7.3.2"
+  },
+  "dependencies": {
+    "@elyndra/bgs": "^1.2.0",
+    "tslib": "2.8.1"
+  },
+  "scripts": {
+    "build": "tsc --noEmit -p tsconfig.json"
+  }
+}

package/src/Dots/Dots.astro

@@ -0,0 +1,29 @@
+---
+import type { DotsElementProps } from '../types.js';
+
+interface Props extends DotsElementProps {}
+
+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-bgs-dots-${Math.random().toString(36).slice(2)}`;
+const serializable = { ...settings };
+---
+
+<canvas
+  id={nodeId}
+  data-elyndra-bgs-dots
+  aria-hidden="true"
+  class={className}
+  style="position: absolute; inset: 0; display: block; border: 0; margin: 0; padding: 0; width: 100%; height: 100%;"
+></canvas>
+
+<script define:vars={{ nodeId, serializable }}>
+  import { initDotsElement } from '../client/bgsClient.js';
+
+  const element = document.getElementById(nodeId);
+  if (element instanceof HTMLCanvasElement) {
+    initDotsElement(element, serializable);
+  }
+</script>

package/src/Dots/Dots.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 Dots from './Dots.astro';
+
+test('Should render the dots canvas shell', async () => {
+  const html = await renderComponent(Dots, {
+    props: { color: '#fff', distance: 20 },
+  });
+
+  expect(html).toContain('data-elyndra-bgs-dots');
+  expect(html).toContain('aria-hidden="true"');
+  expect(html).toContain('initDotsElement');
+});

package/src/GridLines/GridLines.astro

@@ -0,0 +1,29 @@
+---
+import type { GridLinesElementProps } from '../types.js';
+
+interface Props extends GridLinesElementProps {}
+
+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-bgs-grid-lines-${Math.random().toString(36).slice(2)}`;
+const serializable = { ...settings };
+---
+
+<canvas
+  id={nodeId}
+  data-elyndra-bgs-grid-lines
+  aria-hidden="true"
+  class={className}
+  style="position: absolute; inset: 0; display: block; border: 0; margin: 0; padding: 0; width: 100%; height: 100%;"
+></canvas>
+
+<script define:vars={{ nodeId, serializable }}>
+  import { initGridLinesElement } from '../client/bgsClient.js';
+
+  const element = document.getElementById(nodeId);
+  if (element instanceof HTMLCanvasElement) {
+    initGridLinesElement(element, serializable);
+  }
+</script>

package/src/GridLines/GridLines.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 GridLines from './GridLines.astro';
+
+test('Should render the grid-lines canvas shell', async () => {
+  const html = await renderComponent(GridLines, {
+    props: { lineColor: '#fff' },
+  });
+
+  expect(html).toContain('data-elyndra-bgs-grid-lines');
+  expect(html).toContain('aria-hidden="true"');
+  expect(html).toContain('initGridLinesElement');
+});

package/src/MovingLines/MovingLines.astro

@@ -0,0 +1,29 @@
+---
+import type { MovingLinesElementProps } from '../types.js';
+
+interface Props extends MovingLinesElementProps {}
+
+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-bgs-moving-lines-${Math.random().toString(36).slice(2)}`;
+const serializable = { ...settings };
+---
+
+<canvas
+  id={nodeId}
+  data-elyndra-bgs-moving-lines
+  aria-hidden="true"
+  class={className}
+  style="position: absolute; inset: 0; display: block; border: 0; margin: 0; padding: 0; width: 100%; height: 100%;"
+></canvas>
+
+<script define:vars={{ nodeId, serializable }}>
+  import { initMovingLinesElement } from '../client/bgsClient.js';
+
+  const element = document.getElementById(nodeId);
+  if (element instanceof HTMLCanvasElement) {
+    initMovingLinesElement(element, serializable);
+  }
+</script>

package/src/MovingLines/MovingLines.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 MovingLines from './MovingLines.astro';
+
+test('Should render the moving-lines canvas shell', async () => {
+  const html = await renderComponent(MovingLines, {
+    props: { sets: 2 },
+  });
+
+  expect(html).toContain('data-elyndra-bgs-moving-lines');
+  expect(html).toContain('aria-hidden="true"');
+  expect(html).toContain('initMovingLinesElement');
+});

package/src/Puffs/Puffs.astro

@@ -0,0 +1,29 @@
+---
+import type { PuffsElementProps } from '../types.js';
+
+interface Props extends PuffsElementProps {}
+
+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-bgs-puffs-${Math.random().toString(36).slice(2)}`;
+const serializable = { ...settings };
+---
+
+<canvas
+  id={nodeId}
+  data-elyndra-bgs-puffs
+  aria-hidden="true"
+  class={className}
+  style="position: absolute; inset: 0; display: block; border: 0; margin: 0; padding: 0; width: 100%; height: 100%;"
+></canvas>
+
+<script define:vars={{ nodeId, serializable }}>
+  import { initPuffsElement } from '../client/bgsClient.js';
+
+  const element = document.getElementById(nodeId);
+  if (element instanceof HTMLCanvasElement) {
+    initPuffsElement(element, serializable);
+  }
+</script>

package/src/Puffs/Puffs.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 Puffs from './Puffs.astro';
+
+test('Should render the puffs canvas shell', async () => {
+  const html = await renderComponent(Puffs, {
+    props: { color: '#fff', quantity: 4 },
+  });
+
+  expect(html).toContain('data-elyndra-bgs-puffs');
+  expect(html).toContain('aria-hidden="true"');
+  expect(html).toContain('initPuffsElement');
+});

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/bgsClient.test.ts

@@ -0,0 +1,76 @@
+import { beforeEach, expect, test } from 'vitest';
+import {
+  initDotsElement,
+  initGridLinesElement,
+  initMovingLinesElement,
+  initPuffsElement,
+} from './bgsClient.js';
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+const mountCanvas = (): HTMLCanvasElement => {
+  const element = document.createElement('canvas');
+  document.body.appendChild(element);
+  return element;
+};
+
+test('Should mark the dots node and cancel on dispose', () => {
+  const element = mountCanvas();
+
+  const handle = initDotsElement(element, { color: '#fff' });
+
+  // jsdom has no 2d context: the vanilla background is a safe no-op.
+  expect(element.hasAttribute('data-elyndra-bgs-dots-node')).toBe(true);
+
+  handle.dispose();
+  handle.dispose();
+
+  expect(element.hasAttribute('data-elyndra-bgs-dots-node')).toBe(false);
+});
+
+test('Should mark the grid-lines node and cancel on dispose', () => {
+  const element = mountCanvas();
+
+  const handle = initGridLinesElement(element, { lineColor: '#fff' });
+
+  expect(element.hasAttribute('data-elyndra-bgs-grid-lines-node')).toBe(true);
+
+  handle.dispose();
+
+  expect(element.hasAttribute('data-elyndra-bgs-grid-lines-node')).toBe(false);
+});
+
+test('Should mark the moving-lines node and cancel on dispose', () => {
+  const element = mountCanvas();
+
+  const handle = initMovingLinesElement(element, { sets: 2 });
+
+  expect(element.hasAttribute('data-elyndra-bgs-moving-lines-node')).toBe(true);
+
+  handle.dispose();
+
+  expect(element.hasAttribute('data-elyndra-bgs-moving-lines-node')).toBe(false);
+});
+
+test('Should mark the puffs node and cancel on dispose', () => {
+  const element = mountCanvas();
+
+  const handle = initPuffsElement(element, { color: '#fff', quantity: 4 });
+
+  expect(element.hasAttribute('data-elyndra-bgs-puffs-node')).toBe(true);
+
+  handle.dispose();
+
+  expect(element.hasAttribute('data-elyndra-bgs-puffs-node')).toBe(false);
+});
+
+test('Should dispose the previous background on second init', () => {
+  const element = mountCanvas();
+
+  initDotsElement(element, {});
+  initDotsElement(element, {});
+
+  expect(element.hasAttribute('data-elyndra-bgs-dots-node')).toBe(true);
+});

package/src/client/bgsClient.ts

@@ -0,0 +1,137 @@
+import {
+  type BackgroundDots,
+  type BackgroundGridLines,
+  type BackgroundMovingLines,
+  type BackgroundPuffs,
+  createBackgroundDots,
+  createBackgroundGridLines,
+  createBackgroundMovingLines,
+  createBackgroundPuffs,
+} from '@elyndra/bgs';
+import type {
+  DotsElementProps,
+  DotsSerializableSettings,
+  GridLinesElementProps,
+  GridLinesSerializableSettings,
+  MovingLinesElementProps,
+  MovingLinesSerializableSettings,
+  PuffsElementProps,
+  PuffsSerializableSettings,
+} from '../types.js';
+
+const DOTS_NODE_MARKER = 'data-elyndra-bgs-dots-node';
+const GRID_LINES_NODE_MARKER = 'data-elyndra-bgs-grid-lines-node';
+const MOVING_LINES_NODE_MARKER = 'data-elyndra-bgs-moving-lines-node';
+const PUFFS_NODE_MARKER = 'data-elyndra-bgs-puffs-node';
+
+interface BackgroundHandle<T> {
+  readonly background: T;
+  readonly dispose: () => void;
+}
+
+const backgroundsByElement = new WeakMap<Element, { dispose: () => void }>();
+
+// Presentational shell attrs (`className`) never reach the vanilla settings.
+const toSettings = <P extends { className?: string }, S>(props: P): S => {
+  const { className: _presentational, ...settings } = props;
+  void _presentational;
+  return settings as S;
+};
+
+const initBackgroundElement = <T extends { cancel: () => void }>(
+  element: HTMLCanvasElement,
+  marker: string,
+  create: () => T,
+): BackgroundHandle<T> => {
+  backgroundsByElement.get(element)?.dispose();
+
+  const background = create();
+
+  element.setAttribute(marker, '');
+
+  const handle: BackgroundHandle<T> = {
+    background,
+    dispose: () => {
+      if (backgroundsByElement.get(element) !== handle) {
+        return;
+      }
+      backgroundsByElement.delete(element);
+      element.removeAttribute(marker);
+      background.cancel();
+    },
+  };
+
+  backgroundsByElement.set(element, handle);
+
+  return handle;
+};
+
+/**
+ * Hydrates one dots background: the shell canvas itself is the vanilla
+ * target. Islands run standalone (no animator join). Idempotent: re-running
+ * cancels the previous background first.
+ */
+const initDotsElement = (
+  element: HTMLCanvasElement,
+  props: DotsElementProps,
+): BackgroundHandle<BackgroundDots> =>
+  initBackgroundElement(element, DOTS_NODE_MARKER, () =>
+    createBackgroundDots({
+      canvas: element,
+      settingsRef: { current: toSettings<DotsElementProps, DotsSerializableSettings>(props) },
+    }),
+  );
+
+/**
+ * Hydrates one grid-lines background (same island semantics as dots).
+ */
+const initGridLinesElement = (
+  element: HTMLCanvasElement,
+  props: GridLinesElementProps,
+): BackgroundHandle<BackgroundGridLines> =>
+  initBackgroundElement(element, GRID_LINES_NODE_MARKER, () =>
+    createBackgroundGridLines({
+      canvas: element,
+      settingsRef: { current: toSettings<GridLinesElementProps, GridLinesSerializableSettings>(props) },
+    }),
+  );
+
+/**
+ * Hydrates one moving-lines background (same island semantics as dots).
+ */
+const initMovingLinesElement = (
+  element: HTMLCanvasElement,
+  props: MovingLinesElementProps,
+): BackgroundHandle<BackgroundMovingLines> =>
+  initBackgroundElement(element, MOVING_LINES_NODE_MARKER, () =>
+    createBackgroundMovingLines({
+      canvas: element,
+      settingsRef: { current: toSettings<MovingLinesElementProps, MovingLinesSerializableSettings>(props) },
+    }),
+  );
+
+/**
+ * Hydrates one puffs background (same island semantics as dots).
+ */
+const initPuffsElement = (
+  element: HTMLCanvasElement,
+  props: PuffsElementProps,
+): BackgroundHandle<BackgroundPuffs> =>
+  initBackgroundElement(element, PUFFS_NODE_MARKER, () =>
+    createBackgroundPuffs({
+      canvas: element,
+      settingsRef: { current: toSettings<PuffsElementProps, PuffsSerializableSettings>(props) },
+    }),
+  );
+
+export {
+  DOTS_NODE_MARKER,
+  GRID_LINES_NODE_MARKER,
+  initDotsElement,
+  initGridLinesElement,
+  initMovingLinesElement,
+  initPuffsElement,
+  MOVING_LINES_NODE_MARKER,
+  PUFFS_NODE_MARKER,
+};
+export type { BackgroundHandle };

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './client/bgsClient.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,50 @@
+import type {
+  CreateBackgroundDotsSettings,
+  CreateBackgroundGridLinesSettings,
+  CreateBackgroundMovingLinesSettings,
+  CreateBackgroundPuffsSettings,
+} from '@elyndra/bgs';
+
+/**
+ * Serializable subsets of the background settings. Only JSON crosses the
+ * Astro server/client boundary (`define:vars`):
+ * - `easing` function forms are excluded: use easing names instead.
+ * - `canvas`, `animator` and `settingsRef` are excluded: the shell canvas
+ *   itself is hydrated and islands run standalone (no animator join).
+ * - `elementRef`/`id`/`style`/`positioned` are excluded: the shell carries
+ *   `className` server-side; consumers style via classes.
+ */
+interface DotsSerializableSettings extends CreateBackgroundDotsSettings {}
+
+interface DotsElementProps extends DotsSerializableSettings {
+  className?: string;
+}
+
+interface GridLinesSerializableSettings extends CreateBackgroundGridLinesSettings {}
+
+interface GridLinesElementProps extends GridLinesSerializableSettings {
+  className?: string;
+}
+
+interface MovingLinesSerializableSettings extends CreateBackgroundMovingLinesSettings {}
+
+interface MovingLinesElementProps extends MovingLinesSerializableSettings {
+  className?: string;
+}
+
+interface PuffsSerializableSettings extends CreateBackgroundPuffsSettings {}
+
+interface PuffsElementProps extends PuffsSerializableSettings {
+  className?: string;
+}
+
+export type {
+  DotsElementProps,
+  DotsSerializableSettings,
+  GridLinesElementProps,
+  GridLinesSerializableSettings,
+  MovingLinesElementProps,
+  MovingLinesSerializableSettings,
+  PuffsElementProps,
+  PuffsSerializableSettings,
+};