@elyndra/astro-frames 1.2.0

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@elyndra/astro-frames",
+  "version": "1.2.0",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Elyndra frames 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",
+    "./FrameBase": "./src/FrameBase/FrameBase.astro",
+    "./FrameCircle": "./src/FrameCircle/FrameCircle.astro",
+    "./FrameCorners": "./src/FrameCorners/FrameCorners.astro",
+    "./FrameHeader": "./src/FrameHeader/FrameHeader.astro",
+    "./FrameKranox": "./src/FrameKranox/FrameKranox.astro",
+    "./FrameLines": "./src/FrameLines/FrameLines.astro",
+    "./FrameNefrex": "./src/FrameNefrex/FrameNefrex.astro",
+    "./FrameNero": "./src/FrameNero/FrameNero.astro",
+    "./FrameOctagon": "./src/FrameOctagon/FrameOctagon.astro",
+    "./FrameUnderline": "./src/FrameUnderline/FrameUnderline.astro",
+    "./client": "./src/client/frameClient.ts"
+  },
+  "types": "./src/index.ts",
+  "module": "./src/index.ts",
+  "main": "./src/index.ts",
+  "peerDependencies": {
+    "astro": "7.3.2"
+  },
+  "dependencies": {
+    "@elyndra/frames": "^1.2.0",
+    "@elyndra/tools": "^1.2.0",
+    "tslib": "2.8.1"
+  },
+  "scripts": {
+    "build": "tsc --noEmit -p tsconfig.json"
+  }
+}

package/src/FrameBase/FrameBase.astro

@@ -0,0 +1,33 @@
+---
+import type { FrameBaseElementProps } from '../types.js';
+
+interface Props extends FrameBaseElementProps {}
+
+const { className, preserveAspectRatio = 'none', ...settings } = Astro.props as Props;
+
+// Ids only need page-level uniqueness: the component script consumes them in
+// the same render.
+const nodeId = `elyndra-frame-base-${Math.random().toString(36).slice(2)}`;
+const serializable = { ...settings };
+---
+
+<svg
+  id={nodeId}
+  data-elyndra-frame-base
+  role="presentation"
+  class={className}
+  style="position: absolute; inset: 0; display: block; border: 0; margin: 0; padding: 0; width: 100%; height: 100%;"
+  xmlns="http://www.w3.org/2000/svg"
+  preserveAspectRatio={preserveAspectRatio}
+>
+  <slot />
+</svg>
+
+<script define:vars={{ nodeId, serializable }}>
+  import { initFrameBaseElement } from '../client/frameClient.js';
+
+  const element = document.getElementById(nodeId);
+  if (element instanceof SVGSVGElement) {
+    initFrameBaseElement(element, serializable);
+  }
+</script>

package/src/FrameBase/FrameBase.test.ts

@@ -0,0 +1,15 @@
+// @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 FrameBase from './FrameBase.astro';
+
+test('Should render children inside the frame base shell', async () => {
+  const html = await renderComponent(FrameBase, {
+    slots: { default: '<g><circle /></g>' },
+  });
+
+  expect(html).toContain('data-elyndra-frame-base');
+  expect(html).toContain('initFrameBaseElement');
+});

package/src/FrameCircle/FrameCircle.astro

@@ -0,0 +1,33 @@
+---
+import type { FrameCircleElementProps } from '../types.js';
+
+interface Props extends FrameCircleElementProps {}
+
+const { className, preserveAspectRatio = 'none', ...settings } = Astro.props as Props;
+
+// Ids only need page-level uniqueness: the component script consumes them in
+// the same render.
+const nodeId = `elyndra-frame-circle-${Math.random().toString(36).slice(2)}`;
+const serializable = { ...settings };
+---
+
+<svg
+  id={nodeId}
+  data-elyndra-frame-circle
+  role="presentation"
+  class={className}
+  style="position: absolute; inset: 0; display: block; border: 0; margin: 0; padding: 0; width: 100%; height: 100%;"
+  xmlns="http://www.w3.org/2000/svg"
+  preserveAspectRatio={preserveAspectRatio}
+>
+  <slot />
+</svg>
+
+<script define:vars={{ nodeId, serializable }}>
+  import { initFrameCircleElement } from '../client/frameClient.js';
+
+  const element = document.getElementById(nodeId);
+  if (element instanceof SVGSVGElement) {
+    initFrameCircleElement(element, serializable);
+  }
+</script>

