@uniweb/scene 0.1.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,126 @@
+# @uniweb/scene
+
+A React renderer for the **Scene Composition Format** — declarative, layered
+visual scenes composited with CSS blend modes.
+
+> **Status:** initial setup. The renderer implementation is being brought in from
+> its reference implementation; the API below is the shape it lands with.
+
+## What is a scene?
+
+A *scene* is a portable JSON description of a layered visual. Each layer is one of
+a handful of kinds — **text**, **subject** (image), **shape**, **spray**,
+**accent**, **svg**, **separator** — positioned in a shared z-index space and
+composited through CSS `mix-blend-mode`. There's no canvas-2D or WebGL: every
+layer is a positioned DOM element, so scenes are light, themeable, and
+server-renderable.
+
+```json
+{
+  "name": "Hero",
+  "composition": {
+    "aspectRatio": "16 / 9",
+    "background": "#0b0b12",
+    "texts":  [{ "id": "title", "content": "Into the\nUnknown", "vAlign": "center" }],
+    "shapes": [{ "type": "circle", "background": "radial-gradient(circle, #ff0066, transparent)",
+                 "width": "240px", "height": "240px", "top": "20%", "left": "60%",
+                 "mixBlendMode": "screen", "filter": "blur(10px)" }]
+  }
+}
+```
+
+## Install
+
+```bash
+npm install @uniweb/scene react
+```
+
+`react` (>= 18) is a peer dependency. The package has no other runtime
+dependencies.
+
+## Usage
+
+```jsx
+import { Scene } from '@uniweb/scene'
+import doc from './hero.scene.json'
+
+// Contained — fills its parent.
+<div style={{ width: 800 }}>
+  <Scene composition={doc} />
+</div>
+```
+
+`composition` accepts either the full envelope (`{ name, composition }`) or a bare
+composition object.
+
+### Templating
+
+`composeScene` is a pure, SSR-safe helper that applies named-slot **overrides**
+and an ordered **content** stream to a template scene, then hands the result to
+`<Scene>`:
+
+```jsx
+import { Scene, composeScene } from '@uniweb/scene'
+
+const final = composeScene(template, {
+  overrides: { title: { content: 'Article Title' } },
+  content:   [{ kind: 'text', content: 'By Jane Doe' }]
+})
+
+<Scene composition={final} />
+```
+
+### Theming with CSS variables
+
+Every default colour and font reads a `--vc-*` custom property, with a sensible
+literal as the fallback. An explicit value in the scene JSON always wins — only
+the *default* is themeable. Set the variables once on a wrapper and an otherwise
+unstyled scene adopts your tokens:
+
+| Variable | Themes the default… | Fallback |
+| --- | --- | --- |
+| `--vc-text` | text colour | `currentColor` |
+| `--vc-font` | text `font-family` | `inherit` |
+| `--vc-shape` | shape background + ring stroke | `#ffffff` |
+| `--vc-accent` | spray fill + accent fill | `#ff3300` |
+| `--vc-separator` | separator rule/label colour | `currentColor` |
+
+Because text colour falls back to `currentColor` and font to `inherit`, an
+unstyled scene simply adopts the surrounding element's colour and font.
+
+### Server-side rendering
+
+`<Scene>` renders to static HTML and hydrates cleanly — no `useLayoutEffect`, no
+DOM access at module scope. Responsive behaviour is **container-queried** via
+`ResizeObserver` at runtime. For pre-rendering at a known width, pass
+`initialWidth` (a number of CSS pixels) so the first paint matches the
+post-hydration layout:
+
+```jsx
+<Scene composition={doc} initialWidth={360} />
+```
+
+### Untrusted SVG
+
+`svg` layers render inline markup. If a scene can come from an untrusted source,
+pass a sanitizer — the host owns the policy:
+
+```jsx
+<Scene composition={doc} sanitizeSvg={(html) => mySanitizer(html)} />
+```
+
+## Exports
+
+| Export | Description |
+| --- | --- |
+| `Scene` | The renderer component (also the default export). |
+| `composeScene` | Pure templating helper (overrides + content binding). |
+| scene/layer helpers | Pure scene-normalisation and per-layer style utilities. |
+
+`<Scene>` also accepts optional pointer hooks (`onLayerPointerDown`,
+`selectedId`, `draggedId`, `tempPos`) for building an interactive editor on top
+of the renderer; without them it is fully inert (`pointer-events: none`).
+
+## License
+
+Apache-2.0. Derived from a reference renderer for the Scene Composition Format.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@uniweb/scene",
+  "version": "0.1.1",
+  "description": "React renderer for the Scene Composition Format — layered visual scenes composited with CSS blend modes",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "keywords": [
+    "uniweb",
+    "scene",
+    "composition",
+    "renderer",
+    "blend-mode",
+    "react",
+    "visual"
+  ],
+  "author": "Uniweb",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uniweb/scene.git"
+  },
+  "bugs": {
+    "url": "https://github.com/uniweb/scene/issues"
+  },
+  "homepage": "https://github.com/uniweb/scene#readme"
+}

