fix(viewer): rename BCF panel "issues" language to "topics" (#4096)

.changeset/bcf-topic-not-issue-terminology.md

@@ -0,0 +1,19 @@
+---
+"@ifc-lite/viewer": patch
+"@ifc-lite/bcf": patch
+"@ifc-lite/bcf-api": patch
+"@ifc-lite/sdk": patch
+"@ifc-lite/cli": patch
+"@ifc-lite/mcp": patch
+"@ifc-lite/sandbox": patch
+---
+
+Finish renaming the BCF "issues" language to "topics" across the app, docs, and package-facing text. Per the BCF-XML specification, `Topic` is the container element and `Issue` is only one `TopicType` value among several (Request, Comment, Error, Warning, Info); the previous patch fixed the BCF panel's own title, heading, empty-state copy, and topic-title placeholder, and left the rest of the product inconsistent.
+
+Remaining app-visible surfaces now fixed: the Analyze ribbon's "BCF issues" toggle button (a fourth site, alongside the command palette, main toolbar, and workspace-panel controls fixed previously), the compare panel's "Create BCF issue" affordance and "Issue for" header, the auto-created BCF project's default name (`<model>_Issues` → `<model>_Topics`, matching the BCF panel's own default), the landing-page hero animation's "Issue" step label, the MCP playground's BCF category blurb and example export path, and BCF-related copy across three in-app tours (`bcf`, `compare`, `clash`) — tour titles/descriptions plus five step titles/bodies.
+
+Docs updated to match: `docs/index.md`, `README.md`, `docs/guide/quickstart.md`, `docs/guide/bcf.md`, `docs/api/typescript.md`, and the CLI guide/reference's `bcf` examples (`--out topic.bcf`, `bcf list topics.bcf`), which also renamed the example filenames for consistency — they are illustrative only; the CLI has no default BCF filename.
+
+Also reworded now-inconsistent internal comments and JSDoc in the touched files, `@ifc-lite/bcf`'s package README and `createTopic` doc comment, `@ifc-lite/bcf-api`'s README, `@ifc-lite/sdk`'s `bim.bcf` namespace docs, `@ifc-lite/mcp`'s `bcf` tool docblock and fire-rating prompt template, and `@ifc-lite/sandbox`'s clash-to-BCF tool description — all comment/doc-only, no behavior change beyond the CLI's `bcf create` usage-message example (`--title "Issue"` → `--title "Missing door"`, matching the `--help` listing).
+
+Left deliberately unchanged: `bcfHelpers.tsx`'s `TOPIC_TYPES` list and every other real `TopicType` spec value (including the MCP `bcf` tool's `type` default and the sandbox playground's `topicType` default, both `'Issue'`), `ClashPanel`'s unrelated clash-detection "issues", GitHub issue-number references, and `registry.ts`'s `id: 'bcf'` panel key.

.claude/skills/use-ifclite/cli-reference.md

@@ -91,9 +91,9 @@ Flags: `--json` · `--locale en|de|fr`. Exit 0 (pass) / 1 (fail).
 ## bcf
 
 ```bash
-ifc-lite bcf create --title "Missing fire door" --description "Level 2" --out issue.bcf
-ifc-lite bcf list issues.bcf
-ifc-lite bcf add-comment --file issues.bcf --text "Fixed in rev 3" --out updated.bcf
+ifc-lite bcf create --title "Missing fire door" --description "Level 2" --out topic.bcf
+ifc-lite bcf list topics.bcf
+ifc-lite bcf add-comment --file topics.bcf --text "Fixed in rev 3" --out updated.bcf
 ```
 
 ## create

README.md

@@ -243,7 +243,7 @@ Not sure? Start with the browser setup. You can add a server or switch engines l
 | Export to glTF / IFC / Parquet | + `@ifc-lite/export` |
 | Detect clashes | + `@ifc-lite/clash` |
 | Diff two model versions | + `@ifc-lite/diff` |
-| BCF issue tracking | + `@ifc-lite/bcf` |
+| BCF topic tracking | + `@ifc-lite/bcf` |
 | Filter and colorize in 3D by rules | + `@ifc-lite/lens` |
 | Build schedules and property tables | + `@ifc-lite/lists` |
 | Script models with the `bim.*` API | + `@ifc-lite/sdk` |

apps/viewer/src/components/mcp/HeroScene.tsx

