Símbolos SVG portáteis

Monte e compartilhe símbolos SVG estáticos com vínculos Ganter seguros e terminais de ligação tipados.

Os símbolos Ganter mantêm a arte e os dados ao vivo separados. A arte é SVG comum e estático. O Ganter Lab é dono de todo mapeamento de valor e de toda animação, então um arquivo importado não consegue rodar scripts, tratadores de evento, código de animação embutido nem requisições de rede. Esta página é a referência completa do modelo de autoria: o que um símbolo declara, o que a importação aceita e recusa, e como símbolos viajam entre estações.

Um símbolo declara três coisas por cima da arte dele:

• Slots: entradas nomeadas (preenchimento, traço, movimento, texto, visibilidade) que uma instância de dashboard colocada depois alimenta a partir de um endereço da Logic ou de um valor fixo.
• Terminais: pontos de ligação tipados no perímetro, para que o Dashboard consiga rotear tubulações, dutos, fios e eixos entre símbolos.
• Sugestões: composições opcionais com outros símbolos, explicitamente posicionadas.

Símbolos do sistema e Meus símbolos

O catálogo tem duas origens, filtráveis em todo lugar em que símbolos são listados:

Todo símbolo do sistema oferece Duplicar para Meus símbolos: a cópia é um ativo de usuário congelado e de propriedade independente (arte, caixa de visão, ajuste, área ocupada, slots, configurações de tipo, terminais e sugestões copiados juntos), então ela continua se comportando como foi escolhida mesmo quando uma atualização posterior da aplicação muda o original. Excluir um símbolo de usuário pede confirmação; os dashboards que ainda o referenciam mostram um marcador de lugar em vez de quebrar.

Maneiras de criar um símbolo

• Importar um arquivo: o Logic > Ativos > Símbolos > Importar símbolo aceita um .svg simples ou um pacote .ganter-symbol.json completo. Toda importação cria um ativo novo, com identidade própria; ela nunca sobrescreve um símbolo existente, e uma colisão de nome é resolvida com sufixo (" 2", " 3", …) em vez de falhar. O seletor recusa arquivos com mais de 1 MB antes de qualquer byte ser lido. Depois de uma importação de SVG simples, a aplicação relata quantos itens inseguros ela removeu, se houve algum.
• Autorar na aplicação: o Novo símbolo de usuário abre um editor para o nome, a marcação SVG, o layout de dashboard (ajuste e área ocupada inicial) e os slots; assim que o símbolo existe, alterações válidas salvam sozinhas. A geometria de terminal não é editável na aplicação, de propósito: terminais tipados só podem vir de um pacote, e terminais autorados num pacote são preservados como somente leitura ao longo de edições posteriores.
• Pedir a uma IA: dois caminhos compartilham exatamente o mesmo contrato. Pelo endpoint MCP embutido, a ferramenta symbol_validate faz a importação em seco e a symbol_import persiste um ativo novo; as duas carregam o contrato completo nas descrições delas. De um chat externo sem acesso à aplicação, o Copiar instrução de chat do painel de Símbolos copia um comando autossuficiente; salve o SVG ou o pacote devolvido como arquivo e importe-o aqui.

Veja a Logic para o espaço de trabalho de ativos ao redor.

Preparar um SVG simples

Dê um id SVG estável a toda parte que você quiser vincular. Depois da importação, esses ids aparecem nos seletores de alvo dos slots. Ids e nomes de slot compartilham uma gramática: eles começam com uma letra ou _, continuam com letras, dígitos, _, ., : ou -, e têm no máximo 128 caracteres.

Atributos data-ganter-* opcionais são a única marcação específica do Ganter que um símbolo pode carregar:

Terminais de ligação não vivem no SVG e não miram ids de elemento SVG. Atributos chamados data-ganter-port ou data-ganter-port-* não fazem parte do formato: uma importação de SVG simples os remove; um pacote estrito que os contenha é rejeitado.

Uma importação de SVG simples sempre produz um símbolo apenas visual válido: zero terminais, zero slots. O inspetor relata que não existe terminal conectável, porque papel, tipo, direção externa e caminho interno não foram declarados. O Ganter não deduz esses campos do nome do arquivo, da categoria nem da arte, e não abre um editor interno de terminais ou de caminhos.

O que o higienizador aceita

A mesma política de SVG vale para todo caminho (importação de arquivo, editor na aplicação, MCP, pacote). Ela é deliberadamente menor que o SVG:

