@vyriy/render 0.4.7

package/AGENTS.md

@@ -0,0 +1,102 @@
+# Project Agent Guide
+
+This repository follows a calm engineering style: changes should be explicit, reusable, typed, documented, tested, and easy to reason about.
+
+Use this guide as the default behavior for AI agents and contributors working in this repository. Prefer local package conventions when they are more specific than this document.
+
+## Core Principles
+
+- Prefer simple modules over clever frameworks or hidden conventions.
+- Keep package and project boundaries explicit.
+- Avoid project-specific coupling in reusable code.
+- Extract only proven reusable behavior.
+- Keep public APIs small, typed, documented, and stable.
+- Prefer SSR-friendly and SSG-friendly code paths when working with frontend or shared code.
+- Keep integrations replaceable and avoid hard coupling to a CMS, framework, vendor, or runtime host.
+- Prefer infrastructure assumptions that are easy to deploy, observe, and replace.
+- Prefer the option that is simpler to explain, easier to evolve, and calmer to maintain.
+
+## File Shape
+
+- Prefer one exported runtime method, component, helper, or class per production file when it stays readable.
+- Prefer one matching test file per production file, for example `feature.ts` and `feature.test.ts`.
+- Use focused folders when behavior naturally splits into several related files.
+- Keep `index.ts` as a public re-export surface only. Do not place implementation logic in it.
+- Use relative import and export specifiers that match the package module style.
+- Use `.js` relative specifiers in TypeScript source for ESM/NodeNext packages.
+- Add `types.ts` when public shared types are part of the package contract.
+- Keep constants near the code that owns them unless they are shared or clarify repeated behavior.
+
+## Public Surface
+
+- Every new public export must be re-exported from the package or module public entry point.
+- Add or update public-surface tests when exports change.
+- Add JSDoc for public exports when behavior, parameters, return values, or usage expectations need explanation.
+- Avoid exporting internal helpers only to make tests easier.
+- Do not hand-maintain package `exports` maps unless the project has a real custom publishing need.
+
+## Tests
+
+- Cover public behavior and meaningful edge cases.
+- Prefer behavior-focused tests over private implementation lock-in.
+- Keep tests deterministic.
+- Avoid real network, filesystem, timers, browser, or cloud dependencies unless the behavior specifically requires them.
+- When mocking modules, install mocks before loading the module under test.
+- Use focused validation when changing behavior.
+
+Example validation commands:
+
+```bash
+yarn test
+```
+
+For workspaces, prefer the project convention, for example:
+
+```bash
+yarn workspace <package-name> test
+```
+
+For Jest-based packages, focused validation may look like:
+
+```bash
+yarn jest packages/<package> --runInBand --coverage=false
+```
+
+## Documentation
+
+- Keep `README.md` concise and usage-oriented.
+- Start package READMEs with `# <package>`.
+- Document real public exports, supported options, and examples that actually work.
+- Update docs when public behavior changes.
+- Keep generated docs wrappers, such as `doc.mdx`, aligned with the README when the project uses them.
+- For component packages, include visual documentation or stories for supported states and common usage.
+
+## Components
+
+- Prefer lightweight React components with TypeScript when working in React packages.
+- Keep components SSR-friendly and avoid browser globals during render.
+- Prefer composable props and predictable ergonomics.
+- Put each public component in its own file with a matching test.
+- Add stories or examples when a component has visual states, variants, or interaction states.
+- Keep styling explicit and reusable. Avoid hidden theme assumptions unless they are part of the package contract.
+
+## Change Discipline
+
+- Keep changes scoped to the requested behavior.
+- Avoid unrelated refactors and metadata churn.
+- Sync implementation, tests, docs, examples, and public re-exports together.
+- Do not introduce new dependencies unless they clearly reduce complexity or are already part of the project direction.
+- Prefer small, reviewable changes over broad rewrites.
+- Preserve existing conventions unless there is a clear reason to change them.
+
+## Before Finishing
+
+Check that the change is complete:
+
+- Public exports are updated.
+- Public-surface tests are updated when exports change.
+- Matching unit tests exist for new behavior.
+- README examples still match the real API.
+- Visual docs, stories, or examples are updated for visible component behavior.
+- TypeScript imports follow the package module style.
+- No unrelated files, formatting churn, or generated artifacts were changed.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vyriy contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# @vyriy/render
+
+Small explicit React rendering adapters for browser DOM rendering, hydration, custom elements, SSR, streaming SSR, and static generation.
+
+`@vyriy/render` is not a framework. It wraps official React rendering APIs into small predictable helpers that are easy to use in Vyriy-style applications, MFEs, SSR pages, SSG pipelines, and custom elements.
+
+## Install
+
+With npm:
+
+```bash
+npm install @vyriy/render
+```
+
+With Yarn:
+
+```bash
+yarn add @vyriy/render
+```
+
+## API
+
+| API             | Purpose                                                           |
+| --------------- | ----------------------------------------------------------------- |
+| `element`       | Render or hydrate a React component into an existing DOM element. |
+| `customElement` | Register a custom element that renders a React component.         |
+| `html`          | Render a React component to an HTML string.                       |
+| `stream`        | Render a React component to a Web `ReadableStream`.               |
+| `prerender`     | Prerender a React component for static generation.                |
+
+Hydration auto-detection uses a `rendered` marker attribute by default.
+
+## Browser rendering
+
+```tsx
+import { element } from '@vyriy/render';
+
+import { App } from './app.js';
+
+element({
+  root: document.getElementById('root'),
+  component: <App />,
+});
+```
+
+## Browser hydration
+
+```tsx
+import { element } from '@vyriy/render';
+
+import { App } from './app.js';
+
+element({
+  root: document.getElementById('root'),
+  component: <App />,
+});
+```
+
+Server markup:
+
+```html
+<div id="root" rendered></div>
+```
+
+## Custom element
+
+```tsx
+import { customElement } from '@vyriy/render';
+
+import { ProfileCard } from './profile-card.js';
+
+customElement({
+  tag: 'vyriy-profile-card',
+  elements: () => {
+    const styles = document.createElement('style');
+    const container = document.createElement('div');
+
+    styles.textContent = '.profile-card { display: block; }';
+
+    return {
+      elements: [styles, container],
+      root: container,
+    };
+  },
+  render: (customElement) => {
+    return <ProfileCard name={customElement.getAttribute('name') ?? ''} />;
+  },
+});
+```
+
+## HTML string
+
+```tsx
+import { html } from '@vyriy/render';
+
+import { App } from './app.js';
+
+const body = html(<App />);
+```
+
+## Stream
+
+```tsx
+import { stream } from '@vyriy/render';
+
+import { App } from './app.js';
+
+const htmlStream = await stream({
+  component: <App />,
+  bootstrapScripts: ['/assets/app.js'],
+});
+```
+
+## Rrerender
+
+```tsx
+import { prerender } from '@vyriy/render';
+
+import { App } from './app.js';
+
+const result = await prerender({
+  component: <App />,
+  bootstrapScripts: ['/assets/app.js'],
+});
+```
+
+## Non-goals
+
+This package intentionally does not provide routing, data loading, bundling, CSS handling, asset manifest loading, or application framework behavior.