package/src/FrameCircle/FrameCircle.test.ts

@@ -0,0 +1,15 @@
+// @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 FrameCircle from './FrameCircle.astro';
+
+test('Should render the frame circle shell', async () => {
+  const html = await renderComponent(FrameCircle, {
+    props: { padding: 4 },
+  });
+
+  expect(html).toContain('data-elyndra-frame-circle');
+  expect(html).toContain('initFrameCircleElement');
+});

package/src/FrameCorners/FrameCorners.astro

@@ -0,0 +1,33 @@
+---
+import type { FrameCornersElementProps } from '../types.js';
+
+interface Props extends FrameCornersElementProps {}
+
+const { className, preserveAspectRatio = 'none', ...settings } = Astro.props as Props;
+
+// Ids only need page-level uniqueness: the component script consumes them in
+// the same render.
+const nodeId = `elyndra-frame-corners-${Math.random().toString(36).slice(2)}`;
+const serializable = { ...settings };
+---
+
+<svg
+  id={nodeId}
+  data-elyndra-frame-corners
+  role="presentation"
+  class={className}
+  style="position: absolute; inset: 0; display: block; border: 0; margin: 0; padding: 0; width: 100%; height: 100%;"
+  xmlns="http://www.w3.org/2000/svg"
+  preserveAspectRatio={preserveAspectRatio}
+>
+  <slot />
+</svg>
+
+<script define:vars={{ nodeId, serializable }}>
+  import { initFrameCornersElement } from '../client/frameClient.js';
+
+  const element = document.getElementById(nodeId);
+  if (element instanceof SVGSVGElement) {
+    initFrameCornersElement(element, serializable);
+  }
+</script>

package/src/FrameCorners/FrameCorners.test.ts

@@ -0,0 +1,15 @@
+// @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 FrameCorners from './FrameCorners.astro';
+
+test('Should render the frame corners shell', async () => {
+  const html = await renderComponent(FrameCorners, {
+    props: { cornerLength: 8 },
+  });
+
+  expect(html).toContain('data-elyndra-frame-corners');
+  expect(html).toContain('initFrameCornersElement');
+});

package/src/FrameHeader/FrameHeader.astro

@@ -0,0 +1,33 @@
+---
+import type { FrameHeaderElementProps } from '../types.js';
+
+interface Props extends FrameHeaderElementProps {}
+
+const { className, preserveAspectRatio = 'none', ...settings } = Astro.props as Props;
+
+// Ids only need page-level uniqueness: the component script consumes them in
+// the same render.
+const nodeId = `elyndra-frame-header-${Math.random().toString(36).slice(2)}`;
+const serializable = { ...settings };
+---
+
+<svg
+  id={nodeId}
+  data-elyndra-frame-header
+  role="presentation"
+  class={className}
+  style="position: absolute; inset: 0; display: block; border: 0; margin: 0; padding: 0; width: 100%; height: 100%;"
+  xmlns="http://www.w3.org/2000/svg"
+  preserveAspectRatio={preserveAspectRatio}
+>
+  <slot />
+</svg>
+
+<script define:vars={{ nodeId, serializable }}>
+  import { initFrameHeaderElement } from '../client/frameClient.js';
+
+  const element = document.getElementById(nodeId);
+  if (element instanceof SVGSVGElement) {
+    initFrameHeaderElement(element, serializable);
+  }
+</script>

package/src/FrameHeader/FrameHeader.test.ts

@@ -0,0 +1,15 @@
+// @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 FrameHeader from './FrameHeader.astro';
+
+test('Should render the frame header shell', async () => {
+  const html = await renderComponent(FrameHeader, {
+    props: { direction: 'vertical' },
+  });
+
+  expect(html).toContain('data-elyndra-frame-header');
+  expect(html).toContain('initFrameHeaderElement');
+});

