@harpern/edu-modelhub-viewer-core 0.1.0-beta.0 → 0.1.0-beta.2

package/dist/metadata.d.ts

@@ -10,7 +10,7 @@
  * caller's own loader, so the scene and the metadata can never disagree about
  * which file they came from. Nothing here touches a renderer or the DOM.
  */
-import { GlbParseError, type EduModelHub, type ValidationResult } from "@osuecampus/edu-modelhub-extractor";
+import type { EduModelHub, ValidationResult } from "./types.js";
 /** Where a payload came from. `"none"` is the fail-closed case. */
 export type MetadataSource = "embedded" | "sidecar" | "none";
 /** Result of a metadata load. */
@@ -82,4 +82,9 @@ export declare function loadModel(url: string, options?: LoadOptions): Promise<L
  * development without any UI. Errors warn, warnings inform.
  */
 export declare function logFindings(findings: ValidationResult[], label?: string, console_?: Pick<Console, "warn" | "info">): void;
-export { GlbParseError };
+/**
+ * True when a thrown value is the parse error a malformed GLB container
+ * raises. Checks the name rather than the class: a bundled copy of the
+ * parser is a different class object, so instanceof would quietly fail.
+ */
+export declare function isGlbParseError(error: unknown): boolean;

package/dist/normalize.d.ts

@@ -6,7 +6,7 @@
  * and marker positions may need converting. Normalizing once, here, keeps
  * every consumer agreeing about what "annotation 3" means.
  */