package/custom-element.d.ts

@@ -0,0 +1,2 @@
+import type { CustomElementOptions } from './types.js';
+export declare const customElement: ({ tag, mode, renderedAttribute, elements, render, options, }: CustomElementOptions) => void;

package/custom-element.js

@@ -0,0 +1,34 @@
+import { createRoot, hydrateRoot } from 'react-dom/client';
+import { createMissingCustomElementRootError } from './errors.js';
+export const customElement = ({ tag, mode = 'open', renderedAttribute = 'rendered', elements, render, options = {}, }) => {
+    if (customElements.get(tag)) {
+        return;
+    }
+    customElements.define(tag, class extends HTMLElement {
+        #root;
+        #mount;
+        constructor() {
+            super();
+            const shadow = this.attachShadow({ mode });
+            const renderElements = elements(this);
+            if (!renderElements.root) {
+                throw createMissingCustomElementRootError();
+            }
+            this.#mount = renderElements.root;
+            shadow.append(...renderElements.elements);
+        }
+        connectedCallback() {
+            const reactNode = render(this);
+            if (this.hasAttribute(renderedAttribute)) {
+                this.#root = hydrateRoot(this.#mount, reactNode, options);
+                return;
+            }
+            this.#root ??= createRoot(this.#mount, options);
+            this.#root.render(reactNode);
+        }
+        disconnectedCallback() {
+            this.#root?.unmount();
+            this.#root = undefined;
+        }
+    });
+};

package/element.d.ts

@@ -0,0 +1,2 @@
+import type { ElementOptions, ElementResult } from './types.js';
+export declare const element: ({ root, component, renderedAttribute, options, }: ElementOptions) => ElementResult;

package/element.js

@@ -0,0 +1,18 @@
+import { createRoot, hydrateRoot } from 'react-dom/client';
+import { createMissingElementError } from './errors.js';
+export const element = ({ root, component, renderedAttribute = 'rendered', options = {}, }) => {
+    if (!root) {
+        throw createMissingElementError();
+    }
+    const shouldHydrate = root.hasAttribute(renderedAttribute);
+    const reactRoot = shouldHydrate ? hydrateRoot(root, component, options) : createRoot(root, options);
+    if (!shouldHydrate) {
+        reactRoot.render(component);
+    }
+    return {
+        root: reactRoot,
+        unmount: () => {
+            reactRoot.unmount();
+        },
+    };
+};

package/errors.d.ts

@@ -0,0 +1,2 @@
+export declare const createMissingElementError: () => Error;
+export declare const createMissingCustomElementRootError: () => Error;

package/errors.js

@@ -0,0 +1,6 @@
+export const createMissingElementError = () => {
+    return new Error('Render element is required.');
+};
+export const createMissingCustomElementRootError = () => {
+    return new Error('Custom element render root is required.');
+};