package/src/Scene.jsx

@@ -0,0 +1,313 @@
+import { useRef, useState, useEffect, useMemo } from 'react'
+import {
+  VC_KEYFRAMES,
+  DEFAULT_MOBILE_BREAKPOINT,
+  flattenLayers,
+  isLayerHidden,
+  commonStyle,
+  shapeStyle,
+  subjectStyle,
+  sprayStyle,
+  accentContainerStyle,
+  svgStyle,
+  textStyle,
+  separatorStyle,
+  buildSvgHtml
+} from './layers.js'
+
+const SELECTION_OUTLINE = '2px dashed #818cf8'
+
+/**
+ * Renders a Scene. Presentational by default — pass a composition
+ * (either the full `.scene.json` envelope or a bare composition object)
+ * and it draws the layered, blend-mode-composited scene with zero host setup.
+ *
+ * To drive an editor, pass the optional editing hooks: `onLayerPointerDown`
+ * turns layers into pointer targets, `selectedId` draws a selection outline,
+ * and `draggedId` + `tempPos` apply a live drag position. When `onLayerPointerDown`
+ * is omitted the renderer is fully inert (`pointer-events: none`).
+ *
+ * Responsive visibility is container-queried via `ResizeObserver`. For SSR /
+ * pre-rendering, pass `initialWidth` (the known container width) so the first
+ * paint matches the post-hydration layout and avoids a desktop→mobile flash.
+ *
+ * `sanitizeSvg(html) => html` runs author-supplied SVG markup through the
+ * host's sanitizer before injection (default: identity). `injectKeyframes`
+ * (default `true`) can be set false when the host ships `VC_KEYFRAMES` in its
+ * own bundled CSS. Default colors/fonts read `--vc-*` custom properties (see
+ * README) so a wrapper can theme an otherwise-unstyled composition.
+ */
+export function Scene({
+  composition,
+  mobileBreakpoint = DEFAULT_MOBILE_BREAKPOINT,
+  initialWidth = 1000,
+  className,
+  style,
+  sanitizeSvg = null,
+  injectKeyframes = true,
+  selectedId = null,
+  onLayerPointerDown = null,
+  draggedId = null,
+  tempPos = null
+}) {
+  const comp = composition?.composition || composition || {}
+  const interactive = typeof onLayerPointerDown === 'function'
+
+  const containerRef = useRef(null)
+  // `initialWidth` seeds the first render (server + client hydration) before the
+  // ResizeObserver measures the real width. Server HTML and the client's first
+  // render use the same value, so hydration matches; the real width is applied
+  // afterwards. Pass the known width when pre-rendering to avoid a layout flash.
+  const [containerWidth, setContainerWidth] = useState(initialWidth)
+
+  // Container-query the width so responsive behavior tracks the element, not
+  // the viewport.
+  useEffect(() => {
+    if (!containerRef.current) return
+    const obs = new ResizeObserver((entries) => {
+      setContainerWidth(entries[0].contentRect.width)
+    })
+    obs.observe(containerRef.current)
+    return () => obs.disconnect()
+  }, [])
+
+  const layers = useMemo(() => flattenLayers(comp), [comp])
+
+  // Interaction-only style overlay (selection outline, grab cursor, live drag
+  // position). Empty in presentational mode.
+  const editStyle = (layer) => {
+    if (!interactive) return { pointerEvents: 'none' }
+    const s = { pointerEvents: 'auto' }
+    if (selectedId === layer.id) {
+      s.outline = SELECTION_OUTLINE
+      s.outlineOffset = '2px'
+      s.cursor = draggedId === layer.id ? 'grabbing' : 'grab'
+    }
+    if (draggedId === layer.id && tempPos) {
+      s.left = tempPos.left
+      s.top = tempPos.top
+    }
+    return s
+  }
+
+  const handlers = (layer) =>
+    interactive ? { onMouseDown: (e) => onLayerPointerDown(e, layer) } : {}
+
+  const renderAccent = (accent) => {
+    const filterId = `vc-accent-${accent.id}`
+    const intensity = accent.intensity || 0.015
+    const numOctaves = accent.numOctaves || 2
+    const spread = accent.spread || 40
+    const blobs = accent.blobs || []
+    const blurStd =
+      accent.variant === 'mist' ? 5 : accent.variant === 'cloud' ? 8 : 1
+
+    const containerStyle = accentContainerStyle(accent)
+    if (interactive && selectedId === accent.id) {
+      containerStyle.outline = SELECTION_OUTLINE
+      containerStyle.outlineOffset = '-2px'
+    }
+
+    return (
+      <div key={accent.id} style={containerStyle}>
+        <svg
+          width="100%"
+          height="100%"
+          viewBox="0 0 160 90"
+          preserveAspectRatio="xMidYMid slice"
+        >
+          <defs>
+            <filter id={filterId} colorInterpolationFilters="sRGB">
+              <feTurbulence
+                type="fractalNoise"
+                baseFrequency={intensity}
+                numOctaves={numOctaves}
+                seed={accent.seed || 1}
+                result="noise"
+              />
+              <feDisplacementMap
+                in="SourceGraphic"
+                in2="noise"
+                scale={spread}
+                xChannelSelector="R"
+                yChannelSelector="G"
+              />
+              <feGaussianBlur stdDeviation={blurStd} />
+            </filter>
+          </defs>
+          <g filter={`url(#${filterId})`}>
+            {blobs.map((blob, i) => {
+              const b = Array.isArray(blob)
+                ? {
+                    cx: blob[0],
+                    cy: blob[1],
+                    rx: blob[2],
+                    ry: blob[3],
+                    color: blob[4],
+                    opacity: blob[5]
+                  }
+                : blob
+              return (
+                <ellipse
+                  key={i}
+                  cx={b.cx}
+                  cy={b.cy}
+                  rx={b.rx}
+                  ry={b.ry}
+                  fill={b.color || accent.color || 'var(--vc-accent, #ff3300)'}
+                  opacity={b.opacity ?? 1}
+                />
+              )
+            })}
+          </g>
+        </svg>
+      </div>
+    )
+  }
+
+  // Presentational: a themed horizontal rule with an optional centered label
+  // (spec §10). Interactive/editor mode keeps a labeled, selectable box so
+  // authors can see and grab an otherwise-invisible separator.
+  const renderSeparator = (sep) => {
+    const base = {
+      ...separatorStyle(sep),
+      ...commonStyle(sep),
+      ...editStyle(sep)
+    }
+    if (interactive) {
+      return (
+        <div
+          key={sep.id}
+          style={{
+            ...base,
+            border: '1px dashed rgba(99, 102, 241, 0.4)',
+            background: 'rgba(99, 102, 241, 0.1)'
+          }}
+          {...handlers(sep)}
+        >
+          <span
+            style={{
+              fontSize: '10px',
+              color: '#818cf8',
+              fontWeight: 500,
+              letterSpacing: '0.1em',
+              textTransform: 'uppercase',
+              opacity: 0.7
+            }}
+          >
+            Separator ({sep.gap || 'normal'})
+          </span>
+        </div>
+      )
+    }
+    const rule = {
+      flex: 1,
+      borderTop: '1px solid var(--vc-separator, currentColor)',
+      opacity: 0.4
+    }
+    return (
+      <div key={sep.id} style={base}>
+        <div style={rule} />
+        {sep.label && (
+          <>
+            <span
+              style={{
+                padding: '0 0.75rem',
+                fontSize: '0.75rem',
+                color: 'var(--vc-separator, currentColor)',
+                opacity: 0.7,
+                whiteSpace: 'nowrap'
+              }}
+            >
+              {sep.label}
+            </span>
+            <div style={rule} />
+          </>
+        )}
+      </div>
+    )
+  }
+
+  const renderLayer = (layer) => {
+    if (isLayerHidden(layer, containerWidth, mobileBreakpoint)) return null
+    const common = commonStyle(layer)
+
+    switch (layer._kind) {
+      case 'shape':
+        return (
+          <div
+            key={layer.id}
+            style={{ ...shapeStyle(layer), ...common, ...editStyle(layer) }}
+            {...handlers(layer)}
+          />
+        )
+      case 'subject':
+        return (
+          <img
+            key={layer.id}
+            src={layer.src}
+            alt={layer.alt || ''}
+            style={{ ...subjectStyle(layer), ...common, ...editStyle(layer) }}
+            {...handlers(layer)}
+          />
+        )
+      case 'spray':
+        return (
+          <div
+            key={layer.id}
+            style={{ ...sprayStyle(layer), ...common, ...editStyle(layer) }}
+            {...handlers(layer)}
+          />
+        )
+      case 'accent':
+        return renderAccent(layer)
+      case 'svg':
+        return (
+          <div
+            key={layer.id}
+            style={{ ...svgStyle(layer), ...common, ...editStyle(layer) }}
+            {...handlers(layer)}
+            dangerouslySetInnerHTML={{
+              __html: buildSvgHtml(layer, sanitizeSvg)
+            }}
+          />
+        )
+      case 'text':
+        return (
+          <div
+            key={layer.id}
+            style={{ ...textStyle(layer), ...common, ...editStyle(layer) }}
+            {...handlers(layer)}
+          >
+            {layer.content || layer.title || 'Text Layer'}
+          </div>
+        )
+      case 'separator':
+        return renderSeparator(layer)
+      default:
+        return null
+    }
+  }
+
+  return (
+    <div
+      ref={containerRef}
+      className={className}
+      style={{
+        position: 'relative',
+        overflow: 'hidden',
+        width: '100%',
+        height: '100%',
+        background: comp.background || 'transparent',
+        aspectRatio: comp.aspectRatio || 'auto',
+        borderRadius: comp.borderRadius || '0',
+        ...style
+      }}
+    >
+      {injectKeyframes && <style>{VC_KEYFRAMES}</style>}
+      {layers.map(renderLayer)}
+    </div>
+  )
+}
+
+export default Scene