-import type { Annotation, EduModelHub, Region } from "@osuecampus/edu-modelhub-extractor";
+import type { Annotation, EduModelHub, Region } from "./types.js";
 import { type Vec3 } from "./coordinates.js";
 /** An annotation whose id is guaranteed unique and non-empty. */
 export type IdentifiedAnnotation = Annotation & {
@@ -57,6 +57,15 @@ export declare function normalizeAnnotationIds(annotations: readonly Annotation[
 export declare function annotationsInReadingOrder(payload: EduModelHub): IdentifiedAnnotation[];
 /** Regions sorted by `order`, ties keeping storage order. */
 export declare function regionsInOrder(payload: EduModelHub): Region[];
+/** True when a region carries a description an author actually wrote. */
+export declare function isAuthoredRegion(region: Region | undefined): boolean;
+/**
+ * Regions worth showing in a reading view: those an author described, or
+ * those left undescribed but given a real name. A region the tool invented
+ * outright is dropped, so a model nobody annotated shows no region list at
+ * all rather than a wall of object names.
+ */
+export declare function readableRegions(regions: readonly Region[] | undefined): Region[];
 /** Display name for a region, falling back to its id. */
 export declare function regionLabel(region: Region | undefined): string;
 /**

package/dist/regions.d.ts

@@ -11,7 +11,7 @@
  * name is itself a region id.
  */
 import type { Mesh, Object3D, Material } from "three";
-import type { Region } from "@osuecampus/edu-modelhub-extractor";
+import type { Region } from "./types.js";
 /** Region id to the meshes that make it up. */
 export type RegionMeshMap = Map<string, Mesh[]>;
 /** The parts of a glTF JSON this module reads. */

package/dist/transcript.d.ts

@@ -5,7 +5,7 @@
  * screen reader and braille users who want the content without driving a 3D
  * scene. Pure string building: no DOM, so it runs in Node and in tests.
  */
-import type { EduModelHub } from "@osuecampus/edu-modelhub-extractor";
+import type { EduModelHub } from "./types.js";
 /** Options for {@link buildTranscript}. */
 export interface TranscriptOptions {
     /** Heading for the summary section. */

package/dist/types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * The EDU_modelhub payload shape, as this package sees it.
+ *
+ * These are the same schema-derived definitions the extractor carries, and
+ * both are derived from the same source of truth:
+ * `packages/edu-modelhub-schema/EDU_modelhub.schema.json`. This package keeps
+ * its own copy so the published artifact is self-contained: the extractor is
+ * compiled into the bundle rather than installed alongside it, and a type
+ * that pointed at an uninstalled package would break every consumer.
+ *
+ * If the schema changes, both copies change with it.
+ *
+ * Per-primitive region assignment is NOT part of this payload. Each glTF mesh
+ * primitive belonging to a region carries `extras: { modelhubRegionId: "…" }`
+ * on the primitive itself, which is why `regions.ts` reads the loaded scene.
+ */
+/** Usage license for the model. */
+export type ModelLicense = "CC0" | "CC BY" | "CC BY-SA" | "All Rights Reserved";
+/** How the model was created. */
+export type ModelSource = "scan" | "photogrammetry" | "manual" | "other";
+/** Whether a region is visible when the model first loads. */
+export type VisibilityDefault = "shown" | "hidden";
+/** Anchor type for an annotation. */
+export type AnchorType = "marker" | "node" | "primitive" | "aabb";
+/** A named, selectable sub-section of the model. */
+export interface Region {
+    /** Stable snake_case identifier, unique within the model. */
+    id: string;
+    /** Human-readable display name shown in the region list. */
+    label?: string;
+    /** Educational description of what this region represents. */
+    description?: string;
+    /** Free-form tags for filtering or grouping. */
+    tags?: string[];
+    /** Whether this region is visible when the model first loads. */
+    visibilityDefault?: VisibilityDefault;
+    /** Display order in the region list. 0 = first. */
+    order?: number;
+}
+/** Positions the annotation at a world-space coordinate. */
+export interface PositionAnchor {
+    type: "marker";
+    /** World-space [x, y, z] in the payload's coordinate space. */
+    position: [number, number, number];
+}
+/** Targets a named glTF node, mesh primitive, or bounding box. */
+export interface ReferenceAnchor {
+    type: "node" | "primitive" | "aabb";
+    /** Name of the target. */
+    ref: string;
+}
+/** Every anchor variant. */
+export type Anchor = PositionAnchor | ReferenceAnchor;
+/**
+ * An authored camera view for an annotation. Viewers with a tour fly here;
+ * viewers without one ignore it. Positions use the payload's coordinate
+ * space, the same as `anchor.position`.
+ */
+export interface AnnotationCamera {
+    /** Camera position as [x, y, z]. */
+    eye: [number, number, number];
+    /**
+     * A point the camera looks toward. Only the direction from `eye` matters,
+     * so sources that encode direction as a point beside the eye are valid.
+     */
+    target: [number, number, number];
+    /** Vertical field of view in degrees. Omitted means the viewer default. */
+    fov?: number;
+}
+/** An educational note anchored to a specific location on the model. */
+export interface Annotation {
+    /** Stable identifier. */
+    id: string;
+    /** Where in 3D space this annotation sits. */
+    anchor: Anchor;
+    /** Short headline. */
+    title?: string;
+    /** Educational content body. */
+    body?: string;
+    /** Suggested reading sequence. 0 = first. */
+    readingOrder?: number;
+    /** Id of the Region this belongs to; must match a Region.id in the payload. */
+    regionId?: string;
+    /** Authored camera view, used by viewers with a tour. */
+    camera?: AnnotationCamera;
+}
+/** Top-level metadata describing the whole model. */
+export interface ModelMetadata {
+    /** Human-readable name. */
+    title: string;
+    /** One-sentence accessibility description, 300 characters maximum. */
+    altText: string;
+    /** Detailed educational description; may be multiple paragraphs. */
+    longDescription?: string;
+    /** ISO 639-1 two-letter language code. */
+    language?: string;
+    /** Usage license. */
+    license?: ModelLicense;
+    /** Credit string, expected when the license is CC BY or CC BY-SA. */
+    attribution?: string;
+    /** Creator or rights holder. */
+    creator?: string;
+    /** Where the model came from or how it was acquired. */
+    origin?: string;
+    /** How rights were determined or asserted. */
+    rightsStatement?: string;
+    /** ISO 8601 date the institution created or acquired the asset. */
+    acquired?: string;
+    /** How the model was created. */
+    source?: ModelSource;
+    /** ISO 8601 UTC timestamp of first creation. */
+    created?: string;
+    /** ISO 8601 UTC timestamp of last update. */
+    modified?: string;
+}
+/**
+ * Root payload of the EDU_modelhub glTF extension, embedded at
+ * `gltf.extensions.EDU_modelhub` and listed in `gltf.extensionsUsed`.
+ */
+export interface EduModelHub {
+    /** Semantic version of the spec this payload targets. */
+    specVersion: string;
+    /**
+     * Coordinate space of every position in this payload. Written as "gltf"
+     * from spec 0.2.0. Absent means "gltf": almost every payload in the wild
+     * predates the field and already stores glTF Y-up. Only an explicit
+     * "blender" marks Blender Z-up, converted with (x, y, z) -> (x, z, -y).
+     */
+    coordinateSpace?: "gltf" | "blender";
+    /** Metadata describing the entire model. */
+    model: ModelMetadata;
+    /** Named, selectable sub-sections. */
+    regions: Region[];
+    /** Educational notes anchored to parts of the model. */
+    annotations: Annotation[];
+}
+/** Severity of a validation finding. */
+export type ValidationSeverity = "error" | "warning";
+/** A single validation finding. */
+export interface ValidationResult {
+    /** Dot-path to the offending field, such as "model.altText". */
+    field: string;
+    /** Human-readable description of the issue. */
+    message: string;
+    /** Whether this blocks use or is advisory. */
+    severity: ValidationSeverity;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harpern/edu-modelhub-viewer-core",
-  "version": "0.1.0-beta.0",
+  "version": "0.1.0-beta.2",
   "description": "Framework-agnostic viewer core for EDU_modelhub models: metadata loading, normalization, region binding, annotation markers, and camera behaviour shared by every conforming viewer",
   "license": "Apache-2.0",
   "author": "Oregon State University Ecampus",
@@ -54,9 +54,6 @@
     "test": "vitest run",
     "prepublishOnly": "npm run typecheck && npm run test && npm run build"
   },
-  "dependencies": {
-    "@osuecampus/edu-modelhub-extractor": "^0.1.0-beta.0"
-  },
   "peerDependencies": {
     "three": ">=0.160.0",
     "three-mesh-bvh": ">=0.7.0"
@@ -67,6 +64,7 @@
     }
   },
   "devDependencies": {
+    "@osuecampus/edu-modelhub-extractor": "^0.1.0-beta.0",
     "@types/node": "^20.0.0",
     "@types/three": "^0.180.0",
     "three": "^0.180.0",