• Mantidos: geometria e estrutura inertes: svg, g, defs, symbol, use, path, rect, circle, ellipse, line, polyline, polygon, text, tspan, title, desc, clipPath, mask, linearGradient, radialGradient, stop, pattern, marker, com atributos de apresentação (preenchimento, traço, opacidade, transformação, estilo) e rótulos ARIA.
• Removidos ou recusados: <script>, <style>, <foreignObject>, tratadores de evento, animação embutida, e toda URL externa ou data:/file:/http(s). Só referências internas url(#id) e href="#id" sobrevivem.
• Limites: a marcação pode ter no máximo 512 KB e 4096 elementos.

Pinturas seguras são cores hexadecimais, as cores nomeadas do CSS, rgb()/rgba()/hsl()/hsla(), e os símbolos de tema da aplicação var(--color-<name>) (por exemplo var(--color-success), var(--color-symbol-off)). Os símbolos de tema são como uma arte só se adapta ao claro e ao escuro: entregue um desenho que referencie símbolos, nunca duas variantes de tema.

Como as violações são tratadas depende do caminho: um SVG simples é reparado (os itens inseguros são removidos e cada remoção é relatada como aviso); um pacote é estrito e é rejeitado, com as primeiras violações nomeadas, em vez de reparado em silêncio.

Pacote portátil v2

Exportar um símbolo cria um arquivo .ganter-symbol.json. Todo campo do envelope é obrigatório; os três vetores do contrato podem ficar vazios, mas precisam estar presentes:

O JSON Schema público do Ganter symbol v2 valida o envelope de transporte. O importador então faz as conferências semânticas que o JSON Schema não consegue expressar: a existência do alvo no SVG, a geometria do caminho interno, a compatibilidade das sugestões. Um pacote é estrito em todas as dimensões: marcação insegura, campos desconhecidos, entradas nulas em vetores e os antigos contratos ports[], anchors[], profile e connectionStyle são rejeitados, e não reparados.

O pacote nunca contém um endereço de estação, um vínculo de Dashboard, uma escolha de tipo por instância, um GUID de banco de dados ou uma identidade de usuário. Um slot que carrega um endereço da Logic nem consegue ser exportado: o endereço pertence à instância colocada, não ao símbolo reutilizável.

Tamanho, caixa de visão e ajuste

A caixa de visão é o espaço de coordenadas natural do símbolo. Terminais e caminhos internos são declarados nela, e ela precisa bater exatamente com o viewBox da raiz do SVG; um pacote cujas duas caixas de visão discordam é rejeitado. Caixas de visão não quadradas são totalmente suportadas, então uma esteira comprida não precisa morar num quadrado.

O modo de ajuste diz como a arte usa o retângulo de dashboard que o operador desenha:

A área ocupada é o tamanho inicial em células da grade do dashboard quando o símbolo é colocado pela primeira vez: largura de 1 a 24, altura de 1 a 12 (o editor usa 4 × 4 por padrão). Ela é uma sugestão, não uma restrição; o operador redimensiona livremente depois.

Duas portas separadas limitam o tamanho de uma importação: o seletor de arquivo recusa qualquer coisa acima de 1 MB antes de lê-la, e o higienizador recusa marcação acima de 512 KB ou de 4096 elementos.

Slots: a superfície de vínculo

Um slot declara uma entrada: qual elemento ele conduz, o que ele faz com ele, e como os valores de entrada mapeiam para a saída. A instância de dashboard colocada depois escolhe a origem de cada slot (um endereço da Logic ou um valor fixo); o símbolo em si nunca guarda uma origem.

Cada slot carrega:

Os treze tipos de slot:

Estes slots estilizam a arte; eles nunca estilizam as rotas de ligação do Dashboard, cuja cor e largura são globais por tipo de ligação.

Propriedade do vínculo

O símbolo declara parâmetros e escolhas de tipo permitidas, não origens ao vivo nem a seleção de uma instância. Depois de colocar um componente Símbolo, o operador mapeia cada slot para um endereço da Logic ou para um valor fixo e escolhe cada tipo de ligação configurável naquela instância. Essas escolhas ficam dentro da estação e nunca são exportadas com o símbolo reutilizável. Slots não mapeados ficam neutros: o elemento mantém a aparência autorada dele.

Posições globais e tipos de ligação

Todo terminal referencia uma posição do catálogo fixo de dezesseis ancoradouros do perímetro. Um pacote guarda apenas o anchorId; ele nunca repete nem sobrepõe coordenadas. As posições, como frações normalizadas da caixa de visão:

• topo: top-left (0, 0), top-25 (0.25, 0), top-50 (0.5, 0), top-75 (0.75, 0), top-right (1, 0);
• direita: right-25 (1, 0.25), right-50 (1, 0.5), right-75 (1, 0.75);
• base, em sentido horário: bottom-right (1, 1), bottom-75 (0.75, 1), bottom-50 (0.5, 1), bottom-25 (0.25, 1), bottom-left (0, 1);
• esquerda, seguindo em sentido horário: left-75 (0, 0.75), left-50 (0, 0.5), left-25 (0, 0.25).

Estas são posições de perímetro, não uma grade 5×5. Um símbolo não consegue acrescentar outra posição nem guardar coordenadas de ancoradouro próprias.

Os oito tipos globais de ligação são liquid, gas, air-duct, electrical, signal, network, material e mechanical-shaft. Use o Logic > Ativos > Tipos de ligação para configurar a cor e a largura visual de traço associadas a cada tipo. Símbolos e ligações guardam o id estável do tipo, então uma mudança global reestiliza toda rota que o usa. Um pacote nunca copia a cor ou a largura e não tem variantes de rota pequena, padrão ou grande.

Duas pontas formam uma ligação definida quando elas resolvem para o mesmo tipo. O papel do terminal ajuda na autoria e na revisão, mas não proíbe sozinho um arranjo de rede.

Escolhas compartilhadas de tipo

Um símbolo que consegue trabalhar com mais de um meio declara uma configuração de tipo compartilhada, em vez de duplicar a arte dele:

{
  "id": "process-type",
  "name": "Process type",
  "allowedTypes": ["liquid", "gas"],
  "defaultType": "liquid"
}

O id é uma chave estável: letras minúsculas e dígitos com traços simples, começando e terminando em alfanumérico (maiúsculas são recusadas). O allowedTypes é não vazio e contém ids de tipo global únicos; o defaultType precisa pertencer a ele; o name é obrigatório. Todo terminal que referencia process-type segue uma escolha feita na instância de dashboard colocada. Uma definição pode carregar várias configurações independentes, como meio de processo e meio de respiro, enquanto outros terminais ficam fixos.

Terminais completos

Cada terminal conectável declara uma posição global, um papel, exatamente um tipo fixo ou uma configuração compartilhada, uma direção para fora na orientação original, e um caminho interno de chegada:

{
  "anchorId": "left-50",
  "role": "input",
  "typeConfiguration": "process-type",
  "direction": "west",
  "internalPath": [
    { "x": 18, "y": 50 },
    { "x": 36, "y": 50 },
    { "x": 48, "y": 62 }
  ]
}

As regras, todas impostas na importação:

• No máximo 16 terminais, e cada id de ancoradouro usado no máximo uma vez.
• O role é input, output ou bidirectional; a direction é north, east, south ou west.
• Exatamente um entre type (um tipo de ligação global) e typeConfiguration (um id de configuração declarada), nunca os dois, nunca nenhum.
• O ancoradouro global convertido para a caixa de visão natural do SVG é o início implícito do internalPath; não o repita como primeiro ponto. As coordenadas são valores absolutos da caixa de visão, não frações normalizadas, e o caminho tem pelo menos um ponto.
• Todo segmento fica dentro da caixa de visão, tem comprimento diferente de zero, e é horizontal, vertical ou exatamente de 45°; segmentos consecutivos viram no máximo 90°.
• Terminais exigem que o SVG carregue uma caixa de visão.

O Dashboard desenha o caminho interno abaixo da arte do equipamento, o transforma com redimensionamento, rotação de quarto de volta e espelhamentos, e mantém a largura visual do tipo de ligação global em vez de escalá-la com o símbolo, para que um traço contínuo corra de dentro de um corpo até dentro do outro.

Um terminal é tudo ou nada. Um pacote estrito com um terminal parcial é inválido; um pacote apenas visual usa um vetor terminals vazio no lugar. Nada é jamais deduzido para preencher uma lacuna.

Sugestões ordenadas

Uma sugestão registra uma composição intencional, incluindo a pose exata do alvo:

{
  "sourceAnchorId": "right-75",
  "targetSymbol": "system:capping-station",
  "targetAnchorId": "left-75",
  "targetRotationDegrees": 0,
  "targetFlipHorizontal": false,
  "targetFlipVertical": false,
  "connectionType": "material"
}

Validação: o sourceAnchorId precisa ser um dos terminais do próprio símbolo; o targetSymbol precisa ser uma referência qualificada pela origem e, num pacote portátil, ele só pode ser system:<stable-key> (um GUID de usuário só faz sentido dentro da estação dona dele), nomeando um símbolo que existe no catálogo do sistema com um terminal em targetAnchorId; a rotação é 0, 90, 180 ou 270 e os dois sinalizadores de espelhamento são obrigatórios; cada sugestão precisa ser única. O connectionType só pode ser omitido quando os tipos fixos iguais nas duas pontas resolvem o cenário sem ambiguidade; ele é obrigatório quando qualquer uma das pontas é configurável, e precisa então ser permitido nas duas pontas.

As sugestões são direcionais e a ordem do vetor define a prioridade, mas elas nunca são uma lista de permissão para ligações comuns de Dashboard. Com um vetor suggestions vazio, o inspetor relata que não existe composição sugerida, em vez de inventar um parceiro de catálogo.

O que a importação recusa

Uma lista rápida das recusas, para que uma importação que falhou possa ser lida em vez de adivinhada. Num SVG simples, só o primeiro grupo se aplica e, dentro dele, apenas os tetos de tamanho, o XML malformado e uma raiz <svg> ausente recusam a importação: a marcação não permitida é reparada com um aviso. Num pacote, tudo abaixo é rejeição dura.

Arte

• Um arquivo acima de 1 MB, marcação acima de 512 KB, ou mais de 4096 elementos.
• XML malformado, ou uma raiz que não é um <svg> higienizado.
• Num pacote: qualquer marcação que a lista de permissão teria de remover (scripts, tratadores de evento, referências externas, elementos ou atributos não permitidos).
• Um viewBox que não são quatro números finitos com largura e altura positivas, ou que difere do viewBox da raiz do SVG; um pacote sem caixa de visão na raiz.

Envelope

• Um esquema, um formato ou uma versão diferente do contrato v2; campos desconhecidos em qualquer lugar; um name, um fit, um footprint ou qualquer um dos três vetores ausente; uma entrada nula dentro de um vetor.
• Um fit fora dos quatro modos; uma área ocupada fora de 1–24 × 1–12.

Slots

• Um nome ou um id de elemento fora da gramática de identificador; um nome de slot duplicado; um id de alvo que o SVG não contém; um tipo que o elemento alvo não aceita (texto num elemento que não é de texto, preenchimento numa <line>).
• Um slot rotate, spin ou scale cujo alvo não tem um data-ganter-pivot finito; um slot spinEnabled sem um slot spin no mesmo elemento.
• Dois slots no mesmo canal de um elemento. Cada tipo é um canal próprio, exceto que fill e fillColor compartilham o canal de preenchimento e stroke e strokeColor compartilham o canal de traço, então um elemento não aceita duas rotações, assim como não aceita dois preenchimentos.
• Números de faixa não finitos; uma saída secundária com apenas uma ponta, ou num tipo que não seja translate/scale; uma pintura insegura; um slot que carrega um endereço da Logic.

Ligações

• Mais de 16 terminais; um id de ancoradouro repetido ou desconhecido; um terminal com os dois ou com nenhum de type/typeConfiguration; um id de tipo ou de configuração desconhecido; um caminho interno inválido (fora da caixa de visão, segmentos de comprimento zero ou fora de ângulo, uma virada acima de 90°).
• Uma configuração de tipo com id inválido, sem nome, com tipos permitidos duplicados ou desconhecidos, ou com um padrão fora da lista dela.
• Uma sugestão cujo terminal de origem não existe, cujo alvo não é um símbolo do sistema com o terminal nomeado, cuja pose não é um quarto de volta, ou cujo tipo de ligação não é aceito nas duas pontas.

O symbol_validate no endpoint MCP roda exatamente esta importação em seco e relata todo erro, aviso e nota sem persistir nada.

Empacotar e compartilhar

O Exportar pacote (disponível igualmente para símbolos do sistema e de usuário) baixa <name>.ganter-symbol.json com a arte higienizada e o contrato completo: $schema, format, version, name, svg, viewBox, fit, footprint, slots[], typeConfigurations[], terminals[] e suggestions[], com os três vetores de ligação presentes mesmo quando vazios. O que nunca viaja: endereços de estação, escolhas de tipo por instância, identidade de banco de dados, identidade de usuário, e as cores e larguras de tipo de ligação da estação.

Na estação que recebe, o mesmo arquivo passa pelo Importar símbolo (ou pelo symbol_import por MCP) e cai como um símbolo de usuário novo, com terminais e tudo. Como a identidade de tipo é um id estável e a aparência é global, as rotas de um símbolo importado seguem imediatamente o estilo de tipo de ligação da própria estação que recebeu.