package/html.d.ts

@@ -0,0 +1,2 @@
+import type { Html } from './types.js';
+export declare const html: Html;

package/html.js

@@ -0,0 +1,2 @@
+import { renderToString } from 'react-dom/server';
+export const html = (component) => renderToString(component);

package/index.d.ts

@@ -0,0 +1,6 @@
+export * from './custom-element.js';
+export * from './element.js';
+export * from './html.js';
+export * from './prerender.js';
+export * from './stream.js';
+export type * from './types.js';

package/index.js

@@ -0,0 +1,5 @@
+export * from './custom-element.js';
+export * from './element.js';
+export * from './html.js';
+export * from './prerender.js';
+export * from './stream.js';

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@vyriy/render",
+  "version": "0.4.7",
+  "description": "React rendering adapters for Vyriy projects",
+  "type": "module",
+  "dependencies": {
+    "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6"
+  },
+  "agents": "./AGENTS.md",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/evheniy/vyriy",
+    "directory": "packages/render"
+  },
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./custom-element": {
+      "types": "./custom-element.d.ts",
+      "import": "./custom-element.js",
+      "default": "./custom-element.js"
+    },
+    "./custom-element.js": {
+      "types": "./custom-element.d.ts",
+      "import": "./custom-element.js",
+      "default": "./custom-element.js"
+    },
+    "./element": {
+      "types": "./element.d.ts",
+      "import": "./element.js",
+      "default": "./element.js"
+    },
+    "./element.js": {
+      "types": "./element.d.ts",
+      "import": "./element.js",
+      "default": "./element.js"
+    },
+    "./errors": {
+      "types": "./errors.d.ts",
+      "import": "./errors.js",
+      "default": "./errors.js"
+    },
+    "./errors.js": {
+      "types": "./errors.d.ts",
+      "import": "./errors.js",
+      "default": "./errors.js"
+    },
+    "./html": {
+      "types": "./html.d.ts",
+      "import": "./html.js",
+      "default": "./html.js"
+    },
+    "./html.js": {
+      "types": "./html.d.ts",
+      "import": "./html.js",
+      "default": "./html.js"
+    },
+    "./index": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./index.js": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./prerender": {
+      "types": "./prerender.d.ts",
+      "import": "./prerender.js",
+      "default": "./prerender.js"
+    },
+    "./prerender.js": {
+      "types": "./prerender.d.ts",
+      "import": "./prerender.js",
+      "default": "./prerender.js"
+    },
+    "./stream": {
+      "types": "./stream.d.ts",
+      "import": "./stream.js",
+      "default": "./stream.js"
+    },
+    "./stream.js": {
+      "types": "./stream.d.ts",
+      "import": "./stream.js",
+      "default": "./stream.js"
+    }
+  }
+}

package/prerender.d.ts

@@ -0,0 +1,3 @@
+import type { PrerenderOptions } from './types.js';
+declare const prerender: ({ component, bootstrapScripts }: PrerenderOptions) => Promise<import("react-dom/static").PrerenderToNodeStreamResult>;
+export { prerender };

package/prerender.js

@@ -0,0 +1,7 @@
+import { prerenderToNodeStream } from 'react-dom/static';
+const prerender = async ({ component, bootstrapScripts }) => {
+    return prerenderToNodeStream(component, {
+        bootstrapScripts,
+    });
+};
+export { prerender };

package/stream.d.ts

@@ -0,0 +1,2 @@
+import type { StreamOptions } from './types.js';
+export declare const stream: ({ component, bootstrapScripts }: StreamOptions) => Promise<ReadableStream<Uint8Array>>;

package/stream.js

@@ -0,0 +1,6 @@
+import { renderToReadableStream } from 'react-dom/server';
+export const stream = async ({ component, bootstrapScripts }) => {
+    return renderToReadableStream(component, {
+        bootstrapScripts,
+    });
+};

package/types.d.ts

@@ -0,0 +1,33 @@
+import type { ReactNode } from 'react';
+import type { Root, RootOptions } from 'react-dom/client';
+export type ElementOptions = {
+    root: Element | null;
+    component: ReactNode;
+    renderedAttribute?: string;
+    options?: RootOptions;
+};
+export type ElementResult = {
+    root: Root;
+    unmount: () => void;
+};
+export type CustomElementRenderElements = {
+    elements: readonly Node[];
+    root: Element | null;
+};
+export type CustomElementOptions = {
+    tag: string;
+    mode?: ShadowRootMode;
+    renderedAttribute?: string;
+    elements: (customElement: HTMLElement) => CustomElementRenderElements;
+    render: (customElement: HTMLElement) => ReactNode;
+    options?: RootOptions;
+};
+export type Html = (component: ReactNode) => string;
+export type StreamOptions = {
+    component: ReactNode;
+    bootstrapScripts?: string[];
+};
+export type PrerenderOptions = {
+    component: ReactNode;
+    bootstrapScripts?: string[];
+};