package/src/FrameKranox/FrameKranox.astro

@@ -0,0 +1,33 @@
+---
+import type { FrameKranoxElementProps } from '../types.js';
+
+interface Props extends FrameKranoxElementProps {}
+
+const { className, preserveAspectRatio = 'none', ...settings } = Astro.props as Props;
+
+// Ids only need page-level uniqueness: the component script consumes them in
+// the same render.
+const nodeId = `elyndra-frame-kranox-${Math.random().toString(36).slice(2)}`;
+const serializable = { ...settings };
+---
+
+<svg
+  id={nodeId}
+  data-elyndra-frame-kranox
+  role="presentation"
+  class={className}
+  style="position: absolute; inset: 0; display: block; border: 0; margin: 0; padding: 0; width: 100%; height: 100%;"
+  xmlns="http://www.w3.org/2000/svg"
+  preserveAspectRatio={preserveAspectRatio}
+>
+  <slot />
+</svg>
+
+<script define:vars={{ nodeId, serializable }}>
+  import { initFrameKranoxElement } from '../client/frameClient.js';
+
+  const element = document.getElementById(nodeId);
+  if (element instanceof SVGSVGElement) {
+    initFrameKranoxElement(element, serializable);
+  }
+</script>

package/src/FrameKranox/FrameKranox.test.ts

@@ -0,0 +1,15 @@
+// @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 FrameKranox from './FrameKranox.astro';
+
+test('Should render the frame kranox shell', async () => {
+  const html = await renderComponent(FrameKranox, {
+    props: { squareSize: 8 },
+  });
+
+  expect(html).toContain('data-elyndra-frame-kranox');
+  expect(html).toContain('initFrameKranoxElement');
+});

package/src/FrameLines/FrameLines.astro

@@ -0,0 +1,33 @@
+---
+import type { FrameLinesElementProps } from '../types.js';
+
+interface Props extends FrameLinesElementProps {}
+
+const { className, preserveAspectRatio = 'none', ...settings } = Astro.props as Props;
+
+// Ids only need page-level uniqueness: the component script consumes them in
+// the same render.
+const nodeId = `elyndra-frame-lines-${Math.random().toString(36).slice(2)}`;
+const serializable = { ...settings };
+---
+
+<svg
+  id={nodeId}
+  data-elyndra-frame-lines
+  role="presentation"
+  class={className}
+  style="position: absolute; inset: 0; display: block; border: 0; margin: 0; padding: 0; width: 100%; height: 100%;"
+  xmlns="http://www.w3.org/2000/svg"
+  preserveAspectRatio={preserveAspectRatio}
+>
+  <slot />
+</svg>
+
+<script define:vars={{ nodeId, serializable }}>
+  import { initFrameLinesElement } from '../client/frameClient.js';
+
+  const element = document.getElementById(nodeId);
+  if (element instanceof SVGSVGElement) {
+    initFrameLinesElement(element, serializable);
+  }
+</script>

package/src/FrameLines/FrameLines.test.ts

@@ -0,0 +1,15 @@
+// @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 FrameLines from './FrameLines.astro';
+
+test('Should render the frame lines shell', async () => {
+  const html = await renderComponent(FrameLines, {
+    props: { smallLineLength: 8 },
+  });
+
+  expect(html).toContain('data-elyndra-frame-lines');
+  expect(html).toContain('initFrameLinesElement');
+});

package/src/FrameNefrex/FrameNefrex.astro

@@ -0,0 +1,33 @@
+---
+import type { FrameNefrexElementProps } from '../types.js';
+
+interface Props extends FrameNefrexElementProps {}
+
+const { className, preserveAspectRatio = 'none', ...settings } = Astro.props as Props;
+
+// Ids only need page-level uniqueness: the component script consumes them in
+// the same render.
+const nodeId = `elyndra-frame-nefrex-${Math.random().toString(36).slice(2)}`;
+const serializable = { ...settings };
+---
+
+<svg
+  id={nodeId}
+  data-elyndra-frame-nefrex
+  role="presentation"
+  class={className}
+  style="position: absolute; inset: 0; display: block; border: 0; margin: 0; padding: 0; width: 100%; height: 100%;"
+  xmlns="http://www.w3.org/2000/svg"
+  preserveAspectRatio={preserveAspectRatio}
+>
+  <slot />
+</svg>
+
+<script define:vars={{ nodeId, serializable }}>
+  import { initFrameNefrexElement } from '../client/frameClient.js';
+
+  const element = document.getElementById(nodeId);
+  if (element instanceof SVGSVGElement) {
+    initFrameNefrexElement(element, serializable);
+  }
+</script>

