@edv4h/usketch-css3d-renderer 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EdV4H
+
+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

@@ -1,3 +1,132 @@
-# Temporary Holding Version
+# @edv4h/usketch-css3d-renderer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+ボードの 3D 表示（コアの `View3dState`）を CSS の 3D 変形で描くレンダラー。DOM レンダラーと組み合わせて使う。Shape は 2D の DOM のまま描き、それを載せた層だけを傾けて奥へ続く地面にする。3D の見た目を持つ Shape（`ShapeData.view3d`）は、自分の層（`shape-3d`）で地面から立ち上げて描く。
+
+Mode 7 などの 3D ビューは、ボードの 3D 表示の状態（カメラ・切り替えの進み具合・描画距離）を変えるだけで、描くのはこのレンダラー。
+
+## Install
+
+```bash
+pnpm add @edv4h/usketch-css3d-renderer @edv4h/usketch-dom-renderer @edv4h/usketch-shared react
+```
+
+## 使い方
+
+DOM レンダラーと並べて追加する。
+
+```ts
+import { createCss3dRendererPlugin } from "@edv4h/usketch-css3d-renderer";
+import { createDomRendererPlugin } from "@edv4h/usketch-dom-renderer";
+import { createMode7Plugin } from "@edv4h/usketch-plugin-mode7";
+
+createApp({
+	plugins: [
+		createDomRendererPlugin(),
+		createCss3dRendererPlugin(),
+		createMode7Plugin(),
+	],
+});
+```
+
+`createMode7Plugin` は、ボードにレンダラーが無ければ自分で 1 つ用意する。今のバージョンでは追加しなくても動くが、次のメジャーからはホストが追加する。
+
+## どの層をどう描くか
+
+層は `Layer.view3d` で 3D 表示での見え方を宣言する。
+
+| `view3d` | 描き方 |
+|------|------|
+| `tilt` | カメラの傾きで地面に寝かせ、描画距離より奥を切り取る |
+| `depth` | `tilt` と同じく寝かせるが切り取らず、中の要素が地面から立ち上がれるように 3D の文脈を保つ |
+| `screen` / 未指定 | 画面に固定したまま（HUD・空など） |
+| `ground` | 自分で地面を描く層（標高のメッシュなど）。傾けない。奥行きステージでは、地面に立つものより奥に置く |
+| `hidden` | 3D 表示の間は出さない |
+
+3D ビューが自分の層ピッカーを持つとき（Mode 7）は、`setTiltLayers` / `setDepthLayers` で一覧を渡す。`null` で宣言に戻る。
+
+## 奥行きステージ（実験）
+
+既定では、傾けた層は層の順に重なる（後の層が前の層の上に描かれる）。奥行きステージをオンにすると、メインのキャンバスを 1 つの 3D 空間にして、傾けた層の中身を実際の奥行きで重ねる。立てた看板の後ろにいるキャラクターは看板に隠れ、手前にいれば看板の前に出る。
+
+HUD の「3D の描き方（CSS 3D）」→「奥行きで重ねる（実験）」か、`setDepthStage(true)` で切り替える。
+
+- 傾けない層は邪魔にならない位置へ動かす: 最初の傾けた層より前の層（空）と `ground` の層は奥へ、それ以外（霧・HUD）は手前へ。それぞれの中では層の順を保つ
+- `ground` の層が何かを描いている間は、その下に重なる層（傾けた層も）をさらに奥へ置く。平らなボードでも隠れていたものなので見た目は変わらない
+- キャンバスの背景は一番奥に描き直す。ステージ自身は切り取れない（Chrome では `overflow: clip` で 3D が平らになる）ので、親要素で切り取る
+- 標高のメッシュ（canvas）は奥行きで並ばないので、その陰に入ったものは下の「地形の陰」で扱う
+
+## 地形の陰
+
+標高のメッシュは canvas なので、ブラウザは「丘の向こうの看板」を丘の後ろに回せない（丘の上に描いてしまう）。そこで、カメラから見て地面の陰に入ったものを薄くする（既定）か隠す。
+
+- 判定は shared の純関数 `isOccluded(point, view, heightAt)`: 点から目（`cameraEye(view)`、CSS の `perspective()` の視点）までの視線に沿って地面の高さ（`ctx.height` の `groundAt`）を調べ、視線より高い地面があれば陰
+- レンダラーはこの答えを `view3dOcclusionService`（shared）で出す。3D の Shape は上端が陰に入ったら、キャラクターは体の中ほどが入ったら薄くなる。キャラクターの体は描き手（ホスト）が `occluded` を見て面ごとに薄くする（3D の入れ物に opacity を付けると平らになるため）
+- 箱（`box`）は壁と天面を 1 枚ずつ薄くする。種別の自前の 3D 表現（`render3d`）は薄くすると平らになるので、陰では隠す
+- 毎フレームすべてを調べると重いので、答えは 100ms 使い回し、1 フレームで調べ直すのは 40 個まで（`createOcclusionCache`）
+- HUD の「地形の陰」（薄くする / 隠す / そのまま）か `setOcclusion(mode)` で切り替える
+
+## 3D の Shape
+
+`view3d`（または種別の既定）を持つ Shape を、`depth` の層 `shape-3d`（order 51）で立ち上げて描く。
+
+| mode | 見え方 |
+|---|---|
+| `stand` | 下辺の中点を軸に起こして立てる。`facing: "camera"` はカメラの方を向く |
+| `box` | 面を `height` だけ持ち上げて天面にし、四辺に壁を下ろす（壁の色は `style.fill` を暗くしたもの） |
+| `float` | 面をそのまま `height` だけ持ち上げる。下に影 |
+
+- 種別ごとに使える mode と既定・自前の 3D 表現（`render3d`）は、その種別の `ShapeDefinition.view3d`（ホストの `ctx.shapes.configureView3d` で上書き）から読む。宣言の無い種別は `stand` / `float` だけ
+- 3D の見た目を持たない Shape も、起伏のある地形の上では平らなままその高さに乗せる（`groundFlat`、既定オン）
+- 画面上で小さすぎるもの（既定 8px 未満）・描かれている地面の外・全体 LOD 中は立てない。数は手前から最大 200 個
+- 描いている Shape は shared の `shapeClaims(services)` で宣言し、DOM レンダラーはそれを描かない
+- プラグインは `css3dShapeSourceService` で種別の表（`types()`）と上限（`limits()`: `minPx` / `maxCount` / `groundFlat`）を渡せる（shape-3d プラグインが HUD の設定を渡すのに使う）
+- 立ち上がる見た目の HUD とキャラクターとの当たり判定は、shape-3d プラグインとコア（`ctx.height`）が受け持つ
+
+## 公開 API
+
+### `createCss3dRendererPlugin(options?)`
+
+レンダラーのプラグイン。すでにボードにレンダラーがあれば何もしない。
+
+| option | 内容 |
+|------|------|
+| `tiltLayerIds` | 宣言の代わりに傾ける層 |
+| `depthLayerIds` | 宣言の代わりに奥行きを持たせる層 |
+| `view3d` | 3D 表示の状態の置き場所。既定はボードのストア（`BoardStore.getView3d`）。古いストアのホストは自前のセルを渡す |
+| `shapes` | 3D の Shape を描くか。既定 `true` |
+| `depthStage` | 奥行きステージをオンで始める。既定 `false` |
+| `hud` | 設定（地形の陰・奥行きステージ）を HUD に出す。既定 `true` |
+| `occlusion` | 地形の陰に入ったもの: `"fade"`（既定）/ `"hide"` / `"none"` |
+
+### `css3dRendererService`
+
+`ctx.services` に置かれる `Css3dRendererApi`。
+
+| メソッド | 内容 |
+|------|------|
+| `isDrawing()` | いま 3D で描いているか（切り替えの進み具合が 0 より大きい） |
+| `setTiltLayers(ids \| null)` | 傾ける層を決める |
+| `setDepthLayers(ids \| null)` | 奥行きを持たせる層を決める |
+| `getTiltLayers()` / `getDepthLayers()` | いまの一覧 |
+| `setDepthStage(on)` / `isDepthStage()` | 奥行きステージ（実験）の切り替え |
+| `setOcclusion(mode)` / `getOcclusion()` | 地形の陰に入ったものの見せ方 |
+
+### `setupCss3dRenderer(ctx, options?)`
+
+プラグインを使わずに組み込むとき用。`{ api, dispose }` を返す（ボードの 3D 表示の状態が無いときは `null`）。
+
+### 純関数
+
+- `layerTransform(state)`: 傾けた層の `transform` / `transform-origin`
+- `cameraHeightPx(state, zoom)`: 画面上のカメラの高さ（px）
+- `drawDistanceClip(...)` / `drawDistanceOverscanPx(...)`: 描画距離の切り取りと、背景を奥まで敷く幅
+- `tiltLayerRules(ids, options)`: 層を傾ける CSS
+- `depthStageRules(options)`: 奥行きステージの CSS
+- `projectionCamera(state, zoom)`: 描いているカメラを shared の射影関数の形で
+- 3D の Shape の配置: `selectShapes3d` / `shapePose` / `poseBox` / `poseTransform` / `render3dFrame` / `boxWalls` / `shadowStyle` など
+
+## 描画の仕組み
+
+- 1 枚の `<style data-css3d-renderer>` に `!important` の規則を書き、メインのキャンバスに付けた `data-view3d-stage` 属性で範囲を絞る。React の再描画を越えて残り、後から追加された層にも効く
+- カメラの高さは CSS 変数 `--usketch-mode7-camera-height` 1 つで全層を下げるので、毎フレーム変わってもシートは書き換えない
+- 旧属性 `data-mode7-stage` と旧イベント `bg-grid:set-overscan` も次のメジャーまで出す