@@ -78,7 +78,7 @@ export const HERO_STEPS: HeroStep[] = [
   { verb: 'Standardize', line: 'bsdd_property_sets("IfcWall")',                family: 'bSDD',      overlay: { kind: 'psets', psets: ['Pset_WallCommon', 'Qto_WallBaseQuantities', 'Pset_ConcreteElementGeneral'] } },
   { verb: 'Add',       line: 'entity_create(IfcDoor)',                         family: 'Mutation' },
   { verb: 'Section',   line: 'viewer_set_section(z = 2.2)',                    family: 'Viewer' },
-  { verb: 'Issue',     line: 'bcf_topic_create("missing fire rating")',        family: 'BCF',       overlay: { kind: 'pin', ref: 'BCF #04' } },
+  { verb: 'Flag',      line: 'bcf_topic_create("missing fire rating")',        family: 'BCF',       overlay: { kind: 'pin', ref: 'BCF #04' } },
   { verb: 'Inspect',   line: 'viewer_describe_selection()',                    family: 'Viewer',    overlay: { kind: 'card', ref: 'IfcWall #262', lines: ['Pset_WallCommon · IsExternal=true', 'FireRating=EI60 · 240 mm concrete'] } },
 ];
 

apps/viewer/src/components/mcp/data.ts