package/src/FrameNefrex/FrameNefrex.test.ts

@@ -0,0 +1,15 @@
+// @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 FrameNefrex from './FrameNefrex.astro';
+
+test('Should render the frame nefrex shell', async () => {
+  const html = await renderComponent(FrameNefrex, {
+    props: { leftTop: false },
+  });
+
+  expect(html).toContain('data-elyndra-frame-nefrex');
+  expect(html).toContain('initFrameNefrexElement');
+});

package/src/FrameNero/FrameNero.astro

@@ -0,0 +1,33 @@
+---
+import type { FrameNeroElementProps } from '../types.js';
+
+interface Props extends FrameNeroElementProps {}
+
+const { className, preserveAspectRatio = 'none', ...settings } = Astro.props as Props;
+
+// Ids only need page-level uniqueness: the component script consumes them in
+// the same render.
+const nodeId = `elyndra-frame-nero-${Math.random().toString(36).slice(2)}`;
+const serializable = { ...settings };
+---
+
+<svg
+  id={nodeId}
+  data-elyndra-frame-nero
+  role="presentation"
+  class={className}
+  style="position: absolute; inset: 0; display: block; border: 0; margin: 0; padding: 0; width: 100%; height: 100%;"
+  xmlns="http://www.w3.org/2000/svg"
+  preserveAspectRatio={preserveAspectRatio}
+>
+  <slot />
+</svg>
+
+<script define:vars={{ nodeId, serializable }}>
+  import { initFrameNeroElement } from '../client/frameClient.js';
+
+  const element = document.getElementById(nodeId);
+  if (element instanceof SVGSVGElement) {
+    initFrameNeroElement(element, serializable);
+  }
+</script>

package/src/FrameNero/FrameNero.test.ts

@@ -0,0 +1,15 @@
+// @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 FrameNero from './FrameNero.astro';
+
+test('Should render the frame nero shell', async () => {
+  const html = await renderComponent(FrameNero, {
+    props: { cornerLength: 8 },
+  });
+
+  expect(html).toContain('data-elyndra-frame-nero');
+  expect(html).toContain('initFrameNeroElement');
+});

package/src/FrameOctagon/FrameOctagon.astro

@@ -0,0 +1,33 @@
+---
+import type { FrameOctagonElementProps } from '../types.js';
+
+interface Props extends FrameOctagonElementProps {}
+
+const { className, preserveAspectRatio = 'none', ...settings } = Astro.props as Props;
+
+// Ids only need page-level uniqueness: the component script consumes them in
+// the same render.
+const nodeId = `elyndra-frame-octagon-${Math.random().toString(36).slice(2)}`;
+const serializable = { ...settings };
+---
+
+<svg
+  id={nodeId}
+  data-elyndra-frame-octagon
+  role="presentation"
+  class={className}
+  style="position: absolute; inset: 0; display: block; border: 0; margin: 0; padding: 0; width: 100%; height: 100%;"
+  xmlns="http://www.w3.org/2000/svg"
+  preserveAspectRatio={preserveAspectRatio}
+>
+  <slot />
+</svg>
+
+<script define:vars={{ nodeId, serializable }}>
+  import { initFrameOctagonElement } from '../client/frameClient.js';
+
+  const element = document.getElementById(nodeId);
+  if (element instanceof SVGSVGElement) {
+    initFrameOctagonElement(element, serializable);
+  }
+</script>

package/src/FrameOctagon/FrameOctagon.test.ts