package/dist/css3d-css.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The `clip-path` for the tilted layer wrappers. The tilt uses `overflow:visible` to
+ * keep the 3D intact, which would otherwise let content float PAST the grid; the clip
+ * bounds the tilted content instead.
+ *
+ * `distance` is the draw distance in **canvas/world units** measured forward from the
+ * near edge (bottom of the viewport). `distance <= 0` means "auto": clip exactly to the
+ * box (`inset(0)` — nothing floats past the grid, no overscan). A positive `distance`
+ * maps to `distance * zoom` screen px at the bottom of the wrapper box:
+ *   - within the box (`distance*zoom < height`) → positive inset (a closer cutoff);
+ *   - beyond the box (`distance*zoom > height`) → NEGATIVE inset, i.e. the clip extends
+ *     above the box so content farther than the viewport is drawn. The background grid
+ *     must be extended to match (see {@link drawDistanceOverscanPx}) or that far content
+ *     would float; `clip-path` keeps the 3D tilt intact (unlike `overflow`, flattening).
+ */
+export declare function drawDistanceClip(distance: number, zoom: number, viewportHeightPx: number, 
+/** Transition amount 0…1: a near-band clip fades in with the tilt, so the still-flat
+ *  board isn't cut off at the top while the ground rises. */
+strength?: number): string;
+/**
+ * The px the background grid must extend ABOVE/BEYOND the viewport box to stay under the
+ * content that {@link drawDistanceClip} reveals for a draw `distance` larger than the
+ * viewport. `0` when the distance is auto/within the box (no extension needed). This is
+ * what the canvas hands backgrounds as `LayerRenderContext.view3dOverscan` (see
+ * `view3dOverscanPx`), so the grid and the shapes end together.
+ */
+export declare function drawDistanceOverscanPx(distance: number, zoom: number, viewportHeightPx: number): number;
+export interface TiltRuleOptions {
+    /** Attribute marking the main canvas container (rules are scoped to it). */
+    stageAttr: string;
+    transform: string;
+    transformOrigin: string;
+    /** The draw-distance `clip-path` (see {@link drawDistanceClip}). */
+    clip: string;
+    /** Layers rendered with real depth (`Layer.view3d` `depth`). */
+    depthLayerIds: ReadonlySet<string>;
+}
+/**
+ * The injected stylesheet that tilts each selected layer wrapper.
+ *
+ * `overflow:visible` + `transform-style:preserve-3d` are essential for layers like
+ * `dom-shapes`: their wrapper has `overflow:hidden` (which the CSS spec forces
+ * `transform-style` to `flat`) and an inner viewport-transform div that Chrome
+ * composites separately — so without these the SHAPES render flat in screen space
+ * while only the wrapper tilts. A DESCENDANT selector (space, not `>`) matches the
+ * wrapper regardless of nesting.
+ *
+ * Plain layers get the draw-distance clip. A `clip-path` is a grouping property that
+ * FLATTENS its subtree onto the plane, so DEPTH layers skip it and instead keep the
+ * 3D context through the engine's inner wrappers (viewport-transform / pointer divs):
+ * content that sets its own depth (raised map terrain, a character standing on it) then
+ * rises out of the tilted ground instead of being painted onto it.
+ */
+export declare function tiltLayerRules(layerIds: readonly string[], o: TiltRuleOptions): string;
+/** How far (px) the depth stage pushes the layers that aren't tilted out of the ground. */
+export declare const DEPTH_STAGE_FAR_PX = 100000;
+/** A layer as the depth stage sees it, in drawing order. */
+export interface DepthStageLayer {
+    id: string;
+    /** Tilted into the ground (a `tilt` or `depth` layer). */
+    tilted: boolean;
+    /** Draws the ground itself without being tilted (`Layer.view3d` `ground`). */
+    ground?: boolean;
+}
+export interface DepthStageOptions {
+    stageAttr: string;
+    layers: readonly DepthStageLayer[];
+    /** The stage's own background (drawn behind everything once the stage is transparent). */
+    background: string;
+    /** The tilted layers' `transform` (as in {@link TiltRuleOptions.transform}). */
+    tiltTransform: string;
+}
+/**
+ * The depth stage: the main canvas container becomes ONE 3D space (`preserve-3d`), so the
+ * tilted layers' contents sort by their real depth across layers (a character behind a
+ * standing sign is hidden by it, a cliff hides what is behind it) instead of each layer
+ * painting over the ones before it.
+ *
+ * Everything in that space is sorted by depth, so the stage moves what isn't part of the
+ * tilted ground out of the way, keeping the drawing order inside each band (from the back):
+ *
+ * 1. the stage's own background (a `::before`);
+ * 2. every layer stacked under a layer that draws the ground itself (a terrain mesh): it
+ *    covers them on the flat board too. A tilted one is moved back along the view
+ *    (a `translateZ` before its tilt), so it still lands on the same pixels;
+ * 3. the layers drawing the ground, and the untilted ones before the first tilted (a sky);
+ * 4. the tilted layers, where they are;
+ * 5. the other untilted layers (overlays, HUD), in front.
+ *
+ * The stage can't clip without flattening the space (`overflow: clip` flattens in
+ * Chrome), so it is left unclipped: its parent clips instead. Pure.
+ */
+export declare function depthStageRules(o: DepthStageOptions): string;
+//# sourceMappingURL=css3d-css.d.ts.map