package/src/compose.js

@@ -0,0 +1,80 @@
+/**
+ * Pure, SSR-safe templating for content-driven hosts. No React, no DOM, no
+ * randomness — safe to call at build time, in SSR, and on the client (ids are
+ * deterministic, so server/client output matches).
+ *
+ * `composeScene(template, { overrides, content })` returns a NEW composition
+ * with two transforms applied, then handed straight to <Scene>:
+ *
+ *   - overrides (spec §11.3): named-slot templating. `{ [layerId]: partial }`
+ *     shallow-merges onto the layer with that id. An explicit field wins.
+ *   - content  (spec §12): ordered, variable-length content stream. Each item
+ *     `{ kind, ...fields }` becomes a layer, merged under the template's
+ *     `content.defaults[kind]` (so the template enforces brand styling), with
+ *     zIndex auto-assigned from `content.{zStart,zStep}` unless the item sets
+ *     its own.
+ *
+ * Input may be an envelope (`{ $schema, composition }`) or a bare composition;
+ * the return value matches the input shape.
+ */
+
+const KIND_TO_GROUP = {
+  subject: 'subjects',
+  shape: 'shapes',
+  spray: 'sprays',
+  accent: 'accents',
+  svg: 'svgs',
+  text: 'texts',
+  separator: 'separators'
+}
+
+const GROUPS = Object.values(KIND_TO_GROUP)
+
+export function composeScene(template, { overrides, content } = {}) {
+  const isEnvelope = !!(template && typeof template.composition === 'object')
+  const comp = isEnvelope ? template.composition : template || {}
+
+  // Shallow-clone the composition and each layer array/object so we never
+  // mutate the caller's template.
+  const next = { ...comp }
+  for (const group of GROUPS) {
+    if (Array.isArray(comp[group]))
+      next[group] = comp[group].map((l) => ({ ...l }))
+  }
+
+  // 1) Overrides — shallow-merge by id across every layer kind.
+  if (overrides) {
+    for (const group of GROUPS) {
+      if (!Array.isArray(next[group])) continue
+      next[group] = next[group].map((l) =>
+        overrides[l.id] ? { ...l, ...overrides[l.id] } : l
+      )
+    }
+  }
+
+  // 2) Content binding — expand the ordered content stream into layers.
+  const items = Array.isArray(content) ? content : []
+  if (items.length) {
+    const cfg = comp.content || {}
+    const zStart = cfg.zStart ?? 100
+    const zStep = cfg.zStep ?? 100
+    const kindDefaults = cfg.defaults || {}
+
+    items.forEach((item, i) => {
+      if (!item || !item.kind) return
+      const group = KIND_TO_GROUP[item.kind]
+      if (!group) return
+      const layer = {
+        ...(kindDefaults[item.kind] || {}),
+        ...item,
+        // Deterministic id (index-based) so SSR and client hydration agree.
+        id: item.id || `content-${item.kind}-${i}`,
+        zIndex: item.zIndex ?? zStart + i * zStep
+      }
+      if (!Array.isArray(next[group])) next[group] = []
+      next[group] = [...next[group], layer]
+    })
+  }
+
+  return isEnvelope ? { ...template, composition: next } : next
+}