@@ -0,0 +1,15 @@
+// @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 FrameOctagon from './FrameOctagon.astro';
+
+test('Should render the frame octagon shell', async () => {
+  const html = await renderComponent(FrameOctagon, {
+    props: { squareSize: 8 },
+  });
+
+  expect(html).toContain('data-elyndra-frame-octagon');
+  expect(html).toContain('initFrameOctagonElement');
+});

package/src/FrameUnderline/FrameUnderline.astro

@@ -0,0 +1,33 @@
+---
+import type { FrameUnderlineElementProps } from '../types.js';
+
+interface Props extends FrameUnderlineElementProps {}
+
+const { className, preserveAspectRatio = 'none', ...settings } = Astro.props as Props;
+
+// Ids only need page-level uniqueness: the component script consumes them in
+// the same render.
+const nodeId = `elyndra-frame-underline-${Math.random().toString(36).slice(2)}`;
+const serializable = { ...settings };
+---
+
+<svg
+  id={nodeId}
+  data-elyndra-frame-underline
+  role="presentation"
+  class={className}
+  style="position: absolute; inset: 0; display: block; border: 0; margin: 0; padding: 0; width: 100%; height: 100%;"
+  xmlns="http://www.w3.org/2000/svg"
+  preserveAspectRatio={preserveAspectRatio}
+>
+  <slot />
+</svg>
+
+<script define:vars={{ nodeId, serializable }}>
+  import { initFrameUnderlineElement } from '../client/frameClient.js';
+
+  const element = document.getElementById(nodeId);
+  if (element instanceof SVGSVGElement) {
+    initFrameUnderlineElement(element, serializable);
+  }
+</script>

package/src/FrameUnderline/FrameUnderline.test.ts

@@ -0,0 +1,15 @@
+// @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 FrameUnderline from './FrameUnderline.astro';
+
+test('Should render the frame underline shell', async () => {
+  const html = await renderComponent(FrameUnderline, {
+    props: { strokeWidth: 2 },
+  });
+
+  expect(html).toContain('data-elyndra-frame-underline');
+  expect(html).toContain('initFrameUnderlineElement');
+});

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

@@ -0,0 +1,92 @@
+import { beforeEach, expect, test, vi } from 'vitest';
+import {
+  initFrameAssemblerElement,
+  initFrameBaseElement,
+  initFrameCircleElement,
+  initFrameCornersElement,
+  initFrameHeaderElement,
+  initFrameKranoxElement,
+  initFrameLinesElement,
+  initFrameNefrexElement,
+  initFrameNeroElement,
+  initFrameOctagonElement,
+  initFrameUnderlineElement,
+} from './frameClient.js';
+
+const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+  vi.unstubAllGlobals();
+  // jsdom has no ResizeObserver: the vanilla frame observes resizes, so the
+  // tests stub the constructor (observe/disconnect no-ops).
+  vi.stubGlobal(
+    'ResizeObserver',
+    class {
+      observe(): void {}
+      disconnect(): void {}
+    },
+  );
+});
+
+const mountSVG = (): SVGSVGElement => {
+  const element = document.createElementNS(SVG_NAMESPACE, 'svg');
+  document.body.appendChild(element);
+  return element;
+};
+
+test('Should render a static base frame and mark the node', () => {
+  const element = mountSVG();
+
+  const handle = initFrameBaseElement(element, { elements: [] });
+
+  expect(element.hasAttribute('data-elyndra-frame-node')).toBe(true);
+  expect(element.querySelector('[data-frame]')).not.toBeNull();
+
+  handle.dispose();
+  handle.dispose();
+
+  expect(element.hasAttribute('data-elyndra-frame-node')).toBe(false);
+});
+
+test('Should render every named frame statically and unmark on dispose', () => {
+  const inits = [
+    () => initFrameCircleElement(mountSVG(), { animated: false }),
+    () => initFrameCornersElement(mountSVG(), { animated: false }),
+    () => initFrameHeaderElement(mountSVG(), { animated: false }),
+    () => initFrameKranoxElement(mountSVG(), { animated: false }),
+    () => initFrameLinesElement(mountSVG(), { animated: false }),
+    () => initFrameNefrexElement(mountSVG(), { animated: false }),
+    () => initFrameNeroElement(mountSVG(), { animated: false }),
+    () => initFrameOctagonElement(mountSVG(), { animated: false }),
+    () => initFrameUnderlineElement(mountSVG(), { animated: false }),
+  ];
+
+  for (const init of inits) {
+    const handle = init();
+    const svg = document.body.lastElementChild;
+    expect(svg?.hasAttribute('data-elyndra-frame-node')).toBe(true);
+    handle.dispose();
+    expect(svg?.hasAttribute('data-elyndra-frame-node')).toBe(false);
+  }
+});
+
+test('Should dispose the previous frame on second init', () => {
+  const element = mountSVG();
+
+  initFrameCircleElement(element, { animated: false });
+  initFrameCircleElement(element, { animated: false });
+
+  expect(element.hasAttribute('data-elyndra-frame-node')).toBe(true);
+});
+
+test('Should run one assembly and cancel on dispose', () => {
+  const element = mountSVG();
+
+  const handle = initFrameAssemblerElement(element, { duration: 0.05, isEntering: true });
+
+  handle.dispose();
+  handle.dispose();
+
+  expect(element.hasAttribute('data-elyndra-frame-node')).toBe(false);
+});

