@nebula-spatial/studio 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/README.md +2 -0
  2. package/dist/{builders-BAXRR5o5.js → builders-lydx4-Rh.js} +1 -1
  3. package/dist/core/session-persistence-controller.d.ts +55 -0
  4. package/dist/doc/placement-policy.d.ts +4 -0
  5. package/dist/editor/editor.d.ts +3 -1
  6. package/dist/editor/index.d.ts +2 -0
  7. package/dist/editor/session-persistence.d.ts +54 -0
  8. package/dist/editor.js +727 -490
  9. package/dist/{export-evidence-DMNRhgL9.js → export-evidence-z2Ne7Trf.js} +654 -972
  10. package/dist/generalization.js +2 -2
  11. package/dist/index.d.ts +4 -2
  12. package/dist/index.js +226 -219
  13. package/dist/{mjcf-visual-Bt4bUxd1.js → mjcf-visual-IOy-ucto.js} +1 -1
  14. package/dist/persist/indexeddb-store.d.ts +22 -2
  15. package/dist/persist/session.d.ts +22 -0
  16. package/dist/persist/snapshot.d.ts +24 -0
  17. package/dist/{physics-facts-tfQYyNTD.js → physics-facts-D-URIBrt.js} +8 -7
  18. package/dist/{placement-policy-DY_FNRDu.js → placement-policy-C6dV6Tf-.js} +161 -141
  19. package/dist/ports/persistence.d.ts +45 -1
  20. package/dist/project/contracts.d.ts +3 -0
  21. package/dist/remote-asset-resolver-D-UeyDMD.js +311 -0
  22. package/dist/{scene-graph-DBLKAhxa.js → scene-graph-DVOXjMmp.js} +2 -2
  23. package/dist/{scene-session-Cy6vDJ1l.js → scene-session-PhoFXFCY.js} +3365 -3340
  24. package/dist/scene.js +2 -2
  25. package/dist/{session-BRBrCLdd.js → session-2bp8YOA4.js} +2 -2
  26. package/dist/{session-q3uuG7OP.js → session-B3WbC7Y2.js} +1 -1
  27. package/dist/session-B9kEf4xN.js +915 -0
  28. package/dist/{session-DI5tPJxn.js → session-DYThdzLZ.js} +4 -4
  29. package/dist/studio/index.d.ts +5 -0
  30. package/dist/studio/indexeddb-persistence.d.ts +2 -0
  31. package/dist/studio/indexeddb-session-persistence.d.ts +11 -0
  32. package/dist/studio/scene-package-asset-sources.d.ts +14 -0
  33. package/dist/studio.js +1422 -1220
  34. package/dist/{urdf-session-CQir2nb2.js → urdf-session-CRXL4bHf.js} +3 -3
  35. package/dist/{usd-session-DZJnEEOs.js → usd-session-CTzInpNy.js} +2 -2
  36. package/dist/version.d.ts +1 -1
  37. package/dist/view/scene-session.d.ts +5 -1
  38. package/dist/{xacro-DLRXyk60.js → xacro-IpPHTMYs.js} +1 -1
  39. package/package.json +1 -1
  40. package/dist/asset-source-BExlEcRt.js +0 -444
  41. package/dist/editorial-BkAFWfbg.js +0 -83
  42. package/dist/remote-asset-resolver-Cb8cfNmw.js +0 -136
package/README.md CHANGED
@@ -55,6 +55,8 @@ playground/sim-studio 本地验证页面、验证编排、资产
55
55
 
56
56
  `StudioHost` 不创建默认 asset source provider。调用方注入的 persistence / asset source provider 默认不由 Host 拥有;只有显式设置 `ownsPersistence` / `ownsAssetSourceProvider` 才负责 dispose。`/studio` 的 `createWebStudioHost()` 会显式安装 in-memory provider,或使用调用方提供的 IndexedDB/平台 provider,并只拥有自己创建的对象。`openSceneText()` 是异步入口,会顺序等待全部 source 注册完成后才替换文档;失败、取消或场景代次过期时只释放本轮 `created` source。
57
57
 
58
+ 业务编辑器需要恢复 selection、editorial 显隐/锁定和 camera 时,使用根入口的 `StudioSessionPersistenceAdapter` 与 `/editor` 的 `createStudioSessionPersistence()`。会话快照只保存文档、`EditorialStateV1` 和不可变 asset closure 引用;资源字节、签名 URL 和云端传输继续由 asset source provider 负责。`IndexedDbStudioSessionPersistence` 是浏览器本地参考实现,云端实现只需映射 revision/ETag、幂等保存与 typed conflict,不需要引入项目、权限或发布流程。
59
+
58
60
  Visual 交付按独立异步编排执行:
59
61
 
60
62
  ```text
@@ -1,7 +1,7 @@
1
1
  var Ge = Object.defineProperty;
2
2
  var Be = (i, e, r) => e in i ? Ge(i, e, { enumerable: !0, configurable: !0, writable: !0, value: r }) : i[e] = r;
3
3
  var J = (i, e, r) => Be(i, typeof e != "symbol" ? e + "" : e, r);
4
- import { S as fe, A as qe, b as he, G as Ke, a as l, s as y, z as m, L as Ae, l as Ne, B as T, R as z, O as pe, H as ie, w as G, Q as Je, I as B, p as Ye, U as X, M as Ee, a8 as Xe, Y as We, m as Ze, k as oe, c as Qe, X as ei, r as ii } from "./scene-graph-DBLKAhxa.js";
4
+ import { S as fe, A as qe, b as he, G as Ke, a as l, s as y, z as m, L as Ae, l as Ne, B as T, R as z, O as pe, H as ie, w as G, Q as Je, I as B, p as Ye, U as X, M as Ee, a8 as Xe, Y as We, m as Ze, k as oe, c as Qe, X as ei, r as ii } from "./scene-graph-DVOXjMmp.js";
5
5
  const ve = "0123456789ABCDEFGHJKMNPQRSTVWXYZ", ri = 10, ni = 16;
6
6
  let re = -1, Se = [];
7
7
  function L(i = Date.now()) {
@@ -0,0 +1,55 @@
1
+ import type { StudioLoadedSession, StudioSessionPersistenceAdapter, StudioSessionPersistenceConflict, StudioSessionPersistenceSaveMode, StudioSessionPersistenceSaveResult } from '../ports/persistence';
2
+ import type { StudioSessionSnapshot } from '../persist/snapshot';
3
+ export interface StudioSessionPersistenceError {
4
+ readonly code: string;
5
+ readonly message: string;
6
+ }
7
+ export interface StudioSessionPersistenceState {
8
+ readonly available: boolean;
9
+ readonly dirty: boolean;
10
+ readonly saving: boolean;
11
+ readonly lastSavedRevision: string | null;
12
+ readonly lastSavedEtag: string | null;
13
+ readonly lastSavedAt: string | null;
14
+ readonly conflict: StudioSessionPersistenceConflict | null;
15
+ readonly error: StudioSessionPersistenceError | null;
16
+ }
17
+ export interface StudioSessionPersistenceControllerOptions {
18
+ readonly adapter: StudioSessionPersistenceAdapter;
19
+ readonly capture: () => StudioSessionSnapshot;
20
+ readonly currentSignature: () => string;
21
+ readonly autosaveDelayMs?: number;
22
+ readonly now?: () => string;
23
+ readonly createId?: () => string;
24
+ readonly onState?: (state: StudioSessionPersistenceState) => void;
25
+ }
26
+ /**
27
+ * Serializes complete-session saves and exposes optimistic concurrency state.
28
+ * Autosave requests are debounced; checkpoints and publishes join the same
29
+ * serial queue so a later save cannot overtake an in-flight snapshot.
30
+ */
31
+ export declare class StudioSessionPersistenceController {
32
+ private readonly options;
33
+ private state;
34
+ private running;
35
+ private requestedMode;
36
+ private activeSaveController;
37
+ private autosaveTimer;
38
+ private disposed;
39
+ constructor(options: StudioSessionPersistenceControllerOptions);
40
+ getState(): StudioSessionPersistenceState;
41
+ markDirty(): void;
42
+ scheduleAutosave(): void;
43
+ restoreBaseline(session: StudioLoadedSession | null): void;
44
+ clearConflict(): void;
45
+ clearError(): void;
46
+ save(mode?: StudioSessionPersistenceSaveMode): Promise<StudioSessionPersistenceSaveResult>;
47
+ flush(mode?: Extract<StudioSessionPersistenceSaveMode, 'checkpoint' | 'publish'>): Promise<StudioSessionPersistenceSaveResult>;
48
+ retry(mode?: StudioSessionPersistenceSaveMode): Promise<StudioSessionPersistenceSaveResult>;
49
+ cancel(): void;
50
+ dispose(closeAdapter?: boolean): Promise<void>;
51
+ private drain;
52
+ private performSave;
53
+ private clearAutosaveTimer;
54
+ private setState;
55
+ }
@@ -48,6 +48,8 @@ export declare function normalizePlacementPolicy(policy: Partial<StudioPlacement
48
48
  /** Selects a stable, human-readable grid level from the object's largest dimension. */
49
49
  export declare function adaptiveGridStepForBounds(bounds: Vec3Bounds): number;
50
50
  export declare function effectiveGridStep(bounds: Vec3Bounds, policy: Pick<StudioPlacementPolicy, 'gridStepM' | 'adaptiveGridSnap'>): number;
51
+ /** Deterministic XY offsets ordered outward by increasing ring. */
52
+ export declare function placementAvoidanceOffsets(bounds: Vec3Bounds, transform: LocalTransform, clearanceM?: number, maxRings?: number): readonly Vec3[];
51
53
  export declare function isSupportSurfaceNormal(normal: Vec3): boolean;
52
54
  /** Full 15-axis SAT. Face/edge contact is legal; a positive volume intersection is not. */
53
55
  export declare function placementVolumesOverlap(a: StudioPlacementVolume, b: StudioPlacementVolume, tolerance?: number): boolean;
@@ -69,3 +71,5 @@ export declare function supportContactAllowsVolumeOverlap(moved: StudioPlacement
69
71
  /** Checks the complete candidate transaction, including siblings moved in the same batch. */
70
72
  export declare function validatePlacementChanges(before: SceneDocument, after: SceneDocument, policy: StudioPlacementPolicy, measuredBounds?: (node: SceneNode) => Vec3Bounds | null, allowOverlapNodeIds?: ReadonlySet<string>, supportContacts?: readonly StudioSupportContact[]): readonly import('../util/diagnostics').Diagnostic[];
71
73
  export declare function isContainerNode(document: SceneDocument, node: SceneNode): boolean;
74
+ /** Visual-only nodes are renderable but explicitly non-collidable. */
75
+ export declare function isPlacementCollisionNode(node: SceneNode): boolean;
@@ -1,5 +1,5 @@
1
1
  /** UI-independent scene authoring controller. All UI clients share this bridge. */
2
- import type { StudioCommandResult, StudioHost, StudioSelection } from '../core/host';
2
+ import type { StudioCommandResult, StudioBoundingBoxInput, StudioHost, StudioSelection } from '../core/host';
3
3
  import type { CommandRecord } from '../doc/command';
4
4
  import { createAssetNodeFromRevision } from '../doc/builders';
5
5
  import type { LocalTransform, NodePivot, PhysicsOverride, SceneDocument, StudioEditorialState, Vec3 } from '../doc/schema';
@@ -122,6 +122,7 @@ export declare class StudioEditor {
122
122
  captureViewport(options?: import('../view/scene-session').StudioCaptureOptions): Promise<import('../view/scene-session').StudioCaptureResult>;
123
123
  getPlacementPolicy(): StudioPlacementPolicy;
124
124
  setPlacementPolicy(policy: Partial<StudioPlacementPolicy>): void;
125
+ addBoundingBoxPlaceholder(input: StudioBoundingBoxInput): StudioCommandResult;
125
126
  prepareAssetPlacement(input: {
126
127
  readonly revisionId: string;
127
128
  readonly point?: Vec3;
@@ -129,6 +130,7 @@ export declare class StudioEditor {
129
130
  readonly surface?: StudioPlacementSurface | null;
130
131
  readonly parentNodeId?: string;
131
132
  readonly allowOverlap?: boolean;
133
+ readonly autoAvoidOverlap?: boolean;
132
134
  readonly signal?: AbortSignal;
133
135
  }): Promise<StudioAssetPlacementPlan>;
134
136
  commitAssetPlacement(plan: StudioAssetPlacementPlan, input: {
@@ -1,5 +1,7 @@
1
1
  export { StudioEditor, createStudioEditor } from './editor';
2
2
  export type { StudioEditorOptions, StudioAddAssetOptions } from './editor';
3
+ export { captureStudioSessionSnapshot, createStudioSessionPersistence, restoreStudioSessionSnapshot, } from './session-persistence';
4
+ export type { StudioSessionCaptureOptions, StudioSessionPersistenceBinding, StudioSessionPersistenceOptions, StudioSessionRestoreOptions, } from './session-persistence';
3
5
  export type { StudioNodeDisplayOptions, StudioNodeDisplayState, } from '../view/scene-session';
4
6
  export type { StudioNodeFeatureSource, StudioNodeFeatureCapability, StudioNodeCoordinateCapability, StudioNodeFeatures, StudioNodePhysicsVisualization, StudioNodePhysicsVisualizationKey, StudioNodePhysicsVisualizationResult, StudioNodePhysicsVisualizationState, } from '../view/node-features';
5
7
  export type { StudioEffectiveNodeState, StudioNodeCapabilities, StudioSceneTreeNode, StudioSceneTreeSnapshot, } from '../core/scene-tree';
@@ -0,0 +1,54 @@
1
+ import type { StudioHost } from '../core/host';
2
+ import { StudioSessionPersistenceController, type StudioSessionPersistenceState } from '../core/session-persistence-controller';
3
+ import type { StudioLoadedSession, StudioSessionPersistenceAdapter, StudioSessionPersistenceSaveMode, StudioSessionPersistenceSaveResult } from '../ports/persistence';
4
+ import type { StudioAssetSource } from '../ports/asset-source';
5
+ import type { StudioAssetClosureRef, StudioSessionSnapshot } from '../persist/snapshot';
6
+ import type { StudioEditor } from './editor';
7
+ export interface StudioSessionCaptureOptions {
8
+ readonly assetClosure?: () => StudioAssetClosureRef | null;
9
+ }
10
+ export interface StudioSessionRestoreOptions {
11
+ readonly signal?: AbortSignal;
12
+ readonly sources?: readonly StudioAssetSource[];
13
+ }
14
+ export interface StudioSessionPersistenceOptions {
15
+ readonly host: StudioHost;
16
+ readonly editor: StudioEditor;
17
+ readonly adapter: StudioSessionPersistenceAdapter;
18
+ /** Resolve source-provider registrations before opening the document. */
19
+ readonly resolveSources?: (session: StudioLoadedSession, options: {
20
+ readonly signal?: AbortSignal;
21
+ }) => readonly StudioAssetSource[] | Promise<readonly StudioAssetSource[]>;
22
+ readonly assetClosure?: () => StudioAssetClosureRef | null;
23
+ readonly autoRestore?: boolean;
24
+ readonly trackEditorChanges?: boolean;
25
+ readonly autosaveDelayMs?: number;
26
+ readonly now?: () => string;
27
+ readonly createId?: () => string;
28
+ readonly onState?: (state: StudioSessionPersistenceState) => void;
29
+ }
30
+ export interface StudioSessionPersistenceBinding {
31
+ readonly controller: StudioSessionPersistenceController;
32
+ readonly ready: Promise<StudioLoadedSession | null>;
33
+ capture(): StudioSessionSnapshot;
34
+ restore(options?: StudioSessionRestoreOptions): Promise<StudioLoadedSession | null>;
35
+ scheduleAutosave(): void;
36
+ markDirty(): void;
37
+ save(mode?: StudioSessionPersistenceSaveMode): Promise<StudioSessionPersistenceSaveResult>;
38
+ flush(mode?: Extract<StudioSessionPersistenceSaveMode, 'checkpoint' | 'publish'>): Promise<StudioSessionPersistenceSaveResult>;
39
+ retry(mode?: StudioSessionPersistenceSaveMode): Promise<StudioSessionPersistenceSaveResult>;
40
+ dispose(options?: {
41
+ readonly closeAdapter?: boolean;
42
+ }): Promise<void>;
43
+ }
44
+ /**
45
+ * Captures the document and editor-owned view state as one immutable session.
46
+ * Asset closure is a reference only; resource bytes remain provider-owned.
47
+ */
48
+ export declare function captureStudioSessionSnapshot(host: Pick<StudioHost, 'createStateSnapshot'>, editor: Pick<StudioEditor, 'captureEditorialState'>, options?: StudioSessionCaptureOptions): StudioSessionSnapshot;
49
+ /**
50
+ * Applies a loaded session in the only valid order:
51
+ * document -> scene sync -> editorial selection/visibility/camera.
52
+ */
53
+ export declare function restoreStudioSessionSnapshot(host: Pick<StudioHost, 'openSceneText' | 'ready'>, editor: Pick<StudioEditor, 'ready' | 'sync' | 'applyEditorialState'>, snapshot: StudioSessionSnapshot, options?: StudioSessionRestoreOptions): Promise<void>;
54
+ export declare function createStudioSessionPersistence(options: StudioSessionPersistenceOptions): StudioSessionPersistenceBinding;