package/src/index.js

@@ -0,0 +1,6 @@
+// @uniweb/scene — public surface for the Scene Composition Format renderer.
+export { Scene, default } from './Scene.jsx'
+// `Composition` is a back-compat alias (the renderer's pre-rename name upstream).
+export { Scene as Composition } from './Scene.jsx'
+export * from './layers.js'
+export * from './compose.js'

package/src/layers.js

@@ -0,0 +1,277 @@
+/**
+ * Plain-JS core for the scene renderer.
+ *
+ * Pure data + style computation — no React, no DOM access. Every function
+ * takes plain objects and returns plain objects, so this layer can be reused
+ * for server-side rendering, static export, or non-React hosts. The JSX
+ * components in ./Scene.jsx are a thin view on top of these helpers.
+ */
+
+// Injected once by <Scene> so animations work with zero host setup.
+export const VC_KEYFRAMES = `
+  @media (prefers-reduced-motion: no-preference) {
+    @keyframes vc-float {
+      0%, 100% { translate: 0 0; }
+      50% { translate: 0 -6px; }
+    }
+    @keyframes vc-drift {
+      0%, 100% { translate: 0 0; }
+      50% { translate: 3px -3px; }
+    }
+    @keyframes vc-pulse {
+      0%, 100% { opacity: 1; }
+      50% { opacity: 0.4; }
+    }
+    @keyframes vc-rotate-slow {
+      to { rotate: 360deg; }
+    }
+  }
+`
+
+// Width (px) below which a container is treated as "mobile". Container-queried
+// via ResizeObserver, not viewport-queried — so a scene behaves the same
+// whether it fills the screen or sits in a small card.
+export const DEFAULT_MOBILE_BREAKPOINT = 768
+
+// [compositionArrayKey, layer._kind] — render/flatten order within a z tie.
+const GROUPS = [
+  ['subjects', 'subject'],
+  ['shapes', 'shape'],
+  ['sprays', 'spray'],
+  ['accents', 'accent'],
+  ['svgs', 'svg'],
+  ['texts', 'text'],
+  ['separators', 'separator']
+]
+
+/**
+ * Merge every layer array of a composition into one list sorted by zIndex
+ * (ascending = back-to-front paint order). Each layer is tagged with `_kind`
+ * (singular type) and `_group` (its source array name).
+ */
+export function flattenLayers(comp) {
+  let all = []
+  for (const [group, kind] of GROUPS) {
+    if (Array.isArray(comp?.[group])) {
+      all = all.concat(
+        comp[group].map((l) => ({ ...l, _kind: kind, _group: group }))
+      )
+    }
+  }
+  return all.sort((a, b) => (a.zIndex || 0) - (b.zIndex || 0))
+}
+
+// Parse a `hideBelow` length ("640px", "40rem") to raw pixels for comparison.
+export function getHideBelowPx(val) {
+  if (!val) return 0
+  const match = String(val).match(/([\d.]+)(px|rem|em)?/)
+  if (!match) return 0
+  const num = parseFloat(match[1])
+  const unit = match[2] || 'px'
+  if (unit === 'rem' || unit === 'em') return num * 16
+  return num
+}
+
+/**
+ * Container-width-queried visibility. Replaces the editor's Tailwind
+ * `max-md:hidden` / `md:hidden` classes so the renderer needs no CSS framework
+ * and follows the spec's container-query intent.
+ *   - `hidden`     → never rendered
+ *   - `hideBelow`  → hidden when the container is narrower than the threshold
+ *   - `decorative` → desktop-only (hidden below the mobile breakpoint)
+ *   - separators   → mobile-only (hidden at/above the mobile breakpoint)
+ */
+export function isLayerHidden(
+  layer,
+  containerWidth,
+  breakpoint = DEFAULT_MOBILE_BREAKPOINT
+) {
+  if (layer.hidden) return true
+  if (layer.hideBelow && containerWidth < getHideBelowPx(layer.hideBelow))
+    return true
+  if (layer.decorative && containerWidth < breakpoint) return true
+  if (layer._kind === 'separator' && containerWidth >= breakpoint) return true
+  return false
+}
+
+// Common, non-interactive props shared by every non-accent layer.
+export function commonStyle(layer) {
+  return {
+    animation: layer.animation || 'none',
+    backdropFilter: layer.backdropFilter || 'none',
+    WebkitBackdropFilter: layer.backdropFilter || 'none'
+  }
+}
+
+export function shapeStyle(shape) {
+  const style = {
+    position: 'absolute',
+    top: shape.top || '50%',
+    bottom: shape.bottom,
+    left: shape.left || '50%',
+    right: shape.right,
+    width: shape.width || '80px',
+    height: shape.height || '80px',
+    background: shape.background || 'var(--vc-shape, #ffffff)',
+    mixBlendMode: shape.mixBlendMode || 'normal',
+    filter: shape.filter || 'none',
+    transform: shape.transform || 'translate(-50%, -50%)',
+    opacity: shape.opacity ?? 1,
+    zIndex: shape.zIndex || 0
+  }
+  if (shape.type === 'circle' || shape.type === 'blob')
+    style.borderRadius = '50%'
+  else if (shape.type === 'pill') style.borderRadius = '9999px'
+  else if (shape.type === 'rect')
+    style.borderRadius = shape.borderRadius || '0px'
+  else if (shape.type === 'ring') {
+    style.borderRadius = '50%'
+    style.border = `${shape.strokeWidth || '3px'} solid ${shape.color || 'var(--vc-shape, #fff)'}`
+    style.background = 'transparent'
+  } else if (shape.type === 'diamond') {
+    style.transform = `${style.transform !== 'none' ? style.transform : ''} rotate(45deg)`
+  }
+  return style
+}
+
+export function subjectStyle(subject) {
+  return {
+    position: 'absolute',
+    top: subject.top || '50%',
+    left: subject.left || '50%',
+    transform: `translate(-50%, -50%) ${subject.transform || ''}`,
+    width: subject.maxWidth || '70%',
+    height: subject.maxHeight || '80%',
+    objectFit: subject.objectFit || 'contain',
+    objectPosition: subject.objectPosition || 'center',
+    mixBlendMode: subject.mixBlendMode || 'normal',
+    filter: subject.filter || 'none',
+    opacity: subject.opacity ?? 1,
+    zIndex: subject.zIndex || 2
+  }
+}
+
+export function sprayStyle(spray) {
+  const style = {
+    position: 'absolute',
+    top: spray.top || '50%',
+    bottom: spray.bottom,
+    left: spray.left || '50%',
+    right: spray.right,
+    width: spray.width || '300px',
+    height: spray.height || '300px',
+    background: spray.fill || 'var(--vc-accent, #ff3300)',
+    mixBlendMode: spray.mixBlendMode || 'normal',
+    zIndex: spray.zIndex || 0,
+    opacity: spray.opacity ?? 1,
+    transform: spray.transform || 'translate(-50%, -50%)',
+    filter: spray.filter || 'none'
+  }
+  const spread = spray.spread !== undefined ? spray.spread : 60
+  const radius = spray.radius !== undefined ? spray.radius : 50
+  if (spray.mode === 'airbrush' || !spray.mode) {
+    style.maskImage = `radial-gradient(circle, black, transparent ${spread}%)`
+    style.WebkitMaskImage = style.maskImage
+    style.opacity = style.opacity * (radius / 100)
+  } else if (spray.mode === 'splatter') {
+    style.background = 'transparent'
+    style.border = `${spread / 5}px dotted ${spray.fill || 'var(--vc-accent, #ff3300)'}`
+    style.borderRadius = '50%'
+    style.filter = `blur(${radius / 20}px) ${style.filter}`
+  }
+  return style
+}
+
+// Accents are always full-bleed and never pointer-interactive.
+export function accentContainerStyle(accent) {
+  return {
+    position: 'absolute',
+    inset: 0,
+    width: '100%',
+    height: '100%',
+    mixBlendMode: accent.mixBlendMode || 'normal',
+    opacity: accent.opacity ?? 1,
+    zIndex: accent.zIndex || 0,
+    pointerEvents: 'none',
+    animation: accent.animation || 'none',
+    backdropFilter: accent.backdropFilter || 'none',
+    WebkitBackdropFilter: accent.backdropFilter || 'none'
+  }
+}
+
+export function svgStyle(svg) {
+  return {
+    position: 'absolute',
+    top: svg.top || '50%',
+    bottom: svg.bottom,
+    left: svg.left || '50%',
+    right: svg.right,
+    width: svg.width || '120px',
+    height: svg.height || '120px',
+    mixBlendMode: svg.mixBlendMode || 'normal',
+    opacity: svg.opacity ?? 1,
+    zIndex: svg.zIndex || 0,
+    transform: svg.transform || 'translate(-50%, -50%)',
+    filter: svg.filter || 'none',
+    color: svg.color || 'inherit' // drives currentColor in the inline markup
+  }
+}
+
+export function textStyle(text) {
+  return {
+    position: 'absolute',
+    top: text.top || '50%',
+    left: text.left || '50%',
+    transform: text.transform || 'translate(-50%, -50%)',
+    // Default color/font route through --vc-* so a host can theme unstyled text
+    // from its surface tokens; an explicit value in the JSON still wins.
+    // `currentColor` lets text inherit the surrounding surface color by default.
+    color: text.color || 'var(--vc-text, currentColor)',
+    fontFamily: text.fontFamily || 'var(--vc-font, inherit)',
+    fontSize: text.fontSize || '4rem',
+    fontWeight: text.fontWeight || 800,
+    letterSpacing: text.letterSpacing || 'normal',
+    lineHeight: text.lineHeight ?? 1.1,
+    textShadow: text.textShadow || 'none',
+    maxWidth: text.maxWidth || 'none',
+    textAlign: text.align || 'center',
+    mixBlendMode: text.mixBlendMode || 'normal',
+    filter: text.filter || 'none',
+    opacity: text.opacity ?? 1,
+    zIndex: text.zIndex || 10,
+    // pre-wrap (not pre-line) preserves runs of whitespace, not just newlines.
+    whiteSpace: 'pre-wrap'
+  }
+}
+
+// Positioning + centering only. The decoration differs by mode and is applied
+// by the component: a clean rule (presentational) or a labeled debug box
+// (interactive/editor) — see Scene.jsx.
+export function separatorStyle(separator) {
+  return {
+    position: 'absolute',
+    top: separator.top || '50%',
+    left: separator.left || '0',
+    width: separator.width || '100%',
+    height: separator.gap === 'large' ? '40px' : '20px',
+    zIndex: separator.zIndex || 0,
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center'
+  }
+}
+
+// Spec 1.3: an svg layer's `content` may be a bare fragment (a <path>, a <g>,
+// …). Wrap it in a default <svg> using the layer's viewBox; a complete <svg>
+// passes through untouched.
+//
+// `content` reaches `dangerouslySetInnerHTML`, so when it can be author-supplied
+// or imported, pass a `sanitize` function — the host owns the sanitizer; we only
+// provide the injection point. Defaults to identity (unchanged behavior).
+export function buildSvgHtml(svg, sanitize) {
+  const isFragment = !/^\s*<svg/i.test(svg.content || '')
+  const html = isFragment
+    ? `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${svg.viewBox || '0 0 100 100'}" width="100%" height="100%" preserveAspectRatio="xMidYMid meet">${svg.content}</svg>`
+    : svg.content
+  return typeof sanitize === 'function' ? sanitize(html) : html
+}