package/src/client/frameClient.ts

@@ -0,0 +1,186 @@
+import {
+  type Frame,
+  animateFrameAssembler,
+  createFrame,
+  createFrameCircleSettings,
+  createFrameCornersSettings,
+  createFrameHeaderSettings,
+  createFrameKranoxSettings,
+  createFrameLinesSettings,
+  createFrameNefrexSettings,
+  createFrameNeroSettings,
+  createFrameOctagonSettings,
+  createFrameUnderlineSettings,
+} from '@elyndra/frames';
+import { filterProps } from '@elyndra/tools';
+import type {
+  FrameAssemblerSerializableSettings,
+  FrameBaseSerializableSettings,
+  FrameCircleSerializableSettings,
+  FrameCornersSerializableSettings,
+  FrameHeaderSerializableSettings,
+  FrameKranoxSerializableSettings,
+  FrameLinesSerializableSettings,
+  FrameNefrexSerializableSettings,
+  FrameNeroSerializableSettings,
+  FrameOctagonSerializableSettings,
+  FrameUnderlineSerializableSettings,
+} from '../types.js';
+
+const FRAME_NODE_MARKER = 'data-elyndra-frame-node';
+
+interface FrameHandle {
+  readonly frame: Frame;
+  readonly dispose: () => void;
+}
+
+interface FrameAssemblerHandle {
+  readonly dispose: () => void;
+}
+
+const framesByElement = new WeakMap<Element, { dispose: () => void }>();
+
+const initFrameElement = (element: SVGSVGElement, create: () => Frame): FrameHandle => {
+  framesByElement.get(element)?.dispose();
+
+  const frame = create();
+
+  element.setAttribute(FRAME_NODE_MARKER, '');
+
+  const handle: FrameHandle = {
+    frame,
+    dispose: () => {
+      if (framesByElement.get(element) !== handle) {
+        return;
+      }
+      framesByElement.delete(element);
+      element.removeAttribute(FRAME_NODE_MARKER);
+      frame.remove();
+    },
+  };
+
+  framesByElement.set(element, handle);
+
+  return handle;
+};
+
+/**
+ * Hydrates one base frame: the shell `<svg>` itself is the vanilla target,
+ * islands run standalone (no animator join). Idempotent: re-running removes
+ * the previous frame first.
+ */
+const initFrameBaseElement = (
+  element: SVGSVGElement,
+  props: FrameBaseSerializableSettings,
+): FrameHandle =>
+  initFrameElement(element, () =>
+    createFrame(element, {
+      elements: props.elements ?? [],
+      ...filterProps({ contexts: props.contexts }),
+    }),
+  );
+
+const initFrameCircleElement = (
+  element: SVGSVGElement,
+  props: FrameCircleSerializableSettings,
+): FrameHandle =>
+  initFrameElement(element, () => createFrame(element, createFrameCircleSettings(filterProps(props))));
+
+const initFrameCornersElement = (
+  element: SVGSVGElement,
+  props: FrameCornersSerializableSettings,
+): FrameHandle =>
+  initFrameElement(element, () => createFrame(element, createFrameCornersSettings(filterProps(props))));
+
+const initFrameHeaderElement = (
+  element: SVGSVGElement,
+  props: FrameHeaderSerializableSettings,
+): FrameHandle =>
+  initFrameElement(element, () => createFrame(element, createFrameHeaderSettings(filterProps(props))));
+
+const initFrameKranoxElement = (
+  element: SVGSVGElement,
+  props: FrameKranoxSerializableSettings,
+): FrameHandle =>
+  initFrameElement(element, () => createFrame(element, createFrameKranoxSettings(filterProps(props))));
+
+const initFrameLinesElement = (
+  element: SVGSVGElement,
+  props: FrameLinesSerializableSettings,
+): FrameHandle =>
+  initFrameElement(element, () => createFrame(element, createFrameLinesSettings(filterProps(props))));
+
+const initFrameNefrexElement = (
+  element: SVGSVGElement,
+  props: FrameNefrexSerializableSettings,
+): FrameHandle =>
+  initFrameElement(element, () => createFrame(element, createFrameNefrexSettings(filterProps(props))));
+
+const initFrameNeroElement = (
+  element: SVGSVGElement,
+  props: FrameNeroSerializableSettings,
+): FrameHandle =>
+  initFrameElement(element, () => createFrame(element, createFrameNeroSettings(filterProps(props))));
+
+const initFrameOctagonElement = (
+  element: SVGSVGElement,
+  props: FrameOctagonSerializableSettings,
+): FrameHandle =>
+  initFrameElement(element, () => createFrame(element, createFrameOctagonSettings(filterProps(props))));
+
+const initFrameUnderlineElement = (
+  element: SVGSVGElement,
+  props: FrameUnderlineSerializableSettings,
+): FrameHandle =>
+  initFrameElement(element, () =>
+    createFrame(element, createFrameUnderlineSettings(filterProps(props))),
+  );
+
+/**
+ * Runs one frame assembly on an element (the island replacement for the
+ * `useFrameAssembler` hook: a single run instead of an animator
+ * subscription). Idempotent: re-running cancels the previous assembly
+ * first.
+ */
+const initFrameAssemblerElement = (
+  element: HTMLElement | SVGElement,
+  props: FrameAssemblerSerializableSettings,
+): FrameAssemblerHandle => {
+  framesByElement.get(element)?.dispose();
+
+  const animation = animateFrameAssembler({
+    element,
+    duration: props.duration ?? 0.3,
+    isEntering: props.isEntering ?? true,
+  });
+
+  const handle: FrameAssemblerHandle = {
+    dispose: () => {
+      if (framesByElement.get(element) !== handle) {
+        return;
+      }
+      framesByElement.delete(element);
+      animation.cancel();
+    },
+  };
+
+  framesByElement.set(element, handle);
+
+  return handle;
+};
+
+export {
+  FRAME_NODE_MARKER,
+  initFrameAssemblerElement,
+  initFrameBaseElement,
+  initFrameCircleElement,
+  initFrameCornersElement,
+  initFrameHeaderElement,
+  initFrameKranoxElement,
+  initFrameLinesElement,
+  initFrameNefrexElement,
+  initFrameNeroElement,
+  initFrameOctagonElement,
+  initFrameUnderlineElement,
+};
+export type { FrameAssemblerHandle, FrameHandle };

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './client/frameClient.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,100 @@
+import type {
+  CreateFrameCircleSettingsProps,
+  CreateFrameCornersSettingsProps,
+  CreateFrameHeaderSettingsProps,
+  CreateFrameKranoxSettingsProps,
+  CreateFrameLinesSettingsProps,
+  CreateFrameNefrexSettingsProps,
+  CreateFrameNeroSettingsProps,
+  CreateFrameOctagonSettingsProps,
+  CreateFrameUnderlineSettingsProps,
+  FrameSettings,
+} from '@elyndra/frames';
+
+/**
+ * Serializable subsets of the frame settings. Only JSON crosses the Astro
+ * server/client boundary (`define:vars`):
+ * - `FrameBase` takes plain `elements`/`contexts`: `draw`/`path`/context
+ *   `animate` function forms are excluded (static settings only).
+ * - Variant props (`CreateFrame*SettingsProps`) are already scalar-only.
+ * - Excluded everywhere: `animator` nodes (islands run standalone),
+ *   `container` instances (the vanilla container is created internally),
+ *   `elementRef` (the shell `<svg>` itself is hydrated), `useFrameAssembler`
+ *   (hook: use `initFrameAssemblerElement` from the client entry instead).
+ */
+interface FrameBaseSerializableSettings {
+  elements?: FrameSettings['elements'];
+  contexts?: Record<string, string>;
+}
+
+interface FrameBaseElementProps extends FrameBaseSerializableSettings {
+  className?: string;
+  preserveAspectRatio?: string;
+}
+
+interface FrameShellProps {
+  className?: string;
+  preserveAspectRatio?: string;
+}
+
+type FrameCircleSerializableSettings = CreateFrameCircleSettingsProps;
+interface FrameCircleElementProps extends FrameCircleSerializableSettings, FrameShellProps {}
+
+type FrameCornersSerializableSettings = CreateFrameCornersSettingsProps;
+interface FrameCornersElementProps extends FrameCornersSerializableSettings, FrameShellProps {}
+
+type FrameHeaderSerializableSettings = CreateFrameHeaderSettingsProps;
+interface FrameHeaderElementProps extends FrameHeaderSerializableSettings, FrameShellProps {}
+
+type FrameKranoxSerializableSettings = CreateFrameKranoxSettingsProps;
+interface FrameKranoxElementProps extends FrameKranoxSerializableSettings, FrameShellProps {}
+
+type FrameLinesSerializableSettings = CreateFrameLinesSettingsProps;
+interface FrameLinesElementProps extends FrameLinesSerializableSettings, FrameShellProps {}
+
+type FrameNefrexSerializableSettings = CreateFrameNefrexSettingsProps;
+interface FrameNefrexElementProps extends FrameNefrexSerializableSettings, FrameShellProps {}
+
+type FrameNeroSerializableSettings = CreateFrameNeroSettingsProps;
+interface FrameNeroElementProps extends FrameNeroSerializableSettings, FrameShellProps {}
+
+type FrameOctagonSerializableSettings = CreateFrameOctagonSettingsProps;
+interface FrameOctagonElementProps extends FrameOctagonSerializableSettings, FrameShellProps {}
+
+type FrameUnderlineSerializableSettings = CreateFrameUnderlineSettingsProps;
+interface FrameUnderlineElementProps extends FrameUnderlineSerializableSettings, FrameShellProps {}
+
+/**
+ * Serializable settings for the assembler runner (the island replacement
+ * for the `useFrameAssembler` hook): a single entering/exiting assembly
+ * instead of an animator subscription.
+ */
+interface FrameAssemblerSerializableSettings {
+  duration?: number;
+  isEntering?: boolean;
+}
+
+export type {
+  FrameAssemblerSerializableSettings,
+  FrameBaseElementProps,
+  FrameBaseSerializableSettings,
+  FrameCircleElementProps,
+  FrameCircleSerializableSettings,
+  FrameCornersElementProps,
+  FrameCornersSerializableSettings,
+  FrameHeaderElementProps,
+  FrameHeaderSerializableSettings,
+  FrameKranoxElementProps,
+  FrameKranoxSerializableSettings,
+  FrameLinesElementProps,
+  FrameLinesSerializableSettings,
+  FrameNefrexElementProps,
+  FrameNefrexSerializableSettings,
+  FrameNeroElementProps,
+  FrameNeroSerializableSettings,
+  FrameOctagonElementProps,
+  FrameOctagonSerializableSettings,
+  FrameShellProps,
+  FrameUnderlineElementProps,
+  FrameUnderlineSerializableSettings,
+};