@@ -63,7 +63,7 @@ export const CATEGORY_BLURBS: Record<ToolCategory, string> = {
   Geometry: 'Bounding boxes, volumes, areas — read from quantity sets.',
   Validation: 'IDS specs and a built-in model audit.',
   Mutation: 'Queue property/attribute writes; persist on save.',
-  BCF: 'Author and export buildingSMART issues + viewpoints.',
+  BCF: 'Author and export buildingSMART topics + viewpoints.',
   bSDD: 'Look up canonical class/property metadata.',
   Diff: 'Compare two loaded models — added/removed/changed.',
   Export: 'Dump to .ifc, CSV, JSON, glTF, IFCx, PDF.',
@@ -618,7 +618,7 @@ export const EXAMPLES: Record<string, Record<string, unknown>> = {
   bcf_topic_update: { guid: '7e87d7f4-...', comment: 'Confirmed with the structural team.' },
   bcf_topic_close: { guid: '7e87d7f4-...' },
   bcf_viewpoint_create: { guid: '7e87d7f4-...', selection_global_ids: ['1AQAupaRP1txwK1AGiN61V'] },
-  bcf_export: { file_path: '/tmp/issues.bcfzip' },
+  bcf_export: { file_path: '/tmp/topics.bcfzip' },
   bsdd_search: { query: 'wall' },
   bsdd_class: { ifc_type: 'IfcWall' },
   bsdd_property_sets: { ifc_type: 'IfcWall' },

apps/viewer/src/components/mcp/playground-dispatcher.ts

@@ -187,7 +187,7 @@ async function autoStageBcfDownload(): Promise<NonNullable<ToolDispatchResult['d
   const blob = await writeBCF(project);
   // Drop the previous staged copy so the panel only ever shows the latest.
   if (stagedBcfFileId) playgroundFiles.remove(stagedBcfFileId);
-  const filename = coerceFilename(undefined, 'bcfzip', 'issues');
+  const filename = coerceFilename(undefined, 'bcfzip', 'topics');
   const file = playgroundFiles.add({
     filename,
     mimeType: 'application/zip',
@@ -1120,7 +1120,7 @@ const IMPLS: Record<string, ToolImpl> = {
   },
   async bcf_export(_m, args) {
     const project = getBcfProject();
-    const filename = coerceFilename(args.file_path as string | undefined, 'bcfzip', 'issues');
+    const filename = coerceFilename(args.file_path as string | undefined, 'bcfzip', 'topics');
     const blob = await writeBCF(project);
     const file = playgroundFiles.add({
       filename, mimeType: 'application/zip', size: blob.size, blob,
@@ -1766,7 +1766,7 @@ function resolveIdsXml(args: Record<string, unknown>): string | null {
  *
  *   coerceFilename('wall_fire_rating.ids', 'ifc')   → 'wall_fire_rating.ifc'
  *   coerceFilename('/tmp/foo.bar/baz.csv', 'json')  → 'baz.json'
- *   coerceFilename(undefined, 'bcfzip', 'issues')   → 'issues.bcfzip'
+ *   coerceFilename(undefined, 'bcfzip', 'topics')   → 'topics.bcfzip'
  */
 function coerceFilename(
   raw: string | undefined,

apps/viewer/src/components/viewer/BCFPanel.tsx

@@ -3,7 +3,7 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
 
 /**
- * BCFPanel - BIM Collaboration Format issue management panel
+ * BCFPanel - BIM Collaboration Format topic management panel
  *
  * Provides:
  * - Topic list with filtering
@@ -121,15 +121,15 @@ export function BCFPanel({ onClose }: BCFPanelProps) {
     if (models.size === 0) {
       // No models loaded, use date-based name
       const date = new Date().toISOString().split('T')[0];
-      return `BCF_Issues_${date}`;
+      return `BCF_Topics_${date}`;
     }
-    // Use first model's name (without extension) + "_Issues"
+    // Use first model's name (without extension) + "_Topics"
     const firstModel = models.values().next().value;
     if (firstModel?.name) {
       const baseName = firstModel.name.replace(/\.(ifc|ifczip)$/i, '');
-      return `${baseName}_Issues`;
+      return `${baseName}_Topics`;
     }
-    return `BCF_Issues_${new Date().toISOString().split('T')[0]}`;
+    return `BCF_Topics_${new Date().toISOString().split('T')[0]}`;
   }, [models]);
 
   // Initialize project if needed
@@ -194,7 +194,7 @@ export function BCFPanel({ onClose }: BCFPanelProps) {
       setBcfLoading(true);
       const blob = await writeBCF(bcfProject);
       // Use project name, or generate from model name, or date-based fallback
-      const fileName = sanitizeFilename(bcfProject.name || getDefaultProjectName(), { fallback: 'issues' });
+      const fileName = sanitizeFilename(bcfProject.name || getDefaultProjectName(), { fallback: 'topics' });
       downloadBlob(blob, `${fileName}.bcfzip`);
       posthog.capture('bcf_exported', { topic_count: bcfProject.topics.size });
     } catch (error) {
@@ -383,7 +383,7 @@ export function BCFPanel({ onClose }: BCFPanelProps) {
       <div className="flex items-center justify-between px-3 py-2 border-b border-border">
         <div className="flex items-center gap-2">
           <MessageSquare className="h-4 w-4" />
-          <h2 className="font-medium text-sm">BCF Issues</h2>
+          <h2 className="font-medium text-sm">BCF Topics</h2>
           {topics.length > 0 && (
             <Badge variant="secondary" className="text-xs">
               {topics.length}

apps/viewer/src/components/viewer/CommandPalette.tsx

@@ -354,7 +354,7 @@ export function CommandPalette({ open, onOpenChange }: CommandPaletteProps) {
         action: () => { const s = useViewerStore.getState(); s.setLeftPanelCollapsed(!s.leftPanelCollapsed); } },
       { id: 'panel:script', label: 'Script Editor', keywords: 'code automation console', category: 'Panels', icon: FileCode2,
         action: () => { activateBottomPanel('script'); } },
-      { id: 'panel:bcf', label: 'BCF Issues', keywords: 'collaboration topics comments viewpoint', category: 'Panels', icon: MessageSquare,
+      { id: 'panel:bcf', label: 'BCF Topics', keywords: 'collaboration topics comments viewpoint', category: 'Panels', icon: MessageSquare,
         action: () => { activateRightPanel('bcf'); } },
       { id: 'panel:ids', label: 'IDS Validation', keywords: 'information delivery specification check', category: 'Panels', icon: ClipboardCheck,
         action: () => { activateRightPanel('ids'); } },

apps/viewer/src/components/viewer/ComparePanel.tsx

@@ -232,7 +232,7 @@ export function ComparePanel({ onClose }: ComparePanelProps) {
     });
   };
 
-  // Composing a BCF issue: collapse the diff chrome so the form owns the panel.
+  // Composing a BCF topic: collapse the diff chrome so the form owns the panel.
   // Gate on the selected row too, so a vanished selection can never leave the
   // panel empty (chrome hidden but no form to show).
   const bcfComposing = bcf.formOpen && !!selectedRow;
@@ -265,8 +265,8 @@ export function ComparePanel({ onClose }: ComparePanelProps) {
       ) : (
         <>
           {/* Diff chrome (run controls, counts, report, results, detail) — hidden
-              while composing a BCF issue so the form owns the panel. The user has
-              committed to raising an issue and the change context is already in the
+              while composing a BCF topic so the form owns the panel. The user has
+              committed to raising a topic and the change context is already in the
               pre-filled form, so re-running / exports / browsing only get in the way. */}
           {!bcfComposing && (
             <>
@@ -378,15 +378,15 @@ export function ComparePanel({ onClose }: ComparePanelProps) {
               >
                 <ChevronLeft className="h-4 w-4" />
               </button>
-              <span className="text-muted-foreground shrink-0">Issue for</span>
+              <span className="text-muted-foreground shrink-0">Topic for</span>
               <span className="font-medium truncate min-w-0">{selectedRow.name || selectedRow.ifcType}</span>
               <span className="ml-auto text-[10px] text-muted-foreground shrink-0">
                 {selectedRow.ifcType.replace(/^Ifc/, '')}
               </span>
             </div>
           )}
 
-          {/* Raise a BCF issue from the focused change (#1199) */}
+          {/* Raise a BCF topic from the focused change (#1199) */}
           {selectedRow && (
             <BcfFromChange
               row={selectedRow}

apps/viewer/src/components/viewer/MainToolbar.tsx

@@ -588,7 +588,7 @@ export function MainToolbar({ onShowShortcuts }: MainToolbarProps = {} as MainTo
             onCheckedChange={() => handleToggleRightPanel('bcf')}
           >
             <MessageSquare className="h-4 w-4 mr-2" />
-            BCF Issues
+            BCF Topics
           </DropdownMenuCheckboxItem>
           <DropdownMenuCheckboxItem
             checked={activeWorkspacePanels.has('ids')}

apps/viewer/src/components/viewer/bcf/BCFCreateTopicForm.tsx

@@ -37,7 +37,7 @@ export interface BCFCreateTopicFormProps {
   onSubmit: (topic: Partial<BCFTopic>, options?: { includeSnapshot: boolean }) => void;
   onCancel: () => void;
   author: string;
-  /** Pre-fill the title (e.g. when raising an issue from a detected change). */
+  /** Pre-fill the title (e.g. when raising a topic from a detected change). */
   initialTitle?: string;
   /** Pre-fill the description. */
   initialDescription?: string;
@@ -141,7 +141,7 @@ export function BCFCreateTopicForm({
           id="title"
           value={title}
           onChange={(e) => setTitle(e.target.value)}
-          placeholder="Brief description of the issue"
+          placeholder="Brief description of the topic"
           required
         />
       </div>

apps/viewer/src/components/viewer/bcf/BCFTopicList.tsx

@@ -186,7 +186,7 @@ export function BCFTopicList({
               </div>
               {isDefaultEmail && !editingEmail && (
                 <p className="text-xs text-muted-foreground mt-2 text-center">
-                  Set your email to identify your issues and comments
+                  Set your email to identify your topics and comments
                 </p>
               )}
             </div>

apps/viewer/src/components/viewer/compare/BcfFromChange.tsx

@@ -3,7 +3,7 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
 
 /**
- * "Create BCF issue" affordance shown under the focused change (issue #1199).
+ * "Create BCF topic" affordance shown under the focused change (issue #1199).
  * Extracted from ComparePanel; the actual topic creation lives in the panel so
  * it can coordinate the BCF store + viewpoint capture.
  */
@@ -54,7 +54,7 @@ export function BcfFromChange({
     return (
       <div className="border-t border-border shrink-0 px-3 py-2.5 flex items-center gap-2 text-xs">
         <CheckCircle2 className="h-4 w-4 text-[#9ece6a] shrink-0" />
-        <span className="min-w-0 truncate">BCF issue created: “{createdTitle}”</span>
+        <span className="min-w-0 truncate">BCF topic created: “{createdTitle}”</span>
         <Button variant="outline" size="sm" className="ml-auto h-7 px-2 text-xs shrink-0" onClick={onOpenBcfPanel}>
           Open BCF
         </Button>
@@ -63,7 +63,7 @@ export function BcfFromChange({
   }
 
   if (open) {
-    // Composing a BCF issue: the diff chrome is collapsed (ComparePanel), so the
+    // Composing a BCF topic: the diff chrome is collapsed (ComparePanel), so the
     // form owns the remaining height and scrolls internally — its actions stay
     // reachable instead of being clipped off the bottom of the panel.
     return (
@@ -86,7 +86,7 @@ export function BcfFromChange({
     <div className="border-t border-border shrink-0 px-3 py-2.5">
       <Button variant="outline" size="sm" className="w-full gap-1.5 text-xs" onClick={onStart}>
         <MessageSquarePlus className="h-3.5 w-3.5" />
-        Create BCF issue
+        Create BCF topic
       </Button>
     </div>
   );

apps/viewer/src/components/viewer/compare/useBcfFromChange.ts

@@ -3,7 +3,7 @@
  * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
 
 /**
- * Coordinates the "raise a BCF issue from a detected change" flow (#1199),
+ * Coordinates the "raise a BCF topic from a detected change" flow (#1199),
  * extracted from ComparePanel to keep it under the module-size house rule.
  *
  * Owns the create-form open/created state, captures a viewpoint (camera +
@@ -91,7 +91,7 @@ export function useBcfFromChange(
         const state = useViewerStore.getState();
         if (!state.bcfProject) {
           const first = modelList[0]?.name?.replace(/\.(ifc|ifczip)$/i, '') || 'Comparison';
-          state.setBcfProject(createBCFProject({ name: `${first}_Issues` }));
+          state.setBcfProject(createBCFProject({ name: `${first}_Topics` }));
         }
         // Resolve the viewpoint first so the topic's source-file Header can be
         // derived from the models its selection references before it is stored.
@@ -128,7 +128,7 @@ export function useBcfFromChange(
         setFormOpen(false);
         setCreatedTitle(topic.title);
       } catch (error) {
-        console.error('[compare] failed to create BCF issue from change', error);
+        console.error('[compare] failed to create BCF topic from change', error);
       } finally {
         submitInFlight.current = false;
       }

apps/viewer/src/components/viewer/ribbon/tabs/AnalyzeTab.test.tsx

@@ -0,0 +1,38 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/**
+ * The Analyze ribbon tab's "Validate" group has its own toggle button for
+ * the BCF panel — a fourth site (alongside CommandPalette, MainToolbar, and
+ * useWorkspacePanelControls, all pinned elsewhere) that once read "BCF
+ * issues". Topic is the BCF-XML container element and Issue is only one
+ * TopicType value among several (Request, Comment, Error, Warning, Info),
+ * so "issues" narrowed and contradicted the spec (#4096/#4097). Pin the
+ * corrected label here too, so it can't regress silently.
+ */
+
+import '@/test/setup-dom.js';
+import { afterEach, describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { render, cleanup } from '@/test/render.js';
+import { AnalyzeTab } from './AnalyzeTab.js';
+
+describe('AnalyzeTab — BCF ribbon button', () => {
+  afterEach(() => {
+    cleanup();
+  });
+
+  it('labels the Validate-group BCF button "BCF topics", not "BCF issues"', () => {
+    const container = render(<AnalyzeTab />);
+    const labels = [...container.querySelectorAll('button')].map((b) => b.textContent ?? '');
+    assert.ok(
+      labels.some((t) => /BCF topics/.test(t)),
+      `expected a button labelled "BCF topics"; got: ${JSON.stringify(labels)}`,
+    );
+    assert.ok(
+      !labels.some((t) => /BCF issues/i.test(t)),
+      `found a button still labelled "BCF issues": ${JSON.stringify(labels)}`,
+    );
+  });
+});

apps/viewer/src/components/viewer/ribbon/tabs/AnalyzeTab.tsx

@@ -45,7 +45,7 @@ export function AnalyzeTab() {
       <RibbonGroup label="Validate">
         <RibbonLargeButton
           icon={Issue}
-          label="BCF issues"
+          label="BCF topics"
           active={activeWorkspacePanels.has('bcf')}
           onClick={() => handleToggleRightPanel('bcf')}
         />

apps/viewer/src/components/viewer/toolbar/useWorkspacePanelControls.ts

@@ -276,7 +276,7 @@ export function useWorkspacePanelControls() {
     if (activeWorkspacePanels.has('script')) return 'Script Editor';
     if (activeWorkspacePanels.has('lists')) return 'Lists';
     if (activeWorkspacePanels.has('gantt')) return 'Schedule';
-    if (activeWorkspacePanels.has('bcf')) return 'BCF Issues';
+    if (activeWorkspacePanels.has('bcf')) return 'BCF Topics';
     if (activeWorkspacePanels.has('ids')) return 'IDS Validation';
     if (activeWorkspacePanels.has('lens')) return 'Lens Rules';
     if (activeWorkspacePanels.has('clash')) return 'Clash Detection';

apps/viewer/src/lib/panels/registry.test.ts

@@ -69,6 +69,18 @@ describe('workspacePanelForShortcutCode (Alt+digit routing #1200/#1208)', () =>
   });
 });
 
+// The BCF panel's title once read "BCF issues" — Topic is the BCF-XML
+// element and Issue is only one TopicType value among several (Request,
+// Comment, Error, Warning, Info), so "issues" narrowed and contradicted the
+// spec (#4096). Pin the corrected label so it can't regress silently.
+describe('BCF panel title', () => {
+  it('says "BCF topics", not "BCF issues" (#4096)', () => {
+    const bcf = WORKSPACE_PANELS.find((p) => p.id === 'bcf');
+    assert.ok(bcf, 'expected a bcf panel entry in the registry');
+    assert.strictEqual(bcf.title, 'BCF topics');
+  });
+});
+
 // `isBottomPanel` gates `usePanelControls`' toggle routing (script / gantt /
 // lists go through `toggleBottomPanel`, everything else through the sidebar
 // dock). The test above only exercises 'script' (Digit8) and 'lists'