package/dist/css3d-css.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"css3d-css.d.ts","sourceRoot":"","sources":["../src/css3d-css.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC/B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,gBAAgB,EAAE,MAAM;AACxB;6DAC6D;AAC7D,QAAQ,SAAI,GACV,MAAM,CAeR;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACrC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,gBAAgB,EAAE,MAAM,GACtB,MAAM,CAIR;AAED,MAAM,WAAW,eAAe;IAC/B,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACnC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,CAAC,EAAE,eAAe,GAAG,MAAM,CAStF;AAWD,2FAA2F;AAC3F,eAAO,MAAM,kBAAkB,SAAU,CAAC;AAE1C,4DAA4D;AAC5D,MAAM,WAAW,eAAe;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,0DAA0D;IAC1D,MAAM,EAAE,OAAO,CAAC;IAChB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;IACnC,0FAA0F;IAC1F,UAAU,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,aAAa,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,iBAAiB,GAAG,MAAM,CA2B5D"}

package/dist/css3d-css.js

@@ -0,0 +1,136 @@
+// The CSS the renderer injects: the tilt of each layer wrapper, the draw-distance clip
+// and the depth context. Pure string builders (moved from the Mode 7 plugin).
+/**
+ * The `clip-path` for the tilted layer wrappers. The tilt uses `overflow:visible` to
+ * keep the 3D intact, which would otherwise let content float PAST the grid; the clip
+ * bounds the tilted content instead.
+ *
+ * `distance` is the draw distance in **canvas/world units** measured forward from the
+ * near edge (bottom of the viewport). `distance <= 0` means "auto": clip exactly to the
+ * box (`inset(0)` — nothing floats past the grid, no overscan). A positive `distance`
+ * maps to `distance * zoom` screen px at the bottom of the wrapper box:
+ *   - within the box (`distance*zoom < height`) → positive inset (a closer cutoff);
+ *   - beyond the box (`distance*zoom > height`) → NEGATIVE inset, i.e. the clip extends
+ *     above the box so content farther than the viewport is drawn. The background grid
+ *     must be extended to match (see {@link drawDistanceOverscanPx}) or that far content
+ *     would float; `clip-path` keeps the 3D tilt intact (unlike `overflow`, flattening).
+ */
+export function drawDistanceClip(distance, zoom, viewportHeightPx, 
+/** Transition amount 0…1: a near-band clip fades in with the tilt, so the still-flat
+ *  board isn't cut off at the top while the ground rises. */
+strength = 1) {
+    if (!(distance > 0) || !(zoom > 0) || !(viewportHeightPx > 0)) {
+        return "inset(0% 0% 0% 0%)"; // auto → clip to the box
+    }
+    const bandPx = distance * zoom;
+    if (bandPx <= viewportHeightPx) {
+        // Within the viewport: keep only the near band; sides stay at the box.
+        const s = Math.min(1, Math.max(0, strength));
+        return `inset(${round((1 - bandPx / viewportHeightPx) * 100 * s)}% 0% 0% 0%)`;
+    }
+    // Beyond the viewport: extend equally on ALL sides so the far ground fans out
+    // (not just a box-wide strip). The grid overscans to match; the canvas container
+    // clips whatever runs off-screen. Negative inset grows the clip region past the box.
+    const over = round(bandPx - viewportHeightPx);
+    return `inset(${-over}px ${-over}px ${-over}px ${-over}px)`;
+}
+/**
+ * The px the background grid must extend ABOVE/BEYOND the viewport box to stay under the
+ * content that {@link drawDistanceClip} reveals for a draw `distance` larger than the
+ * viewport. `0` when the distance is auto/within the box (no extension needed). This is
+ * what the canvas hands backgrounds as `LayerRenderContext.view3dOverscan` (see
+ * `view3dOverscanPx`), so the grid and the shapes end together.
+ */
+export function drawDistanceOverscanPx(distance, zoom, viewportHeightPx) {
+    if (!(distance > 0) || !(zoom > 0) || !(viewportHeightPx > 0))
+        return 0;
+    const bandPx = distance * zoom;
+    return bandPx > viewportHeightPx ? Math.ceil(bandPx - viewportHeightPx) : 0;
+}
+/**
+ * The injected stylesheet that tilts each selected layer wrapper.
+ *
+ * `overflow:visible` + `transform-style:preserve-3d` are essential for layers like
+ * `dom-shapes`: their wrapper has `overflow:hidden` (which the CSS spec forces
+ * `transform-style` to `flat`) and an inner viewport-transform div that Chrome
+ * composites separately — so without these the SHAPES render flat in screen space
+ * while only the wrapper tilts. A DESCENDANT selector (space, not `>`) matches the
+ * wrapper regardless of nesting.
+ *
+ * Plain layers get the draw-distance clip. A `clip-path` is a grouping property that
+ * FLATTENS its subtree onto the plane, so DEPTH layers skip it and instead keep the
+ * 3D context through the engine's inner wrappers (viewport-transform / pointer divs):
+ * content that sets its own depth (raised map terrain, a character standing on it) then
+ * rises out of the tilted ground instead of being painted onto it.
+ */
+export function tiltLayerRules(layerIds, o) {
+    return layerIds
+        .map((id) => {
+        const layer = `[${o.stageAttr}="on"] [data-layer-id="${attrValue(id)}"]`;
+        const base = `transform:${o.transform} !important;transform-origin:${o.transformOrigin} !important;overflow:visible !important;transform-style:preserve-3d !important;`;
+        if (!o.depthLayerIds.has(id))
+            return `${layer}{${base}clip-path:${o.clip} !important;}`;
+        return `${layer}{${base}}${layer}>div,${layer}>div>div{transform-style:preserve-3d}`;
+    })
+        .join("");
+}
+/** Keep an attribute-selector value valid (layer ids are simple, but be safe). */
+function attrValue(id) {
+    return id.replace(/["\\]/g, "");
+}
+function round(n) {
+    return Math.round(n * 1000) / 1000;
+}
+/** How far (px) the depth stage pushes the layers that aren't tilted out of the ground. */
+export const DEPTH_STAGE_FAR_PX = 100_000;
+/**
+ * The depth stage: the main canvas container becomes ONE 3D space (`preserve-3d`), so the
+ * tilted layers' contents sort by their real depth across layers (a character behind a
+ * standing sign is hidden by it, a cliff hides what is behind it) instead of each layer
+ * painting over the ones before it.
+ *
+ * Everything in that space is sorted by depth, so the stage moves what isn't part of the
+ * tilted ground out of the way, keeping the drawing order inside each band (from the back):
+ *
+ * 1. the stage's own background (a `::before`);
+ * 2. every layer stacked under a layer that draws the ground itself (a terrain mesh): it
+ *    covers them on the flat board too. A tilted one is moved back along the view
+ *    (a `translateZ` before its tilt), so it still lands on the same pixels;
+ * 3. the layers drawing the ground, and the untilted ones before the first tilted (a sky);
+ * 4. the tilted layers, where they are;
+ * 5. the other untilted layers (overlays, HUD), in front.
+ *
+ * The stage can't clip without flattening the space (`overflow: clip` flattens in
+ * Chrome), so it is left unclipped: its parent clips instead. Pure.
+ */
+export function depthStageRules(o) {
+    const stage = `[${o.stageAttr}="on"]`;
+    const far = DEPTH_STAGE_FAR_PX;
+    const firstTilted = o.layers.findIndex((l) => l.tilted);
+    let lastGround = -1;
+    o.layers.forEach((l, i) => {
+        if (l.ground && !l.tilted)
+            lastGround = i;
+    });
+    const parts = [
+        `${stage}{transform-style:preserve-3d !important;overflow:visible !important;background:transparent !important;}`,
+        `${stage}::before{content:"";position:absolute;inset:0;pointer-events:none;background:${o.background};transform:translateZ(-${far * 3}px);}`,
+    ];
+    o.layers.forEach((l, i) => {
+        const ground = l.ground === true && !l.tilted;
+        const layer = `${stage}>[data-layer-id="${attrValue(l.id)}"]`;
+        if (!ground && i < lastGround) {
+            // Under the ground. Later ones a little nearer, as everywhere below.
+            const z = -far * 2 + i;
+            const transform = l.tilted ? `translateZ(${z}px) ${o.tiltTransform}` : `translateZ(${z}px)`;
+            parts.push(`${layer}{transform:${transform} !important;}`);
+            return;
+        }
+        if (l.tilted)
+            return;
+        const behind = ground || firstTilted < 0 || i < firstTilted;
+        parts.push(`${layer}{transform:translateZ(${(behind ? -far : far) + i}px) !important;}`);
+    });
+    return parts.join("");
+}
+//# sourceMappingURL=css3d-css.js.map

package/dist/css3d-css.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"css3d-css.js","sourceRoot":"","sources":["../src/css3d-css.ts"],"names":[],"mappings":"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"}

package/dist/css3d-renderer.d.ts

@@ -0,0 +1,85 @@
+import { type PluginContext, type ProjectionCamera, type UsketchPlugin, type View3dCell, type View3dRendererApi, type View3dState } from "@edv4h/usketch-shared";
+/** Attribute the renderer puts on the main canvas container while drawing in 3D. */
+export declare const STAGE_ATTR = "data-view3d-stage";
+/** The attribute Mode 7 used to set; still set (some plugins look for it) until the next major. */
+export declare const LEGACY_STAGE_ATTR = "data-mode7-stage";
+/** CSS variable on the stage holding the camera height (px); the tilt lowers every layer by it. */
+export declare const CAMERA_HEIGHT_VAR = "--usketch-mode7-camera-height";
+export interface Css3dRendererApi extends View3dRendererApi {
+    /** Whether the board is being drawn in 3D now (the view's amount is above 0). */
+    isDrawing(): boolean;
+    /**
+     * Tilt exactly these layers, or `null` (default) for the layers that declare
+     * `view3d: "tilt" | "depth"`. A 3D view with its own layer picker (Mode 7) sets it.
+     */
+    setTiltLayers(ids: readonly string[] | null): void;
+    /** Give exactly these tilted layers depth, or `null` (default) for those declaring `depth`. */
+    setDepthLayers(ids: readonly string[] | null): void;
+    /** The layers tilted now (as resolved from the declarations or the set lists). */
+    getTiltLayers(): readonly string[];
+    /** The tilted layers drawn with depth. */
+    getDepthLayers(): readonly string[];
+    /**
+     * Sort the layers' 3D contents by their real depth in one 3D space (experimental, off
+     * by default): see `depthStageRules`.
+     */
+    setDepthStage(on: boolean): void;
+    isDepthStage(): boolean;
+    /**
+     * How standing things (3D shapes, characters) behind the ground (a hill, a cliff) are
+     * drawn: faded (default), not drawn, or as if nothing hid them (`none`).
+     */
+    setOcclusion(mode: Css3dOcclusionMode): void;
+    getOcclusion(): Css3dOcclusionMode;
+}
+/** See {@link Css3dRendererApi.setOcclusion}. */
+export type Css3dOcclusionMode = "fade" | "hide" | "none";
+/** The renderer on `ctx.services` (one per board). */
+export declare const css3dRendererService: import("@edv4h/usketch-shared").ServiceHandle<Css3dRendererApi>;
+export interface Css3dRendererOptions {
+    /** Layers to tilt instead of the declared ones (see {@link Css3dRendererApi.setTiltLayers}). */
+    tiltLayerIds?: readonly string[];
+    /** Layers to give depth instead of the declared ones. */
+    depthLayerIds?: readonly string[];
+    /**
+     * Where the 3D view state lives. Default: the board store's (`BoardStore.getView3d`);
+     * a host on an older store passes a cell of its own.
+     */
+    view3d?: View3dCell;
+    /** Draw the shapes that have a 3D look (see css3d-shapes). Default `true`. */
+    shapes?: boolean;
+    /** Start with the depth stage on (see {@link Css3dRendererApi.setDepthStage}). Default `false`. */
+    depthStage?: boolean;
+    /** Offer the renderer's settings on the HUD. Default `true`. */
+    hud?: boolean;
+    /** How things behind the ground are drawn (see {@link Css3dRendererApi.setOcclusion}). Default `"fade"`. */
+    occlusion?: Css3dOcclusionMode;
+}
+/** The camera a tilted layer is drawn with, as the projection functions take it. Pure. */
+export declare function projectionCamera(state: View3dState, zoom: number): ProjectionCamera;
+/** The camera height in screen px as drawn: height × zoom, faded with the amount. */
+export declare function cameraHeightPx(state: View3dState, zoom: number): number;
+/** The transform of a tilted layer: the camera's tilt, lowered by the camera height. */
+export declare function layerTransform(state: View3dState): {
+    transform: string;
+    transformOrigin: string;
+};
+/**
+ * Set up the renderer on `ctx`: draws whenever the 3D view's amount is above 0. Returns
+ * its API and a teardown that clears every injected rule.
+ */
+export declare function setupCss3dRenderer(ctx: PluginContext, options?: Css3dRendererOptions): {
+    api: Css3dRendererApi;
+    dispose: () => void;
+} | null;
+/** HUD field name of the depth stage toggle. */
+export declare const DEPTH_STAGE_FIELD = "depthStage";
+/** HUD field name of the occlusion choice. */
+export declare const OCCLUSION_FIELD = "occlusion";
+/**
+ * The CSS 3D renderer plugin. Add it next to the DOM renderer; a 3D view (Mode 7) then
+ * only changes the core's 3D view state. If a renderer is already on the board (Mode 7
+ * adds one when the host didn't), this one does nothing.
+ */
+export declare function createCss3dRendererPlugin(options?: Css3dRendererOptions): UsketchPlugin;
+//# sourceMappingURL=css3d-renderer.d.ts.map

package/dist/css3d-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"css3d-renderer.d.ts","sourceRoot":"","sources":["../src/css3d-renderer.ts"],"names":[],"mappings":"AAgBA,OAAO,EAKN,KAAK,aAAa,EAClB,KAAK,gBAAgB,EAGrB,KAAK,aAAa,EAClB,KAAK,UAAU,EAGf,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAIhB,MAAM,uBAAuB,CAAC;AAS/B,oFAAoF;AACpF,eAAO,MAAM,UAAU,sBAAsB,CAAC;AAC9C,mGAAmG;AACnG,eAAO,MAAM,iBAAiB,qBAAqB,CAAC;AACpD,mGAAmG;AACnG,eAAO,MAAM,iBAAiB,kCAAkC,CAAC;AAIjE,MAAM,WAAW,gBAAiB,SAAQ,iBAAiB;IAC1D,iFAAiF;IACjF,SAAS,IAAI,OAAO,CAAC;IACrB;;;OAGG;IACH,aAAa,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;IACnD,+FAA+F;IAC/F,cAAc,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;IACpD,kFAAkF;IAClF,aAAa,IAAI,SAAS,MAAM,EAAE,CAAC;IACnC,0CAA0C;IAC1C,cAAc,IAAI,SAAS,MAAM,EAAE,CAAC;IACpC;;;OAGG;IACH,aAAa,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,YAAY,IAAI,OAAO,CAAC;IACxB;;;OAGG;IACH,YAAY,CAAC,IAAI,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC7C,YAAY,IAAI,kBAAkB,CAAC;CACnC;AAED,iDAAiD;AACjD,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAI1D,sDAAsD;AACtD,eAAO,MAAM,oBAAoB,iEAA4D,CAAC;AAE9F,MAAM,WAAW,oBAAoB;IACpC,gGAAgG;IAChG,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,yDAAyD;IACzD,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC;;;OAGG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,mGAAmG;IACnG,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,gEAAgE;IAChE,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,4GAA4G;IAC5G,SAAS,CAAC,EAAE,kBAAkB,CAAC;CAC/B;AAED,0FAA0F;AAC1F,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAInF;AAUD,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAIvE;AAED,wFAAwF;AACxF,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CAQjG;AA0BD;;;GAGG;AACH,wBAAgB,kBAAkB,CACjC,GAAG,EAAE,aAAa,EAClB,OAAO,GAAE,oBAAyB,GAChC;IAAE,GAAG,EAAE,gBAAgB,CAAC;IAAC,OAAO,EAAE,MAAM,IAAI,CAAA;CAAE,GAAG,IAAI,CAgSvD;AAED,gDAAgD;AAChD,eAAO,MAAM,iBAAiB,eAAe,CAAC;AAC9C,8CAA8C;AAC9C,eAAO,MAAM,eAAe,cAAc,CAAC;AA2C3C;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,GAAE,oBAAyB,GAAG,aAAa,CAqB3F"}